git: add docs for usage with Gerrit

Signed-off-by: Sanskar Jaiswal <[email protected]>

Author: aryan9600

docs/spec/v1beta1/imageupdateautomations.md

@@ -398,6 +398,7 @@ spec:
         name: fluxcdbot
 ```
 There are over 70 available functions. Some of them are defined by the [Go template language](https://pkg.go.dev/text/template) itself. Most of the others are part of the [Sprig template library](http://masterminds.github.io/sprig/). 
+
 ### Push
 
 The optional `push` field defines how commits are pushed to the origin.
@@ -463,21 +464,102 @@ spec:
       branch: auto
 ```
 
-In the following snippet, updates and commits will be made on the `auto` branch locally.
-The commits will be then pushed to the `auto` branch and then using the `refs/heads/auto:refs/heads/main`
-refspec:
+In the following snippet, updates and commits will be made on the `main` branch locally.
+The commits will be then pushed using the `refs/heads/main:refs/heads/auto` refspec:
 
 ```yaml
 spec:
   git:
     checkout:
       ref:
         branch: main
+    push:
+      refspec: refs/heads/main:refs/heads/auto
+```
+
+#### Gerrit
+
+
+[Gerrit](https://www.gerritcodereview.com/) operates differently from a
+standard Git server. Rather than sending individual commits to a branch,
+all changes are bundled into a single commit. This commit requires a distinct
+identifier separate from the commit SHA. Additionally, instead of initiating
+a Pull Request between branches, the commit is pushed using a refspec:
+`HEAD:refs/for/main`.
+
+As the image-automation-controller is primarily designed to work with
+standard Git servers, these special characteristics necessitate a few
+workarounds. The following is an example configuration that works
+well with Gerrit:
+
+```yaml
+spec:
+  git:
+    checkout:
+      ref:
+        branch: main
+    commit:
+      author:
+        email: flux@localdomain
+        name: flux
+      messageTemplate: |
+        Perform automatic image update
+
+        Automation name: {{ .AutomationObject }}
+
+        Files:
+        {{ range $filename, $_ := .Updated.Files -}}
+        - {{ $filename }}
+        {{ end }}
+        Objects:
+        {{ range $resource, $_ := .Updated.Objects -}}
+        - {{ $resource.Kind }} {{ $resource.Name }}
+        {{ end }}
+        Images:
+        {{ range .Updated.Images -}}
+        - {{ . }}
+        {{ end }}
+        {{- $ChangeId := .AutomationObject -}}
+        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Files | toString ) -}}
+        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Objects | toString ) -}}
+        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Images | toString ) }}
+        Change-Id: {{ printf "I%s" ( sha256sum $ChangeId | trunc 40 ) }}
     push:
       branch: auto
       refspec: refs/heads/auto:refs/heads/main
 ```
 
+This instructs the image-automation-controller to clone the repository using the
+`main` branch but execute its update logic and commit with the provided message
+template on the `auto` branch. Commits are then pushed to the `auto` branch,
+followed by pushing the `HEAD` of the `auto` branch to the `HEAD` of the remote
+`main` branch. The message template ensures the inclusion of a [Change-Id](https://gerrit-review.googlesource.com/Documentation/concept-changes.html#change-id)
+at the bottom of the commit message.
+
+The initial branch push aims to prevent multiple
+[Patch Sets](https://gerrit-review.googlesource.com/Documentation/concept-patch-sets.html).
+If we exclude `.push.branch` and only specify
+`.push.refspec: refs/heads/main:refs/heads/main`, the desired [Change](https://gerrit-review.googlesource.com/Documentation/concept-changes.html)
+can be created as intended. However, when the controller freshly clones the
+`main` branch while a Change is open, it executes its update logic on `main`,
+leading to new commits being pushed with the same changes to the existing open
+Change. Specifying `.push.branch` circumvents this by instructing the controller
+to apply the update logic to the `auto` branch, already containing the desired
+commit. This approach is also recommended in the
+[Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html#create-change).
+
+Another thing to note is the syntax of `.push.refspec`. Instead of it being
+`HEAD:refs/for/main`, commonly used by Gerrit users, we specify the full
+refname `refs/heads/auto` in the source part of the refpsec.
+
+**Note:** A known limitation of using the image-automation-controller with
+Gerrit involves handling multiple concurrent Changes. This is due to the
+calculation of the Change-Id, relying on factors like file names and image
+tags. If the controller introduces a new file or modifies a previously updated
+image tag to a different one, it leads to a distinct Change-Id for the commit.
+Consequently, this action will trigger the creation of an additional Change,
+even when an existing Change containing outdated modifications remains open.
+
 ## Update strategy
 
 The `.spec.update` field specifies how to carry out updates on the git repository. There is one