# Secrets and variables

Avrea CI uses secrets and variables configured in Avrea. Values stored in
GitHub are not imported automatically. Use secrets for credentials and
variables for non-sensitive configuration.

Review [supported events and access requirements](/avrea-ci/workflows/#managed-configuration)
before configuring values for your workflows.

## Configure values

As an organization administrator, open **Settings → Secrets and variables**
in the Avrea console. Create a named secret or variable, add its value, and
choose where it is available. Contact
[support@avrea.com](mailto:support@avrea.com) to have managed secrets and
variables enabled for the repository.

Scopes can restrict a value to repositories, workflow paths, branches, and
environments. When you specify multiple kinds of scope, all must match;
multiple entries within one kind are alternatives. Entries accept `*` and `**`
as wildcards. For a migrated workflow, use its `.avrea/workflows/` path in
workflow restrictions.

For example, scope `DEPLOY_TOKEN` to your repository,
`.avrea/workflows/deploy.yml`, the `main` branch, and the `production`
environment. Tag runs have no branch name, so a branch-only scope does not
match a tag push. An unrestricted value is available throughout the
organization, subject to repository policy.

Repository writers can change workflows to consume values within their
matching scopes. Choose those scopes with the repository's writers in mind.
Secrets are write-only. Variables are readable plain text.

## Use values in a workflow

```yaml title=".avrea/workflows/deploy.yml"
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: avrea-ubuntu-24.04
    environment: production
    env:
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
      DEPLOY_REGION: ${{ vars.REGION }}
    steps:
      - uses: actions/checkout@v7
      - run: ./scripts/deploy.sh --region "$DEPLOY_REGION"
```

Provision both values before running this example. Names are case-insensitive.
Pass values to actions through `with` or `env`; composite actions do not
receive an implicit secrets context.

`environment: production` selects a configuration scope. It does not implement
GitHub environment approvals, wait timers, or deployment protection rules.

## File secrets

A file secret makes `${{ secrets.NAME }}` resolve to a private file path
containing the value. Pass the path to tools that expect a credential file:

```yaml
env:
  CREDENTIALS_FILE: ${{ secrets.SERVICE_CREDENTIALS }}
steps:
  - run: ./scripts/authenticate.sh --credentials "$CREDENTIALS_FILE"
```

Create `SERVICE_CREDENTIALS` as a file secret. The same expression for a
regular string secret returns its value instead of a path.

## Missing values and rotation

If a name is missing, its scope does not match the run, or it has no active
value, the expression resolves to an empty string. Check required values in
your deployment script and fail if they are absent. An access denial or
failure to retrieve the value selected for the run fails the job.

Values are fixed for a run before jobs start. Rotating a secret affects new
runs; jobs already accepted for execution keep the values selected for them,
including jobs waiting on dependencies. Deleting or disabling a value does not revoke
those runs. To stop its use, disable repository access, cancel affected runs,
and revoke the credential at its issuer when needed.

Secret values are masked in logs, and detected secret-bearing job outputs are
omitted from downstream `needs` outputs. Avoid printing secrets or placing
them in artifacts: masking cannot protect every transformed value or a file
you deliberately upload.

## Variables in scheduling

Named variables such as `vars.RUNNER` can determine `runs-on`, job conditions,
timeouts, matrices, strategy limits, concurrency, and reusable workflow inputs.
These values use the repository, workflow, and branch scopes captured for the
run. Environment-specific overrides apply only inside the job; they cannot
change its runner, condition, matrix, or concurrency group.

Secrets cannot determine scheduling fields. Neither secrets nor variables can
set `run-name`. Environment names cannot be derived from variables.

## Reusable workflow configuration

For [reusable workflows](/avrea-ci/workflows/#reusable-workflows), forward
only the secrets the called workflow needs, for example
`secrets: { TOKEN: '${{ secrets.DEPLOY_TOKEN }}' }`.

When the caller and called repository have the same owner, `secrets: inherit`
lets the called workflow reference any secret available in the caller's scope.
Use it only when you trust the called workflow and the changes its maintainers
accept. Nested calls must forward secrets at every level. Unforwarded secrets
resolve to an empty string.

Values retain the original caller's repository, workflow, and branch scopes.
Literal or computed secret mappings, cross-owner inheritance, and environments
on called workflows are unsupported.

## Configuration limits

- Use explicit names such as `secrets.DEPLOY_TOKEN` and `vars.REGION`.
  Dynamically constructed names and whole-context expressions such as
  `toJSON(secrets)` are unsupported.
- Use secrets in runtime fields such as step inputs and environment variables.
- Environment names must be constant or resolve from a static matrix. Jobs
  with dynamic matrices must use a constant environment when consuming
  managed configuration.
- Container and service `credentials` are unsupported in jobs using managed
  configuration. Avrea secrets and variables do not provide a `GITHUB_TOKEN`.
- Values are limited to 48 KiB. A job can use at most 100 configuration entries,
  and a run can have at most 1,000 across its expanded jobs. Each matrix cell
  counts separately; scheduling variables consume additional entries.