Project Configuration

This page explains how to manage configuration within Chainlink Runtime Environment (CRE) projects. It covers the standard project structure, the roles and usage of the configuration files (project.yaml and workflow.yaml), and the concept of targets for handling environment-specific settings.

You will understand:

• The recommended directory structure for CRE projects and the significance of key files.
• How to define global settings in project.yaml and override them with workflow-specific settings in workflow.yaml.
• The purpose of targets and how they enable seamless switching between different operational environments.
• The process by which the CRE CLI resolves and merges target configurations.

1. Glossary

2. Project structure

A typical CRE Go project is organized as follows:

myProject/
├── go.mod                  # Go module definition
├── go.sum                  # Go dependency checksums
├── .env                    # Secret values (never commit to a Version Control System like Git)
├── .gitignore
├── project.yaml            # Global configuration
├── secrets.yaml            # Secret name declarations
├── contracts/              # Contract-related files
│   └── evm/
│       └── src/
│           ├── abi/        # Contract ABI files (.abi JSON format)
│           └── generated/  # Auto-generated Go bindings
├── workflow1/
│   ├── workflow.yaml       # Workflow-specific configuration (optional)
│   ├── main.go             # Your workflow code
│   └── …
├── workflow2/
│   ├── workflow.yaml       # Workflow-specific configuration (optional)
│   ├── main.go             # Your workflow code
│   └── …
└── …

• go.mod / go.sum: Go module definition and dependency management for the entire project.
• project.yaml: Global settings, shared by every workflow in the project.
• workflow.yaml: Local settings for a single workflow. Add this file only when the workflow needs overrides.
• secrets.yaml: Secret declarations, a manifest of logical secret names used across the project.
• contracts/evm/src/abi/: Contract ABIs, where you place .abi JSON files for contract binding generation.
• contracts/evm/src/generated/: Generated Go bindings, automatically created by the CRE CLI from your ABI files using cre generate-bindings.

3. Configuration files

3.1. Global configuration (project.yaml)

project.yaml holds everything that rarely changes across workflows, such as RPC endpoints.

# project.yaml
staging-settings:
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com

# You can define other targets for future use
production-settings:
  account:
    workflow-owner-address: "0x..." # Optional: For multi-sig wallets
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com
    - chain-name: ethereum-mainnet
      url: https://mainnet.infura.io/v3/<YOUR-PROJECT-ID>

Configuration fields

3.2. Workflow configuration (workflow.yaml)

workflow.yaml captures details unique to one workflow instance, like its name.

# workflow.yaml
staging-settings:
  user-workflow:
    workflow-name: "my-por-workflow-staging"
  workflow-artifacts:
    workflow-path: "." # Points to the workflow directory
    config-path: "./config.staging.json"
    secrets-path: "" # Empty if not using secrets

production-settings:
  user-workflow:
    workflow-owner-address: "<address>" # Optional: For multi-sig wallets
    workflow-name: "my-por-workflow-production"
  workflow-artifacts:
    workflow-path: "." # Points to the workflow directory
    config-path: "./config.production.json"
    secrets-path: "" # e.g. "../secrets.yaml" if using secrets

Configuration fields

3.3. Secrets configuration (secrets.yaml)

secrets.yaml is an optional project-level file that maps logical secret names to environment variables. This allows you to decouple the secret names used in your code from the actual environment variable names.

# secrets.yaml (at project root)
secretsNames:
  DATA_SOURCE_API_KEY:
    - DATA_SOURCE_API_KEY_ENV

To use secrets in your workflow, reference this file in your workflow.yaml:

workflow-artifacts:
  secrets-path: "../secrets.yaml"

For simulation, secret values are loaded from your .env file or environment variables. For deployed workflows, secrets are managed through the Vault DON using cre secrets commands.

For complete details on using secrets in your workflows, see Secrets Management.

4. Targets

A target is a top-level key inside both project.yaml and workflow.yaml. It bundles all settings for a single environment or variant.

The CLI selects the active target using the --target flag. Example:

# Simulate using the 'staging-settings' target
cre workflow simulate my-workflow --target staging-settings

Alternatively, the CRE_TARGET environment variable can be used to specify the target. The CLI picks the active target in this order:

1. --target <name> flag
2. CRE_TARGET=<name> environment variable

4.1. Defining Multiple Targets

You can store many targets in one file. This is useful for managing different environments (like simulation vs. production) or for testing variations of a workflow.

# In project.yaml

# Target for simulation and testing
staging-settings:
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com

# Target for production deployment
production-settings:
  account:
    workflow-owner-address: "0x123..." # Optional: For multi-sig wallets
  rpcs:
    - chain-name: ethereum-mainnet
      url: https://mainnet.infura.io/v3/<YOUR-PROJECT-ID>

4.2. How Target Resolution Works

When you run a CLI command with a target, e.g., --target staging-settings:

1. Load the staging-settings target from project.yaml.
2. Load the same target from workflow.yaml (if the file exists and contains a matching target definition).
3. Merge the two objects.
   • Keys present in both files → value from workflow.yaml wins.
   • Keys present in only one file → that value is used.
4. Validate the final object before execution.