github-actions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Actions Workflow Creation

GitHub Actions工作流创建

Create and configure GitHub Actions workflows for CI/CD, automation, testing, and deployment.

为CI/CD、自动化、测试和部署场景创建并配置GitHub Actions工作流。

What GitHub Actions Provides

GitHub Actions的功能

GitHub Actions is a CI/CD platform that automates build, test, and deployment pipelines through configurable workflows triggered by repository events.

Core capabilities:

Continuous integration and deployment
Automated testing on pull requests
Package publishing and releases
Issue and project management automation
Scheduled tasks and cron jobs
Multi-platform builds (Linux, Windows, macOS)

Key concepts:

Workflows - Automated processes defined in YAML files
Events - Triggers like push, pull_request, schedule
Jobs - Sets of steps running on the same runner
Steps - Individual tasks (scripts or actions)
Actions - Reusable units of code
Runners - Servers executing workflows

GitHub Actions是一款CI/CD平台，可通过由仓库事件触发的可配置工作流，实现构建、测试和部署流水线的自动化。

核心能力:

持续集成与部署
拉取请求的自动化测试
包发布与版本发布
问题与项目管理自动化
定时任务与Cron作业
多平台构建（Linux、Windows、macOS）

关键概念:

Workflows - 用YAML文件定义的自动化流程
Events - 触发条件如push、pull_request、schedule
Jobs - 在同一个runner上运行的步骤集合
Steps - 单个任务（脚本或actions）
Actions - 可复用的代码单元
Runners - 执行工作流的服务器

Creating a Workflow

创建工作流

Basic Workflow Structure

基础工作流结构

Workflows live in

.github/workflows/

and use YAML syntax:

yaml

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Run tests
      run: npm test

工作流存储在

.github/workflows/

目录下，使用YAML语法：

yaml

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Run tests
      run: npm test

Workflow File Location

工作流文件位置

Create workflow files at:

.github/workflows/workflow-name.yml

Each repository can have multiple workflows for different purposes.

在以下路径创建工作流文件：

.github/workflows/workflow-name.yml

每个仓库可针对不同用途创建多个工作流。

Essential Components

核心组件

1. Workflow name:

yaml

name: CI Pipeline

2. Event triggers:

yaml

on:
  push:
    branches: [ main, develop ]
  pull_request:
  workflow_dispatch:  # Manual trigger

3. Jobs definition:

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

4. Steps with actions or scripts:

yaml

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm install
  - run: npm test

1. 工作流名称:

yaml

name: CI Pipeline

2. 事件触发器:

yaml

on:
  push:
    branches: [ main, develop ]
  pull_request:
  workflow_dispatch:  # 手动触发

3. 任务定义:

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

4. 包含actions或脚本的步骤:

yaml

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm install
  - run: npm test

Common Workflow Patterns

常见工作流模式

CI/CD for Node.js

Node.js的CI/CD

yaml

name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [18, 20, 22]
    
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm test

yaml

name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [18, 20, 22]
    
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm test

Build and Deploy

构建与部署

yaml

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Build
      run: npm run build
    
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

yaml

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Build
      run: npm run build
    
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

Multi-Job Workflow

多任务工作流

yaml

name: Build and Test

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/
      - run: npm test

yaml

name: Build and Test

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/
      - run: npm test

Event Triggers

事件触发器

Common Events

常见事件

Event	Usage	Example
`push`	Code pushed to branches	`on: push`
`pull_request`	PR opened/updated	`on: pull_request`
`workflow_dispatch`	Manual trigger	`on: workflow_dispatch`
`schedule`	Cron schedule	`on: schedule`
`release`	Release created	`on: release`
`issues`	Issue activity	`on: issues`

事件	用途	示例
`push`	代码推送到分支时	`on: push`
`pull_request`	拉取请求创建/更新时	`on: pull_request`
`workflow_dispatch`	手动触发	`on: workflow_dispatch`
`schedule`	Cron定时触发	`on: schedule`
`release`	版本发布创建时	`on: release`
`issues`	问题活动触发	`on: issues`

Event Configuration

事件配置

Branch filters:

yaml

on:
  push:
    branches:
      - main
      - 'releases/**'

Path filters:

yaml

on:
  push:
    paths:
      - 'src/**'
      - '**.js'

Schedule (cron):

yaml

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

Multiple events:

yaml

on:
  push:
    branches: [ main ]
  pull_request:
  workflow_dispatch:

分支过滤:

yaml

on:
  push:
    branches:
      - main
      - 'releases/**'

路径过滤:

yaml

on:
  push:
    paths:
      - 'src/**'
      - '**.js'

定时任务（Cron）:

yaml

on:
  schedule:
    - cron: '0 0 * * *'  # 每日午夜执行

多事件配置:

yaml

on:
  push:
    branches: [ main ]
  pull_request:
  workflow_dispatch:

Jobs and Steps

任务与步骤

Job Configuration

任务配置

Basic job:

yaml

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

Job dependencies:

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

Conditional jobs:

yaml

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

基础任务:

yaml

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

任务依赖:

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
  
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

条件任务:

