Skip to content

Release assurance

BoardReadyOps releases must be repeatable, reviewable, and easy to audit.

Branch controls

The main branch uses strict required checks, zero required human approvals for the current single-maintainer model, resolved review conversations, linear history, signed commits, disabled force pushes, disabled deletion, squash-only merges, and a PR-only administrator bypass. CODEOWNERS review is not required while the sole code owner and sole maintainer are the same person.

Every squash merge to main must produce a GitHub-verified commit. Review and CODEOWNERS approval requirements should be reconsidered when a second trusted maintainer is onboarded.

Required status checks

The committed ruleset requires these stable contexts on main:

  • ci / risk-profile
  • ci / lint
  • ci / typecheck
  • ci / test-unit
  • ci / build
  • ci / verify-dist
  • security / gate

Conditional matrix, integration, accessibility, coverage, mutation, and specialist scanner jobs continue to run according to the risk profile, but their individual names are not branch-protection contracts.

Release checks

Before publishing a release, maintainers must verify the build, committed distribution files, version metadata, marketplace metadata, package contents, project health checks, and generated release evidence.

The dist-check workflow includes the package content validator so the npm package contains release-critical files before release work continues.

Artifact checks

Binary release preparation must build and verify each supported target, collect the artifacts, generate checksums, create SBOM evidence, and verify that generated checksums are current before release upload steps run.

Container release preparation must build the smoke image, run the CLI smoke checks, run the fixture project smoke check, and scan the image before any publish mode is used.

npm package provenance

package.json sets publishConfig.provenance: true. When the publish-npm workflow runs with id-token: write permission, npm generates and attaches a Sigstore-based provenance attestation to every published package version. This links the package to the exact GitHub Actions workflow run that produced it.

The publish-npm workflow also uses actions/attest-build-provenance to create a GitHub Artifact Attestation for the committed dist/** bundles. This provides an additional, independently verifiable chain from the source commit to the published distribution files.

Container images follow the same practice: the container-build workflow builds and attests the image before publishing to GHCR.

Maintainer release checklist

Before creating or publishing a release, the maintainer must verify:

  1. All required CI checks are green on main.
  2. corepack pnpm run verify passes locally (or on a clean runner).
  3. npm pack --dry-run --json confirms the tarball includes dist/cli/index.cjs, dist/action/index.cjs, package.json, README.md, LICENSE, NOTICE, SECURITY.md, and action.yml.
  4. The release-please PR version, CHANGELOG.md, package.json, .release-please-manifest.json, and src/generated/version.ts are consistent.
  5. Binary assets, SHA256SUMS, and sbom.cyclonedx.json are uploaded to the GitHub Release.
  6. Formula/boardreadyops.rb checksums are updated for the new release binaries.
  7. GHCR v1, v1.MAJOR, and latest floating tags resolve to the correct digest after the container workflow completes.

Failure recovery

npm publish failed

  1. Check the publish-npm workflow run logs for the exact error.
  2. If the package was partially published (unlikely with npm's atomic publish), verify with npm view boardreadyops@<version> and check the dist-tags.
  3. If authentication failed, verify the npm trusted publisher is configured for repository oaslananka/boardreadyops, workflow file publish-npm.yml, and the npm publish action. Confirm the job still has id-token: write and uses a current npm CLI. Do not add a token fallback to the normal publish path.
  4. If provenance signing failed, verify the trusted publisher tuple and OIDC permission before retrying the same release tag.
  5. If the package version already exists, the workflow skips publication without error; verify the published version and provenance instead of attempting to overwrite it.

During the Trusted Publishing migration only, the previous npm automation credential may remain in the approved secret-management system as a time-bounded rollback credential until one new version has been published successfully through OIDC and independently verified. It must not be injected into the normal publish job or written to .npmrc. After verified cutover, remove the GitHub Actions NPM_TOKEN secret, revoke the upstream npm token, and remove the obsolete source secret from Doppler. A rollback before revocation restores the previously reviewed workflow revision; it never exposes the credential in source, logs, issues, or pull requests.

Release tag on wrong commit

  1. Do not force-push or delete the tag on main. Create a new patch release instead.
  2. If a prerelease tag needs correction before the release is published, delete the tag locally and remotely (git tag -d vX.Y.Z && git push origin :vX.Y.Z) and re-tag the correct commit.

CI broke on main after a merge

  1. Do not publish a release until main is green.
  2. Open a fix PR with the fix: scope, get review, and merge via the standard process.
  3. If the breakage is in a required status check, the automated release-please PR will not be mergeable until the check passes.

Signed artifact attestation missing

  1. Verify the publish-npm and provenance workflow runs completed successfully.
  2. Run gh attestation verify dist/cli/index.cjs --repo oaslananka/boardreadyops to confirm the attestation is queryable.
  3. If missing, re-run the provenance workflow via workflow_dispatch against the release tag.

Evidence expected for closure

The release hardening pass is healthy when these checks are green on main: CI, security workflow, dist-check, binary-build, and container-build smoke mode.