github-actions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Actions

Automate software workflows directly in your GitHub repository with GitHub Actions.

直接在你的GitHub仓库中使用GitHub Actions自动化软件工作流。

When to Use This Skill

何时使用此技能

Use this skill when:

Setting up CI/CD pipelines for GitHub repositories
Automating build, test, and deployment workflows
Creating reusable workflow components
Configuring self-hosted runners
Managing workflow secrets and variables
Debugging failed workflow runs

在以下场景中使用此技能：

为GitHub仓库设置CI/CD流水线
自动化构建、测试和部署工作流
创建可复用的工作流组件
配置自托管运行器（self-hosted runners）
管理工作流密钥与变量
调试失败的工作流运行

Prerequisites

前提条件

GitHub repository with write access
Understanding of YAML syntax
For self-hosted runners: server with Docker (optional)

拥有写入权限的GitHub仓库
了解YAML语法
对于自托管运行器：装有Docker的服务器（可选）

Workflow File Structure

工作流文件结构

Workflows are defined in

.github/workflows/

directory:

yaml

name: CI Pipeline

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

工作流定义在

.github/workflows/

目录中：

yaml

name: CI Pipeline

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

Common Triggers

常见触发条件

Push and Pull Request

推送与拉取请求

yaml

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'
  pull_request:
    branches: [main]

yaml

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'
  pull_request:
    branches: [main]

Scheduled Runs

定时运行

yaml

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

yaml

on:
  schedule:
    - cron: '0 2 * * *'  # 每天UTC时间2点运行

Manual Dispatch

手动触发

yaml

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

yaml

on:
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Job Configuration

任务配置

Matrix Builds

矩阵构建

yaml

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

yaml

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

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
      
  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build
      
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test
      
  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Environment Protection

环境保护

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - run: ./deploy.sh

yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - run: ./deploy.sh

Secrets and Variables

密钥与变量

Using Secrets

使用密钥

yaml

steps:
  - name: Deploy
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    run: aws s3 sync ./dist s3://my-bucket

yaml

steps:
  - name: Deploy
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    run: aws s3 sync ./dist s3://my-bucket

Using Variables

使用变量

yaml

steps:
  - name: Build
    env:
      API_URL: ${{ vars.API_URL }}
    run: npm run build

yaml

steps:
  - name: Build
    env:
      API_URL: ${{ vars.API_URL }}
    run: npm run build

Caching Dependencies

依赖缓存

yaml

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

yaml

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

Artifacts

工件管理

Upload Artifacts

上传工件

yaml

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

yaml

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

Download Artifacts

下载工件

yaml

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

yaml

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

Docker Builds

Docker构建

yaml

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: user/app:latest

yaml

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: 登录Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      
      - name: 构建并推送
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: user/app:latest

Reusable Workflows

可复用工作流

Define Reusable Workflow

定义可复用工作流

yaml

undefined

yaml

undefined

.github/workflows/reusable-deploy.yml

name: Reusable Deploy

on: workflow_call: inputs: environment: required: true type: string secrets: deploy_key: required: true

jobs: deploy: runs-on: ubuntu-latest environment: ${{ inputs.environment }} steps: - run: echo "Deploying to ${{ inputs.environment }}"

undefined

name: Reusable Deploy

on: workflow_call: inputs: environment: required: true type: string secrets: deploy_key: required: true

jobs: deploy: runs-on: ubuntu-latest environment: ${{ inputs.environment }} steps: - run: echo "Deploying to ${{ inputs.environment }}"

undefined

Call Reusable Workflow

调用可复用工作流

yaml

jobs:
  deploy-staging:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
    secrets:
      deploy_key: ${{ secrets.STAGING_KEY }}

yaml

jobs:
  deploy-staging:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
    secrets:
      deploy_key: ${{ secrets.STAGING_KEY }}

Self-Hosted Runners

自托管运行器

Register Runner

注册运行器

bash

undefined

bash

undefined

Download runner

下载运行器

mkdir actions-runner && cd actions-runner curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz tar xzf actions-runner-linux-x64.tar.gz

Configure

配置

