使用GitHub Actions为机器人代码设置CI

在团队环境中工作的一个重要方面是能够测试推送到像 GitHub 一样的中央存储库的代码。例如，项目经理或首席开发人员可能希望在合并拉取请求之前运行一组单元测试，或者可能想要确保存储库主分支上的所有代码都处于正常工作状态。

GitHub Actions <https://github.com/features/actions> _ 是一项服务，它允许团队和个人在各个分支上的代码以及请求请求上构建和运行单元测试。这些类型的服务通常称为“连续集成”服务。本教程将向你展示如何在机器人代码项目上设置 GitHub Actions 。

备注

本教程假定您团队的机器人代码托管在GitHub上。有关Git和GitHub的简介，请参见：doc：入门指南</docs/software/basic-programming/git-getting-started>。

创建动作

进行 CI 处理的指令存储在 YAML 文件中。为了创建动作，请单击存储库顶部的 “操作” 选项卡。然后单击 “自行设置工作流程” 超链接。

你现在会看到一个文本编辑器。将所有默认文本替换为以下内容：

# This is a basic workflow to build robot code.

name: CI

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # This grabs the WPILib docker container
    container: wpilib/roborio-cross-ubuntu:2024-22.04

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v4

    # Declares the repository safe and not under dubious ownership.
    - name: Add repository to git safe directories
      run: git config --global --add safe.directory $GITHUB_WORKSPACE

    # Grant execute permission for gradlew
    - name: Grant execute permission for gradlew
      run: chmod +x gradlew

    # Runs a single command using the runners shell
    - name: Compile and run tests on robot code
      run: ./gradlew build

然后，通过单击屏幕右上角的 “开始提交” 按钮来保存更改。如果愿意，您可以修改默认提交消息。然后，单击绿色的 “提交新文件” 按钮。

现在，无论何时将提交推送到 main 或打开 pull 请求，GitHub 都会自动运行构建。要监视任何构建的状态，你可以单击屏幕顶部的 “操作” 选项卡。

Actions YAML 文件的细分

以下是 YAML 文件的细分。尽管不需要对每一行都有严格的了解，但是一定程度的了解将帮助您添加更多功能并调试可能出现的潜在问题。

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

此代码块指示操作将在何时运行。当前，该操作将在将提交推送到 main 或针对 main 打开拉取请求时运行。

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # This grabs the WPILib docker container
    container: wpilib/roborio-cross-ubuntu:2024-22.04

每个 Action 工作流程都由一个或多个作业组成，这些作业 (依次一个接一个) 运行或并行 (同时) 运行。在我们的工作流程中，只有一项 “构建” 工作。

我们指定希望工作在 Ubuntu 虚拟机上和虚拟化的 Docker 容器<https://www.docker.com/resources/what-container> _中运行，该容器包含 JDK ，C ++ 编译器和 roboRIO 工具链。

# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v4

# Declares the repository safe and not under dubious ownership.
- name: Add repository to git safe directories
  run: git config --global --add safe.directory $GITHUB_WORKSPACE

# Grant execute permission for gradlew
- name: Grant execute permission for gradlew
  run: chmod +x gradlew

# Runs a single command using the runners shell
- name: Compile and run tests on robot code
  run: ./gradlew build

Each job has certain steps that will be executed. This job has four steps. The first step involves checking out the repository to access the robot code. The second step is a workaround for a GitHub Actions issue. The third step involves giving the virtual machine permission to execute gradle tasks using ./gradlew. The final step runs ./gradlew build to compile robot code and run any unit tests.

将构建状态标志添加到 README.md 文件

将 CI 状态标记添加到存储库的 README 文件的顶部非常有帮助，以快速检查 main 上最新版本的状态。为此，请单击屏幕顶部的 “操作” 选项卡，然后选择屏幕左侧的 “ CI” 选项卡。然后，点击右上角的“创建状态标记”按钮，然后复制状态徽章 Markdown 代码。

最后，将复制的 Markdown 代码粘贴到 README 文件的顶部，提交并推送更改。现在，你应该在主存储库页面上看到 GitHub Actions 状态标记。