diff --git a/src/assets/images/pages/configuration/ghpreviewurls.png b/src/assets/images/pages/configuration/ghpreviewurls.png new file mode 100644 index 00000000000000..e0b7abe644f943 Binary files /dev/null and b/src/assets/images/pages/configuration/ghpreviewurls.png differ diff --git a/src/assets/images/workers/platform/ci-cd/gh-status-check-runs.png b/src/assets/images/workers/platform/ci-cd/gh-status-check-runs.png new file mode 100644 index 00000000000000..681a2add78334d Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/gh-status-check-runs.png differ diff --git a/src/assets/images/workers/platform/ci-cd/github-repository-access.png b/src/assets/images/workers/platform/ci-cd/github-repository-access.png new file mode 100644 index 00000000000000..a6d55f7d41d615 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/github-repository-access.png differ diff --git a/src/assets/images/workers/platform/ci-cd/gl-commit-status.png b/src/assets/images/workers/platform/ci-cd/gl-commit-status.png new file mode 100644 index 00000000000000..e4d0c4890b2b40 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/gl-commit-status.png differ diff --git a/src/assets/images/workers/platform/ci-cd/gl-status-checks.png b/src/assets/images/workers/platform/ci-cd/gl-status-checks.png new file mode 100644 index 00000000000000..dcc773a8ea6a04 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/gl-status-checks.png differ diff --git a/src/assets/images/workers/platform/ci-cd/workers-builds-gh-check-runs.png b/src/assets/images/workers/platform/ci-cd/workers-builds-gh-check-runs.png new file mode 100644 index 00000000000000..f76ca3082a5819 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/workers-builds-gh-check-runs.png differ diff --git a/src/assets/images/workers/platform/ci-cd/workers-git-provider.png b/src/assets/images/workers/platform/ci-cd/workers-git-provider.png new file mode 100644 index 00000000000000..63bf637e3fdeb1 Binary files /dev/null and b/src/assets/images/workers/platform/ci-cd/workers-git-provider.png differ diff --git a/src/content/docs/pages/configuration/build-caching.mdx b/src/content/docs/pages/configuration/build-caching.mdx index 669755637cbc83..f2a15dac4433e9 100644 --- a/src/content/docs/pages/configuration/build-caching.mdx +++ b/src/content/docs/pages/configuration/build-caching.mdx @@ -3,36 +3,17 @@ pcx_content_type: concept title: Build caching --- -Improve Pages build times by turning on build caching to restore dependencies and build output between builds. The first build to occur after enabling build caching on your Pages project will save to cache. Every subsequent build will restore from cache unless configured otherwise. +Improve Pages build times by caching dependencies and build output between builds with a project-wide shared cache. -## Requirements +The first build to occur after enabling build caching on your Pages project will save to cache. Every subsequent build will restore from cache unless configured otherwise. -Build caching requires the [V2 build system](/pages/configuration/build-image/#v2-build-system) or later. To update from V1, refer to the [V2 build system migration instructions](/pages/configuration/build-image/#v1-to-v2-migration). - -## Configuration - -### Enable build caching - -To enable build caching in the Cloudflare dashboard: - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. -2. In Account Home, select **Workers & Pages**. -3. In **Overview**, select your Pages project. -4. Go to **Settings** > **Build** > **Build cache** and select **Enable**. +## About build cache -### Clear cache - -The build cache can be cleared for a project if needed, such as when debugging build issues. To clear the build cache: - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. -2. In Account Home, select **Workers & Pages**. -3. In **Overview**, select your Pages project. -4. Go to **Settings** > **Build** > **Build cache**. -5. Select **Clear Cache** to clear the build cache. +When enabled, the build cache will automatically detect and cache data from each build. Refer to [Frameworks](/pages/configuration/build-caching/#frameworks) to review what directories are automatically saved and restored from the build cache. -## How build caching works +### Requirements -When enabled, the build cache will automatically detect and cache data from each build. Refer to [Frameworks](/pages/configuration/build-caching/#frameworks) to review what directories are automatically saved and restored from the build cache. +Build caching requires the [V2 build system](/pages/configuration/build-image/#v2-build-system) or later. To update from V1, refer to the [V2 build system migration instructions](/pages/configuration/build-image/#v1-to-v2-migration). ### Package managers @@ -47,7 +28,9 @@ Pages will cache the global cache directories of the following package managers: ### Frameworks -Caching the build output from frameworks can speed up subsequent build times. The build cache supports the following frameworks: +Some frameworks provide a cache directory that is typically populated by the framework with intermediate build outputs or dependencies during build time. Pages will automatically detect the framework you are using and cache this directory for reuse in subsequent builds. + +The following frameworks support build output caching: | Framework | Directories cached | | ---------- | --------------------------------------------- | @@ -58,9 +41,27 @@ Caching the build output from frameworks can speed up subsequent build times. Th | Next.js | `.next/cache` | | Nuxt | `node_modules/.cache/nuxt` | -## Limits +### Limits The following limits are imposed for build caching: - **Retention**: Cache is purged seven days after its last read date. Unread cache artifacts are purged seven days after creation. - **Storage**: Every project is allocated 10 GB. If the project cache exceeds this limit, the project will automatically start deleting artifacts that were read least recently. + +## Enable build cache + +To enable build caching : + +1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. +2. Find your Pages project. +3. Go to **Settings** > **Build** > **Build cache**. +4. Select **Enable** to turn on build caching. + +## Clear build cache + +The build cache can be cleared for a project if needed, such as when debugging build issues. To clear the build cache: + +1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. +2. Find your Pages project. +3. Go to **Settings** > **Build** > **Build cache**. +4. Select **Clear Cache** to clear the build cache. diff --git a/src/content/docs/pages/configuration/git-integration.mdx b/src/content/docs/pages/configuration/git-integration.mdx deleted file mode 100644 index 132cc91f444f48..00000000000000 --- a/src/content/docs/pages/configuration/git-integration.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -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** > **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. - -### GitHub - -When authorizing Cloudflare Pages to access a GitHub account, you can specify access to your individual account or an organization that you belong to on GitHub. In order to be able to add the Cloudflare Pages installation to that organization, your user account must be an owner or have the appropriate role within the organization (that is, 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 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 - -### GitHub - -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. - -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. - -### GitLab - -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 - -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 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 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. -6. 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 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 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 - -### Project Creation - -#### `This repository is being used for a Cloudflare Pages project on a different Cloudflare account.` - -Using the same Github/Gitlab repository across separate Cloudflare accounts is disallowed. To use the repository for a Pages project in that Cloudflare account, you should delete any Pages projects using the repository in other Cloudflare accounts. - -### Deployments - -If you run into any issues related to deployments or failing, check your project dashboard to see if there are any SCM installation warnings listed as shown in the screenshot below. - -![Pausing a deployment in the Settings of your Pages project](~/assets/images/pages/platform/git.dashboard-error.png) - -To resolve any errors displayed in the Cloudflare Pages dashboard, follow the steps listed below. - -#### `This project is disconnected from your Git account, this may cause deployments to fail.` - -To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support. - -#### `Cloudflare Pages is not properly installed on your Git account, this may cause deployments to fail.` - -To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support. - -#### `The Cloudflare Pages installation has been suspended, this may cause deployments to fail.` - -Go to your GitHub installation settings: - -- `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. - -#### `The project is linked to a repository that no longer exists, this may cause deployments to fail.` - -You may have deleted or transferred the repository associated with this Cloudflare Pages project. For a deleted repository, you will need to create a new Cloudflare Pages project with a repository that has not been deleted. For a transferred repository, you can either transfer the repository back to the original Git account or you will need to create a new Cloudflare Pages project with the transferred repository. - -#### `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: - -- `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. - -#### `There is an internal issue with your Cloudflare Pages Git installation.` - -This is an internal error in the Cloudflare Pages SCM system. You can attempt to [reinstall your Git installation](/pages/configuration/git-integration/#reinstall-a-git-installation), but if the issue persists, [contact support](/support/contacting-cloudflare-support/). - -## 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. diff --git a/src/content/docs/pages/configuration/git-integration/github-integration.mdx b/src/content/docs/pages/configuration/git-integration/github-integration.mdx new file mode 100644 index 00000000000000..c21b2d1ae0505d --- /dev/null +++ b/src/content/docs/pages/configuration/git-integration/github-integration.mdx @@ -0,0 +1,91 @@ +--- +pcx_content_type: concept +title: GitHub integration +--- + +You can connect each Cloudflare Pages project to a GitHub repository, and Cloudflare will automatically deploy your code every time you push a change to a branch. + +## Features + +Beyond automatic deployments, the Cloudflare GitHub integration lets you monitor, manage, and preview deployments directly in GitHub, keeping you informed without leaving your workflow. + +### Custom branches + +Pages will default to setting your [production environment](/pages/configuration/branch-build-controls/#production-branch-control) to the branch you first push. If a branch other than the default branch (e.g. `main`) represents your project's production branch, then go to **Settings** > **Builds** > **Branch control**, change the production branch by clicking the **Production branch** dropdown menu and choose any other branch. + +You can also use [preview deployments](/pages/configuration/preview-deployments/) to preview versions of your project before merging your production branch, and deploying to production. Pages allows you to configure which of your preview branches are automatically deployed using [branch build controls](/pages/configuration/branch-build-controls/). To configure, go to **Settings** > **Builds** > **Branch control** and select an option under **Preview branch**. Use [**Custom branches**](/pages/configuration/branch-build-controls/) to specify branches you wish to include or exclude from automatic preview deployments. + +### Preview URLs + +Every time you open a new pull request on your GitHub repository, Cloudflare Pages will create a unique preview URL, which will stay updated as you continue to push new commits to the branch. Note that preview URLs will not be created for pull requests created from forks of your repository. Learn more in [Preview Deployments](/pages/configuration/preview-deployments/). + +![GitHub Preview URLs](~/assets/images/pages/configuration/ghpreviewurls.png) + +### Skipping a build via a commit message + +Without any configuration required, you can choose to skip a deployment on an ad hoc 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. + +### Check runs + +If you have one or multiple projects connected to a repository (i.e. a [monorepo](/pages/configuration/monorepos/)), you can check on the status of each build within GitHub via [GitHub check runs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks). + +You can see the checks by selecting the status icon next to a commit within your GitHub repository. In the example below, you can select the green check mark to see the results of the check run. + +![GitHub status](~/assets/images/workers/platform/ci-cd/gh-status-check-runs.png) + +Check runs will appear like the following in your repository. + +![GitHub check runs](~/assets/images/pages/configuration/ghcheckrun.png) + +If a build skips for any reason (i.e. CI Skip, build watch paths, or branch deployment controls), the check run/commit status will not appear. + +## Manage access + +You can deploy projects to Cloudflare Workers from your company or side project on GitHub using the [Cloudflare Workers & Pages GitHub App](https://github.com/apps/cloudflare-workers-and-pages). + +### Organizational access + +You can deploy projects to Cloudflare Pages from your company or side project on both GitHub and GitLab. + +When authorizing Cloudflare Pages to access a GitHub account, you can specify access to your individual account or an organization that you belong to on GitHub. In order to be able to add the Cloudflare Pages installation to that organization, your user account must be an owner or have the appropriate role within the organization (that is, 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. 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. To modify these permissions, go to the [Applications page](https://github.com/settings/installations) on GitHub and select **Switch settings context** to access your GitHub organization settings. Then, select **Cloudflare Workers & Pages** > For **Repository access**, select **Only select repositories** > select your repositories. + +::: + +### Remove access + +You can remove Cloudflare Pages' access to your GitHub repository or account by going to the [Applications page](https://github.com/settings/installations) on GitHub (if you are in an organization, select Switch settings context to access your GitHub organization settings). The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects. + +#### Remove Cloudflare access to a GitHub repository + +To remove access to an individual GitHub repository, you can navigate to **Repository access**. Select the **Only select repositories** option, and configure which repositories you would like Cloudflare to have access to. + +![GitHub Repository Access](~/assets/images/workers/platform/ci-cd/github-repository-access.png) + +#### Remove Cloudflare access to the entire GitHub account + +To remove Cloudflare Workers and Pages access to your entire Git account, you can navigate to **Uninstall "Cloudflare Workers and Pages"**, then select **Uninstall**. Removing access to the Cloudflare Workers and Pages app will revoke Cloudflare's access to _all repositories_ from that GitHub account. If you want to only disable automatic builds and deployments, follow the [Disable Build](/workers/ci-cd/builds/#disabling-builds) instructions. + +Note that removing access to GitHub will disable new builds for Workers and Pages project that were connected to those repositories, though your previous deployments will continue to be hosted by Cloudflare Workers. + +### Reinstall the Cloudflare GitHub app + +If you see errors where Cloudflare Pages cannot access your git repository, you should attempt to uninstall and reinstall the GitHub application associated with the Cloudflare Pages installation. + +1. Go to the installation settings page on GitHub: + - Navigate to **Settings > Builds** for the Pages project and select **Manage** under Git Repository. + - Alternatively, visit these links to find the Cloudflare Workers and Pages installation and select **Configure**: + +| | | +| ---------------- | ---------------------------------------------------------------------------------- | +| **Individual** | `https://github.com/settings/installations` | +| **Organization** | `https://github.com/organizations//settings/installations` | + +2. In the Cloudflare Workers and Pages GitHub App settings page, navigate to **Uninstall "Cloudflare Workers and Pages"** and select **Uninstall**. +3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**. +4. Select the **+ Add account** button, select the GitHub account you want to add, and then select **Install & Authorize**. +5. You should be redirected to the create project page with your GitHub 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/pages/configuration/git-integration/gitlab-integration.mdx b/src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx new file mode 100644 index 00000000000000..8a829d389418d2 --- /dev/null +++ b/src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx @@ -0,0 +1,61 @@ +--- +pcx_content_type: concept +title: GitLab integration +--- + +You can connect each Cloudflare Pages project to a GitLab repository, and Cloudflare will automatically deploy your code every time you push a change to a branch. + +## Features + +Beyond automatic deployments, the Cloudflare GitLab integration lets you monitor, manage, and preview deployments directly in GitLab, keeping you informed without leaving your workflow. + +### Custom branches + +Pages will default to setting your [production environment](/pages/configuration/branch-build-controls/#production-branch-control) to the branch you first push. If a branch other than the default branch (e.g. `main`) represents your project's production branch, then go to **Settings** > **Builds** > **Branch control**, change the production branch by clicking the **Production branch** dropdown menu and choose any other branch. + +You can also use [preview deployments](/pages/configuration/preview-deployments/) to preview versions of your project before merging your production branch, and deploying to production. Pages allows you to configure which of your preview branches are automatically deployed using [branch build controls](/pages/configuration/branch-build-controls/). To configure, go to **Settings** > **Builds** > **Branch control** and select an option under **Preview branch**. Use [**Custom branches**](/pages/configuration/branch-build-controls/) to specify branches you wish to include or exclude from automatic preview deployments. + +### Skipping a specific build via a commit message + +Without any configuration required, you can choose to skip a deployment on an ad hoc basis. By adding the `[CI Skip]`, `[CI-Skip]`, `[Skip CI]`, `[Skip-CI]`, or `[CF-Pages-Skip]` flag as a prefix in your commit message, Pages will omit that deployment. The prefixes are not case sensitive. + +### Check runs and preview URLs + +If you have one or multiple projects connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitLab via [GitLab commit status](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html). + +You can see the statuses by selecting the status icon next to a commit or by going to **Build** > **Pipelines** within your GitLab repository. In the example below, you can select the green check mark to see the results of the check run. + +![GitLab Status](~/assets/images/workers/platform/ci-cd/gl-status-checks.png) + +Check runs will appear like the following in your repository. You can select one of the statuses to view the [preview URL](/pages/configuration/preview-deployments/) for that deployment. + +![GitLab Commit Status](~/assets/images/pages/configuration/glcommitstatus.png) + +If a build skips for any reason (i.e. CI Skip, build watch paths, or branch deployment controls), the check run/commit status will not appear. + +## Manage access + +You can deploy projects to Cloudflare Workers from your company or side project on GitLab using the Cloudflare Pages app. + +### Organizational access + +You can deploy projects to Cloudflare Pages from your company or side project on both GitHub and GitLab. + +When you authorize Cloudflare Pages to access your GitLab account, you automatically give Cloudflare Pages access to organizations, groups, and namespaces accessed by your GitLab account. Managing access to these organizations and groups is handled by GitLab. + +### Remove access + +You can remove Cloudflare Workers' access to your GitLab account by navigating to [Authorized Applications page](https://gitlab.com/-/profile/applications) on GitLab. Find the applications called Cloudflare Workers and select the **Revoke** button to revoke access. + +Note that the GitLab application Cloudflare Workers is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though your previous deployments will continue to be hosted by Cloudflare Pages. + +### Reinstall the Cloudflare GitLab app + +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 Pages installation. + +1. Go to your application settings page on GitLab located here: [https://gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications) +2. Select 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`. Select **Create application** > **Pages** > **Connect to Git**. +4. Select the **GitLab** tab at the top, select the **+ Add account** button, select the GitLab account you want to add, and then select **Authorize** on the modal titled "Authorize Cloudflare Pages to use your account?". +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. diff --git a/src/content/docs/pages/configuration/git-integration/index.mdx b/src/content/docs/pages/configuration/git-integration/index.mdx new file mode 100644 index 00000000000000..24ede8576e9dc4 --- /dev/null +++ b/src/content/docs/pages/configuration/git-integration/index.mdx @@ -0,0 +1,57 @@ +--- +pcx_content_type: concept +title: Git integration +--- + +You can connect each Cloudflare Pages project to a [GitHub](/pages/configuration/git-integration/github-integration) or [GitLab](/pages/configuration/git-integration/gitlab-integration) repository, and Cloudflare will automatically deploy your code every time you push a change to a branch. + +:::note +Cloudflare Workers now also supports Git integrations to automatically build and deploy Workers from your connected Git repository. Learn more in [Workers Builds](/workers/ci-cd/builds/). +::: + +When you connect a git repository to your Cloudflare Pages project, Cloudflare will also: + +- **Preview deployments for custom branches**, generating preview URLs for a commit to any branch in the repository without affecting your production deployment. +- **Preview URLs in pull requests** (PRs) to the repository. +- **Build and deployment status checks** within the Git repository. +- **Skipping builds using a commit message**. + +These features allow you to manage your deployments directly within GitHub or GitLab without leaving your team's regular development workflow. + +:::caution[You cannot switch to Direct Upload later] +If you deploy using the Git integration, you cannot switch to [Direct Upload](/pages/get-started/direct-upload/) later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) on all branches. Then, you can use Wrangler to deploy directly to your Pages projects and make changes to your Git repository without automatically triggering a build. + +::: + +## Supported Git providers + +Cloudflare supports connecting Cloudflare Pages to your GitHub and GitLab repositories. Pages does not currently support connecting self-hosted instances of GitHub or GitLab. + +If you using a different Git provider (e.g. Bitbucket) or a self-hosted instance, you can start with a Direct Upload project and deploy using a CI/CD provider (e.g. GitHub Actions) with [Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). + +## Add a Git integration + +If you do not have a Git account linked to your Cloudflare account, you will be prompted to set up an installation to GitHub or GitLab when [connecting to Git](/pages/get-started/git-integration/) for the first time, or when adding a new Git account. Follow the prompts and authorize the Cloudflare Git integration. + +You can check the following pages to see if your Git integration has been installed: + +- [GitHub Applications page](https://github.com/settings/installations) (if you're in an organization, select **Switch settings context** to access your GitHub organization settings) +- [GitLab Authorized Applications page](https://gitlab.com/-/profile/applications) + +For details on providing access to organization accounts, see the [GitHub](/pages/configuration/git-integration/github-integration/#organizational-access) and [GitLab](/pages/configuration/git-integration/gitlab-integration/#organizational-access) guides. + +## Manage a Git integration + +You can manage the Git installation associated with your repository connection by navigating to the Pages project, then going to **Settings** > **Builds** and selecting **Manage** under **Git Repository**. + +This can be useful for managing repository access or troubleshooting installation issues by reinstalling. For more details, see the [GitHub](/pages/configuration/git-integration/github-integration/#managing-access) and [GitLab](/pages/configuration/git-integration/gitlab-integration/#managing-access) guides. + +## Disable automatic deployments + +If you are using a Git-integrated project and do not want to trigger deployments every time you push a commit, you can use [branch control](/pages/configuration/branch-build-controls/) to disable/pause builds: + +1. Go to the **Settings** of your **Pages project** in the [Cloudflare dashboard](https://dash.cloudflare.com). +2. Navigate to **Build** > edit **Branch control** > turn off **Enable automatic production branch deployments**. +3. You can also change your Preview branch to **None (Disable automatic branch deployments)** to pause automatic preview deployments. + +Then, you can use Wrangler to deploy directly to your Pages project and make changes to your Git repository without automatically triggering a build. diff --git a/src/content/docs/pages/configuration/git-integration/troubleshooting.mdx b/src/content/docs/pages/configuration/git-integration/troubleshooting.mdx new file mode 100644 index 00000000000000..5da836dddb7e2e --- /dev/null +++ b/src/content/docs/pages/configuration/git-integration/troubleshooting.mdx @@ -0,0 +1,58 @@ +--- +pcx_content_type: concept +title: Troubleshooting builds +--- + +If your git integration is experiencing issues, you may find the following banners in the Deployment page of your Pages project. + +## Project creation + +#### `This repository is being used for a Cloudflare Pages project on a different Cloudflare account.` + +Using the same GitHub/GitLab repository across separate Cloudflare accounts is disallowed. To use the repository for a Pages project in that Cloudflare account, you should delete any Pages projects using the repository in other Cloudflare accounts. + +## Deployments + +If you run into any issues related to deployments or failing, check your project dashboard to see if there are any SCM installation warnings listed as shown in the screenshot below. + +![Pausing a deployment in the Settings of your Pages project](~/assets/images/pages/platform/git.dashboard-error.png) + +To resolve any errors displayed in the Cloudflare Pages dashboard, follow the steps listed below. + +#### `This project is disconnected from your Git account, this may cause deployments to fail.` + +To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support. + +#### `Cloudflare Pages is not properly installed on your Git account, this may cause deployments to fail.` + +To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support. + +#### `The Cloudflare Pages installation has been suspended, this may cause deployments to fail.` + +Go to your GitHub installation settings: + +- `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. + +#### `The project is linked to a repository that no longer exists, this may cause deployments to fail.` + +You may have deleted or transferred the repository associated with this Cloudflare Pages project. For a deleted repository, you will need to create a new Cloudflare Pages project with a repository that has not been deleted. For a transferred repository, you can either transfer the repository back to the original Git account or you will need to create a new Cloudflare Pages project with the transferred repository. + +#### `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: + +- `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. + +#### `There is an internal issue with your Cloudflare Pages Git installation.` + +This is an internal error in the Cloudflare Pages SCM system. You can attempt to [reinstall your Git installation](/pages/configuration/git-integration/#reinstall-a-git-installation), but if the issue persists, [contact support](/support/contacting-cloudflare-support/). + +#### `GitHub/GitLab is having an incident and push events to Cloudflare are operating in a degraded state. Check their status page for more details.` + +This indicates that GitHub or GitLab may be experiencing an incident affecting push events to Cloudflare. It is recommended to monitor their status page ([GitHub](https://www.githubstatus.com/), [GitLab](https://status.gitlab.com/)) for updates and try deploying again later. diff --git a/src/content/docs/pages/configuration/preview-deployments.mdx b/src/content/docs/pages/configuration/preview-deployments.mdx index 808e740d76fb62..e989051a614792 100644 --- a/src/content/docs/pages/configuration/preview-deployments.mdx +++ b/src/content/docs/pages/configuration/preview-deployments.mdx @@ -11,6 +11,8 @@ Preview deployments allow you to preview new versions of your project without de Every time you open a new pull request on your GitHub repository, Cloudflare Pages will create a unique preview URL, which will stay updated as you continue to push new commits to the branch. This is only true when pull requests originate from the repository itself. +![GitHub Preview URLs](~/assets/images/pages/configuration/ghpreviewurls.png) + For example, if you have a repository called `user-example` connected to Pages, this will give you a `user-example.pages.dev` subdomain. If `main` is your default branch, then any commits to the `main` branch will update your `user-example.pages.dev` content, as well as any [custom domains](/pages/configuration/custom-domains/) attached to the project. ![User-example repository's deployment status and preview](~/assets/images/pages/platform/preview-deployment-mergedone.png) diff --git a/src/content/docs/pages/get-started/c3.mdx b/src/content/docs/pages/get-started/c3.mdx index 15d1cb90f1ca2a..6246b1b2c48e8d 100644 --- a/src/content/docs/pages/get-started/c3.mdx +++ b/src/content/docs/pages/get-started/c3.mdx @@ -10,7 +10,14 @@ description: Use C3 (`create-cloudflare` CLI) to set up and deploy new deployment. --- -import { Render, TabItem, Tabs, Type, MetaInfo, PackageManagers } from "~/components"; +import { + Render, + TabItem, + Tabs, + Type, + MetaInfo, + PackageManagers, +} from "~/components"; Cloudflare provides a CLI command for creating new Workers and Pages projects — `npm create cloudflare`, powered by the [`create-cloudflare` package](https://www.npmjs.com/package/create-cloudflare). @@ -229,7 +236,7 @@ Cloudflare collects anonymous usage data to improve `create-cloudflare` over tim You can opt-out if you do not wish to share any information. @@ -243,15 +250,15 @@ export CREATE_CLOUDFLARE_TELEMETRY_DISABLED=1 You can check the status of telemetry collection at any time. You can always re-enable telemetry collection. diff --git a/src/content/docs/pages/get-started/direct-upload.mdx b/src/content/docs/pages/get-started/direct-upload.mdx index 73fc8e4ce6cf4f..2634e821ff69b0 100644 --- a/src/content/docs/pages/get-started/direct-upload.mdx +++ b/src/content/docs/pages/get-started/direct-upload.mdx @@ -10,7 +10,13 @@ description: Upload your prebuilt assets to Pages and deploy them via the import { Render } from "~/components"; -Direct Upload enables you to upload your prebuilt assets to Pages and deploy them to the Cloudflare global network. This guide will instruct you how to upload your assets using Wrangler or the drag and drop method. +Direct Upload enables you to upload your prebuilt assets to Pages and deploy them to the Cloudflare global network. You should choose Direct Upload over Git integration if you want to [integrate your own build platform](/pages/how-to/use-direct-upload-with-continuous-integration/) or upload from your local computer. + +This guide will instruct you how to upload your assets using Wrangler or the drag and drop method. + +:::caution[You cannot switch to Git integration later] +If you choose Direct Upload, you cannot switch to [Git integration](/pages/get-started/git-integration/) later. You will have to create a new project with Git integration to use automatic deployments. +::: ## Prerequisites @@ -141,4 +147,4 @@ If using the drag and drop method, a red warning symbol will appear next to an a Drag and drop deployments made from the Cloudflare dashboard do not currently support compiling a `functions` folder of [Pages Functions](/pages/functions/). To deploy a `functions` folder, you must use Wrangler. When deploying a project using Wrangler, if a `functions` folder exists where the command is run, that `functions` folder will be uploaded with the project. -However, note that a `_worker.js` file is supported by both Wrangler and drag and drop deployments made from the dashboard. \ No newline at end of file +However, note that a `_worker.js` file is supported by both Wrangler and drag and drop deployments made from the dashboard. diff --git a/src/content/docs/pages/get-started/git-integration.mdx b/src/content/docs/pages/get-started/git-integration.mdx index 85e7ba1ee544d2..c8e53242c2cc4c 100644 --- a/src/content/docs/pages/get-started/git-integration.mdx +++ b/src/content/docs/pages/get-started/git-integration.mdx @@ -5,12 +5,16 @@ head: - tag: title content: Git integration guide description: Connect your Git provider to Pages. - --- -import { Details, Render } from "~/components" +import { Details, Render } from "~/components"; + +In this guide, you will get started with Cloudflare Pages and deploy your first website to the Pages platform through Git integration. The Git integration enables automatic builds and deployments every time you push a change to your connected [GitHub](/pages/configuration/git-integration/github-integration/) or [GitLab](/pages/configuration/git-integration/gitlab-integration/) repository. + +:::caution[You cannot switch to Direct Upload later] +If you deploy using the Git integration, you cannot switch to [Direct Upload](/pages/get-started/direct-upload/) later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) on all branches. Then, you can use Wrangler to deploy directly to your Pages projects and make changes to your Git repository without automatically triggering a build. -In this guide, you will get started with Cloudflare Pages, and deploy your first website to the Pages platform through Git integration. +::: ## Connect your Git provider to Pages diff --git a/src/content/docs/pages/platform/known-issues.mdx b/src/content/docs/pages/platform/known-issues.mdx index e15b0e556bfaf7..97aa558d274f9b 100644 --- a/src/content/docs/pages/platform/known-issues.mdx +++ b/src/content/docs/pages/platform/known-issues.mdx @@ -19,7 +19,7 @@ Here are some known bugs and issues with Cloudflare Pages: ## Git configuration -- After you have selected a GitHub/GitLab repository for your Pages application, it cannot be changed. Delete your Pages project and create a new one pointing at a different repository if you need to update it. +- If you deploy using the Git integration, you cannot switch to Direct Upload later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable/pause automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments). Alternatively, you can delete your Pages project and create a new one pointing at a different repository if you need to update it. ## Build configuration diff --git a/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx b/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx index d8a8b56e993283..88d853f6e75057 100644 --- a/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx +++ b/src/content/docs/workers/ci-cd/builds/advanced-setups.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: reference -title: Advanced Setups +title: Advanced setups description: Learn how to use Workers Builds with more advanced setups sidebar: order: 7 @@ -8,13 +8,25 @@ sidebar: ## 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. +To set up a monorepo workflow: + +1. Find the Workers associated with your project in the [Workers & Pages Dashboard](https://dash.cloudflare.com). +2. Connect your monorepo to each Worker in the repository. +3. Set the root directory for each Worker to specify the location of its `wrangler.toml` and where build and deploy commands should run. +4. Optionally, configure unique build and deploy commands for each Worker. +5. Optionally, configure [build watch paths](/workers/ci-cd/builds/build-watch-paths/) for each Worker to monitor specific paths for changes. + +When a new commit is made to the monorepo, a new build and deploy will trigger for each Worker if the change is within each of its included watch paths. You can also check on the status of each build associated with your repository within GitHub with [check runs](/workers/ci-cd/builds/git-integration/github-integration/#check-run) or within GitLab with [commit statuses](/workers/ci-cd/builds/git-integration/gitlab-integration/#commit-status). ### Example -In the example `ecommerce-monorepo`, a Workers project should be created for `product-service`, `auth-service`, `order-service`, and `notification-service`. +In the example `ecommerce-monorepo`, a Workers project should be created for `product-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, such as [Turborepo](https://turbo.build/), you can configure a different deploy command for each Worker, for example, `turbo deploy -F product-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. +Set the root directory of each Worker to where its wrangler.toml is located. For example, for `product-service`, the root directory should be `/workers/product-service/`. Optionally, you can add [build watch paths](/workers/ci-cd/builds/build-watch-paths/) to optimize your builds. + +When a new commit is made to `ecommerce-monorepo`, a build and deploy will be triggered for each of the Workers if the change is within its included watch paths using the configured commands for that Worker. ``` ecommerce-monorepo/ @@ -23,9 +35,6 @@ ecommerce-monorepo/ │ ├── product-service/ │ │ ├── src/ │ │ └── wrangler.toml -│ ├── auth-service/ -│ │ ├── src/ -│ │ └── wrangler.toml │ ├── order-service/ │ │ ├── src/ │ │ └── wrangler.toml @@ -37,11 +46,11 @@ ecommerce-monorepo/ └── README.md ``` -## Wrangler environments +## 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: +You can use [Wrangler Environments](/workers/wrangler/environments/) with Workers Builds by completing the following steps: -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. +1. [Deploy via Wrangler](/workers/wrangler/commands/#deploy) to create the Workers for your environments on the Dashboard, if you do not 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. @@ -50,17 +59,6 @@ When a new commit is detected in the repository, a new build/deploy will trigger ### 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. +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 have not already, you can deploy `my-worker` for each environment using the commands `wrangler deploy --env staging` and `wrangler deploy --env production`. -```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 -``` +In your Cloudflare Dashboard, you should find the two Workers `my-worker-staging` and `my-worker-production`. Then, connect the Git repository for the Worker, `my-worker`, 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. diff --git a/src/content/docs/workers/ci-cd/builds/build-caching.mdx b/src/content/docs/workers/ci-cd/builds/build-caching.mdx index 92cf20b3a9eda6..0761c4b3785b70 100644 --- a/src/content/docs/workers/ci-cd/builds/build-caching.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-caching.mdx @@ -6,30 +6,11 @@ sidebar: order: 5 --- -Improve Workers Builds build times by turning on build caching to restore dependencies and build output between builds. The first build to occur after enabling build caching on your Pages project will save to cache. Every subsequent build will restore from cache unless configured otherwise. +Improve Workers build times by caching dependencies and build output between builds with a project-wide shared cache. -## Configuration +The first build to occur after enabling build caching on your Workers project will save relevant artifacts to cache. Every subsequent build will restore from cache unless configured otherwise. -### Enable build caching - -To enable build caching in the Cloudflare dashboard: - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. -2. In Account Home, select **Workers & Pages**. -3. In **Overview**, select your Workers project. -4. Go to **Settings** > **Build** > **Build cache** and select **Enable**. - -### Clear cache - -The build cache can be cleared for a project when needed, such as when debugging build issues. To clear the build cache: - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. -2. In Account Home, select **Workers & Pages**. -3. In **Overview**, select your Workers project. -4. Go to **Settings** > **Build** > **Build cache**. -5. Select **Clear Cache** to clear the build cache. - -## How build caching works +## About build cache When enabled, build caching will automatically detect which package manager and framework the project is using from its `package.json` and cache data accordingly for the build. @@ -48,6 +29,8 @@ Workers build cache will cache the global cache directories of the following pac ### Frameworks +Some frameworks provide a cache directory that is typically populated by the framework with intermediate build outputs or dependencies during build time. Workers Builds will automatically detect the framework you are using and cache this directory for reuse in subsequent builds. + The following frameworks support build output caching: | Framework | Directories cached | @@ -63,9 +46,27 @@ The following frameworks support build output caching: [Static assets](/workers/static-assets/) and [frameworks](/workers/frameworks/) are now supported in Cloudflare Workers. ::: -## Limits +### Limits The following limits are imposed for build caching: - **Retention**: Cache is purged 7 days after its last read date. Unread cache artifacts are purged 7 days after creation. - **Storage**: Every project is allocated 10 GB. If the project cache exceeds this limit, the project will automatically start deleting artifacts that were read least recently. + +## Enable build cache + +To enable build caching: + +1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. +2. Find your Workers project. +3. Go to **Settings** > **Build** > **Build cache**. +4. Select **Enable** to turn on build caching. + +## Clear build cache + +The build cache can be cleared for a project when needed, such as when debugging build issues. To clear the build cache: + +1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. +2. Find your Workers project. +3. Go to **Settings** > **Build** > **Build cache**. +4. Select **Clear Cache** to clear the build cache. diff --git a/src/content/docs/workers/ci-cd/builds/build-image.mdx b/src/content/docs/workers/ci-cd/builds/build-image.mdx index ebecf3cf9ba478..11e9e2ff8b0268 100644 --- a/src/content/docs/workers/ci-cd/builds/build-image.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-image.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: reference -title: Build Image +title: Build image description: Understand the build image used in Workers Builds. sidebar: order: 4 diff --git a/src/content/docs/workers/ci-cd/builds/build-watch-paths.mdx b/src/content/docs/workers/ci-cd/builds/build-watch-paths.mdx index 90200ff65bbbb0..bc437662381b2b 100644 --- a/src/content/docs/workers/ci-cd/builds/build-watch-paths.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-watch-paths.mdx @@ -8,7 +8,7 @@ sidebar: When you connect a git repository to Workers, by default a change to any file in the repository will trigger a build. You can configure Workers to include or exclude specific paths to specify if Workers should skip a build for a given path. This can be especially helpful if you are using a monorepo project structure and want to limit the amount of builds being kicked off. -## Configure paths +## Configure Paths To configure which paths are included and excluded: diff --git a/src/content/docs/workers/ci-cd/builds/configuration.mdx b/src/content/docs/workers/ci-cd/builds/configuration.mdx index 5176821a997b7b..ec4ca15299093a 100644 --- a/src/content/docs/workers/ci-cd/builds/configuration.mdx +++ b/src/content/docs/workers/ci-cd/builds/configuration.mdx @@ -6,27 +6,61 @@ sidebar: order: 2 --- -When connecting your repository, you can configure how to build and deploy your Worker. +import { DirectoryListing } from "~/components"; -## Build Settings +When connecting your Git repository to your Worker, you can customize the configurations needed to build and deploy your Worker. -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: +## Build settings -| 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** | +Build settings can be found by navigating to **Settings** > **Build** within your Worker. -:::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: +Note that when you update and save build settings, the updated settings will be applied to your _next_ build. When you _retry_ a build, the build configurations that exist when the build is retried will be applied. + +### Overview + +| Setting | Description | +| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Git account** | Select the Git account you would like to use. After the 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 (e.g. `npm run build`). This is necessary, for example, when using a [front-end framework](/workers/ci-cd/builds/configuration/#framework-support) such as Next.js or Remix. | +| **[Deploy command](/workers/ci-cd/builds/configuration/#deploy-command)** | The deploy command lets you set the [specific Wrangler command](/workers/wrangler/commands/#deploy) used to deploy your Worker. Your deploy command will default to `npx wrangler deploy` but you may customize this command. Workers Builds will use the Wrangler version set in your `package json`. | +| **Root directory** _(Optional)_ | Specify the path to your project. The root directory defines where the build command will be run and can be helpful in [monorepos](/workers/ci-cd/builds/advanced-setups/#monorepos) to isolate a specific project within the repository for builds. | +| **[API token](/workers/ci-cd/builds/configuration/#api-token)** _(Optional)_ | The API token is used to authenticate your build request and authorize the upload and deployment of your Worker to Cloudflare. By default, Cloudflare will automatically generate an API token for your account when using Workers Builds, and continue to use this API token for all subsequent 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 +Currently, Workers Builds does not honor the configurations set in [Custom Builds](/workers/wrangler/custom-builds/) within your wrangler.toml file. +::: + +### Deploy command + +You can run your deploy command using the package manager of your choice. + +If you have added a Wrangler deploy command as a script in your `package.json`, then you can run it by setting it as your deploy command. For example, `npm run deploy`. + +Examples of other deploy commands you can set include: + +| Example Command | Description | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `npx wrangler versions upload` | Upload a [version](/workers/configuration/versions-and-deployments/) of your Worker without deploying it as the Active Deployment. | +| `npx wrangler deploy --assets ./public/` | Deploy your Worker along with static assets from the specified directory. Alternatively, you can use the [assets binding](/workers/static-assets/binding/). | +| `npx wrangler deploy --env staging` | If you have a [Wrangler environment](/workers/ci-cd/builds/advanced-setups/#wrangler-environments) Worker, you should set your deploy command with the environment flag. For more details, see [Advanced Setups](/workers/ci-cd/builds/advanced-setups/#wrangler-environments). | + +### API token + +When you select **Create new token**, a new API token will be created 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) - ::: + +You can configure the permissions of this API token by navigating to **My Profile** > **API Tokens** for user tokens. + +It is recommended to consistently use the same API token across all uploads and deployments of your Worker to maintain consistent access permissions. + +## Framework support + +[Static assets](/workers/static-assets/) and [frameworks](/workers/frameworks/) are now supported in Cloudflare Workers. Learn to set up Workers projects and the commands for each framework in the framework guides: + + diff --git a/src/content/docs/workers/ci-cd/builds/git-integration.mdx b/src/content/docs/workers/ci-cd/builds/git-integration.mdx deleted file mode 100644 index 0ec7d8d1ffc981..00000000000000 --- a/src/content/docs/workers/ci-cd/builds/git-integration.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -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/git-integration/github-integration.mdx b/src/content/docs/workers/ci-cd/builds/git-integration/github-integration.mdx new file mode 100644 index 00000000000000..31dc52e8fa08d5 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/git-integration/github-integration.mdx @@ -0,0 +1,84 @@ +--- +pcx_content_type: reference +title: GitHub integration +description: Learn how to manage your GitHub integration for Workers Builds +sidebar: + order: 2 +--- + +Cloudflare supports connecting your GitHub repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change to a selected branch. + +## Features + +Beyond automatic builds and deployments, the Cloudflare GitHub integration lets you monitor builds directly in GitHub, keeping you informed without leaving your workflow. + +:::note[Upcoming features] +In Beta, Workers Builds supports automatic builds and deployments only from a single selected branch (e.g. `main`). + +Support for building and deploying preview versions from multiple branches will be added soon, along with the ability to generate [Preview URLs](/workers/configuration/previews/) for pull requests (PRs). +::: + +### Check run + +If you have one or multiple Workers connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitHub via [GitHub check runs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks). + +You can see the checks by selecting on the status icon next to a commit within your GitHub repository. In the example below, you can select the green check mark to see the results of the check run. + +![GitHub status](~/assets/images/workers/platform/ci-cd/gh-status-check-runs.png) + +Check runs will appear like the following in your repository. You can select **Details** to view the build (Build ID) and project (Script) associated with each check. + +![GitHub check runs](~/assets/images/workers/platform/ci-cd/workers-builds-gh-check-runs.png) + +Note that when using [build watch paths](/workers/ci-cd/builds/build-watch-paths/), only projects that trigger a build will generate a check run. + +## Manage access + +You can deploy projects to Cloudflare Workers from your company or side project on GitHub using the [Cloudflare Workers & Pages GitHub App](https://github.com/apps/cloudflare-workers-and-pages). + +### Organizational access + +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. 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. To modify these permissions, go to the [Applications page](https://github.com/settings/installations) on GitHub and select **Switch settings context** to access your GitHub organization settings. Then, select **Cloudflare Workers & Pages** > For **Repository access**, select **Only select repositories** > select your repositories. + +::: + +### Remove access + +You can remove Cloudflare Workers' access to your GitHub repository or account by going to the [Applications page](https://github.com/settings/installations) on GitHub (if you are in an organization, select Switch settings context to access your GitHub organization settings). The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects. + +#### Remove Cloudflare access to a GitHub repository + +To remove access to an individual GitHub repository, you can navigate to **Repository access**. Select the **Only select repositories** option, and configure which repositories you would like Cloudflare to have access to. + +![GitHub Repository Access](~/assets/images/workers/platform/ci-cd/github-repository-access.png) + +#### Remove Cloudflare access to the entire GitHub account + +To remove Cloudflare Workers and Pages access to your entire Git account, you can navigate to **Uninstall "Cloudflare Workers and Pages"**, then select **Uninstall**. Removing access to the Cloudflare Workers and Pages app will revoke Cloudflare's access to _all repositories_ from that GitHub account. If you want to only disable automatic builds and deployments, follow the [Disable Build](/workers/ci-cd/builds/#disabling-builds) instructions. + +Note that removing access to GitHub will disable new builds for Workers and Pages project that were connected to those repositories, though your previous deployments will continue to be hosted by Cloudflare Workers. + +### Reinstall the Cloudflare GitHub App + +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 Pages installation. The process for each Git provider is provided below. + +1. Go to the installation settings page on GitHub: + - Navigate to **Settings > Builds** for the Workers or Pages project and select **Manage** under Git Repository. + - Alternatively, visit these links to find the Cloudflare Workers and Pages installation and select **Configure**: + +| | | +| ---------------- | ---------------------------------------------------------------------------------- | +| **Individual** | `https://github.com/settings/installations` | +| **Organization** | `https://github.com/organizations//settings/installations` | + +2. In the Cloudflare Workers and Pages GitHub App settings page, navigate to **Uninstall "Cloudflare Workers and Pages"** and select **Uninstall**. +3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**. +4. Select the **+ Add account** button, select the GitHub account you want to add, and then select **Install & Authorize**. +5. You should be redirected to the create project page with your GitHub 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/git-integration/gitlab-integration.mdx b/src/content/docs/workers/ci-cd/builds/git-integration/gitlab-integration.mdx new file mode 100644 index 00000000000000..4b77d2ff221b2c --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/git-integration/gitlab-integration.mdx @@ -0,0 +1,56 @@ +--- +pcx_content_type: reference +title: GitLab integration +description: Learn how to manage your GitLab integration for Workers Builds +sidebar: + order: 2 +--- + +Cloudflare supports connecting your GitLab repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change to a selected branch. + +## Features + +Beyond automatic builds and deployments, the Cloudflare GitLab integration lets you monitor builds directly in GitLab, keeping you informed without leaving your workflow. + +:::note[Upcoming features] +In Beta, Workers Builds supports automatic builds and deployments only from a single selected branch (e.g. `main`). + +Support for building and deploying preview versions from multiple branches will be added soon, along with the ability to generate [Preview URLs](/workers/configuration/previews/) for pull requests (PRs). +::: + +### Commit Status + +If you have one or multiple Workers connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitLab via [GitLab commit status](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html). + +You can see the statuses by selecting the status icon next to a commit or by going to **Build** > **Pipelines** within your GitLab repository. In the example below, you can select on the green check mark to see the results of the check run. + +![GitLab Status](~/assets/images/workers/platform/ci-cd/gl-status-checks.png) + +Check runs will appear like the following in your repository. You can select one of the statuses to view the build on the Cloudflare Dashboard. + +![GitLab Commit Status](~/assets/images/workers/platform/ci-cd/gl-commit-status.png) + +Note that when using [build watch paths](/workers/ci-cd/builds/build-watch-paths/), only projects that trigger a build will generate a commit status. + +## Manage access + +You can deploy projects to Cloudflare Workers from your company or side project on GitLab using the Cloudflare Pages app. + +### Organizational access + +When you authorize Cloudflare Workers to access your GitLab account, you automatically give Cloudflare Workers access to organizations, groups, and namespaces accessed by your GitLab account. Managing access to these organizations and groups is handled by GitLab. + +### Remove access + +You can remove Cloudflare Workers' access to your GitLab account by navigating to [Authorized Applications page](https://gitlab.com/-/profile/applications) on GitLab. Find the applications called Cloudflare Pages and select the **Revoke** button to revoke access. + +Note that the GitLab application Cloudflare Workers is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though your previous deployments will continue to be hosted by Cloudflare Workers. + +### Reinstall the Cloudflare GitLab App + +1. Go to your application settings page on GitLab: [https://gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications) +2. Click the "Revoke" button on your Cloudflare Workers installation if it exists. +3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**. +4. Select the **+ Add account** button, select the GitLab account you want to add, and then select **Install & Authorize**. +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/git-integration/index.mdx b/src/content/docs/workers/ci-cd/builds/git-integration/index.mdx new file mode 100644 index 00000000000000..b408ab1644c2a7 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/git-integration/index.mdx @@ -0,0 +1,38 @@ +--- +pcx_content_type: configuration +title: Git integration +description: Learn how to add and manage your Git integration for Workers Builds +sidebar: + order: 3 +--- + +Cloudflare supports connecting your [GitHub](/workers/ci-cd/builds/git-integration/github-integration/) and [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/) repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change to a selected branch. + +Adding a Git integration also lets you monitor build statuses directly in your Git provider using [check runs](/workers/ci-cd/builds/git-integration/github-integration/#check-run) or [commit statuses](/workers/ci-cd/builds/git-integration/gitlab-integration/#commit-status), so you can manage deployments without leaving your workflow. + +## Supported Git Providers + +Cloudflare supports connecting Cloudflare Workers to your GitHub and GitLab repositories. Workers Builds does not currently support connecting self-hosted instances of GitHub or GitLab. + +If you using a different Git provider (e.g. Bitbucket), you can use an [external CI/CD provider (e.g. GitHub Actions)](/workers/ci-cd/external-cicd/) and deploy using [Wrangler CLI](/workers/wrangler/commands/#deploy). + +## Add a Git Integration + +Workers Builds provides direct integration with GitHub and GitLab accounts, including both individual and organization accounts, that are _not_ self-hosted. + +If you do not have a Git account linked to your Cloudflare account, you will be prompted to set up an installation to GitHub or GitLab when [connecting a repository](/workers/ci-cd/builds/#get-started) for the first time, or when adding a new Git account. Follow the prompts and authorize the Cloudflare Git integration. + +![Git providers](~/assets/images/workers/platform/ci-cd/workers-git-provider.png) + +You can check the following pages to see if your Git integration has been installed: + +- [GitHub Applications page](https://github.com/settings/installations) (if you are in an organization, select **Switch settings context** to access your GitHub organization settings) +- [GitLab Authorized Applications page](https://gitlab.com/-/profile/applications) + +For details on providing access to organization accounts, see [GitHub organizational access](/workers/ci-cd/builds/git-integration/github-integration/#organizational-access) and [GitLab organizational access](/workers/ci-cd/builds/git-integration/gitlab-integration/#organizational-access). + +## Manage a Git Integration + +You can manage the Git installation associated with your repository connection by navigating to the Worker, then going to **Settings** > **Builds** and selecting **Manage** under **Git Repository**. + +This can be useful for managing repository access or troubleshooting installation issues by reinstalling. For more details, see the [GitHub](/workers/ci-cd/builds/git-integration/github-integration) and [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration) guides for how to manage your installation. diff --git a/src/content/docs/workers/ci-cd/builds/index.mdx b/src/content/docs/workers/ci-cd/builds/index.mdx index 32d78bef7eaeff..5944da38fa8ae1 100644 --- a/src/content/docs/workers/ci-cd/builds/index.mdx +++ b/src/content/docs/workers/ci-cd/builds/index.mdx @@ -1,26 +1,48 @@ --- 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 +description: Use Workers Builds to integrate with Git and automatically build and deploy your Worker when pushing a change sidebar: group: 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. +Workers Builds allows you to connect an _existing Worker_ to its GitHub or GitLab repository, enabling automated builds and deployments for your project on push. -## Get Started +Support for creating a _new Worker_ from importing a Git repository is coming soon. -To set up your Git integration with Workers: +## Get started -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. +If you have an existing Worker and have pushed the project to a Git repository, you can now connect the repository to your Worker, enabling automatic builds and deployments. -## View Build Details +To set up builds for your Worker: -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. +1. Select your Worker in the [Workers & Pages Dashboard](https://dash.cloudflare.com) and navigate to **Settings > Build**. +2. Select the Git provider you would like to connect to or select **Connect** and follow the prompts to install the Cloudflare [Git integration](/workers/ci-cd/builds/git-integration/) on your Git account. +3. Configure your [build settings](/workers/ci-cd/builds/configuration/) by selecting your desired Git repository, branch, and configure commands for your build. +4. Push a commit to your Git repository to trigger a build and deploy for 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**. +:::caution + +When connecting a repository to a Workers project, the Worker name in the Cloudflare dashboard must match the `name` in the wrangler.toml file in the specified root directory, or the build will fail. This ensures that the Worker deployed from the repository is consistent with the Worker registered in the Cloudflare dashboard. For details, see [Workers name requirement](/workers/ci-cd/builds/troubleshoot/#workers-name-requirement). + +::: + +## View build and preview URL + +You can monitor a build's status and its build logs by navigating to **View build history** at the bottom of the **Deployments** tab of your Worker. + +If the build is successful, you can view the build details by selecting **View build** in the associated new [version](/workers/configuration/versions-and-deployments/) created under Version History. There you will also find the [preview URL](/workers/configuration/previews/) generated by the version under Version ID. + +:::note[Builds, versions, deployments] + +If a build succeeds, it is uploaded as a version. If the build is configured to deploy (for example, with `wrangler deploy` set as the deploy command), the uploaded version will be automatically promoted to the Active Deployment. + +::: + +## Disconnecting builds + +To disable automatic builds and deployments from your Git repository, go to **Settings** > **Builds** and select **Disconnect** under **Git Repositories**. If you want to switch to a different repository for your Worker, you must first disable builds, then reconnect to select the new repository. + +To disable automatic deployments while still allowing builds to run automatically and save as [versions](/workers/configuration/versions-and-deployments/) (without promoting them to an active deployment), update your deploy command to: `npx wrangler versions upload`. 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 index dd743b8326f377..f6bf58b7e0f3c6 100644 --- a/src/content/docs/workers/ci-cd/builds/limits-and-pricing.mdx +++ b/src/content/docs/workers/ci-cd/builds/limits-and-pricing.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: concept -title: Limits & Pricing +title: Limits & pricing description: Limits & pricing for Workers Builds sidebar: order: 8 @@ -19,7 +19,7 @@ While in open beta, the following limits are applicable for Workers Builds. Plea | **Memory** | Amount of memory available to the build. | 8GB | | **Disk space** | Disk space available to your build | 8GB | -## Future Pricing +## Future pricing During the beta, Workers Builds will be free to try with the limits stated above. diff --git a/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx b/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx index 1a367c2d24ffb0..4c1bc495026ef5 100644 --- a/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx +++ b/src/content/docs/workers/ci-cd/builds/troubleshoot.mdx @@ -1,18 +1,61 @@ --- pcx_content_type: troubleshooting -title: Troubleshooting -description: Learn about troubleshooting and known issues in Workers Builds. +title: Troubleshooting builds +description: Learn how to troubleshoot common and known issues in Workers Builds. sidebar: order: 9 --- -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**. +This guide explains how to identify and resolve build errors, as well as troubleshoot common issues in the Workers Builds deployment process. -While Workers Builds is in Open Beta, the following issues and limitations may apply: +To view your build history, go to your Worker project in the Cloudflare dashboard, select **Deployment**, select **View Build History** at the bottom of the page, and select the build you want to view. To retry a build, select the ellipses next to the build and select **Retry build**. Alternatively, you can select **Retry build** on the Build Details page. -- **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). +## Known issues or limitations -If you discover additional issues or would like to provide feedback, please notify us in the [Discord](https://discord.com/channels/595317990191398933/1052656806058528849). +Here are some common build errors that may surface in the build logs or general issues and how you can resolve them. + +### Workers name requirement + +`✘ [ERROR] The name in your wrangler.toml file () must match the name of your Worker. Please update the name field in your wrangler.toml file.` + +When connecting a Git repository to your Workers project, the specified name for the Worker on the Cloudflare dashboard must match the `name` argument in the wrangler.toml file located in the specified root directory. If it does not match, update the name field in your wrangler.toml file to match the name of the Worker on the dashboard. + +The build system uses the `name` argument in the wrangler.toml to determine which Worker to deploy to Cloudflare's global network. This requirement ensures consistency between the Worker's name on the dashboard and the deployed Worker. + +:::note +This does not apply to [Wrangler Environments](/workers/wrangler/environments/) if the Worker name before the `-` suffix matches the name in wrangler.toml. + +For example, a Worker named `my-worker-staging` on the dashboard can be deployed from a repository that contains a wrangler.toml with the arguments `name = my-worker` and `[env.staging]` using the deploy command `npx wrangler deploy --env staging`. +::: + +### Missing wrangler.toml + +`✘ [ERROR] Missing entry-point: The entry-point should be specified via the command line (e.g. wrangler deploy path/to/script) or the main config field.` + +If you see this error, a wrangler.toml is likely missing from the root directory. Navigate to **Settings** > **Build** > **Build Configuration** to update the root directory, or add a [wrangler.toml](/workers/wrangler/configuration/) to the specified directory. + +### Incorrect account_id + +`Could not route to /client/v4/accounts//workers/services/, perhaps your object identifier is invalid? [code: 7003]` + +If you see this error, the wrangler.toml likely has an `account_id` for a different account. Remove the `account_id` argument or update it with your account's `account_id`, available in **Workers & Pages Overview** under **Account Details**. + +### Stale API token + +` Failed: The build token selected for this build has been deleted or rolled and cannot be used for this build. Please update your build token in the Worker Builds settings and retry the build.` + +The API Token dropdown in Build Configuration settings may show stale tokens that were edited, deleted, or rolled. If you encounter an error due to a stale token, create a new API Token and select it for the build. + +### Build timed out + +`Build was timed out` + +There is a maximum build duration of 20 minutes. If a build exceeds this time, then the build will be terminated and the above error log is shown. For more details, see [Workers Builds limits](/workers/ci-cd/builds/limits-and-pricing/). + +### Git integration issues + +If you are running into errors associated with your Git integration, you can try removing access to your [GitHub](/workers/ci-cd/builds/git-integration/github-integration/#removing-access) or [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/#removing-access) integration from Cloudflare, then reinstalling the [GitHub](/workers/ci-cd/builds/git-integration/github-integration/#reinstall-a-git-integration) or [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/#reinstall-a-git-integration) integration. + +## For additional support + +If you discover additional issues or would like to provide feedback, reach out to us in the [Cloudflare Developers Discord](https://discord.com/channels/595317990191398933/1052656806058528849). diff --git a/src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx b/src/content/docs/workers/ci-cd/external-cicd/gitlab-cicd.mdx similarity index 99% rename from src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx rename to src/content/docs/workers/ci-cd/external-cicd/gitlab-cicd.mdx index 87e8f0f69000c7..ecc25e37d5ac5b 100644 --- a/src/content/docs/workers/ci-cd/external-cicd/gitlab-pipelines.mdx +++ b/src/content/docs/workers/ci-cd/external-cicd/gitlab-cicd.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: how-to -title: GitLab Pipelines +title: GitLab CI/CD description: Integrate Workers development into your existing GitLab Pipelines workflows. --- diff --git a/src/content/docs/workers/ci-cd/external-cicd/index.mdx b/src/content/docs/workers/ci-cd/external-cicd/index.mdx index 2dd07281ac60e3..77c39b6fb084af 100644 --- a/src/content/docs/workers/ci-cd/external-cicd/index.mdx +++ b/src/content/docs/workers/ci-cd/external-cicd/index.mdx @@ -9,6 +9,6 @@ Deploying Cloudflare Workers with CI/CD ensures reliable, automated deployments 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/) +- [**GitLab CI/CD**](/workers/ci-cd/external-cicd/gitlab-cicd/) 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 index 1e647cea4a41d2..ae936ee0273a91 100644 --- a/src/content/docs/workers/ci-cd/index.mdx +++ b/src/content/docs/workers/ci-cd/index.mdx @@ -6,15 +6,16 @@ sidebar: order: 8 --- -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. +You can set up continuous integration and continuous deployment (CI/CD) for your Workers by using either the integrated 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: +Using a CI/CD pipeline to deploy your Workers is a best practice because it: -- 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 +- Automates the build and deployment process, removing the need for manual `wrangler deploy` commands. +- Ensures consistent builds and deployments across your team by using the same source control management (SCM) system. +- Reduces variability and errors by deploying in a uniform environment. +- Simplifies managing access to production credentials. ## Which CI/CD should I use? @@ -22,20 +23,20 @@ Choose [Workers Builds](/workers/ci-cd/builds) if you want a fully integrated so 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 +- You have a self-hosted instance of GitHub or GitLabs, which is currently not supported in Workers Builds' [Git integration](/workers/ci-cd/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](/workers/ci-cd/builds) is Cloudflare's native CI/CD system that allows you to integrate with GitHub or GitLab to automatically deploy changes with each new push to a selected branch (e.g. `main`). ![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). +Ready to streamline your Workers deployments? 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/) +- [GitLab CI/CD](/workers/ci-cd/external-cicd/gitlab-cicd/) diff --git a/src/content/docs/workers/get-started/dashboard.mdx b/src/content/docs/workers/get-started/dashboard.mdx index 7162f89e4be2a1..75d3c45499c09b 100644 --- a/src/content/docs/workers/get-started/dashboard.mdx +++ b/src/content/docs/workers/get-started/dashboard.mdx @@ -6,10 +6,9 @@ sidebar: head: - tag: title content: Get started - Dashboard - --- -import { Render } from "~/components" +import { Render } from "~/components"; Follow this guide to create a Workers application using [the Cloudflare dashboard](https://dash.cloudflare.com). @@ -38,6 +37,7 @@ To create a Workers application: To do more: +- Push your project to a GitHub or GitLab respoitory then [connect to builds](/workers/ci-cd/builds/#get-started) to enable automatic builds and deployments. - Review our [Examples](/workers/examples/) and [Tutorials](/workers/tutorials/) for inspiration. - Set up [bindings](/workers/runtime-apis/bindings/) to allow your Worker to interact with other resources and unlock new functionality. - Learn how to [test and debug](/workers/testing/) your Workers. diff --git a/src/content/docs/workers/get-started/guide.mdx b/src/content/docs/workers/get-started/guide.mdx index 2c81d3294e5071..0356e21b0ef5ef 100644 --- a/src/content/docs/workers/get-started/guide.mdx +++ b/src/content/docs/workers/get-started/guide.mdx @@ -191,7 +191,7 @@ Preview your Worker at `..workers.dev`.
-If you see [`523` errors](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-523-origin-is-unreachable) when pushing your `*.workers.dev` subdomain for the first time, wait a minute or so and the errors will resolve themselves. +If you see [`523` errors](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-523-origin-is-unreachable) when pushing your `*.workers.dev` subdomain for the first time, wait a minute or so and the errors will resolve themselves.
@@ -199,6 +199,7 @@ If you see [`523` errors](/support/troubleshooting/cloudflare-errors/troubleshoo To do more: +- Push your project to a GitHub or GitLab respoitory then [connect to builds](/workers/ci-cd/builds/#get-started) to enable automatic builds and deployments. - Visit the [Cloudflare dashboard](https://dash.cloudflare.com/) for simpler editing. - Review our [Examples](/workers/examples/) and [Tutorials](/workers/tutorials/) for inspiration. - Set up [bindings](/workers/runtime-apis/bindings/) to allow your Worker to interact with other resources and unlock new functionality.