GitLab App - Aspect Build

The Aspect Workflows GitLab App is what enables the Aspect API to call GitLab on your behalf. Link it once for your GitLab top-level group, and authenticated CLI features (GitlabCommitStatuses, GitlabStatusComments, and GitlabLintComments) start posting results to your merge requests. This page covers linking the App. For the account setup and the ASPECT_API_TOKEN your CI uses, see Authenticating the Aspect CLI.

Using GitHub? See the GitHub App for the equivalent.

What the App enables

Once linked, these CLI features can post to GitLab from your CI runs:

GitlabCommitStatuses: per-task pass/fail status on the commit under review (the rows GitLab shows in the MR’s “Pipelines” / commit status column).
GitlabStatusComments: a single rolling MR note that aggregates every task’s live status into one comment, updated as jobs complete.
GitlabLintComments: inline aspect lint findings posted as position-bound discussions on the MR diff, with one-click suggestion blocks. See aspect lint for behavior and config.

Task status to GitLab state

Aspect task status	GitLab commit status
before any update	`pending`
running	`running`
failing (early-fail, live)	`failed`
passed (final)	`success`
warning (final)	`skipped` — GitLab’s mapping for “ran with non-fatal findings”; renders without a red ✗
failed (final)	`failed`
aborted (final)	`canceled`

aborted is what a Ctrl-C or a cancelled CI job produces. It maps to canceled rather than failed, so automation that matches on failed will miss it.

On a merge request

A commit status per task, updated as the task progresses rather than only when the job ends.
Lint findings on the line that caused them. When aspect lint reports a warning or error, it lands as a discussion on the offending line of the diff, with the fix as a one-click suggestion where the linter has one.
A rolling summary note on the merge request, with every task’s status and links straight to its logs, test results, build profile and uploaded artifacts.

These come from aspect <task>. The CLI streams structured events as each task runs, and the App turns them into statuses and notes. A vanilla bazel step produces none of them.

Link the App

Have an Aspect account with the right role

Linking the App requires an Aspect account with the Account Owner, Account Admin or GitLab Integration Admin role. If you don’t have an account yet, or need a role assigned, see the account setup notes first.

Link the Aspect Workflows GitLab App to your GitLab top-level group

The Aspect Workflows GitLab App is an OAuth Application Aspect has already registered on gitlab.com. You don’t create or register anything on the GitLab side. The link flow walks you through the standard GitLab OAuth consent screen to authorize the existing Aspect App against the top-level group you own; that consent is what enables the Aspect CLI to call the GitLab API on your behalf.Use the panel below to start the consent flow:You must also be an Owner of the top-level GitLab group you want the App to act on; GitLab gates api-scoped OAuth authorization on that role. Beyond selecting Authorize on the consent screen, nothing is required on the GitLab side.Each Aspect account can link several GitLab users, for example one per top-level group; the Aspect API uses the one that owns the project’s top-level group.

Generate an Aspect API token for CI

With the App linked, generate an ASPECT_API_TOKEN and wire it into CI. Pick GitLab CI roles (covers GitlabCommitStatuses, GitlabStatusComments, and GitlabLintComments).See Generate an Aspect API token for the full walkthrough and the GitLab token roles and scopes table. The GitLab tab of that page’s .gitlab-ci.yml example shows the rules: clause both status features need: they gate on a merge-request pipeline.

When the features fire

These features ship enabled by default in the Aspect CLI. They only post to GitLab when:

A merge-request pipeline is running (CI_MERGE_REQUEST_IID present), and
ASPECT_API_TOKEN is set with appropriate roles, and
An Aspect Workflows GitLab App install exists that covers your project’s top-level group.

For an MR pipeline to be created at all, your project must have Settings → Merge requests → Pipelines for merge requests enabled, and your job’s rules: must accept merge_request_event (see the GitLab tab of the .gitlab-ci.yml example). GitlabLintComments additionally only fires on the aspect lint task when lint findings are routed to inline comments. See aspect lint › GitLab MR comments for its behavior, the suggestion/dedup/auto-resolve semantics, and the --gitlab-lint-comments:max-pr-comments cap.

