# GitHub Copilot 应用的存储库配置

定义 GitHub Copilot app特定于存储库的说明、脚本和自动化行为。

在存储库中用于 `.github/github-app.yml` 定义该项目的行为方式 GitHub Copilot app 。

还可以在应用 UI 中编辑这些项目设置。 如果 `.github/github-app.yml` 已存在，UI 更改将写回到该文件。 如果尚不存在，可以从应用中的当前项目设置创建它。

## 关于配置文件位置

在以下位置创建文件：

```text copy
.github/github-app.yml
```

该应用还支持旧文件名 `.github/copilot-desktop.yml` 以实现向后兼容性。

有关基于 UI 的自定义步骤，请参阅 [自定义 GitHub Copilot 应用](/zh/enterprise-cloud@latest/copilot/how-tos/github-copilot-app/customize-github-copilot-app)。

## 查看并信任配置

当应用从存储库检测到配置时，它不会应用文件中的存储库说明、脚本或其他设置，直到查看并接受配置。 这可以防止你运行命令或应用由另一个参与者添加的设置。 通过应用 UI 创建或更新的配置将自动受信任。

> \[!WARNING]
> 在接受存储库配置之前，请查看每个配置的命令及其运行的依赖项。 脚本及其子进程会收到 GitHub 本文后面所述的凭据，因此从不将其配置为记录或保留这些环境变量。

如果文件在应用外部发生更改，包括对空格或注释的更改，则必须在应用应用之前查看并接受更新的配置。 在接受当前版本之前，应用将继续使用以前在应用中配置的项目设置。

## 配置示例

```yaml copy
instructions: |
  Use bun instead of npm.

scripts:
  - name: Setup
    command: bun install
    triggers:
      - session.create
  - name: Run
    command: bun run dev
  - name: Archive cleanup
    command: rm -rf node_modules
    triggers:
      - session.archive

server_ready_pattern: '(?i)Local:\s+(https?://\S+)'
auto_open_in_browser: true

automation:
  auto_issue_session: true
  remote_control: false
```

## 配置说明和脚本

### `instructions`

用于 `instructions` 将特定于存储库的指南添加到项目中的会话的系统提示符。 如果还在应用中配置全局说明，则首先应用全局说明，然后应用项目说明。

### `scripts`

用于 `scripts` 定义显示在应用中的命令，并且可以手动运行或在特定触发器上运行。

每个脚本项都支持：

* `name` （`string`）：UI 中的显示名称。
* `command` （`string`）：要运行的命令。
* `triggers` （`string[]`可选）：自动运行脚本的事件。

没有手动的 `triggers` 脚本。

### 触发器值

在文件中使用规范触发器值：

* `session.create`
* `session.archive`

分析现有文件时，应用还接受这些旧别名：

* `workspace.create` （别名 `session.create`）
* `workspace.archive` （别名 `session.archive`）

当触发的脚本运行时， `COPILOT_SCRIPT_TRIGGER` 设置为规范值：

* `session.create`
* `session.archive`

## 配置服务器检测和浏览器行为

### `server_ready_pattern`

`server_ready_pattern` 是一个正则表达式，用于检测运行脚本何时启动服务器。

模式使用 Rust 箱 `regex` 支持的语法。 有关语法详细信息，请参阅箱文档中的 [语法](https://docs.rs/regex/1/regex/#syntax) 。 如果模式无效，应用将使用其默认服务器检测模式。

对检测到的 URL 或端口使用第一个捕获组。 应用读取捕获组 `1`：

* 如果捕获是 URL（`http://...` 或 `https://...`），则使用 URL。
* 如果捕获只是端口号（例如 `3000`），应用会将其 `http://localhost:3000`转换为 。

### `auto_open_in_browser`

`auto_open_in_browser`如果是`true`，应用将在集成浏览器中打开检测到的运行 URL。 如果省略此字段，则有效默认值为 `true`。

## 配置自动化行为

设置以下自动化 `automation`选项：

* `automation.auto_issue_session` （`boolean`） 控制应用是否自动启动具有问题上下文的会话。 如果省略，则有效默认值为 `true`。
* `automation.remote_control` （`boolean`） 控制是否可以从 GitHub Web 界面访问会话或 GitHub Mobile。 如果省略，则有效默认值为 `false`。

Copilot如果席位来自组织，则必须将适用的“在云中存储本地会话”策略设置为“查看和控制”，以便远程控制可用。 企业管理的 `remoteControl` 设置可以进一步限制远程控制， `automation.remote_control` 即使如此 `true`。 有关详细信息，请参阅 [GitHub Copilot CLI 会话的远程控制](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-remote-control) 和 [企业管理设置](/zh/enterprise-cloud@latest/copilot/reference/enterprise-administrators/enterprise-managed-settings)。

## 脚本的运行时环境变量

脚本使用这些应用提供的环境变量运行：

| Variable                 | 说明                         |
| ------------------------ | -------------------------- |
| `COPILOT_WORKSPACE_NAME` | 当前工作区名称。                   |
| `COPILOT_WORKSPACE_PATH` | 工作区的绝对路径。                  |
| `COPILOT_ROOT_PATH`      | 项目根签出的绝对路径。                |
| `COPILOT_DEFAULT_BRANCH` | Project默认分支。               |
| `COPILOT_PORT`           | 当前工作区上下文的应用 WebSocket 端口。  |
| `COPILOT_SCRIPT_TRIGGER` | 启动脚本的触发器（仅为触发的脚本设置）。       |
| `GH_TOKEN`               | 所选 GitHub 帐户的令牌。           |
| `GH_HOST`                | 所选 GitHub 帐户的主机。           |
| `COPILOT_GH_ACCOUNT_*`   | 每个已登录帐户的主机和帐户特定的令牌，包括所选帐户。 |

对于每个 `COPILOT_GH_ACCOUNT_*` 变量，应用将主机和登录名小写，保留 ASCII 字母和数字不变，并将所有其他 UTF-8 字节替换为其大写十六进制值，并用下划线括起来。 变量名称使用格式 `COPILOT_GH_ACCOUNT_<HOST>_<LOGIN>`。 例如，打开的令牌`alice`是`github.com`，其令牌为 `COPILOT_GH_ACCOUNT_github_2E_com_alice``user`on`ghe-example.com`。`COPILOT_GH_ACCOUNT_ghe_2D_example_2E_com_user`

## 旧版兼容性

为了向后兼容，应用仍可分析基于 `scripts` 对象的较旧形状：

```yaml copy
scripts:
  setup: bun install
  run: bun run dev
  archive: rm -rf node_modules
```

在此旧形状中：

* `setup` 映射到具有创建触发器的脚本。
* `archive` 映射到包含存档触发器的脚本。
* `run` 映射到手动脚本条目，可以是单个命令字符串或对象列表 `{ name, command }` 。