GitHub Actions Docker Workflow Best Practices

GitHub Actions Docker Workflow: Build, Tag, and Push Images

Automating Docker builds is a crucial part of modern DevOps. With a GitHub Actions Docker workflow, you can streamline building, tagging, and pushing Docker images to container registries like GHCR, Docker Hub, and Harbor. This approach follows industry best practices while improving reliability and developer efficiency.

Whether you’re new to CI/CD automation or want to refine your existing setup, this guide covers essential steps, versioning strategies, and registry-specific instructions. In addition, ZippyOPS provides consulting, implementation, and managed services for DevOps, DevSecOps, DataOps, Cloud, Automated Ops, Microservices, Infrastructure, and Security to help your teams implement these workflows efficiently. Learn more about ZippyOPS services.

---

Benefits of a GitHub Actions Docker Workflow

Implementing a GitHub Actions Docker workflow brings several advantages:

• Shared builds: Streamline dependencies and configurations across teams for consistent results.
• Saves build minutes: Developers can use prebuilt images instead of rebuilding from scratch.
• Version control: Image tags make it easier to trace previous builds and pinpoint issues.

Automating Docker builds reduces human errors and accelerates release cycles. Moreover, this workflow aligns with best practices recommended by Docker.

---

Building a Docker Image with GitHub Actions

Using GitHub Actions ensures that Docker builds remain consistent. You only need to replace your existing build commands in the workflow YAML. Typically, images are named after your GitHub repository using the GITHUB_REPOSITORY variable.

Example YAML:

name: Build Docker image
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Build and tag image
        run: |
          COMMIT_SHA=$(echo $GITHUB_SHA | cut -c1-7)
          docker build -t ${{ github.repository }}:$COMMIT_SHA -f path/to/Dockerfile .

This ensures that each image build is linked to a specific commit hash for traceability.

---

Versioning Your Docker Images

Proper versioning prevents issues caused by using generic latest tags. Two common strategies are:

Using the GitHub Commit Hash

GitHub sets default environment variables, including GITHUB_SHA, which stores the commit hash. Using the first seven digits is a reliable way to tag images and trace builds.

Example YAML:

- name: Build and tag image
  run: |
    COMMIT_SHA=$(echo $GITHUB_SHA | cut -c1-7)
    docker build -t ${{ github.repository }}:$COMMIT_SHA -f path/to/Dockerfile .

Semantic Versioning (SemVer)

If your project uses version numbers, following the SemVer specification ensures consistency. Assuming your app’s version is in version.txt:

- name: Get version
  run: |
    export VERSION=$(cat version.txt)
    echo "Version: $VERSION"
- name: Build and tag image
  run: docker build -t ${{ github.repository }}:$VERSION -f path/to/Dockerfile .

This approach works well for releases and patch updates.

---

Pushing Docker Images to a Container Registry

After building and tagging, pushing Docker images is straightforward. The workflow generally involves:

1. Storing credentials securely as repository secrets.
2. Using echo to pipe credentials for registry login.
3. Adding the build command.
4. Executing the push command according to registry requirements.

Splitting each step into separate actions improves traceability in case of failures.

---

Pushing to GHCR

1. Generate a personal access token: Go to Settings → Developer → New personal access token (classic) and select write:packages.
2. Store it as a repository secret named GHCR_TOKEN.

Example workflow snippet:

- name: Log in to ghcr.io
  run: echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
- name: Build and tag image
  run: |
    COMMIT_SHA=$(echo $GITHUB_SHA | cut -c1-7)
    docker build -t ghcr.io/${{ github.repository_owner }}/${{ github.repository }}:$COMMIT_SHA -f path/to/Dockerfile .
- name: Push image to GHCR
  run: docker push ghcr.io/${{ github.repository_owner }}/${{ github.repository }}:$COMMIT_SHA

---

Pushing to Docker Hub

1. Store Docker Hub credentials as repository secrets:
   • DOCKERHUB_USERNAME
   • DOCKERHUB_PASSWORD
2. Ensure your Docker Hub repo exists before pushing.

Workflow example:

- name: Log in to Docker Hub
  run: |
    echo ${{ secrets.DOCKERHUB_PASSWORD }} | docker login -u ${{ secrets.DOCKERHUB_USERNAME }} --password-stdin
- name: Build and tag image
  run: |
    COMMIT_SHA=$(echo $GITHUB_SHA | cut -c1-7)
    docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/${{ github.repository }}:$COMMIT_SHA -f path/to/Dockerfile .
- name: Push image to Docker Hub
  run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/${{ github.repository }}:$COMMIT_SHA

---

Pushing to Harbor

1. Store Harbor credentials and registry URL as secrets:
   • HARBOR_CREDENTIALS → username:password
   • HARBOR_REGISTRY_URL → URL of your Harbor registry

Workflow example:

- name: Log in to Harbor
  run: |
    echo ${{ secrets.HARBOR_CREDENTIALS }} | base64 --decode | docker login -u $(cut -d ':' -f1 <<< "${{ secrets.HARBOR_CREDENTIALS }}") --password-stdin ${{ secrets.HARBOR_REGISTRY_URL }}
- name: Build and tag image
  run: |
    COMMIT_SHA=$(echo $GITHUB_SHA | cut -c1-7)
    docker build -t ${{ secrets.HARBOR_REGISTRY_URL }}/project-name/${{ github.repository }}:$COMMIT_SHA -f path/to/Dockerfile .
- name: Push image to Harbor
  run: docker push ${{ secrets.HARBOR_REGISTRY_URL }}/project-name/${{ github.repository }}:$COMMIT_SHA

---

ZippyOPS Support for Docker and CI/CD

For teams looking to scale and secure their workflows, ZippyOPS provides professional services for:

• DevOps, DevSecOps, DataOps, and Cloud Automation
• Microservices architecture and infrastructure management
• Automated Ops, AIOps, and MLOps solutions
• Security integrations and compliance

You can explore our solutions, products, and YouTube demos to accelerate your CI/CD adoption. Our experts ensure reliable Docker builds and registry deployments while optimizing your DevOps pipelines.

---

Conclusion for GitHub Actions Docker Workflow

A well-structured GitHub Actions Docker workflow not only improves developer productivity but also ensures version control, security, and repeatability across environments. Following the steps above, your team can automate Docker builds and push images safely to GHCR, Docker Hub, or Harbor. At the same time, leveraging ZippyOPS consulting and managed services guarantees that your CI/CD pipelines remain robust and scalable.

For professional assistance or a tailored workflow setup, contact ZippyOPS at sales@zippyops.com.