DocsFeaturesCloud secrets

Cloud secrets

Reference External Secrets Operator values from Lifecycle Services and native Helm deployments.

Lifecycle can get cloud secrets through External Secrets Operator (ESO). You reference a secret in supported lifecycle.yaml fields. Lifecycle then gives the synchronized value to the applicable workload or pipeline.

Before you start

Get this information from your platform team:

  • The provider prefix for your cluster
  • The secret paths that Lifecycle can read
  • The key name for each JSON secret
  • The expected secret refresh interval

Common provider prefixes are aws, gcp, and barbican. Use only a prefix that your platform team supports.

The cluster must have ESO and a matching ClusterSecretStore. The store identity must have access to the requested secret path.

Secret reference syntax

Use this syntax for a JSON secret:

Use this syntax for a plain-text secret:

For example:

The reference must not contain spaces. Provider names, paths, and keys are case-sensitive.

⚠️

Do not commit a secret value to lifecycle.yaml. Commit only the secret reference.

Use secrets in a Service

Lifecycle resolves secret references in supported Service environment blocks. This example uses a GitHub Service:

You can also use the syntax in these Service locations:

  • github.docker.app.env
  • github.docker.init.env
  • docker.env
  • helm.docker.app.env
  • helm.docker.init.env
  • Codefresh Service env
  • Native Helm chart.values

For Service environment blocks, Lifecycle adds the synchronized values to the workload environment.

If a Service secret reference is invalid, Lifecycle can log a warning. The Service can fail because the necessary value is unavailable.

Use secrets with Codefresh

A Codefresh Service can use complete secret references in nested env objects or arrays:

Lifecycle resolves the values before it starts the Codefresh pipeline. If a value cannot resolve, Lifecycle does not start the pipeline.

Codefresh Helm deployments do not support secret references in helm.chart.values. Use native Helm for secret-backed chart values.

Use secrets with native Helm

For native Helm, the complete value after = can be a secret reference:

Lifecycle gives secret-backed values to Helm through files. Plain values use the usual Helm value argument.

Partial secret interpolation is not supported:

For a composite value, store the complete value with the provider. Then, reference that value directly.

⚠️

Do not add --debug or --dry-run to a native Helm deployment with secret values. Lifecycle rejects this combination because Helm can print rendered values.

See Native Helm deployment for the complete Service configuration.

Understand unsupported locations

Webhook env does not resolve cloud secret references. The webhook receives the reference as text.

If a webhook needs credentials, use a credential mechanism that its Job or pipeline supports. Do not put a secret-bearing URL in lifecycle.yaml.

Understand native image builds

For native BuildKit and Kaniko builds, a Service environment secret is also a Docker build argument. The Dockerfile receives the value only if it declares a matching ARG.

⚠️

Docker build arguments are not secret mounts. Build logs, cache, image metadata, or Dockerfile commands can expose their values.

A build-time secret is applicable only to image construction. For a necessary build-time value:

  1. Do not print the value.
  2. Create the temporary credential file in one RUN instruction.
  3. Use the credential in the same RUN instruction.
  4. Delete the credential file in the same RUN instruction.
  5. Use a multi-stage build to keep temporary files out of the final image.

Failure behavior

ConditionUser-visible result
Service reference is invalidLifecycle logs a warning, and the Service can fail
Secret synchronization fails before buildThe Service build fails
Codefresh secret cannot resolveLifecycle does not start the pipeline
Native Helm secret cannot resolveLifecycle does not start the Helm deployment
Helm value contains a partial referenceLifecycle reports a configuration error
Webhook env contains a secret referenceThe webhook receives the reference as text

Troubleshooting

Lifecycle omits a Service value

  1. Check the provider prefix.
  2. Check the case-sensitive secret path.
  3. For a JSON secret, check the key.
  4. Ask the platform team whether the path is allowed.
  5. Examine the Service logs for a secret warning.

Secret synchronization fails

  1. Give the provider, path, Environment ID, and Service name to the platform team.
  2. Ask the team to check the matching ClusterSecretStore.
  3. Ask the team to check the provider identity and path permissions.
  4. After the team corrects access, redeploy the Service.

Do not include the secret value in an issue, chat message, or log excerpt.

A native Helm value fails

  1. Make sure that the entry has key=value syntax.
  2. Make sure that the complete value is one secret reference.
  3. Remove --debug and --dry-run.
  4. Check the provider, path, and JSON key.

A Dockerfile does not receive a value

  1. Make sure that the Service uses a native BuildKit or Kaniko build.
  2. Add an ARG instruction with the same name.
  3. Keep the value out of build output.
  4. Rebuild the Service.

Related pages

Native Helm deploymentEnvironment expiration and cleanup