Authenticating the Aspect CLI

The Aspect CLI signs in as your Aspect account: with aspect auth login on your machine, and with an ASPECT_API_TOKEN on CI. The one credential covers both:

With it	What you get	Also needs
Aspect Cloud	Builds read and write the shared remote cache, and stream to the Build Results UI	Nothing else
Pull-request features	Per-task status checks, a live summary comment, and inline lint findings with suggested fixes, on GitHub pull requests and GitLab merge requests	The GitHub App or GitLab App, installed on your organization

An Aspect Enterprise deployment has its own sign-in, so it takes its own login and its own token. See its and .

Your Aspect account

Sign up for free. The same account works across all Aspect products. The first user to sign up is the Account Owner. Anyone who joins the account after that needs an owner or admin to give them a role in Aspect settings. Installing or linking an App takes one of these:

Role	Can install or link
Account Owner	Both Apps
Account Admin	Both Apps
GitHub Integration Admin	The GitHub App
GitLab Integration Admin	The GitLab App

The role names above are the portal’s. aspect github token --role takes the dotted spellings: checks.read, checks.write, statuses.read, statuses.write, prs.read, prs.write, issues.read, actions.read.

On your machine

aspect auth login

This opens a browser, signs you in, and stores the credential in your OS keyring, or in a 0600 file at ~/.aspect/credentials.json where no keyring is reachable. It renews itself in the background. Aspect Cloud local setup goes on from here: building with --remote, pointing vanilla bazel at the cache, and checking it worked.

aspect auth status shows who you’re signed in as.
aspect auth login --profile <name> keeps a second identity, such as a personal account, separate.
aspect auth logout removes the stored credential.
aspect auth login --with-token reads a JWT from stdin instead of opening a browser, and --with-api-token reads an API token the same way.
aspect auth login --no-browser prints the URL instead of opening one — the path for an SSH session or a container.
aspect auth login --org <org> picks the organization. Required non-interactively if your account belongs to more than one, since there is no prompt to answer.
aspect auth status --output=json is the machine-readable surface. Each entry carries its own login_command, so a script can tell you exactly what to run.
aspect auth logout --all clears every profile at once.
aspect auth configure and aspect auth use add and select an Aspect Workflows deployment; aspect auth remove forgets one.

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.

Create the token

Open API tokens in the Aspect app and select Create token. Give it a Token name that identifies where it will be used (e.g. ci-main), then select Create token.

Copy the token

The app shows the token once. It authenticates as you in your current organization.

The token is shown once and never again. Copy it immediately. If you lose it you’ll need to create a new one.

The whole string is the value of ASPECT_API_TOKEN.

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
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: aspect <task> //...

# ASPECT_API_TOKEN: a masked CI/CD variable in Settings → CI/CD → Variables.
include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

aspect-task:
  extends: .setup-aspect
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - aspect <task> //...

steps:
  - label: "Aspect task"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect <task> //...
    secrets:
      - ASPECT_API_TOKEN

# ASPECT_API_TOKEN: a project environment variable or context secret.
version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  aspect-task:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - setup-aspect/setup
      - run: aspect <task> //...

On GitHub Actions, prefer the with: aspect-api-token: input over env: ASPECT_API_TOKEN:. The aspect-build/setup-aspect action receives the long-lived token only within its own step’s process, pipes it via stdin to aspect auth login —with-api-token, and persists the resulting short-lived JWT on disk. Downstream steps see only the JWT: the long-lived token is never written to GITHUB_ENV, so any other action you call in the same job (including untrusted third-party ones that read process.env) can’t exfiltrate it.Setting the token as a job-level env: exposes the raw secret to every step in the job, which the input-based pattern avoids.On Buildkite, store the token as a Buildkite secret named ASPECT_API_TOKEN and expose it on each step with secrets: [ASPECT_API_TOKEN] (agent v3.106.0 or later). Use secrets: rather than env:, which Buildkite interpolates at upload and so writes the token into the job definition. The GitLab and CircleCI examples above use a CI/CD variable because no equivalent mechanism exists yet for those platforms.

