Connect GitHub

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_repo
read:user
read:org

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.

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.

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.

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

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.

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.

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.