Merge pull request github#38422 from github/repo-sync

Repo sync

Author: docs-bot

assets/images/help/copilot/coding-agent/approve-and-run-workflows.png

@@ -47,6 +47,38 @@ Some migrations cannot be completed through self-service options.
 
 * **Changing between {% data variables.product.prodname_copilot_business_short %} and {% data variables.product.prodname_copilot_enterprise_short %}**: If you need to migrate between these plans within your enterprise and the option isn't available in your "Billing & Licensing" settings, contact {% data variables.contact.contact_support_page %} or your account manager for assistance.
 
+## Allowance usage for {% data variables.copilot.copilot_coding_agent %}
+
+{% data reusables.copilot.coding-agent.premium-requests-start-date %}
+
+Within your monthly usage allowance for {% data variables.product.prodname_actions %} and {% data variables.product.prodname_copilot %} premium requests, you can ask {% data variables.product.prodname_copilot_short %} to work on coding tasks without incurring any additional costs.
+
+When {% data variables.product.prodname_copilot_short %} works on coding tasks, {% data variables.copilot.copilot_coding_agent %} uses:
+
+* **{% data variables.product.prodname_actions %} minutes** from your account's monthly allowance of free minutes for {% data variables.product.prodname_dotcom %}-hosted runners.
+
+  This allowance of free minutes is shared with all {% data variables.product.prodname_actions %} workflows in your account.
+
+  For details of the free minutes allowance for your {% data variables.product.github %} plan, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes).
+
+* **Premium requests** from your account's monthly allowance of premium {% data variables.product.prodname_copilot_short %} requests.
+
+  This allowance of free premium requests is shared with other {% data variables.product.prodname_copilot_short %} features, such as {% data variables.product.prodname_copilot_chat_short %}.
+
+  When you use {% data variables.copilot.copilot_coding_agent %}, {% data variables.product.prodname_copilot_short %} may make multiple premium requests to complete a single task. This includes both user-initiated prompts and follow-up actions {% data variables.product.prodname_copilot_short %} takes on your behalf. The total premium requests used will depend on the complexity of the task and the number of steps involved. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/monitoring-usage-and-entitlements/avoiding-unexpected-copilot-costs).
+
+For more information about {% data variables.copilot.copilot_coding_agent %}, see [AUTOTITLE](/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot).
+
+### What happens if you have used up your monthly quota?
+
+If you run out of free Actions minutes or free premium requests, and you have set up billing and a spending limit, you will be charged at the normal rates for additional minutes and premium requests. See [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/monitoring-usage-and-entitlements/about-premium-requests#additional-premium-requests).
+
+If you run out of free minutes or premium requests, and you have _not_ set up billing, a message is displayed explaining why {% data variables.product.prodname_copilot_short %} cannot work on the task.
+
+### Monitoring your use of Actions minutes and premium requests
+
+You can track your monthly usage of {% data variables.product.prodname_actions %} minutes and premium requests, to help you get the most value from your {% data variables.product.prodname_copilot_short %} plan. See [AUTOTITLE](/enterprise-cloud@latest/billing/managing-billing-for-your-products/managing-billing-for-github-actions/viewing-your-github-actions-usage) and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/monitoring-usage-and-entitlements/monitoring-your-copilot-usage-and-entitlements).
+
 ## Further reading
 
 * [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot)

assets/images/help/copilot/coding-agent/assign-to-copilot.png

@@ -1,7 +1,7 @@
 ---
 title: Adding repository custom instructions for GitHub Copilot
 shortTitle: Repository custom instructions
-intro: 'Create a file in a repository that automatically adds information to questions you ask {% data variables.product.prodname_copilot_chat_short %}.'
+intro: 'Create a file in a repository that gives {% data variables.product.prodname_copilot_short %} additional context for the work it does in that repository.'
 redirect_from:
    - /copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
 versions:
@@ -15,16 +15,18 @@ topics:
 
 > This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change.
 >
-{% data reusables.copilot.repository-custom-instructions-note %}
+{% data reusables.copilot.repository-custom-instructions-note %} They are also supported for {% data variables.copilot.copilot_coding_agent %}.
 >
 > This version of this article is for using repository custom instructions on the {% data variables.product.github %} website. Click the tabs above for information on using custom instructions in other environments. <!-- markdownlint-disable-line MD027 -->
 
