GitHub Actions：完整指南与快速入门教程

更新于 2026-01-27

什么是 GitHub Actions？

GitHub Actions 是 GitHub 内置的自动化框架，旨在帮助开发者在整个软件开发生命周期（SDLC）中实现工作流自动化。GitHub 拥有超过 1 亿用户，这使得 GitHub Actions 成为众多开发团队触手可及的选项。

GitHub Actions 使用事件驱动的触发器来运行一系列步骤（称为“作业”），这些作业可以在多种环境中执行，包括 GitHub 托管的运行器（runner）和自托管运行器。开发者可以使用 YAML 语法定义这些工作流，从而在自己的代码仓库中直接创建版本可控、可重复且易于维护的 CI/CD 流水线。

GitHub Actions 与 GitHub 的 API、代码仓库和 Issue 系统深度集成，使得从测试、构建到部署应用和管理发布等所有环节都能实现自动化。该解决方案还提供了一个庞大的可复用操作（action）市场，促进 CI/CD 流水线中的协作与标准化。

GitHub Actions 的五大核心功能

GitHub Actions 提供了多项关键功能，旨在简化开发者的自动化任务，支持各种开发与运维场景：

  • 工作流自动化：自动化软件开发生命周期中的各类任务，包括持续集成（CI）、测试和部署。开发者可以使用 YAML 格式创建工作流，无缝集成到现有的 GitHub 仓库中。
  • 事件驱动触发：操作可由多种 GitHub 事件触发，例如代码提交（commits）、拉取请求（pull requests）或 Issue 更新。这种事件驱动的自动化机制使团队能够对代码变更或问题做出快速响应，无需人工干预。
  • 可复用的操作（Actions）：GitHub Marketplace 提供了大量预构建的操作，开发者既可以复用现有工作流，也可以构建自定义操作。这些操作可在多个项目间共享，提升模块化程度和效率。
  • 与 GitHub 生态系统集成：提供对 GitHub API、仓库及其他工具的访问能力。这种深度集成使得代码、工作流和 Issue 管理都能在一个统一平台上完成。
  • 自定义运行器（Runners）：除了 GitHub 提供的预配置运行器（支持主流开发环境），用户还可以部署自托管运行器。这种灵活性允许团队根据项目需求定制环境、优化成本并配置特定硬件。

GitHub Actions 组件详解

工作流（Workflows）

工作流由位于仓库 .github/workflows 目录下的 YAML 文件定义。该文件指定了要执行的事件序列和作业，为自动化流程提供了蓝图。每个仓库可以定义多个工作流，分别响应不同的触发条件或执行不同的任务。

每个工作流都可以设置触发器（即“事件”），决定何时启动执行。这种定义方式允许对自动化时机和方式进行精细控制，从而构建量身定制的 CI/CD 流程。此外，工作流可以并发运行，确保需要立即处理的任务能够并行完成。

事件（Events）

GitHub Actions 中的事件用于触发工作流，决定特定工作流何时启动。典型事件包括代码提交、拉取请求或合并等——这些都是开发周期中常需自动化的关键节点。开发者还可以定义自定义事件，以满足特定的自动化需求。

基于特定条件触发工作流的能力有助于维持高效的 CI/CD 流水线。事件还可通过分支、标签或用户等上下文进一步过滤，提供更精细的触发控制。

作业（Jobs）

作业由一系列步骤组成，用于执行自动化流程中的具体任务。每个作业在隔离的环境中运行，并可依赖其他作业，从而定义操作的执行顺序。这种依赖机制有助于高效管理复杂工作流，确保步骤按正确顺序执行。

在作业内部，步骤通过单个操作或脚本执行，这些脚本可用多种编程语言编写（如 JavaScript 或 Python）。这种灵活性使开发者能为每项任务选择最合适的工具，精确定制作业内容。

操作（Actions）

操作是 GitHub Actions 中作业内执行的独立任务。它们可以是小型可复用脚本，也可以是执行复杂操作的完整包，例如设置 Node.js 环境或将代码部署到云服务。开发者既可以创建自定义操作，也可以使用 GitHub Marketplace 中的现成操作。

