Stats
Actions
Tags
From ccfg-github-actions
Scaffold CI/CD workflow files for GitHub Actions projects
How this command is triggered — by the user, by Claude, or both
Slash command
/ccfg-github-actions:scaffold [--type=ci|cd|release|pr-checks|reusable-workflow]Files this command reads when invoked
This command is limited to the following tools:
The summary Claude sees in its command listing — used to decide when to auto-load this command
# scaffold Intelligent workflow scaffolding for GitHub Actions. Generates production-ready CI/CD workflow files with security best practices, language-specific configurations, and modern DevOps patterns. Automatically detects project language and structure to create tailored workflows. ## Usage Scaffold CI workflow (auto-detects language): Scaffold deployment workflow: Scaffold release workflow: Scaffold PR validation workflow: Scaffold reusable workflow: ## Overview The scaffold command generates GitHub Actions workflow files following security and efficiency best practi...
Intelligent workflow scaffolding for GitHub Actions. Generates production-ready CI/CD workflow files with security best practices, language-specific configurations, and modern DevOps patterns. Automatically detects project language and structure to create tailored workflows.
Scaffold CI workflow (auto-detects language):
/ccfg-github-actions scaffold
/ccfg-github-actions scaffold --type=ci
Scaffold deployment workflow:
/ccfg-github-actions scaffold --type=cd
Scaffold release workflow:
/ccfg-github-actions scaffold --type=release
Scaffold PR validation workflow:
/ccfg-github-actions scaffold --type=pr-checks
Scaffold reusable workflow:
/ccfg-github-actions scaffold --type=reusable-workflow
The scaffold command generates GitHub Actions workflow files following security and efficiency best practices:
All scaffolded workflows include:
Auto-detection and configuration for:
Third-party actions: SHA-pinned only
uses: docker/setup-buildx-action@8c0edd44fd9d2d25d1f32147d34faabc28ce1b7d
First-party actions: Version tags acceptable
uses: actions/checkout@v4
uses: actions/setup-node@v4
${{ secrets.EXAMPLE_SECRET }}Default permissions for workflow types:
permissions: read-all or contents: readcontents: read, id-token: write for OIDCcontents: write for tag/release creationcontents: read, pull-requests: write for comments.github/workflows/ exists before writingdocs/infra/github-actions-conventions.mdExtract workflow type from arguments:
cigit rev-parse --git-dir
If not a git repository, warn but continue (workflows can be created before git init).
Use Glob to check:
pattern: .github/workflows
If doesn't exist, create it:
mkdir -p .github/workflows
Target filename based on type:
ci.ymldeploy.ymlrelease.ymlpr-checks.ymlreusable-workflow.ymlUse Glob to check if file exists:
pattern: .github/workflows/ci.yml
If exists, prompt user:
Use Glob:
pattern: docs/infra/github-actions-conventions.md
If found, read and incorporate:
Use Glob to check for language indicators:
JavaScript/TypeScript:
pattern: package.json
pattern: yarn.lock
pattern: pnpm-lock.yaml
pattern: package-lock.json
Python:
pattern: pyproject.toml
pattern: Pipfile
pattern: poetry.lock
pattern: requirements.txt
pattern: setup.py
Java:
pattern: pom.xml
pattern: build.gradle
pattern: build.gradle.kts
Go:
pattern: go.mod
pattern: go.sum
Rust:
pattern: Cargo.toml
pattern: Cargo.lock
Ruby:
pattern: Gemfile
pattern: Gemfile.lock
PHP:
pattern: composer.json
pattern: composer.lock
.NET:
pattern: *.csproj
pattern: *.fsproj
pattern: *.sln
Priority order if multiple languages detected:
Based on detected language, read config:
For Node.js - Read package.json:
{
"name": "project-name",
"scripts": {
"test": "jest",
"lint": "eslint .",
"build": "webpack"
},
"engines": {
"node": ">=18.0.0"
}
}
Extract:
For Python - Read pyproject.toml or setup.py:
[tool.poetry]
name = "project-name"
python = "^3.11"
[tool.poetry.dependencies]
pytest = "^7.0"
Extract:
For other languages, apply similar patterns.
Check for monorepo indicators:
pattern: packages/*/package.json
pattern: apps/*/package.json
pattern: lerna.json
pattern: pnpm-workspace.yaml
pattern: nx.json
If monorepo detected:
Based on language, check for:
JavaScript:
pattern: jest.config.*
pattern: vitest.config.*
pattern: karma.conf.*
Or check package.json devDependencies.
Python:
pattern: pytest.ini
pattern: tox.ini
pattern: .coveragerc
Adjust CI workflow test commands accordingly.
Based on workflow type, load appropriate template structure.
If type is ci:
name: CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
# Cancel outdated CI runs on PR updates
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
lint:
name: Lint
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific setup
- name: Run linter
run: # Language-specific lint command
test:
name: Test
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific setup with caching
- name: Run tests
run: # Language-specific test command
- name: Upload coverage
uses: codecov/codecov-action@<SHA>
if: always()
build:
name: Build
runs-on: ubuntu-latest
timeout-minutes: 10
needs: [lint, test]
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific setup
- name: Build
run: # Language-specific build command
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: build-artifacts
path: # Language-specific build output
If language is Node.js:
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20' # From package.json engines or default
cache: 'npm' # or 'yarn', 'pnpm' based on lockfile
- name: Install dependencies
run: npm ci # or yarn install --frozen-lockfile, pnpm install --frozen-lockfile
- name: Run linter
run: npm run lint # If lint script exists
- name: Run tests
run: npm test
env:
CI: true
- name: Build
run: npm run build # If build script exists
If language is Python:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.11' # From pyproject.toml or default
cache: 'pip' # or 'poetry', 'pipenv'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt # or poetry install
- name: Run linter
run: |
pip install ruff
ruff check .
- name: Run tests
run: |
pip install pytest pytest-cov
pytest --cov=. --cov-report=xml
- name: Build
run: |
pip install build
python -m build
If language is Go:
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: '1.21' # From go.mod or default
cache: true
- name: Download dependencies
run: go mod download
- name: Run linter
run: |
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run
- name: Run tests
run: go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...
- name: Build
run: go build -v ./...
If language is Rust:
- name: Setup Rust
uses: actions-rust-lang/setup-rust-toolchain@v1
with:
toolchain: stable
cache: true
- name: Check formatting
run: cargo fmt --all -- --check
- name: Run Clippy
run: cargo clippy -- -D warnings
- name: Run tests
run: cargo test --all-features
- name: Build
run: cargo build --release
If language is Java (Maven):
- name: Setup Java
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
cache: 'maven'
- name: Build with Maven
run: mvn clean verify
- name: Run tests
run: mvn test
- name: Build JAR
run: mvn package -DskipTests
For Gradle:
- name: Setup Java
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
cache: 'gradle'
- name: Make gradlew executable
run: chmod +x gradlew
- name: Build with Gradle
run: ./gradlew build
- name: Run tests
run: ./gradlew test
For projects needing multi-version testing:
test:
name: Test (Node ${{ matrix.node-version }})
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
matrix:
node-version: [18, 20, 22]
fail-fast: false
steps:
- name: Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
Consider matrix for:
If type is cd:
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
inputs:
environment:
description: 'Deployment environment'
required: true
type: choice
options:
- staging
- production
permissions:
contents: read
id-token: write # Required for OIDC
jobs:
deploy-staging:
name: Deploy to Staging
runs-on: ubuntu-latest
timeout-minutes: 20
environment:
name: staging
url: https://staging.example.com
if: github.ref == 'refs/heads/main'
steps:
- name: Checkout code
uses: actions/checkout@v4
# OIDC Authentication - AWS Example
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
with:
role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
aws-region: us-east-1
- name: Deploy to staging
run: |
# Deployment commands here
# Example: aws s3 sync ./build s3://staging-bucket
# Example: kubectl apply -f k8s/staging/
echo "Deploying to staging..."
- name: Run smoke tests
run: |
# Smoke test commands
echo "Running health checks..."
deploy-production:
name: Deploy to Production
runs-on: ubuntu-latest
timeout-minutes: 30
environment:
name: production
url: https://example.com
needs: deploy-staging
if: github.ref == 'refs/heads/main'
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
with:
role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
aws-region: us-east-1
# Blue-Green Deployment Pattern
- name: Deploy to blue environment
run: |
echo "Deploying to blue environment..."
# Update blue environment
- name: Health check blue environment
run: |
echo "Checking blue environment health..."
# Wait for health checks to pass
- name: Switch traffic to blue
run: |
echo "Switching traffic..."
# Update load balancer to point to blue
- name: Monitor for issues
run: |
echo "Monitoring deployment..."
# Watch error rates for 5 minutes
- name: Keep blue as primary
run: |
echo "Deployment successful"
# Green becomes new blue for next deployment
- name: Azure Login
uses: azure/login@92a5484dfaf04ca78a94597f4f19fea633851fa2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- name: Deploy to Azure
run: |
az webapp deploy --name myapp --resource-group mygroup
- name: Authenticate to Google Cloud
uses: google-github-actions/auth@v2
with:
workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
service_account: '[email protected]'
- name: Deploy to GCP
run: |
gcloud run deploy myservice --image gcr.io/my-project/myimage
If type is release:
name: Release
on:
push:
tags:
- 'v*.*.*' # Semantic versioning tags
workflow_dispatch:
inputs:
version:
description: 'Release version (e.g., v1.2.3)'
required: true
permissions:
contents: write # Required to create releases
jobs:
validate:
name: Validate Release
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for changelog
- name: Validate version tag
run: |
if [[ "${{ github.ref }}" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "Valid semantic version tag"
else
echo "Invalid version tag format"
exit 1
fi
build:
name: Build Release Artifacts
runs-on: ubuntu-latest
timeout-minutes: 15
needs: validate
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific setup and build
- name: Build artifacts
run: |
# Build commands
# Example: npm run build
# Example: cargo build --release
echo "Building release artifacts..."
- name: Create release archive
run: |
tar -czf release.tar.gz dist/ # Adjust path as needed
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: release-artifacts
path: release.tar.gz
release:
name: Create GitHub Release
runs-on: ubuntu-latest
timeout-minutes: 10
needs: build
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Download artifacts
uses: actions/download-artifact@v4
with:
name: release-artifacts
- name: Generate changelog
id: changelog
run: |
# Generate changelog from git commits
PREVIOUS_TAG=$(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1) 2>/dev/null || echo "")
if [ -z "$PREVIOUS_TAG" ]; then
CHANGELOG=$(git log --pretty=format:"- %s (%h)" ${{ github.ref_name }})
else
CHANGELOG=$(git log --pretty=format:"- %s (%h)" $PREVIOUS_TAG..${{ github.ref_name }})
fi
echo "changelog<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGELOG" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
- name: Create Release
uses: softprops/action-gh-release@v1
with:
tag_name: ${{ github.ref_name }}
name: Release ${{ github.ref_name }}
body: |
## What's Changed
${{ steps.changelog.outputs.changelog }}
## Installation
Download the release archive and extract it.
files: |
release.tar.gz
draft: false
prerelease: false
publish:
name: Publish Package
runs-on: ubuntu-latest
timeout-minutes: 10
needs: release
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific publishing
# For npm:
# - uses: actions/setup-node@v4
# with:
# node-version: '20'
# registry-url: 'https://registry.npmjs.org'
# - run: npm publish
# env:
# NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# For PyPI:
# - uses: actions/setup-python@v5
# with:
# python-version: '3.11'
# - run: |
# pip install build twine
# python -m build
# twine upload dist/*
# env:
# TWINE_USERNAME: __token__
# TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
# For crates.io:
# - run: cargo publish --token ${{ secrets.CARGO_TOKEN }}
- name: Publish package
run: |
echo "Package publishing commands here"
If type is pr-checks:
name: PR Checks
on:
pull_request:
branches: [main, develop]
paths:
- 'src/**'
- 'tests/**'
- 'package.json' # Adjust for language
- '.github/workflows/pr-checks.yml'
# Cancel outdated runs when PR is updated
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: true
permissions:
contents: read
pull-requests: write # For PR comments
jobs:
changes:
name: Detect Changes
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
src: ${{ steps.filter.outputs.src }}
tests: ${{ steps.filter.outputs.tests }}
docs: ${{ steps.filter.outputs.docs }}
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Check file changes
uses: dorny/paths-filter@v2
id: filter
with:
filters: |
src:
- 'src/**'
tests:
- 'tests/**'
- 'test/**'
docs:
- 'docs/**'
- '**.md'
lint:
name: Lint Code
runs-on: ubuntu-latest
timeout-minutes: 10
needs: changes
if: needs.changes.outputs.src == 'true'
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific linting
- name: Run linter
run: |
# Lint commands
echo "Running linter..."
test:
name: Run Tests
runs-on: ubuntu-latest
timeout-minutes: 15
needs: changes
if: needs.changes.outputs.src == 'true' || needs.changes.outputs.tests == 'true'
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific testing
- name: Run tests
run: |
# Test commands
echo "Running tests..."
- name: Comment coverage
uses: actions/github-script@v7
if: always()
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '## Test Results\n\nAll tests passed! ✅'
})
security:
name: Security Scan
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run security scan
run: |
# Security scanning commands
# Example: npm audit
# Example: pip-audit
echo "Running security scan..."
build:
name: Build Check
runs-on: ubuntu-latest
timeout-minutes: 10
needs: [lint, test]
steps:
- name: Checkout code
uses: actions/checkout@v4
# Language-specific build
- name: Build
run: |
# Build commands
echo "Building project..."
summary:
name: PR Check Summary
runs-on: ubuntu-latest
timeout-minutes: 5
needs: [lint, test, security, build]
if: always()
steps:
- name: Check all jobs
run: |
if [ "${{ needs.lint.result }}" == "success" ] && \
[ "${{ needs.test.result }}" == "success" ] && \
[ "${{ needs.security.result }}" == "success" ] && \
[ "${{ needs.build.result }}" == "success" ]; then
echo "All PR checks passed!"
exit 0
else
echo "Some PR checks failed"
exit 1
fi
If type is reusable-workflow:
name: Reusable CI Workflow
on:
workflow_call:
inputs:
node-version:
description: 'Node.js version to use'
required: false
type: string
default: '20'
run-tests:
description: 'Whether to run tests'
required: false
type: boolean
default: true
environment:
description: 'Deployment environment'
required: false
type: string
default: 'staging'
secrets:
API_TOKEN:
description: 'API token for deployment'
required: true
SLACK_WEBHOOK:
description: 'Slack webhook for notifications'
required: false
outputs:
build-version:
description: 'Version of the built artifact'
value: ${{ jobs.build.outputs.version }}
permissions:
contents: read
jobs:
setup:
name: Setup
runs-on: ubuntu-latest
timeout-minutes: 5
outputs:
cache-key: ${{ steps.cache.outputs.key }}
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Generate cache key
id: cache
run: echo "key=deps-${{ hashFiles('package-lock.json') }}" >> $GITHUB_OUTPUT
test:
name: Test
runs-on: ubuntu-latest
timeout-minutes: 15
needs: setup
if: inputs.run-tests
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
build:
name: Build
runs-on: ubuntu-latest
timeout-minutes: 10
needs: [setup, test]
if: always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
outputs:
version: ${{ steps.version.outputs.version }}
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Get version
id: version
run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: build-${{ steps.version.outputs.version }}
path: dist/
notify:
name: Notify
runs-on: ubuntu-latest
timeout-minutes: 5
needs: build
if: always() && secrets.SLACK_WEBHOOK != ''
steps:
- name: Send notification
run: |
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"Workflow completed with status: ${{ needs.build.result }}"}' \
${{ secrets.SLACK_WEBHOOK }}
# Example: How to use this reusable workflow
#
# name: CI
#
# on:
# push:
# branches: [main]
#
# jobs:
# call-reusable-workflow:
# uses: ./.github/workflows/reusable-workflow.yml
# with:
# node-version: '20'
# run-tests: true
# environment: 'production'
# secrets:
# API_TOKEN: ${{ secrets.API_TOKEN }}
# SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
In generated template, identify all third-party actions:
For each third-party action, use git to resolve latest stable SHA:
git ls-remote https://github.com/docker/setup-buildx-action.git HEAD
Parse output to get commit SHA.
Replace version tags with resolved SHA:
uses: docker/setup-buildx-action@8c0edd44fd9d2d25d1f32147d34faabc28ce1b7d # v3.0.0
Include version comment for human readability.
If git resolution fails (network issue):
Prepend workflow with documentation:
# This workflow was generated by ccfg-github-actions scaffold
# Generated: 2026-02-09
# Language: JavaScript/Node.js
# Type: CI
#
# Required Secrets:
# - None for basic CI
# - CODECOV_TOKEN (optional) for coverage upload
#
# Required Repository Settings:
# - None
#
# Workflow runs on:
# - Push to main/develop branches
# - Pull requests to main
#
# For more information, see:
# - GitHub Actions docs: https://docs.github.com/actions
Include commented instructions:
# Setup Instructions:
# 1. Review and adjust branch names if needed
# 2. Configure required secrets in repository settings
# 3. Enable Actions in repository settings
# 4. Adjust timeouts based on project needs
# 5. Customize matrix strategy if multi-version testing needed
#
# Customization:
# - Adjust node-version to match your project requirements
# - Add/remove jobs as needed
# - Configure caching strategy
# - Add deployment steps
If conventions document exists:
# Organization Conventions:
# This workflow follows standards documented in:
# docs/infra/github-actions-conventions.md
#
# Key requirements:
# - SHA-pinned third-party actions
# - Explicit permissions blocks
# - Timeout on all jobs
# - Concurrency controls on PR workflows
Use Write tool to create workflow file:
file_path: /absolute/path/.github/workflows/ci.yml
content: [generated workflow content]
Confirm file was written successfully.
Create summary of what was generated:
Based on generated workflow, suggest complementary workflows:
Suggest adding security scanning if not included:
If conventions doc doesn't exist:
"Consider creating a conventions document at: docs/infra/github-actions-conventions.md
This helps maintain consistency across workflows and documents:
Provide checklist of repository settings to configure:
GitHub Actions Scaffold Complete
=================================
Generated: .github/workflows/ci.yml
Type: CI (Continuous Integration)
Language: JavaScript/Node.js (detected)
Workflow Details:
-----------------
Name: CI
Triggers:
- Push to main, develop branches
- Pull requests to main
Concurrency: Enabled with auto-cancel
Jobs:
1. lint (10min timeout)
- Checkout code
- Setup Node.js 20 with npm cache
- Install dependencies
- Run ESLint
2. test (15min timeout)
- Checkout code
- Setup Node.js 20 with npm cache
- Install dependencies
- Run Jest tests
- Upload coverage to Codecov
3. build (10min timeout, needs: [lint, test])
- Checkout code
- Setup Node.js 20 with npm cache
- Install dependencies
- Build with webpack
- Upload build artifacts
Security Features:
------------------
✓ SHA-pinned third-party actions
✓ Explicit permissions (contents: read)
✓ Timeout on all jobs
✓ Concurrency controls
✓ Dependency caching
Detected Configuration:
-----------------------
Package Manager: npm (package-lock.json found)
Node Version: 20 (from package.json engines)
Test Command: npm test (from package.json scripts)
Lint Command: npm run lint (from package.json scripts)
Build Command: npm run build (from package.json scripts)
Next Steps:
-----------
1. Review workflow file: .github/workflows/ci.yml
2. Adjust branch names if needed (currently: main, develop)
3. Configure secrets (optional):
- CODECOV_TOKEN for coverage upload
4. Commit and push to trigger first workflow run
5. Monitor workflow execution in Actions tab
Recommendations:
----------------
- Consider adding matrix testing for Node 18, 20, 22
- Add deployment workflow: /ccfg-github-actions scaffold --type=cd
- Add release automation: /ccfg-github-actions scaffold --type=release
- Create conventions document: docs/infra/github-actions-conventions.md
Resources:
----------
- Workflow file: /home/user/project/.github/workflows/ci.yml
- GitHub Actions docs: https://docs.github.com/actions
- Node.js Actions guide: https://docs.github.com/actions/guides/building-and-testing-nodejs
GitHub Actions Scaffold Complete
=================================
Generated: .github/workflows/deploy.yml
Type: CD (Continuous Deployment)
Language: JavaScript/Node.js (detected)
Workflow Details:
-----------------
Name: Deploy
Triggers:
- Push to main branch (auto-deploy to staging)
- Manual workflow dispatch with environment selection
Jobs:
1. deploy-staging (20min timeout)
Environment: staging
- Checkout code
- Configure AWS credentials (OIDC)
- Build application
- Deploy to staging environment
- Run smoke tests
2. deploy-production (30min timeout, needs: deploy-staging)
Environment: production
- Checkout code
- Configure AWS credentials (OIDC)
- Deploy to blue environment
- Health check blue environment
- Switch traffic to blue
- Monitor for issues
Security Features:
------------------
✓ SHA-pinned third-party actions
✓ Explicit permissions (contents: read, id-token: write for OIDC)
✓ Environment protection rules
✓ OIDC authentication (no long-lived credentials)
✓ Blue-green deployment pattern
✓ Health checks before traffic switch
Required Secrets:
-----------------
None - Using OIDC federation
Required Repository Settings:
------------------------------
1. Configure OIDC provider:
- Settings > Secrets and variables > Actions > Configure
- Add AWS OIDC provider
2. Create environments:
- Settings > Environments
- Create 'staging' environment
- Create 'production' environment
- Add protection rules and reviewers for production
3. AWS IAM Role:
- Create role: GitHubActionsRole
- Trust policy for OIDC federation
- ARN: arn:aws:iam::123456789012:role/GitHubActionsRole (update in workflow)
Next Steps:
-----------
1. Review workflow file: .github/workflows/deploy.yml
2. Update AWS IAM role ARN in workflow
3. Update deployment commands for your infrastructure
4. Configure staging and production environments in GitHub
5. Set up OIDC federation in AWS
6. Test deployment to staging first
Deployment Pattern:
-------------------
This workflow uses blue-green deployment:
- Deploy to inactive (blue) environment
- Health check blue environment
- Switch traffic from green to blue
- Monitor for issues
- Keep blue as active, green becomes next blue
Resources:
----------
- Workflow file: /home/user/project/.github/workflows/deploy.yml
- OIDC guide: https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
GitHub Actions Scaffold Complete
=================================
Generated: .github/workflows/reusable-workflow.yml
Type: Reusable Workflow
Language: JavaScript/Node.js (detected)
Workflow Details:
-----------------
Trigger: workflow_call
Inputs:
- node-version (string, default: '20')
- run-tests (boolean, default: true)
- environment (string, default: 'staging')
Secrets:
- API_TOKEN (required)
- SLACK_WEBHOOK (optional)
Outputs:
- build-version (version of built artifact)
Jobs:
1. setup (5min timeout)
- Checkout and install dependencies
- Generate cache key
2. test (15min timeout, conditional)
- Run tests if run-tests input is true
3. build (10min timeout)
- Build application
- Output version
- Upload artifacts
4. notify (5min timeout, conditional)
- Send Slack notification if webhook provided
Usage Example:
--------------
Create a caller workflow (.github/workflows/ci.yml):
name: CI
on:
push:
branches: [main]
jobs:
call-reusable-workflow:
uses: ./.github/workflows/reusable-workflow.yml
with:
node-version: '20'
run-tests: true
environment: 'production'
secrets:
API_TOKEN: ${{ secrets.API_TOKEN }}
SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
Next Steps:
-----------
1. Review reusable workflow: .github/workflows/reusable-workflow.yml
2. Customize inputs and secrets as needed
3. Create caller workflows to use this reusable workflow
4. Test with different input combinations
5. Document workflow contract for other teams
Benefits:
---------
- DRY: Define once, use many times
- Consistency: Same CI/CD logic across projects
- Maintainability: Update in one place
- Flexibility: Parameterized for different use cases
Resources:
----------
- Workflow file: /home/user/project/.github/workflows/reusable-workflow.yml
- Reusable workflows docs: https://docs.github.com/actions/learn-github-actions/reusing-workflows
@abc123... # v3.0.0Support user-provided templates:
.github/workflow-templates/ directorySupport organization-wide defaults:
.github/.github/workflows/ in org repoFor ambiguous situations:
Update existing workflows:
Test scaffolding with:
Validate generated workflows:
npx claudepluginhub jsamuelsen11/claude-config --plugin ccfg-github-actions/pipelineAdds and validates one CI/CD workflow bundle at a time for GitHub Actions (code quality, build/test, security, integration, operations). Supports --dry-run, --skip-install, --pr flags.
/ghactionsCreates, optimizes, secures, and debugs GitHub Actions workflows via flags like --create, --deploy, --harden, --matrix. Outputs YAML files, composite/reusable actions, security audits.
/ci-pipelineGenerates tailored GitHub Actions CI/CD workflow (.github/workflows/ci.yml) with lint/test/build/deploy jobs based on project analysis, plus README status badge.
/cc-cicdGenerates, audits, or templates CI/CD workflows for GitHub Actions, GitLab CI, or Azure Pipelines, integrating Claude Code for PR reviews, testing, code generation, and security scanning.
/composite-actionsScaffolds, audits, and secures composite GitHub Actions following best practices — includes full repo generation, SHA pinning, secrets-as-inputs, and actionlint validation.
/github-actionsCreates, evaluates, and optimizes GitHub Actions workflows and custom actions using a skill specialized for Ruby/Rails and TypeScript projects.