Open
Conversation
added 2 commits
March 12, 2026 00:49
# 🐳 Docker Image GitHub Actions Workflow – Complete Guide
You want to create a GitHub Actions workflow to build and push a Docker image automatically whenever you push code or create a release. This is a crucial part of modern CI/CD pipelines, especially for projects involving microservices, AI models, or deployable applications.
Below I'll provide you with a **production‑ready template** for `.github/workflows/docker-image.yml`, explain each part, and show you how to customize it for your needs (e.g., pushing to Docker Hub, GitHub Container Registry, or both).
---
## 📁 File Location
Place this file in your repository at:
```
.github/workflows/docker-image.yml
```
---
## 🚀 Full Workflow Example
```yaml
name: Build and Push Docker Image
on:
push:
branches: [ "main", "develop" ]
tags: [ "v*.*.*" ]
pull_request:
branches: [ "main" ]
release:
types: [ published ]
env:
REGISTRY: docker.io # change to ghcr.io for GitHub Container Registry
IMAGE_NAME: ${{ github.repository }} # e.g., username/repo
jobs:
build-and-push:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write # needed for GHCR
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
# If you want to push to GitHub Container Registry instead (or in addition)
# - name: Log in to GHCR
# uses: docker/login-action@v3
# with:
# registry: ghcr.io
# username: ${{ github.actor }}
# password: ${{ secrets.GITHUB_TOKEN }}
- name: Extract metadata (tags, labels) for Docker
id: meta
uses: docker/metadata-action@v5
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha,format=long
type=raw,value=latest,enable={{is_default_branch}}
- name: Build and push Docker image
uses: docker/build-push-action@v5
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max
platforms: linux/amd64,linux/arm64 # optional: multi‑arch
```
---
## 🔍 Step‑by‑Step Explanation
### 1. **Triggers (`on`)**
The workflow runs on:
- `push` to `main` or `develop` branches.
- `push` of tags matching `v*.*.*` (e.g., `v1.2.3`).
- `pull_request` to `main` (builds only, does **not** push).
- `release` published (ideal for final tagging).
Adjust the branches and patterns to match your workflow.
### 2. **Environment Variables**
- `REGISTRY`: set to `docker.io` for Docker Hub, or `ghcr.io` for GitHub Container Registry.
- `IMAGE_NAME`: uses `github.repository` (e.g., `yourusername/yourrepo`). You can hardcode a custom name if needed.
### 3. **Permissions**
- `packages: write` is required if you push to GHCR. For Docker Hub you don’t need it, but it’s harmless to keep.
### 4. **Checkout**
Fetches your code so the Docker build can use it.
### 5. **Set up Docker Buildx**
Enables advanced features like multi‑platform builds and better caching.
### 6. **Login to Registry**
- **Docker Hub**: uses secrets `DOCKER_USERNAME` and `DOCKER_PASSWORD`.
(Create these in your repository **Settings → Secrets and variables → Actions**.)
- **GHCR**: uses the built‑in `GITHUB_TOKEN` – no extra secrets needed. Uncomment the second login block if you want to push there as well.
### 7. **Metadata Extraction**
The `docker/metadata-action` generates Docker tags and labels based on the git reference.
Common tag types:
- `type=ref,event=branch` → e.g., `main`, `develop`
- `type=ref,event=pr` → `pr-123`
- `type=semver,pattern={{version}}` → for tags: `v1.2.3`, `v1.2`, `v1`
- `type=sha,format=long` → full commit hash
- `type=raw,value=latest,enable={{is_default_branch}}` → adds `latest` only on the default branch
You can customise the tag list as you like.
### 8. **Build and Push**
- `push: true` only when the event is **not** a pull request (to avoid pushing PR images).
- `tags` and `labels` come from the metadata step.
- **Caching** (`cache-from` / `cache-to` with `type=gha`) uses GitHub Actions cache to speed up subsequent builds.
- `platforms`: optional, enables multi‑architecture images (e.g., both Intel and ARM). Requires QEMU setup (see below).
---
## 🧪 Adding Multi‑Platform Builds
If you need images for different CPU architectures (e.g., `linux/arm64` for Raspberry Pi), include these steps before `buildx`:
```yaml
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
```
Then in the build step, add:
```yaml
platforms: linux/amd64,linux/arm64,linux/arm/v7
```
---
## 🔒 Security Scanning
Integrate vulnerability scanning to ensure your images are safe:
```yaml
- name: Scan image with Trivy
uses: aquasecurity/trivy-action@master
with:
image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }}
format: 'sarif'
output: 'trivy-results.sarif'
- name: Upload Trivy results to GitHub Security tab
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: 'trivy-results.sarif'
```
Add this **after** the build step.
---
## 🧪 Running Tests Before Building
You can add a separate job for testing, or include test steps in the same job:
```yaml
- name: Run unit tests
run: |
docker build --target test -t test-image .
docker run --rm test-image npm test
```
(Assumes your Dockerfile has a `test` stage.)
---
## 📦 Using the GitHub Container Registry (GHCR)
If you prefer GHCR over Docker Hub:
- Set `REGISTRY: ghcr.io`
- Use the GHCR login step (already shown, commented out).
- Your image will be available at `ghcr.io/yourusername/yourrepo:tag`.
---
## 🔐 Required Secrets
| Secret Name | Description |
|-------------|-------------|
| `DOCKER_USERNAME` | Your Docker Hub username |
| `DOCKER_PASSWORD` | Docker Hub password or access token (recommended) |
If you use two‑factor authentication on Docker Hub, create an **access token** (Account Settings → Security → New Access Token) and use that as the password.
For GHCR, no secrets are needed – `GITHUB_TOKEN` is automatically provided.
---
## 🧠 Customizing for Your Project
### **Context Path**
If your Dockerfile is not in the repository root, change `context` to the correct folder, e.g.:
```yaml
context: ./my-service
```
### **Dockerfile Name**
If your Dockerfile has a different name, add:
```yaml
file: ./my-service/Dockerfile.custom
```
### **Tagging Overrides**
Add custom tags using `type=raw`:
```yaml
tags: |
type=raw,value=production,enable=${{ github.ref == 'refs/heads/production' }}
```
---
## ✅ Example Workflow in Action
1. You push a commit to `main`.
2. GitHub Actions triggers the workflow.
3. It builds the Docker image with tags: `main`, `latest`, and the commit SHA.
4. The image is pushed to Docker Hub.
5. (Optional) Trivy scans it and uploads results.
When you create a release (or push a tag `v1.2.3`), it also builds and pushes `v1.2.3`, `v1.2`, `v1`.
---
## 📚 Next Steps
1. **Copy the template** into your repository.
2. **Add secrets** if using Docker Hub.
3. **Commit and push** to see the first run.
4. **Check the Actions tab** in your GitHub repo to monitor progress.
You now have a fully automated Docker build pipeline. Combine it with your Firebase AI, ESP32, and WebRTC projects to deploy microservices effortlessly. Let me know if you need help adapting it to a specific part of your system! 🚀
github-actions
bot
added
the
triage
Contributor
How to review these changes 👓Thank you for your contribution. To review these changes, choose one of the following options: A Hubber will need to deploy your changes internally to review. Table of review linksNote: Please update the URL for your staging server or codespace. This pull request contains code changes, so we will not generate a table of review links. 🤖 This comment is automatically generated. |
itraveltheworld2020-max
left a comment
itraveltheworld2020-max
left a comment
There was a problem hiding this comment.
whoever this person thinks they are they should know me better than to attack me i will never stop not even against a robot . dick
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why:
Closes:
What's being changed (if available, include any code snippets, screenshots, or gifs):
Check off the following:
https://docs.github.com/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax