Built-in features reference

A feature is behavior that applies across tasks rather than belonging to one: status checks, artifact upload, the remote cache connection. The built-in @aspect module registers the features on this page, and every one is enabled by default. Most act only where they apply, such as BuildkiteAnnotations on Buildkite, and the upload features upload nothing until you choose what. Run aspect feature to list the features active in your repository, and aspect feature <name> to print one feature’s flags.

Setting a feature’s options

Every option has a command-line flag, --<feature>:<option>, that applies to one invocation:

aspect test --artifact-upload:upload-test-logs=failed //...
aspect build --workflows:remote-exec //...

Set it for every invocation in .aspect/config.axl through ctx.features, using the option’s underscore name:

.aspect/config.axl

load("@aspect//feature/artifacts.axl", "ArtifactUpload")
load("@aspect//feature/workflows.axl", "Workflows")

def config(ctx: ConfigContext):
    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"
    ctx.features[Workflows].args.remote_exec = True

Turn a feature off with --<feature>:enabled=false, or ctx.features[<Feature>].enabled = False in config.axl. Each feature loads from @aspect//feature/<file>.axl:

Feature	Load from	Flag prefix
`ArtifactUpload`	`@aspect//feature/artifacts.axl`	`--artifact-upload:`
`BazelFlags`	`@aspect//feature/bazel_flags.axl`	`--bazel-flags:`
`BuildkiteAnnotations`	`@aspect//feature/buildkite_annotations.axl`	`--buildkite-annotations:`
`CircleCITestResults`	`@aspect//feature/circleci_test_results.axl`	`--circle-ci-test-results:`
`Deployment`	`@aspect//feature/deployment.axl`	`--deployment`, `--remote`
`GithubLintComments`	`@aspect//feature/github_lint_comments.axl`	`--github-lint-comments:`
`GithubStatusChecks`	`@aspect//feature/github_status_checks.axl`	`--github-status-checks:`
`GithubStatusComments`	`@aspect//feature/github_status_comments.axl`	`--github-status-comments:`
`GitlabCommitStatuses`	`@aspect//feature/gitlab_commit_statuses.axl`	`--gitlab-commit-statuses:`
`GitlabLintComments`	`@aspect//feature/gitlab_lint_comments.axl`	`--gitlab-lint-comments:`
`GitlabStatusComments`	`@aspect//feature/gitlab_status_comments.axl`	`--gitlab-status-comments:`
`Telemetry`	`@aspect//feature/telemetry.axl`	`--telemetry:`
`Tips`	`@aspect//feature/tips.axl`	`--tips:`
`Workflows`	`@aspect//feature/workflows.axl`	`--workflows:`

ArtifactUpload

Uploads build outputs to your CI provider’s artifact storage: GitHub Actions, Buildkite, CircleCI or GitLab. Everything is off by default, because artifacts are visible to anyone with access to the repository’s CI.

Option	Default	Values
`upload_test_logs`	`none`	`none`, `failed` (non-passing tests), `executed` (skips cached passes), `all`
`upload_build_logs`	`none`	`none`, `failed` (stdout and stderr of every failed build action)
`upload_profile`	`False`	Bazel’s JSON trace profile
`upload_bep`	`False`	The Build Event Protocol file, redacted at the source
`upload_exec_log`	`False`	The compact execution log. It holds action environment variables and command lines, so enable it only where artifact access is controlled

See Artifact upload for what each artifact is for.

BazelFlags

Removes flags that Aspect would otherwise add to a task’s Bazel call. It never touches flags you pass yourself.

Option	Default	What it does
`omit`	none	A flag to drop, named as Aspect spells it (`--bazel-flags:omit=--heap_dump_on_oom`). Any `=value` is ignored. Repeatable

Endpoints, credentials and the runner’s output paths can’t be omitted. The rc that aspect setup bazelrc writes has its own --omit-bazel-flag.

BuildkiteAnnotations

Posts each task’s live status as a Buildkite annotation.

