---
title: "GitHub"
description: "通过 GitHub CLI 审查、创建、签出和合并 GitHub 拉取请求，并克隆自己的仓库。"
---

OpenIDEA 通过 [GitHub CLI](https://cli.github.com)（`gh`）对接 GitHub：登录沿用 gh 的登录状态，API 调用都走 `gh api`。OpenIDEA 自己没有账户管理和令牌输入框，也不保存任何凭据。

## 准备工作

<Steps>
  <Step title="安装 gh">
    安装 GitHub CLI。OpenIDEA 依次在 `OPENIDEA_GH`（完整路径）、`PATH`，以及
    `/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/snap/bin`（macOS/Linux）或 `C:\Program Files\GitHub
    CLI\gh.exe`（Windows）中查找。
  </Step>
  <Step title="登录">
    在终端运行 `gh auth login`。未登录时打开 **拉取请求** 工具窗口，会显示 **未登录 GitHub** 和 **运行 gh auth login**
    按钮，点击后在内置终端中执行该命令。完成后点 **重试**。
  </Step>
  <Step title="打开带 GitHub 远程的项目">
    项目需要有一个指向 `github.com` 的 Git 远程。只有一个 GitHub 远程时自动连接；有多个时，工具窗口会让你选择
    **仓库**，选择按项目记住。之后要切换，可在工具窗口的 `⋮` 菜单中选 **更改仓库或账户…**。
  </Step>
</Steps>

<Note>只支持 `github.com`，不支持 GitHub Enterprise、GitLab 和 Bitbucket。</Note>

## 菜单与快捷键

**Git › GitHub** 菜单（编辑器右键菜单的 **Git** 下也有）包含：

- **查看拉取请求**：打开拉取请求工具窗口。
- **创建拉取请求…**
- **签出拉取请求…**：签出选中的拉取请求，未选中时会询问编号。
- **在 GitHub 上打开**：在浏览器中打开选中的拉取请求，或者仓库主页。

| 操作                                  | macOS | Windows/Linux  |
| ------------------------------------- | ----- | -------------- |
| 创建拉取请求…（在拉取请求工具窗口中） | `⌘N`  | `Alt+Insert`   |
| 刷新列表、拉取请求或时间线            | `⌘R`  | `Ctrl+F5`      |
| 切换已查看/未查看状态                 | `⌘⇧S` | `Ctrl+Shift+S` |

## 浏览拉取请求

**拉取请求** 工具窗口位于左侧。第一个标签页列出仓库的拉取请求，每打开一个拉取请求就多一个 `#N` 标签页。

- **搜索**：输入文本或 GitHub 搜索限定符后按 `Enter`。历史按钮（或 `⌥↓` / `Alt+Down`）显示最近 10 次搜索。
- **快速筛选**（漏斗按钮）：**打开**、**您的拉取请求**、**指派给您**、**审查请求**。
- **筛选条件**：**状态**、**作者**、**标签**、**被指派者**、**审查**、**排序**。在条件上按 `Delete` 或 `Backspace` 可以重置。
- 每一行显示未读标记、标签、状态、合并冲突、被指派者和审阅者头像，以及未解决评论数。

右键拉取请求可选择 **查看拉取请求**、**签出分支**、**在工作树中打开**、**在浏览器中查看拉取请求**、**复制拉取请求 URL** 和 **刷新列表**。

## 拉取请求详情

双击拉取请求（或按 `Enter`）打开详情标签页：

- 标题、状态，以及 **查看时间线** 链接。
- 提交选择器：可以一起看所有提交，也可以逐个提交查看。
- 源分支，提供 **签出**、**在工作树中打开**、**在 Git 日志中显示**、**复制分支名称**。
- 变更文件列表。双击文件打开差异。可以用 **标记为已查看** / **标记为未查看**（或“所有提交”视图中的复选框）标记文件。
- 状态区：检查运行情况（**详细信息…** 列出每个作业，点击在 GitHub 上打开）、合并冲突（**解决** 链接会签出分支并在本地把基础分支合并进来）、必需的审查以及各审阅者状态。

下方按钮取决于你的角色和拉取请求的状态：

| 你的身份         | 按钮                                                                  |
| ---------------- | --------------------------------------------------------------------- |
| 作者             | **请求审查…**，批准后出现合并按钮，**关闭拉取请求**（在“更多操作”中） |
| 审阅者           | **提交审查…**，批准后可以合并                                         |
| 其他人           | **将自己设为审查者**                                                  |
| 任何人，草稿状态 | **发布拉取请求**（标记为可以审查）                                    |
| 任何人，已关闭   | **重新打开拉取请求**                                                  |

合并按钮只提供仓库允许的方式：**合并…**、**压缩并合并…**（这两种可以编辑提交消息）和 **变基**。

## 审查代码

### 在差异视图中评论

拉取请求的差异是合并基础与头提交之间的比较。如果本地缺少拉取请求的引用或基础分支，OpenIDEA 会先获取。

- 鼠标悬停在某行上，点击边栏的 **+** 添加评论；拖动可以选中多行。
- 选择 **开始审查**（评论先挂起，提交审查时一起发出）或 **添加单条评论**。OpenIDEA 会记住你上次的选择。
- 已有的讨论直接显示在对应行下方。在差异设置的 **显示审查讨论** 中选择 **全部**、**仅未解决**（默认）或 **不显示**。
- 差异工具栏有 **刷新审查数据**、**提交审查…**、**上一条评论**、**下一条评论**。过了最后一处变更后，按 `F7` 会跳到拉取请求的下一个文件。

想在打开文件时自动标记为已查看，可以在 **设置 › 版本控制 › GitHub** 中打开 **自动将打开的文件标记为已查看**。

### 提交审查

**提交审查…** 会弹出一个小窗口。可以写一段总结，然后选择 **批准**、**请求更改** 或 **评论**。垃圾桶按钮会丢弃所有挂起的评论。作者不能批准自己的拉取请求，也不能对其请求更改。

### 时间线

**查看时间线** 在编辑器标签页中打开拉取请求的对话：描述、提交、审查、审查讨论和各种事件，最新的在底部。在这里可以：

- 发表评论（`⌘Enter` / `Ctrl+Enter` 发送），支持 `@` 提及补全。
- 编辑或删除自己的评论，添加表情回应。
- 回复审查讨论，并 **解决** 或取消解决。
- 用 **在本地应用** 应用建议的更改，或者用 **提交…** 一步应用并提交。只有签出了拉取请求的分支时才能应用建议。
- 拉取请求合并后，可以在横幅中删除头分支。

### 审查模式

当签出的分支正是某个打开的拉取请求的头分支时，分支微件会显示 `#N on 分支名`，审查模式随之开启：

- 审查讨论直接显示在普通编辑器中，边栏的 **+** 可以添加评论，变更标记以拉取请求的基础为准。
- 编辑器角落的工具栏有 **上一条评论**、**下一条评论** 和 **审查模式** 菜单（**禁用审查模式**、**仅显示未解决的评论**、**显示所有评论**）。
- 编辑器右键菜单中多出 **显示审查差异**。
- 本地分支落后于远程时，分支微件会提供 **更新以启用审查模式…**。

审查模式默认开启，按项目记住开关状态。

## 创建拉取请求

**创建拉取请求…** 会打开一个新建拉取请求的标签页（标题形如“在 owner/repo 新建拉取请求”）：

1. 选择 **基础分支** 和 **头分支**（本地或远程分支；有 fork 时还可以选择仓库）。
2. 检查提交和变更文件。
3. 填写标题和描述。标题默认取唯一提交的主题行或分支名；描述会预先填入仓库的拉取请求模板。
4. 可选：设置 **审阅者:**、**受理人:**、**标签:**。
5. 点击 **创建拉取请求**，或通过旁边的箭头选择 **创建草稿拉取请求**。

如果头分支只存在于本地，OpenIDEA 会询问远程分支名并先推送。如果这两个分支之间已有拉取请求，会提示你直接打开它。

## 签出拉取请求

- **签出分支**（或 **签出拉取请求…**）执行 `gh pr checkout`，来自 fork 的拉取请求也能签出。
- **在工作树中打开** 会在仓库旁边新建一个 Git 工作树（名为 `<repo>_PR_<n>`），签出拉取请求的头提交，并在新窗口中打开。

## 从 GitHub 克隆

**Git › 克隆…** 打开 **克隆仓库** 对话框。在侧栏选择 **GitHub**，会列出你拥有、参与协作或通过组织可以访问的仓库，按最近推送时间排序。用 **搜索仓库** 过滤，双击仓库（或按 `Enter`）即可克隆。URL 默认用 HTTPS；如果 gh 对 github.com 配置的 `git_protocol` 是 `ssh`，则用 SSH。

## Git 日志中的提交检查

Git 日志可以显示每个提交在 GitHub 上的检查状态。在日志的 **视图选项 › 列** 中，或在 **设置 › 版本控制 › 日志** 中打开 **GitHub 提交检查** 列。点击提交的图标列出它的检查运行，再点击某项即可在 GitHub 上打开。

## 暂不支持

- GitHub Enterprise、GitLab、Bitbucket。
- Issue、Gist、通知，以及创建或分享仓库。
- 在 GitHub 上打开文件或某一行、复制永久链接。
- 管理 GitHub Actions（重新运行作业、查看日志）。