# Secrets and variables

Workflows read credentials from **secrets** and plain configuration from
**variables**, as on GitHub: `${{ secrets.NPM_TOKEN }}` and
`${{ vars.NODE_VERSION }}`. You can keep them on a repository or on an
organization, where they can reach many of its repositories.

Every job of a workflow receives them, on GitCafe-hosted runners and on
[self-hosted runners](https://git.cafe/docs/ci/self-hosted-runners.md) alike.

## Secrets

A secret's value is encrypted when you save it and can't be read back, by you
or anyone else; GitCafe decrypts it only to hand it to a job. Lists show only
the names of secrets and when they last changed. The runner masks secret
values in job logs.

To add or replace a repository secret, open the repository's **Settings →
Secrets and variables**, choose **New secret**, and enter its name and value.
To change a value, choose **Update** and enter the new value. You need to be a
repository admin.

```sh
cafe ci secret set NPM_TOKEN --env NPM_TOKEN   # from an environment variable
cafe ci secret set DEPLOY_KEY < deploy_key      # from stdin
cafe ci secret list
cafe ci secret delete NPM_TOKEN --yes
```

`--body VALUE` also works, but leaves the value in your shell history. A
value read from stdin loses one trailing newline. The CLI never prints a
value.

## Variables

Variables are stored in plain text, and admins can read their values in
**Settings → Secrets and variables → Variables** or with the CLI. Don't use
them for anything you would put in a secret.

```sh
cafe ci variable set NODE_VERSION --body 22
cafe ci variable list
cafe ci variable delete NODE_VERSION --yes
```

## Names and values

- Names may contain letters, digits and underscores, and may not start with a
  digit or with `GITHUB_`.
- Names are not case-sensitive: GitCafe saves them in upper case, so
  `npm_token` and `NPM_TOKEN` are the same secret. Use any case in workflows.
- A value can't be empty and can be at most 48 KB.
- A repository can have up to 100 secrets and 500 variables; an organization
  up to 1,000 of each.

## Organization secrets and variables

Organization owners and admins manage them in the organization's **Settings
→ Secrets and variables**, and choose which repositories each one reaches:

- **All repositories** of the organization;
- **Private repositories**: every repository that isn't public;
- **Selected repositories**: only the repositories you pick. You can change the
  list later without entering a secret's value again.

```sh
cafe ci secret set NPM_TOKEN --org acme --env NPM_TOKEN                  # private repositories
cafe ci secret set NPM_TOKEN --org acme --visibility all --env NPM_TOKEN
cafe ci secret set NPM_TOKEN --org acme --repos app,site --env NPM_TOKEN  # selected
cafe ci variable list --org acme
```

## What a job receives

When a job starts, it receives:

- every secret and variable of its repository;
- every organization secret and variable that reaches the repository, except
  those with the same name as one of the repository's: **a repository secret
  or variable overrides the organization's**.

A change applies to jobs that start afterwards. A job receives at most 200
secrets and 200 variables: the repository's first, then the organization's,
each in name order.

Runs for pull requests from forks receive no secrets and no variables. They
don't run in this version anyway ([pull requests from forks](https://git.cafe/docs/ci/actions.md#pull-requests-from-forks)).

## Not supported

GitHub's REST endpoints for secrets, which take values sealed with the
repository's public key, are not supported; use the CLI or the settings pages.
Environment secrets and variables are not supported either: a job with an
`environment` receives the repository's and organization's.