# 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