Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/repo-standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,12 @@ Use only GitHub's default labels and labels added by Dependabot.
- Every repo with code has one workflow, `.github/workflows/ci.yml`, named `CI`. Its jobs are `lint`, `typecheck` (typed code), `test` and `build` (anything that ships), plus `e2e` where there are end-to-end tests. A repo whose checks are one script runs it as one job named `test`.
- A job never sets a `name:` that differs from its id. Required checks and other workflows key on these names.
- Jobs call the repo's own scripts instead of repeating tool commands and flags.
- A change to `.github/workflows/` runs each job it changes with [act](https://github.com/nektos/act) on the local Podman before the push, so a step that fails in CI's container fails here first. Point act at Podman's socket (`DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')`) and run `act <event> -j <job> --container-architecture linux/arm64 -P ubuntu-latest=catthehacker/ubuntu:act-latest --container-daemon-socket -`. act can't run JavaScript actions inside a job with `container:` ([nektos/act#732](https://github.com/nektos/act/issues/732)), so a step there that only speeds CI up, like `actions/cache`, sets `if: ${{ !env.ACT }}`. A job act can't run, like a macOS job, is named in the pull request with how it was checked instead.
- A change to `.github/workflows/` runs each job it changes with [act](https://github.com/nektos/act) on the local Podman before the push, so a step that fails in CI's container fails here first. Point act at Podman's socket (`DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')`) and run `act <event> -j <job> --container-architecture linux/arm64 -P ubuntu-latest=catthehacker/ubuntu:act-latest --container-options '--security-opt label=disable' --container-daemon-socket -`.
- Without `--security-opt label=disable`, act's keep-alive command (`tail -f /dev/null`) is denied under the Podman machine's SELinux labels on Ubuntu 26.04 and the job container exits at start. The option turns off SELinux labels for that throwaway container only.
- Run act from a plain clone. In a linked worktree `.git` is a file that points at a host path, which the container can't follow ([nektos/act#6074](https://github.com/nektos/act/issues/6074)).
- act can't run JavaScript actions inside a job with `container:` ([nektos/act#732](https://github.com/nektos/act/issues/732)), so a step there that only speeds CI up, like `actions/cache`, sets `if: ${{ !env.ACT }}`. A job act can't run, like a macOS job, is named in the pull request with how it was checked instead.
- A green act run doesn't show that a tool exists on the runner. act's image has more tools than the [ARC runner image](https://docs.github.com/en/actions/concepts/runners/actions-runner-controller), which is minimal by design, so a step installs what it calls or uses a setup action.
- A test that passes on macOS and fails only on Linux isn't caught by this check. CI is the gate for it.
- Run on pull requests and on pushes to `main`. Add `workflow_dispatch` when people or other workflows start it by hand, and never remove it without checking what starts it. A job-level `if:` must allow every trigger the workflow has.
- Set `permissions: contents: read` at the top. A job that needs more asks for it itself.
- Every job sets `timeout-minutes`, based on how long it really takes, with room to spare. Jobs that call a reusable workflow are exempt.
Expand Down