Deploy Checkly secrets from Azure Key Vault

Use GitHub OpenID Connect (OIDC) to give a trusted deployment job short-lived access to Azure Key Vault. The job maps each Key Vault secret to the CHECKLY_SECRET_* name expected by your Checkly constructs, then runs checkly deploy. For the scoping model and operational guidance behind this workflow, read Manage secrets at scale.

Prerequisites

A Checkly Monitoring as Code project that declares secrets with secret() and secret: true at group or check scope.
An Azure Key Vault that uses the Azure role-based access control (RBAC) permission model.
A Microsoft Entra application or user-assigned managed identity with a federated identity credential for GitHub Actions.
The identity has the Key Vault Secrets User role on the vault that contains this project’s secrets.
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID, AZURE_KEY_VAULT, and CHECKLY_ACCOUNT_ID configured as GitHub Actions variables.
The Checkly API key stored in Key Vault as checkly-api-key, alongside the secrets required by this project.

This guide uses a fictional payments service; replace its names and URL with your own application values. Checkly requires CHECKLY_API_KEY and CHECKLY_ACCOUNT_ID; the AZURE_* variables configure this workflow.

Configure Azure access

Follow Microsoft’s GitHub OIDC setup guide to create a federated identity for the repository and GitHub environment that deploy Checkly. Assign the identity the read-only Key Vault Secrets User role at the narrowest practical scope. The GitHub Actions runner must be able to reach the vault.

Map Key Vault secrets to Checkly

The following example assumes your application uses two credentials stored in Key Vault as payments-api-key and payments-admin-token. These are example names, not Azure or Checkly requirements. Reference their deployment environment names in your constructs:

__checks__/payments.check.ts

import { ApiCheck, CheckGroupV2 } from 'checkly/constructs'
import { secret } from 'checkly/util'

const paymentsGroup = new CheckGroupV2('payments', {
  name: 'Payments',
  environmentVariables: [
    {
      key: 'PAYMENTS_API_KEY',
      value: secret('PAYMENTS_API_KEY'),
      secret: true,
    },
  ],
})

new ApiCheck('payments-admin-health', {
  name: 'Payments admin health',
  group: paymentsGroup,
  environmentVariables: [
    {
      key: 'PAYMENTS_ADMIN_TOKEN',
      value: secret('PAYMENTS_ADMIN_TOKEN'),
      secret: true,
    },
  ],
  request: {
    method: 'GET',
    url: 'https://payments.example.com/admin/health',
    headers: [
      { key: 'Authorization', value: 'Bearer {{PAYMENTS_ADMIN_TOKEN}}' },
    ],
  },
})

secret('PAYMENTS_API_KEY') reads CHECKLY_SECRET_PAYMENTS_API_KEY when the CLI loads the project. The Key Vault name and the Checkly environment name do not need to match.

Deploy from GitHub Actions

This workflow installs project dependencies before authenticating to Azure. It retrieves named secrets with az keyvault secret show, masks each retrieved value, exports it only in the deployment shell, and does not write it to GITHUB_ENV.

.github/workflows/deploy-checkly.yml

name: Deploy Checkly

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    permissions:
      contents: read
      id-token: write
    env:
      AZURE_CORE_OUTPUT: none
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false

      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Sign in to Azure with OIDC
        uses: azure/login@v3
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: Load secrets and deploy
        shell: bash
        env:
          AZURE_KEY_VAULT: ${{ vars.AZURE_KEY_VAULT }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}
        run: |
          set -euo pipefail

          get_secret() {
            az keyvault secret show \
              --vault-name "$AZURE_KEY_VAULT" \
              --name "$1" \
              --query value \
              --output tsv
          }

          mask_secret() {
            local value="${1//%/%25}"
            value="${value//$'\r'/%0D}"
            value="${value//$'\n'/%0A}"
            printf '::add-mask::%s\n' "$value"
          }

          CHECKLY_API_KEY="$(get_secret checkly-api-key)"
          CHECKLY_SECRET_PAYMENTS_API_KEY="$(get_secret payments-api-key)"
          CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN="$(get_secret payments-admin-token)"

          mask_secret "$CHECKLY_API_KEY"
          mask_secret "$CHECKLY_SECRET_PAYMENTS_API_KEY"
          mask_secret "$CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN"

          export CHECKLY_API_KEY
          export CHECKLY_SECRET_PAYMENTS_API_KEY
          export CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN

          npx checkly deploy --force

The job grants only contents: read and id-token: write. The latter lets azure/login request a GitHub OIDC token; it does not grant repository write access. AZURE_CORE_OUTPUT: none prevents accidental Azure CLI output, while --output tsv explicitly returns only each requested value to the shell.

Do not print or persist fetched values. This example assumes token-like, single-line secret values.

Rotate a secret

Rotating a value in Azure Key Vault does not automatically update the copy stored by Checkly. Run this trusted deployment workflow again after rotation. The next deployment fetches the current value returned by Key Vault and updates the scoped Checkly secret.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Deploy Checkly secrets from Azure Key Vault

Configure Azure access

Map Key Vault secrets to Checkly

Deploy from GitHub Actions

Rotate a secret

​Configure Azure access

​Map Key Vault secrets to Checkly

​Deploy from GitHub Actions

​Rotate a secret

Configure Azure access

Map Key Vault secrets to Checkly

Deploy from GitHub Actions

Rotate a secret