Token roles and scopes

ASPECT_API_TOKEN doesn’t itself carry any VCS permissions. It authenticates to the Aspect API, and when a feature needs to call your VCS the Aspect API uses the linked App to make the call. Which scopes a feature can use is determined by the roles assigned to your token in the API Tokens portal, bounded by the 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 permissions. Pick the smallest bundle that covers what your CI actually does, or pick the Integration User role for everything.

GitHub token roles and scopes

Role	GitHub installation token scope(s)	Typical use
`GitHub CI`	`checks: write`, `statuses: write`, `pull_requests: write`, `actions: read`	Recommended default for CI runners. Covers status checks and PR comments.
`GitHub Integration User`	All scopes below	Full access, equivalent to every `GitHub Token:` role combined.
`GitHub Token: checks`	`checks: read`, `checks: write`	`GithubStatusChecks`.
`GitHub Token: statuses`	`statuses: read`, `statuses: write`	Commit status APIs.
`GitHub Token: pull requests`	`pull_requests: read`, `pull_requests: write`	`GithubStatusComments`, `GithubLintComments`, and other PR-comment features.
`GitHub Token: issues`	`issues: read`	Read-only issue access.
`GitHub Token: actions`	`actions: read`	Read-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.

GitLab token roles and scopes

Role	GitLab token scope	Typical use
`GitLab CI`	`api`	Recommended default for CI runners. Covers `GitlabCommitStatuses`, `GitlabStatusComments`, and `GitlabLintComments`.
`GitLab Integration User`	`api`, `read_api`	Full access, equivalent to every `GitLab Token:` role combined.
`GitLab Token: api`	`api`	Posting commit statuses, creating/updating MR notes, anything else under GitLab’s broad `api` scope.
`GitLab Token: external status checks`	`api`	Posting External Status Check responses on MRs (Premium/Ultimate tier only).
`GitLab Token: MR notes`	`api`	Creating and updating merge request notes.
`GitLab Token: MR read`	`read_api`	Read-only access to merge request metadata + changes.

Unlike the GitHub roles, GitLab token roles do not auto-imply each other. GitLab’s OAuth scope vocabulary is coarser than GitHub’s per-resource permission map, so role narrowing applies primarily as a permission gate; the minted token’s effective scope set is whatever the App was registered with for your role’s GitLab scope.

When a role is missing

If a feature needs a scope your token’s roles don’t cover, the Aspect API returns 403 and the feature logs an authentication failure. Add the missing role in the API Tokens portal and re-issue the token to enable the scope.

Troubleshooting

A pull-request feature that can’t authenticate logs <feature>: Authentication failed for <owner>/<repo> — <reason>, for example GitHub status checks: Authentication failed for …. The reason names what’s missing (no token, no App installed or linked) and links to this page. If PR comments, MR notes, or status checks aren’t appearing as expected, check the App installation and ASPECT_API_TOKEN first. See the GitHub App or GitLab App page for provider-specific symptoms.

Support

Hit a bug or have a feature request? Open an issue on aspect-build/aspect-cli. Join the Aspect Community Slack, Aspect’s free community support. Ask in #help for general support. Join the discussion and see what others are building with the Aspect CLI and Aspect Extension Language (AXL) in the #cli and #axl channels. For Bazel and the Bazel rulesets, Bazel Slack is the best place for support and discussion. Ask about Aspect’s rules_js in #javascript and rules_py in #python.

​Your Aspect account

​On your machine

​Generate an Aspect API token (for CI)

​Token roles and scopes

​GitHub token roles and scopes

​GitLab token roles and scopes

​When a role is missing

​Troubleshooting

​Support

Your Aspect account

On your machine

Generate an Aspect API token (for CI)

Token roles and scopes

GitHub token roles and scopes

GitLab token roles and scopes

When a role is missing

Troubleshooting

Support