GitHub Actions 详解

一、GitHub Actions 是什么

GitHub Actions 是 GitHub 内置的 CI/CD 自动化工具。

简单说：你在 GitHub 仓库里写一份配置文件，定义好"什么时候做什么事"，GitHub 就自动帮你跑。

代码 push 上去 → GitHub 自动触发 → 跑测试 → 打包 → 部署
                （全自动化，不用你管）

---

二、解决什么问题

没有 CI/CD 之前，你发布一个项目可能是这样的：

写代码 → 本地跑测试 → 本地打包 → 手动上传服务器 → 手动重启服务

问题很多：

• 麻烦：每次发布都要手动操作一堆步骤
• 容易出错：漏跑测试、打包错了版本、部署错环境
• 没法协作：每个人本地环境不一样，"我这能跑啊"

用了 GitHub Actions 之后：

push 代码 → 自动跑测试 → 自动打包 → 自动部署 → 通知结果

• 全自动化，一次配置终身受益
• 环境统一，不会有"我这能跑"的问题
• 每次提交都有记录，出问题好追溯

---

三、核心概念

概念	说明	大白话
Workflow	工作流，一份 .yml 配置文件就是一个 workflow	一套自动化流程
Event	触发事件，什么情况下触发 workflow	什么时候开始跑
Job	任务，一个 workflow 里可以有多个 job	做哪几件事
Step	步骤，每个 job 里有多个 step，按顺序执行	每一步具体干啥
Action	动作，社区写好的可复用步骤，直接拿来用	别人写好的插件
Runner	运行器，跑 workflow 的机器	干活的服务器

---

四、文件放哪儿

GitHub Actions 的配置文件统一放在仓库的这个目录下：

你的仓库/
└── .github/
    └── workflows/
        ├── ci.yml          # 可以叫任意名字
        ├── deploy.yml
        └── release.yml

每个 .yml 文件就是一个独立的工作流。

---

五、基础示例：Java 项目 CI

一步步来，先写一个最简单的：push 代码后自动跑测试。

完整配置

.github/workflows/ci.yml：

name: Java CI

# 什么时候触发
on:
  push:
    branches: [ main, develop ]   # push 到 main 或 develop 时触发
  pull_request:
    branches: [ main ]            # 提 PR 到 main 时触发

