|
| 1 | +--- |
| 2 | +title: Set up and use GitHub Copilot CLI |
| 3 | +shortTitle: 'Set up and use {% data variables.copilot.copilot_cli_short %}' |
| 4 | +intro: Configure a model provider for your {% data variables.product.prodname_ghe_server %} instance, then connect {% data variables.copilot.copilot_cli_short %} clients to the instance. |
| 5 | +allowTitleToDifferFromFilename: true |
| 6 | +versions: |
| 7 | + feature: copilot-cli-ghes |
| 8 | +contentType: how-tos |
| 9 | +category: |
| 10 | + - Configure Copilot CLI |
| 11 | +docsTeamMetrics: |
| 12 | + - copilot-cli |
| 13 | +--- |
| 14 | + |
| 15 | +> [!NOTE] |
| 16 | +> This feature is in {% data variables.release-phases.technical_preview %} and subject to change. |
| 17 | +
|
| 18 | +You can configure {% data variables.copilot.copilot_cli_short %} to work with {% data variables.product.prodname_ghe_server %} in disconnected or air-gapped environments without connectivity to {% data variables.product.github %} Cloud. An administrator configures a model provider for the instance, and users connect {% data variables.copilot.copilot_cli_short %} with their {% data variables.product.prodname_ghe_server %} credentials. |
| 19 | + |
| 20 | +Setting up this feature involves two roles: |
| 21 | + |
| 22 | +* **Administrator**: Configures the model provider on the {% data variables.product.prodname_ghe_server %} instance using `ghe-config`. This is a one-time setup that requires administrative SSH access. |
| 23 | +* **End user**: Sets environment variables on a local machine to connect {% data variables.copilot.copilot_cli_short %} to the instance. |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +* You have administrative SSH access to the {% data variables.product.prodname_ghe_server %} instance. |
| 28 | +* You have an API key from a supported LLM provider. |
| 29 | +* {% data variables.copilot.copilot_cli_short %} is installed on client machines. See [AUTOTITLE](/enterprise-cloud@latest/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). |
| 30 | +* {% data variables.product.prodname_cli %} (`gh`) is installed on client machines. See [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/) in the {% data variables.product.prodname_cli %} documentation. |
| 31 | + |
| 32 | +For information about supported providers and model requirements, see [AUTOTITLE](/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-byok-models). |
| 33 | + |
| 34 | +## Configuring your {% data variables.product.prodname_ghe_server %} instance |
| 35 | + |
| 36 | +This step is for the operator or administrator of the {% data variables.product.prodname_ghe_server %} instance. |
| 37 | + |
| 38 | +With administrative SSH access to the {% data variables.product.prodname_ghe_server %} instance, configure the model provider using the following `ghe-config` values. After configuring, run `ghe-config-apply` to apply the changes. |
| 39 | + |
| 40 | +| Variable name | Required | Options | Description | |
| 41 | +|---|---|---|---| |
| 42 | +| `app.copilot-proxy.enabled` | Yes | `true`, `false` | Enables or disables the feature. | |
| 43 | +| `app.copilot-proxy.endpoint-url` | Yes | URI | The full upstream base URL including any version prefix (for example, `https://api.openai.com/v1`). | |
| 44 | +| `secrets.copilot-proxy.endpoint-key` | Yes | String | The API key for the upstream provider. | |
| 45 | +| `app.copilot-proxy.provider-model-id` | Yes | String | The provider model ID that {% data variables.copilot.copilot_cli_short %} uses to look up the model internally. | |
| 46 | +| `app.copilot-proxy.provider-type` | Yes | `openai`, `azure`, `anthropic` | The provider type. OpenAI includes OpenAI, Ollama, vLLM, Foundry Local, and any other OpenAI Chat Completions API-compatible endpoint. | |
| 47 | +| `app.copilot-proxy.upstream-timeout` | No | Integer, in seconds | Read/send timeout in seconds for upstream requests. If not set, falls back to the default timeout. | |
| 48 | +| `app.copilot-proxy.provider-wire-api` | No | `completions`, `responses` | The wire API format for the provider. | |
| 49 | +| `app.copilot-proxy.provider-wire-model` | No | String | Overrides the model identifier sent to the upstream provider if it differs from the internal model ID. | |
| 50 | +| `app.copilot-proxy.enable-upstream-probe` | No | `true`, `false` | Enables or disables the startup upstream probe. Defaults to enabled. When disabled, the startup probe is skipped. | |
| 51 | + |
| 52 | +For example, the following commands configure an OpenAI provider. |
| 53 | + |
| 54 | +```shell |
| 55 | +ghe-config app.copilot-proxy.enabled true |
| 56 | +ghe-config app.copilot-proxy.endpoint-url 'https://api.openai.com/v1' |
| 57 | +ghe-config secrets.copilot-proxy.endpoint-key 'YOUR-API-KEY' |
| 58 | +ghe-config app.copilot-proxy.provider-model-id 'gpt-5.5' |
| 59 | +ghe-config app.copilot-proxy.provider-wire-model 'gpt-5.5' |
| 60 | +ghe-config app.copilot-proxy.provider-type openai |
| 61 | +ghe-config app.copilot-proxy.upstream-timeout 300 |
| 62 | +ghe-config app.copilot-proxy.enable-upstream-probe false |
| 63 | +ghe-config-apply |
| 64 | +``` |
| 65 | + |
| 66 | +Replace `YOUR-API-KEY` with the real API key before applying the configuration. |
| 67 | + |
| 68 | +## Configuring your {% data variables.copilot.copilot_cli_short %} client (end user) |
| 69 | + |
| 70 | +Configure {% data variables.copilot.copilot_cli_short %} to connect to your {% data variables.product.prodname_ghe_server %} instance by setting the following environment variables before starting {% data variables.copilot.copilot_cli_short %}. |
| 71 | + |
| 72 | +| Environment variable | Required | Description | |
| 73 | +|---|---|---| |
| 74 | +| `COPILOT_PROVIDER_GHES_HOST` | Yes | The hostname of your {% data variables.product.prodname_ghe_server %} instance. | |
| 75 | +| `COPILOT_PROVIDER_GHES_TOKEN` | Yes | A {% data variables.product.pat_generic %} for the {% data variables.product.prodname_ghe_server %} instance. This token authenticates requests to the instance. | |
| 76 | +| `COPILOT_OFFLINE` | Yes | Enables offline mode. The {% data variables.product.prodname_ghe_server %} provider is only active when offline mode is enabled. | |
| 77 | + |
| 78 | +## Understanding client (end user) tokens |
| 79 | + |
| 80 | +{% data variables.copilot.copilot_cli_short %} needs access to LLM inference, so `COPILOT_PROVIDER_GHES_TOKEN` is always required. You will also very likely want {% data variables.copilot.copilot_cli_short %} to perform {% data variables.product.github %} operations such as create issues, pull requests, and search repositories. Such operations can be done via the {% data variables.product.prodname_cli %}. |
| 81 | + |
| 82 | +It is recommended and preferred that you run `gh auth login --hostname YOUR-GHES-HOSTNAME`. After it succeeds, next step is to set `COPILOT_PROVIDER_GHES_TOKEN` to the token generated in `gh auth login --hostname YOUR-GHES-HOSTNAME`. It is more secure to retrieve the token dynamically rather than copying it from `~/.config/gh/hosts.yml`. You can do so by using `COPILOT_PROVIDER_GHES_TOKEN="$(gh auth token --hostname YOUR-GHES-HOSTNAME)"`. |
| 83 | + |
| 84 | +Alternatively, you can generate a {% data variables.product.pat_generic %} on your {% data variables.product.prodname_ghe_server %} instance, set that token as `COPILOT_PROVIDER_GHES_TOKEN`, and use the same token when running `gh auth login --hostname YOUR-GHES-HOSTNAME`. |
| 85 | + |
| 86 | +The above approach works when you are using {% data variables.copilot.copilot_cli_short %} interactively. For automation, you need to do a few things differently: |
| 87 | +* Set `GH_ENTERPRISE_TOKEN` (or `GITHUB_ENTERPRISE_TOKEN`) to the {% data variables.product.pat_generic %}. |
| 88 | +* Set `GH_HOST` to your server's hostname. |
| 89 | +* When both `GH_ENTERPRISE_TOKEN` and `gh auth login` credentials exist for the same host, the environment variable takes precedence. |
| 90 | + |
| 91 | +## Recommended end user setup |
| 92 | + |
| 93 | +1. Authenticate {% data variables.product.prodname_cli %}. |
| 94 | + |
| 95 | + ```shell |
| 96 | + gh auth login --hostname YOUR-GHES-HOSTNAME |
| 97 | + ``` |
| 98 | + |
| 99 | +1. Set the environment variables required by {% data variables.copilot.copilot_cli_short %}. |
| 100 | + |
| 101 | + ```shell |
| 102 | + export COPILOT_PROVIDER_GHES_HOST=YOUR-GHES-HOSTNAME |
| 103 | + export COPILOT_PROVIDER_GHES_TOKEN="$(gh auth token --hostname YOUR-GHES-HOSTNAME)" |
| 104 | + export COPILOT_OFFLINE=true |
| 105 | + ``` |
| 106 | + |
| 107 | + If you are authenticated with `gh auth login` to multiple accounts, you can set `GH_HOST` to your server's hostname and set `GH_ENTERPRISE_TOKEN` (or `GITHUB_ENTERPRISE_TOKEN`) to `"$(gh auth token --hostname YOUR-GHES-HOSTNAME)"`. This ensures {% data variables.product.prodname_cli %} targets your {% data variables.product.prodname_ghe_server %} instance. |
| 108 | + |
| 109 | + ```shell |
| 110 | + export GH_HOST=YOUR-GHES-HOSTNAME |
| 111 | + export GH_ENTERPRISE_TOKEN="$(gh auth token --hostname YOUR-GHES-HOSTNAME)" |
| 112 | + ``` |
| 113 | + |
| 114 | +{% data reusables.copilot.copilot-cli.start-cli %} |
| 115 | + |
| 116 | +You can run this entire set-up as a script. |
| 117 | + |
| 118 | +## Examples |
| 119 | + |
| 120 | +If both {% data variables.product.prodname_ghe_server %} and your {% data variables.copilot.copilot_cli_short %} configurations are correct, then you should see responses like the following in your {% data variables.copilot.copilot_cli_short %} session. |
| 121 | + |
| 122 | +```shell |
| 123 | + • fabric-core-mcp — disabled |
| 124 | + • powerbi-mcp — disabled |
| 125 | + • slack — connected |
| 126 | + |
| 127 | + ● Current model: gpt-5.5 |
| 128 | + |
| 129 | + ❯ Hello 13:31 |
| 130 | + |
| 131 | + ● Hello! |
| 132 | + |
| 133 | + ❯ what is going on in github/codeql-action repo? 13:33 |
| 134 | + |
| 135 | + ● I’ll check recent repository activity on the GHES host: repo metadata, open |
| 136 | + PRs/issues, and latest commits. |
| 137 | + |
| 138 | + $ Shell Fetch repo metadata 2 lines… 5s |
| 139 | + gh api --hostname "$GH_HOST" repos/github/codeql-action --jq '{name_with_own… |
| 140 | +``` |
| 141 | +
|
| 142 | +## Supported capabilities on {% data variables.product.prodname_ghe_server %} |
| 143 | +
|
| 144 | +For the most up-to-date information on {% data variables.copilot.copilot_cli_short %} features, refer to [AUTOTITLE](/enterprise-cloud@latest/copilot/how-tos/copilot-cli) as the primary source of truth. In general, any capability that relies on connectivity to {% data variables.product.github %} cloud services is not available in the {% data variables.product.prodname_ghe_server %} offline configuration. |
| 145 | +
|
| 146 | +The following table provides a directional overview of what is available in {% data variables.product.prodname_ghe_server %} offering. |
| 147 | +
|
| 148 | +| Capability | {% data variables.product.prodname_dotcom %} / {% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_server %} | |
| 149 | +|:---|:---:|:---:| |
| 150 | +| AI-assisted coding (prompts, code generation, debugging) | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | |
| 151 | +| Shell commands and file operations | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | |
| 152 | +| {% data variables.product.github %} operations (issues, PRs, repos) via `gh` CLI | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} (requires `gh` CLI authenticated to the instance) | |
| 153 | +| {% data variables.product.github %} MCP server tools | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | |
| 154 | +| Web search and web fetch | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | |
| 155 | +| {% data variables.product.prodname_copilot_short %} model selection ({% data variables.product.github %}-hosted models) | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | |
| 156 | +| Telemetry and usage reporting | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | |
| 157 | +| Auto-update | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | |
| 158 | +
|
0 commit comments