Source Artifacts And Signing

Source Artifacts And Signing

Source publication is a component choice. The core lifecycle does not require a separately built source archive.

Platform-generated source snapshot

 1source:
 2  selection: explicit-ref-or-default-branch
 3  default_branch: main
 4  snapshot:
 5    mode: platform-generated
 6  checks:
 7    platform: github
 8    required:
 9      - Required Checks
10artifacts:
11  produced: []
12  checksums: []

This mode relies on the hosting platform’s snapshot of an immutable tag. Promotion records same-source-revision evidence when candidate and final tags resolve to the same exact commit.

mode: none is also available when a release intentionally exposes no source snapshot.

Built source archive

 1source:
 2  selection: explicit-ref
 3  snapshot:
 4    mode: built-asset
 5    filename_template: "{component}-{version}-src.tar.gz"
 6    archive_root_template: "{component}-{version}"
 7artifacts:
 8  produced:
 9    - source-archive
10  checksums:
11    - sha256
12    - sha512

The templates may use {component} and {version}. No foundation-specific suffix is added by the core. A project that needs a special filename selects it explicitly in its own config.

Components with built artifacts add component-owned build and verification jobs to their workflow. Same-run files should move through workflow artifacts with digest validation. Candidate promotion downloads the durable candidate assets and requires byte-identical digest evidence before uploading them to the final release.

OpenPGP signing

Add signing under artifacts:

 1artifacts:
 2  produced:
 3    - source-archive
 4  checksums:
 5    - sha512
 6  signing:
 7    kind: openpgp
 8    private_key_env: PROJECT_RELEASE_PRIVATE_KEY
 9    passphrase_env: PROJECT_RELEASE_KEY_PASSPHRASE
10    expected_fingerprint: 0123456789ABCDEF0123456789ABCDEF01234567
11    signature_format: detached-ascii-armored

The values of private_key_env and passphrase_env are environment-variable names, not secrets. Map those variables to the component’s GitHub secrets in the job that signs.

For an unprotected private key, omit passphrase_env:

1signing:
2  kind: openpgp
3  private_key_env: PROJECT_RELEASE_PRIVATE_KEY
4  expected_fingerprint: 0123456789ABCDEF0123456789ABCDEF01234567

The signer imports exactly one primary secret key into an isolated temporary GnuPG home. When configured, the full fingerprint must match. A protected-key passphrase is supplied through GnuPG loopback input rather than command arguments. Signing subprocesses receive a constructed environment with the configured key and passphrase variables removed, and errors are sanitized against secret values.

expected_fingerprint is optional in the schema but recommended for a production signing identity.

Responsibility boundary

The component remains responsible for:

• provisioning and rotating its signing key and optional passphrase;
• selecting GitHub Environment and secret access policy;
• ensuring only the intended signing job receives those values;
• publishing or otherwise establishing the public trust path for the signing key.

The CLI is responsible for isolated import, configured fingerprint enforcement, secret-safe signing invocation, detached signature creation, and failure without replacing an existing valid signature when signing does not complete.