ADR 0016: CI/CD pipeline, simplified GitFlow and automated releases
- Status: Accepted. The release workflow, the version handling and the merge methods are superseded by ADR 0022.
- Date: 2026-10-20
Context
The repository had no continuous integration or delivery. Nothing checked formatting, lint, types, tests, coverage or vulnerable dependencies before a change reached main. The branch rules were written conventions only, and releases were not defined. The repository is public and accepts outside contributions, so the maintainer wants a pipeline that is simple to understand, cheap to maintain and safe to open to contributors (spec: issue #11).
Decision
- Simplified GitFlow. Branches are
main,develop,feature/*,bugfix/*andhotfix/*. Work branches fromdevelopand reaches it through a pull request. Ahotfix/*branches frommain, merges intomain, and is back-merged intodevelop. There are norelease/*branches: a release is a pull request fromdevelopintomain. - Branch policy.
scripts/ci/branch-policy.sh <source> <target>allows a pull request intomainonly fromdeveloporhotfix/*, and intodeveloponly fromfeature/*,bugfix/*orhotfix/*. Any other branch name is rejected, with the reason printed. - Rulesets.
mainanddevelopeach have a ruleset that blocks direct pushes and deletions, requires a pull request with one approval from a code owner, requires resolved conversations and a branch up to date with its base, and requires the status checks below..github/CODEOWNERSassigns every path to the maintainer. The maintainer is the only bypass actor, in pull-request-only mode, so the checks still apply to them. - Merge commits only. Squash and rebase merging are disabled, so the atomic commits of a branch stay in the history.
- Biome instead of ESLint and Prettier. Biome (
@biomejs/biome) formats and lints the TypeScript sources. The typescript-eslint parser does not support TypeScript 7, which the project uses. Markdown is outside the format gate. - Local hooks. husky (installed by
npm ci) runspre-commit, which callsnpm run format:checkandnpm run lint, andcommit-msg, which runs commitlint with@commitlint/config-conventional. Commit messages follow Conventional Commits. These four packages are the only new dev dependencies (Biome,@commitlint/cli,@commitlint/config-conventional, husky). No runtime dependency is added. - Coverage gate.
npm run test:coveragerunsnode --testwith the built-in coverage and minimums of 95% lines, 85% branches and 90% functions. The minimums sit below the current coverage (about 98%, 91% and 93.5%) and are raised by hand when coverage rises. - CI workflow (
.github/workflows/ci.yml, on pull requests intodevelopandmain):quality(Ubuntu, Node.js 24): lint, format check, type check, build, andnpm audit --omit=dev --audit-level=high.test: matrix of Ubuntu on Node.js 22.18 and 24, and Windows on Node.js 24, runningnpm run test:coverage.commits: commitlint over the commits of the pull request. GitHub merge commits are skipped by the default ignores.branch-policy: runs the branch policy script with the head and base refs.dependency-review: reviews dependency changes of the pull request.- CodeQL (
.github/workflows/codeql.yml): JavaScript and TypeScript analysis on pull requests and weekly onmain. - Required checks:
quality, eachtestleg,commits,branch-policy,dependency-reviewand the CodeQL analysis.
- Integration workflow (
.github/workflows/integration.yml): manualworkflow_dispatchonly, never on pull requests. It runs in theintegrationenvironment, which requires the maintainer's approval and accepts onlydevelopandmain. It authenticates to the Databricks workspace with a dedicated service principal and OAuth machine-to-machine; host, client id and client secret are environment secrets. The integration tests use these variables when all three are set, and the profile inDAK_IT_PROFILEotherwise. - Release workflow (
.github/workflows/release.yml, on pushes tomain). git-cliff (pinned GitHub action, no npm dependency) computes the next version and the release notes from the Conventional Commits since the last tag. Onlyfeat,fixandperfcommits are releasable. Without releasable commits nothing is published. Otherwise the workflow packs the tarball with the version set for the build only, creates thevX.Y.Ztag and publishes a GitHub Release with the notes and the tarball. There is no changelog file: GitHub Releases is the changelog. The package stays private and is not published to npm. - Workflow hardening. Each workflow defaults to
contents: read; write permissions are granted per job. Third-party actions are pinned to full commit hashes. Dependabot updates npm and GitHub Actions weekly, grouped, intodevelop, with thechorecommit prefix. - Minimum Node.js 22.18 (
engines). The end-to-end tests runsrc/*.tsin child processes and need type stripping without a flag, which Node.js enables from 22.18. On 22.13 nine end-to-end tests fail (commitde3d3e2). The test matrix runs the minimum version, so the declared range stays true.
Consequences
- Required check names are part of the rulesets. Renaming a job or a matrix leg needs the rulesets updated in the same change.
- Rulesets, the
integrationenvironment and the service principal are GitHub settings, not files in the repository. They are applied by the maintainer after the pull request that introduces the pipeline is merged, so that pull request is not blocked by them. Until thenmainanddevelopare briefly unprotected; this is accepted because the history was scanned for secrets and the repository is already public. - Contributors need Node.js 22.18 or later.
npm ciinstalls the hooks. - Commit messages are validated and become the release notes, so a commit with a wrong type is not listed in them.
- Known debts:
- Biome
style/noNonNullAssertionreports 96 warnings. They do not fail the lint gate and are fixed in a later change. - The first release is
v0.1.0, computed from the full history (initial_tagincliff.toml). chore!does not bump the major version (git-cliff limitation). A breaking change should use a releasable type, such asfeat!orfix!.
- Biome