# Set a variable

Give GitHub-syntax workflows plain configuration values as vars.NAME, for the organization, a repository or an environment.

A workflow under `.github/workflows/` reads a variable as `${{ vars.NAME }}`. A variable is plain
text: it is shown to whoever may list variables and is not masked in logs, so keep anything secret
in a secret instead (see [Give a job a secret](give-a-job-a-secret.md)). Workflows in the native
format have no `vars`.

Replace repo-id with the repository's id, production with an environment's name and
DEPLOY_REGION with the variable's name.

## Prerequisites

- `ci:PutVariable` to create or change a variable, `ci:ListVariables` to list them,
  `ci:DeleteVariable` to delete one. Organization variables are checked on all of CI
  (`rn:ews::<organization id>:ci:*`); repository and environment variables on the repository
  (`rn:ews::<organization id>:ci:repository/<repository id>`).
- For an environment variable, the environment exists (see
  [Protect a deployment with an environment](protect-a-deployment.md)). Setting a variable does
  not create it.

## Set the variable

A name has letters, digits and `_`, does not start with a digit or with `GITHUB_`, and has up to 100
characters; it is stored upper-case. A value has up to 48 KiB.

The console has no page for variables.

**CLI**
```sh
# for every repository of the organization
dcloud ci variables put-org DEPLOY_REGION --value de1
# for one repository
dcloud ci variables put repo-id DEPLOY_REGION --value de1
# for one environment of a repository
dcloud ci variables put-environment repo-id production DEPLOY_REGION --value de1
```

**API**
```http
PUT /ci/api/repositories/repo-id/variables/DEPLOY_REGION
{ "value": "de1" }
```

For the organization, `PUT /ci/api/variables/DEPLOY_REGION`; for an environment,
`PUT /ci/api/repositories/repo-id/environments/production/variables/DEPLOY_REGION`.

## Result

The answer is `200` with `{ name, value, updatedAt }`, whether the variable was created or changed.
From the next run on, a job reads it. When the same name is set at several levels, a job in an
environment reads the environment's value, then the repository's, then the organization's.

- `400` with a message naming the rule, such as `names may not start with GITHUB_`, when the name
  breaks it.
- `400` with `issues` when the body has no string `value` or the value is longer than 48 KiB.
- `404` "No such environment" when the repository has no environment of that name; `404` "Not
  found" when the repository is not in your organization.

## List or delete variables

```sh
dcloud ci variables list repo-id
dcloud ci variables delete repo-id DEPLOY_REGION
```

A repository's list holds its own variables, not the organization's. Deleting a name that is not
there answers `404`. Deleting an environment deletes its variables with it.

## Related

- [Protect a deployment with an environment](protect-a-deployment.md)
- [Run GitHub Actions workflows](run-github-actions-workflows.md)
- `ci.variables.put` · `dcloud ci variables put`
