> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Checkly secrets from AWS Secrets Manager

> Use GitHub Actions and OIDC to deploy scoped 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](/docs/platform/manage-secrets-at-scale).

<Accordion title="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.
</Accordion>

<Info>
  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.
</Info>

## Configure AWS access

Follow AWS's guide for [using Secrets Manager in GitHub jobs](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_github.html) 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:

```typescript checks/payments.check.ts theme={null}
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.

```yaml .github/workflows/checkly-deploy.yml theme={null}
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.

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

## 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.