How to Automate SSL Certificate Renewal with HashiCorp Vault in CI Pipelines

Step-by-step guide to set up SSL certificate automation using HashiCorp Vault in your CI pipeline, ensuring zero‑downtime renewals and secure secret handling.

How to Automate SSL Certificate Renewal with HashiCorp Vault in CI Pipelines - Cybersecurity
Short answer: Link Vault’s PKI secrets engine to your CI system, configure a role that can issue short‑lived TLS certificates, and add a small script step that requests a cert, stores it as a CI secret, and deploys it to the target service. The same pipeline can be scheduled to run before the current cert expires, achieving fully automated SSL certificate renewal.

Most teams still rely on manual OpenSSL commands or on third‑party services that require periodic human interaction. That approach creates drift, risks expired certificates, and adds unnecessary toil to release cycles. By using ssl certificate automation with HashiCorp Vault, you centralize secrets management, enforce short‑lived certificates, and let your CI pipelines handle issuance and deployment without any manual steps.

In this guide you will set up Vault’s PKI engine, create a role for your applications, and integrate the flow with three popular CI platforms—GitHub Actions, GitLab CI, and Azure DevOps. After completing the tutorial you will be able to trigger a pipeline that automatically obtains a new TLS cert, validates it, and pushes it to a Kubernetes secret, an Nginx container, or any other service that consumes TLS material.

What You’ll Learn

  • How to enable and configure the Vault PKI secrets engine for automated cert issuance.
  • How to create a Vault role that limits certificate TTL and enforces CN/SAN constraints.
  • How to store Vault credentials safely in each CI system.
  • Step‑by‑step pipeline snippets for GitHub Actions, GitLab CI, and Azure DevOps.
  • Common pitfalls (token leakage, TTL mismatches) and how to avoid them.

Prerequisites

  • Vault server (>= 1.14) reachable from your CI runners. Official docs: Vault Documentation.
  • Access to a CI platform with secret storage (GitHub Actions Secrets, GitLab CI Variables, Azure DevOps Library).
  • Target environment that can consume TLS material (Kubernetes cluster, Docker container, VM).
  • Basic familiarity with vault CLI and your CI YAML syntax.

1. Set up Vault PKI Engine

Enable the PKI secrets engine

vault secrets enable -path=pki pki
vault secrets tune -max-lease-ttl=8760h pki   # 1 year max TTL

Generate a root CA (or import an existing one)

vault write -field=certificate pki/root/generate/internal \
    common_name="example.com" ttl=8760h > ca.crt
# Generate CSR
vault write -format=json pki/intermediate/generate/internal \
    common_name="example.com Intermediate Authority" ttl=4380h > csr.json

# Sign CSR with external CA or the root you just created
vault write pki/root/sign-intermediate \
    csr=@csr.json.csr format=pem_bundle ttl=4380h > signed_intermediate.pem

# Import signed intermediate
vault write pki/intermediate/set-signed \
    certificate=@signed_intermediate.pem

Define a role for CI‑driven certificates

This role limits the certificate’s subject, allowed domains, and TTL (e.g., 30 days).

vault write pki/roles/ci-service \
    allowed_domains="example.com" \
    allow_subdomains=true \
    max_ttl="720h"   # 30 days
Pro Tip: Keep max_ttl short (≤30 days) to force regular rotation and reduce blast‑radius if a cert is compromised.

2. Secure CI Credentials

All CI platforms should store the Vault token (or AppRole credentials) as a secret, never in source code.

GitHub Actions

  1. Generate a token with a policy that only allows pki/issue/ci-service:
vault policy write ci-service -<<EOF
path "pki/issue/ci-service" {
  capabilities = ["update"]
}
EOF

vault token create -policy=ci-service -period=720h -display-name="github-actions-ci"
  1. Copy the token value and add it to the repository’s Settings → Secrets → Actions as VAULT_TOKEN.

GitLab CI

  • Add a CI/CD variable named VAULT_TOKEN with the same token value (Settings → CI/CD → Variables).

Azure DevOps

  • Navigate to Project Settings → Pipelines → Library, create a variable group, and add VAULT_TOKEN (keep it secret).

3. GitHub Actions Integration

Workflow file

name: Automated SSL Renewal

on:
  schedule:
    - cron: '0 2 * * *'   # daily at 02:00 UTC
  workflow_dispatch:

jobs:
  renew-cert:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Install Vault CLI
        run: |
          curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
          sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
          sudo apt-get update && sudo apt-get install -y vault

      - name: Request certificate
        env:
          VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
          VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }}
        run: |
          vault write -format=json pki/issue/ci-service \
            common_name="api.example.com" ttl="720h" > cert.json
          jq -r .data.certificate cert.json > cert.pem
          jq -r .data.private_key cert.json > key.pem
          jq -r .data.issuing_ca cert.json > ca.pem

      - name: Upload cert as artifact
        uses: actions/upload-artifact@v4
        with:
          name: tls-artifact
          path: |
            cert.pem
            key.pem
            ca.pem

Deploy step (optional)

If your target is a Kubernetes cluster, add a step that runs kubectl create secret tls using the downloaded files.

4. GitLab CI Integration

.gitlab-ci.yml snippet

stages:
  - renew

