migrate image tags from docker-compose.yaml to .env

Move BACKEND_TAG/FRONTEND_TAG into a co-located .env file that Docker
Compose loads automatically. CI now uses source/sed instead of yq for
tag operations, eliminating the yq dependency from all workflows except
lint-yaml. Rename the reusable workflow input from composePath to envPath.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AlexF4Dev

.claude/CLAUDE.md

@@ -17,14 +17,14 @@ Ready-to-use workflow files are in [`templates/gitops-ci/`](./templates/gitops-c
 
 ## Demo
 
-The `demo/` directory is a filled-in copy of the templates using `ghcr.io/aquasecurity/trivy` (public image with many semver tags). Backend pinned to `0.24.0`, frontend to `0.23.0` — deliberately old so tag discovery always finds a diff. See [demo/README.md](./demo/README.md).
+The `demo/` directory is a filled-in copy of the templates using `ghcr.io/aquasecurity/trivy` (public image with many semver tags). Backend pinned to `0.24.0`, frontend to `0.23.0` in `.env` — deliberately old so tag discovery always finds a diff. See [demo/README.md](./demo/README.md).
 
 The `.github/` directory contains the same demo workflows configured to actually run on this repo (cron disabled, deployment is echo-only).
 
 ## CI & Testing
 
 - **CI dry-run** (`.github/workflows/ci-dryrun.yaml`) — 5 parallel jobs: lint-yaml, lint-shell, version extraction, GHCR tag discovery, release PR dry-run. Runs on push to main and PRs.
-- **Local smoke test** (`test/smoke.sh`) — validates YAML, version extraction, semver regex, shellcheck, and placeholder replacement. Requires `yq` and `shellcheck` (gracefully skips if missing).
+- **Local smoke test** (`test/smoke.sh`) — validates YAML, `.env` file, version extraction, semver regex, shellcheck, and placeholder replacement. Requires `shellcheck` (gracefully skips if missing); `yq` needed only for YAML validation.
 - **Manual triggers** — all workflows support `workflow_dispatch` for on-demand testing.
 
 ## Key Patterns
@@ -35,16 +35,17 @@ The `.github/` directory contains the same demo workflows configured to actually
 4. **GHCR tag discovery** — Custom composite action that paginates the GHCR API, exchanges tokens for cross-org access, and filters by semver.
 5. **Auto-merge with retry** — `peter-evans/create-pull-request` + `nick-fields/retry` to handle branch protection race conditions.
 6. **Scheduled run cleanup** — Deletes old successful cron runs to keep the Actions tab clean.
-7. **Slack notifications** — Reports deployed versions extracted from `docker-compose.yaml`.
+7. **Slack notifications** — Reports deployed versions extracted from `.env`.
 
 ## Gotchas
 
 - `env` context is **not available** in `with:` for reusable workflow calls — values must be inlined.
 - `GITHUB_TOKEN` cannot read packages from other orgs — the ghcr-latest-tag action exchanges it for a GHCR-scoped token.
 - The default tag pattern is strict semver (`X.Y.Z`) to exclude arch-specific tags like `0.25.2-s390x`.
+- Image tags live in `.env` (not `docker-compose.yaml`). Docker Compose auto-loads `.env` from the same directory.
 
 ## Applying to Monorepos
 
 - Use `paths` filters to only build/deploy what changed
 - Combine with `turbo run build --filter=...[origin/main]` for Turborepo change detection
-- Call the reusable workflow multiple times with different `baseBranch`/`composePath` for staging vs production
+- Call the reusable workflow multiple times with different `baseBranch`/`envPath` for staging vs production

.github/workflows/ci-create-release-pr.yaml

@@ -2,7 +2,7 @@
 # GitOps Release PR Creator (Reusable Workflow) — Demo
 #
 # Called by ci-pr-trigger.yaml. Compares new image tags against current
-# docker-compose.yaml and creates/updates a PR if versions differ.
+# .env file and creates/updates a PR if versions differ.
 ###############################################################################
 
 name: "CI: Create release PR"
@@ -22,8 +22,8 @@ on:
         description: "New frontend image tag"
         required: false
         type: string
-      composePath:
-        description: "Path to docker-compose.yaml"
+      envPath:
+        description: "Path to .env file with image tags"
         required: true
         type: string
 
@@ -35,22 +35,15 @@ jobs:
         with:
           ref: ${{ inputs.baseBranch }}
 
-      - name: Install yq
-        uses: mikefarah/yq@v4.44.6
-
       - name: Read current image tags
         id: current
         run: |
-          backendImage=$(yq e '.services.backend.image' ${{ inputs.composePath }} | tr -d '"')
-          frontendImage=$(yq e '.services.frontend.image' ${{ inputs.composePath }} | tr -d '"')
-
-          currentBackendTag=${backendImage##*:}
-          currentFrontendTag=${frontendImage##*:}
+          source ${{ inputs.envPath }}
 
-          echo "currentBackendTag=${currentBackendTag}" >> $GITHUB_OUTPUT
-          echo "currentFrontendTag=${currentFrontendTag}" >> $GITHUB_OUTPUT
-          echo "Current backend: ${currentBackendTag}"
-          echo "Current frontend: ${currentFrontendTag}"
+          echo "currentBackendTag=${BACKEND_TAG}" >> $GITHUB_OUTPUT
+          echo "currentFrontendTag=${FRONTEND_TAG}" >> $GITHUB_OUTPUT
+          echo "Current backend: ${BACKEND_TAG}"
+          echo "Current frontend: ${FRONTEND_TAG}"
 
       - name: Update image tags if changed
         id: update
@@ -59,19 +52,19 @@ jobs:
           FRONTEND_TAG: ${{ inputs.frontendTag }}
           CURRENT_BACKEND_TAG: ${{ steps.current.outputs.currentBackendTag }}
           CURRENT_FRONTEND_TAG: ${{ steps.current.outputs.currentFrontendTag }}
-          COMPOSE_PATH: ${{ inputs.composePath }}
+          ENV_PATH: ${{ inputs.envPath }}
         run: |
           changed=false
 
           if [[ -n "${BACKEND_TAG}" && "${BACKEND_TAG}" != "${CURRENT_BACKEND_TAG}" ]]; then
             echo "Updating backend: ${CURRENT_BACKEND_TAG} -> ${BACKEND_TAG}"
-            yq -i ".services.backend.image = \"ghcr.io/aquasecurity/trivy:${BACKEND_TAG}\"" "${COMPOSE_PATH}"
+            sed -i "s/^BACKEND_TAG=.*/BACKEND_TAG=${BACKEND_TAG}/" "${ENV_PATH}"
             changed=true
           fi
 
           if [[ -n "${FRONTEND_TAG}" && "${FRONTEND_TAG}" != "${CURRENT_FRONTEND_TAG}" ]]; then
             echo "Updating frontend: ${CURRENT_FRONTEND_TAG} -> ${FRONTEND_TAG}"
-            yq -i ".services.frontend.image = \"ghcr.io/aquasecurity/trivy:${FRONTEND_TAG}\"" "${COMPOSE_PATH}"
+            sed -i "s/^FRONTEND_TAG=.*/FRONTEND_TAG=${FRONTEND_TAG}/" "${ENV_PATH}"
             changed=true
           fi
 

.github/workflows/ci-deployment-self-hosted.yaml

@@ -33,11 +33,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install yq
-        run: |
-          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.44.6/yq_linux_amd64
-          sudo chmod +x /usr/local/bin/yq
-
       - name: "[dry-run] Copy files to deployment directory"
         run: |
           echo "Would copy ${{ env.PROJECT_PATH }}/* -> ${{ env.REMOTE_PATH }}/"
@@ -54,12 +49,11 @@ jobs:
       - name: Get deployed versions
         id: versions
         run: |
-          BACKEND=$(yq e '.services.backend.image' ${{ env.PROJECT_PATH }}/docker-compose.yaml | rev | cut -d: -f1 | rev)
-          FRONTEND=$(yq e '.services.frontend.image' ${{ env.PROJECT_PATH }}/docker-compose.yaml | rev | cut -d: -f1 | rev)
-          echo "backend=${BACKEND}" >> $GITHUB_OUTPUT
-          echo "frontend=${FRONTEND}" >> $GITHUB_OUTPUT
-          echo "Backend: ${BACKEND}"
-          echo "Frontend: ${FRONTEND}"
+          source ${{ env.PROJECT_PATH }}/.env
+          echo "backend=${BACKEND_TAG}" >> $GITHUB_OUTPUT
+          echo "frontend=${FRONTEND_TAG}" >> $GITHUB_OUTPUT
+          echo "Backend: ${BACKEND_TAG}"
+          echo "Frontend: ${FRONTEND_TAG}"
 
   notify:
     needs: deploy

.github/workflows/ci-dryrun.yaml

@@ -56,41 +56,23 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install yq
-        run: |
-          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.44.6/yq_linux_amd64
-          sudo chmod +x /usr/local/bin/yq
-
-      - name: Extract and assert versions from demo compose
+      - name: Extract and assert versions from demo .env
         run: |
-          COMPOSE="demo/projects/demo-app/docker-compose.yaml"
-
-          # Method 1: rev | cut (used in deployment workflow)
-          BACKEND_REV=$(yq e '.services.backend.image' "$COMPOSE" | rev | cut -d: -f1 | rev)
-          FRONTEND_REV=$(yq e '.services.frontend.image' "$COMPOSE" | rev | cut -d: -f1 | rev)
+          ENV_FILE="demo/projects/demo-app/.env"
 
-          # Method 2: ${##*:} (used in release PR workflow)
-          backendImage=$(yq e '.services.backend.image' "$COMPOSE" | tr -d '"')
-          frontendImage=$(yq e '.services.frontend.image' "$COMPOSE" | tr -d '"')
-          BACKEND_PE=${backendImage##*:}
-          FRONTEND_PE=${frontendImage##*:}
+          source "${ENV_FILE}"
 
-          echo "rev|cut  — backend=${BACKEND_REV} frontend=${FRONTEND_REV}"
-          echo '##*:     — backend='"${BACKEND_PE}"' frontend='"${FRONTEND_PE}"
+          echo "backend=${BACKEND_TAG} frontend=${FRONTEND_TAG}"
 
           errors=0
-          for method in REV PE; do
-            bvar="BACKEND_${method}"
-            fvar="FRONTEND_${method}"
-            if [[ "${!bvar}" != "0.24.0" ]]; then
-              echo "FAIL: ${bvar}=${!bvar}, expected 0.24.0"
-              errors=$((errors + 1))
-            fi
-            if [[ "${!fvar}" != "0.23.0" ]]; then
-              echo "FAIL: ${fvar}=${!fvar}, expected 0.23.0"
-              errors=$((errors + 1))
-            fi
-          done
+          if [[ "${BACKEND_TAG}" != "0.24.0" ]]; then
+            echo "FAIL: BACKEND_TAG=${BACKEND_TAG}, expected 0.24.0"
+            errors=$((errors + 1))
+          fi
+          if [[ "${FRONTEND_TAG}" != "0.23.0" ]]; then
+            echo "FAIL: FRONTEND_TAG=${FRONTEND_TAG}, expected 0.23.0"
+            errors=$((errors + 1))
+          fi
 
           if [[ $errors -gt 0 ]]; then
             echo "::error::${errors} version extraction assertion(s) failed"
@@ -132,26 +114,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install yq
-        run: |
-          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/download/v4.44.6/yq_linux_amd64
-          sudo chmod +x /usr/local/bin/yq
-
       - name: Discover latest tag
         id: discover
         uses: ./templates/gitops-ci/.github/actions/ghcr-latest-tag
         with:
           image: "aquasecurity/trivy"
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Compare with demo compose
+      - name: Compare with demo .env
         env:
           LATEST_TAG: ${{ steps.discover.outputs.tag }}
         run: |
-          COMPOSE="demo/projects/demo-app/docker-compose.yaml"
+          ENV_FILE="demo/projects/demo-app/.env"
 
-          backendImage=$(yq e '.services.backend.image' "$COMPOSE" | tr -d '"')
-          currentTag=${backendImage##*:}
+          source "${ENV_FILE}"
+          currentTag="${BACKEND_TAG}"
 
           echo "Current pinned: ${currentTag}"
           echo "Latest on GHCR: ${LATEST_TAG}"
@@ -161,11 +138,11 @@ jobs:
           else
             echo "Tags differ — a release PR would update ${currentTag} -> ${LATEST_TAG}"
 
-            # Show what the updated compose would look like
-            cp "$COMPOSE" /tmp/compose-updated.yaml
-            yq -i ".services.backend.image = \"ghcr.io/aquasecurity/trivy:${LATEST_TAG}\"" /tmp/compose-updated.yaml
-            yq -i ".services.frontend.image = \"ghcr.io/aquasecurity/trivy:${LATEST_TAG}\"" /tmp/compose-updated.yaml
+            # Show what the updated .env would look like
+            cp "${ENV_FILE}" /tmp/env-updated
+            sed -i "s/^BACKEND_TAG=.*/BACKEND_TAG=${LATEST_TAG}/" /tmp/env-updated
+            sed -i "s/^FRONTEND_TAG=.*/FRONTEND_TAG=${LATEST_TAG}/" /tmp/env-updated
 
             echo "--- Diff ---"
-            diff "$COMPOSE" /tmp/compose-updated.yaml || true
+            diff "${ENV_FILE}" /tmp/env-updated || true
           fi

.github/workflows/ci-pr-trigger.yaml

@@ -52,7 +52,7 @@ jobs:
       baseBranch: "main"
       backendTag: ${{ needs.get-versions.outputs.backend_tag }}
       frontendTag: ${{ needs.get-versions.outputs.frontend_tag }}
-      composePath: "projects/demo-app/docker-compose.yaml"
+      envPath: "projects/demo-app/.env"
     secrets: inherit
 
   cleanup:

README.md

@@ -1,6 +1,6 @@
 # GitOps CI/CD Patterns
 
-Reusable GitHub Actions templates for automated GitOps deployments. Polls GHCR for new image tags, creates PRs to update `docker-compose.yaml`, and deploys on merge.
+Reusable GitHub Actions templates for automated GitOps deployments. Polls GHCR for new image tags, creates PRs to update a `.env` file (consumed by `docker-compose.yaml`), and deploys on merge.
 
 ## Structure
 
@@ -19,13 +19,14 @@ test/smoke.sh            # Local validation script
 cp -r templates/gitops-ci/.github /path/to/your/repo/
 cp templates/gitops-ci/deployment.sh /path/to/your/repo/projects/<name>/
 cp templates/gitops-ci/docker-compose.yaml /path/to/your/repo/projects/<name>/
+cp templates/gitops-ci/.env /path/to/your/repo/projects/<name>/
 ```
 
 See the [template README](./templates/gitops-ci/README.md) for full setup instructions.
 
 ## Demo
 
-The `demo/` directory is a working example using [`ghcr.io/aquasecurity/trivy`](https://github.com/aquasecurity/trivy/pkgs/container/trivy) — a public image with many semver tags. Backend pinned to `0.24.0`, frontend to `0.23.0` so tag discovery always finds newer versions.
+The `demo/` directory is a working example using [`ghcr.io/aquasecurity/trivy`](https://github.com/aquasecurity/trivy/pkgs/container/trivy) — a public image with many semver tags. Backend pinned to `0.24.0`, frontend to `0.23.0` in `.env` so tag discovery always finds newer versions.
 
 The `.github/` directory runs the same demo workflows on this repo (cron disabled, deployment is echo-only). Trigger manually:
 
@@ -49,7 +50,7 @@ CI runs automatically on push to main and PRs with 5 parallel validation jobs.
 ## How It Works
 
 1. **Trigger** — Polls GHCR on a schedule for the latest semver image tags
-2. **PR Creation** — Compares with current `docker-compose.yaml`, creates a PR if versions differ
+2. **PR Creation** — Compares with current `.env` file, creates a PR if versions differ
 3. **Deployment** — Merging the PR triggers deployment to the target server
 
 Three deployment strategies: EC2/AWS, SSH, or self-hosted runner.

demo/.github/workflows/ci-create-release-pr.yaml

@@ -2,7 +2,7 @@
 # GitOps Release PR Creator (Reusable Workflow) — Demo
 #
 # Called by ci-pr-trigger.yaml. Compares new image tags against current
-# docker-compose.yaml and creates/updates a PR if versions differ.
+# .env file and creates/updates a PR if versions differ.
 ###############################################################################
 
 name: "CI: Create release PR"
@@ -22,8 +22,8 @@ on:
         description: "New frontend image tag"
         required: false
         type: string
-      composePath:
-        description: "Path to docker-compose.yaml"
+      envPath:
+        description: "Path to .env file with image tags"
         required: true
         type: string
 
@@ -35,22 +35,15 @@ jobs:
         with:
           ref: ${{ inputs.baseBranch }}
 
-      - name: Install yq
-        uses: mikefarah/yq@v4.44.6
-
       - name: Read current image tags
         id: current
         run: |
-          backendImage=$(yq e '.services.backend.image' ${{ inputs.composePath }} | tr -d '"')
-          frontendImage=$(yq e '.services.frontend.image' ${{ inputs.composePath }} | tr -d '"')
-
-          currentBackendTag=${backendImage##*:}
-          currentFrontendTag=${frontendImage##*:}
+          source ${{ inputs.envPath }}
 
-          echo "currentBackendTag=${currentBackendTag}" >> $GITHUB_OUTPUT
-          echo "currentFrontendTag=${currentFrontendTag}" >> $GITHUB_OUTPUT
-          echo "Current backend: ${currentBackendTag}"
-          echo "Current frontend: ${currentFrontendTag}"
+          echo "currentBackendTag=${BACKEND_TAG}" >> $GITHUB_OUTPUT
+          echo "currentFrontendTag=${FRONTEND_TAG}" >> $GITHUB_OUTPUT
+          echo "Current backend: ${BACKEND_TAG}"
+          echo "Current frontend: ${FRONTEND_TAG}"
 
       - name: Update image tags if changed
         id: update
@@ -59,19 +52,19 @@ jobs:
           FRONTEND_TAG: ${{ inputs.frontendTag }}
           CURRENT_BACKEND_TAG: ${{ steps.current.outputs.currentBackendTag }}
           CURRENT_FRONTEND_TAG: ${{ steps.current.outputs.currentFrontendTag }}
-          COMPOSE_PATH: ${{ inputs.composePath }}
+          ENV_PATH: ${{ inputs.envPath }}
         run: |
           changed=false
 
           if [[ -n "${BACKEND_TAG}" && "${BACKEND_TAG}" != "${CURRENT_BACKEND_TAG}" ]]; then
             echo "Updating backend: ${CURRENT_BACKEND_TAG} -> ${BACKEND_TAG}"
-            yq -i ".services.backend.image = \"ghcr.io/aquasecurity/trivy:${BACKEND_TAG}\"" "${COMPOSE_PATH}"
+            sed -i "s/^BACKEND_TAG=.*/BACKEND_TAG=${BACKEND_TAG}/" "${ENV_PATH}"
             changed=true
           fi
 
           if [[ -n "${FRONTEND_TAG}" && "${FRONTEND_TAG}" != "${CURRENT_FRONTEND_TAG}" ]]; then
             echo "Updating frontend: ${CURRENT_FRONTEND_TAG} -> ${FRONTEND_TAG}"
-            yq -i ".services.frontend.image = \"ghcr.io/aquasecurity/trivy:${FRONTEND_TAG}\"" "${COMPOSE_PATH}"
+            sed -i "s/^FRONTEND_TAG=.*/FRONTEND_TAG=${FRONTEND_TAG}/" "${ENV_PATH}"
             changed=true
           fi
 

demo/.github/workflows/ci-deployment-self-hosted.yaml

@@ -48,10 +48,9 @@ jobs:
       - name: Get deployed versions
         id: versions
         run: |
-          BACKEND=$(yq e '.services.backend.image' ${{ env.PROJECT_PATH }}/docker-compose.yaml | rev | cut -d: -f1 | rev)
-          FRONTEND=$(yq e '.services.frontend.image' ${{ env.PROJECT_PATH }}/docker-compose.yaml | rev | cut -d: -f1 | rev)
-          echo "backend=${BACKEND}" >> $GITHUB_OUTPUT
-          echo "frontend=${FRONTEND}" >> $GITHUB_OUTPUT
+          source ${{ env.PROJECT_PATH }}/.env
+          echo "backend=${BACKEND_TAG}" >> $GITHUB_OUTPUT
+          echo "frontend=${FRONTEND_TAG}" >> $GITHUB_OUTPUT
 
   notify:
     needs: deploy

demo/.github/workflows/ci-pr-trigger.yaml

@@ -52,7 +52,7 @@ jobs:
       baseBranch: "main"
       backendTag: ${{ needs.get-versions.outputs.backend_tag }}
       frontendTag: ${{ needs.get-versions.outputs.frontend_tag }}
-      composePath: "projects/demo-app/docker-compose.yaml"
+      envPath: "projects/demo-app/.env"
     secrets: inherit
 
   cleanup:

demo/README.md

@@ -18,10 +18,10 @@ Uses [`ghcr.io/aquasecurity/trivy`](https://github.com/aquasecurity/trivy/pkgs/c
 | `{{REMOTE_PATH}}` | `/opt/demo-app` | Typical server deploy path |
 | `{{RUNNER_LABEL}}` | `demo-runner` | Self-hosted runner label |
 
-## Pinned Versions
+## Pinned Versions (in `.env`)
 
-- Backend: `0.24.0`
-- Frontend: `0.23.0`
+- `BACKEND_TAG=0.24.0`
+- `FRONTEND_TAG=0.23.0`
 
 These are old enough that the GHCR tag discovery will always find newer versions, exercising the full PR-creation flow.
 
@@ -39,6 +39,7 @@ demo/
       ci-deployment-self-hosted.yaml  # Deploys via self-hosted runner
   projects/
     demo-app/
-      docker-compose.yaml    # Pinned to trivy 0.24.0 / 0.23.0
+      .env                   # Pinned to trivy 0.24.0 / 0.23.0
+      docker-compose.yaml    # References ${BACKEND_TAG} / ${FRONTEND_TAG} from .env
       deployment.sh          # Standard deployment script
 ```