From b68f2ecf82425a8840ef66fea1a5703da9f057c4 Mon Sep 17 00:00:00 2001 From: yomna Date: Mon, 1 Dec 2025 15:54:32 -0500 Subject: [PATCH 1/2] adding build image policies for Workers Builds and Pages --- ...25-12-01-build-image-policies-dev-plat.mdx | 17 ++++++++ .../docs/pages/configuration/build-image.mdx | 39 +++++++++++++++++++ .../docs/workers/ci-cd/builds/build-image.mdx | 19 +++++++++ 3 files changed, 75 insertions(+) create mode 100644 src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx diff --git a/src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx b/src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx new file mode 100644 index 000000000000000..9dd5656383852f5 --- /dev/null +++ b/src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx @@ -0,0 +1,17 @@ +--- +title: Build image policies for Workers Builds and Cloudflare Pages +description: Workers Builds and Cloudflare Pages now have documented build image policies outlining deprecation timelines and version update procedures. +products: + - workers +date: 2025-12-01 +--- + +We've published build image policies for [Workers Builds](/workers/ci-cd/builds/build-image) and [Cloudflare Pages](/pages/configuration/build-image) that establish: + +- **Minor version updates** happen automatically without notice +- **Major version updates** require at least 3 months advance notice when language runtimes or tools approach their end-of-life dates +- **Build image version deprecation** (Pages only): Build image versions are supported for at least 2 years and will receive at least 6 months notice before removal + +When deprecations or major updates are announced, you'll receive notifications via the Cloudflare Changelog, dashboard notifications, and email. + +To avoid unexpected build failures, we recommend [pinning specific versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) for production applications and monitoring the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), as well as the dashboard, and your emails. \ No newline at end of file diff --git a/src/content/docs/pages/configuration/build-image.mdx b/src/content/docs/pages/configuration/build-image.mdx index f7c840fa048ae63..22e170ba00cc461 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/src/content/docs/pages/configuration/build-image.mdx @@ -105,3 +105,42 @@ The following features are not currently supported when using the v3 build syste Cloudflare Pages builds are run in a [gVisor](https://gvisor.dev/docs/) container. + + +## Build Image Policy + +New versions come with improvements (vibe) + +### Image Version Deprecation + +Build image versions are deprecated when they only contain end-of-life (EOL) software that is no longer maintained by upstream providers. +Build image versions are deprecated 2 years (at least two years before being ) + +**Deprecation timeline**: We provide at least 6 months notice before removing support for a build image version. + +**Deprecation process**: +1. **Announcement** via [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications +2. **Deprecation warnings** displayed prominently in dashboard for affected projects +3. **Email notifications** to project owners upon announcement +4. **Final removal** on the announced date; the deprecated image version will no longer be available for new deployments prior to being forced upgraded to next major + +Existing deployments using deprecated build images will continue to function, but new builds will require migration to a supported version. + +### Default Version Updates + +Within each build image version, default versions of languages and tools are updated regularly to their latest stable releases. We provide advance notice before making updates that may impact your builds: + +- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/pages/configuration/build-image/#override-default-versions). + +- **Major version updates**: Updates will only occur when Node.js approaches its EOL date. When updating Node.js, we also update related tools and dependencies to their latest stable versions. We will provide at least 3 months advance notice via: + - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) + - Dashboard notification to affected projects upon announcement + - Email notification to affected projects upon announcement + +### Best Practices + +To avoid unexpected build failures: +- **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications +- **Test migrations** when switching to a new build image version or when default versions are updated +- **Pin specific versions** of critical dependencies by [overriding default versions](/pages/configuration/build-image/#override-default-versions) +- **Plan for migration** when you receive deprecation notices—waiting until the last minute may cause service disruption \ No newline at end of file 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 e49d9c48993c9d0..e58bd2b8c998096 100644 --- a/src/content/docs/workers/ci-cd/builds/build-image.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-image.mdx @@ -88,3 +88,22 @@ Workers Builds are run in the following environment: | --------------------- | ------------ | | **Build Environment** | Ubuntu 24.04 | | **Architecture** | x86_64 | + + +## Build Image Policy + +### Default Version Updates + +Default versions of languages and tools are updated regularly to their latest stable releases. + +- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions). + +- **Major version updates**: When a language runtime or tool approaches its end-of-life (EOL) date, e.g. Node.js, we update to the latest supported version. We will provide at least 3 months advance notice via + - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) + - Dashboard notification to affected projects upon announcement + +### Best Practices + +To avoid unexpected build failures: +- **Pin specific versions** for production applications by [overriding default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) +- Monitor the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) for upcoming updates From e3f58f6cfe5c18321a6b586015dbece1b057b84d Mon Sep 17 00:00:00 2001 From: yomna Date: Mon, 1 Dec 2025 16:11:45 -0500 Subject: [PATCH 2/2] uploading saved new version of pages --- .../docs/pages/configuration/build-image.mdx | 22 ++++++++----------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/src/content/docs/pages/configuration/build-image.mdx b/src/content/docs/pages/configuration/build-image.mdx index 22e170ba00cc461..85800c9b97e7913 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/src/content/docs/pages/configuration/build-image.mdx @@ -109,38 +109,34 @@ Cloudflare Pages builds are run in a [gVisor](https://gvisor.dev/docs/) containe ## Build Image Policy -New versions come with improvements (vibe) +New build image versions bring improvements to tooling, security, and performance. ### Image Version Deprecation -Build image versions are deprecated when they only contain end-of-life (EOL) software that is no longer maintained by upstream providers. -Build image versions are deprecated 2 years (at least two years before being ) +Build image versions are supported for at least 2 years before a deprecation is announced. **Deprecation timeline**: We provide at least 6 months notice before removing support for a build image version. **Deprecation process**: 1. **Announcement** via [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications 2. **Deprecation warnings** displayed prominently in dashboard for affected projects -3. **Email notifications** to project owners upon announcement -4. **Final removal** on the announced date; the deprecated image version will no longer be available for new deployments prior to being forced upgraded to next major +3. **Email notifications** to project owners +4. **Final removal** on the announced date; projects using the deprecated image will be automatically upgraded to the next supported version -Existing deployments using deprecated build images will continue to function, but new builds will require migration to a supported version. ### Default Version Updates -Within each build image version, default versions of languages and tools are updated regularly to their latest stable releases. We provide advance notice before making updates that may impact your builds: +Default versions of languages and tools are updated regularly to their latest stable releases. -- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/pages/configuration/build-image/#override-default-versions). +- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions). -- **Major version updates**: Updates will only occur when Node.js approaches its EOL date. When updating Node.js, we also update related tools and dependencies to their latest stable versions. We will provide at least 3 months advance notice via: +- **Major version updates**: When a language runtime or tool approaches its end-of-life (EOL) date, e.g. Node.js, we update to the latest supported version. We will provide at least 3 months advance notice via - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) - Dashboard notification to affected projects upon announcement - - Email notification to affected projects upon announcement ### Best Practices To avoid unexpected build failures: - **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications -- **Test migrations** when switching to a new build image version or when default versions are updated -- **Pin specific versions** of critical dependencies by [overriding default versions](/pages/configuration/build-image/#override-default-versions) -- **Plan for migration** when you receive deprecation notices—waiting until the last minute may cause service disruption \ No newline at end of file +- **Plan for migration** when you receive deprecation notices +- **Pin specific versions** of critical dependencies by [overriding default versions](/pages/configuration/build-image/#override-default-versions) \ No newline at end of file