GitHub AI Agent Integration

Overview

The GitHub integration connects your Claws to your repositories using a personal access token (PAT). Once configured, Claws can create and manage issues, review pull requests, search code across repos, analyze commit history, and respond to webhook events, all from within their isolated ClawCage containers. This turns your Claws into active participants in your development workflow, handling the repetitive work that slows your team down.

Unlike OAuth-based integrations, GitHub uses a personal access token model. You generate a fine-grained PAT in your GitHub settings with the exact repository and permission scopes you want, then provide it to ClawStaff. This gives you granular control over what each Claw can access and do.

What Your Claw Can Do

• Create and manage issues. Claws can file new issues from conversations in other tools, add labels, assign team members, link related issues, and close them when the work is complete. Issue descriptions support full GitHub Markdown.
• Review pull requests. Claws can read PR diffs, leave line-level review comments, approve or request changes, and post summary reviews. They can enforce coding standards, catch common mistakes, or verify that PR descriptions meet your team’s template.
• Search code across repositories. Full code search using GitHub’s search API. Claws can find usage patterns, locate configuration files, identify deprecated API calls, or trace function references across your organization’s repos.
• Analyze commit history. Claws can read commit logs, compare branches, identify who last modified a file, and generate changelogs from commit messages between two tags or dates.
• Respond to webhook events. Configure GitHub webhooks to notify ClawStaff of events like push, pull_request, issue, or release. Claws can react in real-time: auto-labeling issues, posting review comments, or triggering cross-tool workflows.
• Repository management. Claws can read repository metadata, list branches, check workflow run statuses, and interact with GitHub Actions artifacts.

Who Can Reach Your Claw

GitHub access is scoped through the personal access token itself. The PAT defines which repositories and permissions the Claw has:

• By repository. Fine-grained PATs let you scope access to specific repositories. A Claw with a PAT that only grants access to frontend-app and api-server cannot see or interact with any other repository in your organization.
• By permission type. Each resource type (issues, pull requests, code, actions) can be independently set to no access, read-only, or read-write. A Claw that only needs to read issues and create comments does not get push access.

This works alongside three Claw scoping levels:

Private Claw. Only the creator interacts. The Claw works with your personal repos or monitors repos you have access to, responding only to you via Slack DM or another private channel. Example: a personal coding assistant that reviews your PRs, summarizes your open issues, and drafts commit messages.

Team Claw. Whitelisted team members share the Claw. It monitors team repos and responds in the team’s Slack channel. Only whitelisted engineers can trigger it. Example: an engineering team Claw that auto-labels new issues, posts PR review summaries in #engineering, and generates changelogs.

Organization-wide Claw. Any org member can interact. The Claw serves as a company-wide code search or issue triage tool. The PAT still scopes which repos it can access, so organizational access does not mean access to every repository.

How It Works

1. Generate a fine-grained PAT. In your GitHub account settings, create a personal access token with the specific repositories and permissions your Claw needs. Fine-grained tokens let you limit access to individual repos with read-only or read-write scopes per resource type.
2. Add the token to ClawStaff. Paste your PAT into the GitHub integration card on the ClawStaff dashboard. The token is immediately encrypted and stored.
3. Assign to a Claw. Connect the GitHub credential to one or more Claws. Each Claw receives the token at runtime inside its ClawCage.
4. Configure webhooks (optional). For real-time event handling, add ClawStaff’s webhook URL to your repository settings. When events fire, they are routed to the appropriate Claw for processing.
5. Claw works your repos. At runtime, the Claw uses the PAT to call GitHub’s REST and GraphQL APIs from within its isolated container. All actions are attributed to the PAT owner’s GitHub account.

Security

• Fine-grained PATs. GitHub’s fine-grained personal access tokens let you scope access to specific repositories with per-resource permissions. A Claw with read-only issue access cannot push code or modify workflows.
• Token encrypted at rest. Your PAT is stored with AES-256 encryption in ClawStaff’s database. It is decrypted only at runtime, inside the ClawCage container.
• ClawCage isolation. Each Claw runs in a dedicated Docker container. The GitHub token is injected as an environment variable at startup and is not accessible to other Claws, other containers, or the host system.
• No credential sharing. Each Claw gets its own copy of the token at runtime. Revoking the PAT in GitHub immediately cuts off access for all Claws using it.
• Webhook signature verification. Incoming webhook payloads are verified using GitHub’s HMAC signature to prevent spoofed events from triggering Claw actions.
• Audit attribution. All GitHub API calls made by a Claw are attributed to the PAT owner’s account. Actions appear in GitHub’s audit log and activity feeds, maintaining a clear trail.

Cross-Integration Workflows

The GitHub integration is a natural hub for cross-tool automation:

• Slack alert to GitHub issue. When a team member reports a bug or requests a feature in Slack, a Claw can create a GitHub issue with the conversation context, apply appropriate labels, and link back to the Slack thread.
• PR merged to Slack notification + Jira update. When a pull request is merged, a Claw can post a summary to the team’s Slack channel and transition the linked Jira ticket to “Done” with a comment containing the merge commit hash.
• Code review to Notion documentation. After reviewing a PR that introduces a new API endpoint or changes system behavior, a Claw can update the relevant Notion documentation page with the new details.
• GitHub issue labeled “urgent” to Slack escalation. When an issue is labeled with a high-priority tag, a Claw can immediately alert the on-call channel in Slack with issue details and a direct link.
• Release published to Confluence release notes + Slack announcement. When a new GitHub release is created, a Claw can generate formatted release notes in Confluence and post an announcement to Slack with highlights and breaking changes.