知识库

Appearance

Return to top
On this page

GitHub Actions基础概念

GitHub Actions是GitHub提供的持续集成和持续部署（CI/CD）服务，允许开发者在GitHub仓库中自动化软件开发工作流程。通过GitHub Actions，可以在代码推送、拉取请求、问题创建等各种事件发生时自动执行预定义的任务。

核心概念

Workflow（工作流）

工作流是GitHub Actions中最顶层的概念，定义了自动化的执行流程。工作流由一个或多个job组成，存储在仓库的.github/workflows/目录下，使用YAML格式编写。

yaml
# .github/workflows/ci.yml
name: Continuous Integration

on: [push, pull_request]

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

工作流属性：

  • name: 工作流的名称，显示在GitHub界面上
  • on: 触发工作流的事件
  • env: 环境变量
  • jobs: 工作流中包含的一个或多个job

Event（事件）

事件是触发工作流执行的特定活动，例如：

yaml
# 单个事件
on: push

# 多个事件
on: [push, pull_request]

# 详细配置事件
on:
  push:
    branches: [main, develop]
    paths: ['src/**']
  pull_request:
    branches: [main]
    types: [opened, synchronize]

常见的事件类型：

  • push: 代码推送到仓库
  • pull_request: 拉取请求创建或更新
  • schedule: 定时触发（使用cron表达式）
  • workflow_dispatch: 手动触发
  • release: 发布版本

Job（作业）

作业是在运行器上执行的一组步骤，一个工作流可以包含一个或多个作业：

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
  
  test:
    runs-on: ubuntu-latest
    needs: build  # 依赖build作业
    steps:
      - name: Run tests
        run: npm test

Step（步骤）

步骤是作业中的单个任务，可以运行命令或使用action：

yaml
steps:
  - name: Checkout repository
    uses: actions/checkout@v4
  - name: Install dependencies
    run: npm install
  - name: Run linter
    run: npm run lint
    env:
      NODE_ENV: development

Action（动作）

Action是可重用的独立命令，是GitHub Actions的核心构建块：

yaml
steps:
  # 使用社区提供的action
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '18'
  
  # 使用仓库中的action
  - uses: ./path/to/action
  
  # 使用Docker容器action
  - uses: docker://alpine:latest

Runner（运行器）

运行器是执行作业的服务器，可以是：

  • GitHub托管的运行器（ubuntu-latest, windows-latest, macos-latest）
  • 自托管运行器（自行配置的服务器）

工作流语法详解

基本结构

yaml
name: Workflow Name          # 工作流名称

on:                         # 触发事件
  push:
    branches: [main]

env:                        # 环境变量
  NODE_VERSION: '18'

jobs:                       # 作业集合
  job1:                     # 作业名称
    runs-on: ubuntu-latest  # 运行器
    steps:                  # 步骤列表
      - name: Step name
        run: command

触发事件配置

yaml
on:
  # 推送事件
  push:
    branches: [main, develop]
    tags: ['v*']
    paths: ['src/**', 'package.json']
  
  # 拉取请求事件
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]
  
  # 定时事件（UTC时间）
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨2点
  
  # 手动触发
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

条件执行

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'  # 仅在main分支执行
    steps:
      - name: Conditional step
        if: ${{ env.NODE_VERSION == '18' }}
        run: echo "Running on Node 18"

矩阵构建

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

环境变量和上下文

预定义环境变量

GitHub Actions提供许多预定义的环境变量：

yaml
jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - name: Print environment info
        run: |
          echo "Repository: $GITHUB_REPOSITORY"
          echo "Actor: $GITHUB_ACTOR"
          echo "SHA: $GITHUB_SHA"
          echo "Ref: $GITHUB_REF"
          echo "Workspace: $GITHUB_WORKSPACE"

上下文和表达式

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Conditional deployment
        run: |
          if [ "${{ github.event_name }}" == "push" ] && [ "${{ github.ref }}" == "refs/heads/main" ]; then
            echo "Deploying to production..."
          fi
        env:
          BRANCH_NAME: ${{ github.ref_name }}
          RUNNER_OS: ${{ runner.os }}

Secrets（密钥）

敏感信息如API密钥、密码等应存储为secrets：

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        run: deploy-script.sh
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Artifacts（构件）

工作流可以上传和下载构件（文件）：

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build application
        run: npm run build
      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-output
      - name: Deploy
        run: |
          # Deployment commands here

常用Actions

官方Actions

yaml
steps:
  # 代码检出
  - uses: actions/checkout@v4
  
  # 设置Node.js环境
  - uses: actions/setup-node@v4
    with:
      node-version: '18'
      cache: 'npm'
  
  # 设置Java环境
  - uses: actions/setup-java@v4
    with:
      distribution: 'temurin'
      java-version: '17'
  
  # 设置Python环境
  - uses: actions/setup-python@v4
    with:
      python-version: '3.11'

社区Actions

yaml
steps:
  # 代码质量检查
  - uses: github/super-linter@v4
  
  # Docker镜像构建
  - uses: docker/build-push-action@v5
    with:
      context: .
      push: true
      tags: user/app:latest
  
  # 发布到npm
  - uses: JS-DevTools/npm-publish@v3
    with:
      token: ${{ secrets.NPM_TOKEN }}

工作流最佳实践

组织结构

yaml
# .github/workflows/test.yml
name: Test Suite
on:
  push:
    branches-ignore:
      - 'gh-pages'
  pull_request:

env:
  NODE_VERSION: '18'
  CI: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - name: Upload coverage
        if: success()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/

错误处理和重试

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      max-parallel: 1
      fail-fast: false
    steps:
      - name: Deploy with retry
        run: |
          for i in {1..3}; do
            if deploy-command; then
              break
            elif [ $i -eq 3 ]; then
              exit 1
            fi
            sleep 10
          done

安全考虑

最小权限原则

yaml
# 限制工作流权限
name: Secure Workflow
on: [push]

permissions:
  contents: read  # 只读权限
  packages: write # 需要时才给予写权限

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # 不需要额外权限的构建步骤

Secrets验证

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Validate secrets
        run: |
          if [ -z "$SECRET_VAR" ]; then
            echo "Secret not set!"
            exit 1
          fi
        env:
          SECRET_VAR: ${{ secrets.REQUIRED_SECRET }}

总结

GitHub Actions的核心概念包括工作流、事件、作业、步骤、动作和运行器。理解这些概念是有效使用GitHub Actions的基础。通过合理配置工作流，可以实现自动化构建、测试、部署等任务，提高开发效率和软件质量。在实际使用中，应遵循安全最佳实践，合理组织工作流文件，并充分利用GitHub Actions的强大功能。