@@ -18,3 +18,64 @@ When the `Dockerfile` file or `cloudbuild.yaml` template in this directory
1818are changed in a PR, the cloud build template is triggered.
1919Then a new version of the image is deployed as the latest version in
2020Container Registry under the ` flutter-dev-230821 ` project on Google Cloud.
21+
22+ ## Updating the Dart SDK version
23+
24+ The base Dart image in ` Dockerfile ` is pinned by both tag and digest:
25+
26+ ``` dockerfile
27+ FROM dart:<version>@<digest>
28+ ```
29+
30+ When updating the Dart SDK version, update both the tag and the digest.
31+ Use the multi-platform image index digest for the tag.
32+ Don't use a platform-specific digest, such as
33+ the digest for only ` linux/amd64 ` or only ` linux/arm64/v8 ` .
34+
35+ ### Using ` crane `
36+
37+ If you have the ` crane ` CLI from [ ` google/go-containerregistry ` ] [ ] , run:
38+
39+ ``` bash
40+ crane digest docker.io/library/dart:< STABLE_DART_SDK_VERSION>
41+ ```
42+
43+ For example, the following command retrieves the digest for
44+ the ` 3.12.1 ` stable release of the SDK:
45+
46+ ``` bash
47+ crane digest docker.io/library/dart:3.12.1
48+ ```
49+
50+ Copy the returned ` sha256:... ` digest.
51+ Then update the ` FROM ` line in the ` Dockerfile ` with
52+ the new tag (version) and copied index digest.
53+
54+ ``` dockerfile
55+ FROM dart:3.12.1@<digest from crane>
56+ ```
57+
58+ Don't pass ` --platform ` when getting the digest for the ` Dockerfile ` .
59+ Passing a platform returns the digest for that platform's child manifest
60+ instead of the architecture-agnostic index digest.
61+
62+ [ `google/go-containerregistry` ] : https://github.com/google/go-containerregistry
63+
64+ ### Using Docker Hub
65+
66+ If you don't have ` crane ` , use the
67+ [ Dart image tags page on Docker Hub] ( https://hub.docker.com/_/dart/tags ) :
68+
69+ 1 . Search for the new Dart SDK version tag, such as ` 3.12.1 ` .
70+ 1 . Open the tag detail page by selecting the tag name or digest.
71+ 1 . Ensure the opened tag page has a ` MULTI-PLATFORM ` badge.
72+ 1 . Copy the specified ` INDEX DIGEST ` value.
73+ It should start with ` sha256: ` .
74+ 1 . Update the ` FROM ` line in the ` Dockerfile ` with
75+ the new tag (SDK version) and index digest.
76+
77+ <img
78+ width="688"
79+ height="248"
80+ alt="Screenshot of the index digest on Docker Hub, outlined with a red box."
81+ src="https://github.com/user-attachments/assets/909bd713-580f-41f5-882b-9afb3b9bbfaf " />
0 commit comments