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 and its subkeys into an isolated temporary GnuPG home. When configured, the full fingerprint must identify either that primary key or one signing-capable subkey. Selecting a subkey forces GnuPG to use that exact subkey. 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.

Reproducible Python distributions

Buildish Release Tooling’s package build derives SOURCE_DATE_EPOCH from the selected source commit. Its setuptools hooks normalize wheel metadata and sdist tar ownership, modes, timestamps, PAX headers, and gzip headers. The release build requires two clean builds to be byte-identical and requires a wheel rebuilt from the sdist to match the wheel built from the repository. Exact build backend versions are pinned in pyproject.toml.

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.