Skip to content

Commit c6b1e97

Browse files
devopsmattdevopsmatt
committed
fix: resolve CHANGELOG.md merge conflict
2 parents ad05a4b + 57b09a8 commit c6b1e97

File tree

1 file changed

+123
-45
lines changed

1 file changed

+123
-45
lines changed

‎.github/workflows/README.md‎

Lines changed: 123 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,72 @@
22

33
## Overview
44

5-
This directory contains GitHub Actions workflows for automated building, testing, security scanning, and publishing of the FHIR Converter library.
5+
This directory contains GitHub Actions workflows for automated versioning, building, testing, security scanning, and publishing of the FHIR Converter library.
66

77
## Workflows
88

9-
### `build-and-publish.yml` - Main CI/CD Pipeline
9+
### `auto-version.yml` - Automatic Versioning on PR Merge
1010

11-
**Purpose**: Complete DevSecOps pipeline for building, testing, securing, and optionally publishing versioned releases.
11+
**Purpose**: Automatically versions and tags every PR merged to `main`, then triggers the build-and-publish pipeline.
1212

13-
**Trigger**: Manual (`workflow_dispatch`)
13+
**Trigger**: Automatic on PR merge to `main` (`pull_request: types: [closed]`)
14+
15+
**Behavior**:
16+
17+
- **Default (no tag on PR branch)**: Bumps the patch version of the latest semver tag on `main` (e.g., v1.2.3 -> v1.2.4)
18+
- **Custom version (tag on PR branch)**: If the PR author created a semver git tag on their branch (e.g., `v2.0.0`), that version is used instead
19+
- **CHANGELOG**: When a PR has a version tag, the CHANGELOG is updated with the PR title and body
20+
- **Build trigger**: After tagging, dispatches `build-and-publish.yml` with `publish=true`
21+
22+
**How to use as a contributor**:
23+
24+
For most PRs, nothing special is needed. The patch version bumps automatically.
25+
26+
For new features or breaking changes, tag your branch before merging:
27+
28+
```bash
29+
git tag v1.3.0
30+
git push origin v1.3.0
31+
```
32+
33+
See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
34+
35+
**Secrets required**:
36+
37+
- `RELEASE_TOKEN`: Classic PAT with `repo` + `workflow` scopes. Used to push to the protected `main` branch and trigger downstream workflows.
38+
39+
**Flow**:
40+
41+
```
42+
PR merged to main
43+
|
44+
v
45+
Get latest semver tag from main (e.g., v1.2.3)
46+
|
47+
v
48+
Check PR branch commits for version tags
49+
|
50+
+-- No tag found --> bump patch (v1.2.4)
51+
|
52+
+-- Tag found (e.g., v2.0.0) --> use that version
53+
|
54+
v
55+
Update CHANGELOG.md with PR title + body
56+
|
57+
v
58+
Create and push new tag on main
59+
|
60+
v
61+
Trigger build-and-publish.yml (version=X.Y.Z, publish=true)
62+
```
63+
64+
---
65+
66+
### `build-and-publish.yml` - Build, Test, Scan & Publish Pipeline
67+
68+
**Purpose**: Complete DevSecOps pipeline for building, testing, securing, and optionally publishing versioned releases. Typically triggered automatically by `auto-version.yml`, but can also be run manually.
69+
70+
**Trigger**: Manual (`workflow_dispatch`) or dispatched by `auto-version.yml`
1471

1572
**Inputs**:
1673

@@ -21,48 +78,48 @@ This directory contains GitHub Actions workflows for automated building, testing
2178

2279
## Pipeline Architecture
2380

