Skip to content

Commit 22a3cb2

Browse files
dheerajodhadheerajodha
committed
docs: describe release process for EC CLI
This document describes the EC CLI release and bundle process for the Conforma project resolves: EC-1477
1 parent 648b700 commit 22a3cb2

File tree

2 files changed

+157
-1
lines changed

2 files changed

+157
-1
lines changed

‎docs/modules/ROOT/pages/release-process.adoc‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
= Release and Bundle Process
2+
3+
This document describes the EC CLI release and bundle process for the Conforma project.
4+
5+
== Overview
6+
7+
The EC CLI release process is fully automated through GitHub Actions. It builds distribution binaries, container images, Tekton task bundles, and GitHub releases whenever changes are merged to the `main` branch.
8+
9+
== When Releases Are Triggered
10+
11+
Releases are triggered in two ways:
12+
13+
. **Automatic**: After successful completion of the `Checks` workflow on the `main` branch. This happens every time a pull request is merged to `main` (and the checks pass), making the release process continuous.
14+
. **Manual**: Via workflow dispatch in the GitHub Actions UI
15+
16+
== Artifacts Produced
17+
18+
Each release produces the following artifacts:
19+
20+
=== 1. Distribution Binaries
21+
22+
Built for multiple architectures (Linux, macOS, Windows) using `make dist`. These are uploaded to GitHub releases.
23+
24+
=== 2. Container Images
25+
26+
Container images are built and pushed to *two* registry organizations:
27+
28+
* `quay.io/conforma/cli`
29+
* `quay.io/enterprise-contract/ec-cli`
30+
31+
Each image is tagged with:
32+
33+
* `gh-<commit-sha>` - Unique identifier for the build
34+
* `<commit-sha>-<timestamp>` - Timestamped variant
35+
* `snapshot` - Rolling latest tag
36+
37+
=== 3. Tekton Task Bundles
38+
39+
OCI-compliant Tekton task bundles containing:
40+
41+
* `verify-enterprise-contract` task
42+
* `verify-conforma-konflux-ta` task
43+
44+
Published to *two* repositories:
45+
46+
* `quay.io/conforma/tekton-task`
47+
* `quay.io/enterprise-contract/ec-task-bundle`
48+
49+
Bundles are tagged with the same pattern as container images.
50+
51+
=== 4. GitHub Releases
52+
53+
Two releases are created simultaneously every time the workflow runs:
54+
55+
* **Rolling Release** (`snapshot` tag): Always updated to point to the latest successful build from `main`. The previous `snapshot` release is deleted and recreated.
56+
* **Versioned Release**: Created with an auto-generated semantic version tag (e.g., `v0.8.45`). Each versioned release is preserved, creating a historical record of all builds from `main`.
57+
58+
== Release Workflow Steps
59+
60+
The release workflow (`.github/workflows/release.yaml`) executes these steps:
61+
62+
. **Build Distribution**: Compile binaries for all supported platforms
63+
. **Build and Push Images**: Create container images with QEMU for multi-architecture support
64+
. **Verify Images**: Run verification tests to ensure images work correctly
65+
. **Create Tekton Bundles**: Package Tekton tasks with updated image references
66+
. **Deploy Statistics**: Generate and publish build statistics to GitHub Pages
67+
. **Create Releases**: Tag and create GitHub releases with distribution artifacts
68+
69+
== Dual Registry Strategy
70+
71+
The project publishes to two separate organizations for historical and organizational reasons:
72+
73+
* **`conforma/*`**: Primary organizational namespace
74+
* **`enterprise-contract/*`**: Legacy namespace maintained for backward compatibility
75+
76+
Both registries receive identical artifacts with identical tags, ensuring users can pull from either location.
77+
78+
== Image Verification
79+
80+
After images are pushed, the workflow verifies both images work correctly by running:
81+
82+
[source,bash]
83+
----
84+
make verify-image
85+
----
86+
87+
This ensures the `ec` CLI is functional within the container environment.
88+
89+
== Task Bundle Creation
90+
91+
Tekton task bundles are OCI artifacts that package the Tekton task definitions. The bundles are created by:
92+
93+
. **Reading the task definition files** from the repository:
94+
* `tasks/verify-enterprise-contract/0.1/verify-enterprise-contract.yaml`
95+
* `tasks/verify-conforma-konflux-ta/0.1/verify-conforma-konflux-ta.yaml`
96+
+
97+
NOTE: These files in the repository use `:latest` tags. They are NOT modified in the repository itself.
98+
99+
. **Dynamically updating image references** - During the release process, the workflow:
100+
* Reads these task YAML files (which use `:latest` tags)
101+
* Uses `yq` to dynamically replace all `.spec.steps[].image` fields with the specific image reference
102+
* Example transformation:
103+
+
104+
[source,yaml]
105+
----
106+
# What's stored in the repository (unchanged):
107+
spec:
108+
steps:
109+
- name: validate
110+
image: quay.io/conforma/cli:latest
111+
112+
# What gets packaged in the released bundle (using SHA256 digest):
113+
spec:
114+
steps:
115+
- name: validate
116+
image: quay.io/conforma/cli@sha256:a55110c6de8abe9c94b426084dff73669c3dfdd7c49a45f2339bb91ea2975bbe
117+
----
118+
+
119+
NOTE: The bundles use **digest references** (SHA256 content hashes), not tags. This provides the strongest immutability guarantee since the digest is computed from the actual image content.
120+
121+
. **Packaging and pushing** - The modified task definitions are bundled and pushed as OCI artifacts using `make task-bundle-snapshot`
122+
123+
**Important**: The task files in the repository always keep `:latest` tags. Only the published bundles contain specific digest references. This means each released bundle is immutable and always references the exact EC CLI image it was built with, ensuring reproducibility.
124+
125+
== Versioning
126+
127+
Version numbers are automatically derived using:
128+
129+
[source,bash]
130+
----
131+
source hack/derive-version.sh
132+
----
133+
134+
The script generates semantic versions based on git history and tags.
135+
136+
== Monitoring Releases
137+
138+
You can monitor releases through:
139+
140+
* **GitHub Actions**: View workflow runs at `.github/workflows/release.yaml`
141+
* **GitHub Releases**: Check https://github.com/conforma/cli/releases
142+
* **Container Registries**:
143+
** https://quay.io/repository/conforma/cli
144+
** https://quay.io/repository/enterprise-contract/ec-cli
145+
146+
== Manual Release
147+
148+
To trigger a manual release:
149+
150+
. Navigate to Actions → Release workflow
151+
. Click "Run workflow"
152+
. Select the `main` branch
153+
. Click "Run workflow" button
154+
155+
The release will proceed with the same steps as an automatic release.

‎docs/modules/ROOT/partials/main_nav.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@
22
* xref:configuration.adoc[Configuration]
33
* xref:policy_input.adoc[Policy Input]
44
* xref:signing.adoc[Signing]
5-
* xref:troubleshooting.adoc[Troubleshooting]
5+
* xref:troubleshooting.adoc[Troubleshooting]
6+
* xref:release-process.adoc[Release Process]

0 commit comments

Comments
 (0)