gh-token

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a fine-grained GitHub personal access token scoped to exactly what the given task needs — no more.

Note: GitHub does not expose an API for creating fine-grained PATs. Token creation requires the web UI. Your job is to determine the minimal permissions, provide URL to go, and give the user exact settings to copy.

创建权限完全匹配给定任务需求的GitHub细粒度个人访问令牌，绝不授予多余权限。

注意： GitHub没有开放创建细粒度PAT的API，令牌创建需要通过网页UI操作。你的职责是确定最小权限集、提供访问URL，并给出用户可直接复制的精确配置项。

How to run

如何运行

The user invokes this as

/gh-token <task>

where

<task>

describes what the token will be used for. Examples:

/gh-token ecosystem-ci for quarkiverse/quarkus-solr

/gh-token read-only clone of my org repos

/gh-token publish maven packages to quarkiverse

/gh-token trigger workflows in quarkiverse/quarkus-solr

If no task is given, ask the user what the token is for before proceeding.

用户通过

/gh-token <task>

指令调用该功能，其中

<task>

描述令牌的用途，示例如下：

/gh-token ecosystem-ci for quarkiverse/quarkus-solr

/gh-token read-only clone of my org repos

/gh-token publish maven packages to quarkiverse

/gh-token trigger workflows in quarkiverse/quarkus-solr

如果未指定任务，请先询问用户令牌的用途再继续处理。

Your process

处理流程

1. Identify the task and map it to minimal permissions

1. 识别任务并映射到最小权限

Match the described task to one of the known patterns below, or reason from first principles if it's novel. Always start from zero permissions and add only what's required.

Known task patterns and their minimal permission sets:

Task	Resource	Permission
Read-only checkout / clone	Contents	Read
Push commits / create releases	Contents	Write
Trigger `workflow_dispatch`	Actions	Write
Cancel / re-run workflows	Actions	Write
Read workflow run logs	Actions	Read
Publish to GitHub Packages / GHCR	Packages	Write
Read packages	Packages	Read
Dependabot alerts	Vulnerability alerts	Read
Create/close issues	Issues	Write
Comment on PRs	Pull requests	Write
Merge PRs	Pull requests	Write
Read org members	Members	Read
Manage webhooks	Webhooks	Write
Read org audit log	Administration	Read (org-level)
Read GitHub Projects v2	Projects	Read (org-level)
Update GitHub Projects v2 field values	Projects	Read and write (org-level)
Read issues / issue labels	Issues	Read
Add/change issue labels	Issues	Read and write

Projects v2 note: The Projects permission is an Organization permission, not a repository permission. It must be set under "Organization permissions → Projects", not under repository permissions. Repository access still needs to be set (to the relevant repos) for reading issue data alongside project data.

Default: if unsure, use Read. Never use Write unless the task requires mutating state.

将用户描述的任务匹配到下方已知模式，若为新场景则从基础原则推导权限。始终从零权限开始，仅添加任务必需的权限。

已知任务模式及对应的最小权限集：

任务	资源	权限
只读拉取/克隆	Contents	Read
推送提交/创建版本	Contents	Write
触发 `workflow_dispatch`	Actions	Write
取消/重跑工作流	Actions	Write
读取工作流运行日志	Actions	Read
发布到GitHub Packages / GHCR	Packages	Write
读取包内容	Packages	Read
查看Dependabot告警	Vulnerability alerts	Read
创建/关闭Issue	Issues	Write
PR评论	Pull requests	Write
合并PR	Pull requests	Write
读取组织成员列表	Members	Read
管理Webhook	Webhooks	Write
读取组织审计日志	Administration	Read (组织级)
读取GitHub Projects v2	Projects	Read (组织级)
更新GitHub Projects v2字段值	Projects	Read and write (组织级)
读取Issue/Issue标签	Issues	Read
添加/修改Issue标签	Issues	Read and write

Projects v2注意事项： Projects权限属于组织级权限，而非仓库级权限，必须在“组织权限 → Projects”下设置，而非仓库权限板块。若需要同时读取项目数据和Issue数据，仍需设置对应仓库的访问权限。

默认规则：若不确定权限级别，使用Read权限。除非任务需要修改状态，否则绝不授予Write权限。

2. Determine scope (repo vs org)

2. 确定适用范围（仓库vs组织）

Prefer single-repo scope whenever the task is repo-specific.
Use org-wide only when the task genuinely spans multiple repos (e.g. a bot that comments across all org repos).
Ask the user if scope is ambiguous.

