Releasing a versioned application suite¶
A suite repository can select the image versions of several applications without
building those applications. Diatreme tags that selection, combines their published
release notes, and publishes a suite GitHub Release with a release.json snapshot.
Application Kubernetes resources can stay in their own repositories; Flux or another
deployment system reads the central image selections.
Central selections and application catalog¶
Store one Kustomize selection per environment:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../vendor/web/overlays/acc
- ../../vendor/api/overlays/acc
images:
- name: ghcr.io/example/web
newTag: v1.4.0
- name: ghcr.io/example/api
newTag: v2.3.1
The vendor directories in this example are supplied by the deployment system.
Diatreme reads images; it does not fetch, build or deploy the resources. Each
selection needs a unique name and a SemVer newTag; digest selections are rejected.
Map those images to their application repositories:
{
"apps": [
{
"id": "web",
"display_name": "Web application",
"repository": "example/web",
"image": "ghcr.io/example/web"
},
{
"id": "api",
"display_name": "API service",
"repository": "example/api",
"image": "ghcr.io/example/api"
}
]
}
id, repository and image are required. display_name defaults to id.
Every selected image must appear in the catalog. Duplicate IDs, duplicate images
and malformed selections fail the run.
Call the action with an explicit suite version¶
Suite releases require suite-manifest, suite-catalog, version-override,
mode: release and detect-image-name: false. Leave image_name empty.
This path skips automatic version calculation and image builds or promotions.
name: Release suite
on:
workflow_dispatch:
inputs:
version:
description: Suite version, for example 1.5.0-acc.2
required: true
type: string
permissions:
contents: write
concurrency:
group: suite-release-${{ github.ref }}
cancel-in-progress: false
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: MagmaMoose/diatreme@v2
with:
mode: release
auth-mode: github-token
github-token: ${{ secrets.SUITE_RELEASE_TOKEN }}
deployment-model: tbd
environment: acc
environments: '["dev", "tst", "acc", "prd"]'
prerelease-identifiers: '{"dev":"dev", "tst":"tst", "acc":"acc"}'
suite-manifest: k8s/acc/kustomization.yaml
suite-catalog: suite/apps.json
version-override: ${{ inputs.version }}
detect-image-name: 'false'
The action checks out the suite repository with complete history and tags. Pin the action to a published commit SHA in a production workflow.
Use a token that can write the suite repository and read every catalog application
repository, including its GitHub Releases. An installation token obtained from
your own GitHub App works with auth-mode: github-token; the resulting changelog
commit is attributed to that App. The default workflow GITHUB_TOKEN cannot read
other private repositories. On GitHub Enterprise, the same token must cover the
application repositories on that host; the action uses the workflow's
GITHUB_API_URL and GITHUB_SERVER_URL for reads and links.
The caller owns version planning¶
The suite version is separate from each application's image version. Diatreme does not infer a suite bump from the application versions in this mode.
For the environment configuration above, supply versions such as
1.5.0-dev.1, 1.5.0-tst.3, 1.5.0-acc.2 and stable 1.5.0 for prd.
The environment order makes the final environment stable; the preceding ones
are GitHub prereleases. The caller must choose the next base version and revision,
skip unchanged selections, and serialize releases on the same branch. Omit prd
from prerelease-identifiers.
Aggregate notes and immutable snapshots¶
Diatreme compares the selected manifest with the newest reachable suite tag for the same environment. An ACC release is compared with the preceding ACC release, even if a TST or production tag is newer.
For each changed application, it reads every published release in the SemVer range
old < release <= new, on the selected image's channel. Stable image upgrades
include stable releases; candidate upgrades include that candidate channel. Draft
releases are excluded. Initial suite selections and rollbacks include the selected
application release only, with rollbacks labeled explicitly.
The exact application release tag must match newTag and have published notes.
Missing releases, empty notes and API failures stop the run before the suite tag
is created. Notes are copied from the application releases, with links to those
releases. Diatreme never edits the application repositories.
After tagging, one GitHub-signed commit writes CHANGELOG.md and
suite/status.json to the current suite branch. The commit preserves other
environment entries and earlier changelog notes. It checks the branch head
optimistically and refuses to write if the selected manifest has changed since
the release checkout. The suite tag continues to identify the original selection
commit; the later status commit does not move it.
The GitHub Release contains the aggregate notes and an attached release.json.
The snapshot includes the environment, suite tag, release URL and timestamp,
selected image versions, previous suite tag, and changed applications with their
version ranges and release notes. suite/status.json keeps the latest snapshot
under each environment for dashboards and other readers. This records a release
selection; deployment readiness comes from the deployment system.
Resume a failed release¶
Rerun the original workflow at the same commit with the same version-override.
An existing suite tag at that commit resumes instead of creating another version.
The status/changelog commit is idempotent, and an existing GitHub Release is left
unchanged. A tag belonging to another commit, changed image selections for an
already recorded tag, or an attempt to overwrite newer environment history fails.
If the branch now contains a newer image selection, release that selection with a new suite version. Do not reuse an older suite tag for different images.