|
|
|
@@ -1,6 +1,6 @@
|
|
|
|
|
---
|
|
|
|
|
title: Repository Policies
|
|
|
|
|
last_modified: 2026-11-03
|
|
|
|
|
last_modified: 2026-11-01
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
This document covers repository structure, tooling, and workflow standards. Code
|
|
|
|
@@ -20,36 +20,19 @@ style conventions are in separate documents:
|
|
|
|
|
`last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
|
|
|
|
|
with the authoritative source as policies evolve.
|
|
|
|
|
|
|
|
|
|
- **External references must be pinned by cryptographic hash.** This includes
|
|
|
|
|
Docker base images, Go modules, npm packages, GitHub Actions, and anything
|
|
|
|
|
else fetched from a remote source. Version tags (`@v4`, `@latest`, `:3.21`,
|
|
|
|
|
etc.) are server-mutable and therefore remote code execution vulnerabilities.
|
|
|
|
|
Reference an external dependency by its content hash (Docker `@sha256:...`, Go
|
|
|
|
|
module hash in `go.sum`, npm integrity hash in lockfile, GitHub Actions
|
|
|
|
|
`@<commit-sha>`). This also means never `curl | bash` to install tools like
|
|
|
|
|
pyenv, nvm, rustup, etc. Instead, download a specific release archive from
|
|
|
|
|
GitHub, verify its hash (hardcoded in the Dockerfile or script), and only then
|
|
|
|
|
install. Unverified install scripts are arbitrary remote code execution. This
|
|
|
|
|
is the single most important rule in this document. Double-check every
|
|
|
|
|
external reference in every file before committing.
|
|
|
|
|
|
|
|
|
|
There is one exception: a package from the distribution's own package index
|
|
|
|
|
needs no version and no hash. Pulling that index is also allowed. The
|
|
|
|
|
distribution is trusted. In a `Dockerfile`, it is the pinned base image's
|
|
|
|
|
distribution. On a host, it is the host's. These commands are examples:
|
|
|
|
|
- `apt-get update`
|
|
|
|
|
- `apt-get install`
|
|
|
|
|
- `apk update`
|
|
|
|
|
- `apk add`
|
|
|
|
|
|
|
|
|
|
These are not trusted, so everything from them stays pinned by hash:
|
|
|
|
|
- Docker Hub
|
|
|
|
|
- PyPI
|
|
|
|
|
- npm
|
|
|
|
|
- `go get`
|
|
|
|
|
|
|
|
|
|
A package source that a `Dockerfile` adds itself is not the distribution's
|
|
|
|
|
own, so the exception does not cover it.
|
|
|
|
|
- **ALL external references must be pinned by cryptographic hash.** This
|
|
|
|
|
includes Docker base images, Go modules, npm packages, GitHub Actions, and
|
|
|
|
|
anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
|
|
|
|
|
`:3.21`, etc.) are server-mutable and therefore remote code execution
|
|
|
|
|
vulnerabilities. The ONLY acceptable way to reference an external dependency
|
|
|
|
|
is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
|
|
|
|
|
integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
|
|
|
|
|
This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
|
|
|
|
|
etc. Instead, download a specific release archive from GitHub, verify its hash
|
|
|
|
|
(hardcoded in the Dockerfile or script), and only then install. Unverified
|
|
|
|
|
install scripts are arbitrary remote code execution. This is the single most
|
|
|
|
|
important rule in this document. Double-check every external reference in
|
|
|
|
|
every file before committing. There are zero exceptions to this rule.
|
|
|
|
|
|
|
|
|
|
- Every repo with software must have a root `Makefile` with these targets:
|
|
|
|
|
`make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
|
|
|
|
@@ -250,8 +233,6 @@ style conventions are in separate documents:
|
|
|
|
|
# Test phase. -race needs cgo and so a C compiler, which the Debian Go
|
|
|
|
|
# image ships and the alpine one does not. -count=1 because the mounted
|
|
|
|
|
# cache also holds test results, which go test would otherwise replay.
|
|
|
|
|
# A first run that timed out gets no rerun, because a rerun would only
|
|
|
|
|
# wait for the same hang.
|
|
|
|
|
# golang:1.x, YYYY-MM-DD
|
|
|
|
|
FROM golang@sha256:... AS test
|
|
|
|
|
WORKDIR /src
|
|
|
|
@@ -260,24 +241,15 @@ style conventions are in separate documents:
|
|
|
|
|
ARG CACHEBUST
|
|
|
|
|
COPY . .
|
|
|
|
|
RUN --mount=type=cache,target=/root/.cache/go-build \
|
|
|
|
|
status=0; \
|
|
|
|
|
output=$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$?; \
|
|
|
|
|
printf '%s\n' "$output"; \
|
|
|
|
|
test "$status" -eq 0 && exit 0; \
|
|
|
|
|
case "$output" in \
|
|
|
|
|
*"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \
|
|
|
|
|
esac; \
|
|
|
|
|
echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
go test -count=1 -timeout 90s -race -v ./...; \
|
|
|
|
|
exit 1
|
|
|
|
|
go test -count=1 -timeout 90s -race -cover ./... || \
|
|
|
|
|
{ echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
go test -count=1 -timeout 90s -race -v ./...; exit 1; }
|
|
|
|
|
|
|
|
|
|
# Build stage. Nothing is wanted from either phase above; the copies
|
|
|
|
|
# are what make BuildKit build them first, so nothing after them can
|
|
|
|
|
# run unless lint and test passed.
|
|
|
|
|
# golang:1.x-alpine, YYYY-MM-DD
|
|
|
|
|
FROM golang@sha256:... AS builder
|
|
|
|
|
# git comes from the base image's own distribution package index, which
|
|
|
|
|
# is trusted, so it needs no version and no hash.
|
|
|
|
|
RUN apk add --no-cache git
|
|
|
|
|
WORKDIR /src
|
|
|
|
|
COPY go.mod go.sum ./
|
|
|
|
@@ -413,10 +385,11 @@ style conventions are in separate documents:
|
|
|
|
|
`Pipfile.lock`. It installs no Python there: the tests use the base
|
|
|
|
|
image's Python, which the image's hash pins. If it installs anything else
|
|
|
|
|
there, the step goes after `ARG CACHEBUST`.
|
|
|
|
|
- PyPI is not trusted, so `script/bootstrap` installs pipenv and its
|
|
|
|
|
dependencies by hash. It does so with `pip install --require-hashes -r`
|
|
|
|
|
and a requirements file in `script/` that lists each of them with `==` and
|
|
|
|
|
its `--hash`. pip refuses to install a dependency the file does not list.
|
|
|
|
|
- Every external reference must be pinned by hash, so `script/bootstrap`
|
|
|
|
|
installs pipenv and its dependencies by hash. It does so with
|
|
|
|
|
`pip install --require-hashes -r` and a requirements file in `script/`
|
|
|
|
|
that lists each of them with `==` and its `--hash`. pip refuses to install
|
|
|
|
|
a dependency the file does not list.
|
|
|
|
|
- It then runs `pipenv install --deploy`, with `--dev` when the tests need
|
|
|
|
|
the development packages. `--deploy` installs only what `Pipfile.lock`
|
|
|
|
|
names, checks every package against the lockfile's hashes, and fails when
|
|
|
|
@@ -440,8 +413,7 @@ style conventions are in separate documents:
|
|
|
|
|
`pipenv install --dev --deploy`:
|
|
|
|
|
|
|
|
|
|
```dockerfile
|
|
|
|
|
# Test phase. Both pytest runs share one 90-second timeout, so a hang
|
|
|
|
|
# uses it once and gets no rerun.
|
|
|
|
|
# Test phase. The 90-second timeout covers both pytest runs.
|
|
|
|
|
# python:3.x-slim, YYYY-MM-DD
|
|
|
|
|
FROM python@sha256:... AS test
|
|
|
|
|
# make and git are base tools that script/bootstrap installs when they
|
|
|
|
@@ -512,19 +484,15 @@ style conventions are in separate documents:
|
|
|
|
|
improvement bug against that repo. Add a 90-second timeout to the test
|
|
|
|
|
invocation (`go test -timeout 90s`). The backstop deliberately sits above the
|
|
|
|
|
hard cap so that it catches a genuinely hung test rather than a merely slow
|
|
|
|
|
one. A hung package uses the backstop once, because a first run that timed out
|
|
|
|
|
gets no rerun. `-timeout` applies to each package, so several hung packages
|
|
|
|
|
can each use it.
|
|
|
|
|
one.
|
|
|
|
|
|
|
|
|
|
- **The test command should use the conditional verbose rerun pattern.** Run
|
|
|
|
|
tests without `-v` (verbose) first. If tests fail, automatically rerun with
|
|
|
|
|
`-v` to show full output. This keeps CI logs and `docker build` output clean
|
|
|
|
|
on success (just package/suite summaries) while providing full diagnostic
|
|
|
|
|
detail on failure (every test case, every assertion). A first run that timed
|
|
|
|
|
out gets no rerun, because the rerun would only wait for the same hang. The
|
|
|
|
|
command lives in the `test` phase of the `Dockerfile`, since `script/test`
|
|
|
|
|
builds that phase; the Makefile form below is the same pattern for any
|
|
|
|
|
repo-local invocation:
|
|
|
|
|
detail on failure (every test case, every assertion). The command lives in the
|
|
|
|
|
`test` phase of the `Dockerfile`, since `script/test` builds that phase; the
|
|
|
|
|
Makefile form below is the same pattern for any repo-local invocation:
|
|
|
|
|
|
|
|
|
|
```makefile
|
|
|
|
|
test:
|
|
|
|
@@ -537,29 +505,11 @@ style conventions are in separate documents:
|
|
|
|
|
|
|
|
|
|
```makefile
|
|
|
|
|
test:
|
|
|
|
|
@status=0; \
|
|
|
|
|
output=$$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$$?; \
|
|
|
|
|
printf '%s\n' "$$output"; \
|
|
|
|
|
test "$$status" -eq 0 && exit 0; \
|
|
|
|
|
case "$$output" in \
|
|
|
|
|
*"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \
|
|
|
|
|
esac; \
|
|
|
|
|
echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
go test -count=1 -timeout 90s -race -v ./...; \
|
|
|
|
|
exit 1
|
|
|
|
|
@go test -count=1 -timeout 90s -race -cover ./... || \
|
|
|
|
|
{ echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
go test -count=1 -timeout 90s -race -v ./...; exit 1; }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The first run's output is kept so that the recipe can look in it for what Go
|
|
|
|
|
prints for a hang:
|
|
|
|
|
- `panic: test timed out` means the test's own timer fired.
|
|
|
|
|
- `*** Test killed` means `go test` stopped a test that ignored that timer,
|
|
|
|
|
about a minute later.
|
|
|
|
|
|
|
|
|
|
Go prints the goroutine stacks with either line, as long as the test can
|
|
|
|
|
still respond. A rerun would only wait for the same hang, so the recipe
|
|
|
|
|
exits 1. A failure with neither line in its output reruns with `-v`. The
|
|
|
|
|
kept output prints when the first run ends, not while it runs.
|
|
|
|
|
|
|
|
|
|
`-count=1` is required on both invocations: it defeats Go's test _result_
|
|
|
|
|
cache, so neither run can report a stored pass in place of running the
|
|
|
|
|
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
|
|
|
@@ -578,25 +528,17 @@ style conventions are in separate documents:
|
|
|
|
|
|
|
|
|
|
```makefile
|
|
|
|
|
test:
|
|
|
|
|
@timeout 90 sh -c 'python -m pytest || { \
|
|
|
|
|
echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
python -m pytest -v; exit 1; }'
|
|
|
|
|
@python -m pytest || \
|
|
|
|
|
{ echo "--- Rerunning with -v for details ---"; \
|
|
|
|
|
python -m pytest -v; exit 1; }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Both pytest runs share that one 90-second timeout, as in the `Dockerfile`
|
|
|
|
|
example above, so a hang uses it once and gets no rerun. Ctrl-C does not
|
|
|
|
|
stop a running `make test`, which goes on until the tests end or the 90
|
|
|
|
|
seconds run out. On a Mac without `timeout`, the target fails until it is
|
|
|
|
|
installed.
|
|
|
|
|
|
|
|
|
|
The `exit 1` ensures the target always fails after a rerun — the first run
|
|
|
|
|
already proved the tests are broken, so the build must not pass even if a
|
|
|
|
|
flaky test happens to succeed on the second attempt. The rerun exists solely
|
|
|
|
|
for diagnostic output.
|
|
|
|
|
|
|
|
|
|
- Docker builds must complete in under 5 minutes. A hung package uses the
|
|
|
|
|
90-second test backstop once, because a first run that timed out gets no
|
|
|
|
|
rerun.
|
|
|
|
|
- Docker builds must complete in under 5 minutes.
|
|
|
|
|
|
|
|
|
|
- `make check` must not modify any files in the repo. Tests may use temporary
|
|
|
|
|
directories.
|
|
|
|
@@ -716,10 +658,10 @@ style conventions are in separate documents:
|
|
|
|
|
`test-support` depguard rule, where a repo names its own test-support packages
|
|
|
|
|
by full import path. A repo adds entries there and changes nothing else, and a
|
|
|
|
|
re-vendor carries its entries forward. The canonical golangci-lint version is
|
|
|
|
|
v2.14.0 (released 2026-09-24), pinned as the digest of the lint phase's base
|
|
|
|
|
v2.15.0 (released 2026-10-16), pinned as the digest of the lint phase's base
|
|
|
|
|
image
|
|
|
|
|
(`golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f`,
|
|
|
|
|
which reports `2.14.0 built with go1.27.0 from 114493f9`). A module's `go`
|
|
|
|
|
(`golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481`,
|
|
|
|
|
which reports `2.15.0 built with go1.27.0 from 25c5369a`). A module's `go`
|
|
|
|
|
directive must not name a newer Go minor version than the one golangci-lint
|
|
|
|
|
was built with, or golangci-lint refuses to lint it: this release lints
|
|
|
|
|
`go 1.27.1` but not `go 1.28`. That digest is the only pin, since no repo
|
|
|
|
|
sneak