github-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Issues

Manage GitHub issues using the

@modelcontextprotocol/server-github

MCP server.

使用

@modelcontextprotocol/server-github

MCP server 管理 GitHub Issues。

Available Tools

可用工具

MCP Tools (read operations)

MCP 工具（读取操作）

Tool	Purpose
`mcp__github__issue_read`	Read issue details, sub-issues, comments, labels (methods: get, get_comments, get_sub_issues, get_labels)
`mcp__github__list_issues`	List and filter repository issues by state, labels, date
`mcp__github__search_issues`	Search issues across repos using GitHub search syntax
`mcp__github__projects_list`	List projects, project fields, project items, status updates
`mcp__github__projects_get`	Get details of a project, field, item, or status update
`mcp__github__projects_write`	Add/update/delete project items, create status updates

工具	用途
`mcp__github__issue_read`	读取 Issue 详情、子 Issue、评论和标签（方法：get、get_comments、get_sub_issues、get_labels）
`mcp__github__list_issues`	按状态、标签和日期列出并筛选仓库 Issue
`mcp__github__search_issues`	使用 GitHub 搜索语法跨仓库搜索 Issue
`mcp__github__projects_list`	列出项目、项目字段、项目项和状态更新
`mcp__github__projects_get`	获取项目、字段、项目项或状态更新的详情
`mcp__github__projects_write`	添加、更新或删除项目项，创建状态更新

MCP Tools (write operations)

MCP 工具（写入操作）

Tool	Purpose
`mcp__github__issue_write`	Create or update an issue (methods: create, update). Supports title, body, type, labels, assignees, milestone, and issue fields
`mcp__github__add_issue_comment`	Add a comment or a reaction to an issue
`mcp__github__sub_issue_write`	Add, remove, or reprioritize a sub-issue

工具	用途
`mcp__github__issue_write`	创建或更新 Issue（方法：create、update）。支持 title、body、type、labels、assignees、milestone 和 Issue 字段
`mcp__github__add_issue_comment`	向 Issue 添加评论或 reaction
`mcp__github__sub_issue_write`	添加、删除或重新调整子 Issue 的优先级

CLI / REST API (write operations)

CLI / REST API（写入操作）

gh api

performs the same writes and is the form used in the examples below. Reach for it when the MCP server is not connected, or when you need a REST field the MCP tools do not expose.

Operation	Command
Create issue	`gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...`
Update issue	`gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...`
Add comment	`gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...`
Close issue	`gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed`
Set issue type	Include `-f type=Bug` in the create call (REST API only, not supported by `gh issue create` CLI)

Note:

gh issue create

works for basic issue creation but does not support the

--type

flag. Use

gh api

when you need to set issue types.

gh api

可执行相同的写入操作，也是以下示例采用的形式。当 MCP server 未连接，或需要使用 MCP 工具未公开的 REST 字段时，应使用它。

操作	命令
创建 Issue	`gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...`
更新 Issue	`gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...`
添加评论	`gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...`
关闭 Issue	`gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed`
设置 Issue 类型	在创建调用中包含 `-f type=Bug` （仅支持 REST API， `gh issue create` CLI 不支持）

注意：

gh issue create

可用于基本 Issue 创建，但不支持

--type

参数。需要设置 Issue 类型时请使用

gh api

。

Workflow

工作流

Determine action: Create, update, or query?
Gather context: Get repo info, existing labels, milestones if needed
Structure content: Use appropriate template from references/templates.md
Execute: Use MCP tools for reads,
```
gh api
```
for writes
Confirm: Report the issue URL to user

确定操作：创建、更新还是查询？
收集上下文：获取仓库信息；如有需要，还要获取现有标签和里程碑
组织内容：使用 references/templates.md 中适合的模板
执行：读取操作使用 MCP 工具，写入操作使用
```
gh api
```
确认：向用户提供 Issue URL

Creating Issues

创建 Issue

Use

gh api

to create issues. This supports all parameters including issue types.

bash

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Issue title" \
  -f body="Issue body in markdown" \
  -f type="Bug" \
  --jq '{number, html_url}'

使用

gh api

创建 Issue。该方式支持所有参数，包括 Issue 类型。

bash

gh api repos/{owner}/{repo}/issues \\
  -X POST \\
  -f title="Issue title" \\
  -f body="Issue body in markdown" \\
  -f type="Bug" \\
  --jq '{number, html_url}'

Optional Parameters

可选参数

Add any of these flags to the

gh api

call:

