Skip to content

Commit 895df3f

Browse files
NatchicaNatchica
authored
feat: add docker-build-cloud reusable workflow for multi-arch DockerHub publish (#115)
1 parent ac8c6f3 commit 895df3f

5 files changed

Lines changed: 145 additions & 0 deletions

File tree

‎.github/workflows/docker-build-cloud.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Build and Push Multi-Platform Docker Image via Docker Build Cloud
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
image-name:
7+
description: "Name of Docker Image (fully qualified, e.g. 'iexechub/my-image')"
8+
required: true
9+
type: string
10+
image-tag:
11+
description: "Tag to apply to the built image (e.g. '1.0.0', no v prefix)"
12+
required: true
13+
type: string
14+
platforms:
15+
description: "Comma-separated build platforms (e.g. 'linux/amd64,linux/arm64')"
16+
required: true
17+
type: string
18+
cloud-builder-endpoint:
19+
description: "Docker Build Cloud endpoint, format '<dbc-org>/<builder>'"
20+
required: true
21+
type: string
22+
dockerfile:
23+
description: "Path to the Dockerfile (e.g. './Dockerfile', './docker/Dockerfile')"
24+
default: "Dockerfile"
25+
type: string
26+
context:
27+
description: "Path to Docker Build Context"
28+
default: "."
29+
type: string
30+
build-args:
31+
description: "Docker build arguments (multiline format: KEY1=value1\nKEY2=value2)"
32+
default: ""
33+
type: string
34+
secrets:
35+
dockerhub-username:
36+
description: "Username for Docker Hub authentication"
37+
required: true
38+
dockerhub-password:
39+
description: "DockerHub PAT with Build scope (required to authenticate to Docker Build Cloud endpoint)"
40+
required: true
41+
42+
jobs:
43+
build:
44+
runs-on: ubuntu-latest
45+
46+
steps:
47+
- name: Checkout Repository
48+
uses: actions/checkout@v6
49+
50+
# Login MUST run before Set up Docker Buildx so the cloud driver can
51+
# authenticate to the Docker Build Cloud endpoint via ~/.docker/config.json.
52+
- name: Login to Docker Hub
53+
uses: docker/login-action@v4
54+
with:
55+
username: ${{ secrets.dockerhub-username }}
56+
password: ${{ secrets.dockerhub-password }}
57+
58+
- name: Set up Docker Buildx (Docker Build Cloud)
59+
uses: docker/setup-buildx-action@v4
60+
with:
61+
driver: cloud
62+
endpoint: ${{ inputs.cloud-builder-endpoint }}
63+
64+
- name: Build and push multi-platform image
65+
uses: docker/build-push-action@v7
66+
with:
67+
build-args: ${{ inputs.build-args }}
68+
context: ${{ inputs.context }}
69+
file: ${{ inputs.dockerfile }}
70+
platforms: ${{ inputs.platforms }}
71+
push: true
72+
tags: ${{ inputs.image-name }}:${{ inputs.image-tag }}

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ This repository contains a comprehensive collection of reusable GitHub Actions w
77
### 🐳 [Build Docker Image](./docker-build)
88
Automates the process of building, tagging, and pushing Docker images to Docker Hub. Perfect for projects that require containerization with minimal configuration overhead.
99

10+
### ☁️ [Build Docker Image via Docker Build Cloud](./docker-build-cloud)
11+
Builds and pushes a multi-platform Docker image (e.g. `linux/amd64` + `linux/arm64`) to Docker Hub in a single job using Docker Build Cloud's remote builders. No QEMU emulation, no native ARM runners.
12+
1013
### 🚀 [Deploy Docker](./deploy-docker)
1114
Automates the process of building a Docker image and deploying it to a remote server. Configurable for different Dockerfile paths, image names, tags, and remote hosts. Streamlines the deployment process with secure SSH connections.
1215

‎docker-build-cloud/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Changelog

‎docker-build-cloud/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# 🐳 Docker Build Cloud — Multi-Platform Workflow
2+
3+
## 🔍 Overview
4+
5+
This reusable GitHub Actions workflow builds and pushes a multi-platform Docker image to Docker Hub using [Docker Build Cloud](https://docs.docker.com/build-cloud/) remote builders. It produces a single multi-arch manifest (e.g. `linux/amd64` + `linux/arm64`) in one job, with no QEMU emulation and no native ARM runners required.
6+
7+
## ✨ Features
8+
9+
- 🏗️ Multi-platform build in a single job via Docker Build Cloud's remote builders
10+
- 🔐 Authenticates to DockerHub for both registry push and DBC endpoint access
11+
- 🏷️ Tags the image with `<image-name>:<image-tag>`
12+
- 🚀 No QEMU emulation, no native ARM runners — DBC handles arch-specific builds
13+
14+
> [!IMPORTANT]
15+
> Requires a Docker Build Cloud subscription and a builder configured in your DockerHub organization. The DockerHub PAT must have the **Build** scope to authenticate to the cloud endpoint.
16+
17+
## ⚙️ Inputs
18+
19+
| Name | Description | Required | Default |
20+
| ------------------------ | --------------------------------------------------------------------------------- | -------- | -------------- |
21+
| `build-args` | Docker build arguments (multiline format: `KEY1=value1\nKEY2=value2`) | No | `""` |
22+
| `cloud-builder-endpoint` | Docker Build Cloud endpoint, format `<dbc-org>/<builder>` | Yes | - |
23+
| `context` | Path to Docker Build Context | No | `"."` |
24+
| `dockerfile` | Path to the Dockerfile (e.g. `'./Dockerfile'`, `'./docker/Dockerfile'`) | No | `"Dockerfile"` |
25+
| `image-name` | Name of Docker Image, fully qualified (e.g. `iexechub/my-image`) | Yes | - |
26+
| `image-tag` | Tag to apply to the built image (e.g. `1.0.0`, no v prefix) | Yes | - |
27+
| `platforms` | Comma-separated build platforms (e.g. `linux/amd64,linux/arm64`) | Yes | - |
28+
29+
## 🔐 Secrets
30+
31+
| Name | Description | Required |
32+
| -------------------- | ------------------------------------------------------------------------------------------ | -------- |
33+
| `dockerhub-username` | Username for Docker Hub authentication | Yes |
34+
| `dockerhub-password` | Personal Access Token for Docker Hub with the **Build** scope (needed for DBC endpoint) | Yes |
35+
36+
## 💻 Example Usage
37+
38+
```yaml
39+
name: Build and Push Release Image
40+
41+
on:
42+
push:
43+
tags:
44+
- 'v*.*.*'
45+
46+
jobs:
47+
build-multiplatform:
48+
uses: iExecBlockchainComputing/github-actions-workflows/.github/workflows/docker-build-cloud.yml@main # ⚠️ use tagged version here
49+
with:
50+
image-name: iexechub/my-image
51+
image-tag: ${{ github.ref_name }}
52+
platforms: linux/amd64,linux/arm64
53+
cloud-builder-endpoint: ${{ vars.DOCKER_CLOUD_BUILDER_LABEL }}
54+
secrets:
55+
dockerhub-username: ${{ secrets.DOCKERHUB_USERNAME }}
56+
dockerhub-password: ${{ secrets.DOCKERHUB_TOKEN }}
57+
```
58+
59+
## 📝 Notes
60+
61+
- 🔒 The DockerHub PAT must have the **Build** scope, not just Read/Write — DBC endpoints will return `403 Forbidden` otherwise.
62+
- 🪪 The user owning the PAT must be a member of the cloud builder (Docker Hub → org → Build Cloud → builder → Members).
63+
- 🔁 Login to DockerHub MUST run before `setup-buildx-action` — the cloud driver reads `~/.docker/config.json` at bootstrap.
64+
65+
## 🛠️ Troubleshooting
66+
67+
- **`403 Forbidden` on Set up Docker Buildx**: PAT missing Build scope, user not a member of the cloud builder, token owner not in the builder org, malformed endpoint, or inactive DBC subscription.
68+
- **Manifest only contains one platform**: confirm `platforms` input lists every arch with commas (no spaces).

‎docker-build-cloud/version.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.0.0

0 commit comments

Comments
 (0)