# 具体做什么
jobs:
  build:
    name: Build & Test
    runs-on: ubuntu-latest        # 在什么机器上跑（Ubuntu 最新版）

    steps:
      # 第一步：把代码拉下来
      - name: Checkout code
        uses: actions/checkout@v4

      # 第二步：装 JDK
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: maven              # 自动缓存 maven 依赖，下次更快

      # 第三步：跑测试
      - name: Run tests
        run: mvn test

      # 第四步：打包
      - name: Build package
        run: mvn package -DskipTests

      # 第五步：把打包结果上传（可以下载查看）
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: app-jar
          path: target/*.jar

逐行解释

触发条件 on

on:
  push:
    branches: [ main ]

意思是：有人往 main 分支 push 代码时，就跑这个 workflow。

常见的触发事件：

事件	说明
push	代码推送
pull_request	提 PR 或 PR 更新
schedule	定时触发（cron 表达式）
workflow_dispatch	手动触发（页面上点按钮）
release	发布 Release 时
issues	Issue 相关事件

运行环境 runs-on

runs-on: ubuntu-latest

GitHub 提供的免费 runner：

• ubuntu-latest（Linux）
• windows-latest（Windows）
• macos-latest（macOS）

也可以用自己的服务器（self-hosted runner）。

步骤 steps

steps:
  - uses: actions/checkout@v4    # uses = 用别人写好的 action
  - run: mvn test                # run = 执行一条命令

• uses：引用社区或官方的 action，开箱即用
• run：执行 shell 命令，想干啥干啥

---

六、进阶示例：自动部署到服务器

在 CI 的基础上，加上自动部署。

.github/workflows/deploy.yml：

name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    name: Build & Deploy
    runs-on: ubuntu-latest

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

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: maven

      - name: Build
        run: mvn package -DskipTests

      # 通过 SSH 部署到服务器
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: 22
          script: |
            cd /opt/myapp
            git pull
            mvn package -DskipTests
            systemctl restart myapp
            echo "部署完成"

密钥怎么配置

配置里的 ${{ secrets.XXX }} 是 GitHub 的 Secrets 功能，敏感信息不能明文写在 yml 里。

配置方法：

1. 打开仓库 → Settings → Secrets and variables → Actions
2. New repository secret
3. 名字填 SERVER_HOST，值填服务器 IP
4. 同理添加 SERVER_USER、SSH_PRIVATE_KEY

---

七、高级示例：多 Job + 矩阵测试

多版本测试（矩阵）

name: Multi-version Test

on: [push, pull_request]

jobs:
  test:
    name: Test on Java ${{ matrix.java }} / ${{ matrix.os }}
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        java: [ '11', '17', '21' ]
        os: [ ubuntu-latest, windows-latest ]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: ${{ matrix.java }}
          distribution: 'temurin'

      - run: mvn test

这样会生成 3 × 2 = 6 个任务并行跑：

• Java 11 + Ubuntu
• Java 11 + Windows
• Java 17 + Ubuntu
• ...

Job 之间有依赖

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: mvn test

  build:
    needs: test          # 等 test 通过了才跑 build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: mvn package

  deploy:
    needs: build         # 等 build 通过了才跑 deploy
    runs-on: ubuntu-latest
    steps:
      - run: echo "部署中..."

test → build → deploy
 （串行，前面挂了后面就不跑了）

---

八、常用的 Action 推荐

Action	用途
actions/checkout@v4	拉取代码（几乎必用）
actions/setup-java@v4	安装 JDK
actions/setup-node@v4	安装 Node.js
actions/upload-artifact@v4	上传构建产物
actions/download-artifact@v4	下载构建产物
actions/cache@v4	缓存依赖，加速构建
appleboy/ssh-action@v1.0.3	SSH 到服务器执行命令
docker/build-push-action@v5	构建并推送 Docker 镜像
peaceiris/actions-gh-pages@v4	部署到 GitHub Pages

---

九、实用技巧

1. 手动触发

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

配置后，在 Actions 页面可以手动点按钮运行，还能选参数。

2. 定时任务

on:
  schedule:
    - cron: '0 2 * * *'   # 每天凌晨 2 点跑（UTC 时间）

⚠️ cron 是 UTC 时间，北京时间要减 8 小时。比如北京时间早上 10 点 = UTC 2 点。

3. 跳过 CI

commit message 里加 [skip ci]，这次 push 就不会触发 workflow：

git commit -m "更新文档 [skip ci]"

4. 查看运行结果

仓库页面 → Actions 标签 → 能看到所有 workflow 的运行记录，绿色=成功，红色=失败，点进去能看每一步的日志输出。

5. 徽章

README 里加个徽章，显示构建状态：

![CI](https://github.com/用户名/仓库名/workflows/Java%20CI/badge.svg)

效果： 类似这样。

---

十、常见坑

1. 路径问题：每个 step 都是从仓库根目录开始，注意相对路径
2. 时区问题：runner 默认 UTC 时间，定时任务记得换算
3. 缓存失效：依赖变了缓存没更新，清理缓存重试
4. 网络问题：runner 在国外，访问国内资源可能慢或失败
5. 敏感信息泄露：绝对不要把密码、密钥写在 yml 里，用 Secrets
6. Job 是独立的：两个 job 之间不共享文件，要传文件用 artifact

---

一句话总结：GitHub Actions 就是 GitHub 自带的自动化机器人，在 .github/workflows/ 里写 yml 配置好触发条件和执行步骤，就能实现自动测试、自动打包、自动部署等各种流水线操作。