github / github/copilot-cli

Feature: Support .env file loading and per-agent environment variable scoping

Open
#2,879 0 comments 1 reaction 0 assignees View on GitHub
area:agents area:configuration
Dominant language
Shell
Stars
11.2k
Forks
1.9k
Avg merge
14h 16m
Merged PRs (30d)
6

Description

## Summary

Copilot CLI should support automatic `.env` file loading from the project root, and allow agents to declare environment variables scoped to their configuration — so that different agents can have isolated secrets without polluting the global shell environment.

## Problem

When building custom agents with Copilot CLI that use MCP servers requiring credentials (e.g., the Slack MCP server needing `SLACK_USER_OAUTH_TOKEN`), all credentials must be exported in `~/.bashrc` or equivalent shell profile because:

1. Copilot CLI does not load `.env` files from the project directory
2. Agent `env:` blocks in MCP config use `${VAR}` syntax, which resolves from the shell environment only
3. There is no way to scope environment variables per-agent

### No project-scoped configuration
Secrets for one project leak into every shell session. A `.env` file at the repo root (gitignored) is the standard pattern for project-scoped secrets in every major framework (Node.js, Python, Ruby, Go). Copilot CLI is the only tool in my workflow that forces secrets into the global shell profile.

### No secret isolation between agents
If you have multiple agents, each needing different MCP servers, every agent currently sees every exported variable in the shell. Per-agent env scoping would follow the principle of least privilege — an agent that only needs a Slack token should not have access to other API keys.

### Onboarding friction
When sharing a multi-agent repo, contributors need to manually add exports to their shell profile. A `.env.example` + `.env` pattern is universally understood and self-documenting.

## Proposed Solution

### Part 1: `.env` file loading (minimum viable)
- On startup, if a `.env` file exists in the project root (or git root), load it into the environment before resolving `${VAR}` references in agent/MCP configs
- Respect `.env` files at both user level (`~/.copilot/.env`) and project level (`.env` in git root), with project-level taking precedence

### Part 2: Per-agent environment scoping (stretch goal)
Allow agents to declare their own env vars or reference a specific `.env` file:

```yaml
---
name: slack-agent
env:
SLACK_USER_OAUTH_TOKEN: ${SLACK_USER_OAUTH_TOKEN}
env_file: .env.slack
---
```

This would restrict which variables are available to that agent's MCP server subprocesses.

## Current Workaround

Export all variables in `~/.bashrc` and maintain a `.env.example` in the repo for documentation only:

```bash
# ~/.bashrc
export SLACK_USER_OAUTH_TOKEN=xoxp-...
```

This works but violates standard project-scoping conventions.

## Related Issues

- #1232 — `${}` env var expansion in MCP config (implemented, but only reads from shell env)
- #1354 — Per-agent model selection (similar theme of per-agent configuration)

Contributor guide

Open the contributing guide

Research direction

The payload names startup environment initialization and `${VAR}` resolution in agent and MCP configuration, but no implementation files or tests. Start by tracing those entry points and how project and user configuration are discovered. Done should include the requested `.env` precedence behavior and a clear design or implementation for per-agent scoping, with coverage for both parts.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell, yaml
Domain
cli, developer-experience, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.