docs: add ADR-0015 for CI notifications and semantic versioning

2026-02-02 08:00:18 -05:00
parent 730ab32b5d
commit a2a426eb3b
1 changed files with 146 additions and 0 deletions
--- a/decisions/0015-ci-notifications-and-semantic-versioning.md
+++ b/decisions/0015-ci-notifications-and-semantic-versioning.md
@@ -0,0 +1,146 @@
+# ADR-0015: CI Notifications and Semantic Versioning
+
+## Status
+
+Accepted
+
+## Date
+
+2026-02-02
+
+## Context
+
+With Gitea Actions now handling CI/CD for our repositories (ADR-0013), we need:
+
+1. **Visibility** - Notifications when pipelines pass or fail
+2. **Versioning** - Consistent, automated semantic versioning for releases
+3. **Traceability** - Clear version tags linked to commits
+
+We already have ntfy deployed for push notifications (used by alertmanager and Gatus).
+
+## Decision
+
+### 1. CI Notifications via ntfy
+
+All CI workflows send notifications to `ntfy` on pipeline completion:
+
+```yaml
+env:
+  NTFY_URL: http://ntfy.observability.svc.cluster.local:80
+
+notify:
+  name: Notify
+  runs-on: ubuntu-latest
+  needs: [lint, test]
+  if: always()
+  steps:
+    - name: Notify on success
+      if: needs.lint.result == 'success' && needs.test.result == 'success'
+      run: |
+        curl -s \
+          -H "Title: ✅ CI Passed: ${{ gitea.repository }}" \
+          -H "Priority: default" \
+          -H "Tags: white_check_mark,github" \
+          -H "Click: ${{ gitea.server_url }}/${{ gitea.repository }}/actions/runs/${{ gitea.run_id }}" \
+          -d "Branch: ${{ gitea.ref_name }}" \
+          ${{ env.NTFY_URL }}/gitea-ci
+
+    - name: Notify on failure
+      if: needs.lint.result == 'failure' || needs.test.result == 'failure'
+      run: |
+        curl -s \
+          -H "Title: ❌ CI Failed: ${{ gitea.repository }}" \
+          -H "Priority: high" \
+          -H "Tags: x,github" \
+          -d "..." \
+          ${{ env.NTFY_URL }}/gitea-ci
+```
+
+**Topic**: `gitea-ci` (subscribe at `ntfy.daviestechlabs.io/gitea-ci`)
+
+### 2. Semantic Versioning
+
+Version bumps are determined by commit message keywords:
+
+| Keyword in Commit | Version Bump | Example |
+|-------------------|--------------|---------|
+| `major:` or `BREAKING CHANGE` | Major (1.0.0 → 2.0.0) | `major: redesign API` |
+| `minor:` or `feat:` | Minor (1.0.0 → 1.1.0) | `feat: add streaming` |
+| `fix:`, `patch:`, or other | Patch (1.0.0 → 1.0.1) | `fix: null pointer` |
+
+Implementation in workflow:
+
+```yaml
+release:
+  name: Release
+  runs-on: ubuntu-latest
+  needs: [lint, test]
+  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Determine version bump
+      id: version
+      run: |
+        # Get latest tag or default to v0.0.0
+        LATEST=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+        VERSION=${LATEST#v}
+        IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+        
+        # Check commit message for keywords
+        MSG="${{ github.event.head_commit.message }}"
+        if echo "$MSG" | grep -qiE "^major:|BREAKING CHANGE"; then
+          MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0
+        elif echo "$MSG" | grep -qiE "^(minor:|feat:)"; then
+          MINOR=$((MINOR + 1)); PATCH=0
+        else
+          PATCH=$((PATCH + 1))
+        fi
+        
+        NEW_VERSION="v${MAJOR}.${MINOR}.${PATCH}"
+        echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+        echo "Bumping $LATEST → $NEW_VERSION"
+
+    - name: Create tag
+      run: |
+        git config user.name "gitea-actions[bot]"
+        git config user.email "actions@git.daviestechlabs.io"
+        git tag -a ${{ steps.version.outputs.version }} -m "Release ${{ steps.version.outputs.version }}"
+        git push origin ${{ steps.version.outputs.version }}
+
+    - name: Create release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: ${{ steps.version.outputs.version }}
+        generate_release_notes: true
+```
+
+### 3. Topic Structure
+
+| Topic | Purpose |
+|-------|---------|
+| `gitea-ci` | All CI pipeline notifications |
+| `gitea-releases` | New version releases (optional) |
+
+## Consequences
+
+### Positive
+
+- **Immediate visibility** - Know instantly when builds fail
+- **Consistent versioning** - No manual version management
+- **Audit trail** - Git tags link versions to commits
+- **Low friction** - Developers just use conventional commit prefixes
+
+### Negative
+
+- **Commit message discipline** - Requires consistent prefixes
+- **ntfy dependency** - Notifications require ntfy to be running
+- **Tag pollution** - Every main push creates a tag (can skip with `[skip ci]`)
+
+## Related ADRs
+
+- [ADR-0013](0013-gitea-actions-for-ci.md) - Gitea Actions CI/CD
+- [ADR-0014](0014-docker-build-best-practices.md) - Docker best practices