> ## Documentation Index
> Fetch the complete documentation index at: https://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.

export const gatedAccess = (user, group) => {
  const loggedIn = !!(user && user.loggedIn);
  const groups = user && user.tenantMetadata && user.tenantMetadata.docsGroups || [];
  if (loggedIn && (!group || groups.indexOf(group) >= 0)) {
    return "entitled";
  }
  return loggedIn ? "signed-in" : "anonymous";
};

export const accountLabel = user => {
  if (!user || !user.loggedIn) {
    return "";
  }
  const pick = v => typeof v === "string" && v.trim() ? v.trim() : "";
  return pick(user.email) || pick(user.name) || pick(user.firstName) || "";
};

export const AccountAccess = ({access, label, href, action}) => {
  if (access === "anonymous") {
    return <div className="customer-access">
        <a className="customer-access-button" href={"/login?redirect=" + encodeURIComponent(href)}>Log in to {action}</a>
        <span>With your Aspect account, the same one you use at app.aspect.build.</span>
      </div>;
  }
  return <div className="account-access-row">
      <span>Signed in{label ? " as " : ""}{label ? <strong>{label}</strong> : null}</span>
      <span aria-hidden="true">·</span>
      <a className="aspect-logout" href="#log-out">Not the right account? Log out</a>
    </div>;
};

The **[Aspect Workflows GitHub App](https://github.com/apps/aspect-workflows)** puts live Bazel build and test results on pull requests. 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.

Mechanically, the App is what enables the Aspect API to 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, on pull request and push builds, updated live as tasks finish.
* **`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**.

## On a pull request

**A status check per task**, updated as the task progresses rather than only when the job ends.

**Lint findings on the line that caused them.** When [`aspect lint`](/docs/cli/tasks/lint) reports a warning or error, it lands as an annotation on the offending line:

<div className="browser-frame">
  <img src="https://mintcdn.com/aspectbuild/jTPviBFg4t0N8N72/images/github-bot-lint-check.png?fit=max&auto=format&n=jTPviBFg4t0N8N72&q=85&s=4b131ba39265c968daf794b73c03c666" alt="A lint error annotated on the line that caused it in a GitHub pull request" width="2140" height="332" data-path="images/github-bot-lint-check.png" />
</div>

Where the linter can suggest a fix, the annotation carries it as a suggestion the author applies with one click:

<div className="browser-frame">
  <img src="https://mintcdn.com/aspectbuild/jTPviBFg4t0N8N72/images/github-bot-lint-suggestion.png?fit=max&auto=format&n=jTPviBFg4t0N8N72&q=85&s=7978f6d31762eea4e79b35a1d4456b7b" alt="A suggested lint fix on a GitHub pull request, ready to apply" width="1019" height="546" data-path="images/github-bot-lint-suggestion.png" />
</div>

**A summary comment** on the pull request, with every task's status and links straight to its logs, test results, build profile and uploaded artifacts.

<Note>
  These come from <code>aspect \<task></code>. The CLI streams structured events as each task runs, and
  the App turns them into checks and comments. A vanilla <code>bazel</code> step produces none of them.
</Note>

## 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 Owner**, **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#your-aspect-account) 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 enables 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.

    <AccountAccess access={gatedAccess(user)} label={accountLabel(user)} href="/docs/cli/authentication-github" action="install the App" />

    {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 isn't 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>
          ) : null}

    You must also be an **admin of the GitHub organization** where the App is being installed; GitHub gates app installation on that 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>

## Post to a pull request from outside GitHub CI

When no CI variable names the pull request, such as a GitLab pipeline for a repository mirrored from GitHub, or a local run, set `ASPECT_GITHUB_PR_NUMBER`. The repository comes from `ASPECT_VCS_URL`, `GITHUB_REPOSITORY` or the `origin` remote, and the commit from `GITHUB_SHA` or the CI host's commit variable. To test against a real PR from your machine:

```shell theme={null}
export ASPECT_GITHUB_PR_NUMBER=123
export GITHUB_SHA=$(git rev-parse HEAD)
aspect build //... \
    --github-status-checks:mode=always \
    --github-status-comments:mode=always
```

It's the GitHub counterpart of `ASPECT_GITLAB_MR_IID` on the [GitLab App](/docs/cli/authentication-gitlab) page.

## Troubleshooting

A feature that can't authenticate logs one line naming what's missing (no credential, or the App not installed or linked), prefixed with the feature, for example `GitHub status checks: Authentication failed for <owner>/<repo> — <reason>` or `GitHub lint comments: Authentication failed for …`.

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).

**[Join the Aspect Community Slack](https://slack.aspect.build)**, Aspect's free community support. Ask in `#help` for general support. Join the discussion and see what others are building with the [Aspect CLI](/docs/cli/overview) and [Aspect Extension Language (AXL)](/docs/cli/axl) in the `#cli` and `#axl` channels.

For Bazel and the Bazel rulesets, [Bazel Slack](https://slack.bazel.build) is the best place for support and discussion. Ask about Aspect's [rules\_js](/docs/bazel/javascript) in `#javascript` and [rules\_py](/docs/bazel/python) in `#python`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.