gitchegumi/GitchAlerts

Watch

Fork 0

Implement release versioning, container tags, and dashboard update status #41

New issue

Closed

opened 2026-06-03 20:58:30 -05:00 by Gitchegumi · 0 comments

Gitchegumi commented

2026-06-03 20:58:30 -05:00

(Migrated from github.com)

Problem

GitchAlerts is reaching the point where releases need to be published intentionally instead of relying on random GitHub-generated image hashes/tags. Operators need understandable version numbers for releases and containers, and the dashboard should show what version is currently deployed.

Desired direction

Use best practices for release and container versioning while keeping the versioning understandable for self-hosted users.

Preferred model:

The repository/application has a top-level release version.
Each deployable container/service can maintain its own understandable version number.
A release increments whenever any container changes.
Container image tags should be human-readable and traceable, not only random hashes.
The dashboard should display the currently deployed version.
The dashboard should notify the user when a newer release exists in the repo.

Proposed versioning model

Use SemVer-style release tags for the overall project:

v0.1.0
v0.1.1
v0.2.0
v1.0.0

Use service-specific image tags that include both the release version and service identity, for example:

ghcr.io/gitchegumi/gitchalerts-web:v0.2.0
ghcr.io/gitchegumi/gitchalerts-ingress:v0.2.0
ghcr.io/gitchegumi/gitchalerts-worker:v0.2.0

If service-level versions are maintained independently, expose them explicitly as metadata while still tagging release images with the project release version:

Project release: v0.2.0
web service version: 0.4.0
ingress service version: 0.2.1
worker service version: 0.1.3

The image labels should include both:

org.opencontainers.image.version=v0.2.0
org.opencontainers.image.revision=<git-sha>
org.opencontainers.image.source=https://github.com/Gitchegumi/multi-stream-alerts
org.opencontainers.image.title=gitchalerts-web
org.opencontainers.image.description=<service description>

Required implementation

Define the release/versioning strategy in the repo documentation.
Add a single source of truth for the project release version.
Add a clear source of truth for per-service/container versions if service versions are maintained independently.
Update Docker image build/publish workflow to tag images with readable version tags.
Preserve immutable traceability by also tagging or labeling images with the commit SHA.
Add OCI-compliant image labels to all containers.
Make Docker Compose examples reference readable version tags rather than random hashes.
Add release automation or documented release steps for:
- version bump,
- changelog/release notes,
- Git tag creation,
- container build and publish,
- GitHub release publication.
Add dashboard/API support to expose the currently deployed version.
Add dashboard support to check the latest release in the GitHub repo and notify the user when an update is available.

Dashboard requirements

The dashboard should show:

Current project release version.
Current commit SHA or short SHA.
Per-service version/build metadata if available.
Whether a newer GitHub release is available.
Link to the latest release notes.

The update check should be safe for self-hosted deployments:

Do not require authentication to GitHub for public release checks.
Fail quietly if GitHub is unavailable.
Do not block dashboard loading if update check fails.
Cache update-check results to avoid unnecessary GitHub API calls.
Provide a way to disable update checks for offline/private deployments, for example:

UPDATE_CHECK_ENABLED=true
UPDATE_CHECK_REPO=Gitchegumi/multi-stream-alerts

Acceptance criteria

GitHub releases can be published with SemVer tags.
Container images are published with readable tags tied to releases.
Containers also include immutable commit SHA metadata.
Each service/container can expose its own version metadata if implemented.
The dashboard displays the currently deployed version.
The dashboard warns when a newer GitHub release exists.
Docker Compose examples use understandable image tags.
Release process is documented well enough for maintainers and self-hosters.

Notes

Do not rely only on latest. It is fine to publish latest as a convenience tag, but self-hosted users should be encouraged to pin stable release tags.

A good tagging set for each release would be something like:

v0.2.0
0.2.0
sha-<shortsha>
latest

