Skip to main content
The Aspect Workflows GitHub App puts live build & test results on every pull request, for Bazel repos. Driven by the Aspect CLI, 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.
Using GitLab? See the GitLab App for the equivalent.

​
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 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.
1

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 first.
2

Install the Aspect Workflows GitHub App and link it to your Aspect account

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

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 for the full walkthrough and the GitHub token roles and scopes table.

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

​
Support

Hit a bug or have a feature request? Open an issue on aspect-build/aspect-cli. For questions or to chat with the team and other users, join our community Slack at slack.aspect.build.