You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment.md
+80-53Lines changed: 80 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,22 +21,22 @@ category:
21
21
22
22
While working on a task, {% data variables.product.prodname_copilot_short %} has access to its own ephemeral development environment, powered by {% data variables.product.prodname_actions %}, where it can explore your code, make changes, execute automated tests and linters and more.
23
23
24
-
You can customize {% data variables.product.prodname_copilot_short %}'s environment to:
24
+
You can customize {% data variables.product.prodname_copilot_short %}'s development environment with a [{% data variables.product.prodname_copilot_short %} setup steps file](#customizing-copilots-development-environment-with-copilot-setup-steps). You can use a {% data variables.product.prodname_copilot_short %} setup steps file to:
25
25
26
26
*[Preinstall tools or dependencies in {% data variables.product.prodname_copilot_short %}'s environment](#preinstalling-tools-or-dependencies-in-copilots-environment)
27
-
*[Set environment variables in {% data variables.product.prodname_copilot_short %}'s environment](#setting-environment-variables-in-copilots-environment)
28
27
*[Upgrade from standard {% data variables.product.github %}-hosted {% data variables.product.prodname_actions %} runners to larger runners](#upgrading-to-larger-github-hosted-github-actions-runners)
29
-
*[Run on your ARC-based {% data variables.product.prodname_actions %} self-hosted runners](#using-self-hosted-github-actions-runners-with-arc)
28
+
*[Run on {% data variables.product.prodname_actions %} self-hosted runners](#using-self-hosted-github-actions-runners)
29
+
*[Give {% data variables.product.prodname_copilot_short %} a Windows development environment](#switching-copilot-to-a-windows-development-environment), instead of the default Ubuntu Linux environment
30
30
*[Enable Git Large File Storage (LFS)](#enabling-git-large-file-storage-lfs)
31
-
*[Disable or customize the agent's firewall](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
32
31
33
-
## Preinstalling tools or dependencies in {% data variables.product.prodname_copilot_short %}'s environment
32
+
In addition, you can:
34
33
35
-
In its ephemeral development environment, {% data variables.product.prodname_copilot_short %} can build or compile your project and run automated tests, linters and other tools. To do this, it will need to install your project's dependencies.
34
+
*[Set environment variables in {% data variables.product.prodname_copilot_short %}'s environment](#setting-environment-variables-in-copilots-environment)
35
+
*[Disable or customize the agent's firewall](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
36
36
37
-
{% data variables.product.prodname_copilot_short %} can discover and install these dependencies itself via a process of trial and error, but this can be slow and unreliable, given the non-deterministic nature of large language models (LLMs), and in some cases, it may be completely unable to download these dependencies—for example, if they are private.
37
+
## Customizing {% data variables.product.prodname_copilot_short %}'s development environment with {% data variables.product.prodname_copilot_short %} setup steps
38
38
39
-
Instead, you can preconfigure {% data variables.product.prodname_copilot_short %}'s environment before the agent starts by creating a special {% data variables.product.prodname_actions %} workflow file, located at `.github/workflows/copilot-setup-steps.yml` within your repository.
39
+
You can customize {% data variables.product.prodname_copilot_short %}'s environment by creating a special {% data variables.product.prodname_actions %} workflow file, located at `.github/workflows/copilot-setup-steps.yml` within your repository.
40
40
41
41
A `copilot-setup-steps.yml` file looks like a normal {% data variables.product.prodname_actions %} workflow file, but must contain a single `copilot-setup-steps` job. This job will be executed in {% data variables.product.prodname_actions %} before {% data variables.product.prodname_copilot_short %} starts working. For more information on {% data variables.product.prodname_actions %} workflow files, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions).
42
42
@@ -67,23 +67,14 @@ jobs:
67
67
# Set the permissions to the lowest permissions possible needed for your steps.
68
68
# Copilot will be given its own token for its operations.
69
69
permissions:
70
-
# If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
70
+
# If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission.
71
+
# If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
71
72
contents: read
72
73
73
74
# You can define any steps you want, and they will run before the agent starts.
74
75
# If you do not check out your code, Copilot will do this for you.
75
76
steps:
76
-
- name: Checkout code
77
-
uses: {% data reusables.actions.action-checkout %}
78
-
79
-
- name: Set up Node.js
80
-
uses: {% data reusables.actions.action-setup-node %}
81
-
with:
82
-
node-version: "20"
83
-
cache: "npm"
84
-
85
-
- name: Install JavaScript dependencies
86
-
run: npm ci
77
+
# ...
87
78
```
88
79
89
80
In your `copilot-setup-steps.yml` file, you can only customize the following settings of the `copilot-setup-steps` job. If you try to customize other settings, your changes will be ignored.
@@ -107,61 +98,74 @@ When {% data variables.product.prodname_copilot_short %} starts work, your setup
107
98
108
99
If any setup step fails by returning a non-zero exit code, {% data variables.product.prodname_copilot_short %} will skip the remaining setup steps and begin working with the current state of its development environment.
109
100
110
-
## Setting environment variables in {% data variables.product.prodname_copilot_short %}'s environment
111
-
112
-
You may want to set environment variables in {% data variables.product.prodname_copilot_short %}'s environment to configure or authenticate tools or dependencies that it has access to.
113
-
114
-
To set an environment variable for {% data variables.product.prodname_copilot_short %}, create a {% data variables.product.prodname_actions %} variable or secret in the `copilot` environment. If the value contains sensitive information, for example a password or API key, it's best to use a {% data variables.product.prodname_actions %} secret.
115
-
116
-
{% data reusables.repositories.navigate-to-repo %}
117
-
{% data reusables.repositories.sidebar-settings %}
118
-
{% data reusables.actions.sidebar-environment %}
119
-
1. Click the `copilot` environment.
120
-
1. To add a secret, under "Environment secrets," click **Add environment secret**. To add a variable, under "Environment variables," click **Add environment variable**.
121
-
1. Fill in the "Name" and "Value" fields, and then click **Add secret** or **Add variable** as appropriate.
122
-
123
-
## Upgrading to larger {% data variables.product.prodname_dotcom %}-hosted {% data variables.product.prodname_actions %} runners
124
-
125
-
By default, {% data variables.product.prodname_copilot_short %} works in a standard {% data variables.product.prodname_actions %} runner with limited resources.
101
+
## Preinstalling tools or dependencies in {% data variables.product.prodname_copilot_short %}'s environment
126
102
127
-
You can choose instead to use larger runners with more advanced features—for example more RAM, CPU and disk space and advanced networking controls. You may want to upgrade to a larger runner if you see poor performance—for example when downloading dependencies or running tests. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners).
103
+
In its ephemeral development environment, {% data variables.product.prodname_copilot_short %} can build or compile your project and run automated tests, linters and other tools. To do this, it will need to install your project's dependencies.
128
104
129
-
Before {% data variables.product.prodname_copilot_short %} can use larger runners, you must first add one or more larger runners and then configure your repository to use them. See [AUTOTITLE](/actions/using-github-hosted-runners/managing-larger-runners). Once you have done this, you can use the `copilot-setup-steps.yml` file to tell {% data variables.product.prodname_copilot_short %} to use the larger runners.
105
+
{% data variables.product.prodname_copilot_short %} can discover and install these dependencies itself via a process of trial and error, but this can be slow and unreliable, given the non-deterministic nature of large language models (LLMs), and in some cases, it may be completely unable to download these dependencies—for example, if they are private.
130
106
131
-
To use larger runners, set the `runs-on` step of the `copilot-setup-steps` job to the label and/or group for the larger runners you want {% data variables.product.prodname_copilot_short %} to use. For more information on specifying larger runners with `runs-on`, see [AUTOTITLE](/actions/using-github-hosted-runners/running-jobs-on-larger-runners).
107
+
You can use a Copilot setupsteps file to deterministically install tools or dependencies before {% data variables.product.prodname_copilot_short %} starts work. To do this, add `steps` to the `copilot-setup-steps` job:
132
108
133
109
```yaml
134
110
# ...
135
111
136
112
jobs:
137
113
copilot-setup-steps:
138
-
runs-on: ubuntu-4-core
139
114
# ...
115
+
116
+
# You can define any steps you want, and they will run before the agent starts.
117
+
# If you do not check out your code, Copilot will do this for you.
118
+
steps:
119
+
- name: Checkout code
120
+
uses: {% data reusables.actions.action-checkout %}
121
+
122
+
- name: Set up Node.js
123
+
uses: {% data reusables.actions.action-setup-node %}
124
+
with:
125
+
node-version: "20"
126
+
cache: "npm"
127
+
128
+
- name: Install JavaScript dependencies
129
+
run: npm ci
140
130
```
141
131
132
+
## Upgrading to larger {% data variables.product.prodname_dotcom %}-hosted {% data variables.product.prodname_actions %} runners
133
+
134
+
By default, {% data variables.product.prodname_copilot_short %} works in a standard {% data variables.product.prodname_actions %} runner. You can upgrade to larger runners for better performance (CPU and memory), more disk space and advanced features like Azure private networking. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners).
135
+
136
+
1. Set up larger runners for your organization. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/managing-larger-runners).
137
+
1. If you are using larger runners with Azure private networking, configure your Azure private network to allow outbound access to the hosts required for {% data variables.copilot.copilot_coding_agent %}:
138
+
139
+
{% data reusables.copilot.coding-agent-required-hosts %}
140
+
141
+
1. Use a `copilot-setup-steps.yml` file in your repository to configure {% data variables.copilot.copilot_coding_agent %} to run on your chosen runners. Set the `runs-on` step of the `copilot-setup-steps` job to the label and/or group for the larger runners you want {% data variables.product.prodname_copilot_short %} to use. For more information on specifying larger runners with `runs-on`, see [AUTOTITLE](/actions/using-github-hosted-runners/running-jobs-on-larger-runners).
142
+
143
+
```yaml
144
+
# ...
145
+
146
+
jobs:
147
+
copilot-setup-steps:
148
+
runs-on: ubuntu-4-core
149
+
# ...
150
+
```
151
+
142
152
> [!NOTE]
143
-
> * {% data variables.copilot.copilot_coding_agent %} is only compatible with Ubuntu x64 Linux runners. Runners with Windows, macOS or other operating systems are not supported.
153
+
> * {% data variables.copilot.copilot_coding_agent %} is only compatible with Ubuntu x64 Linux and Windows 64-bit runners. Runners with macOS or other operating systems are not supported.
144
154
145
-
## Using self-hosted {% data variables.product.prodname_actions %} runners.
155
+
## Using self-hosted {% data variables.product.prodname_actions %} runners
146
156
147
-
You can run {% data variables.copilot.copilot_coding_agent %} on self-hosted runners powered by ARC (Actions Runner Controller), or the GitHub Actions Runner Scale Set Client. You must first set up ARC- For more information on ARC, see [AUTOTITLE](/actions/reference/runners/self-hosted-runners#supported-autoscaling-solutions).
157
+
You can run {% data variables.copilot.copilot_coding_agent %} on self-hosted runners. You may want to do this to match how you run CI/CD workflows on {% data variables.product.prodname_actions %}, or to give {% data variables.product.prodname_copilot_short %} access to internal resources on your network.
148
158
149
-
> [!WARNING]
150
-
> ARC and the Scale Set Client are the only officially supported solutions for self-hosting {% data variables.copilot.copilot_coding_agent %}.
159
+
We recommend that you only use {% data variables.copilot.copilot_coding_agent %} with ephemeral, single-use runners that are not reused for multiple jobs. Most customers set this up using ARC (Actions Runner Controller) or the {% data variables.product.prodname_actions %} Runner Scale Set Client. For more information, see [AUTOTITLE](/actions/reference/runners/self-hosted-runners#supported-autoscaling-solutions).
151
160
152
161
> [!NOTE]
153
-
> {% data variables.copilot.copilot_coding_agent %} is only compatible with Ubuntu x64 Linux runners. Runners with Windows, macOS or other operating systems are not supported.
162
+
> {% data variables.copilot.copilot_coding_agent %} is only compatible with Ubuntu x64 and Windows 64-bit runners. Runners with macOS or other operating systems are not supported.
154
163
155
164
1. Configure network security controls for your {% data variables.product.prodname_actions %} runners to ensure that {% data variables.copilot.copilot_coding_agent %} does not have open access to your network or the public internet.
156
165
157
166
You must configure your firewall to allow connections to the [standard hosts required for {% data variables.product.prodname_actions %} self-hosted runners](/actions/reference/runners/self-hosted-runners#accessible-domains-by-function), plus the following hosts:
158
167
159
-
* `uploads.github.com`
160
-
* `user-images.githubusercontent.com`
161
-
* `api.individual.githubcopilot.com` (if you expect {% data variables.copilot.copilot_pro_short %} or {% data variables.copilot.copilot_pro_plus_short %} users to use {% data variables.copilot.copilot_coding_agent %} in your repository)
162
-
* `api.business.githubcopilot.com` (if you expect {% data variables.copilot.copilot_business_short %} users to use {% data variables.copilot.copilot_coding_agent %} in your repository)
163
-
* `api.enterprise.githubcopilot.com` (if you expect {% data variables.copilot.copilot_enterprise_short %} users to use {% data variables.copilot.copilot_coding_agent %} in your repository)
164
-
* `api.githubcopilot.com` (*no longer required after February 27, 2026*)
168
+
{% data reusables.copilot.coding-agent-required-hosts %}
165
169
166
170
1. Disable {% data variables.copilot.copilot_coding_agent %}'s integrated firewall in your repository settings. The firewall is not compatible with self-hosted runners. Unless this is disabled, use of {% data variables.copilot.copilot_coding_agent %} will be blocked. For more information, see [AUTOTITLE](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
167
171
1. In your `copilot-setup-steps.yml` file, set the `runs-on` attribute to your ARC-managed scale set name:
@@ -181,7 +185,17 @@ You can run {% data variables.copilot.copilot_coding_agent %} on self-hosted run
181
185
| `ssl_cert_file` | The path to the SSL certificate presented by your proxy server. You will need to configure this if your proxy intercepts SSL connections. | `/path/to/key.pem` |
182
186
| `node_extra_ca_certs` | The path to the SSL certificate presented by your proxy server. You will need to configure this if your proxy intercepts SSL connections. | `/path/to/key.pem` |
183
187
184
-
You can set these environment variables by following the [instructions above](#setting-environment-variables-in-copilots-environment), or by baking the environment variables into your custom runner image. For more information on building a custom image, see [AUTOTITLE](/actions/concepts/runners/actions-runner-controller#creating-your-own-runner-image).
188
+
You can set these environment variables by following the [instructions below](#setting-environment-variables-in-copilots-environment), or by setting them on the runner directly, for example with a custom runner image. For more information on building a custom image, see [AUTOTITLE](/actions/concepts/runners/actions-runner-controller#creating-your-own-runner-image).
189
+
190
+
## Switching {% data variables.product.prodname_copilot_short %} to a Windows development environment
191
+
192
+
By default, {% data variables.product.prodname_copilot_short %} uses an Ubuntu Linux-based development environment.
193
+
194
+
You may want to use a Windows development environment if you're building software for Windows or your repository uses a Windows-based toolchain so {% data variables.product.prodname_copilot_short %} can build your project, run tests and validate its work.
195
+
196
+
{% data variables.copilot.copilot_coding_agent %}'s integrated firewall is not compatible with Windows, so we recommend that you only use self-hosted runners or larger {% data variables.product.prodname_dotcom %}-hosted runners with Azure private networking where you can implement your own network controls. For more information on runners with Azure private networking, see [AUTOTITLE](/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise).
197
+
198
+
To use Windows with self-hosted runners, follow the instructions in the [Using self-hosted {% data variables.product.prodname_actions %} runners](#using-self-hosted-github-actions-runners) section above, using the label for your Windows runners. To use Windows with larger {% data variables.product.prodname_dotcom %}-hosted runners, follow the instructions in the [Upgrading to larger runners](#upgrading-to-larger-github-hosted-github-actions-runners) section above, using the label for your Windows runners.
185
199
186
200
## Enabling Git Large File Storage (LFS)
187
201
@@ -203,6 +217,19 @@ jobs:
203
217
lfs: true
204
218
```
205
219
220
+
## Setting environment variables in {% data variables.product.prodname_copilot_short %}'s environment
221
+
222
+
You may want to set environment variables in {% data variables.product.prodname_copilot_short %}'s environment to configure or authenticate tools or dependencies that it has access to.
223
+
224
+
To set an environment variable for {% data variables.product.prodname_copilot_short %}, create a {% data variables.product.prodname_actions %} variable or secret in the `copilot` environment. If the value contains sensitive information, for example a password or API key, it's best to use a {% data variables.product.prodname_actions %} secret.
225
+
226
+
{% data reusables.repositories.navigate-to-repo %}
227
+
{% data reusables.repositories.sidebar-settings %}
228
+
{% data reusables.actions.sidebar-environment %}
229
+
1. Click the `copilot` environment.
230
+
1. To add a secret, under "Environment secrets," click **Add environment secret**. To add a variable, under "Environment variables," click **Add environment variable**.
231
+
1. Fill in the "Name" and "Value" fields, and then click **Add secret** or **Add variable** as appropriate.
0 commit comments