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.
2. Open Credentials.
3. Select Integrations.
4. Click Add credential.
5. Choose GitHub App.
6. Complete the GitHub installation flow and select the repositories Botyard may access.
7. After GitHub redirects back to Botyard, confirm the GitHub App credential appears in 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.

GitHub tokens

Some workflows may still use a GitHub personal access token provider credential. Add it from Credentials -> Integrations -> Add credential 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.