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:

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

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

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

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

---

Docker

jobs:
  deploy:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/deploy-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

---

GitHub Pages

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

→ Full reference

---

Vercel

Requires three secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.

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

→ Full reference

---

Automated releases

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

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

---

Repository maintenance (purge)

Keep deployments and workflow run history clean automatically:

# .github/workflows/maintenance.yml
name: Maintenance
on:
  schedule:
    - cron: '0 3 * * 0'  # Every Sunday at 03:00 UTC
  workflow_dispatch:

jobs:
  purge-deployments:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/purge-deployments.yml@main
    with:
      keep: 10       # keep the 10 most-recent deployments per environment
      dry-run: false
    secrets: inherit

  purge-workflow-runs:
    uses: KevinDeBenedetti/github-workflows/.github/workflows/purge-workflow-runs.yml@main
    with:
      keep: 10       # keep the 10 most-recent runs per workflow
      dry-run: false
    secrets: inherit

→ Deployments reference · Workflow runs reference

---

All available workflows

Workflow	Description	Doc
ci-node.yml	Node.js CI (lint → typecheck → test → build)	→
ci-python.yml	Python CI (lint → format → typecheck → test)	→
ci-shell.yml	Shell CI (ShellCheck → actionlint → Bats)	→
deploy-docker.yml	Build & push multi-platform Docker image to GHCR	→
deploy-pages.yml	Build & deploy static site to GitHub Pages	→
deploy-vercel.yml	Deploy preview or production to Vercel	→
release.yml	Automated releases via release-please	→
security.yml	Secret scan + CodeQL SAST + dependency audit	→
purge-deployments.yml	Delete old deployments, keep last N per environment	→
purge-workflow-runs.yml	Delete old workflow runs, keep last N per workflow	→
actions-autoupdate.yml	Bump pinned action versions and open a PR	→
prek-autoupdate.yml	Bump prek hook revisions and open a PR	→
label-sync.yml	Sync labels.yml to GitHub labels	→
dispatch-docs.yml	Trigger a remote docs rebuild via repository_dispatch	→
dependabot-automerge.yml	Auto-merge Dependabot PRs	→
check-bot-commits.yml	Guard PRs against bot-authored commits	→

---

Composite actions

Actions can be used individually inside your own workflow steps:

steps:
  - uses: KevinDeBenedetti/github-workflows/.github/actions/setup-node@main
    with:
      node-version: '20'

Action	Description
setup-node	Install Node.js + pnpm/bun with cache
setup-python	Install Python + uv with cache
shellcheck	Run ShellCheck on all .sh files
bats	Run Bats shell unit tests
detect-changes	Output a JSON matrix of changed apps in a monorepo
actionlint	Validate GitHub Actions workflow files
kubeconform	Validate Kubernetes manifests

---

Examples

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

File	Stack
ci-cd-pages.yml	Node.js CI → GitHub Pages → release-please
ci-cd-vercel.yml	Node.js CI → Vercel → release-please
next.yml	Next.js
nuxt.yml	Nuxt
vue-react.yml	Vue / React (Vite)
fastapi.yml	FastAPI (Python)
monorepo.yml	Monorepo with change detection
maintenance.yml	Purge old deployments and workflow runs