diff --git a/README.md b/README.md index c9c605f..8280cb8 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ Whenever the action updates a GitOps file, it stamps the following annotations o |------------|-------| | `deploy.staffbase.com/repositoryFullName` | The source repository in `owner/repo` form (`$GITHUB_REPOSITORY`) | | `deploy.staffbase.com/commitSha` | The commit SHA being deployed (`$GITHUB_SHA`) | -| `deploy.staffbase.com/version` | The deployed image tag — `dev-` on `dev`, `main-` on `main`, `master-` on `master` (with `docker-tag-timestamp` a UTC timestamp is inserted before the SHA), the version without the leading `v` on `v*` tag pushes, and the tag name on other tag pushes | +| `deploy.staffbase.com/version` | The deployed image tag — `dev--` on `dev`, `main--` on `main`, `master--` on `master` (the UTC timestamp is inserted by default; with `docker-tag-timestamp: 'false'` it falls back to `-`), the version without the leading `v` on `v*` tag pushes, and the tag name on other tag pushes | These keys mirror the [Swarmia Deployment API](https://help.swarmia.com/settings/organization/configuring-deployments-in-swarmia) field names and are read by `flux-deployment-reporter` to report deployments to Swarmia once Flux finishes reconciling. @@ -126,7 +126,7 @@ These keys mirror the [Swarmia Deployment API](https://help.swarmia.com/settings | `docker-registry-api` | Docker Registry API (used for retagging without pulling) | `https://registry.staffbase.com/v2/` | | `docker-image` | Docker Image | | | `docker-custom-tag` | Docker Custom Tag to be set on the image | | -| `docker-tag-timestamp` | Insert a UTC timestamp into `dev`/`main`/`master` branch tags (`dev--`) to make them sortable for Flux image automation | `false` | +| `docker-tag-timestamp` | Insert a UTC timestamp into `dev`/`main`/`master` branch tags (`dev--`) to make them sortable for Flux image automation. Enabled by default; set to `'false'` for the legacy `-` format | `true` | | `docker-tag-keep-v-prefix` | Keep the leading `v` on release (`v*`) tags (`v1.2.3` → `v1.2.3`). Default strips it (`v1.2.3` → `1.2.3`) | `false` | | `docker-username` | Username for the Docker Registry | | | `docker-password` | Password for the Docker Registry | | @@ -159,22 +159,22 @@ These keys mirror the [Swarmia Deployment API](https://help.swarmia.com/settings The generated image tag depends on the Git ref: -| Ref | Tag (default) | Tag (`docker-tag-timestamp: 'true'`) | Floating tag | +| Ref | Tag (default) | Tag (`docker-tag-timestamp: 'false'`) | Floating tag | |-----|---------------|--------------------------------------|--------------| -| `dev` branch | `dev-` | `dev--` | `dev` | -| `main` branch | `main-` | `main--` | `main` | -| `master` branch | `master-` | `master--` | `master` | +| `dev` branch | `dev--` | `dev-` | `dev` | +| `main` branch | `main--` | `main-` | `main` | +| `master` branch | `master--` | `master-` | `master` | | `v*` tag (prod) | the version with the `v` stripped, e.g. `v2025.50.14` → `2025.50.14` (or kept with `docker-tag-keep-v-prefix: 'true'`) | _(unchanged)_ | `latest` | | other branch | `` (not pushed) | _(unchanged)_ | — | -By default branch tags keep the legacy `-` shape. Set -`docker-tag-timestamp: 'true'` to insert a `YYYYMMDDHHMMSS` (UTC) timestamp before -the SHA. This makes branch tags **sortable** so +By default branch tags carry a `YYYYMMDDHHMMSS` (UTC) timestamp inserted before the +SHA. This makes branch tags **sortable** so [Flux image automation](https://fluxcd.io/flux/components/image/) can pick the newest build — the Git SHA alone is not orderable. The short SHA is kept for -traceability and Flux sorts on the timestamp only. +traceability and Flux sorts on the timestamp only. Set `docker-tag-timestamp: 'false'` +to fall back to the legacy `-` shape. -> **Note:** with `docker-tag-timestamp: 'true'` the build also pushes the plain +> **Note:** with the timestamp enabled (the default) the build also pushes the plain > `-` tag alongside the timestamped one. That stable per-commit > tag is what the release step retags into the version tag, so it must continue > to exist. It does not match the `^-[0-9]+-[0-9a-f]+$` filter below, so diff --git a/action.yml b/action.yml index 53fa5b9..af4abae 100644 --- a/action.yml +++ b/action.yml @@ -18,9 +18,9 @@ inputs: description: 'Docker Custom Tag' required: false docker-tag-timestamp: - description: 'Insert a UTC timestamp into dev/main/master branch tags (e.g. dev-20260602143055-) to make them sortable for Flux image automation. Opt-in; defaults to the legacy - format.' + description: 'Insert a UTC timestamp into dev/main/master branch tags (e.g. dev-20260602143055-) to make them sortable for Flux image automation. Enabled by default; set to ''false'' for the legacy - format.' required: false - default: 'false' + default: 'true' docker-tag-keep-v-prefix: description: 'Keep the leading "v" on release (v*) tags (v1.2.3 -> v1.2.3). Opt-in; defaults to stripping it (v1.2.3 -> 1.2.3).' required: false diff --git a/scripts/generate-tags.sh b/scripts/generate-tags.sh index 9ca3a75..4d48828 100755 --- a/scripts/generate-tags.sh +++ b/scripts/generate-tags.sh @@ -23,22 +23,22 @@ ALIAS_TAG="" # set_branch_tags computes the immutable tag(s) for an environment branch and # assigns them to the globals TAG and ALIAS_TAG. # -# When INPUT_DOCKER_TAG_TIMESTAMP is "true" the canonical TAG gets a UTC timestamp -# inserted before the short SHA (e.g. dev-20260602143055-abcdef12). This makes -# branch tags sortable by Flux image automation (numerical policy) — the Git SHA -# alone is not orderable, so Flux cannot otherwise tell which build is newest. -# In that case ALIAS_TAG holds the legacy - tag, which is also -# pushed: it is the stable per-commit handle that retag-image.sh looks up to find -# the source image for a release, so dropping it would break the release retag. +# By default (INPUT_DOCKER_TAG_TIMESTAMP unset or "true") the canonical TAG gets a +# UTC timestamp inserted before the short SHA (e.g. dev-20260602143055-abcdef12). +# This makes branch tags sortable by Flux image automation (numerical policy) — the +# Git SHA alone is not orderable, so Flux cannot otherwise tell which build is +# newest. In that case ALIAS_TAG holds the legacy - tag, which is +# also pushed: it is the stable per-commit handle that retag-image.sh looks up to +# find the source image for a release, so dropping it would break the release retag. # The alias does not match Flux's "--" pattern, so Flux -# ignores it. When the flag is unset/false only the legacy - -# tag is produced, so existing consumers are unaffected. +# ignores it. Set INPUT_DOCKER_TAG_TIMESTAMP="false" to opt out and produce only the +# legacy - tag. # # The timestamp is overridable via BUILD_TIMESTAMP for deterministic tests. set_branch_tags() { local prefix="$1" local sha="${GITHUB_SHA::8}" - if [[ "${INPUT_DOCKER_TAG_TIMESTAMP:-false}" == "true" ]]; then + if [[ "${INPUT_DOCKER_TAG_TIMESTAMP:-true}" == "true" ]]; then local ts="${BUILD_TIMESTAMP:-$(date -u +%Y%m%d%H%M%S)}" TAG="${prefix}-${ts}-${sha}" ALIAS_TAG="${prefix}-${sha}" diff --git a/tests/generate-tags.bats b/tests/generate-tags.bats index 515eb53..e11ce43 100644 --- a/tests/generate-tags.bats +++ b/tests/generate-tags.bats @@ -11,8 +11,9 @@ setup() { export INPUT_DOCKER_IMAGE="my-service" export INPUT_DOCKER_CUSTOM_TAG="" export INPUT_DOCKER_DISABLE_RETAGGING="false" - # Timestamp suffix is opt-in; default off so the legacy - format - # is the baseline. Tests that exercise the suffix set the flag explicitly. + # Timestamp suffix is on by default; leaving the flag unset exercises that + # default (the timestamped -- format). Tests that need the + # legacy shape set the flag to "false" explicitly. unset INPUT_DOCKER_TAG_TIMESTAMP # Keeping the "v" prefix on release tags is opt-in; default off. unset INPUT_DOCKER_TAG_KEEP_V_PREFIX @@ -30,7 +31,7 @@ teardown() { export GITHUB_REF="refs/heads/main" run "$SCRIPT" assert_success - assert_output_value "tag" "main-abcdef12" + assert_output_value "tag" "main-20260602143055-abcdef12" assert_output_value "latest" "main" assert_output_value "push" "true" assert_output_value "build" "true" @@ -42,7 +43,7 @@ teardown() { export GITHUB_REF="refs/heads/master" run "$SCRIPT" assert_success - assert_output_value "tag" "master-abcdef12" + assert_output_value "tag" "master-20260602143055-abcdef12" assert_output_value "latest" "master" assert_output_value "push" "true" assert_output_value "build" "true" @@ -54,13 +55,13 @@ teardown() { export GITHUB_REF="refs/heads/dev" run "$SCRIPT" assert_success - assert_output_value "tag" "dev-abcdef12" + assert_output_value "tag" "dev-20260602143055-abcdef12" assert_output_value "latest" "dev" assert_output_value "push" "true" assert_output_value "build" "true" } -# --- timestamp suffix (opt-in, Flux-sortable) --- +# --- timestamp suffix (default, Flux-sortable) --- @test "dev branch with timestamp flag inserts timestamp before sha" { export INPUT_DOCKER_TAG_TIMESTAMP="true" @@ -83,6 +84,7 @@ teardown() { } @test "no - alias is added when timestamp flag is off" { + export INPUT_DOCKER_TAG_TIMESTAMP="false" export GITHUB_REF="refs/heads/main" run "$SCRIPT" assert_success @@ -127,12 +129,33 @@ teardown() { assert_output_value "tag" "2025.50.14" } -@test "timestamp flag explicitly 'false' produces legacy shape" { +# --- legacy shape (timestamp explicitly off) --- + +@test "dev branch with timestamp flag off produces legacy shape" { export INPUT_DOCKER_TAG_TIMESTAMP="false" export GITHUB_REF="refs/heads/dev" run "$SCRIPT" assert_success assert_output_value "tag" "dev-abcdef12" + assert_output_value "latest" "dev" +} + +@test "main branch with timestamp flag off produces legacy shape" { + export INPUT_DOCKER_TAG_TIMESTAMP="false" + export GITHUB_REF="refs/heads/main" + run "$SCRIPT" + assert_success + assert_output_value "tag" "main-abcdef12" + assert_output_value "latest" "main" +} + +@test "master branch with timestamp flag off produces legacy shape" { + export INPUT_DOCKER_TAG_TIMESTAMP="false" + export GITHUB_REF="refs/heads/master" + run "$SCRIPT" + assert_success + assert_output_value "tag" "master-abcdef12" + assert_output_value "latest" "master" } # --- version tag --- @@ -247,7 +270,7 @@ teardown() { assert_success local tag_list tag_list=$(get_output_value "tag_list") - [[ "$tag_list" == "registry.staffbase.com/my-service:main-abcdef12,registry.staffbase.com/my-service:main" ]] + [[ "$tag_list" == "registry.staffbase.com/my-service:main-20260602143055-abcdef12,registry.staffbase.com/my-service:main-abcdef12,registry.staffbase.com/my-service:main" ]] } @test "tag_list has no latest suffix for feature branches" {