./config.sh --url https://github.com/OWNER/REPO --token TOKEN

Run

运行

./run.sh

undefined

./run.sh

undefined

Use Self-Hosted Runner

使用自托管运行器

yaml

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

yaml

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4

Debugging Workflows

调试工作流

Enable Debug Logging

启用调试日志

Set repository secrets:

```
ACTIONS_RUNNER_DEBUG
```
:
```
true
```
```
ACTIONS_STEP_DEBUG
```
:
```
true
```

设置仓库密钥：

```
ACTIONS_RUNNER_DEBUG
```
:
```
true
```
```
ACTIONS_STEP_DEBUG
```
:
```
true
```

Debug Step

调试步骤

yaml

- name: Debug
  run: |
    echo "GitHub context: ${{ toJson(github) }}"
    echo "Job context: ${{ toJson(job) }}"

yaml

- name: 调试
  run: |
    echo "GitHub上下文: ${{ toJson(github) }}"
    echo "任务上下文: ${{ toJson(job) }}"

Common Issues

常见问题

Issue: Workflow Not Triggering

问题：工作流未触发

Problem: Workflow doesn't run on push/PR Solution: Check branch filters, path filters, and ensure workflow file is on the default branch

问题：推送/拉取请求时工作流未运行 解决方案：检查分支过滤、路径过滤，并确保工作流文件在默认分支上

Issue: Permission Denied

问题：权限被拒绝

Problem: Actions can't push or create PRs Solution: Configure

permissions

in workflow or update repository settings

yaml

permissions:
  contents: write
  pull-requests: write

问题：Actions无法推送或创建拉取请求 解决方案：在工作流中配置

permissions

或更新仓库设置

yaml

permissions:
  contents: write
  pull-requests: write

Issue: Cache Not Restoring

问题：缓存未恢复

Problem: Cache misses despite existing cache Solution: Verify cache key matches exactly, check runner OS

问题：已有缓存但仍未命中 解决方案：验证缓存键完全匹配，检查运行器操作系统

Best Practices

最佳实践

Pin action versions to specific commits or tags
Use caching for dependencies to speed up builds
Minimize secrets exposure with environment scoping
Use matrix builds for cross-platform testing
Implement proper error handling with
```
continue-on-error
```
Keep workflows DRY with reusable workflows and composite actions

将Action版本固定到特定提交或标签
使用依赖缓存加速构建
通过环境范围最小化密钥暴露
使用矩阵构建进行跨平台测试
用
```
continue-on-error
```
实现适当的错误处理
通过可复用工作流和复合Action保持工作流简洁（DRY）

github-actions

Original

Translation

GitHub Actions

GitHub Actions

When to Use This Skill

何时使用此技能

Prerequisites

前提条件

Workflow File Structure

工作流文件结构

Common Triggers

常见触发条件

Push and Pull Request

推送与拉取请求

Scheduled Runs

定时运行

Manual Dispatch

手动触发

Job Configuration

任务配置

Matrix Builds

矩阵构建

Job Dependencies

任务依赖

Environment Protection

环境保护

Secrets and Variables

密钥与变量

Using Secrets

使用密钥

Using Variables

使用变量

Caching Dependencies

依赖缓存

Artifacts

工件管理

Upload Artifacts

上传工件

Download Artifacts

下载工件

Docker Builds

Docker构建

Reusable Workflows

可复用工作流

Define Reusable Workflow

定义可复用工作流

.github/workflows/reusable-deploy.yml

.github/workflows/reusable-deploy.yml

Call Reusable Workflow

调用可复用工作流

Self-Hosted Runners

自托管运行器

Register Runner

注册运行器

Download runner

下载运行器

Configure

配置

Run

运行

Use Self-Hosted Runner

使用自托管运行器

Debugging Workflows

调试工作流

Enable Debug Logging

启用调试日志

Debug Step

调试步骤

Common Issues

常见问题

Issue: Workflow Not Triggering

问题：工作流未触发

Issue: Permission Denied

问题：权限被拒绝

Issue: Cache Not Restoring

问题：缓存未恢复

Best Practices

最佳实践

Related Skills