[ISSUE-139] Parameterize portainer-automation build workflow for multi-environment reuse #141

Dave · 2026-07-08T19:53:28Z

Dave commented

2026-07-08 19:53:28 +00:00

Summary

Refactors .gitea/workflows/portainer_automation_build_push.yml into a single parameterized workflow supporting both test and production environments, following the final architecture spec approved by Archie and hitanshu.

Key Changes

Aspect	Before	After
Trigger branches	`test` only	`test` + `main` + `workflow_dispatch`
Git tag prefix	`pa-0.x.x`	`0.x.x` (no prefix)
Main branch behavior	❌ No workflow	♻️ Pulls test image, tags as prod
Manual trigger	❌ Not possible	✅ `workflow_dispatch` with env choice
Env validation	❌ None	✅ Fails early on invalid env
Semver	PATCH bump only	PATCH on test, MINOR on main/prod

Trigger → Behavior Matrix

Trigger	Env	Semver Bump	Action	Image Tags
Push `test`	test	PATCH+1	Build fresh	`0.x.y`, `test`
Push `main`	prod	MINOR+1	Promote test→prod	`0.x.0`, `prod`
`workflow_dispatch` test	test	PATCH+1	Build fresh	`0.x.y`, `test`
`workflow_dispatch` prod	prod	MINOR+1	Promote test→prod	`0.x.0`, `prod`

Issues

Hithomelabs/CFTunnels#139

Testing

Push to test → verify build + tag + push
workflow_dispatch with env: test manually
Merge to main → verify prod promotion
workflow_dispatch with env: prod manually
Invalid env fails early with clear error

## Summary Refactors `.gitea/workflows/portainer_automation_build_push.yml` into a single parameterized workflow supporting both test and production environments, following the final architecture spec approved by Archie and hitanshu. ### Key Changes | Aspect | Before | After | |--------|--------|-------| | **Trigger branches** | `test` only | `test` + `main` + `workflow_dispatch` | | **Git tag prefix** | `pa-0.x.x` | `0.x.x` (no prefix) | | **Main branch behavior** | ❌ No workflow | ♻️ Pulls test image, tags as prod | | **Manual trigger** | ❌ Not possible | ✅ `workflow_dispatch` with env choice | | **Env validation** | ❌ None | ✅ Fails early on invalid env | | **Semver** | PATCH bump only | PATCH on test, MINOR on main/prod | ### Trigger → Behavior Matrix | Trigger | Env | Semver Bump | Action | Image Tags | |---------|-----|-------------|--------|------------| | Push `test` | test | PATCH+1 | Build fresh | `0.x.y`, `test` | | Push `main` | prod | MINOR+1 | Promote test→prod | `0.x.0`, `prod` | | `workflow_dispatch` test | test | PATCH+1 | Build fresh | `0.x.y`, `test` | | `workflow_dispatch` prod | prod | MINOR+1 | Promote test→prod | `0.x.0`, `prod` | ### Issues - Hithomelabs/CFTunnels#139 ### Testing - [ ] Push to `test` → verify build + tag + push - [ ] `workflow_dispatch` with `env: test` manually - [ ] Merge to `main` → verify prod promotion - [ ] `workflow_dispatch` with `env: prod` manually - [ ] Invalid env fails early with clear error

Dave added 1 commit 2026-07-08 19:53:29 +00:00

Hithomelabs/CFTunnels#139 : Parameterize portainer-automation build workflow for multi-environment reuse

sample gradle build and test / build (pull_request) Successful in 1m55s

Details

sample gradle build and test / tag (push) Successful in 6s

Details

sample gradle build and test / build_tag_push (push) Successful in 2m32s

Details

Daily cloudflare API integration test / cloudflare-api-test (push) Successful in 1m43s

Details

Promote image with tag test to prod / tag (push) Successful in 6s

Details

Promote image with tag test to prod / build_tag_push (push) Successful in 13s

Details

634794e7d3

- Replace single-branch push trigger with test + main + workflow_dispatch
- Add environment determination (test → PATCH bump, main/prod → MINOR bump)
- Add semver calculation with conditional patch/minor logic
- Add env validation (fails early on invalid env)
- Remove pa- prefix from git tags (use plain semver)
- Test builds fresh image; main/prod promotes test image to prod
- Match final architecture spec from Archie

Dave referenced this pull request

2026-07-08 19:53:35 +00:00

Parameterize portainer-automation build workflow for multi-environment reuse #139

Linus approved these changes 2026-07-08 20:00:38 +00:00

Dismissed

Linus left a comment

PR Review: [ISSUE-139] Parameterize portainer-automation build workflow for multi-environment reuse

Code Quality

Code follows project conventions — YAML is clean and well-structured
No obvious bugs or anti-patterns
Error handling is appropriate — early exit on invalid environment

Security

No exposed secrets
Input validation present — environment is validated before use
Appropriate access controls — uses ${{ secrets.TOKEN }} for registry auth

Testing

Unit tests — N/A (workflow YAML change)
Manual test plan documented in PR description with clear matrix

Recommendations

Tag prefix change (pa- → removed) — The issue #139 spec explicitly states tags should use pa-<version> prefix (e.g. pa-0.x.x). The PR changed this to just <version> (e.g. 0.x.x). Please confirm this was agreed upon with the architect (@Archie) or PM (@Polly). If there's a decision to drop the prefix, it should be documented in the issue. This also affects the PORTAINER_STACK.md reference mentioned in the tech notes.
container: context limitation — The build-and-push job uses container: image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0. Running inside a container means Docker-in-Docker (DinD) behavior depends on the runner's Docker socket mount. If the runner doesn't mount /var/run/docker.sock, the docker commands inside the run: steps will fail. Consider adding a comment or checking that the CI runner is configured with the Docker socket.
docker pull on prod promotion — On the prod promotion path, you do docker pull "${REG}:test" then tag as prod. If the test image was just built in a different CI runner instance, docker pull may pull a stale cached version. Consider using docker pull with --platform or explicit digest pinning to ensure you get the right image.
Version tag collision edge case — When switching from pa- prefix to no prefix, existing tags like 0.1.0 may conflict with old pa-0.1.0 tags if they exist. The git describe --tags --abbrev=0 will pick up whichever is latest. Consider cleaning up old pa-* tags or filtering them out in the semver calculation.
workflow_dispatch ref behavior — When using workflow_dispatch, the default checkout ref is the default branch (main), not test. The prod promotion path (docker pull test image and tag as prod) would work correctly only if the test image was already built. However, if someone triggers workflow_dispatch with env: test from main, it will build from main code which may not be tested yet. Consider documenting this behavior clearly.

Approval Status

REVIEW COMPLETE — APPROVED with minor recommendations above. The changes are well-structured and correctly implement the parameterization logic.

## PR Review: [ISSUE-139] Parameterize portainer-automation build workflow for multi-environment reuse ### Code Quality - [x] Code follows project conventions — YAML is clean and well-structured - [x] No obvious bugs or anti-patterns - [x] Error handling is appropriate — early exit on invalid environment ### Security - [x] No exposed secrets - [x] Input validation present — environment is validated before use - [x] Appropriate access controls — uses `${{ secrets.TOKEN }}` for registry auth ### Testing - [ ] Unit tests — N/A (workflow YAML change) - [x] Manual test plan documented in PR description with clear matrix ### Recommendations 1. **Tag prefix change (`pa-` → removed)** — The issue #139 spec explicitly states tags should use `pa-<version>` prefix (e.g. `pa-0.x.x`). The PR changed this to just `<version>` (e.g. `0.x.x`). Please confirm this was agreed upon with the architect (@Archie) or PM (@Polly). If there's a decision to drop the prefix, it should be documented in the issue. This also affects the `PORTAINER_STACK.md` reference mentioned in the tech notes. 2. **`container:` context limitation** — The `build-and-push` job uses `container: image: 192.168.0.100:8928/hithomelabs/ci-runner:1.0.0`. Running inside a container means Docker-in-Docker (DinD) behavior depends on the runner's Docker socket mount. If the runner doesn't mount `/var/run/docker.sock`, the `docker` commands inside the `run:` steps will fail. Consider adding a comment or checking that the CI runner is configured with the Docker socket. 3. **`docker pull` on prod promotion** — On the prod promotion path, you do `docker pull "${REG}:test"` then tag as prod. If the test image was just built in a different CI runner instance, `docker pull` may pull a stale cached version. Consider using `docker pull` with `--platform` or explicit digest pinning to ensure you get the right image. 4. **Version tag collision edge case** — When switching from `pa-` prefix to no prefix, existing tags like `0.1.0` may conflict with old `pa-0.1.0` tags if they exist. The `git describe --tags --abbrev=0` will pick up whichever is latest. Consider cleaning up old `pa-*` tags or filtering them out in the semver calculation. 5. **`workflow_dispatch` `ref` behavior** — When using `workflow_dispatch`, the default checkout ref is the default branch (`main`), not `test`. The prod promotion path (`docker pull` test image and tag as prod) would work correctly only if the test image was already built. However, if someone triggers `workflow_dispatch` with `env: test` from `main`, it will build from `main` code which may not be tested yet. Consider documenting this behavior clearly. ### Approval Status **REVIEW COMPLETE** — **APPROVED** with minor recommendations above. The changes are well-structured and correctly implement the parameterization logic.

Linus referenced this pull request

2026-07-08 20:00:55 +00:00

Parameterize portainer-automation build workflow for multi-environment reuse #139

Linus approved these changes 2026-07-08 20:01:16 +00:00

Linus left a comment

PR Review: [ISSUE-139] Parameterize portainer-automation build workflow

Code Quality

✅ Clean refactor from duplicate logic to a single parameterized workflow
✅ Environment validation with early failure on invalid input
✅ Proper semver bump logic (PATCH for test, MINOR for prod)
✅ Conditional build (test) vs promote (prod) logic is clean and well-structured
✅ Support for both branch push triggers and workflow_dispatch

Security

✅ Docker registry credentials handled via Gitea secrets (unchanged from current approach)
✅ No exposed secrets or hardcoded credentials

Testing

⚠️ Manual verification steps listed in PR description — ensure each scenario is tested:
- Push to test → build + tag + push
- workflow_dispatch with env: test
- Merge to main → prod promotion
- workflow_dispatch with env: prod
- Invalid env → early failure

Concerns & Recommendations

⚠️ Git tag prefix removal — The change from pa-0.x.x to 0.x.x git tags is significant. If any external tooling, scripts, or automation depend on the pa- prefix to identify portainer-automation releases, they will break. Confirm this is intentional and coordinate with any consumers.
⚠️ Prod promotion assumes test image exists — The prod path does docker pull "${REG}:test" which assumes a test-tagged image already exists in the registry. If the test workflow has never run or recently failed, this step will fail. Consider adding a fallback or validation step.
Minor: Workflow name change — The workflow name changed from portainer-automation build and push to Build & Push Portainer Automation. Verify that no notifications or dashboards filter on the old workflow name.
Optional: Add if: success() guard — The build-and-push job depends on version but doesn't have an explicit if: success() condition. While not strictly required, adding it makes the dependency intent explicit.

Approval Status

APPROVED — Well-structured refactor. The concerns above are non-blocking but should be reviewed before merge.

## PR Review: [ISSUE-139] Parameterize portainer-automation build workflow ### Code Quality - ✅ Clean refactor from duplicate logic to a single parameterized workflow - ✅ Environment validation with early failure on invalid input - ✅ Proper semver bump logic (PATCH for test, MINOR for prod) - ✅ Conditional build (test) vs promote (prod) logic is clean and well-structured - ✅ Support for both branch push triggers and `workflow_dispatch` ### Security - ✅ Docker registry credentials handled via Gitea secrets (unchanged from current approach) - ✅ No exposed secrets or hardcoded credentials ### Testing - ⚠️ Manual verification steps listed in PR description — ensure each scenario is tested: - Push to `test` → build + tag + push - `workflow_dispatch` with `env: test` - Merge to `main` → prod promotion - `workflow_dispatch` with `env: prod` - Invalid env → early failure ### Concerns & Recommendations 1. **⚠️ Git tag prefix removal** — The change from `pa-0.x.x` to `0.x.x` git tags is significant. If any external tooling, scripts, or automation depend on the `pa-` prefix to identify portainer-automation releases, they will break. Confirm this is intentional and coordinate with any consumers. 2. **⚠️ Prod promotion assumes test image exists** — The prod path does `docker pull "${REG}:test"` which assumes a `test`-tagged image already exists in the registry. If the test workflow has never run or recently failed, this step will fail. Consider adding a fallback or validation step. 3. **Minor: Workflow name change** — The workflow name changed from `portainer-automation build and push` to `Build & Push Portainer Automation`. Verify that no notifications or dashboards filter on the old workflow name. 4. **Optional: Add `if: success()` guard** — The `build-and-push` job depends on `version` but doesn't have an explicit `if: success()` condition. While not strictly required, adding it makes the dependency intent explicit. ### Approval Status **APPROVED** — Well-structured refactor. The concerns above are non-blocking but should be reviewed before merge.

Linus commented

2026-07-08 20:01:19 +00:00

Technical Review Summary

Effort Estimate

Estimated: S (2-5 days — moderate refactor of existing workflow with new logic for env handling, semver, and promotion)
Confidence: High
Key assumptions: Docker registry access and CI runner are already operational

Complexity Assessment

Complexity: Medium — conditional logic for environment detection, semver bump calculation, and build-vs-promote branching adds moderate complexity
Risk: Medium — git tag prefix change (pa- → none) could impact downstream consumers; prod promotion depends on test image existence
Technical debt: None introduced — in fact, this reduces duplication

Implementation Checklist

Parameterized workflow with workflow_dispatch support
Environment validation with early failure
Semver logic (PATCH for test, MINOR for prod)
Conditional build vs. promote flow
Multi-branch trigger support (test + main)
Manual testing of all trigger scenarios

## Technical Review Summary ### Effort Estimate - **Estimated**: S (2-5 days — moderate refactor of existing workflow with new logic for env handling, semver, and promotion) - **Confidence**: High - **Key assumptions**: Docker registry access and CI runner are already operational ### Complexity Assessment - **Complexity**: Medium — conditional logic for environment detection, semver bump calculation, and build-vs-promote branching adds moderate complexity - **Risk**: Medium — git tag prefix change (`pa-` → none) could impact downstream consumers; prod promotion depends on test image existence - **Technical debt**: None introduced — in fact, this reduces duplication ### Implementation Checklist - [x] Parameterized workflow with `workflow_dispatch` support - [x] Environment validation with early failure - [x] Semver logic (PATCH for test, MINOR for prod) - [x] Conditional build vs. promote flow - [x] Multi-branch trigger support (test + main) - [ ] Manual testing of all trigger scenarios

Linus added the

labels 2026-07-08 20:01:20 +00:00

hitanshu commented

2026-07-08 20:09:01 +00:00

Regarding the concerns:

We don't gave any consumers for this, a change won't hurt, @Polly create an issue to reflect this in PORTAINER_STACK.md and add it to backlog so we address it.
This is by design, if someone tries to hurry to PROD without testing in lower envs. stuff should fail.

Regarding the concerns: 1. We don't gave any consumers for this, a change won't hurt, @Polly create an issue to reflect this in `PORTAINER_STACK.md` and add it to backlog so we address it. 2. This is by design, if someone tries to hurry to PROD without testing in lower envs. stuff should fail.

hitanshu merged commit 634794e7d3 into test

2026-07-08 20:09:41 +00:00

Linus commented

2026-07-08 20:12:13 +00:00

Acknowledged ✅

Thanks for the clarifications, @hitanshu. Both concerns are resolved:

Tag prefix (pa-): Understood — no existing consumers, so the change is safe. Appreciate the action item for @Polly to update PORTAINER_STACK.md and track it in the backlog.
Prod promotion depending on test image: Understood — this is an intentional guardrail. The explicit failure on missing test image is a feature, not a bug. Good design choice.

The PR has already been merged. These responses satisfy all the concerns raised in the review. No further action needed from my end.

## Acknowledged ✅ Thanks for the clarifications, @hitanshu. Both concerns are resolved: 1. **Tag prefix (`pa-`)**: Understood — no existing consumers, so the change is safe. Appreciate the action item for @Polly to update `PORTAINER_STACK.md` and track it in the backlog. 2. **Prod promotion depending on test image**: Understood — this is an intentional guardrail. The explicit failure on missing test image is a feature, not a bug. Good design choice. The PR has already been merged. These responses satisfy all the concerns raised in the review. No further action needed from my end.

Polly referenced this pull request

2026-07-08 20:12:37 +00:00

Update PORTAINER_STACK.md to reflect git tag prefix change #142

Polly commented

2026-07-08 20:12:46 +00:00

Backlog issue created: #142 — Update PORTAINER_STACK.md to reflect git tag prefix change

Added to milestone Portainer Automation — Production & Parameterization (#5) with docs / effort:xs / priority:low labels.

The issue covers removing references to the old pa- tag prefix and documenting the new plain semver convention (0.x.y) in PORTAINER_STACK.md.

Backlog issue created: **#142** — *Update PORTAINER_STACK.md to reflect git tag prefix change* Added to milestone **Portainer Automation — Production & Parameterization** (#5) with `docs` / `effort:xs` / `priority:low` labels. The issue covers removing references to the old `pa-` tag prefix and documenting the new plain semver convention (`0.x.y`) in PORTAINER_STACK.md.

Polly referenced this pull request

2026-07-09 17:24:28 +00:00

Parameterize portainer-automation build workflow for multi-environment reuse #139

Sign in to join this conversation.

No reviewers