project-sync-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

project-sync-issues

GitHub Actions ワークフローファイルを生成し、Issue/PR の状態変更をプロジェクトの Status フィールドに自動同期します。手動での一括補正モードも提供します。

生成GitHub Actions工作流文件，将Issue/PR的状态变更自动同步至项目的Status字段。同时提供手动批量修正模式。

前提条件

対象の GitHub Project がリポジトリにリンクされていること
```
gh
```
CLI がインストールされ、認証済みであること（
```
project
```
スコープ付き）

目标GitHub Project已关联至仓库
已安装
```
gh
```
CLI并完成认证（需包含
```
project
```
权限范围）

フロー

流程

ユーザーに実行モードを確認する:

自動同期セットアップ — GitHub Actions ワークフローを生成（初回推奨）
手動一括補正 — 現在の不整合を一括修正（スポット実行用）

向用户确认执行模式：

自动同步设置 — 生成GitHub Actions工作流（首次使用推荐）
手动批量修正 — 批量修正当前状态不一致问题（用于临时执行）

モード A: 自動同期セットアップ

模式A: 自动同步设置

Step A-1: プロジェクト情報を取得する

Step A-1: 获取项目信息

bash

undefined

bash

undefined

オーナーを取得

获取仓库所有者

gh repo view --json owner -q '.owner.login'

プロジェクト番号を確認

确认项目编号

gh project list --owner <owner> --format json


ユーザーに対象プロジェクトの番号を確認する。

gh project list --owner <owner> --format json


向用户确认目标项目的编号。

Step A-2: 認証シークレットを案内する

Step A-2: 配置认证密钥

GitHub Actions から Projects API にアクセスするには

GITHUB_TOKEN

では不足するため、以下のいずれかが必要:

方法 1: Personal Access Token（個人/小規模向け）

GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
必要なスコープ:
```
project
```
（読み書き）+
```
issues
```
（読み書き）+
```
pull_requests
```
（読み書き）
リポジトリの Settings → Secrets and variables → Actions →
```
PROJECT_TOKEN
```
として登録

方法 2: GitHub App トークン（Organization 向け・推奨）

GitHub App を作成し、Organization に
```
Projects: Read and write
```
権限を付与
ワークフロー内で
```
actions/create-github-app-token
```
を使用してトークンを生成

GitHub Actions访问Projects API仅靠

GITHUB_TOKEN

权限不足，需使用以下任一方式：

方法1: Personal Access Token（适用于个人/小规模团队）

进入GitHub设置 → Developer settings → Personal access tokens → Fine-grained tokens
所需权限范围:
```
project
```
（读写）+
```
issues
```
（读写）+
```
pull_requests
```
（读写）
在仓库设置 → Secrets and variables → Actions中，以
```
PROJECT_TOKEN
```
为名添加该令牌

方法2: GitHub App令牌（适用于组织，推荐）

创建GitHub App，并为组织授予
```
Projects: Read and write
```
权限
在工作流中使用
```
actions/create-github-app-token
```
生成令牌

Step A-3: GitHub Actions ワークフローを生成する

Step A-3: 生成GitHub Actions工作流

Fandhe-AI/actions/project-sync

Composite Action を使用する。

.github/workflows/project-sync.yml

を生成する:

PAT を使用する場合:

yaml

name: Project Sync

on:
  issues:
    types: [opened, closed, reopened]
  pull_request:
    types: [opened, closed, ready_for_review, review_requested]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ secrets.PROJECT_TOKEN }}

GitHub App を使用する場合（推奨）:

yaml

name: Project Sync

on:
  issues:
    types: [opened, closed, reopened]
  pull_request:
    types: [opened, closed, ready_for_review, review_requested]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: '<owner>'

      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ steps.token.outputs.token }}

カスタム Status オプション名を使用する場合:

Status オプション名がデフォルト（Todo / In Progress / In Review / Done）と異なる場合は inputs で指定する:

yaml

      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ secrets.PROJECT_TOKEN }}
          status-todo: 'バックログ'
          status-in-progress: '作業中'
          status-in-review: 'レビュー中'
          status-done: '完了'

使用

Fandhe-AI/actions/project-sync

Composite Action，生成

.github/workflows/project-sync.yml

文件：

使用PAT的情况:

yaml

name: Project Sync

on:
  issues:
    types: [opened, closed, reopened]
  pull_request:
    types: [opened, closed, ready_for_review, review_requested]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ secrets.PROJECT_TOKEN }}

