Docker Compose Version Sync

This guide explains the automated synchronization of Docker image versions between the Maven POM and Docker Compose files.

Overview

Docker Compose files in src/main/docker/ reference specific Docker image versions. These versions must match the project dependencies defined in pom.xml. The sync workflow automates this synchronization.

How It Works

When pom.xml is pushed to the develop branch, a GitHub Actions workflow:

  1. Extracts version properties from pom.xml

  2. Updates image tags in Docker Compose files

  3. Commits and pushes changes if any updates were made

Version Properties

The workflow extracts these properties from pom.xml:

Property Source Used For

revision

<revision> property

Gateway/UI image version

admin-service.version

<admin-service.version> property

Admin Service image version

Files Updated

The workflow updates these Docker Compose files:

src/main/docker/dev.yml

Full stack compose file (Gateway, Admin Service, MySQL)
src/main/docker/admin-service.yml

Admin Service and MySQL only

Workflow Configuration

sync-docker-versions.yml
name: 'Sync Docker Compose Versions'

on:
  push:
    branches:
      - develop
    paths:
      - 'pom.xml'

env:
  DOCKER_REGISTRY: christhonie
  PORTAL_IMAGE_NAME: registration-portal  # or membership-ui, event-admin-ui
  ADMIN_IMAGE_NAME: event-admin-service
  DEV_YML_PATH: src/main/docker/dev.yml
  ADMIN_SERVICE_YML_PATH: src/main/docker/admin-service.yml

jobs:
  sync-versions:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract versions from POM
        id: versions
        run: |
          REVISION=$(grep -oP '(?<=<revision>)[^<]+' pom.xml | head -1)
          echo "revision=$REVISION" >> $GITHUB_OUTPUT

          ADMIN_VERSION=$(grep -oP '(?<=<admin-service.version>)[^<]+' pom.xml | head -1)
          echo "admin_version=$ADMIN_VERSION" >> $GITHUB_OUTPUT

      - name: Update Docker Compose files
        run: |
          PORTAL_IMAGE="${DOCKER_REGISTRY}/${PORTAL_IMAGE_NAME}"
          ADMIN_IMAGE="${DOCKER_REGISTRY}/${ADMIN_IMAGE_NAME}"

          sed -i "s|${PORTAL_IMAGE}:[^[:space:]]*|${PORTAL_IMAGE}:${{ steps.versions.outputs.revision }}|g" "$DEV_YML_PATH"
          sed -i "s|${ADMIN_IMAGE}:[^[:space:]]*|${ADMIN_IMAGE}:${{ steps.versions.outputs.admin_version }}|g" "$DEV_YML_PATH"
          sed -i "s|${ADMIN_IMAGE}:[^[:space:]]*|${ADMIN_IMAGE}:${{ steps.versions.outputs.admin_version }}|g" "$ADMIN_SERVICE_YML_PATH"

      - name: Check for changes
        id: changes
        run: |
          if git diff --quiet "$DEV_YML_PATH" "$ADMIN_SERVICE_YML_PATH"; then
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "changed=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit and push changes
        if: steps.changes.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add "$DEV_YML_PATH" "$ADMIN_SERVICE_YML_PATH"
          git commit -m "[AutoTask] Sync Docker image versions with POM"
          git push

POM Configuration

Ensure your pom.xml has the required properties:

<properties>
    <revision>1.2.4-SNAPSHOT</revision>
    <admin-service.version>2.3.1-SNAPSHOT</admin-service.version>
</properties>

Commit Message Format

The workflow creates commits with this format:

[AutoTask] Sync Docker image versions with POM

- registration-portal: 1.2.4-SNAPSHOT
- event-admin-service: 2.3.1-SNAPSHOT

Generated by GitHub Actions

When Sync Runs

The workflow triggers when:

  • A push is made to the develop branch

  • The push includes changes to pom.xml

It does not run for:

  • Pull requests (only merged changes)

  • Other branches

  • Changes to files other than pom.xml

Manual Version Updates

If you need to update versions manually:

  1. Edit pom.xml with new version values

  2. Push to develop branch

  3. The workflow will automatically update Docker Compose files

Alternatively, edit both pom.xml and the compose files in the same commit if you want to avoid the automated commit.

Troubleshooting

Workflow Doesn’t Run

  • Verify the push is to develop branch

  • Check that pom.xml was modified in the push

  • Review GitHub Actions permissions

Version Not Updated

  • Ensure the image name in compose file matches PORTAL_IMAGE_NAME or ADMIN_IMAGE_NAME

  • Check the grep pattern matches your POM structure

  • Verify the sed replacement pattern works with your image format

Commit Loop

The workflow uses github-actions[bot] as the committer, which doesn’t trigger additional workflow runs. If you see a loop:

  • Check for custom workflows that trigger on compose file changes

  • Verify the paths filter is correctly set to only pom.xml

Customizing for New Projects

When adding this workflow to a new project:

  1. Copy the workflow file to .github/workflows/

  2. Update PORTAL_IMAGE_NAME to match your project’s image name

  3. Ensure pom.xml has both revision and admin-service.version properties

  4. Create the Docker Compose files with the expected image references