GitHub Connection

The GitHub connection integrates your GitHub repositories with OpsTower, giving agents access to source code, version control data, and pull request activity. Agents can browse repositories, read files, search code by pattern, inspect commit history with full diffs, list and read pull requests, see reviews and comments, and post comments on PRs. This is particularly useful for Debugger agents that need to correlate code changes with errors, and for agents that participate in the review workflow.

Prerequisites

You need a GitHub account with access to the repositories you want to connect. Both public and private repositories are supported, depending on the token scope you configure.

Credentials Required

To set up a GitHub connection, you need one piece of information:

• Personal Access Token (PAT) — a token for authenticating requests to the GitHub API

How to Create a GitHub Personal Access Token

GitHub offers two types of personal access tokens. Fine-grained tokens are recommended because they allow you to limit access to specific repositories and grant only the permissions OpsTower needs.

Option 1: Fine-Grained Token (Recommended)

1. Go to github.com and click your profile picture in the top-right corner.
2. Navigate to Settings > Developer settings > Personal access tokens > Fine-grained tokens.
3. Click Generate new token.
4. Give the token a descriptive name (e.g., “OpsTower”).
5. Set an expiration date. Choose a duration that fits your security requirements.
6. Under Repository access, select the repositories you want OpsTower to access, or choose All repositories if you want full access.
7. Under Permissions, expand Repository permissions and grant the following:
   • Contents — Read access
   • Metadata — Read access
   • Pull requests — Read access (required for read-only PR tools), or Read and write access if you want agents to be able to post comments on pull requests
8. Click Generate token and copy the token immediately. It will not be shown again.

Option 2: Classic Token

1. Go to github.com and click your profile picture in the top-right corner.
2. Navigate to Settings > Developer settings > Personal access tokens > Tokens (classic).
3. Click Generate new token (classic).
4. Give the token a descriptive name (e.g., “OpsTower”).
5. Select the appropriate scope:
   • repo — full access to private and public repositories (covers reading and commenting on pull requests)
   • public_repo — access to public repositories only (covers reading and commenting on PRs in public repos)
6. Click Generate token and copy the token. Classic tokens start with ghp_.

Store the token securely. If you lose it, you will need to create a new one.

Setting Up the Connection in OpsTower

1. In OpsTower, navigate to Connections in the sidebar.
2. Click Add Connection and select GitHub.
3. Enter your Personal Access Token.
4. Click Save to create the connection.

Optional Settings

• Default Branch — the branch to use when none is specified in a query. If left empty, OpsTower uses the repository’s default branch (typically main or master).
• Restrict to Repository — enter a repository in owner/repo format (e.g., acme/backend) to limit the connection to a single repository. When set, agents can only access that specific repository through this connection.

What Agents Can Do with GitHub

Once connected and enabled on an agent, the agent can:

• List repositories — browse all repositories accessible with the configured token
• Browse file structure — navigate directories and list files within a repository
• Read file contents — retrieve the full content of any file in a repository
• Search code — find code matching a pattern across files in a repository
• List commits — view commit history with optional filtering by date range and author
• Get commit details — inspect individual commits including full diffs showing what changed
• List pull requests — list open, closed, or all PRs with branches, labels, draft flag, and updated date
• Get pull request details — read a PR’s title, description, mergeable status, requested reviewers, labels, and stats
• List pull request files — see the changed files and inline diffs for a PR
• List pull request comments — read the main conversation thread on a PR
• List pull request reviews — see who reviewed a PR and what they decided (APPROVED, CHANGES_REQUESTED, COMMENTED)
• List line-level review comments — read inline review comments left on specific lines of changed files
• Post pull request comments — leave a conversation comment on a PR (requires write scope; see token setup above)

Usage

GitHub connections are primarily used with Debugger agents. When investigating errors or incidents, a Debugger agent can use the GitHub connection to correlate code changes with observed issues — for example, checking recent commits to identify changes that may have introduced a bug.

Troubleshooting

• Authentication errors: Verify that your personal access token is correct and has not expired or been revoked. Generate a new token if needed.
• Repository not found: Confirm that your token has access to the repository in question. For fine-grained tokens, check that the repository is included in the token’s repository access list.
• Permission denied on file read: Ensure your token has Contents read permission (fine-grained) or the repo scope (classic).
• No commits returned: Check that the repository has commits on the branch being queried. Verify date range filters if you are using them.
• Pull request not found: Confirm the PR number exists in the repository and that your fine-grained token includes Pull requests read access (or the classic repo scope).
• Posting a PR comment fails with access denied: Your token needs Pull requests with Read and write access (fine-grained) or the repo scope (classic). Re-issue the token with the elevated scope.