How to Use cert-manager.io certificates in CircleCI Server's Helm Deployment

Introduction:

CircleCI Server, if not using AWS certificate manager, requires TLS certificate and private key values to be populated in values.yaml. Users often hardcode these. If you're using cert-manager, you can dynamically pull from the Kubernetes secret it creates. This avoids manual copy/paste and makes cert rotation seamless.

This guide shows how to inject cert-manager-generated TLS certs into a Helm chart using kubectl and helm's --set parameter.

Prerequisites (If Applicable):

cert-manager installed and managing a TLS certificate for your domain.
A valid Certificate resource that issues to a Secret.
Access to kubectl and helm CLI tools.
The name of the TLS Secret containing tls.crt and tls.key.

Example certificate:

Replace <global.domainName> with the actual domain name of the CircleCI environment from your values.yaml, including the app. as a SAN.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: circle-cert
namespace: circleci
spec:
secretName: circle-tls
issuerRef:
name: letsencrypt-dns
kind: ClusterIssuer
commonName: <global.domainName>
dnsNames:
- "<global.domainName>"
- "app.<global.domainName>"

Instructions:

Locate the cert-manager Secret containing your TLS cert
- By default, cert-manager writes certs to the secret named in your Certificate manifest.
  Example:
```
kubectl get secret -n <namespace>
```

Extract base64-encoded values from the TLS secret Run:

TLS_CERT=$(kubectl get secret -n <namespace> <secret-name> -o jsonpath='{.data.tls\.crt}')
TLS_KEY=$(kubectl get secret -n <namespace> <secret-name> -o jsonpath='{.data.tls\.key}')

Pass the extracted cert/key into your Helm install or upgrade

helm upgrade --install circleci-server oci://cciserver.azurecr.io/circleci-server \
-n <namespace> --version <version> -f values.yaml \
--set "tls.certificate=${TLS_CERT}" \
--set "tls.privateKey=${TLS_KEY}"

Confirm your deployment is using the correct TLS

Example wrapper script:

#!/bin/bash

set -euo pipefail

namespace="circleci"
cci_version="4.7.5"

TLS_SECRET="circle-tls"
TLS_CERT=$(kubectl get secret -n "$namespace" "$TLS_SECRET" -o jsonpath='{.data.tls\.crt}')
TLS_KEY=$(kubectl get secret -n "$namespace" "$TLS_SECRET" -o jsonpath='{.data.tls\.key}')

helm upgrade --install circleci-server oci://cciserver.azurecr.io/circleci-server \
-n "$namespace" --version "$cci_version" -f values.yaml \
--set "tls.certificate=${TLS_CERT}" \
--set "tls.privateKey=${TLS_KEY}"

Outcome:

Your Helm deployment now references cert-manager managed TLS certificates directly from Kubernetes secrets, eliminating hardcoded values and simplifying future certificate rotation.

Additional Notes:

Cert-manager will update the Secret in-place upon renewal. Helm won’t auto-reload those values unless re-deployed, so you might automate a periodic redeploy or use hot-reloading logic where supported.
Avoid embedding large certs in values.yaml—they may be truncated or stored in Git unintentionally.

Additional Resources: