Using Secrets in Simulation

This guide explains how to use secrets during local development and simulation. When you're simulating a workflow on your local machine with cre workflow simulate, secrets are provided via environment variables or a .env file.

At a high level, the process follows a simple, three-step pattern:

1. Declare: You declare the logical names of your secrets in a secrets.yaml file.
2. Provide: You provide the actual secret values in a .env file or as environment variables.
3. Use: You access the secrets in your workflow code using the SDK's secret management API.

This separation of concerns ensures that your workflow code is portable and your secrets are never hard-coded.

Step-by-step guide

Step 1: Declare your secrets (secrets.yaml)

The first step is to create a secrets.yaml file in the root of your project. This file acts as a manifest, defining the "logical names" or "IDs" for the secrets your workflow will use.

In this file, you map a logical name (which you'll use in your workflow code) to one environment variable name that will hold the actual secret value.

Example secrets.yaml:

# in project-root/secrets.yaml
secretsNames:
  # This is the logical ID you will use in your workflow code
  SECRET_ADDRESS:
    # This is the environment variable the CLI will look for
    - SECRET_ADDRESS_ALL

Step 2: Provide the secret values

Next, you need to provide the actual values for the secrets. The cre CLI can read these values in two primary ways.

Method 1: Using shell environment variables (Recommended)

You can provide secrets as standard environment variables directly in your shell.

For example, in your terminal:

export SECRET_ADDRESS_ALL="0x1234567890abcdef1234567890abcdef12345678"

When you run the cre workflow simulate command in the same terminal session, the CLI will have access to this variable.

Method 2: Using a .env file

Create a .env file in your project's root directory. The cre CLI automatically finds this file and loads the variables defined within it into the environment for your simulation. The variable names here must match those you declared in secrets.yaml.

Example .env file:

# in project-root/.env

# The variable name matches the one in secrets.yaml
SECRET_ADDRESS_ALL="0x1234567890abcdef1234567890abcdef12345678"

Step 3: Use the secret in your workflow

Now you can access the secret in your workflow code. The SDK provides a method to retrieve secrets using the logical ID you defined in secrets.yaml.

The following code shows a complete, runnable workflow that triggers on a schedule, fetches a secret, and logs its value.

Example workflow:

Step 4: Configure secrets path in workflow.yaml

Before simulating, you need to tell the CLI where to find your secrets file. This is configured in your workflow.yaml file under workflow-artifacts.secrets-path.

Open your workflow.yaml file and set the secrets-path:

local-simulation:
  user-workflow:
    workflow-name: "my-workflow"
    workflow-artifacts:
      workflow-path: "./main.go"
      config-path: "./config.json"
      secrets-path: "../secrets.yaml" # Path to your secrets file

Notice the path ../secrets.yaml. Because the workflow artifacts are relative to the workflow directory, you need to point to the secrets.yaml file located one level up in the project root.

Step 5: Run the simulation

Now you can simulate your workflow:

cre workflow simulate my-workflow --target staging-settings

The CLI will automatically read the secrets-path from your workflow.yaml and load the secrets from your .env file or environment variables you provided in your terminal session.

Fetching multiple secrets

You can fetch multiple secrets by calling the secret retrieval method multiple times within your workflow.

The following example builds on the previous one. First, update your secrets.yaml to declare two secrets:

secretsNames:
  SECRET_ADDRESS:
    - SECRET_ADDRESS_ALL
  API_KEY:
    - API_KEY_ALL

Then provide the values in your .env file or export them as environment variables in your terminal session:

export SECRET_ADDRESS_ALL="0x1234567890abcdef1234567890abcdef12345678"
export API_KEY_ALL="your-api-key-here"

Now you can fetch both secrets in your workflow code: