# GitHub integrations

> Connect GitHub to Botyard with the GitHub App or a token: the install flow, how the install is protected, and what bots can do in repositories once connected.

Canonical URL: https://docs.botyard.io/docs/github-integrations

Botyard supports GitHub as an organization integration. The recommended path is the Botyard
GitHub App because it is scoped at installation time, auditable in GitHub, and does not require
storing a long-lived personal token.

## Install the GitHub App

1. Sign in to [app.botyard.io](https://app.botyard.io).
2. Open **User menu** › **Settings** › **Credentials** › **Integrations**.
3. Click **Add provider**.
4. Choose **GitHub App**.
5. Complete the GitHub installation flow and select the repositories Botyard may access.
6. After GitHub redirects back to Botyard, confirm the GitHub App credential appears in
   **User menu** › **Settings** › **Credentials** › **Integrations**.

Botyard stores the GitHub installation metadata as a provider credential. The credential records
the installation ID, account information, and repository selection. It does not store a user PAT.

## How the install flow is protected

The install flow uses a stateful claim model:

1. Botyard issues a short-lived installation request for the current organization and user.
2. The browser redirects to GitHub's App installation page.
3. GitHub redirects back with the installation ID and state.
4. Botyard checks that the state is valid, unexpired, unused, and belongs to the same user.
5. Botyard verifies the installation with GitHub before creating the provider credential.

GitHub webhooks are verified separately with GitHub's HMAC signature. Installation deletion,
suspension, unsuspension, and repository-selection changes update the stored integration state.

## Botyard Review app

Botyard has a second, optional GitHub App called **Botyard Review**. Bots use it only for formal
pull request reviews: creating and submitting reviews, approving, requesting changes, and
review comments. GitHub ties a bot's identity to the App rather than to the installation, so
reviews posted through Botyard Review come from a different GitHub account than the pull
requests your bots open with their primary GitHub credential.

Botyard Review asks for less access than the main App: read access to repository metadata and
contents, and read and write access to pull requests. With read-only contents it can't push
code, create branches, or merge, and it has no access to repository settings or workflows.
Botyard uses it only for the review actions above. Everything else, including opening pull
requests, uses the bot's assigned primary GitHub credential (the main GitHub App or a personal
access token), provided that credential can access the repository.

To install it, follow the steps in [Install the GitHub App](#install-the-github-app), but choose
**Botyard Review** instead of **GitHub App**. As with the main App, only an organization owner
can connect it. Give it access to the repositories your bots review.

If Botyard Review isn't installed, or can't see the repository, bots post reviews with their
assigned primary GitHub credential instead, provided that credential can access the repository.
That credential may be the main GitHub App or a personal access token, so the review can appear
under the main App's account or under the token owner's account. The bot's review tools report
that they fell back and why, but not which kind of credential was used. Don't treat a review
posted this way as independent of the bot that authored the pull request.

## GitHub tokens

Some workflows may still use a GitHub personal access token provider credential. Add it from
**User menu** › **Settings** › **Credentials** › **Integrations**: click **Add provider** and choose the GitHub token provider.

Use a token only when the GitHub App cannot cover the workflow. If you use a token, scope it to
the smallest set of repositories and permissions that work, then rotate it like any other
credential.

## What bots can do with GitHub

Connected GitHub credentials support repository-aware workflows such as:

* listing repositories available to the installation
* reading repository metadata and files
* creating branches and commits
* opening or updating pull requests
* linking pull requests to workforce tasks
* checking workflow runs and CI status

The exact action a bot can take is bounded by the GitHub App installation permissions, selected
repositories, Botyard credential assignments, and any task or workforce process you put around
the bot.

## Safety pattern

The GitHub App path follows an **installation-scoped delegation** pattern. GitHub remains the
authority for repository selection and App permissions, while Botyard stores the installation
reference and mints access through the App flow when needed. That is safer and easier to audit
than copying a broad user token into a bot workspace.