|
| 1 | +--- |
| 2 | +title: Configure secrets and variables for Copilot cloud agent |
| 3 | +shortTitle: Configure secrets and variables |
| 4 | +intro: 'Securely pass secrets and variables to {% data variables.copilot.copilot_cloud_agent %} so it can access private resources and configure MCP servers.' |
| 5 | +versions: |
| 6 | + feature: copilot |
| 7 | +contentType: how-tos |
| 8 | +category: |
| 9 | + - Configure Copilot |
| 10 | +--- |
| 11 | + |
| 12 | +## About secrets and variables for {% data variables.copilot.copilot_cloud_agent %} |
| 13 | + |
| 14 | +When you delegate a task to {% data variables.copilot.copilot_cloud_agent %}, it works in its own ephemeral development environment, powered by {% data variables.product.prodname_actions %}. You may want to pass secrets and variables to the agent to: |
| 15 | + |
| 16 | +* Give {% data variables.product.prodname_copilot_short %} access to private resources, such as internal package registries, when it builds, tests, or validates your code in the agent's environment. |
| 17 | +* Configure MCP servers, by passing API keys, tokens, or other configuration to the servers. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp). |
| 18 | +* Set environment variables that are available to scripts and tools that {% data variables.product.prodname_copilot_short %} runs in its environment, including in `copilot-setup-steps.yml`. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment). |
| 19 | + |
| 20 | +{% data variables.copilot.copilot_cloud_agent %} has its own dedicated **Agents** secrets and variables, alongside the existing **Actions**, **Codespaces**, and **Dependabot** types. You can configure Agents secrets and variables at: |
| 21 | + |
| 22 | +* The **organization level**, so a single secret or variable can be shared across any or all repositories in your organization. |
| 23 | +* The **repository level**, for configuration that only applies to a single repository. |
| 24 | + |
| 25 | +Variables and secrets that you configure are exposed to {% data variables.product.prodname_copilot_short %} as environment variables, except secrets and variables prefixed with `COPILOT_MCP_`, which are only available to MCP servers. |
| 26 | + |
| 27 | +> [!NOTE] |
| 28 | +> If you previously configured secrets or variables in the `copilot` environment in a repository's {% data variables.product.prodname_actions %} settings, those secrets and variables have been automatically migrated to the new repository-level **Agents** type. You don't need to take any action, and you can manage them from the new location going forward. |
| 29 | +
|
| 30 | +## Configuring repository-level secrets and variables |
| 31 | + |
| 32 | +You must be a repository administrator to configure Agents secrets and variables for a repository. |
| 33 | + |
| 34 | +{% data reusables.repositories.navigate-to-repo %} |
| 35 | +{% data reusables.repositories.sidebar-settings %} |
| 36 | +1. In the "Security" section of the sidebar, click **Secrets and variables**, then click **Agents**. |
| 37 | +1. To add a secret, click the **Secrets** tab, then click **New repository secret**. To add a variable, click the **Variables** tab, then click **New repository variable**. |
| 38 | +1. Fill in the "Name" and "Value" (or "Secret") fields, and then click **Add secret** or **Add variable**. |
| 39 | + |
| 40 | +## Configuring organization-level secrets and variables |
| 41 | + |
| 42 | +You must be an organization owner to configure Agents secrets and variables for an organization. |
| 43 | + |
| 44 | +{% data reusables.organizations.navigate-to-org %} |
| 45 | +{% data reusables.organizations.org_settings %} |
| 46 | +1. In the "Security" section of the sidebar, click **Secrets and variables**, then click **Agents**. |
| 47 | +1. To add a secret, click the **Secrets** tab, then click **New organization secret**. To add a variable, click the **Variables** tab, then click **New organization variable**. |
| 48 | +1. Fill in the "Name" and "Value" (or "Secret") fields. |
| 49 | +1. Under "Repository access", choose which repositories in your organization can access the secret or variable: |
| 50 | + |
| 51 | + * **All repositories**: any repository in the organization can access the secret or variable. |
| 52 | + * **Private repositories**: any private or internal repository in the organization can access the secret or variable. |
| 53 | + * **Selected repositories**: only the repositories you specify can access the secret or variable. |
| 54 | + |
| 55 | +1. Click **Add secret** or **Add variable**. |
| 56 | + |
| 57 | +## Using secrets and variables |
| 58 | + |
| 59 | +Once configured, Agents secrets and variables are automatically available to {% data variables.copilot.copilot_cloud_agent %} when it works on a task in the repository. They are exposed to the agent as environment variables in its development environment, so they can be used by scripts and tools that {% data variables.product.prodname_copilot_short %} runs, including by your `copilot-setup-steps.yml` workflow. |
| 60 | + |
| 61 | +Secret values are masked in {% data variables.copilot.copilot_cloud_agent %} session logs. |
| 62 | + |
| 63 | +> [!NOTE] |
| 64 | +> {% data variables.copilot.copilot_cloud_agent %} does not have access to {% data variables.product.prodname_actions %}, {% data variables.product.prodname_codespaces %}, or {% data variables.product.prodname_dependabot %} secrets and variables. Only Agents secrets and variables are passed to the agent. |
| 65 | +
|
| 66 | +## Naming requirements for secrets and variables |
| 67 | + |
| 68 | +Names must: |
| 69 | + |
| 70 | +* Only contain alphanumeric characters (`[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed. |
| 71 | +* Not start with the `GITHUB_` prefix. |
| 72 | +* Not start with a number. |
| 73 | + |
| 74 | +Names are case-insensitive. Lowercase letters are converted to uppercase. Names must be unique at the level at which they are created. |
| 75 | + |
| 76 | +If a variable or secret with the same name exists at multiple levels, the value at the lowest level takes precedence. For example, a repository-level secret will override an organization-level secret with the same name. |
| 77 | + |
| 78 | +For secrets and variables that you want to pass to MCP servers, the name must begin with the prefix `COPILOT_MCP_`. Only Agents secrets and variables with this prefix are available to your MCP configuration. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp). |
| 79 | + |
| 80 | +## Further reading |
| 81 | + |
| 82 | +* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment) |
| 83 | +* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp) |
0 commit comments