github-actions（GitHub Actions 自动化）

GitHub Actions

Quick Start

Create a workflow file at .github/workflows/<name>.yml:

name: CI
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello World"

Essential concepts:

• Workflow: Automated process defined in YAML, runs in response to events
• Job: Set of steps that run on the same runner
• Step: Individual action or shell command
• Action: Reusable unit of code (GitHub marketplace or custom)
• Event: What triggers the workflow (push, pull_request, schedule, etc.)

Common Workflow Patterns

Continuous Integration (CI)

• Testing: Run tests on every push/PR
• Linting: Code quality checks
• Building: Compile code, build artifacts
• See: references/tutorials/build-and-test-code/

Continuous Deployment (CD)

• Deploy to production: Merge to main → deploy
• Multi-environment: dev/staging/prod with approvals
• Blue-green deployment: Zero-downtime deployments
• See: references/how-tos/deploy/

Scheduled Tasks

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

Matrix Builds

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [14, 16, 18]

Workflow Syntax Reference

Required Structure

• name: Workflow name
• on: Triggers (events, schedules, manual)
• jobs: One or more jobs

Key Job Fields

• runs-on: Runner type (ubuntu-latest, windows-latest, macos-latest, self-hosted)
• steps: Sequential list of steps
• strategy: Matrix, fail-fast, max-parallel
• outputs: Job-to-job data passing

Key Step Types

steps:
  - name: 'Checkout code'
    uses: actions/checkout@v4

  - name: 'Run script'
    run: npm test

  - name: 'Use action'
    uses: actions/setup-node@v4
    with:
      node-version: '18'

Complete syntax reference: references/reference/workflows-and-actions/workflow-syntax.md

Trigger Events

Common Events

• push: Commits pushed to branch
• pull_request: PR opened/updated/closed
• workflow_dispatch: Manual trigger
• schedule: Cron-based execution

Advanced Events

• release: Release published
• workflow_call: Reusable workflow
• repository_dispatch: Webhook-triggered
• environment: Environment deployment

Complete events reference: references/reference/workflows-and-actions/events-that-trigger-workflows.md

Expressions and Contexts

Expression Syntax

if: github.event_name == 'push'
runs-on: ${{ matrix.os }}

Common Contexts

• github: Event details, repo, actor, ref
• env: Environment variables
• job: Job status, outputs
• steps: Step outputs
• runner: Runner OS, architecture
• secrets: Encrypted secrets
• vars: Custom variables

Complete expressions reference: references/reference/workflows-and-actions/expressions.md Complete contexts reference: references/reference/workflows-and-actions/contexts.md

Security Best Practices

Secrets Management

steps:
  - run: deploy.sh ${{ secrets.API_KEY }}

• Never log secrets (GitHub auto-redacts)
• Use secrets context for sensitive data
• Store in repository Settings → Secrets

Security guide: references/concepts/security/secrets.md

GITHUB_TOKEN

• Automatically provided authentication
• Scoped permissions for repo access
• Use for repo operations (clone, push, create PR)

GITHUB_TOKEN reference: references/concepts/security/github_token.md

OIDC (OpenID Connect)

• Cloud deployments without long-lived credentials
• Supports AWS, Azure, GCP, and more
• Configure OIDC in workflow and cloud provider

OIDC guide: references/concepts/security/openid-connect.md

Security Hardening

• Pin action versions (@v4 not @main)
• Require approval for external workflows
• Use artifact attestations for supply chain security

Security hardening: references/how-tos/security-harden-workflows/

Reusable Workflows and Actions

Reusable Workflows

# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      version:
        required: true
        type: string

# Call from another workflow
jobs:
  call:
    uses: org/repo/.github/workflows/reusable.yml@main
    with:
      version: '1.0'

Composite Actions

Combine multiple steps into a reusable action.

Custom Actions

• JavaScript/TypeScript actions
• Docker actions
• Composite actions

Reusable workflows: references/concepts/workflows-and-actions/reusing-workflow-configurations.md Custom actions: references/concepts/workflows-and-actions/custom-actions.md

Deployment Patterns

Environments

jobs:
  deploy:
    environment: production
    environment:
      url: https://example.com

Deployment Protection Rules

• Require approval before production
• Restrict who can deploy
• Wait timers for manual review

Third-Platform Deployments

• Azure: App Service, Kubernetes, Static Web Apps
• AWS: ECS, EKS, Lambda
• GCP: Kubernetes Engine, Cloud Run

Deployment guides: references/how-tos/deploy/

Caching Dependencies

- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Caching reference: references/concepts/workflows-and-actions/dependency-caching.md

Artifacts and Logs

Upload Artifacts

- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/

Download Artifacts

- uses: actions/download-artifact@v4
  with:
    name: build-output

Artifacts reference: references/concepts/workflows-and-actions/workflow-artifacts.md

Troubleshooting

Enable Debug Logging

Add secret ACTIONS_STEP_DEBUG and ACTIONS_RUNNER_DEBUG to repository.

Common Issues

• Permission errors: Check permissions scope
• Path issues: Use ${{github.workspace}}
• Secret issues: Verify secret names and scopes

Viewing Logs

• Actions tab → Workflow run → Job → Step
• Download logs for offline analysis

Troubleshooting guide: references/how-tos/troubleshoot-workflows.md

Migrating from Other CI Systems

• Jenkins: Import tool and manual patterns
• GitLab CI: Syntax differences and equivalents
• CircleCI: Migration patterns
• Travis CI: Direct equivalents

Migration guides: references/tutorials/migrate-to-github-actions/

Language-Specific Guides

• Node.js: references/tutorials/build-and-test-code/nodejs.md
• Python: references/tutorials/build-and-test-code/python.md
• Java: Maven, Gradle, Ant guides
• .NET: Build and test patterns
• Go, Rust, Ruby, PowerShell: Specific guides

Runners

GitHub-Hosted Runners

• ubuntu-latest: Linux (Ubuntu)
• windows-latest: Windows Server
• macos-latest: macOS
• Larger runners: More CPU/memory (paid)

Self-Hosted Runners

• Custom environments
• Private network access
• Custom tools and dependencies

Runners reference: references/concepts/runners/

Complete Documentation Index

All 242 documentation files are available in references/:

Getting Started

• Quickstart: references/get-started/quickstart.md
• Understanding Actions: references/get-started/understand-github-actions.md
• CI/CD overview: references/get-started/continuous-*.md

Concepts

• Workflows: references/concepts/workflows-and-actions/
• Runners: references/concepts/runners/
• Security: references/concepts/security/

How-To Guides

• Write workflows: references/how-tos/write-workflows/
• Deploy: references/how-tos/deploy/
• Create actions: references/how-tos/create-and-publish-actions/
• Security hardening: references/how-tos/security-harden-workflows/

Reference

• Workflow syntax: references/reference/workflows-and-actions/workflow-syntax.md
• Events: references/reference/workflows-and-actions/events-that-trigger-workflows.md
• Expressions: references/reference/workflows-and-actions/expressions.md
• Contexts: references/reference/workflows-and-actions/contexts.md
• Variables: references/reference/workflows-and-actions/variables.md
• Workflow commands: references/reference/workflows-and-actions/workflow-commands.md

Tutorials

• Build and test: references/tutorials/build-and-test-code/
• Migrate to Actions: references/tutorials/migrate-to-github-actions/
• Create actions: references/tutorials/create-actions/
• Publish packages: references/tutorials/publish-packages/

Complete index: references/_index.md

Online Documentation

All documentation files include source URLs linking to the official GitHub Docs. Use these links to:

• Verify information is current
• Check for updates and changes
• View rendered examples and screenshots
• Report issues or suggest improvements

Official GitHub Actions Docs: https://docs.github.com/en/actions