Direct Release

Direct Release

The direct lifecycle turns one exact source revision into the final tag and final GitHub Release in one manually dispatched workflow. It does not create a candidate, require a vote, or introduce a candidate-shaped placeholder in final release state.

“One click” means one workflow dispatch. The workflow still separates resolution, source checks, tag creation, staging, verification, publication, and manifest attachment so a component can place policy boundaries between those jobs.

Minimal configuration

 1component:
 2  id: example
 3  display_name: Example
 4versioning:
 5  scheme: semver
 6  final_tag_template: "v{version}"
 7source:
 8  selection: explicit-ref-or-default-branch
 9  default_branch: main
10  snapshot:
11    mode: platform-generated
12  checks:
13    platform: github
14    required:
15      - Required Checks
16lifecycle:
17  mode: direct
18artifacts:
19  produced: []
20  checksums: []
21publication:
22  authoritative:
23    kind: github-release
24    repository: example/example
25tags:
26  final_mode: exact-source-commit
27  moving: []
28policy_profiles: {}

This example treats GitHub as authoritative and relies on the source archives GitHub generates from the immutable final tag. It publishes no separately built source artifact.

Dispatch

Run .github/workflows/release-direct.yml with:

• version: the exact final version, for example 1.2.3;
• source_ref: an optional exact branch, tag, or commit allowed by the configured source-selection policy.

When source_ref is omitted, the example configuration resolves main. Resolution records the exact commit; later jobs use that commit identity rather than re-resolving a moving branch.

Workflow phases

1. resolve creates DirectReleaseState with the release identity, exact source commit, final tag, and artifact policy.
2. verify-source checks the configured GitHub check-run/status requirement on that exact commit.
3. create-final-tag creates or revalidates the immutable final tag.
4. stage creates or completes the draft final GitHub Release.
5. verify-final compares the observed tag, release metadata, and assets with the resolved state.
6. publish makes the exact release public or confirms that an identical publication already exists.
7. manifest creates release-manifest-v1.json, validates both workflow handoff digests, attaches the manifest without clobbering an existing asset, and revalidates the release.

Same-run JSON files move through GitHub workflow artifacts. Every privilege-bearing consumer checks the SHA-256 emitted by the producing job before acting.

Reruns and conflicts

The mutation commands are convergent for identical state:

• an identical tag, draft release, public release, or manifest attachment reports an already-complete outcome where applicable;
• an existing tag at another commit, mismatched release body, unexpected asset, size mismatch, or digest mismatch fails closed;
• asset upload never uses clobber behavior.

The workflow uses non-canceling concurrency keyed by repository and version. A second run waits instead of cancelling a run that may already have changed external release state.

Variations

• Use a separately built and signed source artifact when the hosting-platform snapshot is not sufficient.
• Add environment: to the jobs selected by project policy; see Workflow composition.
• Create a release branch separately with create-release-branch when a component needs maintained release lines. The direct lifecycle itself does not require one.
• Use the candidate lifecycle when publication must wait for an external approval or vote over an exact candidate.