yaml

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Matrix Builds

矩阵构建

Run jobs with multiple configurations:

yaml

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

使用多配置运行任务：

yaml

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

Environment Variables

环境变量

Repository secrets:

yaml

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.API_KEY }}
    run: ./deploy.sh

Environment variables:

yaml

env:
  NODE_ENV: production

jobs:
  build:
    env:
      BUILD_VERSION: 1.0.0
    steps:
      - run: echo $BUILD_VERSION

仓库密钥:

yaml

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.API_KEY }}
    run: ./deploy.sh

环境变量:

yaml

env:
  NODE_ENV: production

jobs:
  build:
    env:
      BUILD_VERSION: 1.0.0
    steps:
      - run: echo $BUILD_VERSION

Using Actions

使用Actions

Finding Actions

查找Actions

Search GitHub Marketplace: https://github.com/marketplace?type=actions

Popular actions:

```
actions/checkout@v4
```
- Clone repository
```
actions/setup-node@v4
```
- Setup Node.js
```
actions/setup-python@v5
```
- Setup Python
```
actions/cache@v4
```
- Cache dependencies
```
actions/upload-artifact@v4
```
- Store build artifacts
```
actions/download-artifact@v4
```
- Retrieve artifacts

在GitHub Marketplace搜索：https://github.com/marketplace?type=actions

热门Actions:

```
actions/checkout@v4
```
- 克隆仓库
```
actions/setup-node@v4
```
- 配置Node.js
```
actions/setup-python@v5
```
- 配置Python
```
actions/cache@v4
```
- 缓存依赖
```
actions/upload-artifact@v4
```
- 存储构建产物
```
actions/download-artifact@v4
```
- 拉取构建产物

Action Usage

Action使用方式

With inputs:

yaml

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

With outputs:

yaml

- id: build
  run: echo "version=1.0.0" >> $GITHUB_OUTPUT

- run: echo "Built version ${{ steps.build.outputs.version }}"

带输入参数:

yaml

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

带输出参数:

yaml

- id: build
  run: echo "version=1.0.0" >> $GITHUB_OUTPUT

- run: echo "Built version ${{ steps.build.outputs.version }}"

Contexts and Expressions

上下文与表达式

Common Contexts

常见上下文

Context	Description	Example
`github`	Workflow info	`${{ github.ref }}`
`env`	Environment variables	`${{ env.NODE_ENV }}`
`secrets`	Repository secrets	`${{ secrets.API_KEY }}`
`matrix`	Matrix values	`${{ matrix.node-version }}`
`steps`	Step outputs	`${{ steps.build.outputs.version }}`
`runner`	Runner environment	`${{ runner.os }}`

上下文	描述	示例
`github`	工作流信息	`${{ github.ref }}`
`env`	环境变量	`${{ env.NODE_ENV }}`
`secrets`	仓库密钥	`${{ secrets.API_KEY }}`
`matrix`	矩阵值	`${{ matrix.node-version }}`
`steps`	步骤输出	`${{ steps.build.outputs.version }}`
`runner`	Runner环境	`${{ runner.os }}`

Expressions

表达式

Conditionals:

yaml

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

Functions:

yaml

if: contains(github.event.pull_request.labels.*.name, 'deploy')
if: startsWith(github.ref, 'refs/tags/')
if: success() || failure()

条件判断:

yaml

if: github.event_name == 'push' && github.ref == 'refs/heads/main'

函数使用:

yaml

if: contains(github.event.pull_request.labels.*.name, 'deploy')
if: startsWith(github.ref, 'refs/tags/')
if: success() || failure()

Security Best Practices

安全最佳实践

Secrets Management

密钥管理

Store secrets in repository settings - Never commit secrets
Use environment secrets - For deployment environments
Scope secrets appropriately - Organization vs. repository level

yaml

steps:
  - name: Deploy
    env:
      API_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    run: ./deploy.sh

在仓库设置中存储密钥 - 绝不要提交密钥到仓库
使用环境密钥 - 针对部署环境配置
合理设置密钥范围 - 组织级 vs 仓库级

yaml

steps:
  - name: Deploy
    env:
      API_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    run: ./deploy.sh

Pull Request Security

拉取请求安全

Limit fork permissions:

yaml

on:
  pull_request_target:  # Use for fork PRs
    types: [opened, synchronize]

Require approval for forks: Configure in repository settings → Actions → Fork pull request workflows

限制分叉仓库权限:

yaml

on:
  pull_request_target:  # 用于分叉仓库的拉取请求
    types: [opened, synchronize]

分叉拉取请求需要审批: 在仓库设置 → Actions → 分叉拉取请求工作流中配置

Token Permissions

令牌权限

Restrict GITHUB_TOKEN:

yaml

permissions:
  contents: read
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({...})

限制GITHUB_TOKEN权限:

yaml

permissions:
  contents: read
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({...})

Debugging Workflows

调试工作流

Enable Debug Logging

启用调试日志

Set repository secrets:

```
ACTIONS_STEP_DEBUG: true
```
- Step debugging
```
ACTIONS_RUNNER_DEBUG: true
```
- Runner debugging

