Switch CI deploy trigger to semver tags and document the release workflow #143

New Issue

marcel · 2026-03-28T10:32:06+01:00

marcel commented

2026-03-28 10:32:06 +01:00

Why

Without a defined deployment trigger, every push to main would deploy — including work-in-progress merges, dependency bumps, and minor fixes that aren't ready for users. We want deployment to be an explicit, intentional act.

Tag-based deployment gives us this cleanly:

Day-to-day development: feature branches → PR → main. Tests run, nothing deploys.
Ready to ship: push a semver tag. Tests run, images build, VPS updates.
Release history: every deployed version has a permanent git tag and (optionally) a Gitea release with notes.

This is simpler than maintaining a separate develop branch, which would require every feature to be merged twice and adds merge-conflict risk with no real benefit at this team size.

What to do

1. Ensure the CI workflow `on:` block has the tag trigger

The build-and-push and deploy jobs (added in #142) already gate on startsWith(gitea.ref, 'refs/tags/v'). The on: block at the top of .gitea/workflows/ci.yml must also declare tag pushes as a trigger:

on:
  push:           # runs tests on every branch push — no deploy
  pull_request:   # runs tests on every PR — no deploy
  push:
    tags:
      - 'v*'      # runs tests + build + deploy on semver tags

Note: in Gitea Actions YAML you can merge these into one push: block:

on:
  push:
    tags:
      - 'v*'
  push:           # branch pushes — tests only (jobs gated by if: condition)
  pull_request:

Or more explicitly, using separate entries — verify what Gitea Actions supports and test with a dry run.

2. Document the release process in CONTRIBUTING or DEPLOYMENT.md

Add a "Releasing a new version" section to DEPLOYMENT.md (created in #139):

## Releasing a new version

All work flows through feature branches and pull requests to `main`.
Tests run on every push. Nothing deploys until you create a release tag.

### When to tag

Tag when `main` is in a state you are happy to put in front of users.
There is no minimum number of features required — a tag can contain one fix.

### How to tag

\`\`\`bash
# Make sure you are on main and up to date
git checkout main && git pull

# Create and push a semver tag
git tag v1.2.3
git push origin v1.2.3
\`\`\`

Or create a release via the Gitea UI:
1. Go to the repo → Releases → New Release
2. Choose the tag name (e.g. `v1.2.3`) — Gitea creates the tag for you
3. Write a short changelog in the release notes
4. Publish — CI triggers automatically

### Versioning convention

Use [Semantic Versioning](https://semver.org):

| Change | Version bump | Example |
|---|---|---|
| Breaking change or major feature | MAJOR | `v1.0.0` → `v2.0.0` |
| New feature, backwards compatible | MINOR | `v1.0.0` → `v1.1.0` |
| Bug fix, patch, dependency update | PATCH | `v1.0.0` → `v1.0.1` |

For a family archive at this stage, most releases will be MINOR or PATCH.

### How to roll back

If a deploy causes problems, tag the last known-good commit:

\`\`\`bash
git tag v1.2.4 <sha-of-last-good-commit>
git push origin v1.2.4
\`\`\`

This triggers the full CI pipeline on the old code and redeploys it.
\`\`\`

3. Protect the `main` branch

In Gitea → repo settings → Branches → add a protection rule for main:

Require pull request before merging
Require status checks to pass (the three test jobs)
Disallow force pushes

This ensures main is always green and tags always point to tested code.

4. Verify CI behaviour with a dry-run tag

Before calling this done, push a test tag and confirm:

All three test jobs run
build-and-push runs after they pass
deploy runs after build-and-push
Pushing a branch (not a tag) only runs the three test jobs

Acceptance criteria

git push origin v0.1.0 triggers the full pipeline (tests → build → deploy) in Gitea Actions.
A branch push triggers only tests — no build or deploy jobs appear.
DEPLOYMENT.md contains a "Releasing a new version" section covering tagging, versioning convention, and rollback.
main branch has protection rules requiring passing CI before merge.

## Why Without a defined deployment trigger, every push to `main` would deploy — including work-in-progress merges, dependency bumps, and minor fixes that aren't ready for users. We want deployment to be an explicit, intentional act. Tag-based deployment gives us this cleanly: - Day-to-day development: feature branches → PR → `main`. Tests run, nothing deploys. - Ready to ship: push a semver tag. Tests run, images build, VPS updates. - Release history: every deployed version has a permanent git tag and (optionally) a Gitea release with notes. This is simpler than maintaining a separate `develop` branch, which would require every feature to be merged twice and adds merge-conflict risk with no real benefit at this team size. ## What to do ### 1. Ensure the CI workflow `on:` block has the tag trigger The `build-and-push` and `deploy` jobs (added in #142) already gate on `startsWith(gitea.ref, 'refs/tags/v')`. The `on:` block at the top of `.gitea/workflows/ci.yml` must also declare tag pushes as a trigger: ```yaml on: push: # runs tests on every branch push — no deploy pull_request: # runs tests on every PR — no deploy push: tags: - 'v*' # runs tests + build + deploy on semver tags ``` Note: in Gitea Actions YAML you can merge these into one `push:` block: ```yaml on: push: tags: - 'v*' push: # branch pushes — tests only (jobs gated by if: condition) pull_request: ``` Or more explicitly, using separate entries — verify what Gitea Actions supports and test with a dry run. ### 2. Document the release process in CONTRIBUTING or DEPLOYMENT.md Add a **"Releasing a new version"** section to `DEPLOYMENT.md` (created in #139): ```markdown ## Releasing a new version All work flows through feature branches and pull requests to `main`. Tests run on every push. Nothing deploys until you create a release tag. ### When to tag Tag when `main` is in a state you are happy to put in front of users. There is no minimum number of features required — a tag can contain one fix. ### How to tag \`\`\`bash # Make sure you are on main and up to date git checkout main && git pull # Create and push a semver tag git tag v1.2.3 git push origin v1.2.3 \`\`\` Or create a release via the Gitea UI: 1. Go to the repo → Releases → New Release 2. Choose the tag name (e.g. `v1.2.3`) — Gitea creates the tag for you 3. Write a short changelog in the release notes 4. Publish — CI triggers automatically ### Versioning convention Use [Semantic Versioning](https://semver.org): | Change | Version bump | Example | |---|---|---| | Breaking change or major feature | MAJOR | `v1.0.0` → `v2.0.0` | | New feature, backwards compatible | MINOR | `v1.0.0` → `v1.1.0` | | Bug fix, patch, dependency update | PATCH | `v1.0.0` → `v1.0.1` | For a family archive at this stage, most releases will be MINOR or PATCH. ### How to roll back If a deploy causes problems, tag the last known-good commit: \`\`\`bash git tag v1.2.4 <sha-of-last-good-commit> git push origin v1.2.4 \`\`\` This triggers the full CI pipeline on the old code and redeploys it. \`\`\` ``` ### 3. Protect the `main` branch In Gitea → repo settings → Branches → add a protection rule for `main`: - Require pull request before merging - Require status checks to pass (the three test jobs) - Disallow force pushes This ensures `main` is always green and tags always point to tested code. ### 4. Verify CI behaviour with a dry-run tag Before calling this done, push a test tag and confirm: - All three test jobs run - `build-and-push` runs after they pass - `deploy` runs after `build-and-push` - Pushing a branch (not a tag) only runs the three test jobs ## Acceptance criteria - `git push origin v0.1.0` triggers the full pipeline (tests → build → deploy) in Gitea Actions. - A branch push triggers only tests — no build or deploy jobs appear. - `DEPLOYMENT.md` contains a "Releasing a new version" section covering tagging, versioning convention, and rollback. - `main` branch has protection rules requiring passing CI before merge.

marcel added the devops phase-3: prod-compose labels 2026-03-28 10:46:52 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#143

Switch CI deploy trigger to semver tags and document the release workflow #143

Why