feat: add on-demand image build pipeline to CircleCI

[rshoemaker]

Summary

• Adds a build_image job to CircleCI that builds and pushes a control-plane Docker image from any git ref (commit SHA, branch, or tag)
• Images are tagged v0.0.0-<short-sha> and pushed to GHCR
• Triggered manually via circleci pipeline trigger --parameter build_ref=<ref>
• Reuses existing goreleaser-build and control-plane-images Makefile targets
• Gates the test workflow with unless so it doesn't run during image builds

How to Use

Pre-requisites: install CircleCI CLI (brew install circleci) and authenticate via circleci setup which will install the required token.

By branch name:

  curl -X POST https://circleci.com/api/v2/project/gh/pgEdge/control-plane/pipeline \                                                                                                                                                    
    -H "Circle-Token: $(grep token ~/.circleci/cli.yml | awk '{print $2}')" \                                                                                                                                                            
    -H "Content-Type: application/json" \                                                                                                                                                                                                
    -d '{"branch": "main", "parameters": {"build_ref": "feat/some-branch"}}'                                                                                                                                                             

By commit SHA:

  curl -X POST https://circleci.com/api/v2/project/gh/pgEdge/control-plane/pipeline \
    -H "Circle-Token: $(grep token ~/.circleci/cli.yml | awk '{print $2}')" \
    -H "Content-Type: application/json" \
    -d '{"branch": "main", "parameters": {"build_ref": "af842d1"}}'

Both produce an image tagged v0.0.0-<short-sha>. The branch field tells CircleCI where to read the config from; build_ref is what actually gets checked out and built.

Test plan

• [ x ] Trigger pipeline with build_ref set to a branch name
• [ x ] Trigger pipeline with build_ref set to a commit SHA
• [ x ] Verify image appears in GHCR with correct tag

PLAT-431

[coderabbitai]

📝 Walkthrough

Walkthrough

A new CircleCI parameter build_ref and corresponding build_image job were introduced to manage Docker image building and publishing to ghcr.io. The test and release workflows were updated with conditional logic gated by this parameter.

Changes

Cohort / File(s)	Summary
CircleCI Configuration .circleci/config.yml	Added top-level parameter build_ref, new build_image job with multi-stage Docker build and ghcr.io publishing steps, and conditional workflow guards for test and release workflows based on parameter presence.

Poem

🐰 Whiskers twitch with CircleCI cheer,
New build_image jobs appear!
Parameters dance, workflows align,
Multi-stage Docker images shine,
Registry publishes so fine! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding an on-demand image build pipeline to CircleCI, matching the primary purpose of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	PR description covers summary, changes, testing plan, and issue reference, but checklist is incomplete and missing some required sections.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/PLAT-431/tagged_image_builds

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

.circleci/config.yml (1)

153-169: Missing environment variable validation before use.

The release job (lines 110-118) validates that IMAGE_PUBLISH_TOKEN and IMAGE_PUBLISH_USER are set before attempting Docker login. This job uses the same credentials at lines 164-165 but lacks validation, which would produce a confusing error message if the context secrets are missing.

Proposed fix to add validation

       - run:
           name: Build and publish image
           command: |
             git checkout -- .

+            if [[ -z "${IMAGE_PUBLISH_TOKEN}" ]]; then
+              echo "IMAGE_PUBLISH_TOKEN must be set"
+              exit 1
+            fi
+            if [[ -z "${IMAGE_PUBLISH_USER}" ]]; then
+              echo "IMAGE_PUBLISH_USER must be set"
+              exit 1
+            fi
+
             short_sha=$(git rev-parse --short HEAD)

Note: The release job's validation also lacks exit 1 after the error messages—consider fixing that as well for consistent early termination.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.circleci/config.yml around lines 153 - 169, Add explicit checks for
IMAGE_PUBLISH_TOKEN and IMAGE_PUBLISH_USER before using them in the "Build and
publish image" run step: test that both environment variables are set and if not
print a clear error and exit 1 prior to the docker login and image publish
commands; mirror the validation pattern used in the release job (but ensure you
include the missing exit 1 there as well) so that the docker login line that
pipes "${IMAGE_PUBLISH_TOKEN}" into docker is only executed when
IMAGE_PUBLISH_TOKEN and IMAGE_PUBLISH_USER are present.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.circleci/config.yml:
- Around line 148-152: The CI step named "Checkout build ref and rebuild deps"
uses git checkout << pipeline.parameters.build_ref >> which fails for
remote-only refs; update that step to run an explicit git fetch of the provided
pipeline.parameters.build_ref (fetch the remote ref from origin, e.g. fetch
refs/heads/... or origin/<build_ref> into FETCH_HEAD or a temporary branch)
before attempting checkout, then checkout the fetched ref (keeping the existing
go mod download afterwards) so remote branch names and other ref types work
reliably.

---

Nitpick comments:
In @.circleci/config.yml:
- Around line 153-169: Add explicit checks for IMAGE_PUBLISH_TOKEN and
IMAGE_PUBLISH_USER before using them in the "Build and publish image" run step:
test that both environment variables are set and if not print a clear error and
exit 1 prior to the docker login and image publish commands; mirror the
validation pattern used in the release job (but ensure you include the missing
exit 1 there as well) so that the docker login line that pipes
"${IMAGE_PUBLISH_TOKEN}" into docker is only executed when IMAGE_PUBLISH_TOKEN
and IMAGE_PUBLISH_USER are present.