GitHub Integration

caic integrates with GitHub for automatic pull request creation and CI monitoring. The forge is detected automatically from your repository's git remote URL: no configuration needed for detection.

Config keys are documented in Configuration. This page walks through setup for each integration mode.

Features

• PR creation: after syncing a task branch, caic opens a pull request with the task title and agent summary
• CI monitoring: polls check-runs every 15-30 seconds, notifies the agent when CI passes or fails
• Webhooks (GitHub App): real-time events instead of polling
• Bot automation (GitHub App): auto-creates tasks from issues, PRs, and @caic comments

Choosing a mode

Mode	Best for	Auth	Webhooks	Bot
PAT	Single user, headless	Token in config	No	No
OAuth	Multiple users with login	Login via GitHub	No	No
GitHub App	Org-wide automation	App installation	Yes	Yes

GitHub App can be layered on top of PAT, OAuth, or both. A PAT can also provide server-level GitHub credentials when no user token is available.

PAT setup

For single-user deployments.

1. Create a fine-grained token with:
   • Repository access: select your repositories
   • Permissions: Pull requests (read/write), Checks (read)
2. Add to ~/.config/caic/config.toml:

   [github.pat]
   token = "github_pat_..."

If no token is set and no OAuth is configured, caic falls back to gh auth token from the GitHub CLI automatically.

See your tokens at github.com/settings/personal-access-tokens.

OAuth setup

For multi-user deployments where each user logs in with their GitHub account.

1. Create a GitHub OAuth app
   • Callback URL: https://<your-domain>/auth/github/callback
2. Add to ~/.config/caic/config.toml:

   [server]
   external_url = "https://<your-domain>"
   
   [github.oauth]
   client_id = "<client-id>"
   client_secret = "<client-secret>"
   allowed_users = ["alice", "bob"]

allowed_users restricts login to the listed GitHub usernames. Leave it unset to allow any GitHub user who completes the OAuth flow. Set it to keep login private.

Granting organization access

If your repositories are in an organization:

1. Visit github.com/settings/applications
2. Select your OAuth app
3. Under "Organization access", click Grant

Verify at https://github.com/organizations/<org>/settings/oauth_application_policy: the app should appear as Approved.

Manage your OAuth apps at github.com/settings/developers.

GitHub App setup

For org-wide automation with webhooks and bot-driven task creation.

1. Create a GitHub App
   • Webhook URL: https://<your-domain>/webhooks/github
   • Permissions: Issues (read/write), Pull requests (read/write), Checks (read)
   • Events: Issues, Pull requests, Issue comments, Check suites
2. Generate a private key from the app settings and save the .pem file to ~/.config/caic/
3. Install the app on your organization or repositories (the app must be public for org installs)
4. Add to ~/.config/caic/config.toml:

   [github.app]
   id = 12345
   private_key_pem = "private-key.pem"
   allowed_owners = ["my-org"]
   webhook_secret = "<webhook-secret>"

Generate a webhook secret: openssl rand -hex 32.

Bot triggers

When installed, the bot automatically creates tasks from forge events:

Event	Condition	Action
Issue opened	Issue has caic label	Agent fixes the issue
PR opened	Targets the default branch	Agent reviews the PR
Comment created	Body contains @caic	Agent acts on the instruction

The bot posts comments with links back to your caic instance.

See your apps at github.com/settings/apps and installations at github.com/settings/installations.