The release tag should be the recommended production/self-hosted deployment tag. The SHA tag should be used for debugging and traceability.

## Problem GitchAlerts is reaching the point where releases need to be published intentionally instead of relying on random GitHub-generated image hashes/tags. Operators need understandable version numbers for releases and containers, and the dashboard should show what version is currently deployed. ## Desired direction Use best practices for release and container versioning while keeping the versioning understandable for self-hosted users. Preferred model: - The repository/application has a top-level release version. - Each deployable container/service can maintain its own understandable version number. - A release increments whenever any container changes. - Container image tags should be human-readable and traceable, not only random hashes. - The dashboard should display the currently deployed version. - The dashboard should notify the user when a newer release exists in the repo. ## Proposed versioning model Use SemVer-style release tags for the overall project: ```text v0.1.0 v0.1.1 v0.2.0 v1.0.0 ``` Use service-specific image tags that include both the release version and service identity, for example: ```text ghcr.io/gitchegumi/gitchalerts-web:v0.2.0 ghcr.io/gitchegumi/gitchalerts-ingress:v0.2.0 ghcr.io/gitchegumi/gitchalerts-worker:v0.2.0 ``` If service-level versions are maintained independently, expose them explicitly as metadata while still tagging release images with the project release version: ```text Project release: v0.2.0 web service version: 0.4.0 ingress service version: 0.2.1 worker service version: 0.1.3 ``` The image labels should include both: ```text org.opencontainers.image.version=v0.2.0 org.opencontainers.image.revision=<git-sha> org.opencontainers.image.source=https://github.com/Gitchegumi/multi-stream-alerts org.opencontainers.image.title=gitchalerts-web org.opencontainers.image.description=<service description> ``` ## Required implementation 1. Define the release/versioning strategy in the repo documentation. 2. Add a single source of truth for the project release version. 3. Add a clear source of truth for per-service/container versions if service versions are maintained independently. 4. Update Docker image build/publish workflow to tag images with readable version tags. 5. Preserve immutable traceability by also tagging or labeling images with the commit SHA. 6. Add OCI-compliant image labels to all containers. 7. Make Docker Compose examples reference readable version tags rather than random hashes. 8. Add release automation or documented release steps for: - version bump, - changelog/release notes, - Git tag creation, - container build and publish, - GitHub release publication. 9. Add dashboard/API support to expose the currently deployed version. 10. Add dashboard support to check the latest release in the GitHub repo and notify the user when an update is available. ## Dashboard requirements The dashboard should show: - Current project release version. - Current commit SHA or short SHA. - Per-service version/build metadata if available. - Whether a newer GitHub release is available. - Link to the latest release notes. The update check should be safe for self-hosted deployments: - Do not require authentication to GitHub for public release checks. - Fail quietly if GitHub is unavailable. - Do not block dashboard loading if update check fails. - Cache update-check results to avoid unnecessary GitHub API calls. - Provide a way to disable update checks for offline/private deployments, for example: ```env UPDATE_CHECK_ENABLED=true UPDATE_CHECK_REPO=Gitchegumi/multi-stream-alerts ``` ## Acceptance criteria - GitHub releases can be published with SemVer tags. - Container images are published with readable tags tied to releases. - Containers also include immutable commit SHA metadata. - Each service/container can expose its own version metadata if implemented. - The dashboard displays the currently deployed version. - The dashboard warns when a newer GitHub release exists. - Docker Compose examples use understandable image tags. - Release process is documented well enough for maintainers and self-hosters. ## Notes Do not rely only on `latest`. It is fine to publish `latest` as a convenience tag, but self-hosted users should be encouraged to pin stable release tags. A good tagging set for each release would be something like: ```text v0.2.0 0.2.0 sha-<shortsha> latest ``` The release tag should be the recommended production/self-hosted deployment tag. The SHA tag should be used for debugging and traceability.

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gitchegumi/GitchAlerts#41

No description provided.

Rows
Columns