Docker Build

Build and push container images using the docker-login + docker-build-push templates

Build and push images to a generic Docker registry (Docker Hub, GHCR, Harbor, etc.). The recommended pattern is the collabops/docker-login + collabops/docker-build-push template combination.

collabops/docker-login is the generic Docker registry authentication template — it creates a .docker/config.json using username/password. Use gcloud-docker-auth for GCP Artifact Registry and aws-ecr-auth for AWS ECR instead. Pushing without authentication returns denied from the registry. See System Templates — Core for details.

Basic: Build & Push with Templates

Authenticate to the registry with docker-login, then build and push with docker-build-push. The two templates' default config paths line up, so no extra wiring is required.

name: docker-build-push

triggers:
  push:
    branches: [main]

jobs:
  build-and-push:
    # Enable Docker service
    services:
      - docker
    steps:
      # 1. Checkout source
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

      # 2. Registry login — creates .docker/config.json
      - name: registry-login
        uses: "collabops/docker-login@v1"
        with:
          registry: ghcr.io                       # Defaults to Docker Hub (docker.io) if omitted
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      # 3. Build & push — automatically uses the credentials above
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          tags: |
            ghcr.io/my-org/myapp:latest

Multi-Tag + Multi-Stage Build

Use docker-build-push's tags to push multiple tags at once, target to select a multi-stage build target, and build-args to pass build arguments.

name: multi-tag-build

triggers:
  push:
    branches: [main]
    tags: ["v*"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: my-org/my-app

jobs:
  build:
    services:
      - docker
    steps:
      - name: checkout
        uses: "collabops/checkout@v2"
        with:
          repo-url: "https://<collabops-host>/<workspace>/<repository>.git"

      # Registry login
      - name: registry-login
        uses: "collabops/docker-login@v1"
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      # Multi-stage target + multi-tag build & push
      - name: build-push
        uses: "collabops/docker-build-push@v1"
        with:
          # SHA tag + latest tag
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ collabops.sha }}
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
          target: production               # Multi-stage build target
          build-args: |
            NODE_ENV=production

Direct docker CLI — Selective Service Activation

You can also use the docker CLI directly instead of the templates. In that case you must authenticate manually with docker login --password-stdin. Declare services only on Jobs that need Docker.

name: selective-docker

triggers:
  push:
    branches: [main]

jobs:
  # Test — Docker not needed
  test:
    steps:
      - name: unit-test
        image: node:18
        run: npm test

  # Build — Docker needed
  docker-build:
    needs: [test]
    services:
      - docker                            # Docker service enabled only for this Job
    steps:
      - name: build-push
        image: docker:27.5-cli
        env:
          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
        run: |
          # With direct CLI usage, authenticate via docker login — pass the password on stdin
          echo "${REGISTRY_PASSWORD}" | docker login ghcr.io \
            -u "${REGISTRY_USERNAME}" --password-stdin

          docker build -t ghcr.io/my-org/myapp:${{ collabops.sha }} .
          docker push ghcr.io/my-org/myapp:${{ collabops.sha }}

  # Deploy — Docker not needed
  deploy:
    needs: [docker-build]
    steps:
      - name: deploy
        run: kubectl set image deployment/app app=ghcr.io/my-org/myapp:${{ collabops.sha }}

Key Points

The recommended approach is to authenticate with collabops/docker-login@v1 and then build/push with collabops/docker-build-push@v1.

The config-path of docker-login and docker-config of docker-build-push must point to the same location — the defaults already match.

Use gcloud-docker-auth for GCP Artifact Registry and aws-ecr-auth for AWS ECR.

services: [docker] alone enables the Docker service — omit it on Jobs that don't need it.

When using the docker CLI directly, you must handle authentication yourself with docker login --password-stdin.

Docker Build

Basic: Build & Push with Templates

Multi-Tag + Multi-Stage Build

Direct docker CLI — Selective Service Activation

Key Points

Table of Contents