renew_ssl:
  stage: renew
  image: hashicorp/vault:latest
  variables:
    VAULT_ADDR: $VAULT_ADDR
    VAULT_TOKEN: $VAULT_TOKEN
  script:
    - vault write -format=json pki/issue/ci-service \
        common_name="web.example.com" ttl="720h" > cert.json
    - cat cert.json | jq -r .data.certificate > cert.pem
    - cat cert.json | jq -r .data.private_key > key.pem
    - cat cert.json | jq -r .data.issuing_ca > ca.pem
  artifacts:
    paths:
      - cert.pem
      - key.pem
      - ca.pem
    expire_in: 1 day

Deploy to Kubernetes

Use the kubernetes executor or add a kubectl container to apply the secret.

5. Azure DevOps Integration

Pipeline YAML

trigger: none

schedules:
- cron: "0 3 * * *"
  displayName: Daily SSL renewal
  branches:
    include:
    - main

jobs:
- job: RenewCert
  pool:
    vmImage: 'ubuntu-latest'
  variables:
    VAULT_ADDR: $(VAULT_ADDR)   # defined in pipeline variables
    VAULT_TOKEN: $(VAULT_TOKEN)
  steps:
  - script: |
      sudo apt-get update && sudo apt-get install -y vault jq
      vault write -format=json pki/issue/ci-service \
        common_name="service.example.com" ttl="720h" > cert.json
      jq -r .data.certificate cert.json > cert.pem
      jq -r .data.private_key cert.json > key.pem
      jq -r .data.issuing_ca cert.json > ca.pem
    displayName: 'Request TLS cert from Vault'

  - publish: $(System.DefaultWorkingDirectory)
    artifact: tls-artifact
    displayName: 'Publish certificate artifacts'

6. Deploying the Certificate

Kubernetes secret (any CI)

kubectl create secret tls api-tls \
  --cert=cert.pem \
  --key=key.pem \
  --dry-run=client -o yaml | kubectl apply -f -

Docker container (example with Nginx)

docker run -d \
  -v $(pwd)/cert.pem:/etc/nginx/ssl/tls.crt:ro \
  -v $(pwd)/key.pem:/etc/nginx/ssl/tls.key:ro \
  -p 443:443 nginx:stable
Pro Tip: Use a side‑car container that watches the CI artifact directory and reloads Nginx on change; this removes the need for a full container restart.

7. Troubleshooting & Common Mistakes

  • Token leakage: Verify that the Vault token is stored only in the CI secret store. Accidentally echoing $VAULT_TOKEN in logs will expose it.
  • TTL mismatch: If the role’s max_ttl is shorter than the requested ttl, Vault returns an error. Align the two values or omit ttl to use the role default.
  • Missing CA chain: Some services require the full chain (leaf + intermediate + root). Concatenate cert.pem and ca.pem if needed.
  • Clock skew: CI runners and Vault must have synchronized NTP; otherwise “certificate not yet valid” errors appear.
  • Rate limits: Vault can handle thousands of requests per second, but a mis‑configured cron that fires every minute may flood the server. Use a sensible schedule (daily or every few hours) and monitor Vault audit logs.

Frequently Asked Questions

Can I use AppRole instead of a static token?

Yes. Create an AppRole with a policy that permits pki/issue/ci-service, store the role_id and secret_id as CI variables, and have the pipeline login via vault write auth/approle/login. This adds an extra rotation layer.

Vault supports short lifetimes (e.g., 24‑72 hours). For most web services, a 30‑day TTL balances security and operational overhead. Adjust based on your risk profile and the latency of your deployment pipeline.

Do I need a dedicated Vault namespace for each CI environment?

Namespaces are useful for multi‑tenant setups. For a single organization, a single PKI mount with role‑based access control is sufficient. Use namespaces only when you need strict isolation between teams.

How do I revoke a certificate that was mistakenly issued?

Run vault write pki/revoke serial_number=<SERIAL>. The revocation is recorded in the CRL, which should be served to clients (e.g., via pki/config/urls).

Can this workflow work with external CAs (e.g., Let's Encrypt) via Vault?

Vault can act as a proxy to external CAs using the pki engine’s issuers feature (available in Vault 1.13+). Configure an issuer that points to the ACME endpoint, then request certs through the same role‑based flow.

Is there a way to test the pipeline without affecting production?

Yes. Create a separate Vault role (e.g., ci-service-dev) with a distinct allowed_domains like dev.example.com. Point your test pipelines to that role and to a dev Vault namespace if available.

What are the cost implications of using Vault for SSL automation?

Vault Enterprise adds features such as namespaces and advanced governance, billed per node. The open‑source version is free to run on your own infrastructure. Cloud‑hosted Vault (e.g., HCP Vault) charges per HSM‑protected node; consult the provider’s pricing page for current rates.

Conclusion & Next Steps

Implement the PKI role and CI snippets in a sandbox repository first. Verify that a certificate is issued, stored as a secret, and successfully applied to a test service. Once confirmed, extend the same pattern to all production services that require TLS.

Next actions:

  1. Enable audit logging in Vault to monitor cert issuance (vault audit enable file file_path=/var/log/vault_audit.log).
  2. Set up a monitoring alert (e.g., Prometheus vault_certificate_renewal_success_total) to catch renewal failures early.
  3. Consider rotating the CI Vault token via a scheduled job or using AppRole for zero‑day rotation.
  4. Document the role definitions and CI variable names in your internal wiki to keep the process transparent.

Official documentation