Implementing CI/CD with GitHub Actions to Deploy Docker‑Compose Services

GitHub Actions workflow that builds and deploys a Docker‑Compose stack

1. Prerequisites

• A GitHub repository that contains your docker-compose.prod.yml and a Dockerfile for each service.
• A Docker registry where the images can be stored (DigitalOcean Container Registry, Docker Hub, etc.).
• SSH access to the target host (a DigitalOcean droplet, Hetzner server, etc.) with a private key added to the repository secrets.
• The host must have Docker Compose installed and a directory where the compose file will live.

2. Store secrets safely

Add the following secrets in Settings → Secrets → Actions:

• SERVER_ENV_PROD, the full contents of the .env file required by your compose file.
• DIGITALOCEAN_ACCESS_TOKEN, API token for the registry login.
• GL_SSH_HOST, GL_SSH_USERNAME, GL_SSH_SECRET, GL_SSH_PORT, SSH connection details.

To make the secrets visible inside the job you also need to declare the environment name on the job level, otherwise the secrets stay hidden see this answer.

3. Build and push images

The workflow below follows the pattern described in a high‑voted Stack Overflow answer see source. It checks out the code, creates the .env file, builds the images with Docker Compose, logs in to the registry and pushes the images.

name: Server Build & Push

on:
  push:
    branches: [main]
    paths:
      - 'server/**'
      - 'shared/**'
      - docker-compose.prod.yml
      - Dockerfile

jobs:
  build_and_push:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Checkout the repo
        uses: actions/checkout@v2
      - name: Create env file
        run: |
          touch .env
          echo "${{ secrets.SERVER_ENV_PROD }}" > .env
          cat .env
      - name: Build image
        run: docker compose -f docker-compose.prod.yml build

      - name: Install doctl
        uses: digitalocean/action-doctl@v2
        with:
          token: ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }}

      - name: Log in to DO Container Registry
        run: doctl registry login --expiry-seconds 600

      - name: Push image to DO Container Registry
        run: docker compose -f docker-compose.prod.yml push

      - name: Deploy Stack
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.GL_SSH_HOST }}
          username: ${{ secrets.GL_SSH_USERNAME }}
          key: ${{ secrets.GL_SSH_SECRET }}
          port: ${{ secrets.GL_SSH_PORT }}
          script: |
            cd /srv/www/game
            ./init.sh

The ./init.sh script on the server is a tiny wrapper that runs the actual compose deployment:

docker stack deploy -c <(docker-compose -f docker-compose.yml config) game --with-registry-auth

The --with-registry-auth flag ensures the remote Docker engine can pull private images that were just pushed see source.

4. Deploy with docker‑compose on the target host

1. Copy the compose file, the workflow pushes the images but does not copy the compose file; you can either keep the file in the repo and pull it on the server via git pull, or scp it in the SSH step.
2. Run the init script, the SSH action executes ./init.sh, which expands the compose file with the .env values (Docker Compose does not read .env when used with docker stack deploy, so the <(docker-compose … config) trick pre‑processes it).
3. Verify, after the stack is up, check the service status with docker service ls and docker stack ps game.

5. Common pitfalls and how to avoid them

• Missing environment on the job, without the environment: key the secrets stay hidden and the build will fail when it tries to read $SERVER_ENV_PROD.
• Registry login expiry, the doctl registry login --expiry-seconds 600 command gives a short‑lived token; keep the push step within that window.
• Compose file paths, the paths: filter in the on: block must include every file that, when changed, should trigger a new build; otherwise a change in a service’s Dockerfile will be ignored.
• SSH host key verification, the Appleboy SSH action disables strict host key checking by default; for production you may want to add a known‑hosts file to avoid man‑in‑the‑middle risks.
• Bandwidth constraints, use multi‑stage Dockerfiles and keep base images small (Alpine, Distroless) to minimise the data transferred over limited African links.

Quick checklist you can copy

Deploying Docker‑Compose with GitHub Actions is a lightweight way to get continuous delivery without moving to a full Kubernetes stack. It fits well for NGOs, government agencies or startups that need a predictable, auditable pipeline while keeping operational costs low.

Sources

• Question 67023441, answer with 13 votes on Stack Overflow by Azarro, licensed CC BY-SA 4.0
• Problem with passing env variables from GitHub Actions to Docker container, accepted answer on Stack Overflow by Alex Lebedev, licensed CC BY-SA 4.0

Ready to turn this into a production‑grade pipeline? Talk to our team about it.