Builds and It's Completely Different but Also Still Build #18955
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
aninibread
requested review from
irvinebroque,
GregBrimble,
ToriLindsay,
a team,
WalshyDev and
mikenomitch
as code owners
github-actions
bot
added
product:pages
product:workers
|
This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:
|
![hyperlint-ai[bot]](https://avatars.githubusercontent.com/in/718456?s=60&v=4){kind=small}
src/content/docs/pages/configuration/git-integration/github-integration.mdx
Show resolved
Hide resolved
src/content/docs/pages/configuration/git-integration/github-integration.mdx
Show resolved
Hide resolved
src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx
Show resolved
Hide resolved
src/content/docs/workers/ci-cd/builds/git-integration/gitlab-integration.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/workers/ci-cd/builds/git-integration/github-integration.mdx
Show resolved
Hide resolved
src/content/docs/workers/ci-cd/builds/git-integration/github-integration.mdx
Show resolved
Hide resolved
Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
src/content/docs/workers/ci-cd/builds/git-integration/github-integration.mdx
Show resolved
Hide resolved
src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx
Show resolved
Hide resolved
src/content/docs/workers/ci-cd/builds/git-integration/gitlab-integration.mdx
Show resolved
Hide resolved
Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
…udflare-docs into anni/wb-checkruns
src/content/docs/pages/configuration/git-integration/gitlab-integration.mdx
Show resolved
Hide resolved
src/content/docs/workers/ci-cd/builds/git-integration/gitlab-integration.mdx
Show resolved
Hide resolved
Deploying cloudflare-docs with
|
| Latest commit: |
a1403a9
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6329b7ee.cloudflare-docs-7ou.pages.dev |
| Branch Preview URL: | https://anni-wb-checkruns.cloudflare-docs-7ou.pages.dev |
Maximo-Guk
reviewed
Dec 30, 2024
|
|
||
| ## Managing access | ||
|
|
||
| You can deploy projects to Cloudflare Workers from your open-source team, company, or side project on GitHub using the [Cloudflare Workers & Pages GitHub App](https://github.com/apps/cloudflare-workers-and-pages). |
There was a problem hiding this comment.
Does it make sense to specify "open-source" for team? Your team doesn't need to be open-source to use the app
Maximo-Guk
reviewed
Dec 30, 2024
|
|
||
| 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 Automatic Deployments](/pages/configuration/git-integration/#disable-automatic-deployments) instructions. | ||
|
|
||
| Note that removing access to GitHub will disable new builds for Workers and Pages project that were connected to those repositories, though the last build of your project will continue to be hosted via Cloudflare Workers. |
There was a problem hiding this comment.
Maybe this should be "your previous deployments will continue to be hosted"
Maximo-Guk
reviewed
Dec 30, 2024
|
|
||
| :::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. You can modify these permissions by going to the [Applications page](https://github.com/settings/installations) on GitHub, 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. |
There was a problem hiding this comment.
build with Pages
Should probably be modified to refer to workers builds
Maximo-Guk
reviewed
Dec 30, 2024
|
|
||
| ### Removing 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. |
There was a problem hiding this comment.
We should probably rename the Gitlab app to Cloudflare Workers and Pages yet to match GitHub app name at some point
Maximo-Guk
reviewed
Dec 30, 2024
|
|
||
| ### Git Integration Issues | ||
|
|
||
| If you are running into errors associated with your Git integration, you can try removing access to your GitHub or GitLab integration from Cloudflare, then reinstalling the Git integration. |
There was a problem hiding this comment.
Maybe we could add a docs link here on how to reinstall
irvinebroque
approved these changes
Dec 31, 2024
| 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| After you enable build caching on your Pages project, the first build that runs will populate the build cache. Each subsequent build will restore from cache unless otherwise configured. |
"otherwise configured" == you purge cache?
| 2. In Account Home, select **Workers & Pages**. | ||
| 3. In **Overview**, select your Pages project. | ||
| 4. Go to **Settings** > **Build** > **Build cache** and select **Enable**. | ||
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. |
There was a problem hiding this comment.
Suggested change
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. | |
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com/?to=/:account/workers-and-pages/) on the Dashboard. |
| 3. In **Overview**, select your Pages project. | ||
| 4. Go to **Settings** > **Build** > **Build cache**. | ||
| 5. Select **Clear Cache** to clear the build cache. | ||
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. |
There was a problem hiding this comment.
Suggested change
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard. | |
| 1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com/?to=/:account/workers-and-pages) on the Dashboard. |
| title: GitHub integration | ||
| --- | ||
|
|
||
| Cloudflare supports connecting Cloudflare Pages to your GitHub repositories, and will automatically deploy your code everytime you push a change to a branch. |
There was a problem hiding this comment.
Suggested change
| Cloudflare supports connecting Cloudflare Pages to your GitHub repositories, and will automatically deploy your code everytime you push a change to a branch. | |
| 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. |
|
|
||
| ### 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** > **Branch control**. To change the production branch, click the **Production branch** dropdown menu and choose any other branch. |
There was a problem hiding this comment.
This could be more specific, right?
It's really just — if a branch other than the default branch (ex: main or master) represents your project's production build, do x.
"custom Git workflow" sounds like it could mean many things
|
|
||
| Using Git integration with Cloudflare also provides: | ||
|
|
||
| - **Preview deployments for custom branches**, generating preview URLs for a commit to any branch in the repository without affecting your production deployment. |
There was a problem hiding this comment.
Doesn't seem like this one should be first in the list, since first you kind of have to understand what a preview url is
|
|
||
| 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] |
There was a problem hiding this comment.
Worth calling out that this is not the case with Workers?
|
|
||
| ## Supported Git Providers | ||
|
|
||
| Cloudflare Pages supports the following Git providers: |
There was a problem hiding this comment.
It seems simpler to say — we support GitHub and GitLab, except not if you self-host — right?
The pricing/plan level stuff isn't really the relevant detail, it's whether what you're running is cloud hosted or self hosted.
|
|
||
| If you use [GitHub Enterprise Server](https://docs.github.com/en/[email protected]/admin/overview/about-github-enterprise-server), [Self-Managed GitLab](https://about.gitlab.com/pricing/), or another Git provider (e.g., Bitbucket), you can: | ||
|
|
||
| - Start with a Direct Upload project and deploy using a [CI/CD provider with Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). |
There was a problem hiding this comment.
This seems like the actual recommended path — worth saying GitHub Actions by name here since we're talking about GitHub anyways
| If you use [GitHub Enterprise Server](https://docs.github.com/en/[email protected]/admin/overview/about-github-enterprise-server), [Self-Managed GitLab](https://about.gitlab.com/pricing/), or another Git provider (e.g., Bitbucket), you can: | ||
|
|
||
| - Start with a Direct Upload project and deploy using a [CI/CD provider with Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). | ||
| - Or, [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) in a Git-integrated project and use a [CI/CD provider with Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). |
There was a problem hiding this comment.
This is confusing if I'm starting anything new? Is it necessary to call out in a way here where it's a recommended path? This is a workaround for being restrictive/prescriptive about not mixing together direct upload and pages builds, right?
ToriLindsay
requested changes
Jan 3, 2025
|
|
||
| Then, you can use Wrangler to deploy directly to your Pages project and make changes to your Git repository without automatically triggering a build. | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
Maybe you'd also want to consider breaking Troubleshooting into it's own article, beneath the other three in the "Git Integration" sections for both Workers and Pages?
| - Start with a Direct Upload project and deploy using a [CI/CD provider with Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). | ||
| - Or, [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) in a Git-integrated project and use a [CI/CD provider with Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/). | ||
|
|
||
| ## Adding Git Integration |
There was a problem hiding this comment.
Suggested change
| ## Adding Git Integration | |
| ## Add a Git integration |
Could also be "Set up a Git integration" or any other direct verb.
Also, "integration" should be lowercase for consistency.
|
|
||
| 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. | ||
|
|
||
| ## Managing Git Integration |
There was a problem hiding this comment.
Suggested change
| ## Managing Git Integration | |
| ## Manage a Git integration |
Same as above. It could also be "Manage the Git integration" or "Manage your Git integration". Whatever you think is best.
|
|
||
| #### `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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| You cannot use the same GitHub/GitLab repository with multiple Cloudflare accounts. To use a Pages project with a different Cloudflare account, delete it from the current Cloudflare account first. |
Just simplifying the wording
|
|
||
|  | ||
|
|
||
| To resolve any errors displayed in the Cloudflare Pages dashboard, follow the steps listed below. |
There was a problem hiding this comment.
Suggested change
| To resolve any errors displayed in the Cloudflare Pages dashboard, follow the steps listed below. | |
| To resolve an error displayed in the Cloudflare Pages dashboard, find it below and follow the instructions. |
Minor. Just thought this is clearer since there aren't actually "steps" listed anywhere below here.
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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. |
| @@ -6,36 +6,37 @@ 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 Builds build times by caching dependencies and build output between builds with a project-wide shared cache. | |||
There was a problem hiding this comment.
Suggested change
| Improve Workers Builds build times by caching dependencies and build output between builds with a project-wide shared cache. | |
| Improve Workers build times by caching dependencies and build output between builds with a project-wide shared cache. |
| 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 Builds build times by caching dependencies and build output between builds with a project-wide shared cache. | ||
|
|
||
| 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. | ||
|
|
||
| ## Configuration |
There was a problem hiding this comment.
I left some feedback on the structure of the Pages build-caching article (above). It would still be good for the articles to mirror each other, so consider the same approach for this one.
| @@ -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. | |||
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - 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. |
|
|
||
| </Details> | ||
|
|
||
| ## Next steps | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - 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. |
|
@aninibread I don't want to block you if you need to move ahead with this quickly, so let me know, but I think 90% of the changes I suggested can be resolved quickly since they are mostly grammar and typos. It's up to you what you have time for in terms of the broader structural suggestions. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Revamp builds documentation for Workers and Pages. Focused on git integration.
Screenshots (optional)
Documentation checklist