Setup Guide Beginner

This guide walks you through enabling GitHub Copilot Coding Agent for your organization, configuring your repositories, setting up the environment file, and running your first autonomous task assignment.

Prerequisites

Before you can use the Coding Agent, make sure you have the following in place:

Enabling Copilot Coding Agent for Your Organization

Follow these steps to enable the Coding Agent at the organization level:

1. Navigate to Organization Settings

   Go to your organization's GitHub page, click Settings in the top navigation bar.

2. Open Copilot Settings

   In the left sidebar, click Copilot, then select Policies from the submenu.

3. Enable the Coding Agent

   Find the "Copilot Coding Agent" section and toggle it to Enabled. You can choose to enable it for all repositories or select specific ones.

4. Configure Permissions

   Set which members of the organization can assign issues to Copilot. Options include all members, specific teams, or only organization owners.

5. Save Changes

   Click Save to apply the settings. The Coding Agent will be available in the selected repositories within a few minutes.

github.com/orgs/{your-org}/settings/copilot/policies

# Look for:
# Copilot Coding Agent → Enabled
# Allowed repositories → All / Selected
# Allowed members → All / Specific teams

Repository Configuration

Each repository needs some basic configuration for the Coding Agent to work effectively:

1. Enable Copilot for the repository

   Go to the repository's Settings → Copilot and ensure Copilot access is enabled.

2. Ensure GitHub Actions is active

   The agent relies on GitHub Actions to run tests and validate its changes. Check Settings → Actions → General and confirm Actions are allowed.

3. Set up branch protection (recommended)

   Configure branch protection rules on your default branch to require PR reviews and passing status checks before merging. This ensures agent-generated PRs go through the same quality gates as human PRs.

Setting Up copilot-setup-steps.yml

The copilot-setup-steps.yml file tells the Coding Agent how to set up the development environment. It is a GitHub Actions workflow file that runs before the agent starts working on code. Place it in the .github/ directory of your repository.

name: "Copilot Setup Steps"

on: workflow_dispatch

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

Here is an example for a Python project:

name: "Copilot Setup Steps"

on: workflow_dispatch

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install -r requirements-dev.txt

      - name: Run migrations
        run: python manage.py migrate --settings=config.test

Configuring Allowed Tools and Permissions

You can control which tools and actions the Coding Agent is allowed to use within your repository:

Setting Up CI/CD Integration

The Coding Agent validates its changes by running your CI pipeline. For best results, ensure your CI workflow is configured to run on pull requests:

name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: npm run lint

Testing Your First Assignment

Now that everything is configured, let's test the setup with a simple task:

1. Create a simple issue

   Create a new issue with a well-defined, low-risk task. For example: "Add a getVersion() function to src/utils.ts that returns the version from package.json."

2. Assign it to Copilot

   In the issue's right sidebar, click Assignees and select Copilot from the list. Alternatively, comment @copilot on the issue.

3. Monitor progress

   Watch the issue for status updates. The agent will post comments showing its progress: reading the codebase, making changes, running tests.

4. Review the pull request

   Once the agent finishes, it will open a PR linked to the issue. Review the code changes, run additional checks if needed, and provide feedback.

5. Iterate or merge

   If the changes look good, approve and merge. If you need adjustments, leave review comments and the agent will attempt to address them.