Git---GitHub Actions

GitHub Actions 是 GitHub 提供的一项强大功能，用于实现软件开发过程中的自动化，涵盖了持续集成（CI）、持续部署（CD）等多个方面。

1. 基本概念

1.1 工作流（Workflow）

工作流是在 GitHub 仓库中定义的自动化流程，它由一个或多个作业组成，存储在仓库的 .github/workflows 目录下的 YAML 文件中。一个仓库可以有多个工作流，每个工作流可以根据不同的事件触发。

1.2 作业（Job）

作业是工作流中的一个独立执行单元，每个作业在一个单独的运行器上运行。作业可以并行或串行执行，并且可以依赖其他作业的结果。

1.3 步骤（Step）

步骤是作业中的最小执行单元，它可以是一个 shell 命令或者一个动作。一个作业可以包含多个步骤，这些步骤按顺序执行。

1.4 动作（Action）

动作是 GitHub Actions 的可复用组件，它可以完成特定的任务，如拉取代码、安装依赖、运行测试等。动作可以来自 GitHub 市场或自定义。

1.5 运行器（Runner）

运行器是执行工作流的服务器，可以是 GitHub 托管的运行器（如 Ubuntu、Windows、macOS），也可以是自托管的运行器。

2. 工作流文件结构

工作流文件使用 YAML 格式编写，以下是一个基本的工作流文件示例：

name: My Workflow  # 工作流的名称
on:  # 触发工作流的事件
  push:
    branches:
      - main
jobs:  # 定义作业
  build:  # 作业的 ID
    runs-on: ubuntu-latest  # 指定运行器的操作系统
    steps:  # 定义步骤
      - name: Checkout code  # 步骤的名称
        uses: actions/checkout@v4  # 使用的动作
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:  # 传递给动作的参数
          node-version: 20
      - name: Install dependencies
        run: npm install  # 执行的 shell 命令
      - name: Run tests
        run: npm test

3. 触发事件（on 字段）

工作流可以由多种事件触发，以下是一些常见的触发事件：

3.1 代码事件

• push：当代码推送到指定分支时触发。

on:
  push:
    branches:
      - main
      - develop

• pull_request：当创建、更新或合并拉取请求时触发。

on:
  pull_request:
    types:
      - opened
      - synchronize

3.2 定时事件

• schedule：使用 cron 表达式按指定时间触发。

on:
  schedule:
    - cron: '0 0 * * *'  # 每天凌晨执行

3.3 手动触发

• workflow_dispatch：允许用户在 GitHub 界面手动触发工作流。

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy'
        required: true
        default: 'staging'

4. 作业配置

4.1 运行器选择

可以使用 runs-on 字段指定作业运行的环境，如 ubuntu-latest、windows-latest、macos-latest 等。

jobs:
  build:
    runs-on: ubuntu-latest

4.2 作业依赖

使用 needs 字段指定作业之间的依赖关系，确保作业按顺序执行。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build
        run: echo "Building..."
  test:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Test
        run: echo "Testing..."

4.3 矩阵策略

使用 strategy 字段可以并行执行多个作业，例如在不同的操作系统或版本上进行测试。

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [18, 20]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

5. 步骤配置

5.1 使用动作

使用 uses 字段引用一个动作，可以是 GitHub 市场上的公开动作或自定义动作。

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

5.2 执行命令

使用 run 字段执行 shell 命令。

steps:
  - name: Install dependencies
    run: npm install

5.3 传递参数

使用 with 字段向动作传递参数。

steps:
  - name: Set up Node.js
    uses: actions/setup-node@v4
    with:
      node-version: 20

6. 环境变量和秘密

6.1 环境变量

可以在工作流、作业或步骤中定义环境变量，使用 env 字段。

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      APP_ENV: production
    steps:
      - name: Print environment variable
        run: echo $APP_ENV

6.2 秘密

敏感信息（如 API 密钥、密码等）可以存储在 GitHub 仓库的秘密（Secrets）中，在工作流中使用 ${{ secrets.SECRET_NAME }} 引用。

steps:
  - name: Deploy to server
    run: ssh user@server "deploy ${{ secrets.DEPLOY_KEY }}"

7. 工件（Artifacts）

工件用于在作业之间传递文件或在工作流结束后下载文件。可以使用 actions/upload-artifact 和 actions/download-artifact 动作。

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Build
        run: npm run build
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: build-output
      - name: Deploy
        run: echo "Deploying build output..."

8. 工作流状态和通知

8.1 状态检查

GitHub 会显示工作流的运行状态，如成功、失败、正在运行等。可以在拉取请求中设置状态检查，确保代码满足特定条件才能合并。

8.2 通知

可以通过 GitHub 提供的通知功能或第三方工具（如 Slack、Email 等）接收工作流运行结果的通知。

9. 自定义动作

可以创建自定义动作，将常用的功能封装成可复用的组件。自定义动作可以是 JavaScript 动作或 Docker 动作。

9.1 JavaScript 动作

JavaScript 动作使用 Node.js 编写，需要在 action.yml 文件中定义动作的元数据。

# action.yml
name: 'My Custom Action'
description: 'A custom action to do something'
inputs:
  input1:
    description: 'Input parameter'
    required: true
runs:
  using: 'node16'
  main: 'index.js'

// index.js
const core = require('@actions/core');
const input = core.getInput('input1');
console.log(`Processing input: ${input}`);

9.2 Docker 动作

Docker 动作使用 Docker 容器运行，需要在 action.yml 文件中指定 Dockerfile。

# action.yml
name: 'My Docker Action'
description: 'A custom Docker action'
inputs:
  input1:
    description: 'Input parameter'
    required: true
runs:
  using: 'docker'
  image: 'Dockerfile'

# Dockerfile
FROM alpine:latest
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

# entrypoint.sh
#!/bin/sh
echo "Processing input: $INPUT_INPUT1"

10. 安全性考虑

• 限制权限：确保工作流使用的动作和命令具有最小的必要权限，避免泄露敏感信息。
• 更新动作：定期更新使用的动作，以修复安全漏洞。
• 审查代码：对自定义动作和工作流文件进行代码审查，确保没有安全隐患。

---

示例：简单的代码检查工作流

这个工作流会在每次代码推送到 main 分支时，检查代码文件的数量。

name: Simple Code Check
on:
  push:
    branches:
      - main
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Count files
        run: |
          file_count=$(ls -1 | wc -l)
          echo "Number of files in the repository: $file_count"    

此工作流由以下部分组成：

• name：工作流的名称为 Simple Code Check。
• on：指定工作流会在代码推送到 main 分支时触发。
• jobs：定义了一个名为 check 的作业。
• runs-on：作业会在最新的 Ubuntu 环境中运行。
• steps：包含两个步骤，第一步使用 actions/checkout@v4 拉取代码，第二步统计文件数量并输出结果。