Storing ASPECT_API_TOKEN as a group-level CI/CD variable (rather than per-project) lets every project under the group pick it up.

Configuring the features

Common knobs (set in .aspect/config.axl):

.aspect/config.axl

load("@aspect//feature/gitlab_commit_statuses.axl", "GitlabCommitStatuses")
load("@aspect//feature/gitlab_status_comments.axl", "GitlabStatusComments")
load("@aspect//feature/gitlab_lint_comments.axl", "GitlabLintComments")

def config(ctx: ConfigContext):
    # Slow the commit-status refresh cadence (default 20s) — useful on
    # busy projects where GitLab API rate limit is tight.
    ctx.features[GitlabCommitStatuses].args.min_update_interval_seconds = 60

    # Same for the rolling MR note (default 20s).
    ctx.features[GitlabStatusComments].args.min_poll_interval_seconds = 30

    # Cap inline lint discussions per run (default 25; 0 disables posting).
    ctx.features[GitlabLintComments].args.max_pr_comments = 50

    # Disable a feature entirely:
    # ctx.features[GitlabCommitStatuses].enabled = False

Command-line overrides:

# mode: ci-only (default) | local-only | always
aspect build //... \
    --gitlab-commit-statuses:mode=always \
    --gitlab-status-comments:mode=always

# GitlabLintComments has no mode flag; it gates on the lint task and findings routing.
aspect lint //... \
    --gitlab-lint-comments:max-pr-comments=50

`mode=always` for local testing

To iterate against a real MR without a GitLab CI pipeline, set the override env vars in your shell, then run with mode=always:

export ASPECT_GITLAB_MR_IID=123
export ASPECT_GITLAB_PROJECT_PATH=mygroup/myproject
export ASPECT_GITLAB_SHA=$(git rev-parse HEAD)
aspect build //... \
    --gitlab-commit-statuses:mode=always \
    --gitlab-status-comments:mode=always

These env vars are the same escape hatch used by when posting status back to GitLab from runners that don’t run inside GitLab CI directly.

Self-hosted GitLab

Only gitlab.com is supported today. Self-hosted GitLab instances (gitlab.example.com, GitLab Dedicated, etc.) can’t use the features on this page yet: the Aspect Workflows GitLab App is registered against gitlab.com. If self-hosted support would unblock you, please reach out so we can prioritize it.

Troubleshooting

Each feature logs a line saying why it didn’t post. The first row below is a trace line, so set ASPECT_DEBUG=1 on the job to see it; the rest print unconditionally. The common ones:

Symptom	Likely cause
`GitLab status comments: No GitLab MR context — skipping. (<reason>)` — needs `ASPECT_DEBUG=1`, it is a trace line	Pipeline isn’t an MR pipeline. Confirm `CI_MERGE_REQUEST_IID` is set and that the job’s `rules:` accept `merge_request_event`.
`GitLab commit statuses: Authentication failed for <group>/<project> — credentials expired`	`ASPECT_API_TOKEN` expired or wasn’t injected into the job. Re-issue from the portal and update the CI/CD variable.
`Authentication failed ... access denied: No GitLab App installation linked for "<group>"`	No linked install whose `ownedGroups` covers the project’s top-level group. Re-run the link flow from the panel above as an Owner of that group.
`Authentication failed ... access denied: requires "aspect.gitlab.token.api" permission`	Your `ASPECT_API_TOKEN` was issued without the role the feature needs. Re-issue with GitLab CI (or GitLab Integration User) — see When a role is missing.
Commit status row stuck on `pending` long after the task finished	The terminal-state POST hit a transient API failure. Re-running the job posts the terminal state on next run; no manual recovery needed.

If MR notes or commit statuses aren’t appearing as expected, check the GitLab App installation (above panel) and ASPECT_API_TOKEN first.

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.

​What the App enables

​Task status to GitLab state

​On a merge request

​Link the App

​When the features fire

​Configuring the features

​mode=always for local testing

​Self-hosted GitLab

​Troubleshooting

​Support

What the App enables

Task status to GitLab state

On a merge request

Link the App

When the features fire

Configuring the features

`mode=always` for local testing

Self-hosted GitLab

Troubleshooting

Support