GitHub Actions 快速开始 #

本节将帮助你快速设置GitHub Actions,创建并运行你的第一个工作流。

前置条件 #

1. GitHub账户 #

确保你有一个GitHub账户。如果没有,前往 github.com 注册。

2. 创建仓库 #

创建一个新的仓库用于练习:

bash
# 使用GitHub CLI创建仓库
gh repo create my-actions-demo --public

# 或者在GitHub网页上创建

3. 克隆仓库到本地 #

bash
git clone https://github.com/YOUR_USERNAME/my-actions-demo.git
cd my-actions-demo

创建第一个工作流 #

步骤1:创建工作流目录 #

bash
mkdir -p .github/workflows

步骤2:创建工作流文件 #

创建 .github/workflows/hello.yml 文件:

yaml
name: Hello World

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        run: echo "Hello, GitHub Actions!"
      
      - name: Show Environment
        run: |
          echo "Runner OS: ${{ runner.os }}"
          echo "Repository: ${{ github.repository }}"
          echo "Branch: ${{ github.ref_name }}"

步骤3:提交并推送 #

bash
git add .
git commit -m "Add hello workflow"
git push origin main

查看工作流运行 #

方法1:通过GitHub网页 #

  1. 打开你的仓库页面
  2. 点击 “Actions” 标签
  3. 在左侧选择 “Hello World” 工作流
  4. 点击具体的运行记录查看详情

方法2:使用GitHub CLI #

bash
# 列出工作流运行
gh run list

# 查看特定运行的详情
gh run view

# 实时查看日志
gh run watch

工作流文件解析 #

让我们详细解析上面的工作流文件:

yaml
# 工作流名称 - 显示在GitHub Actions页面
name: Hello World

# 触发条件
on:
  push:                    # 推送事件
    branches:
      - main               # 仅main分支
  workflow_dispatch:       # 允许手动触发

# 作业定义
jobs:
  hello:                   # 作业ID
    runs-on: ubuntu-latest # 运行环境
    
    # 步骤定义
    steps:
      - name: Say Hello    # 步骤名称
        run: echo "Hello, GitHub Actions!"  # 执行的命令
      
      - name: Show Environment
        run: |             # 多行命令
          echo "Runner OS: ${{ runner.os }}"
          echo "Repository: ${{ github.repository }}"
          echo "Branch: ${{ github.ref_name }}"

常用触发事件 #

push - 推送触发 #

yaml
on:
  push:
    branches:
      - main
      - 'release/*'
    paths:
      - 'src/**'
      - '.github/workflows/**'

pull_request - PR触发 #

yaml
on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main

schedule - 定时触发 #

yaml
on:
  schedule:
    - cron: '0 0 * * *'  # 每天UTC 0点

workflow_dispatch - 手动触发 #

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

运行器选择 #

GitHub提供多种托管运行器:

运行器 标签 用途
Ubuntu ubuntu-latest Linux环境
Windows windows-latest Windows环境
macOS macos-latest macOS环境
yaml
jobs:
  test:
    runs-on: ubuntu-latest
    
  test-windows:
    runs-on: windows-latest
    
  test-mac:
    runs-on: macos-latest

多作业示例 #

yaml
name: Multi-Job Example

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building..."
      
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Testing..."
      
  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

使用Actions #

检出代码 #

yaml
steps:
  - uses: actions/checkout@v4

设置Node.js环境 #

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

设置Python环境 #

yaml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: '3.11'
  - run: pip install -r requirements.txt
  - run: pytest

调试工作流 #

启用调试日志 #

在仓库设置中添加以下Secrets:

  • ACTIONS_RUNNER_DEBUG = true
  • ACTIONS_STEP_DEBUG = true

查看失败原因 #

yaml
steps:
  - name: Failing Step
    run: exit 1
    continue-on-error: true  # 即使失败也继续执行
    
  - name: Always Run
    if: always()  # 无论前面结果如何都执行
    run: echo "This always runs"

最佳实践 #

1. 使用版本固定的Action #

yaml
# 推荐:使用具体版本
- uses: actions/checkout@v4

# 不推荐:使用main分支
- uses: actions/checkout@main

2. 使用有意义的名称 #

yaml
jobs:
  build-and-test:  # 清晰的作业名称
    runs-on: ubuntu-latest
    steps:
      - name: Install Dependencies  # 清晰的步骤名称
        run: npm ci

3. 使用环境变量 #

yaml
env:
  NODE_VERSION: '20'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

4. 添加超时设置 #

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # 作业超时
    steps:
      - run: echo "This job will timeout after 30 minutes"
        timeout-minutes: 5  # 步骤超时

常见问题 #

Q: 工作流没有触发? #

检查以下项:

  1. 文件是否在 .github/workflows/ 目录下
  2. 文件扩展名是否为 .yml.yaml
  3. YAML语法是否正确
  4. 触发条件是否满足

Q: 如何重新运行失败的工作流? #

bash
gh run rerun <run-id>

或在GitHub网页上点击 “Re-run jobs”。

Q: 如何取消正在运行的工作流? #

bash
gh run cancel <run-id>

下一步学习 #

小结 #

  • 创建 .github/workflows/ 目录存放工作流文件
  • 使用YAML格式定义工作流
  • 工作流由触发器、作业和步骤组成
  • GitHub提供托管的运行器环境
  • 使用Actions可以简化常见任务
最后更新:2026-03-28