Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 35 additions & 18 deletions docs/RELEASE_PROCESS.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,38 @@
## 🚦 Release Gate & Tag Cleanup
## 🚦 Release Process

This project uses a single-branch flow (`main` → tag → publish). Pushing a version tag triggers a CI workflow that **pauses for manual verification** before building Docker images or publishing assets.
This project uses a **controlled-release** workflow. Releases are triggered manually from the GitHub Actions UI by selecting a source branch and entering a version number. The workflow creates a draft release, opens a verification issue, and pauses for manual approval before building Docker images and publishing assets.

## How to Start a Release

1. Navigate to **Actions** in your repository.
2. In the left sidebar, click the **controlled-release** workflow.
3. Click **Run workflow** (drop‑down button on the right).
4. Choose the **source branch** (usually `main`).
5. Enter the **version** (e.g., `3.5.1` – without the leading `v`).
6. Click **Run workflow**.

The workflow will:
- Create a Git tag matching the version you supplied (e.g., `v3.5.1`).
- Build the project’s JAR.
- Create a draft GitHub Release with auto‑generated release notes.
- Create a **verification issue** whose title matches the version number.
- Pause at the `release-gate` environment, waiting for manual approval.

## How to Approve the Release

Once you push a version tag (e.g., `v4.2.0`), the release workflow automatically pauses at the `release-gate` environment and waits for manual verification. Follow these steps to approve and continue the build:
Once the workflow pauses, you must manually verify the build and approve the deployment to continue.

### 1. Complete Manual Verification
- Run the application locally or on a test instance using Docker Compose
- Walk through the verification checklist (auth flows, map/tiles, live mode, import pipeline, multi-user isolation, i18n/units, etc.)
- Update the auto-created GitHub issue titled with the version number with your findings or confirm all checklist items are completed
- Walk through the verification checklist (auth flows, map/tiles, live mode, import pipeline, multiuser isolation, i18n/units, etc.)
- Update the autocreated verification issue with your findings or confirm all checklist items are completed
- Do not approve until all critical paths are verified

### 2. Approve via GitHub UI (Recommended)
1. Navigate to **Actions** in your repository
2. Click the pending workflow run named `release / Build Release` triggered by your tag
2. Click the pending workflow run named `controlled-release / Build Release`
3. In the workflow summary, locate the job that shows `Waiting`
4. Click **Review deployments** in the top-right corner
4. Click **Review deployments** in the topright corner
5. Select **Approve and deploy**
6. Optionally add a comment (e.g., `Checklist verified, all systems nominal.`) and confirm
7. The workflow will immediately resume from where it paused
Expand All @@ -32,18 +48,18 @@ gh run approve "$RUN_ID"
```
Note: Your GitHub account must be listed as a required reviewer for the `release-gate` environment for CLI approval to succeed.

### What Happens After Approval
- The workflow resumes, builds the JAR, pushes multi-arch Docker images to Docker Hub and GHCR, and publishes the GitHub Release
- The verification issue is automatically closed with a success comment linking to the workflow run
- Check the **Actions** tab to confirm all steps completed successfully
- You can now share the release notes and notify users
## What Happens After Approval
- The workflow resumes, pushes multiarch Docker images to Docker Hub and GHCR, and publishes the GitHub Release.
- The verification issue is automatically closed with a success comment linking to the workflow run.
- Check the **Actions** tab to confirm all steps completed successfully.
- You can now share the release notes and notify users.

### Environment Management
- Add or remove approvers: `Settings -> Environments -> release-gate -> Required reviewers`
- Enable `Prevent self-approval` in the same menu if you require a second maintainer to verify
## Environment Management
- Add or remove approvers: `Settings Environments release-gate Required reviewers`
- Enable `Prevent selfapproval` in the same menu if you require a second maintainer to verify
- Approvals are tied to the environment, not individual runs, so permissions persist across releases

### What happens if I don't approve?
## What happens if I don't approve?
- The workflow stays in a `Waiting` state.
- **The tag is NOT deleted automatically.** Git tags are permanent references.
- If you decide to abort the release, you must cancel the workflow run and delete the tag manually:
Expand All @@ -53,5 +69,6 @@ Note: Your GitHub account must be listed as a required reviewer for the `release
gh run cancel <run-id>

# Delete the tag locally & remotely
git tag -d v4.2.0
git push origin --delete v4.2.0
git tag -d v3.5.1
git push origin --delete v3.5.1
```
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.14</version>
<version>3.5.15</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.dedicatedcode</groupId>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@
import java.time.LocalDate;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

Expand Down
Loading