Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Releasing a New Version

This guide covers all the steps needed to release a new version of Corridor Quest to Codeberg, making it available to users via package managers and direct downloads.

Prerequisites

  • Push access to the Corridor Quest repositories on Codeberg
  • CODEBERG_TOKEN secret configured in each repository with write:repository and write:package permissions
  • All tests passing locally
  • All changes committed and pushed to main

Release Process

Step 1: Update Version Numbers

Update the version in Cargo.toml for each crate that has changes:

# cq/Cargo.toml
[package]
version = "X.Y.Z"

# cq-admin/Cargo.toml
[package]
version = "X.Y.Z"

# cq-server/Cargo.toml
[package]
version = "X.Y.Z"

# cq-common/Cargo.toml (if changed)
[package]
version = "X.Y.Z"

# cq-client/Cargo.toml (if changed)
[package]
version = "X.Y.Z"

Step 2: Update Changelog (Optional)

Update CHANGELOG.md in each crate with notable changes for this release.

Step 3: Update offline sqlx file

cd  /path/to/corridor-quest/cq-server
cargo sqlx prepare -- --all-targets --all-features

Step 4: Commit Version Changes

cd /path/to/corridor-quest
git add -A
git commit -m "Bump version to vX.Y.Z"
git push

Step 5: Create and Push the Tag

git tag vX.Y.Z
git push origin vX.Y.Z

This triggers the CI workflows automatically.

What Happens After Tagging

The CI workflows are designed to be fully automated and idempotent (safe to re-run).

Workflow Structure

Each release workflow (cq, cq-admin) follows this sequence:

  1. create-release job (runs first):

    • Checks if release exists for the tag
    • Creates release if it doesn't exist
    • Outputs release_id and version for other jobs

  2. Build jobs (run in parallel after create-release):

    • build-linux-arm64: Cross-compiles for ARM64
    • build-linux: Builds for x86_64 Linux
    • build-windows: Builds for Windows (cq only)
    • Each job:
      • Deletes any existing assets for its platform
      • Uploads new assets
      • Saves checksums as artifacts

  3. update-release-notes job (runs after all builds):

    • Collects all checksum artifacts
    • Updates release notes with complete checksum list

Artifacts Produced

For cq and cq-admin:

  • Linux x86_64 tarball + DEB + RPM
  • Linux arm64 tarball + DEB + RPM
  • Windows x86_64 zip (cq only)
  • SHA256 checksums in release notes

For cq-server:

  • Multi-arch container image (amd64 + arm64)
  • Tagged as both vX.Y.Z and latest

Package Registries Updated

  • Debian: apt installable packages
  • RPM: dnf installable packages
  • Generic: Tarballs with stable "latest" URLs

Re-releasing a Version

The workflows support re-releasing. Each platform's build job will:

  1. Delete its existing assets from the release
  2. Upload fresh assets
  3. Update checksums

To re-release:

# Delete local and remote tag
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

# Optionally delete the release via Codeberg web UI
# (not required - CI will reuse existing release)

# Re-create and push the tag
git tag vX.Y.Z
git push origin vX.Y.Z

Verifying the Release

After CI completes (usually 15-30 minutes), verify:

  1. Releases page: Check https://codeberg.org/corridor-quest/<repo>/releases

    • All expected assets should be listed
    • Release notes should have all checksums

  2. Container images:

    podman pull codeberg.org/corridor-quest/cq-server:vX.Y.Z

  3. Package registries:

    # Fedora/RHEL
dnf info cq

# Debian/Ubuntu
apt show cq

Troubleshooting

CI fails at "create-release" job

  • Check that CODEBERG_TOKEN secret is set in repository settings
  • Verify the token has write:repository and write:package permissions
  • Check the CI logs for the API response

Build jobs fail but create-release succeeded

  • The release exists, so you can re-push the tag to retry
  • Check specific build logs for compilation errors

Assets uploaded but checksums missing

  • The update-release-notes job may have failed
  • Check if all build jobs completed successfully
  • Checksums are collected via artifacts, so all builds must finish

Package registry returns 409

  • This is OK - means package already exists
  • For DEB/RPM registries, same version can't be overwritten (by design)

Container image build fails

  • Check that CODEBERG_USERNAME secret is set
  • Verify arm64 cross-compilation completed
  • Check buildah/podman logs

User Installation After Release

Once released, users can install via:

Linux (Fedora/RHEL)

dnf config-manager --add-repo https://codeberg.org/api/packages/corridor-quest/rpm/cq.repo
dnf install cq

Linux (Debian/Ubuntu)

echo "deb https://codeberg.org/api/packages/corridor-quest/debian bookworm main" | sudo tee /etc/apt/sources.list.d/corridor-quest.list
sudo apt update
sudo apt install cq

Container (cq-server)

podman pull codeberg.org/corridor-quest/cq-server:latest
# or specific version
podman pull codeberg.org/corridor-quest/cq-server:vX.Y.Z

Direct Download

Tarballs and packages are available at:

  • Releases: https://codeberg.org/corridor-quest/<repo>/releases
  • Latest: https://codeberg.org/api/packages/corridor-quest/generic/<pkg>/latest/