cloudflare/wrangler-action

cloudflare/wrangler-action

Description: 🧙‍♀️ easily deploy cloudflare workers applications using wrangler and github actions

Language: TypeScript

License: Apache-2.0

Stars: 1865

Forks: 210

Open issues: 56

Created: 2019-10-07T19:42:01Z

Pushed: 2026-05-12T20:35:04Z

Default branch: main

Fork: no

Archived: no

README:

Wrangler GitHub Action

Easy-to-use GitHub Action to use Wrangler. Makes deploying Workers a breeze.

Wrangler v3 Support

The action now defaults to Wrangler v4. If you need to stay on Wrangler v3, you can pin the version explicitly:

- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
wranglerVersion: "3.90.0"

Big Changes in v3

• Wrangler v1 is no longer supported.
• Global API key & Email Auth no longer supported
• Action version syntax is newly supported. This means e.g. uses: cloudflare/wrangler-action@v3, uses: cloudflare/wrangler-action@v3.x, and uses: cloudflare/wrangler-action@v3.x.x are all now valid syntax. Previously supported syntax e.g. uses: cloudflare/wrangler-action@3.x.x is no longer supported -- the prefix v is now necessary.

[Refer to Changelog for more information](CHANGELOG.md).

Usage

Add wrangler-action to the workflow for your Workers/Pages application. The below example will deploy a Worker on a git push to the main branch:

name: Deploy

on:
push:
branches:
- main

jobs:
deploy:
runs-on: ubuntu-latest
name: Deploy
steps:
- uses: actions/checkout@v6
- name: Deploy
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Authentication

You'll need to configure Wrangler using GitHub's Secrets feature - go to "Settings -> Secrets" and add your Cloudflare API token (for help finding this, see the Workers documentation). Your API token is encrypted by GitHub, and the action won't print it into logs, so it should be safe!

With your API token set as a secret for your repository, pass it to the action in the with block of your workflow. Below, I've set the secret name to CLOUDFLARE_API_TOKEN:

jobs:
deploy:
name: Deploy
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Configuration

You can pass wranglerVersion to install a specific version of Wrangler from NPM. This accepts any version format NPM understands: an exact version like 4.81.0, a major version like 4, a range like ^4.0.0 or 4.x, or latest.

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
wranglerVersion: "4"

If you omit wranglerVersion and Wrangler is already installed in your environment, the action uses the existing installation. If Wrangler is not installed, the action installs a default version.

Optionally, you can also pass a workingDirectory key to the action. This will allow you to specify a subdirectory of the repo to run the Wrangler command from.

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
workingDirectory: "subfoldername"

Worker secrets can optionally be passed in via secrets as a string of names separated by newlines. Each secret name must match the name of an environment variable specified in the env field. This creates or replaces the value for the Worker secret using the wrangler secret put command. It's also possible to specify worker environment using environment parameter.

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
environment: production
secrets: |
SECRET1
SECRET2
env:
SECRET1: ${{ secrets.SECRET1 }}
SECRET2: ${{ secrets.SECRET2 }}

If you need to run additional shell commands before or after your command, you can specify them as input to preCommands (before deploy) or postCommands (after deploy). These can include additional wrangler commands (that is, whoami, kv:key put) or any other commands available inside the wrangler-action context.

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
preCommands: echo "*** pre command ***"
postCommands: |
echo "*** post commands ***"
wrangler kv:key put --binding=MY_KV key2 value2
echo "******"

You can use the command option to do specific actions such as running wrangler whoami against your project:

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: whoami

You can also add a command that spans multiple lines:

jobs:
deploy:
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: |
pages project list
pages deploy .vercel/output/static --project-name=demo-actions --branch=test

Use cases

Deploy when commits are merged to main

The above workflow examples have already shown how to run wrangler-action when new commits are merged to the main branch. For most developers, this workflow will easily replace manual deploys and be a great first integration step with wrangler-action:

on:
push:
branches:
- main

jobs:
deploy:
runs-on: ubuntu-latest
name: Deploy
steps:
- uses: actions/checkout@v6
- name: Deploy
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Note that there are a number of possible events, like push, that can be used to trigger a workflow. For more details on the events available, refer to the GitHub Actions documentation.

Deploy your Pages site (production & preview)

If you want to deploy your Pages project with GitHub Actions rather than the built-in continous integration (CI), then this is a great way to do it. Wrangler 2 will populate the commit message and branch for you. You only need to pass the project name. If a push to a non-production branch is done, it will deploy as a preview deployment:

on: [push]

jobs:
deploy:
runs-on: ubuntu-latest
name: Deploy
permissions:
contents: read
deployments: write
steps:
- uses: actions/checkout@v6
- name: Deploy
uses:…