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

github-docker-action

Safety Notice

Copy this and send it to your AI assistant to learn