GitHub Actions pipelines

Your GitHub Actions pipeline runs on Aspect Workflows CI runners by targeting a runner group with runs-on:. Your existing bazel steps keep working unchanged: the setup step wires the runner’s remote cache, build event service and NVMe-backed output base into every invocation.

Registering the runners with GitHub Actions is covered in .

Configure GitHub Actions for Aspect Workflows

Create or update your workflow file (for example, .github/workflows/aspect-workflows.yaml). Point each job’s runs-on: at your Workflows runner labels and keep your existing bazel steps. Every job uses the aspect-build/setup-aspect action before its first bazel call. The setup step covers what it does and the inputs it takes.

.github/workflows/aspect-workflows.yaml

name: Aspect Workflows

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
      - name: Build
        run: bazel build //...

  test:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
      - name: Test
        run: bazel test //...

Pin to a full-length SHA per GitHub’s third-party action security guidance. Find the latest SHA and version on the setup-aspect releases page.

Non-Bazel jobs

Jobs that don’t call Bazel need no setup step. Target the runner group and run your commands:

.github/workflows/aspect-workflows.yaml

jobs:
  custom-job:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - run: npm install && npm test

Aspect CLI tasks (optional)

Swap a bazel step for the matching aspect <task> from the open-source Aspect CLI to add status checks, inline PR comments with one-click suggested fixes, retries on transient Bazel errors and selective delivery. To use it, pass your ASPECT_API_TOKEN to setup-aspect and call aspect <task>. The action exchanges the token for a short-lived JWT and persists only the JWT, so the long-lived token isn’t written to GITHUB_ENV or visible to other steps. id-token: write is for artifact uploads and PR summary comments. Status checks and PR comments post as the Aspect Workflows GitHub App, so the job token itself needs only read access:

.github/workflows/aspect-workflows.yaml

permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Build
        run: aspect build --task:name build -- //...

  test:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Test
        run: aspect test --task:name test -- //...

  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Format
        run: aspect format --task:name format

  lint:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Lint
        run: aspect lint --task:name lint -- //...

  delivery:
    needs: [test]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Delivery
        run: aspect delivery --task:name delivery --ci-host=gh --query='attr(tags, deliverable, //...)'

The delivery job runs only on pushes to main. --query selects the targets to deliver; without it or positional targets, aspect delivery delivers nothing. You can set the query once in .aspect/config.axl instead (ctx.tasks["delivery"].args.query). See aspect delivery. See Running tasks in CI for the full task reference.

See Aspect Bazel Examples for a complete working example of a GitHub Actions workflow.

`GITHUB_TOKEN` fallback (optional)

format, lint, and gazelle read a pull request’s changed files from git. When git can’t resolve them, the Aspect CLI asks GitHub’s pull request files API, using the Aspect Workflows GitHub App’s token. If the App isn’t installed on the repository, expose the job’s GITHUB_TOKEN with pull-requests: read so that call can use it instead:

jobs:
  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read
      id-token: write
      pull-requests: read
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

A task that resolves no changed files at all runs across the whole repository, as with --scope=all.

​Configure GitHub Actions for Aspect Workflows

​Non-Bazel jobs

​Aspect CLI tasks (optional)

​GITHUB_TOKEN fallback (optional)

Configure GitHub Actions for Aspect Workflows

Non-Bazel jobs

Aspect CLI tasks (optional)

`GITHUB_TOKEN` fallback (optional)