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.

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

Sign in to app.botyard.io.
Open User menu › Settings › Credentials › Integrations.
Click Add provider.
Choose GitHub App.
Complete the GitHub installation flow and select the repositories Botyard may access.
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:

Botyard issues a short-lived installation request for the current organization and user.
The browser redirects to GitHub's App installation page.
GitHub redirects back with the installation ID and state.
Botyard checks that the state is valid, unexpired, unused, and belongs to the same user.
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, 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.