Deploy Checkly secrets from AWS Secrets Manager

Use GitHub OpenID Connect (OIDC) to obtain short-lived AWS credentials, read the secrets required by one Checkly CLI project, and deploy them as group- or check-level secrets. For the architecture and scoping model, see Manage secrets at scale.

Prerequisites

A Checkly CLI project with checkly installed as a dependency.
An AWS account with your values stored in AWS Secrets Manager.
A GitHub repository with Actions enabled.
A protected GitHub environment named checkly-production. Restrict its deployment branches and reviewers as appropriate.
The repository or environment variables AWS_ROLE_ARN, AWS_REGION, and CHECKLY_ACCOUNT_ID.
Permission to create an AWS IAM OIDC provider and role.

This guide uses a fictional payments service; replace its names, paths, and URL with your own application values. Checkly requires CHECKLY_API_KEY and CHECKLY_ACCOUNT_ID; AWS_ROLE_ARN and AWS_REGION configure this workflow.

Configure AWS access

Follow AWS’s guide for using Secrets Manager in GitHub jobs to create an OIDC provider and IAM role. Restrict the role’s trust policy to the repository and protected GitHub environment that deploy Checkly. Grant the role secretsmanager:GetSecretValue only for the secrets listed in this workflow. The retrieval action also requires secretsmanager:ListSecrets; secrets encrypted with a customer-managed KMS key require kms:Decrypt on that key. Store the role ARN and region in AWS_ROLE_ARN and AWS_REGION GitHub Actions variables.

Scope secrets in your constructs

Use secret() to read CHECKLY_SECRET_* from the deploy process. Set secret: true so Checkly stores the value as a non-retrievable secret. Attach each value at the narrowest level that needs it:

checks/payments.check.ts

import { ApiCheck, CheckGroupV2, Frequency } from "checkly/constructs";
import { secret } from "checkly/util";

const paymentsGroup = new CheckGroupV2("payments", {
  name: "Payments",
  activated: true,
  muted: false,
  frequency: Frequency.EVERY_10M,
  locations: ["us-east-1"],
  environmentVariables: [
    {
      key: "PAYMENTS_API_KEY",
      value: secret("PAYMENTS_API_KEY"),
      secret: true,
    },
  ],
});

new ApiCheck("payments-admin-api", {
  name: "Payments admin API",
  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_API_KEY}}" },
      { key: "X-Admin-Token", value: "{{PAYMENTS_ADMIN_TOKEN}}" },
    ],
  },
});

secret('PAYMENTS_API_KEY') reads CHECKLY_SECRET_PAYMENTS_API_KEY during deployment and fails if it is missing. The shorter key PAYMENTS_API_KEY is what your check receives at runtime.

Fetch and deploy in GitHub Actions

Fetch each AWS secret with an explicit CHECKLY_SECRET_* alias. The retrieval action masks the values and adds them to the environment of subsequent steps.

.github/workflows/checkly-deploy.yml

name: Deploy Checkly

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: checkly-production
    permissions:
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@v7

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

      - name: Install dependencies
        run: npm ci

      - name: Authenticate to AWS
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}
          allowed-account-ids: "123456789012"
          mask-aws-account-id: true
          role-session-name: checkly-${{ github.run_id }}

      - name: Fetch deployment secrets
        uses: aws-actions/aws-secretsmanager-get-secrets@v3
        with:
          secret-ids: |
            CHECKLY_API_KEY, checkly/production/api-key
            CHECKLY_SECRET_PAYMENTS_API_KEY, checkly/production/payments-api-key
            CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN, checkly/production/payments-admin-token

      - name: Deploy Checkly
        env:
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}
        run: npx checkly deploy --force

Install dependencies before fetching secrets, and keep deployment as the final step. Values created by aws-secretsmanager-get-secrets are available to every later step in the job, not only the deploy command.

Do not print or persist fetched values. Keep deployment as the final step that receives them.

Rotate a secret

When you rotate a value in AWS Secrets Manager, run this workflow again. Checkly receives a copy during checkly deploy; rotation in AWS does not update an already deployed Checkly secret automatically.

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Deploy Checkly secrets from AWS Secrets Manager

Configure AWS access

Scope secrets in your constructs

Fetch and deploy in GitHub Actions

Rotate a secret

​Configure AWS access

​Scope secrets in your constructs

​Fetch and deploy in GitHub Actions

​Rotate a secret

Configure AWS access

Scope secrets in your constructs

Fetch and deploy in GitHub Actions

Rotate a secret