schubergphilis/mcvs-golang-action
GitHub: schubergphilis/mcvs-golang-action
一个集成安全扫描、代码检查、测试与发布功能的 Golang 项目 CI/CD 标准化工具集，通过 GitHub Action 和 Taskfile 实现本地与云端一致的质量门禁。
Stars: 5 | Forks: 2
# MCVS-golang-action
任务关键型漏洞扫描器（Mission Critical Vulnerability Scanner，简称 MCVS）Golang Action 仓库是一套标准化工具集合，旨在确保包含 Go 代码的项目具备一定的质量水平。
## Github Action
本仓库中的 [GitHub Action](https://github.com/features/actions) 包含以下步骤：
- 安装项目 `go.mod` 中定义的 Golang 版本。
- 验证已下载的 Golang modules。
- 检查错误的导入顺序并提示解决方法。
- 代码安全扫描，并对特定 CVE 进行最长一个月的抑制。在某些情况下，特定的 CVE 可能会在几周内被解决，这允许开发人员以安全的方式继续工作，同时知道如果问题在几周内未解决，流水线将再次失败。
- Linting。
- 单元测试。
- 集成测试。
- 代码覆盖率。
总之，使用此 action 将确保 Golang 代码在部署到生产环境之前满足特定标准，因为如果出现问题，流水线将失败。
注意：有一个 [内部 action](.github/workflows/package-version-updater.yml) 会更新无法由 Dependabot 更新的包版本。
## 版本控制
此 action 遵循语义化版本控制。在工作流中使用此 action 时：
- **最新稳定版本**：在生产工作流中使用最新的 `v3.x.x` 标签（例如 `v3.4.2`）。
- **主版本跟踪**：使用 `@v3` 自动获取最新的 v3.x.x 更新。
- **Taskfile 引用**：在包含远程 Taskfile 时，请使用符合您需求的特定版本标签（例如 `v2.1.0`）。
- **破坏性变更**：主版本号升级（v3 → v4）可能会引入破坏性变更，并需要更新工作流。
请查看 [发布页面](https://github.com/schubergphilis/mcvs-golang-action/releases) 获取最新版本和变更日志。
## Taskfile
另一个工具是 [Task](https://taskfile.dev/) 的配置。本仓库提供了一个 `./build/task.yml`，其中包含标准任务，例如安装和运行 linter。
此 `./build/task.yml` 随后可被其他项目使用。这样的好处是您不需要从一个项目到另一个项目复制和粘贴 Makefile 片段。因此，每个使用此 `./build/task.yml` 的项目都能立即从此处进行的改进（例如新任务或任务改进）中受益。
如果您是 Task 的新手，可能需要查看以下资源：
- [安装说明](https://taskfile.dev/installation/)
- [配置自动补全](https://taskfile.dev/installation/#setup-completions) 的说明
- 与例如 Visual Studio Code、Sublime 和 IntelliJ 的 [集成](https://taskfile.dev/integrations/)。
### 配置
本项目中的 `./build/task.yml` 定义了许多变量。其中一些可以在将此 Taskfile 包含到您的项目中时被覆盖。请参阅下面的示例，其中覆盖了 `CODE_COVERAGE_STRICT` 变量，以了解如何执行此操作。
以下变量可以被覆盖：
| 变量 | 描述 |
| :-------------------------- | :------------------------------------------------------------------------------------------------------- |
| `CODE_COVERAGE_STRICT` | 启用或禁用将最小覆盖率设置为观察到的最大覆盖率的强制执行。 |
| `GOLANGCI_LINT_CONFIG_PATH` | 定义 golangci-lint 配置文件的路径。 |
## 用法
### 本地
创建一个包含以下内容的 `Taskfile.yml`：
```
---
version: 3
vars:
REMOTE_URL: https://raw.githubusercontent.com
REMOTE_URL_REF: v2.1.0
REMOTE_URL_REPO: schubergphilis/mcvs-golang-action
includes:
remote: >-
{{.REMOTE_URL}}/{{.REMOTE_URL_REPO}}/{{.REMOTE_URL_REF}}/build/task.yml
```
并运行：
```
TASK_X_REMOTE_TASKFILES=1 \
task remote:test
```
请注意，只要远程 Taskfiles 仍处于实验阶段，就需要 `TASK_X_REMOTE_TASKFILES` 变量。（有关更多信息，请参阅 [issue 1317](https://github.com/go-task/task/issues/1317)。）
您可以使用 `task --list-all` 获取所有可用任务的列表。
或者，如果您在 shell 中 [配置了自动补全](https://taskfile.dev/installation/#setup-completions)，您可以按 Tab 键获取可用任务的列表。
### 自动修复 Linting 问题
当 golangci-lint 报告可以自动修复的问题时，您可以使用 `fix-linting-issues` 任务：
```
TASK_X_REMOTE_TASKFILES=1 \
task remote:fix-linting-issues --yes
```
此任务使用两个工具自动修复常见的 linting 问题：
- **golines**：重新格式化 Go 代码以满足行长度要求（包装长行）。
- **wsl**：修复空格 linting 问题（根据样式规则添加/删除空行）。
运行此任务后，请检查更改并提交它们。请注意，某些 linting 问题可能仍需要手动修复。
如果您想覆盖我们 Taskfile 中的某个变量，您必须像这样调整 `includes` 部分：
```
---
includes:
remote:
taskfile: >-
{{.REMOTE_URL}}/{{.REMOTE_URL_REPO}}/{{.REMOTE_URL_REF}}/build/task.yml
vars:
CODE_COVERAGE_STRICT: "false"
```
注意：`GOLANGCI_LINT_RUN_TIMEOUT_MINUTES` 设置也是如此。
## Build Tags
Build tags（也称为构建约束）允许您根据条件在编译时包含或排除 Go 文件。此 action 支持以下常见的 build tag 模式：
- **`integration`**：用于需要外部服务或数据库的集成测试。
- **`component`**：用于测试多个单元协同工作的组件测试。
- **`e2e`**：用于测试整个应用程序流程的端到端测试。
- **`lambda.norpc`**：用于构建不支持 RPC 的 AWS Lambda 函数。
### 使用 Build Tags
当使用特定的 build tags 运行测试时：
```
# 运行集成测试
task remote:test-integration --yes
# 运行组件测试
task remote:test-component --yes
```
当使用特定的 build tags 进行代码 linting 时，您可能需要多次运行 linter 以覆盖所有代码路径：
```
- testing-type: "lint" # Lint main code
- testing-type: "lint", build-tags: "integration" # Lint integration test code
- testing-type: "lint", build-tags: "component" # Lint component test code
```
这确保具有不同 build tags 的测试文件中的代码得到正确的 linting。
### GitHub
#### 基本示例
对于需要标准测试和 linting 的简单项目，创建一个 `.github/workflows/golang.yml` 文件：
```
---
name: Golang
"on": pull_request
permissions:
contents: read
packages: read
jobs:
MCVS-golang-action:
strategy:
matrix:
args:
- testing-type: "unit"
- testing-type: "lint"
- testing-type: "coverage"
- testing-type: "security-golang-modules"
runs-on: ubuntu-24.04
env:
TASK_X_REMOTE_TASKFILES: 1
steps:
- uses: actions/checkout@v4.1.1
- uses: schubergphilis/mcvs-golang-action@v3
with:
testing-type: ${{ matrix.args.testing-type }}
token: ${{ secrets.GITHUB_TOKEN }}
```
此基本配置将在您的 Go 代码上运行单元测试、linting、代码覆盖率检查和安全扫描。
#### 高级示例
对于具有多种构建配置、集成测试或自定义要求的项目，创建一个包含以下内容的 `.github/workflows/golang.yml` 文件：
```
---
name: Golang
"on": pull_request
permissions:
contents: read
packages: read
jobs:
MCVS-golang-action:
strategy:
matrix:
args:
- release-architecture: "amd64",
release-dir: "./cmd/path-to-app",
release-type: "binary",
release-application-name: "some-app",
- release-architecture: "arm64",
release-dir: "./cmd/path-to-app",
release-type: "binary",
release-application-name: "some-lambda-func",
release-build-tags: "lambda.norpc",
- testing-type: "component"
- testing-type: "coverage"
- testing-type: "graphql-lint"
- testing-type: "integration"
- testing-type: "lint", build-tags: "component"
- testing-type: "lint", build-tags: "e2e"
- testing-type: "lint", build-tags: "integration"
- testing-type: "mcvs-texttidy"
- testing-type: "mocks-tidy"
- testing-type: "security-golang-modules"
- testing-type: "security-grype"
- testing-type: "security-trivy"
security-trivyignore: ""
- testing-type: "unit"
runs-on: ubuntu-24.04
env:
TASK_X_REMOTE_TASKFILES: 1
test-timeout: 10m0s
steps:
- uses: actions/checkout@v4.1.1
with:
fetch-depth: 0 # this is necessary for gta partial testing
- uses: schubergphilis/mcvs-golang-action@v0.9.0
with:
build-tags: ${{ matrix.args.build-tags }}
golang-unit-tests-exclusions: |-
\(cmd\/some-app\|internal\/app\/some-app\)
gta-base-branch: main
gta-partial-testing: true
release-architecture: ${{ matrix.args.release-architecture }}
release-dir: ${{ matrix.args.release-dir }}
release-type: ${{ matrix.args.release-type }}
security-trivyignore: ${{ matrix.args.security-trivyignore }}
task-install: yes
testing-type: ${{ matrix.args.testing-type }}
token: ${{ secrets.GITHUB_TOKEN }}
test-timeout: ${{ env.test-timeout }}
code-coverage-timeout: ${{ env.test-timeout }}
```
以及一个 [.golangci.yml](https://golangci-lint.run/usage/configuration/)。
| 选项 | 默认值 | 必需 | 描述 |
| :---------------------------------------------- | :------ | -------- | :--------------------------------------------------------------------------------------------------------------- |
| build-tags | x | | 运行测试和 linting 时使用的 build tags（例如 "integration", "component", "e2e"） |
| code-coverage-expected | x | | 标准测试的最低预期代码覆盖率百分比 |
| code-coverage-opa-expected | x | | OPA (Open Policy Agent) 测试的最低预期代码覆盖率百分比 |
| code-coverage-timeout | | | 代码覆盖率分析的超时持续时间（例如 "10m0s"） |
| github-token-for-downloading-private-go-modules | | | 具有从私有仓库下载 Go modules 权限的 GitHub token |
| golangci-timeout | x | | golangci-lint 执行的超时持续时间 |
| golang-unit-tests-exclusions | x | | 用于从单元测试中排除特定包的正则表达式模式（例如 `\(cmd\/app\|internal\/app\)`） |
| grype-version | | | 要使用的 Grype 漏洞扫描器的特定版本 |
| gta-base-branch | x | | 用于执行部分测试的对比分支，变更的 go packages 将与之比较 |
| gta-partial-testing | x | | 是否运行部分测试（true 或 false） |
| release-application-name | | | 要构建的应用程序二进制文件的名称（设置 release-type 时需要） |
| release-architecture | | | 二进制文件的目标架构（例如 "amd64", "arm64"） |
| release-build-tags | | | 构建发布二进制文件时使用的 build tags（例如 "lambda.norpc"） |
| release-dir | | | 包含要构建的二进制文件 main.go 文件的目录 |
| release-os | x | | 二进制文件的目标操作系统（例如 "linux", "darwin"） |
| release-type | | | 要构建的发布类型（例如 "binary"） |
| task-install | x | | 是否安装 Task runner（"yes" 或 "no"） |
| task-version | x | | 要安装的 Task runner 版本 |
| testing-type | | | 要运行的测试类型（例如 "unit", "integration", "lint", "coverage", "security-golang-modules"） |
| test-timeout | | | 测试执行的超时持续时间（例如 "10m0s"） |
| token | | | 用于身份验证的 GitHub token（通常为 ${{ secrets.GITHUB_TOKEN }}） |
| trivy-action-db | x | | Trivy 漏洞数据库配置 |
| trivy-action-java-db | x | | Trivy Java 漏洞数据库配置 |
| trivy-version | x | | aquasecurity/trivy-action 使用的 Trivy CLI 版本（例如 "v0.69.2"） |
注意：如果在默认值列中注册了 **x**，请参阅 [action.yml](action.yml) 获取相应的值。
### 发布
在某些情况下，您可能希望自动构建并发布可执行二进制文件。此 action 将构建二进制文件，然后将其用作发布资产。
创建一个包含以下内容的 `.github/workflows/golang-releases.yml` 文件：
```
---
name: golang-releases
"on": push
permissions:
contents: write
packages: read
jobs:
mcvs-golang-action:
strategy:
matrix:
args:
- release-application-name: mcvs-image-downloader
release-architecture: amd64
release-dir: cmd/mcvs-image-downloader
release-type: binary
- release-application-name: mcvs-image-downloader
release-architecture: arm64
release-dir: cmd/mcvs-image-downloader
release-os: darwin
release-type: binary
runs-on: ubuntu-24.04
env:
TASK_X_REMOTE_TASKFILES: 1
steps:
- uses: actions/checkout@v4.2.2
- uses: schubergphilis/mcvs-golang-action@v3.4.2
with:
release-application-name: ${{ matrix.args.release-application-name }}
release-architecture: ${{ matrix.args.release-architecture }}
release-build-tags: ${{ matrix.args.release-build-tags }}
release-dir: ${{ matrix.args.release-dir }}
release-os: ${{ matrix.args.release-os }}
release-type: ${{ matrix.args.release-type }}
token: ${{ secrets.GITHUB_TOKEN }}
```
### 集成
要执行集成测试，请确保代码位于带有 `_integration_test.go` 后缀的文件中，例如 `some_integration_test.go`。
此外，在文件中包含以下标头：
```
//go:build integration
```
添加此标头后，按照此示例所示发出命令 `task remote:test-integration --yes`。此 action 将运行单元测试和集成测试。如果执行 `task remote:test --yes`，则只会运行单元测试。
### 组件
有关步骤，请参阅集成段落，并将 `integration` 替换为 `component` 以运行它们。
### 从另一个私有仓库下载发布资产
您需要一个具有 `repo` 范围的个人访问令牌（PAT）才能从私有仓库下载发布版本。您可以简单地使用 gh 命令或 curl 来下载发布资产。请阅读 [GitHub 文档](https://docs.github.com/en/rest/releases/assets) 了解更多信息。
标签：Claude, CVE检测, DevSecOps, GitHub Action, Golang, Go语言, Linting, SAST, XML 请求, 上游代理, 代码覆盖率, 代码规范, 依赖管理, 单元测试, 安全专业人员, 安全开发, 安全编程, 开源框架, 持续集成, 日志审计, 盲注攻击, 程序破解, 软件供应链安全, 远程方法调用, 错误基检测, 集成测试, 静态代码分析