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网页 #
- 打开你的仓库页面
- 点击 “Actions” 标签
- 在左侧选择 “Hello World” 工作流
- 点击具体的运行记录查看详情
方法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=trueACTIONS_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: 工作流没有触发? #
检查以下项:
- 文件是否在
.github/workflows/目录下 - 文件扩展名是否为
.yml或.yaml - YAML语法是否正确
- 触发条件是否满足
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