操作的模块化特性促进了复用性和社区共享，使开发者能够站在他人工作的基础上构建。通过组合一系列操作，开发者可以创建高度定制化且高效的工作流。此外，操作支持跨项目或团队共享，增强协作能力。

运行器（Runners）

运行器是 GitHub Actions 中执行作业的环境。GitHub 提供灵活选项：

  • GitHub 托管运行器：为常见操作系统预配置了构建和部署所需软件，简化了设置流程，无需额外基础设施即可快速启动作业。
  • 自托管运行器：为需要更多环境控制的开发者提供可定制方案。通过将自有机器配置为运行器，开发者可满足特定软硬件需求、优化成本并利用现有资源。

快速入门教程：创建你的第一个 GitHub Actions 工作流

本快速入门指南将带你创建并运行第一个 GitHub Actions 工作流。

1. 创建工作流文件

首先，在 GitHub 上进入你的仓库。如果根目录下尚无 .github/workflows 目录，请先创建它。然后在此目录中新建一个名为 demo-github-actions-workflow.yml 的文件。

将以下工作流定义粘贴到该文件中：

name: Demo GitHub Actions Workflow
on: [push]
jobs:
  Discover-GitHub-Actions-Workflows:
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ github.event_name }} event automatically triggered this job."
      - run: echo "A ${{ runner.os }} server hosted by GitHub has this job running"
      - run: echo "Details of your repository: repo-name: ${{ github.repository }} and branch name is ${{ github.ref }} and your repository is ${{ github.repository }}."
      - name: Checking out the repository's code
        uses: actions/checkout@v3
      - run: echo "The runner has cloned your ${{ github.repository }} repository."
      - run: echo "The workflow can now test your code with the runner."
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      - run: echo "This job has a ${{ job.status }} status."

通过 GitHub 界面提交该文件：选择“提议新文件”，创建新分支并发起拉取请求。一旦提交，工作流将由文件中定义的 push 事件自动触发。

2. 查看工作流结果

要检查工作流运行情况：

  1. 进入仓库主页，点击 Actions 标签页。
  2. 在左侧边栏中找到并点击 Demo GitHub Actions Workflow。
  3. 在工作流运行列表中，选择由创建 YAML 文件所触发的那次运行。
  4. 在 Jobs 下点击 Discover-GitHub-Actions-Workflows 查看日志。
  5. 日志中每一步都会显示执行的命令和输出，GitHub 特定变量（如 ${{ github.repository }}）会被实际值替换。
  6. 点击 List files in the repository 步骤，即可看到工作区中的文件列表。

GitHub 还会根据仓库中检测到的框架或语言提供入门模板工作流，你可以以此为基础进行定制，以满足项目需求。

GitHub Actions 最佳实践

为了充分发挥 GitHub Actions 的优势，同时确保工作流的安全性、稳定性和高效性，请遵循以下最佳实践：

  • 设置工作流超时时间：默认情况下，GitHub 允许工作流运行长达 6 小时，可能导致 PR 长时间挂起或作业卡住。建议为每个作业显式设置 timeout-minutes。大多数场景下，30 分钟已足够。这有助于保持 CI 流水线响应迅速，并防止因卡住的作业造成资源瓶颈。

  • 使用并发控制：当短时间内推送多个提交时，可能触发冗余工作流。在 YAML 文件中定义并发组（concurrency group），可在新作业启动时取消同一上下文中正在进行的作业，避免不必要的构建并减少排队时间。

    concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

  • 限制工作流权限：GitHub 默认为工作流提供一个权限较宽泛的访问令牌。应遵循最小权限原则，仅授予所需权限。例如，若 CI 工作流无需写操作，可将其限制为只读：

    permissions:
  contents: read

  • 将操作版本固定到 SHA：避免使用 @v3 或 @latest 等标签引用操作，因为这些标签可能随时间变化。应将操作固定到具体的提交 SHA，以确保一致性，并防范第三方代码中的恶意或意外变更。

    uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846

  • 谨慎评估第三方操作：将操作视为外部依赖项。优先选择由可信组织（如 GitHub 或 Exercism）维护的操作，并在使用前评估其维护活跃度。对于关键逻辑，尽可能自行实现以掌握控制权。

  • 使用版本化的运行器：将运行器环境固定到特定版本（如 ubuntu-22.04），而非使用 ubuntu-latest。这可减少构建变异性，并防止环境突变导致工作流中断。

  • 安全地管理密钥（Secrets）：将密钥存储在 GitHub 加密的密钥管理器中，并限制其仅对特定环境或工作流可见。切勿在工作流文件中硬编码密钥。

  • 缓存依赖以提升速度：使用 actions/cache 功能在作业间复用构建产物或依赖项。这能显著减少设置时间，尤其适用于大型包生态系统。

  • 保持 YAML 文件可读性：通过一致的命名、缩进和注释组织工作流。对跨仓库共享的逻辑，使用复合操作（composite actions）。清晰的 YAML 文件更易于调试，也便于团队协作维护。

