Skip to content

Update README for accuracy and completeness #422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vliggio wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README for accuracy and completeness #422

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 116 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,16 @@
# Wrangler GitHub Action

Easy-to-use GitHub Action to use [Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/). Makes deploying Workers a breeze.
Easy-to-use GitHub Action to use [Wrangler](https://developers.cloudflare.com/workers/wrangler/). Makes deploying Workers a breeze.

## Wrangler v3 Support
## Migrating from v2

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

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

## Big Changes in v3
If you are upgrading from v2, note the following breaking changes:

- 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.
- Global API key & Email Auth are no longer supported.
- The action version must be prefixed with `v` (e.g. `uses: cloudflare/wrangler-action@v3`). The older `@3.x.x` syntax without the `v` prefix is no longer valid.

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

## Usage

Expand Down Expand Up @@ -49,16 +40,18 @@ jobs:

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](https://developers.cloudflare.com/workers/wrangler/ci-cd/#api-token)). 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`:
With your API token set as a secret for your repository, pass it to the action in the `with` block of your workflow. In the example below, the secret name is set to `CLOUDFLARE_API_TOKEN`:

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

## Configuration
Expand All @@ -68,11 +61,13 @@ You can pass `wranglerVersion` to install a specific version of Wrangler from NP
```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
wranglerVersion: "4"
- uses: actions/checkout@v4
- 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.
Expand All @@ -82,71 +77,114 @@ Optionally, you can also pass a `workingDirectory` key to the action. This will
```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
workingDirectory: "subfoldername"
```

If you want to suppress Wrangler's command output in your workflow logs, set `quiet` to `true`:

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
quiet: true
```

[Worker secrets](https://developers.cloudflare.com/workers/wrangler/commands/#secret) 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. You can also specify a Worker environment using the `environment` parameter.

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
workingDirectory: "subfoldername"
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
environment: production
secrets: |
SECRET1
SECRET2
env:
SECRET1: ${{ secrets.SECRET1 }}
SECRET2: ${{ secrets.SECRET2 }}
```

[Worker secrets](https://developers.cloudflare.com/workers/tooling/wrangler/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.
Similarly, you can pass environment variables to bind to your Worker as plaintext `vars`. Each variable name must match the name of an environment variable declared in the `env` field of the workflow:

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
environment: production
secrets: |
SECRET1
SECRET2
env:
SECRET1: ${{ secrets.SECRET1 }}
SECRET2: ${{ secrets.SECRET2 }}
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
vars: |
APP_ENV
LOG_LEVEL
env:
APP_ENV: "production"
LOG_LEVEL: "info"
```

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

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
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 "******"
- uses: actions/checkout@v4
- 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:

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: whoami
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
command: whoami
```

You can also add a command that spans multiple lines:

```yaml
jobs:
deploy:
runs-on: ubuntu-latest
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
- uses: actions/checkout@v4
- 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
Expand Down Expand Up @@ -177,7 +215,7 @@ Note that there are a number of possible events, like `push`, that can be used t

### 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:
If you want to deploy your Pages project with GitHub Actions rather than the built-in continuous integration (CI), then this is a great way to do it. Wrangler 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:

```yaml
on: [push]
Expand Down Expand Up @@ -259,7 +297,7 @@ To create a new version of your Worker that is not deployed immediately, use the
jobs:
upload:
runs-on: ubuntu-latest
name: Deploy
name: Upload Worker Version
steps:
- uses: actions/checkout@v6
- name: Upload Worker Version
Expand Down Expand Up @@ -353,6 +391,19 @@ Resulting in:
https://new-feature.<your_pages_site>.pages.dev
```

For Pages deployments, two additional output variables are available (since Wrangler v3.81.0):

- `pages-deployment-id` — the ID of the Pages deployment.
- `pages-environment` — the environment of the Pages deployment (e.g. `production` or `preview`).

```yaml
- name: print pages deployment info
env:
DEPLOYMENT_ID: ${{ steps.deploy.outputs.pages-deployment-id }}
PAGES_ENV: ${{ steps.deploy.outputs.pages-environment }}
run: echo "Deployment $DEPLOYMENT_ID to $PAGES_ENV"
```

### Using a different package manager

By default, this action will detect which package manager to use, based on the presence of a `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb`/`bun.lock` file.
Expand All @@ -362,11 +413,13 @@ If you need to use a specific package manager for your application, you can set
```yaml
jobs:
deploy:
runs-on: ubuntu-latest
steps:
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
packageManager: pnpm
- uses: actions/checkout@v4
- uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
packageManager: pnpm
```

## Troubleshooting
Expand Down