Repository Dispatch 使用教程

1. 项目介绍

Repository Dispatch 是一个 GitHub Action，用于创建仓库调度事件。通过这个 Action，你可以触发特定的工作流或事件，从而实现自动化流程。这个工具特别适用于 CI/CD 流程中，当你需要在不同的仓库之间进行事件调度时。

2. 项目快速启动

2.1 安装与配置

首先，你需要在 GitHub 仓库中创建一个工作流文件（例如 .github/workflows/dispatch.yml）。然后，将以下内容复制到该文件中：

name: Repository Dispatch

on:
  workflow_dispatch:

jobs:
  dispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.PAT }}
          repository: username/my-repo
          event-type: my-event
          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'

2.2 创建 Personal Access Token (PAT)

为了能够调度远程仓库，你需要创建一个 Personal Access Token (PAT)，并将其存储为仓库的秘密（Secret）。具体步骤如下：

1. 在 GitHub 上，进入你的账户设置，选择“Developer settings”。
2. 点击“Personal access tokens”，然后选择“Generate new token”。
3. 为你的 Token 选择适当的权限（例如 repo 权限），然后生成 Token。
4. 将生成的 Token 存储为仓库的秘密，例如 PAT。

2.3 触发调度事件

你可以通过以下方式触发调度事件：

• 手动触发：在 GitHub 仓库的 Actions 页面中，选择你的工作流并手动运行。
• 通过 API 触发：使用 GitHub API 发送 POST 请求到 /repos/{owner}/{repo}/dispatches 端点。

3. 应用案例和最佳实践

3.1 跨仓库事件调度

假设你有两个仓库：repo-A 和 repo-B。你希望在 repo-A 中完成某个任务后，自动触发 repo-B 中的某个工作流。你可以使用 Repository Dispatch 来实现这一需求。

在 repo-A 的工作流中添加以下步骤：

- name: Dispatch to repo-B
  uses: peter-evans/repository-dispatch@v3
  with:
    token: ${{ secrets.PAT }}
    repository: org-name/repo-B
    event-type: trigger-workflow

在 repo-B 的工作流中，监听 trigger-workflow 事件：

on:
  repository_dispatch:
    types: [trigger-workflow]

3.2 多仓库调度

如果你有多个仓库需要调度，可以使用矩阵策略（Matrix Strategy）来简化配置。例如，调度三个仓库：

jobs:
  dispatch:
    strategy:
      matrix:
        repo: ['org-name/repo1', 'org-name/repo2', 'org-name/repo3']
    runs-on: ubuntu-latest
    steps:
      - name: Repository Dispatch
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.PAT }}
          repository: ${{ matrix.repo }}
          event-type: my-event

4. 典型生态项目

4.1 GitHub Actions

Repository Dispatch 是 GitHub Actions 生态系统中的一个重要组件。它与其他 GitHub Actions 结合使用，可以实现复杂的自动化流程。

4.2 CI/CD 工具

在 CI/CD 流程中，Repository Dispatch 可以用于触发不同阶段的任务，例如构建、测试和部署。通过与其他 CI/CD 工具集成，可以实现更高效的自动化工作流。

4.3 开源社区

许多开源项目使用 Repository Dispatch 来管理跨仓库的依赖和事件调度。例如，一些大型开源项目可能会在核心仓库中完成某个任务后，自动触发其他相关仓库的工作流。

通过以上步骤和案例，你可以快速上手并应用 Repository Dispatch 来实现复杂的自动化任务。