使用GitHub App的情况（推荐）:

yaml

name: Project Sync

on:
  issues:
    types: [opened, closed, reopened]
  pull_request:
    types: [opened, closed, ready_for_review, review_requested]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: '<owner>'

      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ steps.token.outputs.token }}

使用自定义Status选项名的情况:

若Status选项名与默认值（Todo / In Progress / In Review / Done）不同，可通过inputs参数指定：

yaml

      - name: Sync project status
        uses: Fandhe-AI/actions/project-sync@main
        with:
          project-number: '<number>'
          project-owner: '<owner>'
          token: ${{ secrets.PROJECT_TOKEN }}
          status-todo: 'バックログ'
          status-in-progress: '作業中'
          status-in-review: 'レビュー中'
          status-done: '完了'

Step A-4: ステータスマッピングを確認する

Step A-4: 确认状态映射规则

生成するワークフローのデフォルトマッピング:

イベント	アクション	Status
Issue	opened	Todo
Issue	closed	Done
Issue	reopened	Todo
PR	opened	In Progress
PR	ready_for_review	In Review
PR	review_requested	In Review
PR	closed (merged)	Done
PR	closed (not merged)	Todo

ユーザーの要望に応じてマッピングをカスタマイズする。

生成的工作流默认映射规则如下：

事件	操作	Status
Issue	opened	Todo
Issue	closed	Done
Issue	reopened	Todo
PR	opened	In Progress
PR	ready_for_review	In Review
PR	review_requested	In Review
PR	closed (merged)	Done
PR	closed (not merged)	Todo

可根据用户需求自定义映射规则。

Step A-5: ワークフローファイルを配置する

Step A-5: 部署工作流文件

bash

mkdir -p .github/workflows

bash

mkdir -p .github/workflows

ワークフローファイルを .github/workflows/project-sync.yml に書き出す

将工作流文件写入.github/workflows/project-sync.yml


ユーザーにコミット・プッシュを案内する。

---


引导用户提交并推送该文件。

---

モード B: 手動一括補正

模式B: 手动批量修正

プロジェクトと Issue/PR の現在の状態を比較し、不整合を一括修正する。自動同期セットアップ後の初回補正や、手動変更の反映に使用する。

对比项目与Issue/PR的当前状态，批量修正不一致问题。适用于自动同步设置后的首次修正，或手动变更后的状态同步。

Step B-1: プロジェクトアイテムを取得する

Step B-1: 获取项目项

bash

gh project item-list <number> \
  --owner <owner> \
  --format json \
  --limit 999

bash

gh project item-list <number> \
  --owner <owner> \
  --format json \
  --limit 999

Step B-2: Issue/PR の現在状態を確認する

Step B-2: 确认Issue/PR当前状态

Issue/PR タイプのアイテムに対して現在の状態を確認:

bash

gh issue view <issue-url> --json state,labels,assignees
gh pr view <pr-url> --json state,isDraft,reviewRequests,merged

针对Issue/PR类型的项目项，确认其当前状态：

bash

gh issue view <issue-url> --json state,labels,assignees
gh pr view <pr-url> --json state,isDraft,reviewRequests,merged

Step B-3: 状態の不一致を検出する

Step B-3: 检测状态不一致

以下の不一致パターンを検出:

Issue が closed だがプロジェクトの Status が Done でない → Done に更新
Issue が open だがプロジェクトの Status が Done → Todo に更新
PR がマージ済みだが Status が Done でない → Done に更新
PR にレビューリクエストがあるが Status が In Review でない → In Review に更新

检测以下不一致场景：

Issue已关闭但项目Status未设为Done → 更新为Done
Issue已重新打开但项目Status设为Done → 更新为Todo
PR已合并但Status未设为Done → 更新为Done
PR已发起评审请求但Status未设为In Review → 更新为In Review

Step B-4: リポジトリの未追加 Issue/PR を検出する

Step B-4: 检测仓库中未添加至项目的Issue/PR

bash

gh issue list --state open --json number,url,title --limit 999
gh pr list --state open --json number,url,title --limit 999

プロジェクトのアイテム URL と比較して未追加分を特定する。

bash

gh issue list --state open --json number,url,title --limit 999
gh pr list --state open --json number,url,title --limit 999

对比项目项的URL，识别未添加的Issue/PR。

Step B-5: ユーザーに同期内容を確認する

Step B-5: 向用户确认同步内容

