This page helps you run rules_dx checks, docs, updates and releases in GitHub Actions.
You call reusable workflows that rules_dx ships. A reusable workflow is a
workflow file in another repository that your own workflow runs with uses:.
You pin it to a rules_dx commit.
-
Add rules_dx to your module. A module is your Bazel project, and
MODULE.bazelat the repository root lists what it depends on. Add this line, as in Adopting rules_dx in an existing Bazel repo:bazel_dep(name = "rules_dx", version = "...")
-
Write the workflow files:
bazel run @rules_dx//:dx -- init --apply
With
dxinstalled,dx init --applydoes the same. Init writes:.github/workflows/ci.yml. When it already exists, init only updates the rules_dx commit inuses:..github/workflows/dx-update.yml, when missing..github/workflows/release.yml, when missing and a BUILD file callsdeploymentor a*_deploymacro from@rules_dx//deploy:defs.bzl.
See
dx init. -
Push the branch and open a pull request.
-
In branch protection, require the check
dx-ci (aggregate). Do not require the per-platform jobs. -
Set the repository settings under Repository settings.
A ci.yml that checks Linux x86_64 and dry-runs the release deployments looks like this:
name: ci
on:
pull_request: {}
merge_group:
types: [checks_requested]
push:
branches: [main]
workflow_dispatch: {}
jobs:
dx:
uses: devhusdk/rules_dx/.github/workflows/reusable-consumer.yml@<commit>
with:
platforms: '["linux_x86_64"]'
deploy_dry_run: true
secrets:
BUILDBUDDY_API_KEY: ${{ secrets.BUILDBUDDY_API_KEY }}
REMOTE_CACHE_HEADER: ${{ secrets.REMOTE_CACHE_HEADER }}
permissions:
actions: read
contents: write
pull-requests: writeThe ci.yml that init writes uses your default branch under push, pins <commit>, and sets remote_cache: ${{ vars.DX_REMOTE_CACHE }} in place of platforms. Add or change inputs under with:. The inputs are listed under Inputs.
When you open a pull request, you get one checks (<platform>) job per platform, a security-audit job per platform, and dx-ci (aggregate) with the overall result.
A target is one thing Bazel can build or test, such as a library or a test. A label names a target, like //pkg:lib. The pattern //... means every target in the repository.
Most jobs first run dx completion bash. It writes the gitignored .dx/bazelrc files, so the next Bazel command reads the rules_dx Bazel settings.
Per platform, checks (<platform>) runs these in order. A failing check does not stop the next one.
| Check | Command | Reports |
|---|---|---|
lint |
dx lint |
lint.sarif |
typecheck |
dx typecheck |
typecheck.sarif |
format |
dx format |
none |
generate |
dx generate //... |
none |
license-audit |
dx license //... |
none |
test |
dx test --timings |
junit.xml, failures.json, results.json |
build |
dx build --timings |
failures.json |
coverage |
dx coverage |
failures.json, results.json |
The other jobs:
| Job | What it does |
|---|---|
validate (inputs) |
Checks the inputs. Runs first. |
advisory snapshots (one run, every platform) |
Prepares the advisory snapshots once for all platforms. |
security-audit |
Runs dx security //... in its own job per platform. |
advisory pin bump |
Runs when advisory_pr is true. Opens the advisory pin pull request. |
fuzz, bench, deploy dry run |
Run when their inputs are set. |
dx-ci (aggregate) |
Reports the result of validate, checks, security-audit and the advisory snapshots. |
Every check runs on every call. A skipped required job fails dx-ci. To turn a tool off, set it under [families.<id>] in dx.toml (see Choose tools and tier). CI and local runs then agree.
On pull requests, lint, typecheck, format, test, build and coverage run with --affected, which picks only the targets your change reaches. Other events use //....
coverageuses//...whenmin_coverageormin_changed_line_coverageis set.- Set
affected_on_pr: falseto use//...on pull requests. - When the checkout is not a merge commit, scoped checks warn and run
//.... - When nothing is affected, the check passes and uploads no reports.
-
Open the run summary. Each check has a line like
<check>: passed (exit 0), ran: tools/dx <check> ... <scope>or<check>: failed (exit N), ran: .... A scoped check with nothing affected adds(nothing affected). A failedlintortypecheckalso adds up to 10 annotations on the affected lines and a table of the first 50 findings. -
Open the failed job log.
-
Download the reports with the GitHub CLI:
gh run download <run-id> -n dx-reports-test-linux_x86_64 gh run download <run-id> -p 'dx-reports-*'
Report artifacts:
- Names:
dx-reports-lint-<platform>,dx-reports-typecheck-<platform>,dx-reports-test-<platform>,dx-reports-build-<platform>anddx-reports-coverage-<platform>. Withinvocation_idset, the name ends in-<invocation_id>. - They are kept 3 days.
- They carry test output and log tails. Treat them like logs.
- The test and build artifacts also carry
profile-<check>.json, the--timingsreport.
On a pull request from the same repository, each platform posts a summary comment. It shows coverage, cache hit rate, wall time and critical path. Pull requests from forks get the job summary only.
Common failures:
| Message | Fix |
|---|---|
| Rejected input | Use a value listed under Inputs. |
Config value 'ci' is not defined in any .rc file |
Add the .bazelrc lines under Caches. |
advisory_refresh_failed |
Rerun the workflow, or run bazel run @rules_dx//dx/advisory_prep --. See Advisory Snapshots. |
Stale MODULE.bazel.lock |
Run bazel mod deps and commit the lock file. |
| Skipped, cancelled or missing check | Rerun the pull request run. |
A remote cache stores build and test results on a server, so later runs reuse them instead of redoing the work. A remote cache is recommended.
The workflows write a credential helper that reads the key from the environment and hands it to Bazel. You only pass the secret. Do not put the key in --remote_header or in any rc file.
-
For BuildBuddy, set the
BUILDBUDDY_API_KEYsecret:secrets: BUILDBUDDY_API_KEY: ${{ secrets.BUILDBUDDY_API_KEY }}
-
For another REAPI cache, set
remote_cache. If the cache needs a header, add theREMOTE_CACHE_HEADERsecret asname=value. When it is set,BUILDBUDDY_API_KEYis not used.with: remote_cache: grpcs://cache.example.com secrets: REMOTE_CACHE_HEADER: ${{ secrets.REMOTE_CACHE_HEADER }}
The
ci.ymlthat init writes readsremote_cachefrom the Actions variableDX_REMOTE_CACHE. -
Add the cache URL to the
ciconfig in.bazelrc..bazelrcis the file of default Bazel flags at the repository root. A line that starts withcommon:ciapplies only when Bazel runs with--config=ci, which the workflow passes when a cache is set.common:ci --remote_cache=grpcs://remote.buildbuddy.io common:ci --experimental_remote_downloader=grpcs://remote.buildbuddy.io common:ci --experimental_remote_downloader_local_fallback
tools/dx init --apply writes the rest of the ci and ci-pr configs to .dx/bazelrc:
- compression, timeouts, retries and local fallback
- all CPUs,
--jobs=64,--loading_phase_threads=32and--remote_max_connections=200 --nobuild_runfile_links- an up-to-date
MODULE.bazel.lock - no uploads from pull requests
Runfiles are the files a program needs when it runs. Under --config=ci, <bin>.runfiles trees are not built. A script that builds and then runs bazel-bin/... and needs its runfiles breaks.
Without a remote cache, no config is passed. The .dx/bazelrc preset sets startup --experimental_remote_repo_contents_cache. It stores fetched repositories in the remote cache when one is set and does nothing otherwise. It applies to local runs too. With 32 loading threads, the lookups run in parallel.
For more, see Remote cache.
The workflow keeps these GitHub Actions caches:
| Cache | When |
|---|---|
Disk cache per checks job, keyed on the check and platform |
Only without a remote cache. Saved on the default branch; other runs restore it. |
Advisory snapshots under .dx/local/advisory |
When .dx/pins pins them. |
Fuzz corpus under .dx/local/fuzz |
When fuzz is true. |
Bazel downloads and Bazelisk are fetched fresh in each job.
These are the with: inputs of reusable-consumer.yml.
| Input | Meaning |
|---|---|
platforms |
JSON array. Default ["linux_x86_64"]. Values: linux_x86_64, linux_arm64, macos_arm64, windows_x86_64, windows_arm64. [] fails validation. |
min_coverage |
Whole number 0 to 100. Fails below it. Empty sets no threshold. |
min_changed_line_coverage |
Whole number 0 to 100. Pull requests only. Fails when fewer of the added executable lines are covered. Empty skips it. |
affected_on_pr |
Default true. Use --affected on pull requests. |
buf_breaking_on_pr |
Default false. On pull requests, run lint with --breaking-against so buf breaking compares the proto files with the pull request base. |
link_check_online |
Default false. Run lint with --online so lychee checks external links. Ignored on pull requests; call the workflow from a schedule trigger to use it. |
fuzz |
Default false. Run dx fuzz on dx-fuzz targets on Linux x86_64. The corpus under .dx/local/fuzz is cached between runs. A crash fails the job and uploads the dx-fuzz-crashes artifact for 30 days; the log shows the reproduce line. |
fuzz_time |
Default 300s. Time budget per fuzz target, such as 90s, 5m or 1h. |
bench |
Default false. Run dx bench on Linux x86_64. Pushes to the default branch upload .dx/local/bench/last.json as the dx-bench-linux_x86_64 artifact for 90 days. Pull requests run dx bench --compare <base branch> --max-regression=<bench_max_regression> and add the table to the job summary. |
bench_max_regression |
Default 20. Whole number 0 to 100. Percent a benchmark may be slower than the base branch before a pull request fails. |
deploy_dry_run |
Default false. Run dx deploy, the dry run, on every deployment tagged release on Linux x86_64. The job runs dx deploy --affected. Pull requests with affected_on_pr dry-run only the deployments the change reaches. A Starlark or module change, or a deleted file, checks every release deployment. |
remote_cache |
REAPI cache URL. dx init --apply sets it to the DX_REMOTE_CACHE Actions variable. |
advisory_pr |
Default false. Run dx update advisory --pr, which opens or refreshes the dx-update/advisory pull request that moves the advisory pins in .dx/pins to the newest snapshot release. Call the workflow from a schedule trigger with contents: write and pull-requests: write permissions. |
invocation_id |
1 to 40 letters, digits, underscores or hyphens. Set a different one per call when a run has several calls. |
| Secret | Meaning |
|---|---|
BUILDBUDDY_API_KEY |
BuildBuddy API key. Optional. |
REMOTE_CACHE_HEADER |
Header for remote_cache as name=value. Optional. |
Changed-line coverage runs dx coverage --min-changed-line-coverage <percent>. See Build, test, and coverage for output lines and error codes.
To check and publish an mdBook docs site:
- Copy the YAML below to
.github/workflows/docs.yml. - Set
siteto the label of the target that renders your site. - Before the first publish, set the Pages source to GitHub Actions in the repository settings.
- In branch protection, require
docs-check. Adddocs-publish (GitHub Pages)whenpublishis true.
name: docs
on:
pull_request: {}
merge_group:
types: [checks_requested]
push:
# Change to your default branch if it is not main.
branches: [main]
workflow_dispatch: {}
jobs:
docs:
uses: devhusdk/rules_dx/.github/workflows/reusable-docs.yml@d971da0e0d70907d291b84c44e3306efda22efe3
with:
docs_scope: "//..."
site: "//docs:site"
publish: ${{ github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
secrets:
BUILDBUDDY_API_KEY: ${{ secrets.BUILDBUDDY_API_KEY }}
permissions:
contents: read
pages: write
id-token: writedocs-publish (GitHub Pages) does not run on pull requests.
| Input | Meaning |
|---|---|
docs_scope |
Space-separated target patterns for dx lint. Default //.... |
site |
Required. Target label whose output is the rendered mdBook tree. |
site_check |
Target label for dx docs. Default empty, which skips it. |
publish |
Deploy to Pages. Default false. Needs pages: write and id-token: write. |
environment |
Pages environment. Default github-pages. |
forbid |
Text the site must not contain, one per line. |
landing |
Require a landing page. Default false. |
smoke_test |
Test label run with DX_PAGES_URL set, after the deploy. |
dx-update.yml runs tools/dx update --pr every Monday at 04:00 UTC and on workflow_dispatch. To change it, edit cron and the flags in the file.
- Allow auto-merge in the repository settings.
- Allow GitHub Actions to create and approve pull requests (Settings, Actions, General, Workflow permissions).
- For CI on update pull requests and for Actions pins, create a GitHub App with read and write on Contents, Pull requests and Workflows.
- Set the secrets
DX_UPDATE_APP_IDandDX_UPDATE_APP_PRIVATE_KEY.
Without the App secrets, the job warns and CI does not run on the update pull requests.
release.yml calls reusable-release.yml when you push a v* tag.
-
Tag each
deploymenttarget to publish withtags = ["release"]. The tag must be exactlyrelease;prereleaseandrelease-notesdo not match. -
Store registry tokens, such as
NPM_API_TOKEN, as repository secrets. The caller passessecrets: inherit. -
Push a tag:
git tag v1.0.0 git push origin v1.0.0
What runs:
planlists the deployables.dry run (<platform>)runsdx deploy <label>for each one on every platform inplatforms, so the dry run is in the log.releaserunsdx deploy --apply <label>for each, in the order of the list, with only the*_APPROVEDvariables set. A failed deployable stops the rest. The job summary lists the ones already published and agh workflow run release.ymlcommand that resumes with the rest.
A github_deploy creates a draft release.
publish gates the release job, which also needs a tag ref. With publish: false, the plan and dry run run on any ref and nothing is published. The release.yml that dx init writes has a workflow_dispatch with publish defaulting to false, so dispatching it from a branch only plans and dry-runs. Pass true on a tag to publish. Tag pushes always publish.
An existing release.yml keeps its triggers. Add the workflow_dispatch publish input by hand, and this line under with::
publish: ${{ github.event_name != 'workflow_dispatch' || inputs.publish }}The caller grants contents, id-token, attestations and packages write.
| Input | Meaning |
|---|---|
deployables |
JSON array of labels, for example ["//pkg:npm", "//pkg:github"]. Empty publishes every deployment tagged release. |
platforms |
JSON array of platforms for the dry run. Default ["linux_x86_64"]. |
publish |
Default true. Publish after the dry run. |
runner |
Runner label for the release job. Default ubuntu-latest. |
- Approval policy for fork pull request workflows:
all_external_contributors. - Merge gate: require up-to-date branches, or use a merge queue.
- Workflow permissions: read-only default.