CI Setup

What It Does

Verifies the CI prerequisites (gh, jq, ssh) and GitHub CLI authentication, then optionally walks a wizard to configure the plugin's runner SSH config — previewing the config and confirming before any write.

When to Use

• First installing the plugin, after adding runners, or when CI commands fail with auth or connectivity errors.

Usage

This skill is wizard-driven and takes no arguments; the argument text after the skill name (if any) is available as context.

Config location. This skill operates on the plugin's runner SSH config file, yellow-ci.local.md. When an invoking command supplies a host-resolved path (on Claude Code, the repo-local plugin config), use that path. Otherwise — for example, on direct invocation with no invoking command — fall back to the host-neutral default: ${XDG_CONFIG_HOME:-$HOME/.config}/yellow-ci/yellow-ci.local.md. Never hard-code a host-specific config directory into this body.

Runner scope. yellow-ci targets Linux self-hosted runners. Windows/macOS runners are not probed by the health/cleanup workflows; note this if a non-Linux runner is configured.

Step 1: Check Prerequisites

Run all prerequisite checks in a single Bash call:

printf '=== Prerequisites ===\n'
command -v gh  >/dev/null 2>&1 && printf 'gh:  ok\n' || printf 'gh:  NOT FOUND\n'
command -v jq  >/dev/null 2>&1 && printf 'jq:  ok\n' || printf 'jq:  NOT FOUND\n'
command -v ssh >/dev/null 2>&1 && printf 'ssh: ok\n' || printf 'ssh: NOT FOUND (needed for runner health/cleanup)\n'

Collect all missing-tool failures before stopping — report them together.

Stop conditions (after reporting all failures):

• gh not found: "GitHub CLI is required. Install from https://cli.github.com/ then run gh auth login."
• jq not found: "jq is required. Install from https://jqlang.github.io/jq/download/".

ssh missing is a warning only — it affects the runner health, cleanup, and self-hosted-optimization workflows. Diagnosis and linting are unaffected.

Step 2: Check GitHub CLI Auth

gh auth status 2>&1

• Non-zero exit: if the output says "not logged in", report "GitHub CLI is not authenticated. Run: gh auth login" and stop; if it looks like a network error, report "Could not reach GitHub API — check connectivity." and stop.
• Zero exit: record PASS; parse the logged-in account and the Active token scopes: line. Warn (do not stop) if repo or workflow are absent, pointing at gh auth login --scopes repo,workflow,read:org.

Step 3: Check Existing Config

Check whether the runner SSH config file already exists and its YAML front matter (after the opening --- delimiter) contains a schema: 1 line. If it does, read it, count runners (awk '/^[[:space:]]*- name:/{c++} END{print c+0}' — always emits one integer), list the runner names, and ask via AskUserQuestion: "Runner config already exists (N runner(s): …). Reconfigure?"

• No → show the current config summary and stop.
• Yes → continue to Step 4.

If absent, continue to Step 4.

Step 4: SSH Config Wizard (Optional)

Ask via AskUserQuestion: "Do you use self-hosted GitHub Actions runners? (Required for runner health and cleanup)".

• No → prepare a minimal config (no runners block); skip to Step 5.
• Yes → collect runner details below, looping until the user says done.

For each runner, collect and validate (reject and re-prompt on failure — never warn-and-continue):

• Runner name — must match ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$ (length 2-64, DNS-safe).
• SSH host — accept only a private IPv4 (10.x, 127.x, 172.16-31.x, 192.168.x) or an internal FQDN ending in .internal, .local, .lan, .corp, .home, .intra, or .private. Public IPs and public-TLD hostnames are rejected — private network only.
• SSH user — must match ^[a-z_][a-z0-9_-]{0,31}$.
• SSH key path (optional) — if provided, must start with ~/ or /, contain only safe characters, and contain no .. or shell metacharacters. Reject the ~user/... form: it would pass a looser "starts with ~" check, but ci-runner-health's expansion only resolves ~/, so such a key would reach ssh as a literal tilde path and silently fail the probe. Accepting only the forms that are actually expanded keeps setup and health-check in agreement on which key paths are usable.

Security — never place a raw collected value inside a shell heredoc body. A quoted delimiter (<<'EOF') only blocks $/backtick expansion inside the body; it does not stop the body from containing a line that matches the delimiter itself. A value with an embedded newline followed by that line closes the heredoc early, and everything after it runs as shell commands — before any pattern check above ever sees the value. Do not "fix" this with a longer or more unusual delimiter either: this skill body is committed to the repo and world-readable, so a deliberately hostile answer can just reuse whatever delimiter is documented here — a unique delimiter only rules out accidental collision, not a chosen attack.

Instead, treat every raw answer as opaque until it has been checked: write it to a fresh temp file with the Write tool (its content is a structured parameter, never parsed as shell) before it touches any Bash command, then run the pattern check above by reading that file's content (for example, grep -Eq '<pattern>' "$tmpfile") — never by interpolating the raw text inline in a command string or heredoc body. Reject and re-prompt on any check failure, and delete the temp file once the field is accepted or rejected. Only a value that has passed its check — which already excludes newlines, quotes, $, ;, and other shell metacharacters — may be reused afterward.

Step 5: Preview and Confirm, Then Write Config

Preview first (R32). Render the exact config content (schema header, each - name: runner block with host/user/optional ssh_key, and the defaults block) and show it to the user. Then ask via AskUserQuestion: "Write this runner config? [Write / Edit / Cancel]". Only write after explicit confirmation; on a host without AskUserQuestion, obtain an equivalent explicit user confirmation first — never write config without one. Write the confirmed content with the Write tool, not a shell heredoc or redirection — the rendered content still carries the collected host/user/name values, so Step 4's no-heredoc rule applies here too.

Config shape (with runners):

---
schema: 1
runners:
  - name: [name]
    host: [host]
    user: [user]
    ssh_key: ~/.ssh/runner-key   # only when the user provided a key path
defaults:
  ssh_timeout: 3
  max_parallel_ssh: 5
  cache_dirs:
    - /home/runner/.cache
  log_retention_days: 14
  docker_prune_age: 168h
---

## Runner Notes

Configured on [ISO-8601-UTC timestamp]. Edit this file directly to add runners
or change defaults, or re-run setup to reconfigure interactively.

With no runners (user declined), write the same shape with a commented-out # runners: [] placeholder and the defaults block. Create the parent config directory first if it does not exist. Obtain the timestamp with date -u +%Y-%m-%dT%H:%M:%SZ.

Step 6: Validate the Written Config

Confirm the written file's YAML front matter (after the opening --- delimiter) contains schema: 1. Then re-read it and verify: the runner count matches the number collected in Step 4, and each runner name entered appears verbatim. On any mismatch, report it and stop.

Step 7: Report

Report prerequisites, GitHub CLI account/scopes, and the runner config summary (where it was written, runner count, names). If the config was written to a repo-local path (an invoking command's host-resolved path inside the repository), advise: the config contains runner hostnames — if this is a shared repository, add the config to .gitignore to avoid committing host details. The host-neutral fallback location lives outside the repository, so this advice does not apply when the config was written there.

Error Handling

• Missing gh/jq → collect and stop with install links; missing ssh → warn and continue.
• gh not authenticated → "Run: gh auth login"; network error → "Could not reach GitHub API".
• Invalid runner name / SSH host / SSH user / SSH key path → report the specific rule and re-prompt.
• Config directory not creatable, or write/validation failure → report a permissions hint and stop.

Success Criteria

• Prerequisites and auth are reported accurately.
• The runner config is previewed and confirmed before any write, validated after writing, and the written runner names/count match what was collected.