-For an overview of the methods you can use to customize {% data variables.product.prodname_copilot_chat %} responses, see [AUTOTITLE](/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses?tool=webui).
+For an overview of the methods you can use to customize {% data variables.product.prodname_copilot_chat %} responses, see [AUTOTITLE](/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses?tool=webui). For information on customizing {% data variables.copilot.copilot_coding_agent %} see [AUTOTITLE](/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent).
 
-## About repository custom instructions for {% data variables.product.prodname_copilot_chat %}
+## About repository custom instructions for {% data variables.product.prodname_copilot_short %}
 
 {% data variables.product.prodname_copilot %} can provide chat responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your chat questions, you can create a file in your repository that automatically adds this information for you. The additional information is not displayed in the chat, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses.
 
+The custom instructions file is also used by {% data variables.product.prodname_copilot_short %} when you assign it to an issue or ask it to create a pull request. Instructions included in this file can help {% data variables.product.prodname_copilot_short %} to work on files in a way that matches your team's working practices and conforms to coding standards for your project. See [AUTOTITLE](/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot).
+
 ### Example
 
 {% data reusables.copilot.repository-custom-instructions-example %}

assets/images/help/copilot/coding-agent/comment-to-agent-on-pr.png

@@ -0,0 +1,59 @@
+---
+title: Customizing or disabling the firewall for Copilot coding agent
+shortTitle: Customize the agent firewall
+intro: "Learn how to control the domains and URLs that {% data variables.copilot.copilot_coding_agent %} can access."
+versions:
+  feature: copilot
+topics:
+  - Copilot
+type: how_to
+---
+
+> [!NOTE]
+> {% data reusables.copilot.coding-agent.preview-note-text %}
+>
+> For more information about {% data variables.copilot.copilot_coding_agent %}, see [AUTOTITLE](/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot).
+
+## Overview
+
+By default, {% data variables.product.prodname_copilot_short %}'s access to the internet is limited by a firewall.
+
+Limiting access to the internet helps to manage data exfiltration risks, where surprising behavior from {% data variables.product.prodname_copilot_short %}, or malicious instructions given to it, could lead to code or other sensitive information being leaked to remote locations.
+
+The default firewall rules allow access to a number of hosts that {% data variables.product.prodname_copilot_short %} uses to interact with {% data variables.product.github %} or to download dependencies.
+
+If {% data variables.product.prodname_copilot_short %} tries to make a request which is blocked by the firewall, a warning is added to the pull request body (if {% data variables.product.prodname_copilot_short %} is creating a pull request for the first time) or to a comment (if {% data variables.product.prodname_copilot_short %} is responding to a pull request comment). The warning shows the blocked address and the command that tried to make the request.
+
+![Screenshot of a warning from {% data variables.product.prodname_copilot_short %} about being blocked by the firewall.](/assets/images/help/copilot/coding-agent/firewall-warning.png)
+
+## Allowlisting additional hosts in the agent's firewall
+
+You can allowlist additional addresses in the agent's firewall by setting the `COPILOT_AGENT_FIREWALL_ALLOW_LIST_ADDITIONS` {% data variables.product.prodname_actions %} variable to a comma-separated list. In that list, you can include:
+
+* **Domains** (for example, `packages.contoso.corp`), in which case traffic will be allowed to that domain and any subdomains.
+
+  **Example**: `packages.contoso.corp` would allow traffic to `packages.contoso.corp` and `prod.packages.contoso.corp`, but not `artifacts.contoso.corp`.
+
+* **URLs** (for example, `https://packages.contoso.corp/project-1/`), in which case traffic will only be allowed on the specified scheme (`https`) and host (`packages.contoso.corp`), and limited to the specified path and descendant paths.
+
+  **Example**: `https://packages.contoso.corp/project-1/` would allow traffic to `https://packages.contoso.corp/project-1/` and `https://packages.contoso.corp/project-1/tags/latest`, but not `https://packages.consoto.corp/project-2`, `ftp://packages.contoso.corp` or `https://artifacts.contoso.corp`.
+
+## Overwriting the firewall allowlist
+
+By default, the firewall allows access to a number of hosts that are commonly used to download dependencies or that {% data variables.product.prodname_copilot_short %} uses to interact with {% data variables.product.github %}.
+
+To completely clear this default allowlist and start again from scratch, set the `COPILOT_AGENT_FIREWALL_ALLOW_LIST` {% data variables.product.prodname_actions %} variable to a comma-separated list of hosts.
+
+For example, to _only_ allow access to `packages.contoso.corp` and `artifacts.contoso.corp`, set the `COPILOT_AGENT_FIREWALL_ALLOW_LIST` variable to `packages.contoso.corp,artifacts.contoso.corp`.
+
+### Disabling the firewall
+
+> [!WARNING]
+> Disabling the firewall will allow {% data variables.product.prodname_copilot_short %} to connect to any host, increasing risks of exfiltration of code or other sensitive information.
+
+The firewall is enabled by default. To disable the firewall, set the `COPILOT_AGENT_FIREWALL_ENABLED` {% data variables.product.prodname_actions %} variable to `false`.
+
+## Further reading
+
+* [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository)
+* [AUTOTITLE](/copilot/customizing-copilot/customizing-the-development-environment-for-copilot-coding-agent)

