Add GitCredentialSecret to checkout params

README.md

@@ -12,6 +12,7 @@
   - [Options](#Options)
 - [Sample Buildkite Pipeline](#Sample-Buildkite-Pipelines)
   - [Cloning repos via SSH](#Cloning-repos-via-SSH)
+  - [Cloning repos via HTTPS](#Cloning-repos-via-HTTPS)
   - [Pod Spec Patch](#Pod-Spec-Patch)
   - [Sidecars](#Sidecars)
   - [Extra volume mounts](#Extra-volume-mounts)
@@ -267,6 +268,62 @@ steps:
                   - --image=ttl.sh/example:1h
 ```
 
+### Cloning repos via HTTPS
+
+To use HTTPS to clone private repos, you can use a `.git-credentials` file stored in a secret, and refer to this secret using the `gitCredentialsSecret` checkout parameter.
+
+By default, this secret is only attached to the `checkout` container, and will not necessarily be available in your job containers.
+If you need the `.git-credentials` file inside the other containers as well, you can add a volume mount (of type secret) for the `git-credentials` volume, as needed.
+
+#### Example secret creation for HTTPS cloning
+Once again, this example is illustrative only.
+
+First, create a Kubernetes secret containing the key `.git-credentials`, formatted in the manner expected by [the `store` Git credendial helper](https://git-scm.com/docs/git-credential-store):
+```bash
+kubectl create secret generic my-git-credentials --from-file='.git-credentials'="$HOME/.git-credentials"
+```
+
+Then you can use the `checkout/gitCredentialsSecret` (in your pipeline) or `default-checkout-params/gitCredentialsSecret` (in values.yaml) to reference the secret volume source:
+
+```yaml
+# pipeline.yaml
+steps:
+  - label: build image
+    agents:
+      queue: kubernetes
+    plugins:
+      - kubernetes:
+          checkout:
+            gitCredentialsSecret:
+              secretName: my-git-credentials # <----
+          podSpec:
+            ...
+```
+
+```yaml
+# values.yaml
+...
+default-checkout-params:
+  gitCredentialsSecret:
+    secretName: my-git-credentials
+...
+```
+
+If you wish to use a different key within the secret than `.git-credentials`, you can
+[project it](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#project-secret-keys-to-specific-file-paths)
+to `.git-credentials` by using `items` within `gitCredentialsSecret`.
+
+```yaml
+# values.yaml
+...
+default-checkout-params:
+  gitCredentialsSecret:
+    secretName: my-git-credentials
+    items:
+    - key: funky-creds
+      path: .git-credentials
+...
+```
 
 ### Pod Spec Patch
 Rather than defining the entire Pod Spec in a step, there is the option to define a [strategic merge patch](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/) in the controller.

charts/agent-stack-k8s/values.schema.json

@@ -252,6 +252,9 @@
               "default": null,
               "title": "If set, appends the BUILDKITE_GIT_FETCH_FLAGS variable"
             },
+            "gitCredentialsSecret": {
+              "$ref": "https://kubernetesjsonschema.dev/master/_definitions.json#/definitions/io.k8s.api.core.v1.SecretVolumeSource"
+            },
             "envFrom": {
               "type": "array",
               "default": [],

cmd/controller/controller_test.go

@@ -42,6 +42,9 @@ func TestReadAndParseConfig(t *testing.T) {
 			}},
 		},
 		DefaultCheckoutParams: &config.CheckoutParams{
+			GitCredentialsSecret: &corev1.SecretVolumeSource{
+				SecretName: "my-git-credentials",
+			},
 			EnvFrom: []corev1.EnvFromSource{{
 				Prefix: "GITHUB_",
 				SecretRef: &corev1.SecretEnvSource{

examples/config.yaml

@@ -23,6 +23,8 @@ prohibit-kubernetes-plugin: true
 
 # Applies to the checkout container in all spawned pods
 default-checkout-params:
+  gitCredentialsSecret:
+    secretName: "my-git-credentials"
   envFrom:
     - prefix: GITHUB_
       secretRef:

internal/controller/config/config.go

@@ -118,10 +118,11 @@ func (sc *SidecarParams) ApplyTo(ctr *corev1.Container) {
 // CheckoutParams contains parameters that provide additional control over the
 // checkout container.
 type CheckoutParams struct {
-	Skip       *bool                  `json:"skip,omitempty"`
-	CloneFlags *string                `json:"cloneFlags,omitempty"`
-	FetchFlags *string                `json:"fetchFlags,omitempty"`
-	EnvFrom    []corev1.EnvFromSource `json:"envFrom,omitempty"`
+	Skip                 *bool                      `json:"skip,omitempty"`
+	CloneFlags           *string                    `json:"cloneFlags,omitempty"`
+	FetchFlags           *string                    `json:"fetchFlags,omitempty"`
+	GitCredentialsSecret *corev1.SecretVolumeSource `json:"gitCredentialsSecret,omitempty"`
+	EnvFrom              []corev1.EnvFromSource     `json:"envFrom,omitempty"`
 }
 
 func (co *CheckoutParams) ApplyTo(ctr *corev1.Container) {
@@ -142,3 +143,10 @@ func (co *CheckoutParams) ApplyTo(ctr *corev1.Container) {
 	}
 	ctr.EnvFrom = append(ctr.EnvFrom, co.EnvFrom...)
 }
+
+func (co *CheckoutParams) GitCredsSecret() *corev1.SecretVolumeSource {
+	if co == nil {
+		return nil
+	}
+	return co.GitCredentialsSecret
+}

internal/controller/scheduler/scheduler.go

@@ -611,6 +611,36 @@ func (w *worker) createCheckoutContainer(
 		}
 	}
 
+	// If configured, set up a volume mount of a secret containing a
+	// .git-credentials file. k8sPlugin (if allowed) supersedes the default.
+	gitCredsSecret := w.cfg.DefaultCheckoutParams.GitCredsSecret()
+	if k8sPlugin != nil {
+		gitCredsSecret = k8sPlugin.CheckoutParams.GitCredsSecret()
+	}
+	gitConfigCmd := "true"
+	if gitCredsSecret != nil {
+		podSpec.Volumes = append(podSpec.Volumes, corev1.Volume{
+			Name:         "git-credentials",
+			VolumeSource: corev1.VolumeSource{Secret: gitCredsSecret},
+		})
+
+		checkoutContainer.VolumeMounts = append(checkoutContainer.VolumeMounts, corev1.VolumeMount{
+			Name:      "git-credentials",
+			ReadOnly:  true,
+			MountPath: "/tmp/ro/.git-credentials",
+			SubPath:   ".git-credentials",
+		})
+
+		// Why copy the file instead of mounting it directly into place?
+		// K8s secret mounts are always read only, but the 'store' credential
+		// helper always tries to write back to the file.
+		// If we didn't do this, we'd get some alarming-looking log lines like:
+		// "fatal: unable to write credential store: Resource busy"
+		// (which is Git being a drama llama - it doesn't impact the checkout
+		// process in any meaningful way).
+		gitConfigCmd = "cp /tmp/ro/.git-credentials ~ && git config --global credential.helper store"
+	}
+
 	// Ensure that the checkout occurs as the user/group specified in the pod's security context.
 	// we will create a buildkite-agent user/group in the checkout container as needed and switch
 	// to it. The created user/group will have the uid/gid specified in the pod's security context.
@@ -620,16 +650,17 @@ func (w *worker) createCheckoutContainer(
 		checkoutContainer.SecurityContext = &corev1.SecurityContext{
 			RunAsUser:    ptr.To[int64](0),
 			RunAsGroup:   ptr.To[int64](0),
-			RunAsNonRoot: ptr.To[bool](false),
+			RunAsNonRoot: ptr.To(false),
 		}
 
 		checkoutContainer.Command = []string{"ash", "-c"}
 		checkoutContainer.Args = []string{fmt.Sprintf(`set -exufo pipefail
 addgroup -g %d buildkite-agent
 adduser -D -u %d -G buildkite-agent -h /workspace buildkite-agent
-su buildkite-agent -c "buildkite-agent-entrypoint bootstrap"`,
+su buildkite-agent -c "%s && buildkite-agent-entrypoint bootstrap"`,
 			podGroup,
 			podUser,
+			gitConfigCmd,
 		)}
 
 	case podUser != 0 && podGroup == 0:
@@ -643,18 +674,21 @@ su buildkite-agent -c "buildkite-agent-entrypoint bootstrap"`,
 		checkoutContainer.Command = []string{"ash", "-c"}
 		checkoutContainer.Args = []string{fmt.Sprintf(`set -exufo pipefail
 adduser -D -u %d -G root -h /workspace buildkite-agent
-su buildkite-agent -c "buildkite-agent-entrypoint bootstrap"`,
+su buildkite-agent -c "%s && buildkite-agent-entrypoint bootstrap"`,
 			podUser,
+			gitConfigCmd,
 		)}
 
 	// If the group is not root, but the user is root, I don't think we NEED to do anything. It's fine
 	// for the user and group to be root for the checked out repo, even though the Pod's security
 	// context has a non-root group.
 	default:
 		checkoutContainer.SecurityContext = nil
-		// these are the default, but that default is sepciifed in the agent repo, so lets make it explicit
-		checkoutContainer.Command = []string{"buildkite-agent-entrypoint"}
-		checkoutContainer.Args = []string{"bootstrap"}
+		checkoutContainer.Command = []string{"ash", "-c"}
+		checkoutContainer.Args = []string{fmt.Sprintf(`set -exufo pipefail
+%s
+buildkite-agent-entrypoint bootstrap`,
+			gitConfigCmd)}
 	}
 
 	return checkoutContainer