GitHub Integration

ElasticClaw uses a GitHub App (not a personal access token) for integration. The app is installed on your org or repos, and ElasticClaw authenticates as the app to act on your behalf.

Agents can:

• Clone and read repositories installed on the app
• Create branches and push commits
• Open, update, and manage pull requests
• Read checks and publish status updates when workflows need them
• Clone private repos using the app's installation token

A personal access token belongs to a human user. If you give it to an agent system, every agent effectively inherits that user's reachable repositories and permissions. That is too broad for automated coding work.

GitHub Apps give ElasticClaw a narrower security model:

• Repo-scoped installs — install the app only on repos agents should access
• Permission-scoped access — request only contents, pull requests, checks, and any issue-tracker permissions needed by the workflow
• Short-lived tokens — ElasticClaw Server mints installation tokens when an agent needs repo access instead of storing a long-lived user token
• Bot identity — commits, comments, and PRs are attributed to the app instead of a maintainer's personal account
• Revocation boundary — uninstalling or restricting the app cuts off access without rotating a human's credentials

In practice, this lets each workspace declare the repos it needs and lets ElasticClaw Server mint a token for that installation at agent creation time.

1. Go to GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App
2. Set the app name, homepage URL, and callback URL (or use a placeholder)
3. Enable these permissions:
   • Repository: Contents (read & write)
   • Repository: Issues (read & write)
   • Repository: Pull requests (read & write)
   • Repository: Checks (read & write)
4. Generate and download a private key (.pem file)
5. Note the App ID from the app settings page

On the app settings page, click Install App and select the repos or org you want ElasticClaw to access. ElasticClaw discovers the matching installation for each requested repo at runtime; you do not configure an installation ID.

Store GitHub App credentials on the workspace that needs repository access. You can use the server settings UI or the CLI:

elasticclaw github-app create app-bot \
  --workspace my-app \
  --app-id 123456 \
  --url https://github.com/apps/my-app \
  --installation my-org \
  --private-key-file ./my-app.private-key.pem

elasticclaw github-app list --workspace my-app

ElasticClaw Server tries the GitHub Apps configured on the workspace to find an installation that covers the requested repos. One app can cover multiple orgs if installed on all of them.

Workspaces can specify which repos the agent needs access to:

# elasticclaw-config.yaml
repositories:
  - repo: "my-org/my-repo"
    permissions: "write"
  - repo: "my-org/other-repo"
    permissions: "read"

ElasticClaw Server resolves the right GitHub App installation and mints a token with the requested repo permissions. permissions is eitherread or write; omitted values default to read.