You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adding build image policies for Workers Builds and Pages Builds (#26840)
* adding build image policies for Workers Builds and Pages
* uploading saved new version of pages
* updated verbiage to be more clear
* adding feedback
* updated wording of policies and changelog
* updated wording of policies and changelog
* add dates
title: Build image policies for Workers Builds and Cloudflare Pages
3
+
description: Workers Builds and Cloudflare Pages now have documented build image policies outlining deprecation timelines and version update procedures.
4
+
products:
5
+
- workers
6
+
date: 2025-12-18
7
+
---
8
+
9
+
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), which establish:
10
+
11
+
-**Minor version updates**: We typically update preinstalled software to the latest available minor version without notice. For tools that don't follow semantic versioning (e.g., Bun or Hugo), we provide 3 months’ notice.
12
+
-**Major version updates**: Before preinstalled software reaches end-of-life, we update to the next stable LTS version with 3 months’ notice.
13
+
-**Build image version deprecation (Pages only)**: We provide 6 months’ notice before deprecation. Projects on v1 or v2 will be automatically moved to v3 on their specified deprecation dates.
14
+
15
+
To prepare for updates, monitor the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), dashboard notifications, and email. You can also [override default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) to maintain specific versions.
Copy file name to clipboardExpand all lines: src/content/docs/pages/configuration/build-image.mdx
+35Lines changed: 35 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -105,3 +105,38 @@ The following features are not currently supported when using the v3 build syste
105
105
Cloudflare Pages builds are run in a [gVisor](https://gvisor.dev/docs/) container.
106
106
107
107
<PagesBuildEnvironment />
108
+
109
+
110
+
## Build Image Policy
111
+
112
+
### Build Image Version Deprecation
113
+
114
+
If you are currently using the v1 or v2 build image, your project will be automatically moved to v3:
115
+
116
+
-**v1 build image**: If you are using the Pages v1 build image, your project will be automatically moved to v3 on August 25, 2026.
117
+
-**v2 build image**: If you are using the Pages v2 build image, your project will be automatically moved to v3 on February 23, 2027.
118
+
119
+
You will receive 6 months’ notice before the deprecation date via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), dashboard notifications, and email.
120
+
121
+
Going forward, the v3 build image will receive rolling updates to preinstalled software per the policy below. There will be no further build image version changes.
122
+
123
+
### Preinstalled Software Updates
124
+
125
+
Preinstalled software (languages and tools) will be updated before reaching end-of-life (EOL). These updates apply only if you have not [overridden the default version](/pages/configuration/build-image/#override-default-versions).
126
+
127
+
-**Minor version updates**: May be updated to the latest available minor version without notice. For tools that do not follow semantic versioning (e.g., Bun or Hugo), updates that may contain breaking changes will receive 3 months’ notice.
128
+
-**Major version updates**: Updated to the next stable long-term support (LTS) version with 3 months’ notice.
129
+
130
+
**How you'll be notified (for changes requiring notice):**
- Dashboard notifications for projects that will receive the update
133
+
- Email notifications to project owners
134
+
135
+
To maintain a specific version and avoid automatic updates, [override the default version](/pages/configuration/build-image/#override-default-versions).
136
+
137
+
### Best Practices
138
+
139
+
To avoid unexpected build failures:
140
+
-**Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), dashboard notifications, and email
141
+
-**Plan for migration** when you receive update notices
142
+
-**Pin specific versions** of critical preinstalled software by [overriding default versions](/pages/configuration/build-image/#override-default-versions)
Copy file name to clipboardExpand all lines: src/content/docs/workers/ci-cd/builds/build-image.mdx
+23Lines changed: 23 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -88,3 +88,26 @@ Workers Builds are run in the following environment:
88
88
| --------------------- | ------------ |
89
89
|**Build Environment**| Ubuntu 24.04 |
90
90
|**Architecture**| x86_64 |
91
+
92
+
93
+
## Build Image Policy
94
+
95
+
### Preinstalled Software Updates
96
+
97
+
Preinstalled software (languages and tools) will be updated before reaching end-of-life (EOL). These updates apply only if you have not [overridden the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions).
98
+
99
+
-**Minor version updates**: May be updated to the latest available minor version without notice. For tools that do not follow semantic versioning (e.g., Bun or Hugo), updates that may contain breaking changes will receive 3 months’ notice.
100
+
-**Major version updates**: Updated to the next stable long-term support (LTS) version with 3 months’ notice.
101
+
102
+
**How you'll be notified (for changes requiring notice):**
- Dashboard notifications for projects that will receive the update
105
+
- Email notifications to project owners
106
+
107
+
To maintain a specific version and avoid automatic updates, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions).
108
+
109
+
### Best Practices
110
+
111
+
To avoid unexpected build failures:
112
+
-**Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), dashboard notifications, and email
113
+
-**Pin specific versions** of critical preinstalled software by [overriding default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions)
0 commit comments