{"meta":{"title":"Repository configuration for the GitHub Copilot app","intro":"Define repository-specific instructions, scripts, and automation behavior for the GitHub Copilot app.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/en/enterprise-cloud@latest/copilot/reference","title":"Reference"},{"href":"/en/enterprise-cloud@latest/copilot/reference/github-copilot-app-reference","title":"GitHub Copilot app reference"},{"href":"/en/enterprise-cloud@latest/copilot/reference/github-copilot-app-reference/repository-configuration","title":"Repository configuration"}],"documentType":"article"},"body":"# Repository configuration for the GitHub Copilot app\n\nDefine repository-specific instructions, scripts, and automation behavior for the GitHub Copilot app.\n\nUse `.github/github-app.yml` in your repository to define how the GitHub Copilot app should behave for that project.\n\nYou can also edit these project settings in the app UI. If `.github/github-app.yml` already exists, UI changes are written back to that file. If it does not exist yet, you can create it from current project settings in the app.\n\n## About the config file location\n\nCreate the file at:\n\n```text copy\n.github/github-app.yml\n```\n\nThe app also supports the legacy filename `.github/copilot-desktop.yml` for backward compatibility.\n\nFor UI-based customization steps, see [Customizing the GitHub Copilot app](/en/enterprise-cloud@latest/copilot/how-tos/github-copilot-app/customize-github-copilot-app).\n\n## Review and trust the configuration\n\nWhen the app detects a configuration from the repository, it does not apply repository instructions, scripts, or other settings from the file until you review and accept the configuration. This protects you from running commands or applying settings that were added by another contributor. Configurations that you create or update through the app UI are trusted automatically.\n\n> \\[!WARNING]\n> Before accepting a repository configuration, review every configured command and the dependencies it runs. Scripts and their child processes receive the GitHub credentials described later in this article, so never configure them to log or persist these environment variables.\n\nIf the file changes outside the app, including changes to whitespace or comments, you must review and accept the updated configuration before the app applies it. Until you accept the current version, the app continues to use the project settings that were previously configured in the app.\n\n## Example configuration\n\n```yaml copy\ninstructions: |\n  Use bun instead of npm.\n\nscripts:\n  - name: Setup\n    command: bun install\n    triggers:\n      - session.create\n  - name: Run\n    command: bun run dev\n  - name: Archive cleanup\n    command: rm -rf node_modules\n    triggers:\n      - session.archive\n\nserver_ready_pattern: '(?i)Local:\\s+(https?://\\S+)'\nauto_open_in_browser: true\n\nautomation:\n  auto_issue_session: true\n  remote_control: false\n```\n\n## Configure instructions and scripts\n\n### `instructions`\n\nUse `instructions` to add repository-specific guidance to the system prompt for sessions in the project. If you also configure global instructions in the app, the global instructions are applied first, followed by the project instructions.\n\n### `scripts`\n\nUse `scripts` to define commands that appear in the app and can run manually or on specific triggers.\n\nEach script item supports:\n\n* `name` (`string`): Display name in the UI.\n* `command` (`string`): Command to run.\n* `triggers` (`string[]`, optional): Events that auto-run the script.\n\nScripts without `triggers` are manual.\n\n### Trigger values\n\nUse canonical trigger values in your file:\n\n* `session.create`\n* `session.archive`\n\nThe app also accepts these legacy aliases when parsing existing files:\n\n* `workspace.create` (alias for `session.create`)\n* `workspace.archive` (alias for `session.archive`)\n\nWhen a triggered script runs, `COPILOT_SCRIPT_TRIGGER` is set to the canonical value:\n\n* `session.create`\n* `session.archive`\n\n## Configure server detection and browser behavior\n\n### `server_ready_pattern`\n\n`server_ready_pattern` is a regular expression used to detect when a run script has started a server.\n\nPatterns use the syntax supported by Rust's `regex` crate. For syntax details, see [Syntax](https://docs.rs/regex/1/regex/#syntax) in the crate documentation. If the pattern is invalid, the app uses its default server detection pattern.\n\nUse a first capture group for the detected URL or port. The app reads capture group `1`:\n\n* If the capture is a URL (`http://...` or `https://...`), the URL is used.\n* If the capture is only a port number (for example `3000`), the app converts it to `http://localhost:3000`.\n\n### `auto_open_in_browser`\n\nIf `auto_open_in_browser` is `true`, the app opens the detected run URL in the integrated browser. If this field is omitted, the effective default is `true`.\n\n## Configure automation behavior\n\nSet automation options under `automation`:\n\n* `automation.auto_issue_session` (`boolean`) controls whether the app automatically starts a session with issue context. If omitted, the effective default is `true`.\n* `automation.remote_control` (`boolean`) controls whether sessions can be accessed from the GitHub web interface or GitHub Mobile. If omitted, the effective default is `false`.\n\nIf your Copilot seat comes from an organization, the applicable \"Store local sessions in the Cloud\" policy must be set to \"View and control\" for remote control to be available. Enterprise-managed `remoteControl` settings can further restrict remote control even when `automation.remote_control` is `true`. For more information, see [About remote control of GitHub Copilot CLI sessions](/en/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-remote-control) and [Enterprise managed settings](/en/enterprise-cloud@latest/copilot/reference/enterprise-administrators/enterprise-managed-settings).\n\n## Runtime environment variables for scripts\n\nScripts run with these app-provided environment variables:\n\n| Variable                 | Description                                                                                    |\n| ------------------------ | ---------------------------------------------------------------------------------------------- |\n| `COPILOT_WORKSPACE_NAME` | Current workspace name.                                                                        |\n| `COPILOT_WORKSPACE_PATH` | Absolute path to the workspace.                                                                |\n| `COPILOT_ROOT_PATH`      | Absolute path to the project root checkout.                                                    |\n| `COPILOT_DEFAULT_BRANCH` | Project default branch.                                                                        |\n| `COPILOT_PORT`           | App WebSocket port for the current workspace context.                                          |\n| `COPILOT_SCRIPT_TRIGGER` | Trigger that launched the script (only set for triggered scripts).                             |\n| `GH_TOKEN`               | Token for the selected GitHub account.                                                         |\n| `GH_HOST`                | Host for the selected GitHub account.                                                          |\n| `COPILOT_GH_ACCOUNT_*`   | Host- and account-specific tokens for every signed-in account, including the selected account. |\n\nFor each `COPILOT_GH_ACCOUNT_*` variable, the app lowercases the host and login, leaves ASCII letters and digits unchanged, and replaces every other UTF-8 byte with its uppercase hexadecimal value surrounded by underscores. The variable name uses the format `COPILOT_GH_ACCOUNT_<HOST>_<LOGIN>`. For example, the token for `alice` on `github.com` is `COPILOT_GH_ACCOUNT_github_2E_com_alice`, and the token for `user` on `ghe-example.com` is `COPILOT_GH_ACCOUNT_ghe_2D_example_2E_com_user`.\n\n## Legacy compatibility\n\nFor backward compatibility, the app can still parse the older object-based `scripts` shape:\n\n```yaml copy\nscripts:\n  setup: bun install\n  run: bun run dev\n  archive: rm -rf node_modules\n```\n\nIn this legacy shape:\n\n* `setup` maps to a script with the create trigger.\n* `archive` maps to a script with the archive trigger.\n* `run` maps to manual script entries and can be either a single command string or a list of `{ name, command }` objects."}