Test a change
Run the local check for each kind of change before you open a pull request, with the CI workflow that runs the same check.
Use this runbook before you open a pull request. It gives the local command for each kind of change and the CI workflow that runs the same check.
note
Each CI workflow starts only for the paths in its filter. A path that no filter lists runs no check, and the pull request still shows green.
Before you start#
- Run
mise installandbun installfrom the repository root. - For a Nix change, run
mise run devshell. mise tasks lslists every task. If a task exists for a check, use the task.
Test the change#
| You changed | Command | CI workflow |
|---|---|---|
docs/, a .md file, or .agents/ | mise run docs:check | wiki.yml |
apps/wiki/ | bun run --cwd apps/wiki test, then mise run docs:build | wiki.yml |
nix/, flake.nix, flake.lock, or a topology JSON file | mise run nix:check | nix-ci.yaml, which builds only after the merge to main |
clusters/ or packages/charts/ | mise run k8s:render-apps, then mise run k8s:check-rules | kustomize.yml |
One directory under clusters/<site>/ with a kustomization.yaml | kubectl kustomize clusters/<site>/<dir> | None |
clusters/<site>/config/cluster-topology.json | conftest verify -p .github/policy, then the conftest test command in topology-contract.yml | topology-contract.yml |
A .tf or .terraform.lock.hcl file | The local checks in Apply an OpenTofu change | terraform.yml |
A .tftest.hcl file | mise run tf:init, then tofu -chdir=<root> test | terraform.yml |
TypeScript in apps/ or packages/ | mise run ts:check, then bun run test | typescript.yml, if its changed-files list names the path |
A Go module in apps/ | go -C apps/<app> vet ./..., then go -C apps/<app> test ./... | go.yml, rackstat.yml or view-counter.yml, if one of them lists the module |
apps/fml-pki/ or terraform/pki/certs/ | mise run pki:verify | go.yml |
apps/fml-derive-rs/ or apps/fml-ceremony/ | mise run rust:test, then mise run pki:crosscheck | rust.yml |
A shell script in scripts/ or .github/scripts/ | mise run check | shell.yml |
.github/scripts/validation-impact.sh | mise run validation-impact:test | terraform.yml |
.github/scripts/cd-*.sh, .github/scripts/detect-containers.sh, .github/scripts/image-affected.sh, .github/containers.json or .github/workflows/containers.yml | mise run cd-digest:test | containers.yml |
List the files that the branch changes.
git diff --name-only main...HEADResult: One changed file on each line.
Find the Nix check and the OpenTofu directories that CI checks for these files.
git diff --name-only main...HEAD | .github/scripts/validation-impact.sh targetsResult:
nix:flake-check, oneterraform:<dir>line for each root or module that the change affects, or no output.For each row of the table that matches a changed file, run its command from the repository root.
Result: Each command completes without an error.
docs:checkprintsokafter each check.If you changed
docs/, search the pages for secret values.grep -rn -i -E -e 'BEGIN [A-Z ]*PRIVATE KEY' -e '(password|secret|token) *[:=] *[^ <$]' docsResult: Each line that can hold a secret.
Make sure that no line from step 4 holds a secret value.
If something goes wrong#
| Symptom | Cause | Action |
|---|---|---|
docs:check prints MISSING and a path. | A page names a repository path that does not exist. | Correct the path in the page. |
docs:check prints BROKEN, a file and a wiki reference. | The file points at a page path that the wiki does not serve. The wiki has no redirects. | Point the reference at the current path of the page. |
docs:check prints past tense in docs. | A page describes history. | Describe the current state. |
bun run test cannot connect to Postgres. | The kthx tests in apps/kthx-engine/ need a database. | Set DATABASE_URL, as apps/kthx-engine/README.md describes. |
mise tasks ls exits with an error. | mise does not trust the configuration of the checkout. | Run mise trust. |
Related#
- Apply an OpenTofu change: the OpenTofu checks and the Atlantis apply.
- Apply a Kubernetes change: the Flux path.
- Deploy a NixOS host: deploy a host after the checks pass.
- Build and release: CI routing and the workflows.
Linked from 6
- HomeThe owner's homelab at two sites, folly and offsite, managed as code: its apps, platform, hosts and runbooks.
- Build and releaseHow first-party code builds, how its images and charts publish and deploy, how Renovate updates dependencies, and which CI checks run on a pull request.
- NixOSThe flake that builds each Linux host and OS image, the fleet baseline each host shares, and the daily upgrade from main.
- Apply an OpenTofu changeChange an OpenTofu root, check it on your machine, and apply it through Atlantis on the pull request.
- Deploy a NixOS hostDeploy the NixOS configuration of a host from your machine or from GitHub Actions, or restore the previous generation.
- RunbooksStep-by-step procedures for the hosts, clusters, network, secrets and apps, grouped by area.