Artifact pulled to downloaded

Renamed artifact pull do downloaded, drop artifact.md and other review feedback. Signed-off-by: Andrea Frittoli <[email protected]>
cdevents · Jan 12, 2024 · 2a61b77 · 2a61b77
1 parent 3390042
commit 2a61b77
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 125 deletions.
diff --git a/artifacts.md b/artifacts.md
diff --git a/continuous-integration.md b/continuous-integration.md
@@ -19,10 +19,9 @@ This specification defines two subjects in this stage: `build` and `artifact`. E
 | Subject | Description | Predicates |
 |---------|-------------|------------|
 | [`build`](#build) | A software build | [`queued`](#build-queued), [`started`](#build-started), [`finished`](#build-finished)|
-
+| [`artifact`](#artifact) | An artifact produced by a build | [`packaged`](#artifact-packaged), [`signed`](#artifact-signed), [`published`](#artifact-published), [`downloaded`](#artifact-downloaded)|
 
 > `testCase`/`testSuite` events have moved to their own top-level bucket [Testing Events](testing-events.md)
-> `artifact` events have moved to their own top-level bucket [Artifact Events](artifacts.md)
 
 ### `build`
 
@@ -37,6 +36,19 @@ __Note:__ The data model for `build`, apart from `id` and `source`, only include
 | type | `String` | See [type](spec.md#type-subject) | `build` |
 | artifactId | `String` | Identifier of the artifact produced by the build | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` |
 
+### `artifact`
+
+An `artifact` is usually produced as output of a build process. Events need to be generated to indicate that an `artifact` has been packaged and released for others to use. These events can be produced by the artifact producer or by the artifact storage system.
+
+| Field | Type | Description | Examples |
+|-------|------|-------------|----------|
+| id    | `String` | See [id](spec.md#id-subject)| `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | `staging/tekton`, `tekton-dev-123`|
+| type | `String` | See [type](spec.md#type-subject) | `artifact` |
+| change | `object`        | The change (tag, commit, revision) of the repository which was used to build the artifact" | `{"id": "527d4a1aca5e8d0df24813df5ad65d049fc8d312", "source": "my-git.example/an-org/a-repo"}`, `{"id": "feature1234", "source": "my-git.example/an-org/a-repo"}` |
+| signature | `string`     | The signature of the artifact | `MEYCIQCBT8U5ypDXWCjlNKfzTV4KH516/SK13NZSh8znnSMNkQIhAJ3XiQlc9PM1KyjITcZXHotdMB+J3NGua5T/yshmiPmp` |
+| user      | `string`     | The user who performed the predicate on the artifact registry. [^user] | `mybot-myapp` |
+
 ## Events
 
 ### [`build queued`](examples/build_queued.json)
@@ -81,3 +93,86 @@ This event represents a Build task that has finished. This event will eventually
 | source | `URI-Reference` | See [source](spec.md#source-subject) | | |
 | type | `String` | See [type](spec.md#type-subject) | |
 | artifactId | `Purl` | Identifier of the artifact produced by the build | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | `build` | |
+
+### [`artifact packaged`](examples/artifact_packaged.json)
+
+The event represents an artifact that has been packaged for distribution; this artifact is now versioned with a fixed version.
+The `artifact packaged` event is typically produced by the CI or build system.
+
+- Event Type: __`dev.cdevents.artifact.packaged.0.1.1`__
+- Predicate: packaged
+- Subject: [`artifact`](#artifact)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| change | `object`        | The change (tag, commit, revision) of the repository which was used to build the artifact" | `{"id": "527d4a1aca5e8d0df24813df5ad65d049fc8d312", "source": "my-git.example/an-org/a-repo"}`, `{"id": "feature1234", "source": "my-git.example/an-org/a-repo"}` | ✅ |
+
+### [`artifact signed`](examples/artifact_signed.json)
+
+The event represents an artifact that has been signed. The signature is included in the events itself.
+An artifact may be signed after it has been packaged or sometimes after it has published, depending on the tooling being used and the type of artifact. The `artifact signed` event is typically produced by the CI or build system.
+
+- Event Type: __`dev.cdevents.artifact.signed.0.1.0`__
+- Predicate: signed
+- Subject: [`artifact`](#artifact)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427?repository_url=mycr.io/myapp`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| signature | `string`     | The signature of the artifact | `MEYCIQCBT8U5ypDXWCjlNKfzTV4KH516/SK13NZSh8znnSMNkQIhAJ3XiQlc9PM1KyjITcZXHotdMB+J3NGua5T/yshmiPmp` | ✅ |
+
+
+### [`artifact published`](examples/artifact_published.json)
+
+The event represents an artifact that has been published and it can be advertised for others to use.
+The `artifact signed` event is typically produced by the artifact registry, but it may also be produced by the build system.
+
+- Event Type: __`dev.cdevents.artifact.published.0.2.0-draft`__
+- Predicate: published
+- Subject: [`artifact`](#artifact)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427?repository_url=mycr.io/myapp`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| user | `String` | The user who published to the artifact registry. [^user] | `mybot-myapp` | |
+
+### [`artifact downloaded`](examples/artifact_downloaded.json)
+
+The event represents an artifact that has been published and it can be advertised for others to use.
+The `artifact signed` event is typically produced by the artifact registry, but it may also be produced by the build system.
+
+- Event Type: __`dev.cdevents.artifact.downloaded.0.1.0-draft`__
+- Predicate: downloaded
+- Subject: [`artifact`](#artifact)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427?repository_url=mycr.io/myapp`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| user | `String` | The user who downloaded from the artifact registry. [^user] | `mybot-myapp` | |
+
+### [`artifact deleted`](examples/artifact_deleted.json)
+
+The event represents an artifact that has been deleted from an artifact registry.
+The `artifact deleted` event is typically produced by the artifact registry, but it may also be produced by the build system.
+
+- Event Type: __`dev.cdevents.artifact.deleted.0.1.0-draft`__
+- Predicate: deleted
+- Subject: [`artifact`](#artifact)
+
+| Field | Type | Description | Examples | Required |
+|-------|------|-------------|----------|----------------------------|
+| id    | `Purl` | See [id](spec.md#id-subject) | `pkg:oci/myapp@sha256%3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427?repository_url=mycr.io/myapp`, `pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c` | ✅ |
+| source | `URI-Reference` | See [source](spec.md#source-subject) | | |
+| type | `String` | See [type](spec.md#type-subject) | `artifact` | |
+| user | `String` | The user who deleted from the artifact registry. [^user] | `mybot-myapp` | |
+
+[^user]: The actual format of `user` depends on the specific registry and authentication method used. If access to the artifact registry is obtained through a long lived token, this could be the name or description associated with the token at provisioning time. In case of an anonymous read operations, the user depends on the protocol used, a typically useful value would be the IP address of the client performing the read.
diff --git a/examples/artifact_pulled.json → examples/artifact_downloaded.json b/examples/artifact_pulled.json → examples/artifact_downloaded.json
@@ -3,7 +3,7 @@
     "version": "0.4.0-draft",
     "id": "271069a8-fc18-44f1-b38f-9d70a1695819",
     "source": "/event/source/123",
-    "type": "dev.cdevents.artifact.pulled.0.1.0-draft",
+    "type": "dev.cdevents.artifact.downloaded.0.1.0-draft",
     "timestamp": "2023-03-20T14:27:05.315384Z"
   },
   "subject": {

diff --git a/schemas/artifactpulled.json → schemas/artifactdownloaded.json b/schemas/artifactpulled.json → schemas/artifactdownloaded.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdevents.dev/0.4.0-draft/schema/artifact-pulled-event",
+  "$id": "https://cdevents.dev/0.4.0-draft/schema/artifact-downloaded-event",
   "properties": {
     "context": {
       "properties": {
@@ -20,9 +20,9 @@
         "type": {
           "type": "string",
           "enum": [
-            "dev.cdevents.artifact.pulled.0.1.0-draft"
+            "dev.cdevents.artifact.downloaded.0.1.0-draft"
           ],
-          "default": "dev.cdevents.artifact.pulled.0.1.0-draft"
+          "default": "dev.cdevents.artifact.downloaded.0.1.0-draft"
         },
         "timestamp": {
           "type": "string",