Go 的 GitHub Actions

GitHub Actions 为开源仓库提供免费的 CI/CD 服务。本文档包含了如何让它在 Go 中良好运行的相关信息。您可以在这里查看它们的实际运行情况：

$ cat .github/workflows/test.yml
on: [push, pull_request]
name: Test
jobs:
  test:
    strategy:
      matrix:
        go-version: [1.21.x, 1.22.x]
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
    - uses: actions/setup-go@v5
      with:
        go-version: ${{ matrix.go-version }}
    - uses: actions/checkout@v4
    - run: go test ./...

概述

每个工作流文件包含多个作业，这些作业在指定事件触发时并发运行。您可以为工作流添加状态徽章。

每个job在配置的matrix上运行。例如，我们可以在三个操作系统上测试两个主要的 Go 版本。

每个作业包含多个steps，如安装 Go 或检出仓库代码。

注意，name字段是可选的。

常见问题

如何设置环境变量？

可以通过env为整个工作流、一个作业或每个步骤设置环境变量：

env:
  GOPROXY: "https://proxy.company.com"
jobs:
  [...]

如何在运行时设置环境变量？

您可以使用环境文件来设置环境变量或向$PATH添加元素。例如：

steps:
- name: Set env vars
  run: |
      echo "CGO_ENABLED=0" >> $GITHUB_ENV
      echo "${HOME}/goroot/bin" >> $GITHUB_PATH

注意，这些设置在作业的后续步骤中生效。

如何在构建之间设置缓存？

从 v4 开始，actions/setup-go 会自动缓存 GOCACHE 和 GOMODCACHE，使用 go.sum 作为缓存键。您可以通过 cache: false 关闭它，然后也可以使用自定义缓存，例如只保留 GOMODCACHE：

- uses: actions/cache@v3
  with:
    path: ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-go-

更多详情请参阅此指南。

如何有条件地运行步骤？

您可以使用 if 条件语句，使用他们的自定义表达式语言：

- if: github.event_name == 'push' && matrix.os == 'ubuntu-latest'
  run: go run ./endtoend

如何设置自定义构建矩阵？

你可以包括额外的矩阵任务，也可以排除特定的矩阵任务。

如何运行多行脚本？

- name: 一系列命令
  run: |
    go test ./...
    go test -race ./...

我应该使用两个工作流，还是在一个工作流中使用两个任务？

最大的区别在于用户界面；工作流结果是分开显示的。如果想要自定义工作流触发器，或通过needs设置依赖关系，将任务组合在工作流中也很有用。

如何设置一个秘密环境变量？

按照这些步骤在仓库设置中设置秘密。添加像FOO_SECRET这样的秘密后，在步骤中如下使用：

- run: some-command
  env:
    FOO_SECRET: ${{ secrets.FOO_SECRET }}

如何安装私有模块？

可以在不使用自己的代理的情况下从私有GitHub仓库安装模块。你需要将个人访问令牌添加为秘密环境变量，并配置GOPRIVATE。你也可以直接使用GitHub在工作流中提供的令牌。在URL中你可以定义任何内容作为用户名，GitHub不会考虑这个。

- name: 为私有模块配置git
  env:
    TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
  run: git config --global url."https://user:${TOKEN}@github.com".insteadOf "https://github.com"

env:
  GOPRIVATE: "*.company.com"
jobs:
  [...]

如何安装Linux软件包？

使用sudo apt，确保只在Linux上运行该步骤：

- if: matrix.os == 'ubuntu-latest'
  run: sudo apt update && sudo apt install -y --no-install-recommends mypackage

如何设置`GOPATH`构建？

声明GOPATH并在其中克隆：

jobs:
  test-gopath:
    env:
      GOPATH: ${{ github.workspace }}
      GO111MODULE: off
    defaults:
      run:
        working-directory: ${{ env.GOPATH }}/src/github.com/${{ github.repository }}
    steps:
    - uses: actions/checkout@v3
      with:
        path: ${{ env.GOPATH }}/src/github.com/${{ github.repository }}