cyrus-setup-github

What this skill does

**CRITICAL: Never use `Read`, `Edit`, or `Write` tools on `~/.cyrus/.env` or any file inside `~/.cyrus/`. Use only `Bash` commands (`grep`, `printf >>`, etc.) to interact with env files — secrets must never be read into the conversation context.**

# Setup GitHub

Configures GitHub CLI and git so Cyrus can create branches, commits, and pull requests. Optionally creates a GitHub App so Cyrus can receive and respond to @mentions in PR comments and reviews, automate rebases and merges, and auto-fix based on CI failures (coming soon).

---

## Part A: GitHub CLI + Git Config (Outbound)

### Step 1: Check Existing Configuration

Check if `gh` is already authenticated:

```bash
gh auth status 2>&1
```

If authenticated, check git config:

```bash
git config --global user.name
git config --global user.email
```

If both `gh` auth and git config are set, inform the user:

> GitHub is already configured. Skipping to webhook setup.

Skip to Part B.

### Step 2: Authenticate GitHub CLI

If `gh` is not authenticated:

```bash
gh auth login
```

This opens an interactive browser flow. Let the user complete it.

After completion, verify:

```bash
gh auth status
```

### Step 3: Configure Git Identity

If git user name or email are not set, ask the user for their preferred values:

> **What name should appear on commits made by Cyrus?**
> (e.g., your name, or "Cyrus Bot")

> **What email should appear on commits?**
> (e.g., your email, or a noreply address)

Then set them:

```bash
git config --global user.name "<name>"
git config --global user.email "<email>"
```

### Step 4: Verify

```bash
gh auth status
git config --global user.name
git config --global user.email
```

---

## Part B: GitHub App + Webhooks (Inbound — Optional)

Ask the user:

> **Do you want Cyrus to respond to GitHub @mentions in PR comments and reviews?**
>
> - **Yes — enable @mentions**: Creates a GitHub App so Cyrus can receive PR comments and reviews via webhooks, respond when @mentioned, and act on "changes requested" reviews.
> - **No — PRs only**: Cyrus will create branches, commits, and PRs but won't respond to comments.

If **No** → skip to Completion.

### Step 5: Check Existing Webhook Config

```bash
grep -c '^GITHUB_WEBHOOK_SECRET=.' ~/.cyrus/.env 2>/dev/null
grep -c '^GITHUB_APP_ID=.' ~/.cyrus/.env 2>/dev/null
grep -c '^GITHUB_APP_INSTALLATION_ID=.' ~/.cyrus/.env 2>/dev/null
test -f ~/.cyrus/github-app.pem && echo "PEM exists" || echo "PEM missing"
```

If all four checks pass (1, 1, 1, "PEM exists"), skip to Completion — webhooks are already configured.

### Step 6: Collect Inputs

Read the webhook base URL:

```bash
grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-
```

If `CYRUS_BASE_URL` is not set, stop and tell the user to run the endpoint setup step first.

Use the `AGENT_NAME` value from the orchestrator (set in Step 0 of `/cyrus-setup`). If not available, ask:

> **What should the GitHub App be named?** (e.g., "Cyrus", "My Code Agent")

**Important — GitHub @mention autocomplete quirk:** GitHub's autocomplete in PR comments only suggests real GitHub *user accounts*, not App bots. This means `@your-bot` won't appear in the autocomplete dropdown unless a GitHub user with that exact name exists. The mention still *works* if typed manually, but for the best experience:

> **Before choosing a name**, check if the same name is available as a GitHub username at `https://github.com/<name>`. If it is:
>
> 1. Create a free GitHub user account with that name
> 2. Invite it to your org and/or repo as a collaborator
> 3. Set `GITHUB_BOT_USERNAME` to that username (the one users will type in @mentions, *not* `<slug>[bot]`)
>
> This is the simplest way to get autocomplete working — a silly GitHub limitation, but the known workaround.
>
> **Without a matching GitHub user**, @mentions still work if typed manually, but won't autocomplete. In that case users would need to set up co-authorship (via a git message template or `prepare-commit-msg` hook adding `Co-authored-by:`) to get the bot's name showing as a repo contributor, which is more involved.

Ask:

> **Where should the GitHub App be created?**
> - **Personal account** (github.com/settings/apps)
> - **Organization** — which org? (github.com/organizations/`<ORG>`/settings/apps)

Store the org name if applicable.

Ask:

> **What homepage URL should the GitHub App use?** This is displayed on the app's settings page as its website. It has no functional impact — GitHub just shows it as a link. Most users use their company website, GitHub org page, or any placeholder URL.
>
> (e.g., `https://github.com/your-org`, your company URL, or just `https://example.com`)

### Step 7: Build Manifest JSON

Construct the manifest, substituting `AGENT_NAME`, `HOMEPAGE_URL`, and `CYRUS_BASE_URL`:

```json
{
  "name": "<AGENT_NAME>",
  "url": "<HOMEPAGE_URL>",
  "redirect_url": "http://localhost:8976",
  "hook_attributes": {
    "url": "<CYRUS_BASE_URL>/github-webhook",
    "active": true
  },
  "public": false,
  "default_permissions": {
    "contents": "write",
    "issues": "write",
    "pull_requests": "write",
    "repository_hooks": "write"
  },
  "default_events": [
    "issue_comment",
    "organization",
    "pull_request_review",
    "pull_request_review_comment",
    "repository"
  ]
}
```

**Note:** `redirect_url` is required by GitHub's manifest flow. The actual redirect will include a `?code=` parameter appended to this URL — the code is what matters, not the destination page.

### Step 8: Create GitHub App via Manifest

GitHub's manifest flow works by POSTing a form with a `manifest` field to the app creation URL. After the user approves, GitHub redirects to a URL containing a `code` parameter.

Determine the creation URL:
- Personal: `https://github.com/settings/apps/new`
- Organization: `https://github.com/organizations/<ORG>/settings/apps/new`

GitHub's manifest flow requires a **form POST** with a `manifest` field to the creation URL — the page itself does not have a manifest input field. All paths use the same helper HTML page approach.

First, create the helper page and serve it via a local web server. This works for both local and remote/headless setups (e.g., tmux/SSH into a server). The manifest JSON must be HTML-entity-escaped (replace `"` with `&quot;`) since it's placed in an HTML attribute:

```bash
# Escape the manifest JSON for safe embedding in an HTML attribute
MANIFEST_HTML_ESCAPED=$(echo '<MANIFEST_JSON>' | sed 's/"/\&quot;/g')

cat > /tmp/github-app-manifest.html << HTMLEOF
<form method="post" action="<CREATION_URL>">
  <input type="hidden" name="manifest" value="$MANIFEST_HTML_ESCAPED">
  <p>Click the button to create the GitHub App:</p>
  <button type="submit" style="font-size:18px;padding:12px 24px;">Create GitHub App</button>
</form>
HTMLEOF

# Serve the page on a local port (works for headless/remote setups)
python3 -m http.server 8976 --directory /tmp &
HTTP_SERVER_PID=$!
echo "Serving at http://localhost:8976/github-app-manifest.html"
```

After the user completes the flow, stop the server:

```bash
kill $HTTP_SERVER_PID 2>/dev/null
```

Choose the automation path based on what's available:

1. If `claude-in-chrome` MCP tools are available → use **Path A-1**
2. If `agent-browser` is installed and a Chrome debug session is connected → use **Path A-2**
3. Otherwise → use **Path B** (manual)

**Path A-1 (claude-in-chrome):**

1. Navigate to `http://localhost:8976/github-app-manifest.html`
2. Click the submit button to POST the manifest to GitHub
3. GitHub shows a confirmation page — click **Create GitHub App**
4. After redirect, extract the `code` parameter from the URL

**Path A-2 (agent-browser):**

Same flow via `agent-browser` — navigate to the helper page, click submit, then click Create.

**Path B (manual):**

Tell the user:

> 1. Open `http://localhost:8976/github-app-manifest.html` in your browser and click the button
> 2. Review the permissions on GitHub and click **Create GitHub App**
> 3. After redir