GitLab CI/CD pipelines - Aspect Build

Your GitLab CI/CD pipeline runs on Aspect Workflows CI runners by targeting a runner group with tags:. 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 GitLab CI/CD is covered in .

Configure a pipeline

In your GitLab repository, click the Set up CI/CD link in the sidebar of your project.
On the Pipeline editor page, click the Configure pipeline button.
Replace the contents of the editor with the following. Each job runs your existing bazel commands unchanged.

Every job pulls in the aspect-build/setup-aspect-gitlab-component CI/CD component through the .ci template, which extends .setup-aspect. The setup step covers what it does and the inputs it takes.

.gitlab-ci.yml

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

stages:
  - CI

.ci:
  extends: .setup-aspect
  stage: CI
  tags: [aspect-workflows, aspect-default]
  rules:
    # Scheduled pipelines run only the warming job.
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - when: on_success

build:
  extends: .ci
  script:
    - bazel build //...

test:
  extends: .ci
  script:
    - bazel test //...

The workflow: rules run a merge request pipeline while a merge request is open and a branch pipeline otherwise, so a push creates one pipeline, not two. The job rules keep build and test off scheduled pipelines, which run the warming job instead.

Keep .setup-aspect in the extends chain of every job that calls bazel.

A job that defines its own before_script replaces the one .setup-aspect supplies, and the setup step doesn’t run. Pull it in with !reference ahead of your own commands:

.gitlab-ci.yml

build:
  extends: .ci
  before_script:
    - !reference [.setup-aspect, before_script]
    - ./tools/prepare.sh
  script:
    - bazel build //...

Self-hosted GitLab. The $CI_SERVER_FQDN in the include resolves to the GitLab instance running your pipeline, and GitLab only resolves components from that same instance, so a self-hosted pipeline can’t pull the component from gitlab.com directly. To use it on a self-hosted instance, mirror the component project into a group on your instance and mark the mirror as a CI/CD Catalog resource. The pipeline config above then works unchanged.

Non-Bazel jobs

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

.gitlab-ci.yml

custom-job:
  tags: [aspect-workflows, aspect-default]
  script:
    - npm install && npm test

Aspect CLI tasks (optional)

Swap a bazel command for the matching aspect <task> from the open-source Aspect CLI to add status checks, inline merge request comments with one-click suggested fixes, retries on transient Bazel errors and selective delivery. To use it, add your ASPECT_API_TOKEN as a CI/CD variable (Settings > CI/CD > Variables) that is masked, not protected: protected variables don’t reach merge request pipelines from unprotected branches, and merge request comments and status checks need those pipelines. Then call aspect <task> in each job:

.gitlab-ci.yml

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

stages:
  - CI

.ci:
  extends: .setup-aspect
  stage: CI
  tags: [aspect-workflows, aspect-default]
  rules:
    # Scheduled pipelines run only the warming job.
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - when: on_success

build:
  extends: .ci
  script:
    - aspect build --task:name build -- //...

test:
  extends: .ci
  script:
    - aspect test --task:name test -- //...

format:
  extends: .ci
  script:
    - aspect format --task:name format

lint:
  extends: .ci
  script:
    - aspect lint --task:name lint -- //...

delivery:
  extends: .ci
  needs: [test]
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - aspect delivery --task:name delivery --ci-host=gl --query='attr(tags, deliverable, //...)'

The delivery job runs only on the default branch; its rules replace the ones it would inherit from .ci. --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 GitLab CI pipeline.

​Configure a pipeline

​Non-Bazel jobs

​Aspect CLI tasks (optional)

Configure a pipeline

Non-Bazel jobs

Aspect CLI tasks (optional)