-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
-f 'labels[]=bug'                # Labels (repeat for multiple)
-f 'assignees[]=username'        # Assignees (repeat for multiple)
-f milestone=1                   # Milestone number

Quote the whole
name[]=value
pair.

[]

is a glob pattern in zsh, the default shell on macOS, so an unquoted

-f labels[]=bug

never reaches

gh

zsh: no matches found: labels[]=bug

Issue types are organization-level metadata. To discover available types, use:

bash

gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'

Prefer issue types over labels for categorization. When issue types are available (e.g., Bug, Feature, Task), use the

type

parameter instead of applying equivalent labels like

bug

enhancement

. Issue types are the canonical way to categorize issues on GitHub. Only fall back to labels when the org has no issue types configured.

可以在

gh api

调用中添加以下任意参数：

-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
-f 'labels[]=bug'                # Labels (repeat for multiple)
-f 'assignees[]=username'        # Assignees (repeat for multiple)
-f milestone=1                   # Milestone number

请为整个
name[]=value
参数加引号。

[]

在 macOS 默认 shell zsh 中是 glob 模式，因此未加引号的

-f labels[]=bug

永远不会传递给

gh

：

zsh: no matches found: labels[]=bug

Issue 类型是组织级元数据。要发现可用类型，请使用：

bash

undefined

在分类时，优先使用 Issue 类型而不是标签。如果组织提供了 Issue 类型（例如 Bug、Feature、Task），请使用

type

参数，而不是添加

bug

或

enhancement

等等效标签。Issue 类型是在 GitHub 上对 Issue 进行分类的标准方式。仅当组织未配置 Issue 类型时，才回退使用标签。

Title Guidelines

标题规范

Be specific and actionable
Keep under 72 characters
When issue types are set, don't add redundant prefixes like
```
[Bug]
```

Examples:

```
Login fails with SSO enabled
```
(with type=Bug)
```
Add dark mode support
```
(with type=Feature)
```
Add unit tests for auth module
```
(with type=Task)

具体且易于执行
保持在 72 个字符以内
设置 Issue 类型后，不要添加
```
[Bug]
```
等冗余前缀

示例：

```
Login fails with SSO enabled
```
（type=Bug）
```
Add dark mode support
```
（type=Feature）
```
Add unit tests for auth module
```
（type=Task）

Body Structure

正文结构

Always use the templates in references/templates.md. Choose based on issue type:

User Request	Template
Bug, error, broken, not working	Bug Report
Feature, enhancement, add, new	Feature Request
Task, chore, refactor, update	Task

始终使用 references/templates.md 中的模板。根据 Issue 类型选择：

用户请求	模板
Bug、错误、故障、无法正常工作	Bug Report
功能、增强、添加、新功能	Feature Request
任务、杂务、重构、更新	Task

Updating Issues

更新 Issue

Use

gh api

with PATCH:

bash

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="Updated title" \
  --jq '{number, html_url}'

Only include fields you want to change. Available fields:

title

body

state

(open/closed),

labels

assignees

milestone

使用

gh api

和 PATCH：

bash

gh api repos/{owner}/{repo}/issues/{number} \\
  -X PATCH \\
  -f state=closed \\
  -f title="Updated title" \\
  --jq '{number, html_url}'

仅包含需要更改的字段。可用字段包括：

title

、

body

、

state

（open/closed）、

labels

、

assignees

、

milestone

。

Examples

示例

Example 1: Bug Report

示例 1：Bug Report

User: "Create a bug issue - the login page crashes when using SSO"

Action:

bash

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Login page crashes when using SSO" \
  -f type="Bug" \
  -f body="## Description
The login page crashes when users attempt to authenticate using SSO.

用户：“创建一个 Bug Issue——使用 SSO 时登录页面会崩溃”

操作：

bash

gh api repos/github/awesome-copilot/issues \\
  -X POST \\
  -f title="Login page crashes when using SSO" \\
  -f type="Bug" \\
  -f body="## Description
The login page crashes when users attempt to authenticate using SSO.

Steps to Reproduce

Navigate to login page
Click 'Sign in with SSO'
Page crashes

Navigate to login page
Click 'Sign in with SSO'
Page crashes

Expected Behavior

SSO authentication should complete and redirect to dashboard.

Actual Behavior

Page becomes unresponsive and displays error."
--jq '{number, html_url}'

undefined

Page becomes unresponsive and displays error." \ --jq '{number, html_url}'

undefined

Example 2: Feature Request

示例 2：Feature Request

