> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub App

> Permissions the Blacksmith GitHub App requests, and which product features use them

## Overview

The [blacksmith.sh](https://github.com/apps/blacksmith-sh) GitHub App is the single integration point between Blacksmith and your GitHub organization. Installing it is how Blacksmith registers runners, receives workflow events, and powers observability and [\[code\]smith](/codesmith/overview) agent features; there are no PATs, deploy keys, or other standing credentials involved. You can review the exact permission set on the GitHub App listing before or after install, and choose whether the app can access all repositories or only the ones you select.

The short version:

* **Running your CI needs almost nothing.** Provisioning runners uses the organization self-hosted runners permission plus webhook events. It does not require access to your code.
* **Observability is read-only.** [Run History](/blacksmith-observability/history), [Logs](/blacksmith-observability/logs), [Metrics](/blacksmith-observability/metrics), and [CI Analytics](/blacksmith-observability/dashboard) read workflow run and job data from the Actions API.
* **Write access exists for two features you invoke.** The [Migration Wizard](/introduction/quickstart#use-our-migration-wizard-to-update-your-github-actions-workflow-files) and \[code]smith are the only features that write to your repositories. Both deliver changes through branches and pull requests, and those PRs remain subject to your existing branch protections, required checks, and review rules. The app does not have permission to change or bypass those controls.
* **No secrets, no admin.** The app does not request access to secrets, variables, environments, or any administration permission, and GitHub never exposes secret values over its API in any case.

## Repository permissions

| Permission    | Access       | Used for                                                                                                                                                                                                                           |
| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Metadata      | Read         | Required baseline for every GitHub App. Lets Blacksmith identify the installation and the repositories it can access.                                                                                                              |
| Actions       | Read & write | Read workflow run and job metadata and job logs for Run History, Logs, Metrics, [Monitors](/blacksmith-observability/monitors), and CI Analytics. Write is used to cancel or re-dispatch runs when a product feature calls for it. |
| Contents      | Read & write | Read workflow files for the Migration Wizard and analytics. Create branches and commits when the Migration Wizard or \[code]smith prepares a pull request.                                                                         |
| Workflows     | Read & write | Required by GitHub for any commit that touches `.github/workflows/`. Used solely by the Migration Wizard and \[code]smith when they edit workflow files; nothing else uses this scope.                                             |
| Pull requests | Read & write | Open Migration Wizard and \[code]smith pull requests, which remain subject to your branch protections, required checks, and review rules. Post PR comments (test results, CI summaries) and reply on review threads.               |
| Checks        | Read & write | Post the `[code]smith` check run on a pull request. Read check suites so managed-PR status stays current.                                                                                                                          |
| Issues        | Read         | Required by GitHub to receive pull request comment events, including `@codesmith` mentions.                                                                                                                                        |

## Organization permissions

| Permission                            | Access       | Used for                                                                                                                       |
| ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Administration of self-hosted runners | Read & write | Just-in-time runner registration and deregistration, and runner group management. This is how jobs land on Blacksmith runners. |
| Members                               | Read         | Map GitHub org membership and repository collaborator access onto the Blacksmith dashboard, including the team page.           |

## What we do not request

The Blacksmith GitHub App does **not** request:

* Actions secrets, organization secrets, Dependabot secrets, or Codespaces secrets
* Actions variables or environments
* Administration (repository or organization)
* Packages, deployments, or Dependabot

It cannot read secret values, change org or repository settings, or manage membership.

## Webhook events

The app subscribes to the events it needs to provision runners and keep product features current:

* `workflow_job`, `workflow_run`: runner pickup, run history, logs, monitors, [autofix](/codesmith/autofix)
* `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issue_comment`, `issues`: PR tracking, comments, `@codesmith`
* `check_run`, `check_suite`: `[code]smith` check status and mergeability
* `push`: merge-conflict detection when \[code]smith is enabled
* `organization`, `membership`, `member`, `team`, `repository`: keep dashboard access and repo lists in sync
* `installation`, `installation_repositories`, `installation_target`: install, repo-selection, and rename lifecycle