diff --git a/public/_redirects b/public/_redirects index 24c1aa0a5ee72e..66f4881eb45300 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1425,7 +1425,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 @@ -1435,6 +1435,7 @@ /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/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/content/docs/workers/ci-cd/builds/build-configuration.mdx b/src/content/docs/workers/ci-cd/builds/build-configuration.mdx new file mode 100644 index 00000000000000..997118f48452b7 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/build-configuration.mdx @@ -0,0 +1,83 @@ +--- +pcx_content_type: configuration +title: Build Configuration +description: Understand the different settings associated with your build. +sidebar: + badge: + text: Beta +--- + +You may tell Workers Builds how your application needs to be built and deployed. + +## Build Settings + +You can configure Cloudflare to automatically build and deploy your Worker when a pull request is merged into a specific branch of your Git repository. + +Build settings can be found on the Settings page of your Worker. The following options are available: + +- **Git account** + - Set the git account you would like to choose your repository from. +- **Git repository** + - Select the git repository you would like to connect to your Worker. +- **Git branch** + - Select the branch you would like Cloudflare to listen to for new commits. This will be defaulted to main. +- **Build command** _(Optional)_ + - Add a build command if your project requires a build step for example if you are building with assets. Reference supported frameworks for correct build command. +- **Deploy command** + - The deploy command lets you choose the specific Wrangler command you would like to use to deploy your Worker. Your deploy command is defaulted to `npx wrangler deploy`, but it can be customized as needed. You can also upload as a version, and take advantage of [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/). +- **Root Directory** _(Optional)_ + - Specify the root directory of your Worker. The root directory describes where the build command will run. +- **API Key** _(Optional)_ + - By default, Cloudflare will generate an API token for your account or you can create and select an existing API token from a previous build in the API token drop down. These API tokens will be created with the following permissions for your account: + - **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) +- **Build variable** _(Optional)_ + - Add variables and secrets accessible only to your build. + +## Monorepo support + +You can choose to use a monorepo (a Git repository that contains multiple project) with Workers Builds. To do so, you must: + +1. Connect your monorepo git repository to each of your associated Workers on the dashboard +2. In each of the Workers, set up your build configuration to only deploy to that specific Worker by setting the correct root directory in your build configuration. + +When a new commit is detected in the monorepo, all the associated Workers will trigger a new build and deploy. + +### 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, with the root directory in the build configurations set as `workers/product-service/`, `workers/auth-service/`, `workers/order-service/`, and `workers/notification-service/` respectively. + +When a push is made to `ecommerce-monorepo`, a build will be triggered for all of the Workers. + +``` +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 Environment support + +To set up Workers with [Wrangler Enviornments](/workers/wrangler/environments/): + +1. (Optional) [Deploy via Wrangler](/workers/wrangler/commands/#deploy) to create the Worker 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, all the associated Workers will trigger a new build and deploy. 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..a3b121bf6c1f64 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/build-image.mdx @@ -0,0 +1,77 @@ +--- +pcx_content_type: reference +title: Build Image +description: Understand the build image used in Workers Builds. +sidebar: + badge: + text: Beta +--- + +Workers Builds' build environment has broad support for a variety of languages, such as Ruby, Node.js, Python, PHP, and Go. + +If you need to use a [specific version](/workers/ci-cd/builds/build-image/#overriding-default-versions) of a language, (for example, Node.js or Ruby) you can specify it by providing an associated environment variable in your build configuration, or setting the relevant file in your source code. + +## Supported Languages and Tools + +In the following tables, review the preinstalled versions for languages and tools included in the Cloudflare Pages' 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 | Supported versions | Environment variable | File | +| ----------- | ---------------- | ------------------ | -------------------- | ---------------------------- | +| **Go** | 1.22.0 | Any version | `GO_VERSION` | | +| **Node.js** | 20.16.0 | Any version | `NODE_VERSION` | .nvmrc, .node-version | +| **Python** | 3.12.5 | Any version | `PYTHON_VERSION` | .python-version, runtime.txt | +| **Ruby** | 3.3.4 | Any version | `RUBY_VERSION` | .ruby-version | +| **Bun** | 1.1.22 | Any version | `BUN_VERSION` | | +| **Hugo** | extended_0.130.0 | Any version | `HUGO_VERSION` | | + +:::note[Any version] +Under Supported versions, "Any version" refers to support for all versions of the language or tool including versions newer than the Default version. +::: + +### Frameworks + +To use a specific version of a framework, specify it in the project's package manager configuration file. +For example, if you use Gatsby, your `package.json` should include the following: + +``` +"dependencies": { + "gatsby": "^5.13.7", +} +``` + +When your build starts, version 5.13.7 of Gatsby will be installed using `npm install`. + +## Overriding default versions + +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: + +1. Find the environment variable name for the language or tool in [this table](). +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: + +1. Find the environment variable name for the language or tool in [this table](). +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. + +## Build Environment + +Cloudflare Workers builds are run in the following environment: + +| | | +| --------------------- | ------------ | +| **Build Enviornment** | Ubuntu 24.04 | +| **Architecture** | x86_64 | + +## Container Resources + +Each build will have the following resources: + +| | | +| -------------- | ------ | +| **CPU** | 2 CPUs | +| **Disk Space** | 8 GB | +| **Memory** | 8 GB | 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..8dd107ab39a811 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/index.mdx @@ -0,0 +1,41 @@ +--- +pcx_content_type: concept +title: Builds +description: Leverage Workers Builds to integrate with Git and automatically build and deploy your project when you make a change. +sidebar: + badge: + text: Beta +--- + +Connect your existing Worker to a GitHub or GitLab repository to set up automatic build and deployment for your Worker. + +## Get Started + +To set up your Git integration with a Worker: + +1. **Select your Worker** in the Dashboard and navigate to the Build settings of your Worker under the Settings tab. +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 a deploy command. +4. **Push a commit** to your repository to trigger your first build and deploy. + +If you have a monorepo or [Wrangler Enviornments](/workers/wrangler/environments/) setup, reference [Build Configuration](/workers/ci-cd/builds/build-configuration). + +## Build Details + +When a build is in progress you can monitor the build by viewing its logs. Navigate to the “View build history” on the deployments page, and select “View Build”. The build can take on the status of in progress, queued, successful, failed and canceled builds. + +When a commit is successfully built and deployed, you can also view build details for each new version created with git. + +## Build Limits + +In Closed Beta, the following limits are applicable for Workers Builds: + +| 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 interrupted and failed. | 20 mins | + +## Pricing + +xyz 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..270d1eebd2ea2d --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx @@ -0,0 +1,16 @@ +--- +pcx_content_type: troubleshooting +title: Troubleshooting +description: Learn about troubleshooting and known issues in Workers Builds. +sidebar: + badge: + text: Beta +--- + +## Known Issues + +- **Deleted API Token listed:** In build configurations, you may see deleted API Keys still appear in the list of selectable API Keys. +- **Updating API Token:** +- **Wrangler.toml mismatch:** + +If you discover additional issues, please notify us in the [Discord](https://discord.cloudflare.com). diff --git a/src/content/docs/workers/wrangler/ci-cd.mdx b/src/content/docs/workers/ci-cd/external-cicd.mdx similarity index 76% rename from src/content/docs/workers/wrangler/ci-cd.mdx rename to src/content/docs/workers/ci-cd/external-cicd.mdx index 35d28dc9c11a68..f1d8a76b7c7398 100644 --- a/src/content/docs/workers/wrangler/ci-cd.mdx +++ b/src/content/docs/workers/ci-cd/external-cicd.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: External CI/CD +description: Integrate Workers development into your existing continuous integration and continuous development workflows, such as GitHub Actions or GitLab Pipelines. --- -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 from within a GitHub Actions or GitLab Pipelines CI/CD environment with Wrangler. Here's how you can set it up: ## 1. Authentication @@ -36,17 +34,17 @@ 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/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/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). :::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. +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 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. 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..8845ec8a3be6ab --- /dev/null +++ b/src/content/docs/workers/ci-cd/index.mdx @@ -0,0 +1,31 @@ +--- +pcx_content_type: concept +title: Builds (CI/CD) +description: Set up continuous integration and continuous deployment for your Workers. +sidebar: + order: 7 +--- + +Set up **continuous integration and continuous deployment (CI/CD)** for your Workers project by using either [Workers Builds](#workers-builds) or using [existing services and platforms](#external-cicd) to optimize your development workflow. + +## Why use CI/CD? + +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, and it also makes it easier to control access to production credentials. + +## Workers Builds + +[Workers Builds](/workers/ci-cd/builds) allows you to integrate with your Git provider, and automatically deploy your changes when you make a push. + +## External CI/CD + +### GitHub Actions + +[Wrangler GitHub Action](https://github.com/cloudflare/wrangler-action) offers a reliable and convenient way to deploy Workers projects automatically when you push. To set up GitHub Actions with Workers, reference [External CI/CD](/workers/ci-cd/external-cicd). + +### 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. To set up GitLab Pipelines with Workers, reference [External CI/CD](/workers/ci-cd/external-cicd). + +### 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/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.