workflow-development
创建、调试和优化GitHub Actions工作流程,遵循安全最佳实践。当用户说“创建工作流程”、“修复工作流程”、“工作流程失败”、“添加CI”、“可重用工作流程”或需要GitHub Actions的帮助时使用此技能。
📖 中文导读:创建、调试和优化GitHub Actions工作流程,遵循安全最佳实践。当用户说“创建工作流程”、“修复工作流程”、“工作流程失败”、“添加CI”、“可重用工作流程”或需要GitHub Actions的帮助时使用此技能。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: workflow-development description: Create, debug, and optimize GitHub Actions workflows with security best practices. USE THIS SKILL when user says "create workflow", "fix workflow", "workflow fails", "add CI", "reusable workflow", or needs help with GitHub Actions. allowed-tools: - Bash - Read - Write - Edit - Glob - Grep
Workflow Development Skill
Purpose
Create, debug, and optimize GitHub Actions workflows with security best practices.
Triggers
- "create a CI workflow"
- "add a release workflow"
- "my workflow is failing"
- "make this workflow reusable"
- "workflow security audit"
- "add [language] CI"
Usage
Invoke this skill to create new CI/CD workflows, debug failing workflows, or convert existing workflows to use reusable patterns with proper SHA pinning and minimal permissions.
Security Requirements (Non-Negotiable)
SHA Pinning
# CORRECT
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
# WRONG - Never use tags
- uses: actions/checkout@v4
Minimal Permissions
permissions:
contents: read # Start with minimum
# Only add what's needed:
# pull-requests: write # For PR comments
# packages: write # For container registry
Reusable Workflow Pattern
Caller (in project)
name: CI
on: [push, pull_request]
jobs:
ci:
uses: zircote/.github/.github/workflows/reusable-ci-python.yml@main
with:
python-version: '3.12'
coverage-threshold: 80
secrets: inherit
Reusable Definition (in .github repo)
name: Reusable Python CI
on:
workflow_call:
inputs:
python-version:
required: false
type: string
default: '3.12'
coverage-threshold:
required: false
type: number
default: 80
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
- uses: zircote/.github/actions/setup-python-uv@main
with:
python-version: ${{ inputs.python-version }}
- run: uv run ruff check .
Available Reusable Workflows
| Workflow | Purpose |
|---|---|
reusable-ci-python.yml |
Python with uv, ruff, pyright, pytest |
reusable-ci-typescript.yml |
TypeScript with pnpm, ESLint, Vitest |
reusable-ci-go.yml |
Go with golangci-lint |
reusable-release.yml |
Semantic release |
reusable-security.yml |
Gitleaks + dependency scanning |
reusable-docs.yml |
Documentation deployment |
reusable-content.yml |
Content validation |
Composite Action Pattern
# action.yml
name: 'Setup Python with uv'
description: 'Install Python and uv with caching'
inputs:
python-version:
required: false
default: '3.12'
runs:
using: 'composite'
steps:
- uses: astral-sh/setup-uv@v4
with:
enable-cache: true
- shell: bash
run: uv python install ${{ inputs.python-version }}
Debugging Workflows
Common Failures
| Error | Cause | Fix |
|---|---|---|
| "Resource not accessible" | Missing permission | Add to permissions: |
| Cache never hits | Wrong key | Check hashFiles path |
| Secrets unavailable | Wrong context | Use secrets: inherit |
| Workflow not triggered | Event mismatch | Check on: config |
Debug Step
- name: Debug
run: |
echo "Event: ${{ github.event_name }}"
echo "Ref: ${{ github.ref }}"
echo "Actor: ${{ github.actor }}"
Validation
# Validate SHA pinning
./scripts/validate-sha-pinning.sh .github/workflows/
# Check for unpinned actions
grep -rn "uses:.*@v[0-9]" .github/workflows/
# Validate workflow structure
./scripts/validate-workflows.sh .github/workflows/
Performance Optimization
Caching
- uses: actions/cache@0c907a75c2c80ebcb7f088228285e798b750cf8f
with:
path: ~/.cache/uv
key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
Matrix Builds
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
python: ['3.11', '3.12']
Concurrency
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true