Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

​
Why authenticate the CLI?

Some Aspect CLI features — GithubStatusChecks (per-task pass/fail status checks on the commit) and GithubLintComments (inline lint findings as PR review comments) — post results back to GitHub from your CI runs. They authenticate to the Aspect API, which then calls GitHub via the Aspect Workflows GitHub App installed on your GitHub organization that is linked to your Aspect account. aspect format and aspect lint also use that authenticated App on GitHub Actions PR builds to read the GitHub PR Files API, which gives a more accurate changed-file set than diffing against the merge base. Without authentication, both tasks fall back to a local git diff <merge-base> and continue to work normally — the App just upgrades the changed-file detection when it’s available. Plain commands that don’t touch any of the above — for example, aspect test //... locally, or aspect build //... against a remote cache — work without authentication, so you can skip this page if none of these apply to your usage. Setup, end to end:
  1. Install the Aspect Workflows GitHub App on your GitHub org and link it to your Aspect account (one-time per org).
  2. Generate an ASPECT_API_TOKEN — this is what the CLI uses to authenticate to the Aspect API on CI runners.

​
Setup

1

Create an Aspect account

Authentication is tied to an Aspect account — whenever the CLI authenticates (on CI via ASPECT_API_TOKEN, or locally via aspect auth login), it does so as your Aspect account.
Sign up for free at signup.aspect.build if you don’t have one. A free account works across all Aspect products and unlocks our free Bazel training courses.
The first user to sign up for an Aspect account is automatically granted the Account Admin role, which has the permissions needed for the next step. Subsequent users joining the same Aspect account need an existing admin to assign them either Account Admin or GitHub Integration Admin in the Aspect admin portal before they can install or link the GitHub App.
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 (see the previous step).
3

Generate an Aspect API token (for CI)

CI runners are non-interactive, so they authenticate with a long-lived token instead of a browser flow. Open the API Tokens portal and click Generate Token. In the dialog:
  • Description — any label that identifies where the token will be used (e.g. ASPECT_API_TOKEN, ci-main).
  • Roles — select one or more GitHub Integration roles. The role you pick gates which GitHub scopes tasks and features can use — see Token roles and GitHub scopes below for the mapping. For most CI use cases pick GitHub CI (covers GithubStatusChecks and GithubLintComments); pick GitHub Integration User if you want a single token with every scope.
  • This token will expire — pick a lifetime that matches your secret-rotation policy.
After clicking Create, the portal shows a Client ID and Secret Key.
The Secret Key is shown once and never again. Copy it immediately — if you lose it you’ll need to generate a new token.
The value of ASPECT_API_TOKEN is the two strings joined with a colon:
<CLIENT_ID>:<SECRET_KEY>
4

Provide the token to CI

Store ASPECT_API_TOKEN as a secret in your CI platform and expose it to the runner. How you wire it in depends on the platform:
jobs:
  aspect-task:
    runs-on: ubuntu-latest
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - run: aspect <task> //...

​
Token roles and GitHub scopes

ASPECT_API_TOKEN does not itself carry GitHub permissions. It authenticates to the Aspect API, and when a feature needs to call GitHub the Aspect API uses the linked App to make the call. Which GitHub scopes a feature can use is determined by the roles assigned to your ASPECT_API_TOKEN in the API Tokens portal, bounded by the GitHub App’s own permissions (so a feature can never receive more access than the App was granted at install time). Roles are bundles of fine-grained scope permissions. Pick the smallest bundle that covers what your CI actually does, or pick GitHub Integration User for everything.
RoleGitHub installation token scope(s)Typical use
GitHub CIchecks: write, statuses: write, pull_requests: write, actions: readRecommended default for CI runners. Covers status checks and PR comments.
GitHub Integration UserAll scopes belowFull access — equivalent to every GitHub Token: role combined.
GitHub Token: checkschecks: read, checks: writeGithubStatusChecks.
GitHub Token: statusesstatuses: read, statuses: writeCommit status APIs.
GitHub Token: pull requestspull_requests: read, pull_requests: writeGithubLintComments and other PR-comment features.
GitHub Token: issuesissues: readRead-only issue access.
GitHub Token: actionsactions: readRead-only GitHub Actions API access.
Write implies read — assigning a *.write role automatically authorizes the matching *.read scope, so you don’t need to add both. metadata: read is always included on every token.
If the requested feature needs a scope your token’s roles don’t cover, the Aspect API returns 403 and the feature skips gracefully — status checks and lint comments log authentication failed for <owner>/<repo> — <reason>. Add the missing role in the API Tokens portal and re-issue the token to enable the scope.

​
Local development

None of the built-in Aspect CLI tasks currently need authentication when run on a developer machine — aspect <task> works locally without any auth setup. Future CLI features that interact with Aspect API from your machine will, and when they ship you’ll authenticate by running: 
aspect auth login
This walks through a device OAuth flow in your browser and stores credentials so subsequent aspect invocations pick them up automatically. The flow needs an interactive browser session and does not work on CI runners; CI must always use ASPECT_API_TOKEN.

​
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 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 and ASPECT_API_TOKEN first.

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