Creating Docker Container Actions
1. Creating Dockerfile Action
| Property | Description | Example |
|---|---|---|
| name | Name of the action | my-docker-action |
| description | Short description of the action | A Docker-based GitHub Action to build and push images |
| inputs | Input parameters the action accepts | { "image-name": { "required": true, "default": "myapp" } } |
| outputs | Output parameters the action provides | { "image-id": { "description": "ID of the built image" } } |
| runs | How the action runs (e.g., using a Dockerfile) | { "using": "docker", "image": "Dockerfile" } |
Example: Dockerfile Action
name: 'My Docker Action'
description: 'A GitHub Action that uses a Dockerfile'
inputs:
image-name:
description: 'Name of the Docker image to build'
required: true
default: 'myapp'
outputs:
image-id:
description: 'ID of the built Docker image'
runs:
using: 'docker'
image: 'Dockerfile'
Note: The
Dockerfile must be in the root of your action repository.
Example: Dockerfile
FROM alpine:latest
WORKDIR /app
COPY . .
RUN apk add --no-cache nodejs npm
RUN npm install
CMD ["node", "index.js"]
2. Defining Container Image
| Property | Description | Value |
|---|---|---|
| name | Name of the action | my-docker-action |
| description | Short description of the action | A Docker-based GitHub Action to build and push images |
| inputs | Input parameters for the action | { "image-name": { "required": true, "description": "Name of the Docker image to build" } } |
| outputs | Output parameters from the action | { "image-url": { "description": "URL of the built Docker image" } } |
| runs | How the action runs (container image) | { "image": "docker://my-docker-action:latest" } |
Example: Dockerfile for Container Action
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["node", "index.js"]
Example: action.yml for Container Action
name: 'My Docker Action'
description: 'A Docker-based GitHub Action to build and push images'
inputs:
image-name:
required: true
description: 'Name of the Docker image to build'
outputs:
image-url:
description: 'URL of the built Docker image'
runs:
image: 'docker://my-docker-action:latest'
3. Using Pre-built Images
| Image | Description | Usage Example | Notes |
|---|---|---|---|
| node:18 | Pre-built Node.js image with version 18 | |
Good for Node.js projects |
| python:3.10 | Pre-built Python image with version 3.10 | |
Recommended for Python projects |
| golang:1.21 | Pre-built Go image with version 1.21 | |
Useful for Go applications |
Example: Using a Pre-built Python Image
name: Python CI
on: [push]
jobs:
test:
runs-on: ubuntu-latest
container:
image: python:3.10
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
pip install -r requirements.txt
- name: Run tests
run: python -m pytest
Note: When using container actions, ensure that the image's architecture matches your runner's architecture (e.g.,
linux/amd64).
4. Building from Dockerfile
| Property | Description | Example |
|---|---|---|
| uses | Specifies the Dockerfile to build from | uses: docker://my-action:latest |
| with | Optional parameters to pass to the build process | with: { context: . } |
Example: Building a Docker Action
name: "Build Docker Action"
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Build Docker image
uses: docker/build-push-action@v5
with:
context: .
file: ./Dockerfile
tags: my-action:latest
Note: The Dockerfile must define a default entrypoint or command that will be executed when the container runs.
5. Passing Arguments
| Argument | Type | Description | Required |
|---|---|---|---|
| args | string |
Arguments to pass to the Docker container | Yes |
Example: Passing Arguments to a Docker Container Action
name: 'Docker Container Action Example'
uses: './docker-action'
with:
args: '--verbose --output /tmp/output.txt'
6. Setting Environment Variables
| Variable | Value | Description |
|---|---|---|
| GITHUB_ACTION | string |
Name of the action |
| GITHUB_ACTOR | string |
Username of the person or app that triggered the workflow |
| GITHUB_REPOSITORY | string |
Name of the repository in the format owner/repo |
| GITHUB_WORKFLOW | string |
Name of the workflow |
| GITHUB_REF | string |
Git ref that triggered the workflow |
| GITHUB_SHA | string |
Git commit SHA that triggered the workflow |
Example: Setting environment variables in a Docker container action
name: 'Docker Container Action Example'
inputs:
message:
description: 'Message to echo'
required: true
default: 'Hello World'
runs:
using: 'docker'
image: 'Dockerfile'
env:
CUSTOM_MESSAGE: ${{ inputs.message }}
GITHUB_ACTOR: ${{ github.actor }}
7. Mounting Workspace
| Option | Values | Description |
|---|---|---|
| mounts | array |
Array of mount configurations to apply to the container |
| source | string |
Path in the host filesystem to mount |
| target | string |
Path in the container to mount to |
| type | string |
Mount type, e.g., bind, volume |
Example: Mounting workspace to container
name: "Docker Container Action"
on:
workflow_call:
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: "Mount workspace"
uses: docker://my-action-image
with:
mount-workspace: true
8. Using ENTRYPOINT Script
| Property | Description | Example |
|---|---|---|
| ENTRYPOINT | Defines the executable that will be run when the container starts | ENTRYPOINT ["/entrypoint.sh"] |
Example: Dockerfile with ENTRYPOINT
FROM alpine:latest
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
Note: The
ENTRYPOINT script must be executable and should handle input arguments passed from the action.
Example: entrypoint.sh script
#!/bin/bash
set -e
echo "Running custom action..."
echo "Input parameter: $1"
9. Handling Action Inputs
| Input | Description | Type | Required |
|---|---|---|---|
| name | The name of the input parameter | string |
Yes |
| description | A description of what the input is used for | string |
No |
| required | Whether the input is required or not | boolean |
No |
| default | The default value if the input is not provided | string |
No |
| options | A list of valid values for the input | array |
No |
Example: Using Inputs in a Docker Action
name: 'Docker Container Action'
description: 'A sample Docker container action'
inputs:
greeting:
description: 'The greeting to use'
required: true
default: 'Hello'
name:
description: 'The name to greet'
required: false
default: 'World'
outputs:
message:
description: 'The generated message'
runs:
using: 'docker'
image: 'Dockerfile'
Example: Accessing Inputs in the Dockerfile
#!/bin/bash
greeting="${GITHUB_ACTION_INPUT_GREETING:-Hello}"
name="${GITHUB_ACTION_INPUT_NAME:-World}"
echo "$greeting $name"
10. Setting Action Outputs
| Property | Description | Example |
|---|---|---|
| name | Name of the output parameter | result |
| value | Value to set for the output | $[[ steps.step1.outputs.result ]] |
Note: The
GITHUB_OUTPUT file is used to set outputs from a Docker container action.
Example: Setting Multiple Outputs
echo "result=success" >> $GITHUB_OUTPUT
echo "message=Action completed successfully" >> $GITHUB_OUTPUT
11. Using Docker Build Arguments
| Argument | Description | Default Value | Usage |
|---|---|---|---|
| build-arg | Build-time variables passed to the Docker build process | None | --build-arg KEY=VALUE |
Example: Setting Docker Build Arguments
name: Build Docker Image
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build Image
uses: docker/build-push-action@v5
with:
context: .
file: ./Dockerfile
build-args: |
VERSION=1.0.0
ENV=production
Note: Build arguments are only available during the Docker build process and are not persisted in the final image.
12. Publishing Container Actions
| Field | Description | Example |
|---|---|---|
| name | Name of the action | my-docker-action |
| description | Short description of the action | A Docker-based action to build and push images |
| inputs | Input parameters the action accepts | |
| outputs | Output parameters the action returns | |
| runs | Defines how the action runs (container image) | |
Example: Publishing a Docker Action to GitHub Container Registry
name: Publish Docker Action
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build and push image
uses: docker/build-push-action@v5
with:
context: .
push: true
tags: ghcr.io/myuser/my-docker-action:latest
- name: Update action manifest
run: |
echo "image=ghcr.io/myuser/my-docker-action:latest" >> $GITHUB_OUTPUT
Note: Ensure the Docker image is built and pushed to a registry that GitHub Actions can access, such as GitHub Container Registry (GHCR).