GitHub Docker Container Action

Build, package, and test custom GitHub Actions using Docker containers.

Not what you need? For running sidecar services (Redis, PostgreSQL, etc.) in CI workflows, see the github-service-containers skill.

Prerequisites

• Repository on GitHub (public, internal, or private)
• Basic understanding of GitHub Actions and Docker
• Self-hosted runners must run Linux with Docker installed

Security: Always treat workflow inputs as untrusted. Avoid script injection via ${{ }} in run: blocks.

Workflow: Creating a Docker Action

Step 1: Create project structure

my-action/
├── Dockerfile
├── action.yml
├── entrypoint.sh
└── README.md

Step 2: Write Dockerfile

See dockerfile-patterns.md

Minimal:

FROM alpine:3.21
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

Step 3: Define action metadata

See action-metadata.md

Declare inputs, outputs, and Docker configuration in action.yml.

Step 4: Write entrypoint script

See entrypoint-scripts.md

Script receives inputs as positional args. Write outputs to $GITHUB_OUTPUT.

Step 5: Make entrypoint executable

git add entrypoint.sh
git update-index --chmod=+x entrypoint.sh

Verify: git ls-files --stage entrypoint.sh should show 100755.

Step 6: Tag and push

git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "Initial action release"
git tag -a -m "v1 release" v1
git push --follow-tags

Step 7: Test in a workflow

See workflow-testing.md

Quick Reference

Component	Purpose
Dockerfile	Container image definition
action.yml	Action metadata (inputs, outputs, runner)
entrypoint.sh	Code executed when container starts
README.md	Usage docs for action consumers

Key environment variables

Variable	Description
$GITHUB_OUTPUT	File to write output key=value pairs
$GITHUB_WORKSPACE	Repo checkout dir (maps to /github/workspace in container)
$GITHUB_ENV	File to set env vars for later steps

Container filesystem mapping

The runner maps GITHUB_WORKSPACE to /github/workspace in the container. Files written there are available to subsequent workflow steps.

Reading Order

Task	Files to Read
Scaffold new action	SKILL.md (this file)
Dockerfile questions	dockerfile-patterns.md
Configure inputs/outputs	action-metadata.md
Write entrypoint logic	entrypoint-scripts.md
Test in workflow	workflow-testing.md
Debug container issues	dockerfile-patterns.md + entrypoint-scripts.md

In This Reference

File	Purpose
dockerfile-patterns.md	Dockerfile templates and gotchas
action-metadata.md	action.yml spec and examples
entrypoint-scripts.md	Entrypoint, outputs, permissions
workflow-testing.md	Workflow YAML for public/private