stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
150b3730ef592c761bd7064f0d09e4ea4d5a0df8
git.stella-ops.org/docs/modules/mirror/signing-runbook.md
StellaOps Bot 150b3730ef
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
up
2025-11-24 07:52:25 +02:00

2.3 KiB
Raw Blame History

Mirror bundle signing runbook (CI)

Prerequisites

  • Ed25519 private key (PEM). Keep in CI secrets only.
  • Base64-encode the PEM: base64 -w0 mirror-ci-ed25519.pem > mirror-ci-ed25519.pem.b64.
  • Create CI secret MIRROR_SIGN_KEY_B64 with that value.

Pipeline step (Gitea example)

- name: Build/sign mirror thin bundle
  env:
    MIRROR_SIGN_KEY_B64: ${{ secrets.MIRROR_SIGN_KEY_B64 }}
    REQUIRE_PROD_SIGNING: 1
    OCI: 1
  run: |
    scripts/mirror/check_signing_prereqs.sh
    scripts/mirror/ci-sign.sh

Outputs are placed under out/mirror/thin/ and out/mirror/thin/oci/; archive these as artifacts.

How to add the secret in Gitea (one-time)

  1. Repository → Settings → Secrets.
  2. New secret: name MIRROR_SIGN_KEY_B64, value = base64-encoded Ed25519 PEM (no newlines, no header/footer).
  3. Scope: repository (or environment-specific if needed).
  4. Save. The pipeline step will skip if the secret is empty; keep it present in release branches only.

Local dry-run with test key

MIRROR_SIGN_KEY_B64=$(base64 -w0 out/mirror/thin/tuf/keys/mirror-ed25519-test-1.pem) \
OCI=1 scripts/mirror/ci-sign.sh

Temporary dev key (to unblock CI until production key is issued)

Use this throwaway Ed25519 key only for non-production runs. Generated 2025-11-24 to replace the previous placeholder; rotate TUF metadata immediately after swapping in the production key.

MIRROR_SIGN_KEY_B64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1DNENBUUF3QlFZREsyVndCQ0lFSUxGdFMwbjBpMVVueE1maGt0cDNlY1N4WHVxYmcrVFJuaENhS05jaGtTbFIKLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLQo=

Do not ship with this key. Set REQUIRE_PROD_SIGNING=1 for release/tag builds so they fail without the real key. Add the production key as a Gitea secret (MIRROR_SIGN_KEY_B64) and rerun the workflow; remove this temporary key block once rotated.

Verification

The CI step already runs scripts/mirror/verify_thin_bundle.py. For OCI, ensure out/mirror/thin/oci/index.json references the manifest digest.

Fallback (if secret absent)

  • CI can fall back to an embedded test Ed25519 key when MIRROR_SIGN_KEY_B64 is unset only when REQUIRE_PROD_SIGNING is not set. This is for dev smoke runs; release/tag jobs must set REQUIRE_PROD_SIGNING=1 to forbid fallback.
  • For release branches, always set REQUIRE_PROD_SIGNING=1 and provide MIRROR_SIGN_KEY_B64; otherwise the step will fail early.