GitHub Actions 定价

GitHub Actions 的定价模型基于仓库类型（公开或私有）、存储空间以及 GitHub 托管运行器所使用的分钟数。

  • 公开仓库：免费使用 GitHub 托管运行器。
  • 私有仓库：根据账户计划提供有限的免费分钟数和存储空间。

私有仓库的免费额度如下：

计划类型 存储空间 免费分钟数
GitHub Free 500 MB 2,000 分钟
GitHub Pro 1 GB 3,000 分钟
GitHub Team 2 GB 3,000 分钟
GitHub Enterprise Cloud 50 GB 50,000 分钟

超出免费额度后将产生超额费用：

  • 存储：$0.008 / GB / 天
  • 运行分钟费用（按操作系统）：
    • Linux：$0.008 / 分钟
    • Windows：$0.016 / 分钟
    • macOS：$0.08 / 分钟

自托管运行器不产生使用费用，是私有仓库的成本优化选择。但需注意，大型运行器或 Windows/macOS 运行器会以更高倍率消耗分钟数。

组织还可连接 Azure 订阅以获得额外支付选项，尤其适用于超出免费层级的大规模使用场景。

GitHub Actions 的局限性

尽管 GitHub Actions 提供了强大的自动化功能，但仍存在一些局限性和挑战，根据 G2 平台用户的反馈：

  • 复杂性高：平台功能丰富，对新手而言可能显得复杂。尤其是对不熟悉版本控制的用户，设置工作流的学习曲线较为陡峭。
  • 私有仓库免费额度有限：虽然 GitHub 提供了一定免费资源，但对于大型或复杂项目团队而言往往不足。额外资源的成本可能成为小团队或预算有限组织的负担，尤其在需要私有仓库时，定价可能过高。
  • 性能不稳定：用户报告即使对于小型应用，部署速度也较慢，偶尔还会遇到停机或性能延迟问题。这些延迟不仅影响生产力，还会消耗宝贵的免费分钟配额，令受限用户感到沮丧。
  • 排错困难：GitHub Actions 内部问题的调试可能耗时较长，缺乏统一全面的排错指南，导致工作流出错时修复延迟。

此外，根据我们的经验，许多组织使用 GitHub Actions 及相关工具来实现完整的持续交付（Continuous Delivery, CD）流水线，尽管这些工具最初并非为此设计。这导致了“影子 CD（Shadow CD）”问题：

  • 影子 CD 制造了自动化的假象，但缺乏人们信任该流程所必需的关键要素。
  • 为管理平台不支持的自动化层级，开发者往往编写包含数百甚至数千行代码的脚本集合。
  • 这些脚本通常由少数工程师（有时仅一人）创建和维护，导致维护、安全和支持成为重大挑战。
  • 与手动部署类似，基于脚本的部署无法提供可重复、可靠的发布能力，也无法提供足够的可见性以建立团队信任。