GitHub

Source code manager integration

Use this integration to bring GitHub repository assets into Guard for continuous monitoring. You can connect with the Guard GitHub App (recommended) or with a personal access token.

Choose a connection method

• GitHub App (recommended): an organization owner installs the App and chooses which repositories Guard can see. Guard stores no GitHub token for your organization. Praetorian holds the App's private key, which Guard uses to request short-lived tokens.
• Personal access token (PAT): use this when you can't install a GitHub App, when you want to import a personal account's repositories, or when you want Guard to open fix pull requests today (see Fix pull requests).

Read-only access is enough for repository discovery and scanning. Write access is needed only if you want Guard to open fix pull requests, and it is always your choice.

Connect with the GitHub App

1. In Guard, go to Integrations > Source Code Managers > GitHub.
2. Click Install GitHub App. Guard sends you to GitHub's install page. GitHub currently shows the App's name as Praetorian Chariot, its former product name.
3. Choose the organization to install on, then choose All repositories or Only select repositories.
4. Confirm the install. GitHub returns you to Guard, and the integration is connected.

If you are not an owner of the organization, GitHub doesn't install the App. It sends an install request to the organization's owners instead. Guard links the installation to your account when an owner approves the request. An owner must approve within 7 days; after that, start the install again from Guard.

Guard confirms that the person installing owns or administers the installation before it links it, so an installation can't be attached to another Guard account.

Permissions the App requests

The App requests read-only access. It subscribes to no GitHub events.

How the App authenticates

For your connection, Guard stores only the installation ID. Each time it needs to call GitHub, it signs a request with the App's private key and gets a short-lived installation access token for that installation. GitHub expires these tokens after one hour. The token acts as the App, not as any GitHub user, and reaches only the repositories you chose during the install.

To change which repositories Guard can see, edit the App's repository access in your GitHub organization settings under GitHub Apps. To remove access entirely, uninstall the App there.

Connect with a personal access token

Prerequisites

• A GitHub personal access token that can list the repositories you want to monitor. To let Guard open fix pull requests, the token also needs write access (see Fix pull requests).
• The URL of the GitHub organization or user whose repositories Guard should import.
• To import repositories owned by organization members, the token must also be able to list the organization's members. For a fine-grained token, grant the Members organization permission (read). If the token can't list members, Guard still imports the organization's repositories but skips member-owned ones.

Connect

1. In Guard, go to Integrations > Source Code Managers > GitHub.
2. Click Use alternative authentication.
3. Enter your token in Personal Access Token (PAT).
4. Enter the organization or user URL in GitHub Organization, for example github.com/<organization>.
5. Click Connect. Guard validates the token against the organization before saving.

What is imported

• Every repository the credential can list for the organization or user becomes a repository asset. Guard records whether each repository is public. With the GitHub App, that is the repositories you selected during the install.
• For an organization, Guard also lists the organization's members and imports repositories each member owns, with the status Pending.

Webhooks

Guard doesn't receive webhook events from GitHub today. It picks up new repositories and changes to existing ones each time the integration runs.

Fix pull requests

When Constantine produces a patch for a risk in a GitHub repository, Guard can open a pull request with the fix in that repository:

1. Open the risk and select the patch.
2. Click Create Pull Request. Guard creates a branch, commits the patch, and opens a pull request for your team to review.
3. Guard shows View PR #<number> with a link to the pull request.

Guard never merges the pull request; your team reviews and merges it. Guard doesn't yet update the pull request's status in Guard when it is merged or closed.

Opening a pull request needs write access to the repository, which is optional and off by default:

• GitHub App: the App is read-only today, so it can't open fix pull requests yet.
• Personal access token: use a fine-grained token with Contents: Read and write and Pull requests: Read and write on the repositories, or a classic token with the repo scope.

If you don't want Guard to write to your repositories, keep a read-only connection. Scanning works the same either way.

Secrets found in repositories

When Guard finds a secret in a repository, the risk's evidence shows the matched value in full, and exports of that risk include it. Treat these risks and their exports as sensitive, and rotate any exposed secret.