Add the opencontainers annotations to API docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

Author: stefanprodan

controllers/ocirepository_controller.go

@@ -200,7 +200,7 @@ func (r *OCIRepositoryReconciler) Reconcile(ctx context.Context, req ctrl.Reques
 			summarize.WithReconcileError(retErr),
 			summarize.WithIgnoreNotFound(),
 			summarize.WithProcessors(
-				summarize.RecordContextualError,
+				summarize.ErrorActionHandler,
 				summarize.RecordReconcileReq,
 			),
 			summarize.WithResultBuilder(sreconcile.AlwaysRequeueResultBuilder{RequeueAfter: obj.GetRequeueAfter()}),
@@ -347,7 +347,7 @@ func (r *OCIRepositoryReconciler) reconcileSource(ctx context.Context, obj *sour
 	if err != nil {
 		if _, ok := err.(invalidOCIURLError); ok {
 			e := serror.NewStalling(
-				fmt.Errorf("failed to determine the artifact address for '%s': %w", obj.Spec.URL, err),
+				fmt.Errorf("URL validation failed for '%s': %w", obj.Spec.URL, err),
 				sourcev1.URLInvalidReason)
 			conditions.MarkTrue(obj, sourcev1.FetchFailedCondition, e.Reason, e.Err.Error())
 			return sreconcile.ResultEmpty, e

docs/spec/v1beta2/ocirepositories.md

@@ -484,23 +484,36 @@ specific OCIRepository, e.g.
 The OCIRepository reports the latest synchronized state from the OCI repository
 as an Artifact object in the `.status.artifact` of the resource.
 
+The `.status.artifact.revision` holds the SHA256 digest of the upstream OCI artifact.
+
+The `.status.artifact.metadata` holds the upstream OCI artifact metadata such as the
+[OpenContainers standard annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md).
+If the OCI artifact was created with `flux push artifact`, then the `metadata` will contain the following
+annotations:
+- `org.opencontainers.image.created` the date and time on which the artifact was built
+- `org.opencontainers.image.source` the URL of the Git repository containing the source files
+- `org.opencontainers.image.revision` the Git branch and commit SHA1 of the source files
+
 The Artifact file is a gzip compressed TAR archive (`<commit sha>.tar.gz`), and
 can be retrieved in-cluster from the `.status.artifact.url` HTTP address.
 
 #### Artifact example
 
 ```yaml
----
 apiVersion: source.toolkit.fluxcd.io/v1beta2
 kind: OCIRepository
 metadata:
   name: <repository-name>
 status:
   artifact:
-    checksum: e750c7a46724acaef8f8aa926259af30bbd9face2ae065ae8896ba5ee5ab832b
-    lastUpdateTime: "2022-06-29T06:59:23Z"
+    checksum: 9f3bc0f341d4ecf2bab460cc59320a2a9ea292f01d7b96e32740a9abfd341088
+    lastUpdateTime: "2022-08-08T09:35:45Z"
+    metadata:
+      org.opencontainers.image.created: "2022-08-08T12:31:41+03:00"
+      org.opencontainers.image.revision: 6.1.8/b3b00fe35424a45d373bf4c7214178bc36fd7872
+      org.opencontainers.image.source: https://github.com/stefanprodan/podinfo.git
     path: ocirepository/<namespace>/<repository-name>/<digest>.tar.gz
-    revision: master/363a6a8fe6a7f13e05d34c163b0ef02a777da20a
+    revision: <digest>
     url: http://source-controller.<namespace>.svc.cluster.local./ocirepository/<namespace>/<repository-name>/<digest>.tar.gz
 ```
 

go.mod

@@ -37,7 +37,7 @@ require (
 	github.com/fluxcd/pkg/gitutil v0.1.0
 	github.com/fluxcd/pkg/helmtestserver v0.7.4
 	github.com/fluxcd/pkg/lockedfile v0.1.0
-	github.com/fluxcd/pkg/oci v0.2.0
+	github.com/fluxcd/pkg/oci v0.3.0
 	github.com/fluxcd/pkg/runtime v0.16.2
 	github.com/fluxcd/pkg/ssh v0.5.0
 	github.com/fluxcd/pkg/testserver v0.2.0

go.sum

@@ -399,8 +399,8 @@ github.com/fluxcd/pkg/helmtestserver v0.7.4 h1:/Xj2+XLz7wr38MI3uPYvVAsZB9wQOq6rp
 github.com/fluxcd/pkg/helmtestserver v0.7.4/go.mod h1:aL5V4o8wUOMqeHMfjbVHS057E3ejzHMRVMqEbsK9FUQ=
 github.com/fluxcd/pkg/lockedfile v0.1.0 h1:YsYFAkd6wawMCcD74ikadAKXA4s2sukdxrn7w8RB5eo=
 github.com/fluxcd/pkg/lockedfile v0.1.0/go.mod h1:EJLan8t9MiOcgTs8+puDjbE6I/KAfHbdvIy9VUgIjm8=
-github.com/fluxcd/pkg/oci v0.2.0 h1:pvLF6iKmSj9u48Da7qlBDVIiH2NLOrbFUFE4Yr431Lc=
-github.com/fluxcd/pkg/oci v0.2.0/go.mod h1:c1pj9E/G5927gSa6ooACAyZe+HwjgmPk9johL7oXDHw=
+github.com/fluxcd/pkg/oci v0.3.0 h1:GFn6JZeg5fV2K4vsQ0s5lJFid6qrpA4RybLXL+7qUbQ=
+github.com/fluxcd/pkg/oci v0.3.0/go.mod h1:c1pj9E/G5927gSa6ooACAyZe+HwjgmPk9johL7oXDHw=
 github.com/fluxcd/pkg/runtime v0.16.2 h1:CexfMmJK+r12sHTvKWyAax0pcPomjd6VnaHXcxjUrRY=
 github.com/fluxcd/pkg/runtime v0.16.2/go.mod h1:OHSKsrO+T+Ym8WZRS2oidrnauWRARuE2nfm8ewevm7M=
 github.com/fluxcd/pkg/ssh v0.5.0 h1:jE9F2XvUXC2mgseeXMATvO014fLqdB30/VzlPLKsk20=