Skip to main content

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
uses: actions/checkout@v4
uses: actions/setup-node@v4
with:
  node-version: '18'
Good for Node.js projects
python:3.10 Pre-built Python image with version 3.10
uses: actions/checkout@v4
uses: actions/setup-python@v5
with:
  python-version: '3.10'
Recommended for Python projects
golang:1.21 Pre-built Go image with version 1.21
uses: actions/checkout@v4
uses: actions/setup-go@v5
with:
  go-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 ]]

Example: Setting an Output in a Docker Action

echo "result=success" >> $GITHUB_OUTPUT
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
{
  "image-name": {
    "description": "Name of the Docker image",
    "required": true
  }
}
outputs Output parameters the action returns
{
  "image-id": {
    "description": "ID of the built image"
  }
}
runs Defines how the action runs (container image)
{
  "image": "docker://my-ghcr.io/my-action:latest"
}

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).

Was this article helpful?