A GitHub template repository for building Go-based GitHub Actions (Docker container actions) with automated CI/CD workflows.
| Category | Files | Description |
|---|---|---|
| Action | action.yml |
Action metadata with example inputs/outputs |
| Docker | Dockerfile, .dockerignore |
Multi-stage build (golang:alpine → alpine) |
| Go Code | cmd/, internal/ |
Entry point, action logic, config loader, output helpers |
| Build | Makefile |
build, test, cover, fmt, vet |
| CI/CD | .github/workflows/ |
CI (test + Docker + action test), release, changelog, contributors |
| Config | .github/dependabot.yml |
Weekly dependency updates (Docker + Actions + Go modules) |
| Docs | CLAUDE.md, docs/ |
Project guidelines and development guide |
Click "Use this template" on GitHub, or:
gh repo create my-action --template somaz94/template-go-action --public --clone
cd my-action| Placeholder | Replace With | Example |
|---|---|---|
YOUR_USERNAME |
Your GitHub username | somaz94 |
YOUR_ACTION |
Your repository name | my-awesome-action |
YOUR_GITLAB_GROUP |
Your GitLab group (for mirror) | backup6695808 |
myaction |
Your binary name | my-awesome-action |
Quick replace:
# macOS
find . -type f -not -path './.git/*' -exec sed -i '' \
-e 's/YOUR_USERNAME/somaz94/g' \
-e 's/YOUR_ACTION/my-awesome-action/g' \
-e 's/YOUR_GITLAB_GROUP/backup6695808/g' \
-e 's/myaction/my-awesome-action/g' {} +
# Linux
find . -type f -not -path './.git/*' -exec sed -i \
-e 's/YOUR_USERNAME/somaz94/g' \
-e 's/YOUR_ACTION/my-awesome-action/g' \
-e 's/YOUR_GITLAB_GROUP/backup6695808/g' \
-e 's/myaction/my-awesome-action/g' {} +go mod init github.com/YOUR_USERNAME/YOUR_ACTION
go mod tidymake build # → ./myaction
make test # Run unit tests
# Docker test
docker build -t myaction:local .
docker run --rm -e INPUT_DRY_RUN=true myaction:local.
├── cmd/
│ └── main.go # Entry point with signal handling
├── internal/
│ ├── action/
│ │ ├── action.go # Core action logic (replace this)
│ │ └── action_test.go
│ ├── config/
│ │ ├── config.go # Load INPUT_* env vars
│ │ └── config_test.go
│ └── output/
│ ├── output.go # GitHub Actions output helpers
│ └── output_test.go
├── .github/
│ ├── workflows/
│ │ ├── ci.yml # CI: test, Docker build, action test
│ │ ├── release.yml # GitHub release + major tag update
│ │ ├── changelog-generator.yml
│ │ ├── contributors.yml
│ │ ├── dependabot-auto-merge.yml
│ │ ├── stale-issues.yml
│ │ ├── issue-greeting.yml
│ │ └── gitlab-mirror.yml
│ ├── dependabot.yml
│ └── release.yml # Release note categories
├── scripts/
│ └── create-pr.sh # Auto-generate PR body
├── action.yml # Action metadata (inputs/outputs)
├── Dockerfile # Multi-stage build
├── .dockerignore
├── .gitattributes
├── .gitignore
├── Makefile
├── CLAUDE.md
├── LICENSE
├── docs/
│ └── DEVELOPMENT.md
├── go.mod
└── README.md
GitHub Actions runner
→ Docker build (Dockerfile)
→ Reads INPUT_* env vars (internal/config)
→ Executes action logic (internal/action)
→ Writes GITHUB_OUTPUT (internal/output)
action.yml— Define your inputs, outputs, and brandinginternal/config/config.go— Add fields for your inputsinternal/action/action.go— Replace with your action logicDockerfile— Add runtime dependencies (e.g.,git,curl)
make help # Show all targets
make build # Build binary → ./myaction
make test # Run unit tests with coverage
make cover # Generate coverage report
make cover-html # Open coverage in browser
make fmt # Format code (gofmt)
make vet # Run go vet
make branch name=x # Create feature branch feat/x
make pr title="..." # Test → push → create PR
make clean # Remove build artifacts| Workflow | Trigger | Description |
|---|---|---|
ci.yml |
push (main), PR, dispatch | Unit tests → Docker build & dry-run → Action integration test |
release.yml |
tag push v* |
GitHub release + major tag update (v1) |
changelog-generator.yml |
after release, PR merge | Auto-generate CHANGELOG.md |
contributors.yml |
after changelog | Auto-generate CONTRIBUTORS.md |
dependabot-auto-merge.yml |
dependabot PR | Auto-merge minor/patch updates |
stale-issues.yml |
daily cron | Auto-close stale issues (30d + 7d) |
issue-greeting.yml |
issue opened | Welcome message |
gitlab-mirror.yml |
push to main | Mirror to GitLab |
tag push v* → Create release + update major tag (v1)
└→ Generate changelog
└→ Generate Contributors
| Secret | Usage |
|---|---|
PAT_TOKEN |
Release, major tag update, contributors (cross-repo access) |
GITLAB_TOKEN |
GitLab mirror (optional) |
GITHUB_TOKENis automatically provided by GitHub Actions.
git tag v1.0.0
git push origin v1.0.0The release workflow automatically:
- Creates a GitHub release with generated notes
- Updates the major version tag (
v1→ points tov1.0.0)
Users reference your action as:
- uses: YOUR_USERNAME/YOUR_ACTION@v1template-go-cli |
template-go-action |
|
|---|---|---|
| Entry point | Cobra CLI | action.yml + Docker |
| Distribution | GoReleaser + Homebrew | Docker container action |
| Config | CLI flags + YAML | INPUT_* env vars |
| Output | stdout/file | GITHUB_OUTPUT |
| Release | Multi-platform binaries | Major tag update (v1) |
| Makefile | build, branch, pr | build, test, branch, pr |
- Commits: Conventional Commits (
feat:,fix:,docs:,refactor:,test:,ci:,chore:) - paths-ignore: CI skips
.github/workflows/**and**/*.mdchanges
See LICENSE — replace with your chosen license.