24-
```ascii
25-
┌─────────────────────────────────────────────────────────────────┐
26-
│ Stage 0: Validation │
27-
│ ✓ Validate semantic version format │
28-
│ ✓ Check for version uniqueness (no existing tags) │
29-
└─────────────────────────────────────────────────────────────────┘
81+
```
82+
+-------------------------------------------------------------------+
83+
| Stage 0: Validation |
84+
| * Validate semantic version format |
85+
| * Check for version uniqueness (no existing tags) |
86+
+-------------------------------------------------------------------+
3087
|
31-
┌─────────────────────────┴────────────────────────┐
32-
│ │
33-
┌───┴────────────────────────┐ ┌────────────────────┴──────┐
34-
│ Stage 1a: Build │ │ Stage 1b: Repo Security │
35-
│ ✓ Kotlin linting (ktlint) │ │ ✓ Trivy config scan │
36-
│ ✓ Compile with version │ │ ✓ Secrets detection │
37-
│ ✓ Create Main JAR │ │ ✓ IaC misconfiguration │
38-
│ ✓ Create Shadow JAR │ └───────────────────────────┘
39-
└─────────────┬──────────────┘
40-
|
41-
┌─────────┴──────────────────────────────────┐
42-
│ │
43-
┌───┴──────────────────┐ ┌──────────────────────┴────────┐
44-
│ Stage 2a: Test │ │ Stage 2b: Security Scans │
45-
│ ✓ JUnit 5 tests │ │ ✓ Dependency CVE scan (Trivy) │
46-
│ ✓ JaCoCo coverage │ │ ✓ Artifact JAR scan (Trivy) │
47-
└──────────────────────┘ └───────────────────────────────┘
88+
+-------------------------+----------------------------+
89+
| |
90+
+---+----------------------------+ +--------------------+------+
91+
| Stage 1a: Build | | Stage 1b: Repo Security |
92+
| * Kotlin linting (ktlint) | | * Trivy config scan |
93+
| * Compile with version | | * Secrets detection |
94+
| * Create Main JAR | | * IaC misconfiguration |
95+
| * Create Shadow JAR | +---------------------------+
96+
+-------------+------------------+
4897
|
49-
| (if publish=true)
50-
v
51-
┌─────────────────────────────────────────────────────────────────┐
52-
│ Stage 2c: CodeQL SAST (release builds only) │
53-
│ ✓ Source code security analysis │
54-
│ ✓ Security-only queries │
55-
└─────────────┬───────────────────────────────────────────────────┘
98+
+---------+------------------------------------------+
99+
| |
100+
+---+----------------------+ +--------- ----------------+--------+
101+
| Stage 2a: Test | | Stage 2b: Security Scans |
102+
| * JUnit 5 tests | | * Dependency CVE scan (Trivy) |
103+
| * JaCoCo coverage | | * Artifact JAR scan (Trivy) |
104+
+---+----------------------+ +--------------------------------- -+
105+
|
106+
| (if publish=true)
107+
v
108+
+-------------------------------------------------------------------+
109+
| Stage 2c: CodeQL SAST (release builds only) |
110+
| * Source code security analysis |
111+
| * Security-only queries |
112+
+-------------+-----------------------------------------------------+
56113
|
57-
┌─────────┴──────────────────┐
58-
│ │
59-
┌───┴────────────────┐ ┌────────┴───────────┐
60-
│ Stage 3a: Publish │ │ Stage 3b: Summary │
61-
│ (if enabled) │ │ ✓ Execution report │
62-
│ ✓ Create release │ │ ✓ Stage statuses │
63-
│ ✓ Attach JARs │ └────────────────────┘
64-
│ ✓ Generate notes │
65-
└────────────────────┘
114+
+---------+--------------------------+
115+
| |
116+
+---+--------------------+ +------------+-----------+
117+
| Stage 3a: Publish | | Stage 3b: Summary |
118+
| (if enabled) | | * Execution report |
119+
| * Create release | | * Stage statuses |
120+
| * Attach JARs | +------------------------+
121+
| * Generate notes |
122+
+------------------------+
66123
67124
Note: All security scan results remain private (workflow logs only)
68125
```
@@ -385,6 +442,27 @@ git push origin :refs/tags/v1.0.0
385442
- Verify all build, test, and security scans passed
386443
- Check workflow summary for failed jobs
387444

445+
#### [ERROR] Auto-version failed to push tag or CHANGELOG
446+
447+
**Problem**: The `RELEASE_TOKEN` secret is missing, expired, or lacks permissions
448+
449+
**Solution**:
450+
451+
1. Verify the `RELEASE_TOKEN` secret exists in repo Settings > Secrets
452+
2. Ensure the Classic PAT has `repo` and `workflow` scopes
453+
3. Check that the PAT has not expired
454+
4. Verify the PAT owner has push access to the `main` branch
455+
456+
#### [ERROR] "Tag already exists" in auto-version
457+
458+
**Problem**: The calculated version tag already exists (e.g., a concurrent merge)
459+
460+
**Solution**:
461+
462+
1. Check existing tags: `git tag -l`
463+
2. If the tag was created by a prior run, the next merge will increment past it
464+
3. If a PR branch tag conflicts with an existing tag, use a different version
465+
388466
---
389467

390468
## Maintenance
@@ -417,7 +495,7 @@ Renovate is configured to automatically update dependencies with the following f
417495

418496
**Dashboard**:
419497

420-
- View all pending updates: Issues tab → "Renovate Dependency Dashboard"
498+
- View all pending updates: Issues tab > "Renovate Dependency Dashboard"
421499
- See PRs before they're created
422500
- Control update scheduling per dependency
423501

@@ -427,7 +505,7 @@ Renovate is configured to automatically update dependencies with the following f
427505

428506
Recommended repository settings:
429507

430-
### Branch Protection Rules (master)
508+
### Branch Protection Rules (main)
431509

432510
- [x] Require pull request before merging
433511
- [x] Require status checks to pass

0 commit comments

Comments
 (0)