--- title: Connect GitHub canonical: "https://agentbarn.dev/guides/integrations/github" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Connect GitHub to an Agent Barn Agent with a scoped personal access token, least-privilege repository permissions, generated aai-cli profiles, and validation." tags: [Integrations, How-to, "GitHub administrators, Agent operators, and Organization administrators", GitHub, personal access token, fine-grained token, classic token, repository access, github-work profile, pull requests, GitHub Actions, shared credential] categories: [Guides, Integrations] --- - Integrations - 10–15 minutes - Requires a GitHub personal access token Connect GitHub to let an Agent inspect repositories, work with issues and pull requests, review source code, and examine GitHub Actions runs. Agent Barn stores the token as an encrypted Agent Secret, and configures an `aai-cli` GitHub profile when the Agent starts. **Security boundary** The GitHub token determines which repositories and operations the Agent can access. The repository names entered in Agent Barn configure convenient profiles, but they do not restrict what the token itself can reach. ## Connection model 1. GitHub PAT 2. Encrypted Agent Secret 3. aai-cli profile 4. Repository operations The credential authenticates the Agent. The GitHub Skill supplies the `aai-cli` workflows the Agent runs against it. ## Before you begin You need: - A GitHub account permitted to access the intended repositories - Permission to create a personal access token - Access to configure the Agent - `agent.update` and `agent.secret.manage` permissions - Lifecycle permission when connecting a running Agent - The GitHub owner or organization name - The bare names of the intended repositories - An access plan defining whether the Agent can read or write Decide whether to use a Fine-grained personal access token, a Classic personal access token, or an existing Organization Shared Credential. ## Choose a token type Fine-grained personal access tokens are the preferred choice when the organization permits them. ### Fine-grained PAT **Advantages:** repository selection, granular permissions, and expiration controls. **Tradeoffs:** may require organization approval and careful permission selection. ### Classic PAT **Advantages:** broad compatibility and familiar scopes. **Tradeoffs:** scopes are broader and offer less repository-level control. Use a Classic token only when a required workflow cannot use a Fine-grained token, or organizational policy requires it. ## Plan the required permissions Grant permissions based on the Agent’s intended workflow. | Agent capability | Suggested Fine-grained permission | | --- | --- | | Read repository metadata | Metadata: Read | | Read source files and commits | Contents: Read | | Read pull requests | Pull requests: Read | | Comment on or review pull requests | Pull requests: Read and write | | Read issues | Issues: Read | | Create or comment on issues | Issues: Read and write | | Inspect workflow runs and logs | Actions: Read | | Modify repository contents | Contents: Read and write | Do not grant write permissions merely because they are available. **Important** Agent Barn’s live validator checks identity and selected repository access, but it cannot prove that every future GitHub operation has the required permission. Test the actual workflows the Agent will perform. ### Classic token scopes For a Classic PAT, Agent Barn’s validator recognizes `repo` for private and public repository access, `public_repo` for public-repository-only access, `read:user`, and `read:org`; the last is recommended for organization repositories. The broader `user` and `admin:org` scopes also satisfy the identity and organization checks, but should not be granted merely for validation. **Security** The `repo` scope is broad. Prefer a Fine-grained token for restricted production access. ### Public repositories **Public repositories** Agents can work with public repositories. Prefer a Fine-grained token limited to the required public repository access, granting Metadata: Read and Contents: Read, and adding Pull request or Issue permissions only when needed. A Classic PAT can use `public_repo`, but that scope is broader than simple read-only source access. Agent Barn still expects a token for a configured GitHub integration. Public repository visibility does not bypass the encrypted credential and profile setup used by `aai-cli`. ## Create the personal access token ### Create a Fine-grained token 1. Open your account’s developer settings. 2. Go to personal access tokens. 3. Choose **Fine-grained tokens**. 4. Create a new token. 5. Enter a descriptive name, such as `Agent Barn: Support Reviewer`. 6. Set an expiration date. 7. Select the intended resource owner. 8. Select only the required repositories. 9. Grant the minimum repository permissions. 10. Create the token. 11. Copy it immediately. For a read-only code-review Agent, begin with: ``` Metadata: Read Contents: Read Pull requests: Read ``` Add Pull requests: Read and write only if the Agent must post comments, submit reviews, approve, or request changes. An organization may require administrator approval before the token can access its repositories. ### Create a Classic token 1. Open GitHub developer settings. 2. Go to **Tokens (classic)**. 3. Create a new token. 4. Enter a descriptive note. 5. Set an expiration date. 6. Select the minimum required scopes. 7. Create and copy the token. ### Public repositories ``` public_repo read:user read:org ``` ### Private repositories ``` repo read:user read:org ``` Review the broad access implied by `repo` before using the token. ### Configure organization access For repositories owned by a GitHub organization, confirm that: - The token’s resource owner is correct - The repository is included in the token’s repository selection - The organization approved the token when approval is required - The account can access the repository - Organization authentication policies are satisfied - The granted permissions match the intended operation A correctly formatted token can still receive `404` for a private repository when the account or token lacks access. ## Understand the Agent Barn fields | Field | Purpose | | --- | --- | | Personal access token | Authenticates the GitHub account | | Owner / Org | Default GitHub user or organization | | Repositories | Optional repository names used to build profiles | ### Enter bare repository names ``` agent-barn aai-cli website ``` ### Do not enter owners or URLs ``` aai-labs/agent-barn https://github.com/aai-labs/agent-barn ``` The same Owner / Org value is stored as the GitHub profile’s `owner` and `org`. ## Repository list versus token access The optional repository list configures `aai-cli` profiles. It is not an enforcement boundary. ### GitHub token Authorizes every request. It can reach any repository GitHub allows it to reach, whatever Agent Barn lists. **This is the real security boundary.** ### Agent Barn repository list Creates convenient profile defaults, so commands need fewer explicit flags. **This is a convenience, not an authorization control.** Even when a repository list is configured, an `aai-cli` command can explicitly pass another `--owner` and `--repo`. GitHub then authorizes the request using the token. To prevent access to another repository, restrict the token in GitHub. **Warning** Never rely on the Agent Barn repository list to compensate for an overly broad token. ## Connect GitHub in Agent Barn 1. Stop the Agent, or begin the web interface’s restart-aware edit flow. 2. Open the Agent. 3. Go to **Configuration**. 4. Select **Keys & integrations**. 5. Select **Edit**. 6. Add **GitHub** under Integration credentials. 7. Choose **Enter credentials**. 8. Paste the personal access token. 9. Enter the GitHub owner or organization. 10. Add the intended repository names. 11. Apply the configuration. 12. Restart the Agent if it was running. 13. Validate the credential. 14. Test repository access. The token value becomes hidden after it is saved. ### Use a Shared GitHub Credential GitHub is supported by Organization Shared Credentials. To attach one: 1. Open the Agent’s integration configuration. 2. Select GitHub. 3. Choose **Use shared credential**. 4. Select the named GitHub credential. 5. Apply the configuration. 6. Restart the Agent. 7. Validate and test access. **Shared credential** The Agent stores a reference to the Shared Credential rather than another encrypted token copy. An Agent can use either a manual GitHub credential or a Shared GitHub Credential, not both. See [Use shared credentials](/guides/integrations/shared-credentials) for the complete management boundary. ### Assign the GitHub Skill The credential supplies authentication. The GitHub Skill supplies detailed instructions for using GitHub through `aai-cli`. If the active Template requires the GitHub Skill: 1. Open the Agent’s **Skills** configuration. 2. Confirm that GitHub is assigned. 3. Confirm the expected Skill version. 4. Save the Agent configuration. 5. Start the Agent. Agent Barn may mount eligible Built-in provider Skills from configured credentials at startup. Explicit Template Skill requirements still require an explicit Skill assignment. ## Validate the credential 1. Open **Keys & integrations**. 2. Find **GitHub**. 3. Select **Validate**. 4. Confirm the authenticated GitHub username. 5. Review any missing permissions. 6. Resolve warnings before production use. Validation begins with: ``` GET https://api.github.com/user ``` For a Classic PAT, Agent Barn inspects the reported OAuth scopes. For a Fine-grained PAT with configured repositories, Agent Barn probes each repository and its pull request endpoint. ``` { "validation_status": "valid", "validation_identity": "octocat", "validation_error": null, "missing_scopes": [] } ``` A token can authenticate successfully while returning warnings: ``` { "validation_status": "warning", "validation_identity": "octocat", "validation_error": null, "missing_scopes": [ "example-org/private-repo: Repository contents read access" ] } ``` ### Fine-grained validation without repositories If the GitHub credential has no configured repository names, Agent Barn validates the token’s identity but does not probe repository access. ``` Token authentication: validated Repository access: not tested ``` **Important** A successful identity result does not prove access to every repository. Add the intended repositories and validate again, or test them through a controlled Agent task. ## Verify access **Verification** Verify reads before writes, and use a designated test repository or pull request for anything that changes state. ### Verify repository listing ``` List the GitHub repositories available for the configured organization. ``` ``` aai-cli github repos list --limit 10 --profile github-work ``` `repos list` does not require a `--repo` value. Confirm that only expected repositories are returned. If unexpected repositories appear, restrict the token in GitHub. ### Verify source access ``` Read README.md from the main branch of the agent-barn repository. ``` ``` aai-cli github source get main README.md \ --owner aai-labs \ --repo agent-barn \ --profile github-work ``` Every repository-specific command should explicitly include: ``` --profile github-work --owner OWNER --repo REPOSITORY ``` ### Verify pull request access ``` aai-cli github prs list \ --owner aai-labs \ --repo agent-barn \ --state open \ --limit 10 \ --profile github-work ``` Test comments or reviews only against a designated test pull request, and only when the token intentionally has write permission. ### Verify issue access ``` aai-cli github issues list \ --owner aai-labs \ --repo agent-barn \ --limit 10 \ --profile github-work ``` Do not begin by creating or editing issues unless the Agent’s role requires it. ## Multiple repository profiles When multiple repositories are configured, Agent Barn creates profiles such as: ``` github-work github-work-2 github-work-3 ``` All profiles use the same token and owner, but have different default repositories. The Agent’s runtime context records the mapping: ``` github-work → aai-labs/agent-barn github-work-2 → aai-labs/aai-cli github-work-3 → aai-labs/website ``` Commands can normally continue using `github-work` while explicitly passing `--owner` and `--repo`. Do not guess a numbered profile’s repository mapping; review the Agent’s generated integration context. ### No configured repository An empty repository list creates one profile without a default `repo`. ``` [profiles.github-work] provider = "github" auth_type = "bearer_token" owner = "aai-labs" org = "aai-labs" ``` Repository-specific commands must then provide `--repo REPOSITORY`. Omitting it produces a configuration error. Leaving the list empty does not mean “no repository access.” The token can still reach repositories allowed by GitHub. ## Runtime behavior When the Agent starts, Agent Barn: 1. Decrypts the GitHub credential. 2. Stores the token in the runtime secret store. 3. Creates one or more `aai-cli` profiles. 4. Mounts eligible GitHub Skill instructions. 5. Adds the configured owner and repository mappings to the tool context. 6. Tells the Agent that credentials are already available. ``` Encrypted GitHub Agent Secret │ ▼ Agent start │ ├── Secret: github.token ├── Profile: github-work └── GitHub Skill instructions │ ▼ GitHub API ``` **Runtime** The Agent should not ask users to paste a GitHub token into conversation. The runtime supplies the profile and token automatically. ## Rotate the token 1. Create the replacement token in GitHub. 2. Give it the intended repository access and permissions. 3. Stop the Agent, or begin a restart-aware edit. 4. Open **Keys & integrations**. 5. Enter a complete replacement GitHub credential. 6. Re-enter the Owner / Org and repository list. 7. Apply and restart. 8. Validate the replacement. 9. Test repository and pull request access. 10. Revoke the old token in GitHub. Stored credential values cannot be retrieved or partially edited. Submit the complete replacement payload. ### Change repository access 1. Update the token’s repository selection in GitHub. 2. Update its permissions if required. 3. Update the Agent Barn repository profile list for clarity. 4. Restart the Agent. 5. Validate each configured repository. 6. Run controlled source and pull request tests. Changing the Agent Barn repository list alone does not change GitHub authorization. ## Remove GitHub access 1. Stop the Agent, or begin a restart-aware configuration edit. 2. Identify any assigned Skill requiring `github`. 3. Remove or replace that Skill when permitted. 4. Open **Keys & integrations**. 5. Select **Remove** for GitHub. 6. Apply the configuration. 7. Restart the Agent. 8. Confirm that GitHub is no longer available. 9. Revoke the token in GitHub. Agent Barn rejects removal if a remaining assigned Skill requires the GitHub provider. ## API reference ### Add or replace a GitHub credential The Agent must be stopped. ``` PATCH /api/v1/organizations/{organization_id}/agents/{agent_id} Content-Type: application/json ``` ``` { "secrets": [ { "provider": "github", "content": { "token": "github_pat_REDACTED", "owner": "aai-labs", "org": "aai-labs", "repos": [ "agent-barn", "aai-cli" ] } } ] } ``` The `owner` and `org` fields normally contain the same GitHub login. Every token value in these examples is redacted; supply your own. ### Configure no default repositories ``` { "secrets": [ { "provider": "github", "content": { "token": "github_pat_REDACTED", "owner": "aai-labs", "org": "aai-labs", "repos": [] } } ] } ``` The Agent must pass a repository name explicitly for repository-specific commands. ### Attach a Shared GitHub Credential ``` { "shared_credentials": [ { "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca" } ] } ``` ### Validate GitHub ``` POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/github/validate ``` Validation requires `agent.secret.manage`. ### Remove GitHub ``` { "removed_secret_providers": [ "github" ] } ``` ## Troubleshooting ### Validation says the token is invalid or expired Rotate and resubmit Create or rotate the token in GitHub, submit the complete replacement credential, and validate again. ### Validation succeeds but shows missing permissions Authentication is not authorization Authentication succeeded, but the token may not support the intended workflow. Review: - Repository selection - Contents permission - Pull request permission - Issue permission - Actions permission - Organization approval ### A private repository returns 404 GitHub hides inaccessible repositories GitHub often returns `404` when the authenticated token cannot access a private repository. Check the owner, repository name, token repository selection, account membership, and organization approval. ### A public repository cannot be read Check names, token, and flags Confirm that: - The owner and repository are spelled correctly - The token can authenticate - A Fine-grained token has the needed public repository access - A Classic token includes an appropriate public repository scope - The command passes `--owner` and `--repo` ### Validation did not test repository access No repositories were configured Fine-grained validation skips repository probes when the Agent Barn repository list is empty. Add the intended repository names and validate again. ### The Agent accesses repositories not listed in Agent Barn The list is not a boundary The repository list configures profiles, not authorization. Restrict the token’s repository selection and permissions in GitHub. ### The Agent says --repo is missing No default repository in the profile No default repository is configured for the selected profile. Pass `--repo REPOSITORY` explicitly, or add repository names to the GitHub credential. ### Pull request listing works, but comments fail Read is not write The token probably has Pull requests: Read but not Read and write. Grant write access only if the Agent should post comments or reviews. ### Source access works, but GitHub Actions logs fail Actions is a separate permission Actions access uses a separate repository permission. Grant Actions: Read if the Agent needs workflow runs, jobs, or logs. ### The token is awaiting organization approval An administrator must approve it An organization administrator must approve the Fine-grained token before it can access the selected organization resources. ### A Shared Credential conflicts with a manual token One source per provider An Agent can use only one GitHub credential source. Remove the manual credential before attaching the Shared Credential, or replace the Shared attachment with a manual credential. ### GitHub was connected but the Agent cannot use it Restart, Skill, profile, or token scope Check that: - The Agent restarted after the credential was saved - The GitHub Skill is assigned when required - The expected Skill version is pinned - The `github-work` profile was generated - The requested repository is allowed by the token - Startup logs contain no Skill mount errors ## Recommended practices - Prefer Fine-grained personal access tokens - Use a dedicated GitHub identity for production Agents - Select only the required repositories - Grant Metadata and Contents read before adding write access - Grant Pull request write only for reviewing or commenting Agents - Keep Issue and Actions permissions aligned with the documented workflow - Set token expiration dates - Treat the token as the true repository authorization boundary - Keep the Agent Barn repository list accurate for profile clarity - Validate every configured repository - Test read operations before write operations - Rotate tokens on a documented schedule - Revoke replaced and unused tokens - Review organization token approvals regularly - Never place tokens in Templates, Skills, prompts, or conversations ## Next steps Continue to [Connect Jira](/guides/integrations/jira) to configure an Atlassian API token and scope an Agent to the intended Jira site and projects. - [Manage Agent credentials](/guides/integrations/credentials) - [Use shared credentials](/guides/integrations/shared-credentials) - [Work with Skills](/guides/templates-and-skills/skills)