Option	Default	What it does
`mode`	`ci-only`	When to annotate: `ci-only`, `local-only` or `always`
`min_update_interval_seconds`	`5`	Minimum seconds between live refreshes, at least 1. The final result and phase changes post immediately
`expand_phases`	none	Phase ids (such as `build` or `test`) whose log section starts expanded. CLI flag `--buildkite-annotations:expand-phase`, repeatable
`metadata_keys`	none	Extra BES `build_metadata` keys to show in the summary. `["*"]` shows all. CLI flag `--buildkite-annotations:metadata-key`
`template_preset`	`full`	The template bundle the annotation renders with
`templates`	`{}`	Jinja2 overrides for the `title`, `summary` and `details` slots, optionally per task kind. `config.axl` only

CircleCITestResults

Uploads Bazel’s JUnit results to CircleCI’s Tests tab. Acts only on CircleCI, and uploads nothing until you choose which results.

Option	Default	What it does
`upload_test_results`	`none`	`none`, `failed` (non-passing and flaky), `executed` (skips cached results) or `all`
`cached_as_skipped`	`False`	Report cached tests as skipped instead of passed. Applies only with `all`

Deployment

Connects a task to a deployment’s remote cache, build event service and remote execution. Its flags carry no prefix.

Flag	Default	What it does
`--remote`	`auto`	Which endpoints to connect. `auto` is the cache and BES on CI and nothing elsewhere. See the full `--remote` table
`--deployment <name>`	the default deployment	Which configured deployment to draw endpoints from. Needs `--remote` to say what to connect

On an Aspect Workflows runner the Workflows feature connects the runner’s own endpoints, and an explicit --remote is refused.

GithubLintComments

Posts aspect lint findings as GitHub pull request review comments, with fix suggestions where the linter provides them. Needs the Aspect Workflows GitHub App.

Option	Default	What it does
`max_pr_comments`	`25`	Most comments per run. Errors go first, then warnings, then notes. `0` posts none; the lint verdict is unchanged either way

GithubStatusChecks

Reports each task’s live status as a GitHub check run. Needs the Aspect Workflows GitHub App.

Option	Default	What it does
`mode`	`ci-only`	When to post: `ci-only`, `local-only` or `always`
`min_update_interval_seconds`	`20`	Minimum seconds between live refreshes on pull request builds. Push builds refresh every 60 seconds. The interval stretches as the GitHub API quota runs low
`only_annotate_changed_regions`	`True`	Limit lint annotations to the changed regions shown in Files changed
`metadata_keys`	none	Extra BES `build_metadata` keys to show in the summary. `["*"]` shows all. CLI flag `--github-status-checks:metadata-key`
`template_preset`	`full`	The template bundle the check run renders with
`templates`	`{}`	Jinja2 overrides for the `title`, `summary` and `details` slots, optionally per task kind. `config.axl` only

GithubStatusComments

Keeps one comment on the pull request with every task’s live status.

Option	Default	What it does
`mode`	`ci-only`	When to post: `ci-only`, `local-only` or `always`
`min_poll_interval_seconds`	`20`	Minimum seconds between comment refreshes. Final results post immediately
`template_preset`	`full`	The template bundle the comment renders with
`templates`	`{}`	A Jinja2 override for the comment `body`. `config.axl` only
`status_badges`	`{}`	Overrides for the status labels, such as `failed` or `passed`. `config.axl` only

GitlabCommitStatuses

Reports each task’s live status as a GitLab commit status on merge request pipelines. Needs the Aspect Workflows GitLab App.

Option	Default	What it does
`mode`	`ci-only`	When to post: `ci-only`, `local-only` or `always`
`min_update_interval_seconds`	`20`	Minimum seconds between live refreshes, at least 1
`metadata_keys`	none	Extra BES `build_metadata` keys passed to the rendered output. CLI flag `--gitlab-commit-statuses:metadata-key`
`template_preset`	`full`	The template bundle the status renders with
`templates`	`{}`	Jinja2 overrides. Only the rendered `title` reaches the commit status, truncated to 255 characters. `config.axl` only

GitlabLintComments

Posts aspect lint findings as discussions on the merge request diff. Needs the Aspect Workflows GitLab App.

Option	Default	What it does
`max_pr_comments`	`25`	Most discussions per run. Errors go first, then warnings, then notes. `0` posts none; the lint verdict is unchanged either way

GitlabStatusComments

Keeps one note on the merge request with every task’s live status.

Option	Default	What it does
`mode`	`ci-only`	When to post: `ci-only`, `local-only` or `always`
`min_poll_interval_seconds`	`20`	Minimum seconds between note refreshes. Final results post immediately
`template_preset`	`full`	The template bundle the note renders with
`templates`	`{}`	A Jinja2 override for the note `body`. `config.axl` only
`status_badges`	`{}`	Overrides for the status labels. `config.axl` only

Telemetry

Exports the CLI’s traces and metrics over OTLP.

Option	Default	What it does
`discover_endpoints`	`True`	Read endpoints from the standard `OTEL_EXPORTER_OTLP_*` environment variables
`endpoint`	none	An OTLP endpoint as `URL[;header=value;...]`, over gRPC with every signal. Repeatable

For per-signal routing or resource attributes, call ctx.telemetry.exporters.add() from config.axl.

Tips

Collects and shows short, non-fatal suggestions on each task. See Add and customize tips.

Option	Default	What it does
`silence`	none	Tip ids to suppress. Repeatable
`auto_print`	`True`	Print tips to the terminal. When off, tips still appear on check runs and PR comments

Workflows

Configures Bazel for an Aspect Workflows runner: the runner’s cache, build event service, output paths and health checks. Off a runner it connects the endpoints an ASPECT_WORKFLOWS_* environment names, if any. On a runner it injects, among others:

--remote_cache pointing at the runner’s local cache daemon, and the deployment’s build event service.
--repository_cache on the runner’s shared external-repository cache.
--output_base / --output_user_root on the runner’s NVMe storage, namespaced per repository so concurrent checkouts don’t collide. With runner warming configured, --output_user_root starts pre-warmed.
--disk_cache=, turning off any disk cache an rc sets, since the runner’s cache covers it.

aspect setup bazelrc writes the same flags to an rc, so vanilla bazel on the runner picks them up too.

Option	Default	What it does
`remote_exec`	`False`	Run actions on the runner’s remote executor. CLI flag `--workflows:remote-exec`. A vanilla `bazel` call opts in with `--config=aspect-exec` instead
`runner_output_base_suffix`	empty	Give this task its own Bazel server by suffixing the runner’s `--output_base`, so a task with incompatible flags doesn’t discard the shared analysis cache. `--output_user_root` stays shared. No effect off a runner
`bes_max_retries`	`4`	Reconnect attempts after a transient BES error. `0` turns retries off
`bes_retry_min_delay`	`1s`	Base delay for backoff between BES reconnects
`bes_retry_max_buffer_bytes`	`0`	Byte budget for unacknowledged BES events kept for replay. `0` uses `ASPECT_CLI_BES_RETRY_MAX_BUFFER_BYTES`, or 256 MiB when that’s unset
`bes_timeout`	`0s`	Overall BES upload deadline. `0s` means none

See Keep incompatible tasks off each other’s analysis cache for when to set runner_output_base_suffix.

Opting in to remote execution

Which flag turns on remote execution depends on where the call runs:

Where	Flag
An `aspect` task on an Aspect Workflows runner	`--workflows:remote-exec` (`--remote` is refused there)
An `aspect` task anywhere else	`--remote=exec`, with `--deployment <name>` to pick the deployment
Vanilla `bazel` on a runner	`--config=aspect-exec`
Vanilla `bazel` with an rc from `aspect setup bazelrc`	`--config=aspect-<name>-exec`

​Setting a feature’s options

​ArtifactUpload

​BazelFlags

​BuildkiteAnnotations

​CircleCITestResults

​Deployment

​GithubLintComments

​GithubStatusChecks

​GithubStatusComments

​GitlabCommitStatuses

​GitlabLintComments

​GitlabStatusComments

​Telemetry

​Tips

​Workflows

​Opting in to remote execution