Use a secret input¶

Create a workflow that checks whether a secret was supplied and writes a nonsecret greeting. Then run it using a named entry in your Keycloak user vault.

The secret must not appear in the greeting or application logs. This exercise does not require a GitLab CI/CD variable: declared secret inputs and project-variable overrides are separate mechanisms.

Before you start¶

You need an AntFlow instance configured with Keycloak and user-secret support, access to a workflow project, and a suitable launcher. The execution environment must be able to run python:3.12-slim, or your administrator must provision its Singularity equivalent for HPC.

Use only a nonempty, nonsecret test value for this tutorial. For vault setup, follow Manage workflow secrets.

1. Declare the workflow and consuming tool¶

Create secret-check.cwl in your workflow repository:

cwlVersion: v1.2
class: Workflow
label: Check a secret input
doc: Check secret availability and produce a greeting without the secret value.
$namespaces:
  cwltool: http://commonwl.org/cwltool#
hints:
  cwltool:Secrets:
    secrets: [api_key]
inputs:
  api_key:
    label: Secret
    doc: Select a vault entry for the availability check.
    type: string
  message:
    label: Message
    type: string
    default: Hello
outputs:
  greeting:
    type: File
    outputSource: check/greeting
steps:
  check:
    in:
      api_key: api_key
      message: message
    out: [greeting]
    run:
      class: CommandLineTool
      baseCommand: [python3, -c]
      arguments:
        - |
          import os
          from pathlib import Path

          if not os.environ.get("DEMO_SECRET"):
              raise SystemExit("Secret input is missing")

          Path("greeting.txt").write_text(
              os.environ["GREETING"] + ", world!\n", encoding="utf-8"
          )
      hints:
        cwltool:Secrets:
          secrets: [api_key]
      requirements:
        DockerRequirement:
          dockerPull: python:3.12-slim
        EnvVarRequirement:
          envDef:
            DEMO_SECRET: $(inputs.api_key)
            GREETING: $(inputs.message)
      inputs:
        api_key:
          type: string
        message:
          type: string
      outputs:
        greeting:
          type: File
          outputBinding:
            glob: greeting.txt

The workflow and its consuming tool both declare api_key as a secret. The tool reads it through an environment variable, checks that it is nonempty, and writes only the nonsecret message to its output.

Validate the definition with cwltool extension support enabled:

cwltool --enable-ext --validate secret-check.cwl

For the supported declarations and how saved secret names are used, see Secret inputs.

2. Add a test vault entry¶

Open Profile from AntFlow's user menu and add a vault entry named MY_SECRET with the value nonempty-test-value. Follow the procedure for your deployment's secret editor, then save the profile.

This entry is a workflow credential, not a GitLab repository token. Do not put it in the separate GitLab token field.

3. Publish and execute¶

1. Commit and push secret-check.cwl to your workflow project.
2. Check the project's discovery topic and access.
3. Open the project and select the Git reference containing the new workflow.
4. Open Check a secret input and select MY_SECRET in Secret.
5. Leave Message as Hello, select a launcher, and submit the job.

The form supplies the alias MY_SECRET; AntFlow resolves the vault value for execution. Do not replace the alias with the real value in an API request or reusable input file.

4. Inspect the result¶

Use the job details to inspect logs and retrieve greeting. With the default message, its content is:

Hello, world!

The test value must not appear in the greeting or application logs. If an empty value reaches the tool, it fails with Secret input is missing.

What's next¶

• Manage workflow secrets: maintain vault entries for other workflows.
• Secret inputs: look up the declaration and use of saved secret names when adapting your own workflow.