README
¶
hack/ci
Go code that runs the PR workflow's tests. .github/workflows/pr-ci.yml only
connects GitHub Actions steps: checkout, caches, and artifacts. The manifest
and subcommands here decide which tests exist, where they run, and how.
Test tiers
suites.yaml is the only manifest.
| Tier | Contents | Runs | Defined by |
|---|---|---|---|
unit |
Go tests that need no running workspace | go run ./hack/ci unit or mise run cli:test |
unit.steps |
e2e, group unprivileged |
Ginkgo suites that run as the runner user | ci e2e run |
e2e.suites |
e2e, group integration |
Ginkgo suites that need a container runtime. Linux runs them with sudo unless a suite sets privileged: false. |
ci e2e run |
e2e.suites |
e2e, group microsandbox |
MicroSandbox suites | devsy-ci-microsandbox run |
e2e.suites |
ci unit runs every step that applies to the current OS. The Unit Tests job
runs it on each runner in unit.runners. The workflow builds one job matrix per
e2e group from e2e.suites.
Adding tests
- Go unit test in an ordinary package: no change. The
packagesstep finds every package outsidetest/ande2e/on Linux and macOS. - Go test under
test/ore2e/that must run as a unit test: add its package to aunit.stepsentry. List packages that stay out inunit.excludedwith a reason. - Go test that must run on Windows: discovery skips Windows. List its
packages in a
unit.stepsentry withos: [windows]. - Ginkgo spec: add its label to
e2e.suitesand choose agroup. Set only the fields that differ from the group defaults, such asrunner,test_timeout,install_kind,install_podman,requires_secret, andhost_setup. List labels that PR CI must not select directly ine2e.ungatedwith a reason. These include sub-labels exercised by gated suites and labels run manually or by another workflow.
go test ./hack/ci fails when a Ginkgo label or Go test package has no tier, or
when the manifest names a label that no longer exists. New tests need no
workflow edits.
Commands
| Command | Purpose |
|---|---|
ci matrix [--group G] [--secret-available] |
Print the job matrices as GitHub outputs. Drops suites that need the GitHub App secret when it is unavailable. |
ci unit [--os GOOS] [--step NAME] [--list] [--coverprofile P] |
Run the unit tier on this machine. |
ci e2e prepare --bin-src DIR --e2e-dir DIR |
Put the CLI binaries next to e2e.test. |
ci e2e run --label L --runner R |
Run a suite, with its focused checks, sudo and environment setup, and post checks. |
ci setup host --label L --runner R |
Run the suite's host_setup actions: remove-docker and insecure-registry. |
ci setup podman-linux ... |
Download, verify, and install the pinned static Podman build. |
ci success --always-run JOBS |
Fold the needs results into the required CI Success check. |
The Podman and MicroSandbox runtime helpers live in hack/podman_ci and
hack/microsandbox.
Documentation
¶
Overview ¶
Command ci is the Go implementation of the PR workflow's scripting.
The workflow (.github/workflows/pr-ci.yml) only wires GitHub Actions together. What tests exist, where they run and how they run lives in suites.yaml and in the subcommands here:
matrix emit the job matrices for the workflow unit run the unit-test tier on this machine e2e prepare and run Ginkgo suites setup host setup for suites (Docker, Podman) success fold the needed job results into the required status check
Source Files