Secrets & variables

Settings → Secrets & variables has two tabs:

• Credentials: passwords, tokens, keys, certificates and files. Values are kept in the secret store. The database only holds the name, kind, field names and metadata.
• Variables: plain key/value settings per environment, which can point at a credential instead of holding a secret.

Credentials are used by reference everywhere in OpsNexus: integrations, cloud accounts, notification channels, registries and pipelines.

#Where values are stored

OpsNexus has two secret backends. Choose one with SECRET_BACKEND.

#Vault settings

The scheduler renews the Vault token daily. A least-privilege Vault policy is provided in deploy/vault/opsnexus-policy.hcl.

#Local store settings

LOCAL_SECRET_KEY holds the Fernet key. If it is empty, a key is derived from SECRET_KEY. In that case, changing SECRET_KEY makes stored values unreadable. Generate a key with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

#Scopes: project and shared

Each credential and variable is available in one of two places, chosen with Available in when you create it:

• This project: only pipelines and settings in the current project can use it.
• Shared with all projects: every project can use it.

A project credential with the same ID as a shared one overrides it inside that project. The shared one is then marked Overridden here in that project's list.

Shared items belong to the organization. Creating, changing or revealing them needs that level on Secrets & variables in your organization role. Project items follow your project role. An organization admin can turn off sharing of secrets for the whole organization on the Projects page. See Access control.

#Permissions

Inside a project, the Developer project role gets read-only access to secrets, and Viewer gets none.

#Add a credential

1. Open Settings → Secrets & variables, tab Credentials.
2. Select Add credential and choose the kind.
3. Enter the ID. Use 2 or more characters: letters, digits, ., _ or -. Pipelines and forms refer to the credential by this ID, and it can't be changed later.
4. Fill in the fields for the kind, and optionally a Description.
5. Choose Available in.
6. Leave Use in pipelines on if builds may read it. Turn it off to keep it for portal features only (integrations, cloud accounts and similar).
7. Optionally set Remind me to rotate every (days).
8. Select Save credential.

#Credential kinds

#Use a credential in a form

Secret fields across OpsNexus offer Use saved credential. Pick a credential instead of pasting a value. The form then stores a reference, and OpsNexus reads the credential's current value whenever it needs it. Rotating the credential updates every place that uses it.

#Use secrets and variables in pipelines

In a pipeline file:

name: web-app
environment: prod                  # which environment vars.* are read from
env:
  API_TOKEN: ${{ secrets.deploy-token }}
  DB_USER: ${{ secrets.prod-db.username }}
  KUBECONFIG: ${{ secrets.prod-kubeconfig }}
  LOG_LEVEL: ${{ vars.LOG_LEVEL }}
stages:
  - name: Deploy
    steps:
      - run: ./deploy.sh

• ${{ secrets.ID }} gives the main value of the credential: the password, token or secret.
• ${{ secrets.ID.field }} gives one field, for example .username.
• For a Secret file, ${{ secrets.ID }} gives a path to a file the agent writes. Use ${{ secrets.ID.content }} for the file's text.
• ${{ vars.KEY }} gives a variable for the pipeline's environment.

The project's own credential is used first, then the shared one. A credential with Use in pipelines off can't be used in a build, and the build fails with a message that says so. See Pipeline syntax for the full expression syntax.

#How values reach the agent

Secrets are never stored with a build run. OpsNexus reads them from the secret store when the agent asks for the run plan, and sends them once over HTTPS.

#Masking in build logs

Every secret value resolved for a run is masked in the console output, by the agent and again by the server. Values shorter than 3 characters are not masked. For multi-line values, such as private keys, each line of 3 or more characters is masked separately.

#Variables

Variables hold non-secret settings per environment.

1. Open the Variables tab.
2. In Add or update a variable, enter the Key, for example LOG_LEVEL.
3. Pick the Environment: dev, staging, prod or all environments.
4. Enter the Value. To use a secret, write vault:<credential ID> instead of the secret itself.
5. Optionally set Scope. The default is global.
6. Select Save. Saving the same key and environment again updates it.

When a pipeline reads ${{ vars.KEY }}, OpsNexus looks for the variable in the pipeline's environment and in all environments, then picks the best match in this order:

1. An exact environment match beats all environments.
2. The project's own variable beats a shared one.
3. A variable whose Scope is the pipeline's full name or its top-level folder beats one that isn't.
4. A global scope beats any other non-matching scope.

If no variable matches, the build fails and names the missing key and environment.

#Reveal a value

Select Reveal on a credential to see its stored value. This needs Full access on Secrets & variables (for a shared credential, in your organization role). Every reveal is recorded in the audit log as secret.reveal, with your name, the credential and your IP address. See Audit logs.

#Rotate a credential

1. Select Update on the credential.
2. Enter new values. Empty fields keep their current value.
3. Optionally change the Description, Rotate every (days, empty = off) or Use in pipelines.
4. Select Save.

Each update writes a new version. The Version column shows the current version number, and the Rotation column shows the reminder period or Overdue. The Due for rotation tile counts overdue credentials. A rotation reminder only marks the credential. OpsNexus doesn't change values by itself.

#Delete a credential

1. Select Used by to see where the credential is used.
2. Select Delete.

If the credential is still in use, OpsNexus lists the places that will stop working. Select Keep it, or Delete anyway. Deleting removes the value from the secret store.

#Audit trail

Secret values are never written to the audit log.

#Related pages

• Pipeline syntax
• Environment variables
• Backup & restore