Environment customization for headless mode (Copilot coding agent)

[arnaudlh]

Context

Git-Ape runs in two modes: Interactive (VS Code / Copilot Chat, backed by .devcontainer/devcontainer.json) and Headless (Copilot coding agent / GitHub Actions). Today the .devcontainer/ tree has a full toolchain (Azure CLI, PowerShell, Checkov, PSRule, ARM-TTK, Azure MCP VS Code extension, etc.), but the headless coding-agent environment has no equivalent customization file. When the coding agent picks up an issue, it boots a vanilla Ubuntu runner with no Azure tooling, no MCP server, and default egress firewall rules.

Per .github/agents/git-ape.agent.md the agent is expected to:

• detect headless mode via GITHUB_ACTIONS / CI
• authenticate via OIDC (azure/login)
• run az commands (MCP tools are noted as "NOT available" — we should change that)
• generate & commit ARM templates / what-if

None of that works without a customized environment.

Goal

Add a .github/workflows/copilot-setup-steps.yml (Copilot coding agent pre-run hook) plus a firewall allow-list so the coding agent has parity with the devcontainer.

Proposed changes

1. copilot-setup-steps.yml — install the toolchain

Mirror what .devcontainer/post-create.sh installs today, so headless runs have the same validators.

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # required for OIDC later in the agent's session
    steps:
      - uses: actions/checkout@v4

      - name: Install Azure CLI + Bicep
        run: |
          curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
          az bicep install
          az bicep version

      - name: Setup PowerShell + Azure PSRule + ARM-TTK
        shell: bash
        run: |
          sudo apt-get update && sudo apt-get install -y powershell
          pwsh -Command "Install-Module -Name PSRule.Rules.Azure -Scope CurrentUser -Force"
          git clone --depth 1 https://github.com/Azure/arm-ttk.git "$HOME/.arm-ttk"
          mkdir -p "$HOME/.config/powershell"
          echo 'Import-Module $HOME/.arm-ttk/arm-ttk/arm-ttk.psd1' \
            >> "$HOME/.config/powershell/Microsoft.PowerShell_profile.ps1"

      - name: Setup Python 3.12 + Checkov
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install --user checkov

      - name: Setup Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Azure MCP server (headless)
        run: |
          npm install -g @azure/mcp@latest
          azmcp --version

      - name: Verify tools
        run: |
          az version
          checkov --version
          pwsh -Command "Get-Module PSRule.Rules.Azure -ListAvailable"

2. Firewall / egress allow-list

GitHub-hosted runners used by the Copilot coding agent support an allow-list of outbound domains. Add the following (either via the repo's Copilot coding agent settings UI or a committed config) so Azure docs, ARM schemas, and MCP resource lookups succeed:

# Microsoft / Azure docs & learn
*.microsoft.com
*.learn.microsoft.com
learn.microsoft.com
docs.microsoft.com

# Azure management & identity planes
management.azure.com
login.microsoftonline.com
graph.microsoft.com
*.azure.com

# ARM template schemas & samples
schema.management.azure.com
raw.githubusercontent.com
github.com

# Azure CLI / Bicep / PSRule installers & telemetry
aka.ms
azcliextensionsync.blob.core.windows.net
azclijlts.blob.core.windows.net
biceptypes.blob.core.windows.net
*.blob.core.windows.net

# Azure MCP server
*.mcp.azure.com
mcp.azure.com

# Package registries (already in GitHub default allow-list, listed for clarity)
registry.npmjs.org
pypi.org
files.pythonhosted.org
ghcr.io

Note: evaluate trimming *.blob.core.windows.net to the specific subdomains actually used, since it's broad.

3. Azure MCP server — make it available in headless mode

Today azure-resource-deployer.agent.md says "MCP tools are NOT available — use Azure CLI commands exclusively" in headless mode. With @azure/mcp installed in step 1 + OIDC login, MCP can be started as a sidecar. Proposed config:

{
  "servers": {
    "azure": {
      "command": "azmcp",
      "args": ["server", "start", "--mode", "namespace", "--read-only", "false"],
      "env": {
        "AZURE_MCP_COLLECT_TELEMETRY": "false"
      }
    }
  }
}

Then update the agent docs (.github/agents/git-ape.agent.md, azure-resource-deployer.agent.md, azure-requirements-gatherer.agent.md) to remove the "MCP tools are NOT available in headless mode" caveat.

4. Anything else worth adding?

• jq, yq — used across scripts like .github/skills/azure-drift-detector/ (parses JSON state files).
• sqlcmd — used by .github/skills/azure-integration-tester/scripts/test-database.sh.
• mermaid-cli (@mermaid-js/mermaid-cli) — for architecture diagram rendering in the template generator.
• gh CLI — for PR comments & workflow dispatch from the agent.
• Env vars the agent expects: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID (consumed by azure/login@v2 in the example workflows).
• Default region / environment defaults for headless runs when the issue body is missing them (currently hardcoded to East US / dev in the requirements gatherer — surface as repo variables: GIT_APE_DEFAULT_REGION, GIT_APE_DEFAULT_ENV).
• Caching: cache ~/.azure, PowerShell modules, and pip to speed up each agent session.

Acceptance criteria

• .github/workflows/copilot-setup-steps.yml exists and is invoked by the Copilot coding agent before it starts work.
• Firewall allow-list applied (via repo Copilot settings) covering Microsoft/Azure domains.
• Azure MCP server runs successfully in a headless coding-agent session (verified by a test issue that asks the agent to run az account show + an MCP resource lookup).
• Agent docs updated to reflect MCP availability in headless mode.
• docs/CODESPACES.md gains a sibling doc docs/HEADLESS-ENV.md describing the coding-agent environment and how to customize it.

References

• .devcontainer/devcontainer.json
• .devcontainer/post-create.sh
• .github/agents/git-ape.agent.md
• .github/agents/azure-resource-deployer.agent.md
• GitHub docs: Customize the Copilot coding agent environment