---
type: User Story
title: Build and publish versioned releases
description: Gitea Actions validate every change and publish semantically versioned Velocity and container artifacts.
tags: [operations, ci, release, velocity, docker]
timestamp: 2026-08-01T20:05:49Z
story_id: US-016
status: verified
---

# User Story

As a platform operator, I want automated validation and semantic releases, so that deployable web, migration, and Velocity artifacts are reproducible and downloadable.

# Acceptance Criteria

- [x] Pushes and pull requests run OKF validation, linting, type checks, tests, the web build, and the Velocity build.
- [x] Pull requests validate conventional commit messages.
- [x] CI uploads the development Velocity JAR as a workflow artifact.
- [x] Main-branch conventional commits determine the next semantic version and create a `vMAJOR.MINOR.PATCH` tag.
- [x] A release build embeds the semantic version in the Velocity plugin and JAR filename.
- [x] A public Gitea release exposes the versioned Velocity JAR as a downloadable asset.
- [x] Releases publish semantically versioned web runtime images to the Gitea registry.
- [x] Releases publish semantically versioned Discord bot images to the Gitea registry.
- [x] Releases publish semantically versioned migration images that run versioned Drizzle migrations.
- [x] Releases do not publish mutable container tags such as `latest`.
- [x] Runtime containers use unprivileged users and exclude development source and secrets where practical.
- [x] Operators are told which repository secrets must be configured before the first push.

# Implementation

- [CI workflow](../.gitea/workflows/ci.yml)
- [Release workflow](../.gitea/workflows/release.yml)
- [Semantic Release configuration](../.releaserc)
- [Web and migration Docker targets](../Dockerfile)
- [Velocity Gradle build](../plugins/velocity/build.gradle.kts)
- [Release and deployment guide](../docs/releases.md)

# Validation

Local OKF, lint, typecheck, test, Next.js build, and versioned Velocity JAR checks pass. Initial Gitea CI and release runs succeeded. Release `v1.0.0` provides a publicly downloadable JAR whose Velocity metadata reports `1.0.0`. Registry manifests were resolved for the published semantic-version tags. Release `v1.1.0` also publishes resolvable versioned web, Discord bot, and migration manifests and a public Velocity JAR whose metadata reports `1.1.0`. Release `v1.1.1` published immutable semantic-version tags only; prior `latest` digests remained unchanged. Pull-request commitlint configuration is present; its conditional execution will be exercised by the first pull request.

# Related Stories

- [Deploy and operate securely](us-015-platform-operations.md)
- [Velocity game admission](us-009-velocity-admission.md)