Skip to content

Commit 64dc8bb

Browse files
EricWittmannEricWittmann
committed
Added a load-docker-image action
1 parent 28da2af commit 64dc8bb

2 files changed

Lines changed: 437 additions & 0 deletions

File tree

‎load-docker-image/README.md‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
# Load Docker Image Action
2+
3+
A GitHub Action to download and load a Docker image from an artifact created by the `save-docker-image` action.
4+
5+
## Features
6+
7+
- 📥 Download Docker image artifacts automatically
8+
- 🐳 Load Docker images into the local Docker daemon
9+
- 🔍 Verify loaded image names and tags
10+
- 📊 Report file size and image information
11+
- ✅ Cross-platform support (Linux, macOS, Windows)
12+
- 🔧 Flexible input options for different workflows
13+
- 📋 Detailed logging and verification
14+
15+
## Usage
16+
17+
### Basic Usage
18+
19+
```yaml
20+
- name: Load Docker Image
21+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
22+
with:
23+
artifact-name: 'docker-image'
24+
```
25+
26+
### Advanced Usage
27+
28+
```yaml
29+
- name: Load Docker Image
30+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
31+
with:
32+
artifact-name: 'my-app-image'
33+
image-name: 'my-app'
34+
tag: 'v1.2.3'
35+
```
36+
37+
### Complete Workflow Example
38+
39+
```yaml
40+
name: Build, Save, and Load Docker Image
41+
42+
on:
43+
push:
44+
branches: [ main ]
45+
46+
jobs:
47+
build-and-save:
48+
runs-on: ubuntu-latest
49+
50+
steps:
51+
- name: Checkout code
52+
uses: actions/checkout@v4
53+
54+
- name: Build Docker image
55+
run: |
56+
docker build -t my-app:latest .
57+
58+
- name: Save Docker image
59+
uses: apicurio/apicurio-github-actions/save-docker-image@v1
60+
with:
61+
image-name: 'my-app'
62+
tag: 'latest'
63+
artifact-name: 'my-app-docker-image'
64+
65+
test:
66+
needs: build-and-save
67+
runs-on: ubuntu-latest
68+
69+
steps:
70+
- name: Load Docker image
71+
id: load-image
72+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
73+
with:
74+
artifact-name: 'my-app-docker-image'
75+
image-name: 'my-app'
76+
tag: 'latest'
77+
78+
- name: Verify loaded image
79+
run: |
80+
echo "Loaded image: ${{ steps.load-image.outputs.loaded-image }}"
81+
echo "Image ID: ${{ steps.load-image.outputs.image-id }}"
82+
echo "File size: ${{ steps.load-image.outputs.file-size }} bytes"
83+
84+
# Run the loaded image
85+
docker run --rm ${{ steps.load-image.outputs.loaded-image }} echo "Hello from loaded image!"
86+
```
87+
88+
## Inputs
89+
90+
| Input | Description | Required | Default |
91+
|-------|-------------|----------|---------|
92+
| `artifact-name` | Name of the artifact containing the Docker image | ❌ No | `docker-image` |
93+
| `image-path` | Path where the Docker image tar file will be downloaded to | ❌ No | `./docker-image.tar` |
94+
| `image-name` | Expected name of the Docker image (for verification) | ❌ No | - |
95+
| `tag` | Expected tag of the Docker image (for verification) | ❌ No | `latest` |
96+
97+
## Outputs
98+
99+
| Output | Description |
100+
|--------|-------------|
101+
| `loaded-image` | Name and tag of the loaded Docker image |
102+
| `image-id` | ID of the loaded Docker image |
103+
| `file-size` | Size of the Docker image file in bytes |
104+
105+
## Use Cases
106+
107+
### 1. Multi-Job Workflows
108+
109+
Load Docker images saved in previous jobs:
110+
111+
```yaml
112+
jobs:
113+
build:
114+
runs-on: ubuntu-latest
115+
steps:
116+
- name: Build and save image
117+
uses: apicurio/apicurio-github-actions/save-docker-image@v1
118+
with:
119+
image-name: 'my-app'
120+
artifact-name: 'my-app-docker-image'
121+
122+
test:
123+
needs: build
124+
runs-on: ubuntu-latest
125+
steps:
126+
- name: Load Docker image
127+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
128+
with:
129+
artifact-name: 'my-app-docker-image'
130+
131+
- name: Run tests
132+
run: docker run --rm my-app:latest npm test
133+
134+
deploy:
135+
needs: [build, test]
136+
runs-on: ubuntu-latest
137+
steps:
138+
- name: Load Docker image
139+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
140+
with:
141+
artifact-name: 'my-app-docker-image'
142+
143+
- name: Deploy image
144+
run: |
145+
docker tag my-app:latest registry.example.com/my-app:latest
146+
docker push registry.example.com/my-app:latest
147+
```
148+
149+
### 2. Image Verification
150+
151+
Verify that the loaded image matches expectations:
152+
153+
```yaml
154+
- name: Load and verify Docker image
155+
id: load-image
156+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
157+
with:
158+
artifact-name: 'production-image'
159+
image-name: 'my-app'
160+
tag: 'v1.0.0'
161+
162+
- name: Validate loaded image
163+
run: |
164+
if [[ "${{ steps.load-image.outputs.loaded-image }}" == "my-app:v1.0.0" ]]; then
165+
echo "✅ Image loaded successfully with correct name and tag"
166+
else
167+
echo "❌ Image name/tag mismatch"
168+
exit 1
169+
fi
170+
```
171+
172+
### 3. Cross-Platform Workflows
173+
174+
Load images across different operating systems:
175+
176+
```yaml
177+
strategy:
178+
matrix:
179+
os: [ubuntu-latest, windows-latest, macos-latest]
180+
181+
runs-on: ${{ matrix.os }}
182+
183+
steps:
184+
- name: Load Docker image
185+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
186+
with:
187+
artifact-name: 'cross-platform-image'
188+
```
189+
190+
### 4. Conditional Loading
191+
192+
Load images only when needed:
193+
194+
```yaml
195+
- name: Check if image exists
196+
id: check-image
197+
run: |
198+
if docker images --format "{{.Repository}}:{{.Tag}}" | grep -q "my-app:latest"; then
199+
echo "exists=true" >> $GITHUB_OUTPUT
200+
else
201+
echo "exists=false" >> $GITHUB_OUTPUT
202+
fi
203+
204+
- name: Load Docker image if not exists
205+
if: steps.check-image.outputs.exists == 'false'
206+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
207+
with:
208+
artifact-name: 'my-app-docker-image'
209+
```
210+
211+
### 5. Multiple Image Loading
212+
213+
Load multiple Docker images in a single job:
214+
215+
```yaml
216+
- name: Load application image
217+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
218+
with:
219+
artifact-name: 'app-image'
220+
image-name: 'my-app'
221+
222+
- name: Load database image
223+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
224+
with:
225+
artifact-name: 'db-image'
226+
image-name: 'my-db'
227+
228+
- name: Start services
229+
run: |
230+
docker run -d --name app my-app:latest
231+
docker run -d --name db my-db:latest
232+
```
233+
234+
## Requirements
235+
236+
- Docker must be available in the runner environment
237+
- The specified artifact must exist and contain a valid Docker image tar file
238+
- Sufficient disk space to load the Docker image
239+
240+
## Error Handling
241+
242+
The action will fail if:
243+
- The specified artifact doesn't exist or can't be downloaded
244+
- The Docker image tar file is not found at the specified path
245+
- The tar file is corrupted or not a valid Docker image
246+
- Docker is not available in the runner environment
247+
- There are insufficient permissions or disk space
248+
249+
## Troubleshooting
250+
251+
### Common Issues
252+
253+
1. **Artifact not found**: Ensure the artifact name matches exactly with the one created by `save-docker-image`
254+
2. **File not found**: Check that the `image-path` is correct and the file exists
255+
3. **Docker not available**: Ensure Docker is installed and running in the runner environment
256+
4. **Permission denied**: Check file permissions and runner capabilities
257+
258+
### Debug Information
259+
260+
The action provides detailed logging including:
261+
- File size information
262+
- Docker load output
263+
- Image verification results
264+
- Current Docker images list
265+
266+
## Integration with save-docker-image
267+
268+
This action is designed to work seamlessly with the `save-docker-image` action:
269+
270+
```yaml
271+
# Job 1: Save image
272+
- name: Save Docker image
273+
uses: apicurio/apicurio-github-actions/save-docker-image@v1
274+
with:
275+
image-name: 'my-app'
276+
tag: 'v1.0.0'
277+
artifact-name: 'my-app-image'
278+
279+
# Job 2: Load image (in different job/workflow)
280+
- name: Load Docker image
281+
uses: apicurio/apicurio-github-actions/load-docker-image@v1
282+
with:
283+
artifact-name: 'my-app-image' # Same as save action
284+
image-name: 'my-app' # Same as save action
285+
tag: 'v1.0.0' # Same as save action
286+
```
287+
288+
## Contributing
289+
290+
This action is part of the [Apicurio GitHub Actions](https://github.com/Apicurio/apicurio-github-actions) repository. Please refer to the main repository for contribution guidelines.
291+
292+
## License
293+
294+
This action is licensed under the Apache License 2.0. See the [LICENSE](../LICENSE) file for details.

0 commit comments

Comments
 (0)