---
title: "corestack_environment_registry_secret_set"
url: https://docs.corefinity.com/mcp/tools/corestack_environment_registry_secret_set
type: tool
last_updated: 2026-11-13
feature: registry-secrets
related:
  - https://docs.corefinity.com/guides/sites/code-and-deployments/registry-secrets.md
---
# corestack_environment_registry_secret_set

**Set a CoreStack Enterprise registry credential.** Add or change a Composer registry credential a CoreStack Enterprise environment's builds install with (secret_id changes one), and optionally verify it with the registry. The username and secret are write-only. Scope: write.

- Scope: `write`
- Runs as a task: no

## When to use it

Add a Composer registry credential to a CoreStack Enterprise environment, so its builds can install packages from a
private registry, or change one: the environment page's "Composer registries" card's Save. Without `secret_id` it adds
one (`label`, `registry`, `auth_type`, `secret`, and `username` for http-basic); with `secret_id` it changes only what
you send. A change of host, auth type, username or secret clears the credential's verification.

Saved credentials are used by the environment's builds on build pipeline version 2, and only once Composer registry
credentials are switched on for that environment; until then they are kept, and builds do not receive them. They are
given to a build for that build only and removed after it.

A host the project's own `auth.json` also signs in to: Composer 2.10 and later use the saved credential for it, older
Composer versions the project's. One in COMPOSER_HOME's `auth.json`: the saved credential. The build log says when
either happens.

Send `verify: true` to ask the registry once, after saving, whether it accepts the credentials (`verified` and
`message` in the answer). `secret_id` with `verify: true` and nothing else verifies a saved credential. The registry is
asked over HTTPS only, at a public address, and a redirect is reported, never followed.

The username and the secret are write-only: never answered and never kept in the MCP audit. Never ask the person to
paste a secret into the chat; they can also add it on the card.

This is for CoreStack Enterprise environments only. A CoreStack or CoreCluster site uses
`corestack_deployments_secret_set`, by `site_id`.

The public API does the same with the same checks, refusals and scope: `POST` and `PUT
/api/corestack/environments/{environment}/deploy-secrets[/{secret}]`, and `POST …/{secret}/verify`.

## Inputs

- `enterprise_env_id` (integer, ≥ 1, required)
- `secret_id` (integer, ≥ 1): change this credential; leave out to add one.
- `label` (string): a name for it, up to 255 characters.
- `registry` (string): the registry's host, with a port if it needs one; no scheme or path.
- `auth_type` (string, one of `http-basic`, `bearer`, `github-oauth`, `gitlab-token`)
- `username` (string): http-basic only. Write-only.
- `secret` (string): the password or token. Write-only.
- `verify` (boolean): after saving, ask the registry once.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "auth_type": {
      "enum": [
        "http-basic",
        "bearer",
        "github-oauth",
        "gitlab-token"
      ],
      "type": "string"
    },
    "enterprise_env_id": {
      "description": "A CoreStack Enterprise environment's id; for a CoreStack or CoreCluster site use corestack_deployments_secrets_list by site_id.",
      "minimum": 1,
      "type": "integer"
    },
    "label": {
      "description": "A name for it.",
      "type": "string"
    },
    "registry": {
      "description": "The registry's host, with a port if it needs one; no scheme or path.",
      "type": "string"
    },
    "secret": {
      "description": "The password or token.",
      "type": "string"
    },
    "secret_id": {
      "description": "Change this credential (corestack_environment_registry_secret_list); leave out to add one.",
      "minimum": 1,
      "type": "integer"
    },
    "username": {
      "description": "http-basic only.",
      "type": "string"
    },
    "verify": {
      "description": "After saving, ask the registry once whether it accepts these credentials.",
      "type": "boolean"
    }
  },
  "required": [
    "enterprise_env_id"
  ],
  "type": "object"
}
```

## Refusals

- `exists`: a credential for that host is already saved; change it with its `secret_id` (in `details.id`).
- `secret_invalid` (with the field): a value is not valid (the host, the auth type, the secret's characters, a missing
  username for http-basic), the registry's address is not public, the environment already holds the most credentials
  it can, or its credentials together would be too large for a build; the message says which.
- `invalid_arguments` (field `secret_id`): `secret_id` with nothing to change and no `verify: true`. Also (field
  `enterprise_env_id`) a CoreStack or CoreCluster environment; use `corestack_deployments_secret_set` by `site_id`.
- `forbidden`: the person's role lacks the Edit Environment Deployment Pipeline permission. The message names it and
  says an owner of the company can grant it in Roles; `details.permission` is `editEnvironmentDeploymentPipeline`.
  Nothing is changed.
- `tenant_mismatch` (also for a `secret_id` that is not this environment's), `pin_refused`, `rate_limited` (20 changes a
  minute per person, shared with the public API), and the refusals every tool can answer: `scope_required`,
  `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_environment_registry_secret_set",
  "arguments": {
    "enterprise_env_id": 1530,
    "label": "Private packages",
    "registry": "repo.example.com",
    "auth_type": "http-basic",
    "username": "<the registry username>",
    "secret": "<the registry password or token>",
    "verify": true
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_environment_registry_secret_set with enterprise_env_id 1530, label Private packages, registry repo.example.com, auth_type http-basic, username <the registry username>, secret <the registry password or token>, verify true. (Set a CoreStack Enterprise registry credential.) Tell me what it returned.
```

## The same task elsewhere

- Guide: [Private registries](https://docs.corefinity.com/guides/sites/code-and-deployments/registry-secrets.md)
