Updated Dockerfile reference and updated Dockerfile to match guidance

.github/dependabot.yml

@@ -6,3 +6,8 @@ updates:
     interval: weekly
     time: "03:00"
   open-pull-requests-limit: 10
+- package-ecosystem: docker
+  directory: "/"
+  schedule:
+    interval: weekly
+    time: "03:00"

Dockerfile

@@ -1,4 +1,5 @@
-FROM ruby:3.1.3-buster
+ # 3.1.3-buster
+FROM ruby@sha256:55cd5fab4140db7a04f46921eafcd941be95f6c5687b01154d43e75479ba0fe9
 
 EXPOSE 4567:4567
 EXPOSE 35729:35729

source/manuals/programming-languages/docker.html.md.erb

@@ -11,6 +11,13 @@ This style guide:
 * provides some conventions for creating production-ready Dockerfiles at GDS
 * supplements the official [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
 
+## Why we use Dockerfile
+
+The [Open Container Initiative](https://opencontainers.org/) started in June 2015, and is an open governance structure for creating open standards around container formats.
+Docker were one of the first movers in this space. Their documentation defined the de facto standard and then delegated to the OCI.
+
+The [OCI's documentation on Containerfile](https://github.com/containers/common/blob/main/docs/Containerfile.5.md) is derived from Docker's Dockerfile documentation.
+
 ## Using tags and digests in FROM instructions
 
 The `FROM` instruction specifies the starting image for your Docker image build.
@@ -31,7 +38,10 @@ where:
 As you cannot rely on the tag pointing to the exact same image over time, you
 should instead use a digest, which identifies the image by a hash of its
 contents. This makes sure that you are always referencing the image that you
-expect.
+expect.  Add a comment above the FROM line with the intended tag and version.
+Though dependabot will not use this, please update it when the digest changes
+so that it is possible to understand the magnitude of the change by knowing
+the significance of the version change.
 
 For example:
 
@@ -55,6 +65,19 @@ As [Dependabot](https://dependabot.com) has [support for updating `FROM` lines
 which use digests](https://github.com/dependabot/dependabot-core/pull/100),
 you can still use Dependabot to keep your images up-to-date.
 
+If you specify both the tag and the digest, then the digest takes precedence.
+The standard implies that you may only specify one or the other.  Do not specify
+both as the behaviour may vary across different platforms.
+
+Instead, the recommended way to keep track of the intended version is to add it in a line above FROM as a comment.
+
+Please double-check that the digest and the commented version are consistent each time you upgrade, as dependabot does not have perfect capability at either identifying the magnitude of the upgrade, or necessarily updating the commented pin.
+```
+# alpine:3.9
+FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+...
+```
+
 ## Using multi-stage builds
 
 Using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) enables the drastic
@@ -65,13 +88,16 @@ used in the compilation steps.
 As an example;
 
 ```
-FROM golang:1.16 AS builder
+# golang:bullseye
+FROM golang@sha256:ecb3fe70e1fd6cef4c5c74246a7525c3b7d59c48ea0589bbb0e57b1b37321fb9 AS builder
 WORKDIR /go/src/github.com/alphagov/paas-aiven-broker/
 RUN git clone https://github.com/alphagov/paas-aiven-broker.git .
 RUN go mod download
 RUN go build
 
-FROM alpine:latest
+# alpine:3.9
+FROM alpine@sha256:769fddc7cc2f0a1c35abb2f91432e8beecf83916c421420e6a6da9f8975464b6
+
 RUN apk --no-cache add ca-certificates
 WORKDIR /root/
 COPY --from=builder /go/src/github.com/alphagov/paas-aiven-broker/paas-aiven-broker .

source/standards/source-code/use-github.html.md.erb

@@ -60,12 +60,14 @@ Consider creating a Workflow Template in the [alphagov workflow folder](https://
 If using GitHub-owned actions, [pin to a specific version](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions) and [configure Dependabot to keep your actions up to date](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot#example-dependabotyml-file-for-github-actions) by adding a comment on the same line with the tag the commitsha represents. For example:
 
 ```
-- uses: actions/checkout@01aecccf739ca6ff86c0539fbc67a7a5007bbc81 #v2.1.0
+- uses: actions/checkout@01aecccf739ca6ff86c0539fbc67a7a5007bbc81 # v2.1.0
 ```
 
 Pinned versions should include the semver version in a comment next to the SHA, helping humans understand which versions we are pinned to.
 Where possible, allow automated dependency management tools to scan these version comments and suggest updates.
 
+Please double-check that the digest and the commented version are consistent each time you upgrade, as dependabot does not have perfect capability at either identifying the magnitude of the upgrade, or necessarily updating the commented pin.
+
 Third-party actions should only be used if:
 
 - The provider is verified by GitHub (for example, [aws-actions](https://github.com/aws-actions))