Explain how the push field works

Signed-off-by: Michael Bridgen <[email protected]>

Author: squaremo

docs/spec/v1alpha1/imageupdateautomations.md

@@ -27,18 +27,24 @@ type ImageUpdateAutomationSpec struct {
 	// value.
 	// +kubebuilder:default={"strategy":"Setters"}
 	Update *UpdateStrategy `json:"update,omitempty"`
-	// Commit specifies how to commit to the git repo
+	// Commit specifies how to commit to the git repository.
 	// +required
 	Commit CommitSpec `json:"commit"`
 
+	// Push specifies how and where to push commits made by the
+	// automation. If missing, commits are pushed (back) to
+	// `.spec.checkout.branch`.
+	// +optional
+	Push *PushSpec `json:"push,omitempty"`
+
 	// Suspend tells the controller to not run this automation, until
 	// it is unset (or set to false). Defaults to false.
 	// +optional
 	Suspend bool `json:"suspend,omitempty"`
 }
 ```
 
-See the sections below, regarding `checkout`, `update`, and `commit`.
+See the sections below regarding `checkout`, `update`, `commit`, and `push`.
 
 The required `interval` field gives a period for automation runs, in [duration notation][durations];
 e.g., `"5m"`.
@@ -67,8 +73,8 @@ with write access; e.g., if using a GitHub deploy key, "Allow write access" shou
 creating it. Only the `url`, `secretRef` and `gitImplementation` (see just below) fields of the
 `GitRepository` are used.
 
-The `branch` field names the branch in the git repository to check out; this will also be the branch
-the controller pushes commits to.
+The `branch` field names the branch in the git repository to check out. When the `push` field is not
+present (see [below](#push)), this will also be the branch pushed back to the origin repository.
 
 **Git implementation**
 
@@ -256,6 +262,28 @@ spec:
       {{ end -}}
 ```
 
+## Push
+
+The optional `push` field defines how commits are pushed to the origin.
+
+```go
+// PushSpec specifies how and where to push commits.
+type PushSpec struct {
+	// Branch specifies that commits should be pushed to the branch
+	// named. The branch is created using `.spec.checkout.branch` as the
+	// starting point, if it doesn't already exist.
+	// +required
+	Branch string `json:"branch"`
+}
+```
+
+If `push` is not present, commits are made on the same branch as `.checkout.branch` and pushed to
+the same branch at the origin.
+
+When `push` is present, the `push.branch` field specifies a branch to push to at the origin. The
+branch will be created locally if it does not already exist, starting from `.checkout.branch`. If it
+does already exist, updates will be calculated on top of any commits already on the branch.
+
 ## Status
 
 The status of an `ImageUpdateAutomation` object records the result of the last automation run.