Cloudflare Preview URL

Retrieve the preview/deployment URL from the Cloudflare API, filtered by the repository and branch. The URL can then be used for further end-to-end tests, link checks and other PR integrations/actions.

Usage

API Token (recommended)

Navigate to the Cloudflare API Tokens page and create a new token with the following permissions:

• Account - Cloudflare Pages - Read
• Include - [your page]

Copy the token and add it to your repository secrets as CLOUDFLARE_API_TOKEN.

Global API Key (legacy)

If you cannot use an API Token, you can authenticate with a Global API Key. Set your Global API Key as CLOUDFLARE_API_TOKEN and also add CLOUDFLARE_ACCOUNT_EMAIL with your Cloudflare account email. Do not mix these — if you're using an API Token, leave CLOUDFLARE_ACCOUNT_EMAIL unset.

Workflow template

name: Cloudflare Preview URL
on:
  push:
    branches:
      - '**'
      - '!main'

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4

      # Optional: Add a sleep action to wait until the deployment is ready
      # or use wait_until_ready: true below
      - run: sleep 30

      - name: Get Cloudflare Preview URL
        uses: zentered/cloudflare-preview-url@v1
        id: cloudflare_preview_url
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        with:
          cloudflare_project_id: 'your-project-name'
          wait_until_ready: true

      - name: Use Preview URL
        run: echo "Preview URL: ${{ steps.cloudflare_preview_url.outputs.preview_url }}"

Environment Variables / Secrets

In your repository, go to "Settings" → "Secrets and variables" → "Actions" and add the following secrets:

Required Secrets

• CLOUDFLARE_API_TOKEN - Your Cloudflare API token (see API Token setup above)
• CLOUDFLARE_ACCOUNT_ID - Your Cloudflare Account ID (find it in the URL: https://dash.cloudflare.com/[account-id]/...)

Optional Secrets

• CLOUDFLARE_ACCOUNT_EMAIL - Your Cloudflare account email address (only for Global API Key authentication)

⚠️ Important: Only set CLOUDFLARE_ACCOUNT_EMAIL if you are using a Global API Key. When this variable is present, the action switches from Bearer token authentication to API Key authentication. If you set CLOUDFLARE_ACCOUNT_EMAIL while using an API Token, authentication will fail. If you're using the recommended API Token approach, do not set CLOUDFLARE_ACCOUNT_EMAIL.

Inputs

Name	Requirement	Default	Description
cloudflare_project_id	required	-	Cloudflare Pages project name (found in your Cloudflare Pages dashboard)
wait_until_ready	optional	false	Wait until the Cloudflare deployment is ready before returning the URL
environment	optional	preview	Filter by deployment environment (preview or production). Set to empty string to include all environments
commit_hash	optional	-	Filter deployments by commit hash. Useful when the same branch has multiple deployments
branch	optional	auto-detect	Override branch name for filtering. By default, uses the branch from the GitHub context

Outputs

Name	Description
preview_url	A string with the unique URL of the deployment. Always set when a deployment is found, regardless of deployment status

Example Use Cases

• End-to-end Testing: Use the preview URL to run automated tests against your deployment
• Visual Regression Testing: Integrate with tools like Percy, Chromatic, or BackstopJS
• Link Checking: Validate that all links work in your preview deployment
• Performance Testing: Run Lighthouse or other performance audits
• Notifications: Comment the preview URL on pull requests or send to Slack

Compatibility

This action uses the official Cloudflare TypeScript SDK v5 and is compatible with:

• Node.js 20+
• Cloudflare Pages API v4
• Both API Token (recommended) and Global API Key authentication

Contributing

See CONTRIBUTING.

License

See LICENSE.