Monte Library 私人知识库 资料库 EN

原始笔记

GitHub Actions Quickstart（整理版）

GitHub Actions Quickstart（整理版）

原始资料: Quickstart for GitHub Actions created: 2026-07-01 17:49 整理说明: 本版本结合原始笔记和可读取的 GitHub Docs 教程重排、补全和翻译，保留常用英文术语；教程截图已下载到本地附件目录，便于 Obsidian 快速打开。

内容简要概括

这篇笔记记录如何用 GitHub Actions 创建第一个可运行的 workflow，并通过一次 push 事件自动触发它。核心步骤是：在仓库中创建 .github/workflows/github-actions-demo.yml，写入示例 YAML，提交后到 GitHub 的 Actions 页面查看 workflow run、job 和 step 日志。这个 Quickstart 的重点不是掌握所有语法，而是快速跑通 GitHub Actions 的最小闭环。

GitHub Actions、CI/CD、workflow、YAML、.github/workflows、github-actions-demo.yml、push、job、step、runner、ubuntu-latest、actions/checkout、workflow run、GitHub-hosted runner

目录

1. GitHub Actions 的作用

GitHub Actions 是 GitHub 内置的 CI/CD 自动化平台，可以把 build、test、deployment 等流程写成 workflow，并在特定事件发生时自动执行。

常见使用方式包括：

  • 每次 push 后自动运行测试。
  • PR 合并后自动部署到生产环境。
  • 用预配置 workflow templates 快速生成项目的 CI、deployment、automation、code scanning 或 GitHub Pages workflow。
  • 通过 workflow run 的日志检查每个 job 和 step 的执行细节。

这篇 Quickstart 的目标是先跑通一个示例 workflow。此阶段不需要完全理解 ${{ github.actor }}、${{ github.event_name }}、${{ github.workspace }} 等 context，只需要知道它们是 GitHub Actions 在运行时提供的上下文变量。

2. 前置条件与 workflow 文件位置

开始前需要满足三个条件：

  • 已经基本会使用 GitHub 仓库、branch 和 PR。
  • 有一个可以添加文件的 GitHub repository。
  • 该 repository 已启用 GitHub Actions。

GitHub Actions 的 workflow 文件必须放在仓库根目录下的 .github/workflows 目录中。文件名可以自定义，但扩展名必须是 .yml 或 .yaml。

推荐的 Quickstart 文件路径是：

.github/workflows/github-actions-demo.yml

如果仓库中已经有 .github/workflows 目录，可以进入该目录后创建 github-actions-demo.yml。如果还没有这个目录，可以直接在 GitHub 网页端创建 .github/workflows/github-actions-demo.yml，GitHub 会同时创建中间目录和文件。

3. 创建第一个 workflow

把下面的 YAML 内容写入 .github/workflows/github-actions-demo.yml：

name: GitHub Actions Demo
run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
on: [push]
jobs:
  Explore-GitHub-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v6
      - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."

3.1 字段速读

字段 作用
name workflow 在 GitHub Actions 页面中显示的名称。
run-name 单次 workflow run 的显示名称，可以使用 context。
on: [push] 当代码被 push 到 branch 时触发 workflow。
jobs 定义一个或多个 job。
Explore-GitHub-Actions 示例 job 的 ID。
runs-on: ubuntu-latest 在 GitHub-hosted Ubuntu runner 上运行该 job。
steps job 内按顺序执行的步骤。
uses: actions/checkout@v6 把仓库代码 checkout 到 runner。
run 在 runner shell 中执行命令。

3.2 提交流程

在 GitHub 网页端创建并保存 workflow 文件后，点击 Commit changes。可以直接提交到默认分支，也可以创建新 branch 并发起 PR。

只要包含 workflow 文件的 commit 被提交到 branch，就会触发 push 事件并运行这个 workflow。即使选择创建 PR，对 Quickstart 来说也已经完成了触发 workflow 的关键步骤。

4. 查看 workflow 运行结果

workflow 触发后，可以在 GitHub 的 Actions 页面查看结果。

  1. 打开 GitHub repository 首页。
  2. 点击仓库顶部导航中的 Actions。

Actions tab highlighted

  1. 在左侧边栏选择要查看的 workflow，例如 GitHub Actions Demo。

Workflow sidebar highlighted

  1. 在 workflow runs 列表中点击某次运行，例如 USERNAME is testing out GitHub Actions。
  2. 在 workflow run 页面左侧 Jobs 下点击 Explore-GitHub-Actions。

Job in workflow run highlighted

  1. 展开 step，可以查看每一步的日志。

Workflow run logs

例如，展开 List files in the repository 后可以看到 ls ${{ github.workspace }} 输出的仓库文件列表。

List files step log detail

5. 原始教程要点

GitHub Docs 的 Quickstart 还补充了几个学习方向：

  • 如果想从预配置模板开始，可以查看 GitHub 提供的 workflow templates，常见分类包括 CI、Deployments、Automation、Code Scanning 和 Pages。
  • 这个示例 workflow 的目的只是演示基础能力：触发事件、选择 runner、checkout 代码、执行 shell 命令、查看 job status。
  • 跑通 Quickstart 后，下一步可以继续学习 workflow syntax、contexts、build and test、package publishing、deployment，以及更复杂的 concurrency 和 test matrix。
  • 如果仓库中看不到 Actions tab，可能是仓库设置里禁用了 GitHub Actions，需要检查 repository settings。

6. 可复用模板汇总

6.1 最小 workflow 文件路径

.github/workflows/<workflow-name>.yml

6.2 最小触发模型

name: Example Workflow
on: [push]

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v6
      - name: Run a shell command
        run: |
          ls ${{ github.workspace }}

6.3 查看结果的固定路径

Repository page -> Actions -> Workflow name -> Workflow run -> Job -> Step logs

Switch to English