Skip to content

Examples

Every script here is evaluated by the tests (internal/plan/examples_test.go), which also check that each does what its comments say. Try one against any checkout:

starci plan --file examples/basic/monorepo.ci.star --changed packages/api/src/main.ts
starci run ~/src/some-repo --local --file examples/basic/hello.ci.star

Most refer to scripts and files a real repository would have (npm test, ./scripts/deploy.sh), so they plan anywhere but only run where those exist. The three pi-gamebook ones run as they are against that repository.

Basic: ci(ctx) returns the steps
hello The smallest script.
diamond Steps that depend on each other.
docs-only Do nothing for a documentation commit.
events One script for pushes, tags, pull requests, a nightly schedule and manual runs.
branches Publish from main only; cache = False for steps with effects.
matrix A matrix is a loop, with exclusions as an if.
monorepo Test only the packages a commit touched.
polyglot Per-language checks, chosen by which files changed.
helpers Functions that return groups of steps.
changed-files match_files and paths_filter: what changed-files and paths-filter actions are for.
wrapping-actions setup-node, trivy, hadolint and docker build as functions that return steps.
wrapping-lint-actions golangci-lint, ruff, shellcheck and actionlint, each run only when its kind of file changed.
wrapping-release-actions Image push and goreleaser, for a tag only and never reused.
changed-files-matrix A job per service that changed, the usual use of a changed-files action.
python-uv A tool (uv), apt packages, and input patterns.
services A database beside each test step, its own and ready before the step starts.
go The Go toolchain as a tool; builds for several platforms.
rust Cargo, with its caches kept between runs.
terraform Validate each stack that changed.
shell-scripts Two small tools, one an archive and one a single binary.
security Secrets, vulnerable dependencies, Dockerfile lint.
gpu Shared base inputs plus per-step test files; a step that needs a GPU worker.
placement worker, prefer and avoid.
pi-gamebook A real repository's CI.
pi-gamebook-tools The same, on plain Debian with Bun as a tool.

Compiled

Every basic script is also written out for GitHub Actions (which Forgejo and Gitea read too) and for CircleCI, to see what starci compile makes of it:

  • basic/compiled/github/<name>.yml, from starci compile
  • basic/compiled/circleci/<name>.yml, from starci compile --target circleci

events is the one to read first for GitHub: its jobs carry conditions and the workflow's on: is worked out from the script. services shows a database started and stopped by the job itself. Each file's header says what did not carry over. Advanced scripts cannot be compiled, so there are none for them.

basic/compile.sh writes them all again; basic/compile.sh --check fails if any is not what its script compiles to now.

Advanced: pipeline(ctx) runs steps and reacts
fanout One step per test file, found by a step.
shards Count the tests, then choose how many shards to run.
affected Ask the build tool what a commit affects; test that.
choose-by-step A step decides which heavy checks the commit needs.
first-failure Cheap checks first, expensive ones only if they pass.
retry-flaky Retry only what failed, and report what passed only on retry.
tolerated Advisory checks that are reported but never block.
coverage-gate Read numbers out of steps and hold the commit to a rule.
deploy-gate Deploy from main, smoke test, roll back on failure.
canary Widen a release stage by stage, withdrawing at the first bad sign.
wait-until-ready Poll until something is up, test it, always clean up.
pi-gamebook A real repository: fan out over its test files, retry failures.