fix: more reliable dev version tagging (#1424)

## Which problem is this PR solving?

- Image builds in Circle were still using the job ID as the version.

## Short description of the changes

- Reliably set the version regardless of where the image build is being
run.
- Moves the image tagging logic to below the version-determination
logic. Now the dev-build tagging can reuse the determined dev version
instead of using the CircleCI build ID.
- Sets some defaults for environment variables to appease the `nounset`
shell rule when this script is run outside of CI.

## Example Outputs

### Dev build in Dev

```
❯ ./build-docker.sh
++ git describe --tags '--match=v[0-9]*' --always
+ VERSION=2.8.2-58-g264d4af
… 
+ GOFLAGS=-ldflags=-X=main.BuildID=2.8.2-58-g264d4af
… 
+ ./ko publish --tags 2.8.2-55-gcc8c2a2 …
… 
2024/11/12 13:58:26 Adding tag 2.8.2-55-gcc8c2a2
… 
```

### [Dev build off branch in
CI](https://app.circleci.com/pipelines/github/honeycombio/refinery/4519/workflows/956f775f-f48d-4938-8e87-ca32feb551e6/jobs/13888?invite=true#step-106-1804_56)

```
#!/bin/bash -eo pipefail
./build-docker.sh
…
+ GOFLAGS=-ldflags=-X=main.BuildID=2.8.2-58-g264d4af-ci13888
…
2024/11/12 18:34:40 Adding tag 2.8.2-58-g264d4af-ci13888
2024/11/12 18:34:40 Adding tag branch-robb.use-new-dev-version-as-tag-for-dev-builds
… 
```

### Dev build off branch in simulated CI

```
❯ CIRCLE_BUILD_NUM=8675309 CIRCLE_BRANCH=$(git rev-parse --abbrev-ref HEAD) ./build-docker.sh
++ git describe --tags '--match=v[0-9]*' --always
+ VERSION=v2.8.2-55-gcc8c2a2
… 
+ GOFLAGS=-ldflags=-X=main.BuildID=2.8.2-58-g264d4af-ci8675309
… 
+ ./ko publish --tags 2.8.2-55-gcc8c2a2-ci8675309,branch-robb.use-new-dev-version-as-tag-for-dev-builds 
… 
2024/11/12 14:02:32 Adding tag 2.8.2-55-gcc8c2a2-ci8675309
2024/11/12 14:02:32 Adding tag branch-robb.use-new-dev-version-as-tag-for-dev-builds
… 
```

### Dev build off main in simulated CI

```
❯ CIRCLE_BUILD_NUM=8675309 CIRCLE_BRANCH=main ./build-docker.sh
… 
+ GOFLAGS=-ldflags=-X=main.BuildID=2.8.2-58-g264d4af-ci8675309
… 
2024/11/12 14:13:54 Adding tag 2.8.2-55-gcc8c2a2-ci8675309
2024/11/12 14:13:54 Adding tag branch-main
2024/11/12 14:13:54 Adding tag latest
… 
```

### Tagged release build off main in simulated CI

```
❯ CIRCLE_BUILD_NUM=8675309 CIRCLE_BRANCH=main CIRCLE_TAG=v999.99.9 ./build-docker.sh
…
+ GOFLAGS=-ldflags=-X=main.BuildID=999.99.9
… 
2024/11/12 14:16:32 Adding tag 999
2024/11/12 14:16:32 Adding tag 999.99
2024/11/12 14:16:32 Adding tag 999.99.9
2024/11/12 14:16:32 Adding tag latest
…
```

---------

Co-authored-by: Mike Goldsmith <[email protected]>

build-docker.sh

@@ -3,18 +3,6 @@ set -o nounset
 set -o pipefail
 set -o xtrace
 
-TAGS=""
-# Check if CIRCLE_BRANCH is set and not empty
-if [[ -n "${CIRCLE_BRANCH}" ]]; then
-    BRANCH_TAG=${CIRCLE_BRANCH//\//-}
-    TAGS="${CIRCLE_BUILD_NUM},branch-${BRANCH_TAG}"
-fi
-
-# We only want to tag main with latest on ECR
-if [[ "${CIRCLE_BRANCH}" == "main" ]]; then
-    TAGS+=",latest"
-fi
-
 # Determine a version number based on most recent version tag in git.
 #   git describe - Return the most recent annotated tag that is reachable from a commit.
 #     --tags - OK, any tag, not just the annotated ones. We don't always remember to annotate a version tag.
@@ -24,7 +12,9 @@ fi
 #   - The build was on git commit ID a1b2c3d.
 #   - v2.1.1 is the most recent version tag in the history behind that commit
 #   - That commit is 45 commits ahead of that version tag.
-VERSION=$(git describe --tags --match='v[0-9]*' --always)
+VERSION_FROM_GIT=$(git describe --tags --match='v[0-9]*' --always)
+# trim the v prefix per Docker image version-tagging conventions
+VERSION=${VERSION_FROM_GIT#'v'}
 
 # If we are doing a dev build on circle, append the build number (job id) to the version
 # Ex: v2.1.1-45-ga1b2c3d-ci8675309
@@ -34,23 +24,40 @@ if [[ -n "${CIRCLE_BUILD_NUM:-}" ]]; then
   VERSION="${VERSION}-ci${CIRCLE_BUILD_NUM}"
 fi
 
+### Image tagging ###
+TAGS="${VERSION}"
+
+## CI dev tagging: append the dev branch name to image tags
+if [[ -n "${CIRCLE_BRANCH:-}" ]]; then
+  BRANCH_TAG=${CIRCLE_BRANCH//\//-}
+  TAGS+=",branch-${BRANCH_TAG}"
+
+  # If the dev build is on main, we tag it as latest in ECR
+  if [[ "${CIRCLE_BRANCH}" == "main" ]]; then
+      TAGS+=",latest"
+  fi
+fi
+
+## CI release tagging: apply major, major.minor, major.minor.patch, and latest tags
+
 # if we're running off a git tag, it is a release which we tag with the versions as well as latest
 # caution: this means if we ever release an update to a previous version, it will be marked latest
 # it is probably best if people just use the major or minor version tags
 
 if [[ -n ${CIRCLE_TAG:-} ]]; then
-  # trim 'v' prefix if present
-  VERSION=${CIRCLE_TAG#"v"}
+  VERSION=${CIRCLE_TAG#"v"} # trim the v prefix per version-tagging convention
 
   # Extract major, major.minor, and major.minor.patch versions
   MAJOR_VERSION=${VERSION%%.*}
   MINOR_VERSION=${VERSION%.*}
 
-  # Append versions to image tags
-  # So 2.1.1 would be tagged with "2","2.1","2.1.1"
+  # Reset tag list: add major, major.minor, major.minor.patch, and latest
+  # So 2.1.1 would be tagged with "2","2.1","2.1.1", and "latest".
   TAGS="$MAJOR_VERSION,$MINOR_VERSION,$VERSION,latest"
 fi
 
+GIT_COMMIT=${CIRCLE_SHA1:-$(git rev-parse HEAD)}
+
 unset GOOS
 unset GOARCH
 export KO_DOCKER_REPO=${KO_DOCKER_REPO:-ko.local}
@@ -63,5 +70,5 @@ export SOURCE_DATE_EPOCH=${SOURCE_DATE_EPOCH:-$(make latest_modification_time)}
   --platform "linux/amd64,linux/arm64" \
   --image-label org.opencontainers.image.source=https://github.com/honeycombio/refinery \
   --image-label org.opencontainers.image.licenses=Apache-2.0 \
-  --image-label org.opencontainers.image.revision=${CIRCLE_SHA1} \
+  --image-label org.opencontainers.image.revision=${GIT_COMMIT} \
   ./cmd/refinery