From 076758aec7aca0ed4864ce93b235bfd0ed879554 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Mon, 15 Mar 2021 15:08:06 +0000 Subject: [PATCH 1/2] Explain how the push field works Signed-off-by: Michael Bridgen --- docs/spec/v1alpha1/imageupdateautomations.md | 36 +++++++++++++++++--- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/spec/v1alpha1/imageupdateautomations.md b/docs/spec/v1alpha1/imageupdateautomations.md index 02c23f49..0f5c5b57 100644 --- a/docs/spec/v1alpha1/imageupdateautomations.md +++ b/docs/spec/v1alpha1/imageupdateautomations.md @@ -27,10 +27,16 @@ 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 @@ -38,7 +44,7 @@ type ImageUpdateAutomationSpec struct { } ``` -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. From 340d1a4462ffa49aa1ce307890d5805477dc9b18 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Mon, 15 Mar 2021 15:14:41 +0000 Subject: [PATCH 2/2] Give an example of {checkout,push}.branch As a YAML example, this also shows the YAML/JSON field names. Since field names are different in the Go types, it can be confusing. Signed-off-by: Michael Bridgen --- docs/spec/v1alpha1/imageupdateautomations.md | 26 ++++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/spec/v1alpha1/imageupdateautomations.md b/docs/spec/v1alpha1/imageupdateautomations.md index 0f5c5b57..ec35390e 100644 --- a/docs/spec/v1alpha1/imageupdateautomations.md +++ b/docs/spec/v1alpha1/imageupdateautomations.md @@ -277,12 +277,28 @@ type PushSpec struct { } ``` -If `push` is not present, commits are made on the same branch as `.checkout.branch` and pushed to -the same branch at the origin. +If `push` is not present, commits are made on the same branch as `.spec.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. +When `push` is present, the `.spec.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 +`.spec.checkout.branch`. If it does already exist, updates will be calculated on top of any commits +already on the branch. + +In the following snippet, updates will be pushed as commits to the branch `auto`, and when that +branch does not exist at the origin, it will be created locally starting from the branch `main` and +pushed: + +```yaml +spec: + # ... commit, update, etc. + checkout: + gitRepositoryRef: + name: app-repo + branch: main + push: + branch: auto +``` ## Status