> ## 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 Google Secret Manager

> Use GitHub OIDC to fetch Google Secret Manager values and deploy them as scoped Checkly secrets.

Use Workload Identity Federation to authenticate a trusted GitHub Actions deployment to Google Cloud without storing a service account key in GitHub. The workflow fetches only the values its Checkly project needs and exposes them to the Checkly deploy step.

For guidance on choosing account, group, or check scope, see [Manage secrets at scale](/docs/platform/manage-secrets-at-scale).

<Accordion title="Prerequisites">
  * A Checkly Monitoring as Code project with its dependencies and lockfile committed.
  * `CHECKLY_ACCOUNT_ID` stored as a GitHub Actions variable.
  * The Checkly API key and required deployment values stored as enabled secret versions in Google Secret Manager.
  * A Google Cloud project with the IAM, Resource Manager, Service Account Credentials, Security Token Service, and Secret Manager APIs enabled.
  * Permission to configure Workload Identity Federation, service account impersonation, and IAM access on the required secrets.
</Accordion>

<Info>
  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 `GCP_*` variables configure this workflow.
</Info>

## Configure Google Cloud access

Follow Google's [deployment pipeline guide](https://cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines) or the [`google-github-actions/auth` instructions](https://github.com/google-github-actions/auth#workload-identity-federation-through-a-service-account) to configure Workload Identity Federation and a dedicated service account.

Restrict the Workload Identity Provider to the repository and ref that deploy Checkly. Grant the repository principal `roles/iam.workloadIdentityUser` on the service account, then grant that service account `roles/secretmanager.secretAccessor` only on the secrets listed in the workflow.

Add these non-secret values as GitHub Actions variables:

| Variable                         | Value                                                                                   |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| `GCP_PROJECT_ID`                 | The project ID that contains the secrets.                                               |
| `GCP_WORKLOAD_IDENTITY_PROVIDER` | The full provider resource name, including the project **number** and `/providers/...`. |
| `GCP_SERVICE_ACCOUNT`            | The dedicated deployment service account email.                                         |

## Scope secrets in your constructs

Read each value with `secret()` and mark it as secret on the group or check that needs it:

```typescript __checks__/payments.check.ts theme={null}
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', {
  name: 'Payments admin',
  group: paymentsGroup,
  environmentVariables: [
    {
      key: 'PAYMENTS_ADMIN_TOKEN',
      value: secret('PAYMENTS_ADMIN_TOKEN'),
      secret: true,
    },
  ],
  request: {
    method: 'GET',
    url: 'https://payments.example.com/admin',
    headers: [
      { key: 'Authorization', value: 'Bearer {{PAYMENTS_ADMIN_TOKEN}}' },
    ],
  },
})
```

The helper reads `CHECKLY_SECRET_PAYMENTS_API_KEY` and `CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN` when the project is loaded for deployment. If a required value is missing, `secret()` stops the deployment instead of deploying an empty value. Checkly then stores each value at the declared scope.

## Fetch and deploy from GitHub Actions

The Google Secret Manager action returns masked step outputs. Map those outputs to `CHECKLY_SECRET_*` variables only on the deploy step:

<Note>
  Google maintains `get-secretmanager-secrets` in the `google-github-actions` organization, but its README states that it is not an officially supported Google Cloud product and is not covered by a Google Cloud support contract.
</Note>

```yaml .github/workflows/deploy-checkly.yml theme={null}
name: Deploy Checkly

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

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

      - run: npm ci

      - id: google-auth
        name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v3
        with:
          project_id: ${{ vars.GCP_PROJECT_ID }}
          workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - id: google-secrets
        name: Fetch deployment secrets
        uses: google-github-actions/get-secretmanager-secrets@v3
        with:
          secrets: |-
            checkly_api_key:${{ vars.GCP_PROJECT_ID }}/checkly-api-key
            payments_api_key:${{ vars.GCP_PROJECT_ID }}/payments-api-key
            payments_admin_token:${{ vars.GCP_PROJECT_ID }}/payments-admin-token

      - name: Deploy Checkly
        run: npx checkly deploy --force
        env:
          CHECKLY_API_KEY: ${{ steps.google-secrets.outputs.checkly_api_key }}
          CHECKLY_ACCOUNT_ID: ${{ vars.CHECKLY_ACCOUNT_ID }}
          CHECKLY_SECRET_PAYMENTS_API_KEY: ${{ steps.google-secrets.outputs.payments_api_key }}
          CHECKLY_SECRET_PAYMENTS_ADMIN_TOKEN: ${{ steps.google-secrets.outputs.payments_admin_token }}
```

The `id-token: write` permission lets the job request a GitHub OIDC token. Google Cloud IAM still determines which secrets it can read.

<Warning>
  Do not print or persist fetched values. Expose the outputs only to the Checkly
  deployment step.
</Warning>

## Rotate a secret

The short secret names in the workflow fetch the `latest` enabled version. After you add a new version in Google Secret Manager, run this deployment workflow again to update the encrypted value stored by Checkly. Rotation in Google Cloud alone does not update an already deployed Checkly secret.

When the workflow no longer needs a value, remove it from the construct, workflow mapping, and service account IAM policy.