Skip to content

Commit 5c6d15a

Browse files
dheerajodhadheerajodha
authored
Merge pull request #3021 from dheerajodha/EC-1477
docs: Describe the Release process for EC CLI
2 parents c9431a2 + 9beed65 commit 5c6d15a

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` - Primary registry
29+
* `quay.io/enterprise-contract/ec-cli` - Deprecated (see note below)
30+
31+
IMPORTANT: The `quay.io/enterprise-contract/ec-cli` registry is deprecated and maintained only for backward compatibility. It will stop receiving updates in the future. Use `quay.io/conforma/cli` for all new deployments.
32+
33+
Each image is tagged with:
34+
35+
* `gh-<commit-sha>` - Unique identifier for the build
36+
* `<commit-sha>-<timestamp>` - Timestamped variant
37+
* `snapshot` - Rolling latest tag
38+
39+
=== 3. Tekton Task Bundles
40+
41+
OCI-compliant Tekton task bundles containing:
42+
43+
* `verify-enterprise-contract` task
44+
* `verify-conforma-konflux-ta` task
45+
46+
Published to *two* repositories:
47+
48+
* `quay.io/conforma/tekton-task` - Primary repository
49+
* `quay.io/enterprise-contract/ec-task-bundle` - Deprecated (see note below)
50+
51+
IMPORTANT: The `quay.io/enterprise-contract/ec-task-bundle` repository is deprecated and maintained only for backward compatibility. It will stop receiving updates in the future. Use `quay.io/conforma/tekton-task` for all new deployments.
52+
53+
Bundles are tagged with the same pattern as container images.
54+
55+
=== 4. GitHub Releases
56+
57+
Two releases are created simultaneously every time the workflow runs:
58+
59+
* **Rolling Release** (`snapshot` tag): Always updated to point to the latest successful build from `main`. The previous `snapshot` release is deleted and recreated.
60+
* **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`.
61+
62+
== Release Workflow Steps
63+
64+
The release workflow (`.github/workflows/release.yaml`) executes these steps:
65+
66+
. **Build Distribution**: Compile binaries for all supported platforms
67+
. **Build and Push Images**: Create container images with QEMU for multi-architecture support
68+
. **Verify Images**: Run verification tests to ensure images work correctly
69+
. **Create Tekton Bundles**: Package Tekton tasks with updated image references
70+
. **Deploy Statistics**: Generate and publish build statistics to GitHub Pages
71+
. **Create Releases**: Tag and create GitHub releases with distribution artifacts
72+
73+
== Dual Registry Strategy
74+
75+
The project publishes to two separate organizations for historical and organizational reasons:
76+
77+
* **`conforma/*`**: Primary organizational namespace
78+
* **`enterprise-contract/*`**: Legacy namespace (deprecated)
79+
80+
Both registries currently receive identical artifacts with identical tags. However, the `enterprise-contract/*` namespace is deprecated and will eventually stop receiving updates.
81+
82+
== Image Verification
83+
84+
After images are pushed, the workflow verifies both images work correctly by running:
85+
86+
[source,bash]
87+
----
88+
make verify-image
89+
----
90+
91+
This ensures the `ec` CLI is functional within the container environment.
92+
93+
== Task Bundle Creation
94+
95+
Tekton task bundles are OCI artifacts that package the Tekton task definitions. The bundles are created by:
96+
97+
. **Reading the task definition files** from the repository:
98+
* `tasks/verify-enterprise-contract/0.1/verify-enterprise-contract.yaml`
99+
* `tasks/verify-conforma-konflux-ta/0.1/verify-conforma-konflux-ta.yaml`
100+
101+
. **Dynamically updating image references** - During the release process, the workflow:
102+
* Reads these task YAML files (which use `:latest` tags)
103+
* Uses `yq` to dynamically replace all `.spec.steps[].image` fields with specific image digests
104+
* Example transformation:
105+
+
106+
[source,yaml]
107+
----
108+
# What's stored in the repository (unchanged):
109+
spec:
110+
steps:
111+
- name: validate
112+
image: quay.io/conforma/cli:latest
113+
114+
# What gets packaged in the released bundle (pinned to digest):
115+
spec:
116+
steps:
117+
- name: validate
118+
image: quay.io/conforma/cli@sha256:a55110c6de8abe9c94b426084dff73669c3dfdd7c49a45f2339bb91ea2975bbe
119+
----
120+
121+
. **Packaging and pushing** - The modified task definitions are bundled and pushed as OCI artifacts using `make task-bundle-snapshot`.
122+
123+
NOTE: The task files in the repository use `:latest` tags, but when the bundles are created and pushed, the image references are pinned to specific image digests (SHA256 content hashes). The repository files are never modified. This ensures each released bundle is immutable and always references the exact EC CLI image it was built with.
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:release-process.adoc[Release Process]
6+
* xref:troubleshooting.adoc[Troubleshooting]

0 commit comments

Comments
 (0)