Home

Appearance

Getting Started ​

KevinDeBenedetti/github-workflows is a library of reusable GitHub Actions workflows and composite actions. Callers stay minimal — CI steps run consistently across all your repos.

Prerequisites ​

  • A GitHub repository
  • Appropriate secrets set in your repo/org (see each workflow's docs)

How it works ​

Workflows are called with workflow_call and referenced from your own workflow files:

yaml
jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/<name>.yml@main
    secrets: inherit

Production tip: Pin to a commit SHA instead of @main for reproducible builds.

Important: All workflow files must live at the flat root of .github/workflows/. GitHub Actions does not support reusable workflows in subdirectories.

Quick start by stack ​

Node.js ​

yaml
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-node.yml@main
    secrets: inherit

Auto-detects pnpm or bun from your lockfile. Runs lint → typecheck → test → build. → Full reference

Python ​

yaml
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-python.yml@main
    secrets: inherit

Uses uv and ruff. Runs lint → format check → test. → Full reference

Shell scripts ​

yaml
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-shell.yml@main
    secrets: inherit

Runs ShellCheck → actionlint → Bats. → Full reference

Helm ​

yaml
jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-helm.yml@main
    with:
      chart-paths: 'charts/*'
      run-template: true
    secrets: inherit

Runs helm lint and an optional helm template dry-run on all charts.

Kubernetes ​

yaml
jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-kubernetes.yml@main
    with:
      kubeconform-paths: kubernetes/
    secrets: inherit

Validates Kubernetes manifests with kubeconform (CRDs-catalog enabled by default).

Terraform ​

yaml
jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-terraform.yml@main
    with:
      tf-dir: terraform
    secrets: inherit

Runs terraform validate and terraform fmt -check -diff.

Ansible ​

yaml
jobs:
  ci:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/ci-ansible.yml@main
    with:
      ansible-dir: ansible/
      run-syntax-check: true
    secrets: inherit

Runs ansible-lint and an optional ansible-playbook --syntax-check.

Docker ​

yaml
jobs:
  deploy:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/cd-docker.yml@main
    with:
      image-name: my-app
      tag-latest: true
    secrets: inherit

Builds and pushes a multi-platform image to GHCR (ghcr.io). → Full reference

Kaniko (self-hosted) ​

yaml
jobs:
  deploy:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/cd-kaniko.yml@main
    with:
      image-name: my-app
      runner: '["self-hosted","linux","k3s","kaniko"]'
    secrets: inherit

Builds and pushes an image to GHCR using Kaniko on self-hosted runners (no Docker daemon required).

GitHub Pages ​

yaml
jobs:
  deploy:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/cd-pages.yml@main
    with:
      output-directory: dist
    secrets: inherit

→ Full reference

Vercel ​

Requires three secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.

yaml
jobs:
  deploy:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/cd-vercel.yml@main
    with:
      environment: preview
    secrets: inherit

→ Full reference

Docs sync ​

Sync this repo's docs to a centralized docs site via repository_dispatch. Requires a GitHub App: pass its client-id and the APP_PRIVATE_KEY secret.

yaml
jobs:
  docs:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/cd-docs.yml@main
    with:
      docs-directory: docs
      client-id: ${{ vars.DOCS_APP_CLIENT_ID }}
    secrets:
      APP_PRIVATE_KEY: ${{ secrets.DOCS_APP_PRIVATE_KEY }}

→ Full reference

Automated releases ​

yaml
jobs:
  release:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/release.yml@main
    secrets: inherit

Uses release-please. Automatically moves a v<major> tag after each release. → Full reference

Security scanning ​

yaml
jobs:
  security:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/security.yml@main
    secrets: inherit

Combines Gitleaks secret scanning, CodeQL SAST, and optional dependency audits. → Full reference

All available workflows ​

WorkflowDescriptionDoc
ci-node.ymlNode.js CI (lint → typecheck → test → build)→
ci-python.ymlPython CI (lint → format → test)→
ci-shell.ymlShell CI (ShellCheck → actionlint → Bats)→
ci-ansible.ymlAnsible CI (ansible-lint + syntax check)→
ci-helm.ymlHelm CI (lint + template dry-run)→
ci-kubernetes.ymlKubernetes CI (kubeconform manifest validation)→
ci-terraform.ymlTerraform CI (validate + fmt check)→
cd-docker.ymlBuild & push multi-platform Docker image to GHCR→
cd-kaniko.ymlBuild & push image with Kaniko on self-hosted runners→
cd-pages.ymlBuild & deploy static site to GitHub Pages→
cd-vercel.ymlDeploy preview or production to Vercel→
cd-docs.ymlSync docs to a centralized docs repository→
release.ymlAutomated releases via release-please→
security.ymlSecret scan + CodeQL SAST + dependency audit→
check-bot-commits.ymlGuard PRs against bot-authored commits→

Composite actions ​

Actions can be used individually inside your own workflow steps:

yaml
steps:
  - uses: KevinDeBenedetti/github-workflows/.github/actions/setup-node@main
    with:
      node-version: '20'
ActionDescription
setup-nodeInstall Node.js + pnpm/bun with cache
setup-pythonInstall Python + uv with cache
shellcheckRun ShellCheck on all .sh files
batsRun Bats shell unit tests
detect-changesOutput a JSON matrix of changed apps in a monorepo
actionlintValidate GitHub Actions workflow files
kubeconformValidate Kubernetes manifests
check-docs-linksCheck for broken links in docs
check-vitepress-mdValidate VitePress markdown
notify-deploymentPost a deployment status notification

Examples ​

Complete ready-to-use caller files live in examples/:

FileStack
ci-cd-pages.ymlNode.js CI → GitHub Pages → release-please
ci-cd-vercel.ymlNode.js CI → Vercel → release-please
next.ymlNext.js
nuxt.ymlNuxt
vue-react.ymlVue / React (Vite)
fastapi.ymlFastAPI (Python)
monorepo.ymlMonorepo with change detection
vitepress.ymlVitePress docs site