若任务针对特定仓库，优先使用单仓库范围。
仅当任务确实需要覆盖多个仓库时（例如需要在组织所有仓库下评论的机器人），才使用全组织范围。
若范围不明确，询问用户确认。

3. Determine expiration

3. 确定过期时间

Pick the shortest sensible window for the task:

Use case	Default expiry	Rationale
One-off / local dev task	7 days	Throw away after use
Short-lived CI experiment	30 days	Covers a decent dev cycle
Stable CI secret (e.g. ECOSYSTEM_CI_TOKEN)	90 days	Forces regular rotation

Never suggest or accept more than 90 days. If the user asks for longer, push back: token compromise windows scale directly with expiry. Shorter is always safer —

gh secret set

makes rotation a one-liner so there's no practical reason to go long.

为任务选择最短的合理有效期：

使用场景	默认有效期	设计逻辑
一次性/本地开发任务	7天	使用后即可废弃
短期CI实验	30天	覆盖完整的开发周期
稳定CI密钥（例如ECOSYSTEM_CI_TOKEN）	90天	强制定期轮换

绝不建议或接受超过90天的有效期。如果用户要求更长有效期，请说明风险：令牌泄露的影响范围与有效期直接相关，越短越安全——

gh secret set

命令仅需一行即可完成密钥轮换，没有实际理由使用更长有效期。

4. Generate a prefill URL and show exact settings

4. 生成预填URL并展示精确配置

Construct a GitHub URL with the token name pre-filled:

https://github.com/settings/personal-access-tokens/new?name=<token-name>

Then display a clear settings block the user can copy from — GitHub's form does not support prefilling permissions or repo scope via URL, so those must be set manually:

Click to open:

https://github.com/settings/personal-access-tokens/new?name=<token-name>

Fill in these settings:

Field	Value
Token name	`<token-name>` (pre-filled)
Expiration	`<N> days`
Resource owner	`<owner>`
Repository access	Only selected → `<owner/repo>`
Permissions
<resource>	Read / Read and write

(All other permissions stay "No access")

The token name should be descriptive and kebab-case, e.g.

ecosystem-ci-quarkiverse-quarkus-solr

issues-comment-maxandersen-skills

构造预填了令牌名称的GitHub URL：

https://github.com/settings/personal-access-tokens/new?name=<token-name>

然后展示清晰的配置块供用户复制——GitHub表单不支持通过URL预填权限或仓库范围，因此这些配置需要手动设置：

点击跳转：

https://github.com/settings/personal-access-tokens/new?name=<token-name>

填写以下配置：

配置项	取值
令牌名称	`<token-name>` （已预填）
有效期	`<N> 天`
资源所有者	`<owner>`
仓库访问权限	仅选中指定仓库 → `<owner/repo>`
权限
<resource>	Read / Read and write

（所有其他权限保持“无访问权限”即可）

令牌名称应采用描述性的短横线分隔命名，例如

ecosystem-ci-quarkiverse-quarkus-solr

或

issues-comment-maxandersen-skills

。

5. After the user has the token — show how to verify and store it

5. 用户获取令牌后——展示验证和存储方式

To verify what permissions were actually granted, direct the user to:

https://github.com/settings/personal-access-tokens

Click the token name to see its exact permission set and expiry. There is no reliable CLI command to inspect fine-grained PAT permissions — the introspection endpoints require a fine-grained token themselves, and

X-Accepted-Github-Permissions

response headers only report the minimum required for the specific endpoint called, not the full token permission set.

Then show how to store it:

bash

undefined

若要验证实际授予的权限，引导用户访问：

https://github.com/settings/personal-access-tokens

点击令牌名称即可查看完整的权限集和有效期。目前没有可靠的CLI命令可以查看细粒度PAT的权限——自省接口本身就需要细粒度令牌才能访问，且

X-Accepted-Github-Permissions

响应头仅会返回当前调用接口所需的最小权限，而非令牌的完整权限集。

然后展示存储方式：

bash

undefined

Set as a repo secret

gh secret set <SECRET_NAME> --repo <owner/repo> --body "<token>"

Set as an org secret (available to specific repos)

gh secret set <SECRET_NAME> --org <org> --repos "<repo1>,<repo2>" --body "<token>"


Remind the user to copy the token immediately — GitHub only shows it once. Warn them **never to paste the token value into a conversation or chat** — treat any exposed token as compromised and revoke it immediately via:

```bash

gh secret set <SECRET_NAME> --org <org> --repos "<repo1>,<repo2>" --body "<token>"


提醒用户立即复制令牌——GitHub仅会展示一次。警告用户**绝对不要将令牌值粘贴到对话或聊天中**——一旦令牌泄露，请立即视为已被攻陷，通过以下命令吊销：

```bash

Find the token ID

gh api /user/personal-access-tokens | jq '.[] | select(.name=="<token-name>") | .id'

Revoke it

gh api --method DELETE /user/personal-access-tokens/<id>

undefined

gh api --method DELETE /user/personal-access-tokens/<id>

undefined

6. Warn on anti-patterns

6. 反模式警告

Flag these if the user's request would trigger them:

Classic PAT instead of fine-grained: If the user mentions creating a classic PAT (
```
github.com/settings/tokens/new
```
without
```
/fine-grained
```
), warn them that classic PATs cannot be scoped to a single repo and push them to use fine-grained instead. Fine-grained tokens are strictly safer.
Requesting
```
write
```
on
```
contents
```
+
```
actions
```
+
```
secrets
```
together (near-full repo access — suggest splitting into separate tokens)
Token expiry > 90 days
Org-wide scope when a single repo would suffice
Storing the token in a file or env var in plaintext (suggest
```
gh secret set
```
or a secrets manager)

如果用户的请求触发以下场景，请予以提醒：

使用经典PAT而非细粒度PAT：如果用户提到要创建经典PAT（URL为
```
github.com/settings/tokens/new
```
，不带
```
/fine-grained
```
路径），请提醒用户经典PAT无法限定为单仓库权限，建议优先使用细粒度PAT，细粒度令牌的安全性更高。
同时申请
```
contents
```
、
```
actions
```
、
```
secrets
```
的
```
write
```
权限（接近完整的仓库控制权限——建议拆分为多个独立令牌）
令牌有效期超过90天
本可使用单仓库范围却使用全组织范围
将令牌明文存储在文件或环境变量中（建议使用
```
gh secret set
```
或密钥管理器存储）

7. Suggest the matching

permissions:

block for the workflow

7. 为工作流推荐匹配的

permissions:

配置块

If the task is GitHub Actions CI-related, also output the minimal

permissions:

block to add to the workflow YAML so the auto-issued

GITHUB_TOKEN

is also locked down:

yaml

permissions:
  contents: read        # example — adjust to task

Remind the user that

permissions:

in the workflow overrides the org default, so this works regardless of org settings.

如果任务和GitHub Actions CI相关，还需要输出最小

permissions:

配置块，添加到工作流YAML中，确保自动生成的

GITHUB_TOKEN

也遵循最小权限原则：

yaml

permissions:
  contents: read        # example — adjust to task

提醒用户工作流中的

permissions:

配置会覆盖组织默认设置，因此无论组织配置如何，该规则都生效。

gh-token

Original

Translation

How to run

如何运行

Your process

处理流程

1. Identify the task and map it to minimal permissions

1. 识别任务并映射到最小权限

2. Determine scope (repo vs org)

2. 确定适用范围（仓库vs组织）

3. Determine expiration

3. 确定过期时间

4. Generate a prefill URL and show exact settings

4. 生成预填URL并展示精确配置

5. After the user has the token — show how to verify and store it

5. 用户获取令牌后——展示验证和存储方式

Set as a repo secret

Set as a repo secret

Set as an org secret (available to specific repos)

Set as an org secret (available to specific repos)

Find the token ID

Find the token ID

Revoke it

Revoke it

6. Warn on anti-patterns

6. 反模式警告

7. Suggest the matching
`permissions:`
block for the workflow

7. 为工作流推荐匹配的
`permissions:`
配置块

gh-token

Original

Translation

How to run

如何运行

Your process

处理流程

1. Identify the task and map it to minimal permissions

1. 识别任务并映射到最小权限

2. Determine scope (repo vs org)

2. 确定适用范围（仓库vs组织）

3. Determine expiration

3. 确定过期时间

4. Generate a prefill URL and show exact settings

4. 生成预填URL并展示精确配置

5. After the user has the token — show how to verify and store it

5. 用户获取令牌后——展示验证和存储方式

Set as a repo secret

Set as a repo secret

Set as an org secret (available to specific repos)

Set as an org secret (available to specific repos)

Find the token ID

Find the token ID

Revoke it

Revoke it

6. Warn on anti-patterns

6. 反模式警告

7. Suggest the matching permissions: block for the workflow

7. 为工作流推荐匹配的permissions:配置块

7. Suggest the matching
`permissions:`
block for the workflow

7. 为工作流推荐匹配的
`permissions:`
配置块