assets/images/help/copilot/coding-agent/copilot-finished-work.png

@@ -0,0 +1,111 @@
+---
+title: Customizing the development environment for Copilot coding agent
+shortTitle: Customize the agent environment
+intro: "Learn how to customize {% data variables.product.prodname_copilot %}'s development environment with additional tools."
+versions:
+  feature: copilot
+topics:
+  - Copilot
+type: how_to
+---
+
+> [!NOTE]
+> {% data reusables.copilot.coding-agent.preview-note-text %}
+>
+> For more information about {% data variables.copilot.copilot_coding_agent %}, see [AUTOTITLE](/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot).
+
+## About customizing {% data variables.copilot.copilot_coding_agent %}'s development environment
+
+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.
+
+You can customize {% data variables.product.prodname_copilot_short %}'s environment by:
+
+* [Preinstalling tools or dependencies in {% data variables.product.prodname_copilot_short %}'s environment](#preinstalling-tools-or-dependencies-in-copilots-environment).
+* [Upgrading from standard {% data variables.product.prodname_dotcom %}-hosted {% data variables.product.prodname_actions %} runners to larger runners](#upgrading-to-larger-github-hosted-github-actions-runners).
+* [Disabling or customizing the agent's firewall](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
+
+## Preinstalling tools or dependencies in {% data variables.product.prodname_copilot_short %}'s environment
+
+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.
+
+{% 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.
+
+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.
+
+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).
+
+Here is a simple example of a `copilot-setup-steps.yml` file for a TypeScript project that clones the project, installs Node.js and downloads and caches the project's dependencies. You should customize this to fit your own project's language(s) and dependencies:
+
+```yaml copy
+name: "Copilot Setup Steps"
+
+# Allow testing of the setup steps from your repository's "Actions" tab.
+on: workflow_dispatch
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # 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.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: {% data reusables.actions.action-checkout %}
+
+      - name: Set up Node.js
+        uses: {% data reusables.actions.action-setup-node %}
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install JavaScript dependencies
+        run: npm ci
+```
+
+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.
+
+* `steps` (see above)
+* `permissions` (see above)
+* `runs-on` (see below)
+* `container `
+* `services`
+* `snapshot`
+* `timeout-minutes` (maximum value: `59`)
+
+For more information on these options, see [AUTOTITLE](/actions/writing-workflows/workflow-syntax-for-github-actions#jobs).
+
+Once you have created a `copilot-setup-steps.yml` file and merged it into your default branch, you can manually run the workflow from the repository's **Actions** tab to check that it works. For more information, see [AUTOTITLE](/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow).
+
+## Upgrading to larger {% data variables.product.prodname_dotcom %}-hosted {% data variables.product.prodname_actions %} runners
+
+By default, {% data variables.product.prodname_copilot_short %} works in a standard {% data variables.product.prodname_actions %} runner with limited resources.
+
+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).
+
+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.
+
+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).
+
+```yaml
+# ...
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-4-core
+    # ...
+```
+
+> [!NOTE]
+> * {% data variables.copilot.copilot_coding_agent %} is only compatible with Ubuntu x86 Linux runners. Runners with Windows, macOS or other operating systems are not supported.
+> * Self-hosted {% data variables.product.prodname_actions %} runners are not supported.
+
+## Further reading
+
+* [AUTOTITLE](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent)