此前关注到了 trickest/cve 这个仓库，十分眼馋整理归类的poc，因此想自动化拉取到Github仓库然后搞成静态页面（虽然因为md文档数量太多，因此构建失败）。在寻找解决方案的时候，接触到了Github Action，这才有了这边文章。

nektos/act介绍

nektos/act 是一个开源工具，它模拟 GitHub Actions 的 CI/CD 环境，允许你在本地运行 GitHub Actions 工作流。它可以节省大量的时间，因为你可以在本地验证工作流逻辑，而不必每次都推送代码到 GitHub 仓库并等待远程执行。

配置 GitHub Actions 示例工作流

以下是一个示例 GitHub Actions 工作流，笔者将用这个工作流来演示如何通过 nektos/act 本地调试 GitHub Actions。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
name: Trickest CVE Monitor And Deploy

on:
  workflow_dispatch:

jobs:
  sync_with_upstream:
    name: Sync with Upstream
    runs-on: ubuntu-latest
    if: ${{ github.event.repository.fork }}

    steps:
      - name: Checkout target repo
        uses: actions/checkout@v4

      - name: Sync Upstream
        uses: aormsby/Fork-Sync-With-Upstream-action@v3.4
        with:
          target_repo_token: ${{ secrets.GITHUB_TOKEN }}
          upstream_sync_repo: trickest/cve
          upstream_sync_branch: main
          target_sync_branch: main
          test_mode: false

      - name: Check for Failure
        if: failure()
        run: |
          echo "[Error] Due to a change in the workflow file of the upstream repository, GitHub has automatically suspended the scheduled automatic update. You need to manually sync your fork."
          exit 1

      - name: Generate Mkdocs Yaml File
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      
      - run: |
          python -m pip install --upgrade pip
          pip install pyyaml
          python mkdocs_yaml_gen.py

      - name: Conver Markdown to Site
        run: |
          mkdir docs
          rsync -av --include='[0-9][0-9][0-9][0-9]/' --include='[0-9][0-9][0-9][0-9]/*.md' --exclude='*' --exclude="docs/" --exclude="summary_html/"  . docs/
          echo '<!DOCTYPE html><html><head><meta http-equiv="refresh" content="0; url=/docs/README.html" /></head></html>' > index.html

      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG_FILE: ./mkdocs.yml

使用 nektos/act 本地运行 GitHub Actions 的优化版教程

配置 GitHub Secrets

在 GitHub Actions 中，敏感信息通常通过 secrets 管理。nektos/act 提供了通过 .env 文件或命令行传递 secrets 的便捷方式。
创建 .env 文件：在项目根目录新建一个 .env 文件，用于存储敏感信息（如 GitHub token）。确保 .env 文件不会被提交到版本控制系统（建议在 .gitignore 中添加 .env）。

1
GITHUB_TOKEN=your_github_token

通过命令行设置 secrets：也可以直接通过 -s 参数在运行时传递 secrets，无需创建 .env 文件。

1
act -s GITHUB_TOKEN=your_github_token

本地运行工作流

笔者建议先确保项目中已有 GitHub Actions 工作流文件（通常位于 .github/workflows 目录下）。然后使用以下命令本地运行：

1
act workflow_dispatch

workflow_dispatch 事件模拟了 GitHub 上手动触发工作流的功能，相当于在 GitHub 界面点击“Run workflow”按钮。

实时查看日志输出

运行后，act 会打印每个步骤的详细日志，包括成功或失败信息。如果某个步骤出错，日志中会显示详细的错误提示，有助于快速定位问题。

调试技巧

在调试 GitHub Actions 工作流时，笔者建议通过增加调试步骤获取更多环境信息。例如：

1
2
3
4
5
6
7
- name: Debug Environment
  run: |
    echo "Current working directory: $(pwd)"
    echo "Files in directory:"
    ls -la
    echo "Environment variables:"
    env

本地运行时，act 将输出上述信息，便于分析工作流行为是否符合预期。

常见问题及解决方法

  1. 镜像问题： 默认情况下，act 会下载一个通用的 Docker 镜像。如果需要自定义镜像（如支持特殊环境的镜像），可以使用 -P 参数指定：
    1
    act -P ubuntu-latest=custom-image:tag
  2. 网络依赖问题： 如果工作流步骤依赖外部服务（如 API 请求），请确保本地网络环境与 GitHub 环境一致，或者在本地搭建模拟服务。
  3. 权限不足： 如果需要额外权限（如访问私有仓库），请确保使用的 GITHUB_TOKEN 拥有足够的权限，并正确配置工作流。