検出結果を表示:

undefined

展示检测结果：

undefined

同期内容

同步内容

ステータス更新（N 件）

状态更新（N项）

#42: ソーシャルログイン — Status: In Progress → Done（Issue closed）
#45: バグ修正 — Status: Done → Todo（Issue reopened）
#50: リファクタリング PR — Status: In Progress → In Review（レビュー依頼済み）

#42: 社交登录 — Status: In Progress → Done（Issue已关闭）
#45: Bug修复 — Status: Done → Todo（Issue已重新打开）
#50: 重构PR — Status: In Progress → In Review（已发起评审请求）

新規追加（M 件）

新增项目项（M项）

#55: 新機能リクエスト (Issue)
#56: ドキュメント更新 PR

実行しますか？

undefined

#55: 新功能请求 (Issue)
#56: 文档更新PR

是否执行同步？

undefined

Step B-6: 同期を実行する

Step B-6: 执行同步

bash

undefined

bash

undefined

フィールドメタデータを取得

获取字段元数据

gh project field-list <number> --owner <owner> --format json

ステータス更新

更新状态

gh project item-edit
--id <item-id>
--field-id <status-field-id>
--project-id <project-id>
--single-select-option-id <option-id>

新規追加

新增项目项

gh project item-add <number>
--owner <owner>
--url <issue-or-pr-url>
--format json

undefined

gh project item-add <number>
--owner <owner>
--url <issue-or-pr-url>
--format json

undefined

Step B-7: 同期結果を報告する

Step B-7: 同步结果报告

操作	件数
ステータス更新	N 件
新規追加	M 件
変更なし	K 件

操作	数量
状态更新	N项
新增项目项	M项
无变更	K项

注意事項

注意事项

認証: GitHub Actions から Projects API へのアクセスには
```
GITHUB_TOKEN
```
では不足。PAT または GitHub App トークンが必要
PAT 有効期限: fine-grained PAT は最大1年。定期ローテーション推奨
ビルトインワークフローとの併用:
```
project-init
```
でビルトインワークフロー（closed→Done, merged→Done）を有効化済みの場合、Actions ワークフローと二重に発火するが、同じ値への更新なので実害はない
PR ライフサイクル: ビルトインワークフローは closed/merged のみ対応。opened→In Progress, review_requested→In Review は Actions でのみ自動化可能
プライベートリポジトリ: org の Settings → Actions → General でプライベートリポジトリからの Action 共有を許可する必要あり
手動補正モードは同期前に必ずユーザーの確認を得る
DraftIssue タイプのアイテムは同期対象外（実 Issue が存在しないため）
sandbox 環境での
GIT_SSL_NO_VERIFY=1
併用：詳細は後述の「sandbox 環境での実行」節を参照

认证: GitHub Actions访问Projects API仅靠
```
GITHUB_TOKEN
```
权限不足，需使用PAT或GitHub App令牌
PAT有效期: 细粒度PAT最长有效期为1年，建议定期轮换
与内置工作流共存: 若已通过
```
project-init
```
启用内置工作流（closed→Done, merged→Done），会与本Actions工作流重复触发，但因是更新为相同值，无实际影响
PR生命周期: 内置工作流仅支持closed/merged状态，opened→In Progress、review_requested→In Review仅能通过本Actions实现自动化
私有仓库: 需在组织设置 → Actions → General中允许私有仓库共享Action
手动修正模式执行前必须获得用户确认
DraftIssue类型的项目项不在同步范围内（因无对应实际Issue）
sandbox环境下需配合
GIT_SSL_NO_VERIFY=1
：详情请参考后文「sandbox环境下的执行」章节

sandbox 環境での実行

sandbox环境下的执行

sandbox で本スキルを実行する場合、ネットワーク越しの GitHub 操作には

GIT_SSL_NO_VERIFY=1

の併用を検討してください。本スキルの主なリモート操作は

git push

gh project item-edit

gh issue list

で、「リモート書き込み」判定は要です。コマンド分類の詳細と TLS 検証無効化の注意事項は

docs/sandbox-tls.md

を参照してください。

在sandbox环境中执行本技能时，通过网络操作GitHub需考虑配合使用

GIT_SSL_NO_VERIFY=1

。本技能的主要远程操作包括

git push

gh project item-edit

gh issue list

，均属于需要远程写入的操作。命令分类详情及TLS验证禁用注意事项请参考

docs/sandbox-tls.md

。