Customizing the development environment for Copilot coding agent

About customizing Copilot 코딩 에이전트's development environment

While working on a task, Copilot has access to its own ephemeral development environment, powered by GitHub Actions, where it can explore your code, make changes, execute automated tests and linters and more.

You can customize Copilot's environment to:

• Preinstall tools or dependencies in Copilot's environment.
• Upgrade from standard GitHub-hosted GitHub Actions runners to larger runners.
• Enable Git Large File Storage (LFS)
• Disable or customize the agent's firewall.

Preinstalling tools or dependencies in Copilot's environment

In its ephemeral development environment, Copilot 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.

Copilot 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 Copilot's environment before the agent starts by creating a special GitHub Actions workflow file, located at .github/workflows/copilot-setup-steps.yml within your repository.

A copilot-setup-steps.yml file looks like a normal GitHub Actions workflow file, but must contain a single copilot-setup-steps job. This job will be executed in GitHub Actions before Copilot starts working. For more information on GitHub Actions workflow files, see 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:

name: "Copilot Setup Steps"

# Automatically run the setup steps when they are changed to allow for easy validation, and
# allow manual testing through the repository's "Actions" tab
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

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: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install JavaScript dependencies
        run: npm ci

name: "Copilot Setup Steps"

# Automatically run the setup steps when they are changed to allow for easy validation, and
# allow manual testing through the repository's "Actions" tab
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

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: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        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 GitHub Actions에 대한 워크플로 구문.

Your copilot-setup-steps.yml file will automatically be run as a normal GitHub Actions workflow when changes are made, so you can see if it runs successfully. This will show alongside other checks in a pull request where you create or modify the file.

Once you have merged the yml file into your default branch, you can manually run the workflow from the repository's Actions tab at any time to check that everything works as expected. For more information, see 워크플로 수동 실행.

Upgrading to larger GitHub-hosted GitHub Actions runners

By default, Copilot works in a standard GitHub 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 대규모 실행기 정보.

Before Copilot can use larger runners, you must first add one or more larger runners and then configure your repository to use them. See 대형 실행기 관리하기. Once you have done this, you can use the copilot-setup-steps.yml file to tell Copilot 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 Copilot to use. For more information on specifying larger runners with runs-on, see 더 큰 실행기에서 작업 실행.

# ...

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-4-core
    # ...

Enabling Git Large File Storage (LFS)

If you use Git Large File Storage (LFS) to store large files in your repository, you will need to customize Copilot's environment to install Git LFS and fetch LFS objects.

To enable Git LFS, add a actions/checkout step to your copilot-setup-steps job with the lfs option set to true.

# ...

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for actions/checkout
    steps:
      - uses: actions/checkout@v4
        with:
          lfs: true

# ...

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for actions/checkout
    steps:
      - uses: actions/checkout@v4
        with:
          lfs: true

Further reading

• Customizing or disabling the firewall for Copilot coding agent