Configure GitHub for Cyrus — gh CLI login and git config for PRs, with optional webhook setup to enable @mention responses in PR comments, automated rebases and merges, and auto-fixing based on CI failures (coming soon).

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: If authenticated, check git config: 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: This opens an interactive browser flow. Let the user complete it. After completion, verify: 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: Step 4: Verify 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 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: 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 : 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 " ) since it's placed in an HTML attribute: After the user completes the flow, stop the server: 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 redirect, copy the entire URL from the browser address bar and paste it here Extract the code parameter from the redirect URL. Step 9: Exchange Code for Credentials IMPORTANT: The /app manifests/<CODE /conversions endpoint is one time use. Call it exactly once. Step 10: Write Credentials to Env Verify all values were written: All checks must pass (return 1, 1, 1, "PEM exists"). Step 11: Install App on Repositories The GitHub App must be installed on the repositories Cyrus will monitor. Go to: https://github.com/apps/<GITHUB APP SLUG /installations/new Select which repositories (or "All repositories") and click Install . Or via browser automation (navigate to URL, select repos, click Install). After installation, capture the installation ID: If there are multiple installations, ask the user which one to use. Then write the installation ID: Verify: Must return 1. Completion ✓ GitHub CLI authenticated ✓ Git identity configured: <name < email If webhooks were enabled: ✓ GitHub App created: <GITHUB APP SLUG ✓ Webhook secret and app credentials saved to ~/.cyrus/.env ✓ Private key saved to ~/.cyrus/github app.pem ✓ App installed (installation ID: <GITHUB APP INSTALLATION ID ) ✓ Cyrus will respond to @<GITHUB BOT USERNAME mentions in PR comments Note: The webhook URL will only respond successfully once Cyrus is running. If GitHub shows a webhook delivery failure during setup, it will retry automatically once Cyrus starts.

cyrus-setup-github