# Grant a consumer access to a secret

Let workflow jobs, app deployments or another part of the platform read a secret, for every repository or one, with or without an expiry, and revoke it again.

Until a consumer is granted a secret, that consumer cannot read it. A grant is necessary, not
sufficient: a workflow job also needs the person who started the run to hold
`secrets:GetSecretValue` on the secret (see [Use a secret in a workflow](use-a-secret-in-a-workflow.md)).

| Consumer      | What reads with it                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `actions`     | Workflow jobs that list the secret under `secrets:`, and GitHub Actions syntax workflows that use `secrets.<NAME>`. |
| `deploy`      | App deployments, as environment variables bound on the app. Binding a secret on the app grants `deploy` by itself.  |
| `compute`     | Functions that bind the secret. Binding grants `compute` by itself.                                                 |
| `registry`    | Pull-through cache upstream logins.                                                                                 |
| `cli`, `code` | Accepted and listed; nothing on the platform reads with them today.                                                 |

Replace _5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e_ with the secret's id and
_2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b_ with a repository's id.

## Prerequisites

- Permission for `secrets:GrantSecret` on the secret to grant, `secrets:RevokeSecretGrant` to
  revoke, `secrets:ListSecretGrants` to list grants with their scope and expiry. In the console,
  also `secrets:ListSecrets` to open **Secrets**; without it the page says "You do not have
  permission to list secrets."

## Grant a consumer

**Console**
1. Open **Secrets** and choose the secret.
2. In its panel, under **Consumers**, choose **Grant** on the consumer's row.

The console grants every repository and sets no expiry. For one repository or an expiry, use the
CLI, the API or Terraform.

**CLI**
```sh
dcloud secrets secrets grant 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e --consumer actions \
  --repository-id 2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b --ttl-days 90
```

**API**
```http
POST /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e/grants
{ "consumer": "actions", "repositoryId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b", "ttlDays": 90 }
```

**Terraform**
```hcl
resource "dcloud_secret_grant" "ci" {
  secret_id     = dcloud_secret.stripe.id
  consumer      = "actions"
  repository_id = "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  ttl_days      = 90
}
```

`repositoryId` applies only to `actions`. Set it: a workflow names the secrets it wants in a file in
the repository, so an `actions` grant without it lets the workflows of every repository in the
organization read the secret. `ttlDays` (1 to 3650) makes the grant expire; an expired grant counts
as absent.

Granting the same consumer and repository again replaces the expiry; a re-grant without `ttlDays`
removes it. A grant for another repository is a grant of its own.

## Grant or revoke for many secrets

**Console**
1. Open **Secrets** and select the secrets' check boxes.
2. Choose **Grant consumer** or **Revoke consumer**.
3. For **Consumer**, choose the consumer.
4. Choose **Grant** or **Revoke**.

A revoke here removes the grant for every repository; repository-scoped grants stay.

**CLI**
```sh
dcloud secrets secrets bulk-grant --consumer deploy --ids 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e
```

**API**
```http
POST /secrets/api/secrets/bulk/grant
{ "ids": ["5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e"], "consumer": "deploy" }
```

`POST /secrets/api/secrets/bulk/revoke` takes `{ ids, consumer, repositoryId? }`.

**Terraform:** not available. Write one `dcloud_secret_grant` per secret.

At most 500 ids per call, each authorized and answered on its own; not atomic.

## Revoke a grant

**Console**
In the secret's panel, under **Consumers**, choose **Revoke** on the consumer's row. This removes
only the grant that covers every repository. A row also shows **Revoke** when the consumer holds
only repository-scoped grants; those stay, and so does the button. Revoke them with the CLI, the
API or Terraform.

**CLI**
```sh
dcloud secrets secrets revoke-grant 5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e --consumer actions \
  --repository-id 2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b
```

**API**
```http
DELETE /secrets/api/secrets/5b8c1d2e-3f4a-4b6c-8d7e-9f0a1b2c3d4e/grants
{ "consumer": "actions", "repositoryId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b" }
```

**Terraform**
Remove the `dcloud_secret_grant` and run `terraform apply`.

The consumer is named in the body. Without `repositoryId`, the every-repository grant is revoked,
not the repository-scoped ones. The answer is `200` whether or not such a grant existed.

## Refusals

- `400` "A repository scope applies only to the actions consumer".
- `404` "No such repository", for a repository not in your organization.

## Related

- [Use a secret in a workflow](use-a-secret-in-a-workflow.md)
- [Use a secret in a deployment](use-a-secret-in-a-deployment.md)
- `secrets.secrets.grant` · `secrets.secrets.revoke-grant` · `dcloud_secret_grant`
