diff --git a/public/_redirects b/public/_redirects index 2c1c4853aac576..2de3abd3091f8b 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1434,7 +1434,7 @@ /workers/runtime-apis/webgpu/ /durable-objects/api/webgpu/ 301 /workers/runtime-apis/websockets/use-websockets/ /workers/examples/websockets/ 301 /workers/runtime-apis/websockets/websockets/ /workers/runtime-apis/websockets/ 301 -/workers/learning/continuous-integration/ /workers/configuration/continuous-integration/ 301 +/workers/learning/continuous-integration/ /workers/ci-cd/ 301 /workers/learning/security-model/ /workers/reference/security-model/ 301 /workers/runtime-apis/R2/ /workers/runtime-apis/bindings/R2/ 301 /workers/runtime-apis/durable-objects/ /durable-objects/api/ 301 @@ -1444,6 +1444,8 @@ /workers/runtime-apis/service-bindings/ /workers/runtime-apis/bindings/service-bindings/ 301 /workers/observability/local-development-and-testing/ /workers/testing/local-development/ 301 /workers/configuration/deployments/ /workers/configuration/versions-and-deployments/ 301 +/workers/configuration/continuous-integration/ /workers/ci-cd/ 301 +/workers/wrangler/ci-cd/ /workers/ci-cd/external-cicd/ 301 /workers/tutorials/hello-world-rust/ /workers/tutorials/ 301 /workers/tutorials/introduction-to-cloudflare-workers/ https://www.youtube.com/watch?v=H7Qe96fqg1M 301 /workers/configuration/bindings/about-service-bindings/ /workers/runtime-apis/bindings/service-bindings/ 301 diff --git a/src/assets/images/workers/platform/ci-cd/workers-builds-workflow.png b/src/assets/images/workers/platform/ci-cd/workers-builds-workflow.png new file mode 100644 index 00000000000000..0684dc07ff99d6 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/workers-builds-workflow.png differ diff --git a/src/content/changelogs/workers.yaml b/src/content/changelogs/workers.yaml index d338e5c722ddc1..e4f8db7a43880c 100644 --- a/src/content/changelogs/workers.yaml +++ b/src/content/changelogs/workers.yaml @@ -5,6 +5,9 @@ productLink: "/workers/" productArea: Developer platform productAreaLink: /workers/platform/changelog/platform/ entries: + - publish_date: "2024-09-26" + description: |- + - You can now connect your GitHub or GitLab repository to an existing Worker to automatically build and deploy your changes when you make a git push with [Workers Builds](/workers/ci-cd/builds/). - publish_date: "2024-09-19" description: |- - Revamped Workers and Pages UI settings to simplify the creation and management of project configurations. For bugs and general feedback, please submit this [form](https://forms.gle/XXqhRGbZmuzninuN9). diff --git a/src/content/docs/pages/configuration/build-image.mdx b/src/content/docs/pages/configuration/build-image.mdx index 5af4535aa94ab1..007736c54f04b0 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/src/content/docs/pages/configuration/build-image.mdx @@ -51,14 +51,14 @@ When your build starts, if not already [cached](/pages/configuration/build-cachi To override default versions of languages and tools in the build system, you can either set the desired version through environment variables or by adding files to your project. -To set the version using **environment variables**, you can: +To set the version using environment variables, you can: 1. Find the environment variable name for the language or tool in [this table](/pages/configuration/build-image/#supported-languages-and-tools). 2. Add the environment variable on the dashboard by going to **Settings** > **Environmnet variables** in your Pages project, or [add the environment variable via Wrangler](/workers/configuration/environment-variables/#add-environment-variables-via-wrangler). -Or, to set the version by **adding a file** to your project, you can: +Or, to set the version by adding a file to your project, you can: -1. Find the environment variable name for the language or tool in [this table](/pages/configuration/build-image/#supported-languages-and-tools). +1. Find the file name for the language or tool in [this table](/pages/configuration/build-image/#supported-languages-and-tools). 2. Add the specified file name to the root directory of your project, and add the desired version number as the contents of the file. For example, if you were previously relying on the default version of Node.js in the v1 build system, to migrate to v2, you must specify that you need Node.js `12.18.0` by setting a `NODE_VERSION = 12.18.0` environment variable or by adding a `.node-version` or `.nvmrc` file to your project with `12.18.0` added as the contents to the file. diff --git a/src/content/docs/pages/configuration/git-integration.mdx b/src/content/docs/pages/configuration/git-integration.mdx index a456af90307042..132cc91f444f48 100644 --- a/src/content/docs/pages/configuration/git-integration.mdx +++ b/src/content/docs/pages/configuration/git-integration.mdx @@ -1,19 +1,22 @@ --- pcx_content_type: concept title: Git integration - --- Cloudflare supports connecting Cloudflare Pages to your GitHub and GitLab repositories to look for new changes to your project. Pages does not currently support self-hosted instances of GitHub or GitLab. ## Custom branches -Suppose you have a custom Git workflow that uses specific branches to represent your project's production build. In that case, you can specify a custom branch when creating (or managing an existing) project in the Pages dashboard by going to **Settings** > **Builds & deployments** and clicking the **Configure Production deployments** button. You can change the production branch to any other branch in the dropdown menu under **production branch**. +Suppose you have a custom Git workflow that uses specific branches to represent your project's production build. In that case, you can specify a custom branch when creating (or managing an existing) project in the Pages dashboard by going to **Settings** > **Builds & deployments** > **Configure Production deployments**. To change the production branch, click the **production branch** dropdown menu and choose any other branch. You can also use [preview deployments](/pages/configuration/preview-deployments/) to preview how the new version of your project looks before merging into `production`. In addition, Pages allows you to configure which of your preview branches are built and deployed by using [branch build controls](/pages/configuration/branch-build-controls/). To configure this in your Pages project go to **Settings** > **Builds & deployments** > **Configure preview deployment** and select **Custom branches**. Here you can specify branches you wish to include and exclude from automatic deployments in the provided configuration fields. To learn more refer to the [branch build controls](/pages/configuration/branch-build-controls/) documentation. +## Skipping a specific build via a commit message + +Without any configuration required, you can choose to skip a deployment on an adhoc basis. By adding the `[CI Skip]`, `[CI-Skip]`, `[Skip CI]`, `[Skip-CI]`, or `[CF-Pages-Skip]` flag as a prefix in your commit message, and Pages will omit that deployment. The prefixes are not case sensitive. + ## Organizational access You can deploy projects to Cloudflare Pages from your open-source team, company, or side project on both GitHub and GitLab. @@ -24,27 +27,27 @@ When authorizing Cloudflare Pages to access a GitHub account, you can specify ac :::caution[GitHub security consideration] - A GitHub account should only point to one Cloudflare account, however, this is not enforced. If you are setting up Cloudflare with GitHub for your organization, Cloudflare recommends that you limit the scope of the application to only the repositories you intend to build with Pages at the time that you set up your project. You can modify these permissions as you build more applications. - ::: ### GitLab By authorizing Cloudflare Pages to access your GitLab account, you will automatically allow access to organizations, groups, and namespaces your GitLab account can access for use by Cloudflare Pages. Managing access to these organizations and groups is handled by GitLab. -## Removing access to your GitHub account +## Removing access -You can remove Cloudflare Pages' access to your GitHub account by viewing the [**Applications** page](https://github.com/settings/installations) on GitHub. Note that removing access to GitHub will also disable new builds, though the last build of your site will continue to be hosted via Cloudflare Pages. +### GitHub -## Removing access to your GitLab account +You can remove Cloudflare Pages' access to your GitHub account by viewing the [**Applications** page](https://github.com/settings/installations) on GitHub. The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects. -You can remove Cloudflare Pages' access to your GitLab account by navigating to **User Settings** > **Applications** > **Authorized Applications**. Find the applications called Cloudflare Pages and select the **Revoke** button to revoke access. +Note that removing access to GitHub will disable new builds for Workers and Pages, though the last build of your site will continue to be hosted via Cloudflare Pages. -## Skipping a specific build via a commit message +### GitLab -Without any configuration required, you can choose to skip a deployment on an adhoc basis. By adding the `[CI Skip]`, `[CI-Skip]`, `[Skip CI]`, `[Skip-CI]` or `[CF-Pages-Skip]` flag as a prefix in your commit message, and Pages will omit that deployment. The prefixes are case insensitive. +You can remove Cloudflare Pages' access to your GitLab account by navigating to **User Settings** > **Applications** > **Authorized Applications**. Find the applications called Cloudflare Pages and select the **Revoke** button to revoke access. + +Note that the GitLab application Cloudflare Pages is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though the last build of your site will continue to be hosted via Cloudflare Pages. ## Reinstall a Git installation @@ -55,7 +58,7 @@ When encountering Git integration related issues, one potential troubleshooting 1. Go to the installation settings page on GitHub: 1. `https://github.com/settings/installations` for individual accounts. 2. `https://github.com/organizations//settings/installations` for organizational accounts. -2. If the Cloudflare Pages installation is there, click **Configure**, and click **Uninstall "Cloudflare Pages"** (if there is no "Cloudflare Pages" installation, the user doesn't need to do anything) +2. If the Cloudflare Workers and Pages installation is there, click **Configure**, and click **Uninstall "Cloudflare Workers and Pages"**. If there is no "Cloudflare Workers and Pages" installation there, then you don't need to do anything. 3. Go back to the **Workers & Pages** overview page at `https://dash.cloudflare.com/[YOUR_ACCOUNT_ID]/workers-and-pages`. Click **Create application** > **Pages** > **Connect to Git** 4. Click the **+ Add account** button, click the GitHub account you want to add, and then click **Install & Authorize**. 5. You should be redirected to the create project page with your GitHub account or organization in the account list. @@ -67,7 +70,7 @@ When encountering Git integration related issues, one potential troubleshooting 2. Click the "Revoke" button on your Cloudflare Pages installation if it exists. 3. Go back to the **Workers & Pages** overview page at `https://dash.cloudflare.com/[YOUR_ACCOUNT_ID]/workers-and-pages`. Click **Create application** > **Pages** > **Connect to Git** 4. Select the **GitLab** tab at the top, click the **+ Add account** button, click the GitLab account you want to add, and then click **Authorize** on the modal titled "Authorize Cloudflare Pages to use your account?". -5. You should be redirected to the create project page with your GitHub account or organization in the account list. +5. You will be redirected to the create project page with your GitLab account or organization in the account list. 6. Attempt to make a new deployment with your project which was previously broken. ## Troubleshooting @@ -98,8 +101,8 @@ To resolve this issue, follow the steps provided above in the [Reinstalling a Gi Go to your GitHub installation settings: -* `https://github.com/settings/installations` for individual accounts -* `https://github.com/organizations//settings/installations` for organizational accounts +- `https://github.com/settings/installations` for individual accounts +- `https://github.com/organizations//settings/installations` for organizational accounts Click **Configure** on the Cloudflare Pages application. Scroll down to the bottom of the page and click **Unsuspend** to allow Cloudflare Pages to make future deployments. @@ -109,10 +112,10 @@ You may have deleted or transferred the repository associated with this Cloudfla #### `The repository cannot be accessed, this may cause deployments to fail.` -You may have excluded this repository from your installation's repository access settings. Go to your GitHub installation settings: +You may have excluded this repository from your installation's repository access settings. Go to your GitHub installation settings: -* `https://github.com/settings/installations` for individual accounts -* `https://github.com/organizations//settings/installations` for organizational accounts +- `https://github.com/settings/installations` for individual accounts +- `https://github.com/organizations//settings/installations` for organizational accounts Click **Configure** on the Cloudflare Pages application. Under **Repository access**, ensure that the repository associated with your Cloudflare Pages project is included in the list. @@ -122,4 +125,4 @@ This is an internal error in the Cloudflare Pages SCM system. You can attempt to ## Related resources -* [Branch build controls](/pages/configuration/branch-build-controls/#production-branch-control) - Control which environments and branches you would like to automatically deploy to. +- [Branch build controls](/pages/configuration/branch-build-controls/#production-branch-control) - Control which environments and branches you would like to automatically deploy to. diff --git a/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx b/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx new file mode 100644 index 00000000000000..7dd4cd7ec2377f --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx @@ -0,0 +1,66 @@ +--- +pcx_content_type: reference +title: Advanced Setups +description: Learn how to use Workers Builds with more advanced setups +sidebar: + order: 5 +--- + +## Monorepos + +While the Workers Builds beta has limited support for monorepos, it is still possible to set up a monorepo workflow. In the Cloudflare Dashboard, you must connect your monorepo to each of the existing Worker projects. When a new commit is detected in the monorepo, a new build/deploy will trigger for each Worker. + +### Example + +In the example `ecommerce-monorepo`, a Workers project should be created for `product-service`, `auth-service`, `order-service`, and `notification-service`. + +A git connection to `ecommerce-monorepo` should be added in all of the Workers projects. If you are using a monorepo tool (e.g. [Turborepo](https://turbo.build/)), you can configure a different deploy command for each Worker (e.g. `turbo deploy -F product-service`). When a new commit is made to `ecommerce-monorepo`, a build and deploy will be triggered for each of the Workers (i.e. `product-service`, `auth-service`, `order-service`, `notification-service`) and respect the configured commands for that Worker. + +``` +ecommerce-monorepo/ +│ +├── workers/ +│ ├── product-service/ +│ │ ├── src/ +│ │ └── wrangler.toml +│ ├── auth-service/ +│ │ ├── src/ +│ │ └── wrangler.toml +│ ├── order-service/ +│ │ ├── src/ +│ │ └── wrangler.toml +│ └── notification-service/ +│ ├── src/ +│ └── wrangler.toml +├── shared/ +│ └── utils/ +└── README.md +``` + +## Wrangler environments + +If you are using [Wrangler Environments](/workers/wrangler/environments/), you can choose to continue using with Workers Builds with a bit of set up: + +1. [Deploy via Wrangler](/workers/wrangler/commands/#deploy) to create the Workers for your environments in the Dashboard, if you don't already have them. +2. Find the Workers for your environments. They are typically named `[name of Worker] - [environment name]`. +3. Connect your repository to each of the Workers for your environment. +4. In each of the Workers, edit your Wrangler deploy command to include the flag `--env: ` in the build configurations. + +When a new commit is detected in the repository, a new build/deploy will trigger for each associated Worker. + +### Example + +Imagine you have a Worker named `my-worker`, and you want to set up two environments `staging` and `production` set in the `wrangler.toml`. If you haven't already, you can deploy `my-worker` for each environment using the commands `wrangler deploy --env staging` and `wrangler deploy --env production`. + +In your Cloudflare Dashboard, you should find two Workers `my-worker-staging` and `my-worker-production`. A git connection to a `my-worker` git repository should be added to both of the environment Workers. In the build configurations of each environment Worker, edit the deploy commands to be `npx wrangler deploy --env staging` and `npx wrangler deploy --env production` respectively. + +```mermaid +graph TD + A[Git Repo for my-worker] --> |Connect| B[my-worker-staging] + A --> |Connect| C[my-worker-production] + + subgraph Cloudflare Dashboard + B + C + end +``` diff --git a/src/content/docs/workers/ci-cd/builds/build-image.mdx b/src/content/docs/workers/ci-cd/builds/build-image.mdx new file mode 100644 index 00000000000000..ebecf3cf9ba478 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/build-image.mdx @@ -0,0 +1,63 @@ +--- +pcx_content_type: reference +title: Build Image +description: Understand the build image used in Workers Builds. +sidebar: + order: 4 +--- + +Workers Builds uses a build image with support for a variety of languages and tools such as Node.js, Python, PHP, Ruby, and Go. + +## Supported Languages and Tools + +In the following table, review the preinstalled versions for languages and tools included in the Cloudflare Workers' build image, and the environment variables and/or files available for [overriding the preinstalled version](/workers/ci-cd/builds/build-image/#overriding-default-versions): + +| Tool | Default version | Environment variable | File | +| ----------- | ---------------- | -------------------- | ---------------------------- | +| **Go** | 1.23.0 | `GO_VERSION` | | +| **Node.js** | 22 | `NODE_VERSION` | .nvmrc, .node-version | +| **Python** | 3.12.5 | `PYTHON_VERSION` | .python-version, runtime.txt | +| **Ruby** | 3.3.5 | `RUBY_VERSION` | .ruby-version | +| **Bun** | 1.1.28 | `BUN_VERSION` | | +| **Hugo** | extended_0.134.3 | `HUGO_VERSION` | | + +The default versions will be updated regularly to the latest minor version. No major version updates will be made without notice. If you need a specific minor version, please specify it by overriding the default version. + +### Overriding Default Versions + +If you need to override a [specific version](/workers/ci-cd/builds/build-image/#overriding-default-versions) of a language or tool within the image, you can specify it as a [build environment variable](/workers/ci-cd/builds/configuration/#build-settings), or set the relevant file in your source code as shown above. + +To set the version using a build environment variables, you can: + +1. Find the environment variable name for the language or tool and desired version (e.g. `NODE_VERSION = 22`) +2. Add and save the environment variable on the dashboard by going to **Settings** > **Build** > **Build Variables and Secrets** in your Workers project + +Or, to set the version by adding a file to your project, you can: + +1. Find the filename for the language or tool (e.g. `.nvmrc`) +2. Add the specified file name to the root directory and set the desired version number as the file's content. For example, if the version number is 22, the file should contain '22'. + +## Pre-installed Packages + +In the following table, review the pre-installed packages in the build image. The packages are installed with `apt`, a package manager for Linux distributions. + +| | | | +| ----------------- | ----------------- | ----------------- | +| `curl` | `libbz2-dev` | `libreadline-dev` | +| `git` | `libc++1` | `libssl-dev` | +| `git-lfs` | `libdb-dev` | `libvips-dev` | +| `unzip` | `libgdbm-dev` | `libyaml-dev` | +| `autoconf` | `libgdbm6` | `tzdata` | +| `build-essential` | `libgbm1` | `wget` | +| `bzip2` | `libgmp-dev` | `zlib1g-dev` | +| `gnupg` | `liblzma-dev` | `zstd` | +| `libffi-dev` | `libncurses5-dev` | | + +## Build Environment + +Workers Builds are run in the following environment: + +| | | +| --------------------- | ------------ | +| **Build Environment** | Ubuntu 24.04 | +| **Architecture** | x86_64 | diff --git a/src/content/docs/workers/ci-cd/builds/configuration.mdx b/src/content/docs/workers/ci-cd/builds/configuration.mdx new file mode 100644 index 00000000000000..5176821a997b7b --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/configuration.mdx @@ -0,0 +1,32 @@ +--- +pcx_content_type: configuration +title: Configuration +description: Understand the different settings associated with your build. +sidebar: + order: 2 +--- + +When connecting your repository, you can configure how to build and deploy your Worker. + +## Build Settings + +Build settings can be found by navigating to **Settings** > **Build** within your Worker. Note that when you update and save build settings, the updated settings will be applied in your next build. The following configurations are available: + +| Setting | Description | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Git account** | Select the git account you would like to use. After initial connection, you can continue to use this git account for future projects. | +| **Git repository** | Choose the git repository you would like to connect your Worker to. | +| **Git branch** | Select the branch you would like Cloudflare to listen to for new commits. This will be defaulted to `main`. | +| **Build command** _(Optional)_ | Set a build command if your project requires a build step. This is necessary, for example, when using a front-end framework such as Astro or Remix. +| **Deploy command** | The deploy command lets you set the **specific** Wrangler command to deploy your Worker. Your deploy command will default to `npx wrangler deploy` but you may customize this command if for example you want to create a [version](/workers/configuration/versions-and-deployments/gradual-deployments/) of your Worker or just run `npm run deploy`. Workers Builds will use the Wrangler version set in your `package json`. | +| **Root directory** _(Optional)_ | Specify the root directory of your repository. The root directory describes where the build command will be run. | +| **API token** _(Optional)_ | By default, Cloudflare will automatically generate an API token for your account when using Workers Builds. Workers Builds will continue to use this API token for all subsequent projects and builds. Alternatively, you can [create your own API token](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/authentication/#generate-tokens), or select one that you already own. | +| **Build variables and secrets** _(Optional)_ | Add environment variables and secrets accessible only to your build. Build variables will not be accessible at runtime. If you would like to configure runtime variables you can do so in **Settings** > **Variables & Secrets** | + +:::note[API Token Permissions] +When you connect your Worker to a git repository and configure Workers Builds, Workers Builds will create an API token automatically with the following permissions: + +- **Account:** Account Settings (read), Workers Scripts (edit), Workers KV Storage (edit), Workers R2 Storage (edit) +- **Zone:** Workers Routes (edit) for all zones on the account +- **User:** User Details (read), Memberships (read) + ::: diff --git a/src/content/docs/workers/ci-cd/builds/git-integration.mdx b/src/content/docs/workers/ci-cd/builds/git-integration.mdx new file mode 100644 index 00000000000000..0ec7d8d1ffc981 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/git-integration.mdx @@ -0,0 +1,68 @@ +--- +pcx_content_type: configuration +title: Git Integration +description: Learn how to configure your git integration for Workers Builds +sidebar: + order: 3 +--- + +Cloudflare supports connecting Cloudflare Workers to your GitHub and GitLab repositories to look for new changes to your Worker. Workers does not currently support self-hosted instances of GitHub or GitLab, but you can use `wrangler deploy` with an [external CI/CD provider](/workers/ci-cd/external-cicd/). + +## Organizational access + +You can deploy projects to Cloudflare Workers from your open-source team, company, or side project on both GitHub and GitLab. + +### GitHub + +When authorizing Cloudflare Workers to access a GitHub account, you can specify access to your individual account or an organization that you belong to on GitHub. + +To add Cloudflare Workers installation to an organization, your user account must be an owner or have the appropriate role within the organization (i.e. the GitHub Apps Manager role). More information on these roles can be seen on [GitHub's documentation](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers). + +:::caution[GitHub security consideration] + +A GitHub account should only point to one Cloudflare account, however, this is not enforced. If you are setting up Cloudflare with GitHub for your organization, Cloudflare recommends that you limit the scope of the application to only the repositories you intend to build with Workers at the time that you set up your project. You can modify these permissions as you build more applications. + +::: + +### GitLab + +By authorizing Cloudflare Workers to access your GitLab account, you will automatically allow access to organizations, groups, and namespaces your GitLab account can access for use by Cloudflare Workers. Managing access to these organizations and groups is handled by GitLab. + +## Removing access + +### GitHub + +You can remove Cloudflare Workers' access to your GitHub account by viewing the [**Applications** page](https://github.com/settings/installations) on GitHub. The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects. + +Note that removing access to GitHub will disable new builds for Workers and Pages, though the last build of your project will continue to be hosted via Cloudflare Workers. + +### GitLab + +You can remove Cloudflare Workers' access to your GitLab account by navigating to **User Settings** > **Applications** > **Authorized Applications**. Find the applications called Cloudflare Pages and select the **Revoke** button to revoke access. + +Note that the GitLab application Cloudflare Pages is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though the last build of your project will continue to be hosted via Cloudflare Workers. + +## Reinstall a Git installation + +When encountering Git integration related issues, one potential troubleshooting step is attempting to uninstall and reinstall the GitHub or GitLab application associated with the Cloudflare Workers & Pages installation. The process for each Git provider is provided below. + +### GitHub + +1. Go to the installation settings page on GitHub: + 1. `https://github.com/settings/installations` for individual accounts. + 2. `https://github.com/organizations//settings/installations` for organizational accounts. +2. If the Cloudflare Workers and Pages installation is there, click **Configure**, and click **Uninstall "Cloudflare Workers and Pages"** (if there is no "Cloudflare Workers and Pages" installation, then no action is needed) +3. Go back to the **Workers & Pages** overview page. Select a Worker, then go to **Settings > Build**. +4. In the Build settings, either select the **GitHub button** to establish a GitHub connection, or select **Connect** then go to the Git Account dropdown and select **+ New GitHub Connection** +5. Click the **+ Add account** button, click the GitHub account you want to add, and then click **Install & Authorize**. +6. You should be redirected to the create project page with your GitHub account or organization in the account list. +7. Attempt to make a new deployment with your project which was previously broken. + +### GitLab + +1. Go to your application settings page on GitLab located here: [https://gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications) +2. Click the "Revoke" button on your Cloudflare Pages installation if it exists. +3. Go back to the **Workers & Pages** overview page. Select a Worker, then go to **Settings > Build**. +4. In the Build settings, either select the **GitLab button** to establish a GitLab connection, or select **Connect** then go to the Git Account dropdown and select **+ New GitLab Connection** +5. You should be redirected to the create project page with your GitLab account or organization in the account list. +6. Attempt to make a new deployment with your project which was previously broken. diff --git a/src/content/docs/workers/ci-cd/builds/index.mdx b/src/content/docs/workers/ci-cd/builds/index.mdx new file mode 100644 index 00000000000000..f323719c6a380b --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/index.mdx @@ -0,0 +1,25 @@ +--- +pcx_content_type: concept +title: Builds +description: Use Workers Builds to integrate with Git and automatically build and deploy your Worker when you merge a pull request +sidebar: + badge: + text: Beta +--- + +Workers Builds allows you to connect an existing Worker to a GitHub or GitLab repository to set up automatic builds and deployments for your development workflow. Creating a new Worker from a git repository will be supported soon. + +## Get Started + +To set up your Git integration with Workers: + +1. **Select your Worker** in the [Workers & Pages dashboard](https://dash.cloudflare.com) and navigate to **Settings > Build** +2. **Select the Git provider** you'd like to connect to by clicking "Connect". Follow the prompts to install the Cloudflare application on your git account. +3. **Configure your build settings** by selecting your desired git repository, branch, and [configuring](/workers/ci-cd/builds/configuration/) a deploy command and optionally a build command. +4. **Push a commit** to your git repository to trigger your first build and deploy. + +## View Build Details + +Once a build is in-progress, you can monitor its build logs and view build history by navigating to **View build history** at the bottom of the deployments tab of your Worker. + +If the build is successful, you can also view the build details by selecting **View build** in the associated new [version](/workers/configuration/versions-and-deployments/) created under **Version History**. diff --git a/src/content/docs/workers/ci-cd/builds/limits-and-pricing.mdx b/src/content/docs/workers/ci-cd/builds/limits-and-pricing.mdx new file mode 100644 index 00000000000000..1bee50c720280e --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/limits-and-pricing.mdx @@ -0,0 +1,31 @@ +--- +pcx_content_type: concept +title: Limits & Pricing +description: Limits & pricing for Workers Builds +sidebar: + order: 6 +--- + +## Limits + +While in open beta, the following limits are applicable for Workers Builds. Please note, these are subject to change while in beta. + +| Metric | Description | Limit | +| --------------------- | ---------------------------------------------------------------------- | --------- | +| **Build Minutes** | The amount of minutes that it takes to build a project. | Unlimited | +| **Concurrent Builds** | Number of builds that run in parallel across an account. | 1 | +| **Build Timeout** | The amount of minutes that a build can be run before it is terminated. | 20 mins | +| **CPU** | Number of CPU cores available to your build | 2 CPUs | +| **Memory** | Amount of memory available to the build. | 8GB | +| **Disk space** | Disk space available to your build | 8GB | + +## Future Pricing + +During the beta, Workers Builds will be free to try with the limits stated above. + +In the future, once Workers Builds becomes generally available, you can expect the following updates to the limits and pricing structure. + +| Metric | Workers Free | Paid | +| ------------------------- | ------------- | ---------------------------------- | +| **Build Minutes / Month** | 3,000 minutes | 6,000 minutes (then +$0.005 / min) | +| **Concurrent Builds** | 1 | 6 | diff --git a/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx b/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx new file mode 100644 index 00000000000000..9f2095f8568dfd --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx @@ -0,0 +1,18 @@ +--- +pcx_content_type: troubleshooting +title: Troubleshooting +description: Learn about troubleshooting and known issues in Workers Builds. +sidebar: + order: 7 +--- + +Workers Builds provides build logs for every build started. You can view build logs by navigating to your **Worker project** > **Deployments** > **View Build History** > **View Build**. + +While Workers Builds is in Open Beta, the following issues and limitations may apply: + +- **Worker name:** The Worker name in your Cloudflare dashboard and the Worker name written in the associated `wrangler.toml` must be the same. If they do not match, the deploy will fail, and you must update either the file or dashboard. +- **Updating API tokens:** If you have updated or deleted an API Token, the changes may not be reflected in the Build Configuration settings on the dashboard. If you are encountering authentication errors after updating your build's API Token, we recommend creating a new API Token for the build. +- **Failed builds stuck in in-progress:** If your build has failed but the status still show that the build is "In-progress", you should cancel the build, review your build configuration, then retry the build. +- **Git integration:** If you are running into errors associated with your git integration, you can try [removing access](/workers/ci-cd/builds/git-integration/#removing-access) to your GitHub or GitLab from Cloudflare, then [reinstalling the git integration](/workers/ci-cd/builds/git-integration/#reinstall-a-git-installation). + +If you discover additional issues or would like to provide feedback, please notify us in the [Discord](https://discord.com/channels/595317990191398933/1052656806058528849). diff --git a/src/content/docs/workers/wrangler/ci-cd.mdx b/src/content/docs/workers/ci-cd/external-cicd/github-actions.mdx similarity index 54% rename from src/content/docs/workers/wrangler/ci-cd.mdx rename to src/content/docs/workers/ci-cd/external-cicd/github-actions.mdx index 35d28dc9c11a68..23cf7cbf268a59 100644 --- a/src/content/docs/workers/wrangler/ci-cd.mdx +++ b/src/content/docs/workers/ci-cd/external-cicd/github-actions.mdx @@ -1,12 +1,10 @@ --- -pcx_content_type: configuration -title: Run in CI/CD -head: [] -description: Deploy your Workers within a CI/CD environment. - +pcx_content_type: how-to +title: GitHub Actions +description: Integrate Workers development into your existing GitHub Actions workflows. --- -Wrangler can be run in a [continuous integration/continuous deployment (CI/CD) environment](/workers/configuration/continuous-integration/). It is good practice to only deploy your Workers from within a CI/CD environment, rather than running adhoc deployments manually using `wrangler deploy`. Among other benefits, deploying Workers from within a CI/CD environment makes sure that your Worker is built and deployed within a consistent environment. Deploying Workers from within a CI/CD environment also makes it easier to control access to production credentials. +You can deploy Workers with [GitHub Actions](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler). Here is how you can set up your GitHub Actions workflow. ## 1. Authentication @@ -28,27 +26,27 @@ To create an API token to authenticate Wrangler in your CI job: You will need to choose the account and zone resources that the generated API token will have access to. We recommend scoping these down as much as possible to limit the access of your token. For example, if you have access to three different Cloudflare accounts, you should restrict the generated API token to only the account on which you will be deploying a Worker. -## 2. Set up CI +## 2. Set up CI/CD The method for running Wrangler in your CI/CD environment will depend on the specific setup for your project (whether you use GitHub Actions/Jenkins/GitLab or something else entirely). -To set up your CI: +To set up your CI/CD: -1. Go to your CI platform and add the following as secrets: +1. Go to your CI/CD platform and add the following as secrets: -* `CLOUDFLARE_ACCOUNT_ID`: Set to the [Cloudflare account ID](/workers/wrangler/ci-cd/#cloudflare-account-id) for the account on which you want to deploy your Worker. -* `CLOUDFLARE_API_TOKEN`: Set to the [Cloudflare API token you generated](/workers/wrangler/ci-cd/#api-token). +- `CLOUDFLARE_ACCOUNT_ID`: Set to the [Cloudflare account ID](/workers/ci-cd/external-cicd/#cloudflare-account-id) for the account on which you want to deploy your Worker. +- `CLOUDFLARE_API_TOKEN`: Set to the [Cloudflare API token you generated](/workers/ci-cd/external-cicd/#api-token). :::caution -It is important not to store the value of `CLOUDFLARE_API_TOKEN` in your repository, as it gives access to deploy Workers on your account. Instead, you should utilise your CI/CD provider's support for storing secrets. +Don't store the value of `CLOUDFLARE_API_TOKEN` in your repository, as it gives access to deploy Workers on your account. Instead, you should utilize your CI/CD provider's support for storing secrets. ::: 2. Create a workflow that will be responsible for deploying the Worker. This workflow should run `wrangler deploy`. Review an example [GitHub Actions](https://docs.github.com/en/actions/using-workflows/about-workflows) workflow in the follow section. -### GitHub Action +### GitHub Actions -If you use GitHub Actions, Cloudflare provides [an official action](https://github.com/cloudflare/wrangler-action) for deploying Workers. Refer to the following example workflow which deploys your Worker on push to the `main` branch. +Cloudflare provides [an official action](https://github.com/cloudflare/wrangler-action) for deploying Workers. Refer to the following example workflow which deploys your Worker on push to the `main` branch. ```yaml name: Deploy Worker @@ -69,7 +67,3 @@ jobs: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ``` - -### GitLab Pipelines - -Refer to [GitLab's blog](https://about.gitlab.com/blog/2022/11/21/deploy-remix-with-gitlab-and-cloudflare/) for an example pipeline. Under the `script` key, replace `npm run deploy` with [`npx wrangler deploy`](/workers/wrangler/commands/#deploy). diff --git a/src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx b/src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx new file mode 100644 index 00000000000000..45c3bedc0fd9b0 --- /dev/null +++ b/src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx @@ -0,0 +1,49 @@ +--- +pcx_content_type: how-to +title: GitLab Pipelines +description: Integrate Workers development into your existing GitLab Pipelines workflows. +--- + +You can deploy Workers with [GitLab CI/CD](https://docs.gitlab.com/ee/ci/pipelines/index.html). Here is how you can set up your GitHub Actions workflow. + +## 1. Authentication + +When running Wrangler locally, authentication to the Cloudflare API happens via the [`wrangler login`](/workers/wrangler/commands/#login) command, which initiates an interactive authentication flow. Since CI/CD environments are non-interactive, Wrangler requires a [Cloudflare API token](/fundamentals/api/get-started/create-token/) and [account ID](/fundamentals/setup/find-account-and-zone-ids/) to authenticate with the Cloudflare API. + +### Cloudflare account ID + +To find your Cloudflare account ID, refer to [Find account and zone IDs](/fundamentals/setup/find-account-and-zone-ids/). + +### API token + +To create an API token to authenticate Wrangler in your CI job: + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com). +2. Select **My Profile** > **API Tokens**. +3. Select **Create Token** > find **Edit Cloudflare Workers** > select **Use Template**. +4. Customize your token name. +5. Scope your token. + +You will need to choose the account and zone resources that the generated API token will have access to. We recommend scoping these down as much as possible to limit the access of your token. For example, if you have access to three different Cloudflare accounts, you should restrict the generated API token to only the account on which you will be deploying a Worker. + +## 2. Set up CI + +The method for running Wrangler in your CI/CD environment will depend on the specific setup for your project (whether you use GitHub Actions/Jenkins/GitLab or something else entirely). + +To set up your CI: + +1. Go to your CI platform and add the following as secrets: + +- `CLOUDFLARE_ACCOUNT_ID`: Set to the [Cloudflare account ID](/workers/ci-cd/external-cicd/#cloudflare-account-id) for the account on which you want to deploy your Worker. +- `CLOUDFLARE_API_TOKEN`: Set to the [Cloudflare API token you generated](/workers/ci-cd/external-cicd/#api-token). + +:::caution + +Don't store the value of `CLOUDFLARE_API_TOKEN` in your repository, as it gives access to deploy Workers on your account. Instead, you should utilize your CI/CD provider's support for storing secrets. +::: + +2. Create a workflow that will be responsible for deploying the Worker. This workflow should run `wrangler deploy`. Review an example [GitHub Actions](https://docs.github.com/en/actions/using-workflows/about-workflows) workflow in the follow section. + +### GitLab Pipelines + +Refer to [GitLab's blog](https://about.gitlab.com/blog/2022/11/21/deploy-remix-with-gitlab-and-cloudflare/) for an example pipeline. Under the `script` key, replace `npm run deploy` with [`npx wrangler deploy`](/workers/wrangler/commands/#deploy). diff --git a/src/content/docs/workers/ci-cd/external-cicd/index.mdx b/src/content/docs/workers/ci-cd/external-cicd/index.mdx new file mode 100644 index 00000000000000..2dd07281ac60e3 --- /dev/null +++ b/src/content/docs/workers/ci-cd/external-cicd/index.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: concept +title: External CI/CD +description: Integrate Workers development into your existing continuous integration and continuous development workflows, such as GitHub Actions or GitLab Pipelines. +--- + +Deploying Cloudflare Workers with CI/CD ensures reliable, automated deployments for every code change. + +If you prefer to use your existing CI/CD provider instead of [Workers Builds](/workers/ci-cd/builds/), this section offers guides for popular providers: + +- [**GitHub Actions**](/workers/ci-cd/external-cicd/github-actions/) +- [**GitLab Pipelines**](/workers/ci-cd/external-cicd/gitlab-pipelines/) + +Other CI/CD options including but not limited to Terraform, CircleCI, Jenkins, and more, can also be used to deploy Workers following a similar set up process. diff --git a/src/content/docs/workers/ci-cd/index.mdx b/src/content/docs/workers/ci-cd/index.mdx new file mode 100644 index 00000000000000..8a9738a10f13ab --- /dev/null +++ b/src/content/docs/workers/ci-cd/index.mdx @@ -0,0 +1,41 @@ +--- +pcx_content_type: concept +title: CI/CD +description: Set up continuous integration and continuous deployment for your Workers. +sidebar: + order: 7 +--- + +You can set up continuous integration and continuous deployment (CI/CD) for your Workers by using either the native build system, [Workers Builds](#workers-builds), or using [external providers](#external-cicd) to optimize your development workflow. + +## Why use CI/CD? + +It is best practice to deploy your Workers with a CI/CD pipeline to automate the build and deployment process. A CI/CD pipeline offers several advantages: + +- Streamlines the build and deployment process, eliminating the need for manual adhoc `wrangler deploy` commands +- Ensures your Worker is always built and deployed in a uniform environment, reducing variability and potential errors +- Simplifies managing access to production credentials + +## Which CI/CD should I use? + +Choose [Workers Builds](/workers/ci-cd/builds) if you want a fully integrated solution within Cloudflare's ecosystem that requires minimal setup and configuration for GitHub or GitLab users. + +We recommend using [external CI/CD providers](/workers/ci-cd/external-cicd) if: + +- You have a self-hosted instance of GitHub or GitLabs, which is currently not supported in Workers Builds' git integration +- You are using a git provider that is not GitHub or GitLab + +## Workers Builds + +[Workers Builds](/workers/ci-cd/builds) is Cloudflare's native CI/CD system that allows you to integrate with GitHub or GitLab, and automatically deploy your changes with each new commit. + +![Workers Builds Workflow Diagram](~/assets/images/workers/platform/ci-cd/workers-builds-workflow.png) + +Ready to streamline your Workers deployment? Get started with [Workers Builds](/workers/ci-cd/builds/#get-started). + +## External CI/CD + +You can also choose to set up your CI/CD pipeline with an external provider. + +- [GitHub Actions](/workers/ci-cd/external-cicd/github-actions/) +- [GitLab Pipelines](/workers/ci-cd/external-cicd/gitlab-pipelines/) diff --git a/src/content/docs/workers/configuration/continuous-integration.mdx b/src/content/docs/workers/configuration/continuous-integration.mdx deleted file mode 100644 index bde1dd8b23daf1..00000000000000 --- a/src/content/docs/workers/configuration/continuous-integration.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -pcx_content_type: concept -title: Continuous integration -head: [] -description: Optimize your continuous integration and continuous deployment flow - with Workers. - ---- - -Integrate Workers to your existing services and platforms to optimize your continuous integration and continuous deployment flow. On this page, review some of the supported integrations for Cloudflare Workers. - -## GitHub - -* [Wrangler GitHub Action](https://github.com/cloudflare/wrangler-action) offers a reliable and convenient way to deploy Workers projects automatically when you push. - -## GitLab Pipelines - -* [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/index.html) allow you to set up a continuous integration flow with Cloudflare Workers. - -## Other resources - -### Terraform - -* [Terraform](https://www.terraform.io/) provides an alternative way to configure Workers and routes. Instead of using the Cloudflare dashboard or API directly, you define Worker code and routes in declarative configuration files. Terraform then figures out how to make the API calls for you. This also lets you treat your Worker configuration like your code. You can check your configuration files into version control and integrate them into your normal software development workflow. diff --git a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx b/src/content/docs/workers/configuration/versions-and-deployments/index.mdx index caf9d0486b3c8b..5ebc4a2854bfe5 100644 --- a/src/content/docs/workers/configuration/versions-and-deployments/index.mdx +++ b/src/content/docs/workers/configuration/versions-and-deployments/index.mdx @@ -13,9 +13,9 @@ You can upload changes (versions) to your Worker independent of changing the ver Using versions and deployments is useful if: -* You are running critical applications on Workers and want to reduce risk when deploying new versions of your Worker using a rolling deployment strategy. -* You want to monitor for performance differences when deploying new versions of your Worker. -* You have a CI pipeline configured for Workers but want to cut manual releases. +- You are running critical applications on Workers and want to reduce risk when deploying new versions of your Worker using a rolling deployment strategy. +- You want to monitor for performance differences when deploying new versions of your Worker. +- You have a CI/CD pipeline configured for Workers but want to cut manual releases. ## Versions @@ -43,7 +43,11 @@ Review the different ways you can create versions of your Worker and deploy them #### Upload a new version and deploy it immediately -Changes uploaded with [`wrangler deploy`](/workers/wrangler/commands/#deploy), via the Cloudflare dashboard, or the [Workers Script Upload API](/api/operations/worker-script-upload-worker-module) create a new version that is automatically deployed to 100% of traffic. +A new version that is automatically deployed to 100% of traffic when: + +- Changes are uploaded with [`wrangler deploy`](/workers/wrangler/commands/#deploy) via the Cloudflare Dashboard +- Changes are deployed with the command [`npx wrangler deploy`](/workers/wrangler/commands/#deploy) via [Workers Builds](/workers/ci-cd/builds) +- Changes are uploaded with the [Workers Script Upload API](/api/operations/worker-script-upload-worker-module) #### Upload a new version to be gradually deployed or deployed at a later time diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index dedfc0272eddff..b59d0c96f638fd 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -1609,7 +1609,7 @@ wrangler queues consumer remove Authorize Wrangler with your Cloudflare account using OAuth. Wrangler will attempt to automatically open your web browser to login with your Cloudflare account. -If you prefer to use API tokens for authentication, such as in headless or continuous integration environments, refer to [Running Wrangler in CI/CD](/workers/wrangler/ci-cd/). +If you prefer to use API tokens for authentication, such as in headless or continuous integration environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/). ```txt wrangler login [OPTIONS] diff --git a/src/content/docs/workers/wrangler/deprecations.mdx b/src/content/docs/workers/wrangler/deprecations.mdx index 5d5c68656562c5..08ba0caf3c496e 100644 --- a/src/content/docs/workers/wrangler/deprecations.mdx +++ b/src/content/docs/workers/wrangler/deprecations.mdx @@ -128,7 +128,7 @@ A few configuration fields which were previously required, are now optional in p The `account_id` field is not required for any of the commands. Any relevant commands will check if you are logged in, and if not, will prompt you to log in. Once logged in, it will use your account ID and will not prompt you again until your login session expires. If you have multiple account IDs, you will be presented with a list of accounts to choose from. - You can still configure `account_id` in your `wrangler.toml` file, or as an environment variable `CLOUDFLARE_ACCOUNT_ID`; this will make startup faster, and bypass the list of choices if you have multiple IDs. The `CLOUDFLARE_API_TOKEN` environment variable is also useful for situations where it is not possible to login interactively - refer to [Running in CI/CD](/workers/wrangler/ci-cd). + You can still configure `account_id` in your `wrangler.toml` file, or as an environment variable `CLOUDFLARE_ACCOUNT_ID`. This makes startup faster and bypasses the list of choices if you have multiple IDs. The `CLOUDFLARE_API_TOKEN` environment variable is also useful for situations where it is not possible to login interactively. To learn more, visit [Running in CI/CD](/workers/ci-cd/external-cicd/). * **`workers_dev`** `boolean`, default: `true` when no routes are present