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

# GitHub App

> Install and link the Aspect Workflows GitHub App so authenticated Aspect CLI features can post live status checks and inline lint comments on your GitHub pull requests.

The **[Aspect Workflows GitHub App](https://github.com/apps/aspect-workflows)** puts live Bazel build & test results on every pull request. Driven by the [Aspect CLI](/docs/cli/overview), it posts per-task status checks and inline lint comments to your PR as your Bazel build runs — surfacing test failures the moment they happen, not after the whole job finishes.

Mechanically, the App is what lets the Aspect API call GitHub on your behalf. Install it once on your GitHub organization and link it to your Aspect account, and authenticated CLI features — `GithubStatusChecks`, `GithubStatusComments`, and `GithubLintComments` — start posting results to your pull requests.

This page covers installing and linking the App. For the account setup and the `ASPECT_API_TOKEN` your CI uses, see [Authenticating the Aspect CLI](/docs/cli/authentication).

<Note>
  Using GitLab? See the [GitLab App](/docs/cli/authentication-gitlab) for the equivalent.
</Note>

## What the App enables

Once installed and linked, these CLI features can post to GitHub from your CI runs:

* **`GithubStatusChecks`** — per-task pass/fail status checks on the commit under review, updated live as tasks finish. Test failures surface while the build is still running, so you get time-to-failure feedback without waiting for the whole job.
* **`GithubStatusComments`** — a single PR task summary comment that aggregates every task's live status into one comment, updated as jobs complete.
* **`GithubLintComments`** — `aspect lint` findings posted as inline PR review comments, with one-click suggestion blocks. See [`aspect lint`](/docs/cli/tasks/lint#github-pr-annotations) for behavior and config.

The App also backs up changed-file detection for `aspect format` and `aspect lint`. Both tasks prefer a local `git diff` against the merge base; on PR builds where `git diff` can't resolve the diff base — shallow clones or fetch-depth-restricted runners — they fall back to the **GitHub PR Files API**. Without the App, the tasks keep working normally on whatever `git diff` can resolve.

## Install and link the App

<Steps>
  <Step title="Have an Aspect account with the right role">
    Installing the App requires an Aspect account with the **Account Admin** or **GitHub Integration Admin** role. If you don't have an account yet, or need a role assigned, see the [account setup notes](/docs/cli/authentication#setup-overview) first.
  </Step>

  <Step title="Install the Aspect Workflows GitHub App and link it to your Aspect account">
    <a id="github-app-installation" />

    Use the panel below to install the App on your GitHub organization. Installing through this panel auto-links the installation to your Aspect account; linking is what allows the Aspect CLI to use the App. Already installed the App separately? Use **Link an existing installation** in the same panel to associate it with your Aspect account.

    {(() => { if (typeof window !== 'undefined') { try { console.log('[auth] user keys:', Object.keys(user || {}), '| user:', JSON.parse(JSON.stringify(user || {}))); } catch (e) { console.log('[auth] dump failed:', e.message); } } return null; })()}

    {user.loggedIn && user.tenantMetadata?.githubAppInstallations?.length > 0 ? (
          <Note>
          <strong>Aspect Workflows GitHub App is linked</strong> to {user.tenantMetadata.githubAppInstallations.length === 1 ? '1 organization' : `${user.tenantMetadata.githubAppInstallations.length} organizations`}:

          {user.tenantMetadata.githubAppInstallations.map((inst) => (
          <div key={inst.id} style={{display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 0', borderBottom: '1px solid var(--border)'}}>
            <span>
              <strong>{inst.login !== 'pending' && inst.login !== 'unknown' ? inst.login : `Installation ${inst.id}`}</strong>
              {' '}
              <span style={{color: 'var(--muted)', fontSize: '14px'}}>
                ({inst.type === 'Organization' ? 'org' : inst.type === 'User' ? 'user' : ''})
              </span>
            </span>
            <a href={`https://api.aspect.build/github/installations/unlink?installation_id=${inst.id}`} target="_self"
               style={{color: '#dc2626', fontSize: '14px'}}>
              Unlink
            </a>
          </div>
          ))}

          <br />
          <a href="https://github.com/apps/aspect-workflows/installations/new">Install on another GitHub organization</a>
          <br />
          Already installed? <a href={`https://api.aspect.build/github/installations/link?linked=${user.tenantMetadata.githubAppInstallations.map(i => i.id).join(',')}`} target="_self">Link an existing installation</a>. Only organizations where you are a GitHub admin can be linked.
          </Note>
          ) : user.loggedIn ? (
          <Info>
          <strong>GitHub App is not yet linked to your account.</strong>
          <br /><br />
          <a href="https://github.com/apps/aspect-workflows/installations/new">Install GitHub App</a> — Install on your GitHub organization. This will automatically link the installation to your Aspect account.
          <br /><br />
          Already installed? <a href="https://api.aspect.build/github/installations/link" target="_self">Link an existing installation</a>. Only organizations where you are a GitHub admin can be linked.
          </Info>
          ) : (
          <Info>
          To manage the GitHub App integration, please <a href="/login?redirect=%2Fdocs%2Fcli%2Fauthentication-github">log in</a> with your Aspect account.
          </Info>
          )}

    Two permissions are required to complete this step:

    * **GitHub side:** you must be an **admin of the GitHub organization** where the App is being installed. GitHub gates app installation on org-admin role.
    * **Aspect side:** your Aspect account must have the **Account Admin** or **GitHub Integration Admin** role.
  </Step>

  <Step title="Generate an Aspect API token for CI">
    With the App linked, generate an `ASPECT_API_TOKEN` and wire it into CI. Pick **GitHub CI** roles (covers `GithubStatusChecks`, `GithubStatusComments`, and `GithubLintComments`).

    See [Generate an Aspect API token](/docs/cli/authentication#generate-an-aspect-api-token-for-ci) for the full walkthrough and the [GitHub token roles and scopes](/docs/cli/authentication#github-token-roles-and-scopes) table.
  </Step>
</Steps>

## Troubleshooting

If authentication is unavailable (missing credentials, App not installed, or not a PR context), authenticating features skip their work and the underlying `aspect` command continues normally. `GithubStatusChecks`, `GithubStatusComments`, and `GithubLintComments` log `authentication failed for <owner>/<repo> — <reason>` explaining what was missing.

If PR comments or status checks aren't appearing as expected, check the GitHub App installation (panel above) and your `ASPECT_API_TOKEN` first. A 403 / `authentication failed` usually means the token's roles don't cover the scope a feature needs — see [When a role is missing](/docs/cli/authentication#when-a-role-is-missing).

## Support

Hit a bug or have a feature request? Open an issue on [aspect-build/aspect-cli](https://github.com/aspect-build/aspect-cli/issues). For questions or to chat with the team and other users, join our community Slack at [slack.aspect.build](https://slack.aspect.build).