GitHub Connection

The GitHub connection integrates your GitHub repositories with OpsTower, giving agents access to source code and version control data. Agents can browse repositories, read files, search code by pattern, and inspect commit history with full diffs. This is particularly useful for Debugger agents that need to correlate code changes with errors.

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
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
   • public_repo — access to public repositories only
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

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.