Merge pull request #1 from Relism/feature/ci-cd/setup

ci: setup CI/CD pipelines, versioning and agent guidelines
This commit is contained in:
Relism
2026-05-11 14:24:13 +02:00
committed by GitHub
22 changed files with 544 additions and 15 deletions
+17
View File
@@ -0,0 +1,17 @@
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/maven-1.0.0.xsd">
<servers>
<server>
<id>Personal</id>
<username>${env.MAVEN_USERNAME}</username>
<password>${env.MAVEN_PASSWORD}</password>
</server>
<server>
<id>Personal-snapshots</id>
<username>${env.MAVEN_USERNAME}</username>
<password>${env.MAVEN_PASSWORD}</password>
</server>
</servers>
</settings>
+47
View File
@@ -0,0 +1,47 @@
name: CI
on:
push:
branches:
- master
- 'feature/**'
- 'fix/**'
- 'hotfix/**'
tags-ignore:
- 'v*'
pull_request:
branches:
- master
jobs:
build:
name: Build & Test
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Temurin 21
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
server-id: Personal
server-username: MAVEN_USERNAME
server-password: MAVEN_PASSWORD
- name: Build and test
run: mvn -B --settings .github/settings.xml clean verify
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- name: Publish test results
uses: actions/upload-artifact@v4
if: always()
with:
name: test-results
path: '**/target/surefire-reports/*.xml'
retention-days: 7
+69
View File
@@ -0,0 +1,69 @@
name: Prepare Release
on:
workflow_dispatch:
inputs:
version:
description: 'Release version (e.g. 2.0.0)'
required: true
type: string
next_version:
description: 'Next development version without -SNAPSHOT (e.g. 2.1.0)'
required: true
type: string
jobs:
prepare:
name: Bump, Tag & Push
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout
uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
fetch-depth: 0
- name: Set up Temurin 21
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
- name: Configure Git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Set release version
run: mvn -B --settings .github/settings.xml versions:set -DnewVersion=${{ inputs.version }}
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- name: Commit release version
run: |
git add -A
git commit -m "chore(release): ${{ inputs.version }}"
- name: Tag release
run: git tag v${{ inputs.version }}
- name: Set next snapshot version
run: mvn -B --settings .github/settings.xml versions:set -DnewVersion=${{ inputs.next_version }}-SNAPSHOT
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- name: Commit next snapshot version
run: |
git add -A
git commit -m "chore(release): prepare ${{ inputs.next_version }}-SNAPSHOT"
- name: Push commits and tag
run: |
git push origin master
git push origin v${{ inputs.version }}
+136
View File
@@ -0,0 +1,136 @@
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
name: Build, Sign, Deploy & Publish
runs-on: ubuntu-latest
permissions:
contents: write
pages: write
id-token: write
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Extract version from tag
id: version
run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
- name: Set up Temurin 21
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
- name: Import GPG key
run: |
echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --batch --import
GPG_KEY_ID=$(gpg --list-secret-keys --with-colons | grep '^sec' | cut -d: -f5 | head -1)
echo "GPG_KEY_ID=$GPG_KEY_ID" >> $GITHUB_ENV
- name: Build, sign and deploy to releases
run: |
mvn -B --settings .github/settings.xml \
-DperformRelease=true \
-Dgpg.keyname=$GPG_KEY_ID \
clean deploy
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- name: Generate aggregated JavaDoc
run: |
mvn -B --settings .github/settings.xml \
-pl flash,flash-extensions -am \
javadoc:aggregate -DskipTests
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
- name: Checkout gh-pages
uses: actions/checkout@v4
with:
ref: gh-pages
path: gh-pages-out
token: ${{ secrets.GITHUB_TOKEN }}
- name: Copy JavaDoc to versioned folder
run: |
VERSION=${{ steps.version.outputs.VERSION }}
mkdir -p gh-pages-out/javadoc/$VERSION
cp -r target/reports/apidocs/. gh-pages-out/javadoc/$VERSION/
rm -rf gh-pages-out/latest
mkdir -p gh-pages-out/latest
cp -r target/reports/apidocs/. gh-pages-out/latest/
- name: Regenerate index.html
run: |
cd gh-pages-out
python3 - <<'EOF'
import os, re
versions = sorted(
[d for d in os.listdir("javadoc") if os.path.isdir(f"javadoc/{d}")],
key=lambda v: [int(x) for x in re.sub(r'[^0-9.]', '', v).split('.') if x],
reverse=True
)
rows = "\n".join(
f' <li><a href="javadoc/{v}/index.html">{v}</a></li>'
for v in versions
)
html = f"""<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Flash JavaDoc</title>
<style>
body {{ font-family: sans-serif; max-width: 600px; margin: 4rem auto; }}
h1 {{ font-size: 1.6rem; }}
ul {{ line-height: 2; }}
a {{ color: #0070f3; text-decoration: none; }}
a:hover {{ text-decoration: underline; }}
</style>
</head>
<body>
<h1>Flash — JavaDoc</h1>
<p><a href="latest/index.html">&#8594; Latest</a></p>
<h2>All versions</h2>
<ul>
{rows}
</ul>
</body>
</html>"""
with open("index.html", "w") as f:
f.write(html)
print(f"index.html generated with {len(versions)} versions: {versions}")
EOF
- name: Push gh-pages
run: |
cd gh-pages-out
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add -A
git diff --cached --quiet || git commit -m "docs(javadoc): release ${{ steps.version.outputs.VERSION }}"
git push origin gh-pages
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
tag_name: v${{ steps.version.outputs.VERSION }}
name: v${{ steps.version.outputs.VERSION }}
generate_release_notes: true
draft: false
prerelease: false
+30
View File
@@ -0,0 +1,30 @@
name: Publish Snapshot
on:
push:
branches:
- master
tags-ignore:
- 'v*'
jobs:
snapshot:
name: Deploy Snapshot
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Temurin 21
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
- name: Deploy snapshot
run: mvn -B --settings .github/settings.xml clean deploy -DskipTests
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+3
View File
@@ -1,4 +1,7 @@
target/ target/
*.versionsBackup
.mvn/timing.properties
*.class
!.mvn/wrapper/maven-wrapper.jar !.mvn/wrapper/maven-wrapper.jar
!**/src/main/**/target/ !**/src/main/**/target/
!**/src/test/**/target/ !**/src/test/**/target/
+118
View File
@@ -0,0 +1,118 @@
# Flash — Agent Guidelines
This document defines the conventions and rules that all agents (AI or human) must follow
when working on this repository. Read it entirely before making any change.
---
## Git Workflow
### Branch Naming
| Type | Pattern | Example |
|------|---------|---------|
| New feature | `feature/<scope>/<short-description>` | `feature/ext-oidc/pkce-support` |
| Bug fix | `fix/<scope>/<short-description>` | `fix/core/router-npe` |
| Hotfix on released version | `hotfix/<version>/<short-description>` | `hotfix/2.0.1/auth-bypass` |
| CI/infra changes | `feature/ci/<short-description>` | `feature/ci/add-snapshot-workflow` |
Rules:
- Always branch from `master`.
- Branch names are lowercase, words separated by `-`.
- Never push directly to `master`.
- Never create `develop`, `release/*`, or any other long-lived branch.
### Commit Messages — Conventional Commits
Format: `<type>(<scope>): <short description>`
| Type | When to use |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code change without feature/fix |
| `test` | Adding or updating tests |
| `docs` | Documentation only |
| `chore` | Build, deps, tooling — no production code |
| `ci` | Changes to GitHub Actions workflows |
Allowed scopes: `core`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-web-bundler`,
`ext-data-core`, `ext-data-jdbc`, `ext-data-hibernate`, `release`, `deps`, `ci`.
Examples:
```
feat(ext-oidc): add PKCE support
fix(core): fix NPE in RouteHandler when path is null
chore(deps): upgrade jackson to 2.18.0
ci: add timeout to snapshot workflow
chore(release): 2.1.0
```
### Pull Requests
- Every branch must be merged via PR, never with a direct push.
- PR title must follow Conventional Commits format.
- CI (`ci.yml`) must be green before merging.
- Squash merge is preferred for `feature/*` and `fix/*` to keep history clean.
- Merge commit is preferred for hotfixes (preserves the fix commit intact).
---
## Versioning
- All modules share a single version defined in the root `pom.xml` (`flash-parent`).
- Never change the version in child POMs — always and only in the parent.
- Current scheme: `MAJOR.MINOR.PATCH`
- MAJOR: breaking API changes
- MINOR: new backward-compatible features
- PATCH: backward-compatible bug fixes on an already-released version
- During development, master always carries a `-SNAPSHOT` version.
- **Never manually edit the version** — versions are bumped exclusively by the
`prepare-release` GitHub Actions workflow.
### Release Process (for maintainers only)
1. Ensure `master` is green (CI passing).
2. Go to GitHub Actions → `Prepare Release``Run workflow`.
3. Input `version` (e.g. `2.1.0`) and `next_version` (e.g. `2.2.0`).
4. The workflow handles everything: bump, commit, tag, push.
5. The `release` workflow then triggers automatically on the tag.
---
## Maven & Module Structure
- Root POM: `flash-parent` — defines all dependency versions and plugin config.
- `flash` module: the core framework JAR.
- `flash-extensions` POM: aggregator for all extension modules.
- Extensions live under `flash-extensions/flash-ext-*/`.
- When adding a new extension:
1. Add the module to `flash-extensions/pom.xml` `<modules>`.
2. Add the dependency to `flash-extensions/pom.xml` `<dependencyManagement>`.
3. Add the dependency to the root `pom.xml` `<dependencyManagement>`.
4. Do **not** declare a `<version>` in the new module's POM — it inherits from the parent.
---
## CI/CD Pipelines
| Workflow | Trigger | What it does |
|----------|---------|--------------|
| `ci.yml` | Push to any branch, PR to master | Compile + test — required gate |
| `snapshot.yml` | Push to `master` | Deploy `-SNAPSHOT` to `maven.relism.dev/snapshots` |
| `prepare-release.yml` | Manual `workflow_dispatch` | Bump version, commit, tag, push |
| `release.yml` | Push of tag `v*` | GPG sign, deploy to `/releases`, JavaDoc to GitHub Pages, GitHub Release |
**Agents must never manually trigger `prepare-release` or modify version strings.**
---
## What Agents Must NOT Do
- Push directly to `master` or `gh-pages`.
- Manually edit `<version>` tags in any POM.
- Add new `<repositories>` or `<distributionManagement>` entries without explicit instruction.
- Modify `.github/workflows/*.yml` files without explicit instruction.
- Commit generated files (`target/`, `*.class`, `*.versionsBackup`).
- Use `git push --force` on any branch.
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-data-core</artifactId> <artifactId>flash-ext-data-core</artifactId>
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-data-hibernate</artifactId> <artifactId>flash-ext-data-hibernate</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-data-jdbc</artifactId> <artifactId>flash-ext-data-jdbc</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-jackson</artifactId> <artifactId>flash-ext-jackson</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-limiter</artifactId> <artifactId>flash-ext-limiter</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-oidc</artifactId> <artifactId>flash-ext-oidc</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-openapi</artifactId> <artifactId>flash-ext-openapi</artifactId>
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-routeviewer</artifactId> <artifactId>flash-ext-routeviewer</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-view-core</artifactId> <artifactId>flash-ext-view-core</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-view-jte</artifactId> <artifactId>flash-ext-view-jte</artifactId>
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-view-thymeleaf</artifactId> <artifactId>flash-ext-view-thymeleaf</artifactId>
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-ext-web-bundler</artifactId> <artifactId>flash-ext-web-bundler</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-parent</artifactId> <artifactId>flash-parent</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash-extensions</artifactId> <artifactId>flash-extensions</artifactId>
+1 -1
View File
@@ -7,7 +7,7 @@
<parent> <parent>
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-parent</artifactId> <artifactId>flash-parent</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>flash</artifactId> <artifactId>flash</artifactId>
+110 -1
View File
@@ -6,7 +6,7 @@
<groupId>dev.relism</groupId> <groupId>dev.relism</groupId>
<artifactId>flash-parent</artifactId> <artifactId>flash-parent</artifactId>
<version>1.1-indev6</version> <version>2.0.0-SNAPSHOT</version>
<packaging>pom</packaging> <packaging>pom</packaging>
<modules> <modules>
@@ -19,6 +19,10 @@
<id>Personal</id> <id>Personal</id>
<url>https://maven.relism.dev/releases</url> <url>https://maven.relism.dev/releases</url>
</repository> </repository>
<snapshotRepository>
<id>Personal-snapshots</id>
<url>https://maven.relism.dev/snapshots</url>
</snapshotRepository>
</distributionManagement> </distributionManagement>
<properties> <properties>
@@ -27,6 +31,10 @@
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<lombok.version>1.18.44</lombok.version> <lombok.version>1.18.44</lombok.version>
<slf4j.version>2.0.16</slf4j.version> <slf4j.version>2.0.16</slf4j.version>
<maven.javadoc.plugin.version>3.11.2</maven.javadoc.plugin.version>
<maven.source.plugin.version>3.3.1</maven.source.plugin.version>
<maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
<maven.versions.plugin.version>2.18.0</maven.versions.plugin.version>
</properties> </properties>
<repositories> <repositories>
@@ -141,8 +149,109 @@
</annotationProcessorPaths> </annotationProcessorPaths>
</configuration> </configuration>
</plugin> </plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>${maven.source.plugin.version}</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven.javadoc.plugin.version}</version>
<configuration>
<source>${maven.compiler.source}</source>
<encoding>${project.build.sourceEncoding}</encoding>
<doclint>none</doclint>
<failOnError>true</failOnError>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>${maven.gpg.plugin.version}</version>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>versions-maven-plugin</artifactId>
<version>${maven.versions.plugin.version}</version>
<configuration>
<generateBackupPoms>false</generateBackupPoms>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-deploy-plugin</artifactId>
<version>3.1.2</version>
</plugin>
</plugins> </plugins>
</pluginManagement> </pluginManagement>
</build> </build>
<profiles>
<profile>
<id>attach-artifacts</id>
<activation>
<file>
<exists>src/main/java</exists>
</file>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<phase>verify</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>sign-artifacts</id>
<activation>
<property>
<name>performRelease</name>
<value>true</value>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project> </project>