User: "Create a feature request for dark mode with high priority"

Action:

bash

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Add dark mode support" \
  -f type="Feature" \
  -f 'labels[]=high-priority' \
  -f body="## Summary
Add dark mode theme option for improved user experience and accessibility.

用户：“创建一个高优先级的深色模式功能请求”

操作：

bash

gh api repos/github/awesome-copilot/issues \\
  -X POST \\
  -f title="Add dark mode support" \\
  -f type="Feature" \\
  -f 'labels[]=high-priority' \\
  -f body="## Summary
Add dark mode theme option for improved user experience and accessibility.

Motivation

Reduces eye strain in low-light environments
Increasingly expected by users

Reduces eye strain in low-light environments
Increasingly expected by users

Proposed Solution

Implement theme toggle with system preference detection.

Acceptance Criteria

Toggle switch in settings
Persists user preference
Respects system preference by default"
--jq '{number, html_url}'

undefined

Toggle switch in settings
Persists user preference
Respects system preference by default" \ --jq '{number, html_url}'

undefined

Common Labels

常用标签

Use these standard labels when applicable:

Label	Use For
`bug`	Something isn't working
`enhancement`	New feature or improvement
`documentation`	Documentation updates
`good first issue`	Good for newcomers
`help wanted`	Extra attention needed
`question`	Further information requested
`wontfix`	Will not be addressed
`duplicate`	Already exists
`high-priority`	Urgent issues

适用时使用以下标准标签：

标签	用途
`bug`	某项功能无法正常工作
`enhancement`	新功能或改进
`documentation`	文档更新
`good first issue`	适合新手处理
`help wanted`	需要更多关注
`question`	需要进一步了解
`wontfix`	不会处理
`duplicate`	已存在
`high-priority`	紧急 Issue

Tips

提示

Always confirm the repository context before creating issues
Ask for missing critical information rather than guessing
Link related issues when known:
```
Related to #123
```
For updates, fetch current issue first to preserve unchanged fields

创建 Issue 前始终确认仓库上下文
缺少关键信息时应询问，而不是猜测
已知时关联相关 Issue：
```
Related to #123
```
更新时，先获取当前 Issue，以保留未更改的字段

Extended Capabilities

扩展能力

The following features require REST or GraphQL APIs beyond the basic MCP tools. Each is documented in its own reference file so the agent only loads the knowledge it needs.

Capability	When to use	Reference
Advanced search	Complex queries with boolean logic, date ranges, cross-repo search, issue field filters ( `field.name:value` )	references/search.md
Sub-issues & parent issues	Breaking work into hierarchical tasks	references/sub-issues.md
Milestones	Create, read, update, close, reopen, delete milestones and manage milestone issues	references/milestones.md
Labels	Discover, create, rename, recolor, and delete repository labels; add or replace labels on an issue	references/labels.md
Issue dependencies	Tracking blocked-by / blocking relationships	references/dependencies.md
Issue types (advanced)	GraphQL operations beyond MCP `list_issue_types` / `type` param	references/issue-types.md
Projects V2	Project boards, progress reports, field management	references/projects.md
Issue fields	Custom metadata: dates, priority, text, numbers (private preview)	references/issue-fields.md
Images in issues	Embedding images in issue bodies and comments via CLI	references/images.md

以下功能需要使用基本 MCP 工具之外的 REST 或 GraphQL APIs。每个功能都在各自的参考文件中记录，使 agent 只加载所需的知识。

能力	使用场景	参考文档
高级搜索	使用布尔逻辑、日期范围、跨仓库搜索和 Issue 字段筛选器（ `field.name:value` ）进行复杂查询	references/search.md
子 Issue 与父 Issue	将工作拆分为层级任务	references/sub-issues.md
里程碑	创建、读取、更新、关闭、重新打开和删除里程碑，以及管理里程碑中的 Issue	references/milestones.md
标签	发现、创建、重命名、重新设置颜色和删除仓库标签；向 Issue 添加或替换标签	references/labels.md
Issue 依赖项	跟踪 blocked-by / blocking 关系	references/dependencies.md
Issue 类型（高级）	MCP `list_issue_types` / `type` 参数之外的 GraphQL 操作	references/issue-types.md
Projects V2	项目看板、进度报告和字段管理	references/projects.md
Issue 字段	自定义元数据：日期、优先级、文本和数字（私有预览）	references/issue-fields.md
Issue 中的图片	通过 CLI 在 Issue 正文和评论中嵌入图片	references/images.md