GitHub Copilot Agent Environment Setup

This document describes the development environment configuration for GitHub Copilot Agent in the llm-proxy project.

Overview

The GitHub Copilot Agent environment has been configured to provide:

  • Optimized development workflow matching our CI/CD pipelines
  • Network access to GitHub documentation and APIs
  • Efficient caching for faster development cycles
  • Consistent tooling and dependencies

Environment Configuration

Firewall Configuration

The Copilot Agent firewall has been configured to allow access to essential GitHub services:

COPILOT_AGENT_FIREWALL_ALLOW_LIST_ADDITIONS: "https://docs.github.com,https://api.github.com,https://raw.githubusercontent.com"

This configuration allows the agent to:

  • ✅ Access GitHub documentation for research and guidance
  • ✅ Interact with GitHub APIs for repository operations
  • ✅ Fetch raw content from GitHub repositories

Development Environment

The environment mirrors our existing GitHub Actions workflows with:

  • Go Version: 1.23 (matches build.yml, test.yml, lint.yml)
  • Node.js Version: 20 (for frontend tooling)
  • OS: Ubuntu Latest (consistent with CI/CD)
  • Caching: Enabled for Go modules, build cache, and development tools
  • Workflow: .github/workflows/copilot-setup-steps.yml

Available Tools

The environment includes all development tools specified in our Makefile:

  • golangci-lint for code linting
  • swag for API documentation generation
  • godoc for Go documentation
  • mockgen for test mocks

Usage

Manual Trigger

The Copilot Agent environment can be manually set up using the workflow dispatch:

  1. Go to the Actions tab in the repository
  2. Select “Copilot Setup Steps” workflow
  3. Click “Run workflow”
  4. Optionally provide a task description

Automatic Setup

The environment setup runs automatically when:

  • A Copilot Agent task is assigned
  • Development environment validation is needed

Validation

The environment includes comprehensive validation:

  • Network Connectivity: Verifies access to whitelisted domains
  • Tool Availability: Confirms all required development tools are installed
  • Build Verification: Ensures the project builds successfully
  • Test Execution: Runs the full test suite
  • Code Quality: Performs linting and formatting checks

Cache Strategy

The environment uses multi-level caching for optimal performance:

  1. Go Module Cache: Caches downloaded dependencies
  2. Build Cache: Caches compiled artifacts
  3. Tool Cache: Caches development tools
  4. Test Results Cache: Caches test outputs and coverage reports

Cache keys are prefixed with copilot-agent for easy identification and management.

Environment Variables

Core Configuration

  • GO_VERSION: Go language version
  • NODE_VERSION: Node.js version for tooling
  • CACHE_KEY_PREFIX: Cache identification prefix

Security Configuration

  • COPILOT_AGENT_FIREWALL_ALLOW_LIST_ADDITIONS: Network access whitelist

Troubleshooting

Network Access Issues

If the Copilot Agent reports network access issues:

  1. Verify the firewall allowlist includes required domains
  2. Check the environment validation logs
  3. Ensure the workflow has necessary permissions

Build Issues

If builds fail in the Copilot Agent environment:

  1. Compare with CI/CD workflow configurations
  2. Check cache status and clear if necessary
  3. Verify Go and Node.js versions match specifications

Performance Issues

If the environment is slow:

  1. Check cache hit rates in workflow logs
  2. Verify concurrent job limitations
  3. Review timeout configurations

Integration with Existing Workflows

The Copilot Agent environment is designed to complement, not replace, existing workflows:

  • build.yml: Build validation and binary creation
  • test.yml: Comprehensive testing (unit and integration)
  • lint.yml: Code quality and formatting
  • docker.yml: Container image building and publishing

The agent environment provides a development-focused setup that mirrors these production workflows while optimizing for interactive development tasks.

Repository Variables

For organization-wide configuration, set these GitHub Actions variables:

# Required for all repositories using Copilot Agent
COPILOT_AGENT_FIREWALL_ALLOW_LIST_ADDITIONS: "https://docs.github.com,https://api.github.com,https://raw.githubusercontent.com"

# Optional: Disable firewall completely (NOT RECOMMENDED for production)
# COPILOT_AGENT_FIREWALL_ENABLED: false

# Optional: Complete firewall override (replaces default allowlist)
# COPILOT_AGENT_FIREWALL_ALLOW_LIST: "custom.domain.com,another.domain.com"

Security Considerations

  • The firewall allowlist is limited to essential GitHub services
  • No external domains beyond GitHub are included by default
  • Full firewall bypass is NOT enabled for security reasons
  • All network access is logged and auditable through workflow runs

Future Enhancements

Potential improvements to consider:

  • Dynamic environment scaling based on task complexity
  • Integration with code coverage reporting
  • Custom toolchain support for specific project types
  • Enhanced caching strategies for monorepo structures