设置仓库密钥:

```
ACTIONS_STEP_DEBUG: true
```
- 步骤调试
```
ACTIONS_RUNNER_DEBUG: true
```
- Runner调试

View Logs

查看日志

Access workflow run logs from:

Repository → Actions tab
Select workflow run
Click job name
Expand steps to view output

从以下路径访问工作流运行日志:

仓库 → Actions标签
选择对应的工作流运行记录
点击任务名称
展开步骤查看输出

Common Issues

常见问题

Issue	Solution
Checkout fails	Use `actions/checkout@v4`
Secrets not available	Check secret name and scope
Step skipped	Check `if` conditions
Action version error	Update to latest version tag
Permission denied	Check `permissions` in workflow

问题	解决方案
拉取仓库失败	使用 `actions/checkout@v4`
密钥无法获取	检查密钥名称和范围
步骤被跳过	检查 `if` 条件配置
Action版本错误	更新到最新版本标签
权限不足	检查工作流中的 `permissions` 配置

Workflow Creation Checklist

工作流创建检查清单

Use this checklist when creating workflows:

File in
```
.github/workflows/
```
with
```
.yml
```
or
```
.yaml
```
extension
Workflow has descriptive
```
name
```
Appropriate event triggers configured
Runner OS specified with
```
runs-on
```
First step uses
```
actions/checkout@v4
```
Secrets used for sensitive data (never hardcoded)
Job dependencies configured with
```
needs
```
if required
Matrix strategy used for multi-environment testing (if needed)
Artifacts uploaded for build outputs (if needed)
Appropriate permissions set for
```
GITHUB_TOKEN
```
Workflow tested on feature branch before merging

创建工作流时使用以下检查清单:

文件存放在
```
.github/workflows/
```
目录下，后缀为
```
.yml
```
或
```
.yaml
```
工作流有描述性的
```
name
```
配置了合适的事件触发器
通过
```
runs-on
```
指定了Runner操作系统
第一步使用
```
actions/checkout@v4
```
敏感数据使用密钥（绝不硬编码）
若需要，通过
```
needs
```
配置任务依赖
若需要，使用矩阵策略进行多环境测试
若需要，上传构建产物作为artifacts
为
```
GITHUB_TOKEN
```
设置了合适的权限
合并到主分支前，在功能分支测试工作流

Additional Resources

额外资源

Reference Files

参考文档

For detailed syntax and patterns:

references/workflow-syntax.md
- Complete YAML syntax reference
references/common-patterns.md
- Workflow patterns by use case
references/security-guide.md
- Security best practices and OIDC

如需详细语法和模式:

references/workflow-syntax.md
- 完整YAML语法参考
references/common-patterns.md
- 按使用场景分类的工作流模式
references/security-guide.md
- 安全最佳实践与OIDC

Example Workflows

示例工作流

Working examples in

examples/

examples/ci-nodejs.yml
- Node.js CI with testing and linting
examples/ci-python.yml
- Python CI with multiple versions
examples/deploy-pages.yml
- Deploy to GitHub Pages
examples/release.yml
- Automated releases with changelog
examples/docker-build.yml
- Build and push Docker images

examples/

目录下的可用示例:

examples/ci-nodejs.yml
- 包含测试与代码检查的Node.js CI
examples/ci-python.yml
- 多版本Python的CI
examples/deploy-pages.yml
- 部署到GitHub Pages
examples/release.yml
- 自动生成变更日志的版本发布
examples/docker-build.yml
- 构建并推送Docker镜像

External Resources

外部资源

GitHub Actions documentation: https://docs.github.com/en/actions
GitHub Actions Marketplace: https://github.com/marketplace?type=actions
Workflow syntax reference: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

GitHub Actions官方文档: https://docs.github.com/en/actions
GitHub Actions市场: https://github.com/marketplace?type=actions
工作流语法参考: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

Quick Reference

快速参考

Minimal workflow:

yaml

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Common action versions:

```
actions/checkout@v4
```
```
actions/setup-node@v4
```
```
actions/setup-python@v5
```
```
actions/cache@v4
```
```
actions/upload-artifact@v4
```

Useful expressions:

```
${{ github.ref }}
```
- Current branch/tag
```
${{ github.sha }}
```
- Commit SHA
```
${{ runner.os }}
```
- Runner OS (Linux, Windows, macOS)
```
${{ secrets.SECRET_NAME }}
```
- Access secret
```
${{ matrix.value }}
```
- Matrix value

最简工作流:

yaml

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

常用Action版本:

```
actions/checkout@v4
```
```
actions/setup-node@v4
```
```
actions/setup-python@v5
```
```
actions/cache@v4
```
```
actions/upload-artifact@v4
```

实用表达式:

```
${{ github.ref }}
```
- 当前分支/标签
```
${{ github.sha }}
```
- 提交SHA
```
${{ runner.os }}
```
- Runner操作系统（Linux、Windows、macOS）
```
${{ secrets.SECRET_NAME }}
```
- 获取密钥
```
${{ matrix.value }}
```
- 矩阵值