gitrepo: add docs for tag verification

Signed-off-by: Sanskar Jaiswal <[email protected]>
fluxcd · Aug 14, 2023 · c88b0bf · c88b0bf
1 parent a332d92
commit c88b0bf
Showing 1 changed file with 25 additions and 4 deletions.
diff --git a/docs/spec/v1/gitrepositories.md b/docs/spec/v1/gitrepositories.md
@@ -366,8 +366,17 @@ spec:
 `.spec.verify` is an optional field to enable the verification of Git commit
 signatures. The field offers two subfields:
 
-- `.mode`, to specify what Git commit object should be verified. Only supports
-  `head` at present.
+- `.mode`, to specify what Git object(s) should be verified. Supported
+  values are:
+  - `HEAD`: Verifies the commit object pointed to by the HEAD of the repository
+     after performing a checkout via `.spec.ref`.
+  - `head`: Same as `HEAD`, supported for backwards compatibility purposes.
+  - `Tag`: Verifies the tag object pointed to by the specified/inferred tag
+     reference in `.spec.ref.tag`, `.spec.ref.semver` or `.spec.ref.name`.
+  - `TagAndHEAD`: Verifies the tag object pointed to by the specified/inferred tag
+     reference in `.spec.ref.tag`, `.spec.ref.semver` or `.spec.ref.name` and
+     the commit object pointed to by the tag.
+
 - `.secretRef.name`, to specify a reference to a Secret in the same namespace as
   the GitRepository. Containing the (PGP) public keys of trusted Git authors.
 
@@ -384,7 +393,7 @@ spec:
   ref:
     branch: master
   verify:
-    mode: head
+    mode: HEAD
     secretRef:
       name: pgp-public-keys
 ```
@@ -394,7 +403,7 @@ following attributes to the GitRepository's `.status.conditions`:
 
 - `type: SourceVerifiedCondition`
 - `status: "True"`
-- `reason: Succeeded`
+- `reason: VerifiedCommit | VerifiedTag | VerifiedTagAndCommit`
 
 #### Verification Secret example
 
@@ -978,6 +987,18 @@ status:
   ...
 ```
 
+### Observed Verification Mode
+
+The source-controller reports the observed verification mode in the
+GitRepository's `.status.observedVerificationMode`.  The observed verification
+mode is the latest `.spec.observedVerificationMode` value which resulted in a
+[ready state](#ready-gitrepository), or stalled due to error it can not recover
+from without human intervention. The value is the same as the
+[verification mode in spec](#verification). It indicates the verification
+configuration used in verifying Git objects.
+It is also used by the controller to determine if an artifact needs to be
+rebuilt.
+
 ### Observed Generation
 
 The source-controller reports an [observed generation][typical-status-properties]