Skip to content

Manage workflow secrets

Store a password or access token in your vault, the encrypted secret store in your AntFlow profile. Give it a name, then select that name when a workflow needs the secret. You can reuse it without typing the value into each form.

Before you start

This feature is available on instances using Keycloak for sign-in, when the administrator has enabled a secrets field in your profile. If that field is missing, ask your administrator to check the user-secret configuration.

A workflow secret is not a GitLab repository token. Use the secrets field, not the separate GitLab token field, for credentials consumed by workflow code. For repository credentials, see Authentication and project access.

Add a vault entry

Open the user menu in AntFlow and select Profile. Choose the procedure that matches your profile editor.

Secrets editor with automatic encryption

  1. Add an entry in the secrets editor.
  2. Give it a recognizable name, such as MY_SECRET.
  3. Enter the value and save the profile.

Start with a nonempty test value. The editor encrypts the value for your AntFlow server before storing it.

Profile field containing encrypted strings

If you are not familiar with command-line tools, ask your administrator to help you use this encryption procedure. Do not send them your secret value.

Do not paste a plaintext credential into this field. Obtain the scripts/tools/antflow-secret.py helper from the AntFlow server repository and confirm your instance's API base URL with the administrator.

Follow Access the API to set API_URL for that instance. Encryption uses its public certificate; you do not need to load an API token for this step. From the server repository, encrypt a nonsecret test value:

uv run --script scripts/tools/antflow-secret.py \
  --key "$API_URL/certs/jwk.json" \
  MY_SECRET "nonempty-test-value"

Use the same instance for encryption and sign-in; another server's key will not work. Add the returned encrypted JSON string as one entry in the profile's secrets list, then save the profile.

Real credentials need careful handling

Values passed on a command line may appear in shell history and process listings. Use your deployment's approved credential-entry procedure for real secrets; the command above demonstrates the format with a test value.

Use a secret input

  1. Open a process with a declared secret input.
  2. Select the vault entry's name, such as MY_SECRET, in that input.
  3. Supply the other required inputs and run the workflow.

The form lists the names you gave your secrets rather than their values. These names are called aliases. For API requests, also supply the name, not the secret value. AntFlow retrieves the value when running the workflow. See CWL secret inputs for the workflow author's input declarations.

For a workflow you can try with a nonsecret test value, follow Use a secret input.

If the entry is missing from the form, confirm that you saved the profile and that the process declares the input as a secret. Contact your administrator if the vault remains unavailable.

Override a project variable

A matching vault entry can also override an existing GitLab project variable for your job when the instance enables user-secret overrides. For example, a vault entry named TEST_VAR can override GitLab's CWL__TEST_VAR with the default prefix. This is separate from choosing a secret input, and it does not create a new variable when no project variable matches. Ask the workflow author for the expected name; see User secret overrides.

Check for disclosure

Use test values to inspect the workflow's logs and outputs before providing real credentials. A secret declaration does not prevent application code from printing the value or writing it into a result. Report unexpected disclosure to the workflow author and follow your organization's credential-rotation policy.

What's next