From b68f2ecf82425a8840ef66fea1a5703da9f057c4 Mon Sep 17 00:00:00 2001 From: yomna Date: Mon, 1 Dec 2025 15:54:32 -0500 Subject: [PATCH 1/3] 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/3] 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 From 5267d67f11d3cf70ea0666921d39d551b9692a6d Mon Sep 17 00:00:00 2001 From: yomna Date: Tue, 2 Dec 2025 17:25:04 -0500 Subject: [PATCH 3/3] updated verbiage to be more clear --- ...25-12-01-build-image-policies-dev-plat.mdx | 14 +++++------ .../docs/pages/configuration/build-image.mdx | 25 +++++++++++-------- .../docs/workers/ci-cd/builds/build-image.mdx | 14 ++++++----- 3 files changed, 29 insertions(+), 24 deletions(-) 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 index 9dd5656383852f5..2f37464b750ac22 100644 --- 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 @@ -6,12 +6,12 @@ products: 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: +We've published build image policies for [Workers Builds](/workers/ci-cd/builds/build-image/#build-image-policy) and [Cloudflare Pages](/pages/configuration/build-image/#build-image-policy) 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 +- **Minor version updates**: Default versions are updated to the latest available minor version without notice +- **Major version updates**: When language runtimes or tools reach end-of-life, we update to the next stable LTS version with at least 3 months advance notice via Changelog and dashboard notifications +- **Build image version deprecation** (Pages only): Build image versions are supported for at least 2 years and receive 6 months notice before removal via Changelog, dashboard notifications, and email -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 +To prepare for updates and avoid unexpected build failures: +- Monitor the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), the dashboard, and your email for announcements +- [Override default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) if you need to maintain specific versions for your applications \ 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 85800c9b97e7913..56eb636c8bc9dad 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/src/content/docs/pages/configuration/build-image.mdx @@ -113,30 +113,33 @@ New build image versions bring improvements to tooling, security, and performanc ### Image Version Deprecation -Build image versions are supported for at least 2 years before a deprecation is announced. +Build image versions are supported for at least 2 years from their initial release before a deprecation is announced. -**Deprecation timeline**: We provide at least 6 months notice before removing support for a build image version. +**Deprecation timeline**: We provide 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 +1. **Announcement** via [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) +2. **Deprecation warnings** displayed in dashboard for projects using the build image version scheduled for deprecation 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 - +4. **Final removal** on the announced date: + - The deprecated image version will no longer be available for selection + - Projects that have not migrated will be automatically upgraded to the latest supported version ### Default Version Updates -Default versions of languages and tools are updated regularly to their latest stable releases. +Default versions of languages and tools are updated as they reach end-of-life (EOL). These updates only apply if you have not [overridden 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). +- **Minor version updates**: Updated to the latest available minor version without notice. -- **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 +- **Major version updates**: Updated to the next stable, long-term support (LTS) version with at least 3 months advance notice via: - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) - - Dashboard notification to affected projects upon announcement + - Dashboard notifications to projects that will receive the default version update + +To maintain a specific version and avoid automatic updates, [override the default version](/pages/configuration/build-image/#override-default-versions). ### Best Practices To avoid unexpected build failures: - **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications - **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 +- **Pin specific versions** of critical dependencies by [overriding default versions](/pages/configuration/build-image/#override-default-versions) to maintain full control over when versions change \ 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 e58bd2b8c998096..a0187bc6711e33a 100644 --- a/src/content/docs/workers/ci-cd/builds/build-image.mdx +++ b/src/content/docs/workers/ci-cd/builds/build-image.mdx @@ -94,16 +94,18 @@ Workers Builds are run in the following environment: ### Default Version Updates -Default versions of languages and tools are updated regularly to their latest stable releases. +Default versions of languages and tools are updated as they reach end-of-life (EOL). These updates only apply if you have not [overridden 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). +- **Minor version updates**: Updated to the latest available minor version without notice. -- **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 +- **Major version updates**: Updated to the next stable, long-term support (LTS) version with at least 3 months advance notice via: - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) - - Dashboard notification to affected projects upon announcement + - Dashboard notifications to projects that will receive the default version update + +To maintain a specific version and avoid automatic updates, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions). ### 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 +- **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications +- **Pin specific versions** of critical dependencies by [overriding default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) to maintain full control over when versions change \ No newline at end of file