From bb617660d22ae0cdfc9ee0f7102a3966cc013ea8 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Sun, 26 Nov 2023 10:30:16 +0000 Subject: [PATCH] Add artifact downloaded and deleted events Cleaned up some wrong references, left over when moving test events, added testing events to spec.md too. Partially-fixes: #143 Signed-off-by: Andrea Frittoli --- .spellcheck-en-custom.txt | 5 ++ continuous-integration.md | 56 +++++++++++++---- examples/artifact_deleted.json | 17 +++++ examples/artifact_downloaded.json | 17 +++++ examples/artifact_published.json | 3 +- schemas/artifactdeleted.json | 101 ++++++++++++++++++++++++++++++ schemas/artifactdownloaded.json | 101 ++++++++++++++++++++++++++++++ schemas/artifactpublished.json | 4 ++ spec.md | 6 +- 9 files changed, 296 insertions(+), 14 deletions(-) create mode 100644 examples/artifact_deleted.json create mode 100644 examples/artifact_downloaded.json create mode 100644 schemas/artifactdeleted.json create mode 100644 schemas/artifactdownloaded.json diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index cca0d6ca..d340a061 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -13,6 +13,8 @@ NGua NIST Notational README +SBOM +SBOMs SCM SIG SRE @@ -54,6 +56,8 @@ lifecycle markdownlint md modelled +myapp +mybot mydata myvalue namespace @@ -70,6 +74,7 @@ quicktime rfc rolledback runtime +sbom somewherelse specversion src diff --git a/continuous-integration.md b/continuous-integration.md index 59f43841..730ae418 100644 --- a/continuous-integration.md +++ b/continuous-integration.md @@ -10,7 +10,7 @@ description: > --> # Continuous Integration Events -Continuous Integration (CI) events include the subject and predicates related to CI activities such as building software, producing artifacts and running tests. +Continuous Integration (CI) events include the subject and predicates related to CI activities such as [building software](#build), producing [artifacts](#artifact) and [running tests](./testing-events.md). ## Subjects @@ -19,7 +19,7 @@ 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), [`published`](#artifact-published), [`signed`](#artifact-signed)| +| [`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) @@ -48,6 +48,7 @@ An `artifact` is usually produced as output of a build process. Events need to b | 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` | | sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` | +| user | `string` | The user who performed the predicate on the artifact registry. [^user] | `mybot-myapp` | ## Events @@ -111,11 +112,26 @@ This event is usually produced by the build system. If an SBOM URI is available | 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"}` | ✅ | | sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` | | +### [`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. -This event may be produced both by the build system and by the artifact registry that received the artifact. -If an SBOM was published and the SBOM URI is available at this stage, it should be included. +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 @@ -126,15 +142,15 @@ If an SBOM was published and the SBOM URI is available at this stage, it should | 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` | | -| sbom | [`sbom`](#sbom) | The Software Bill of Material (SBOM) associated with the artifact | `{"uri": "https://sbom.storage.service/my-projects/3A0b31b1c02ff458ad9b7b81cbdf8f028bd54699fa151f221d1e8de6817db93427.sbom"}` | | +| user | `String` | The user who published to the artifact registry. [^user] | `mybot-myapp` | | -### [`artifact signed`](examples/artifact_signed.json) +### [`artifact downloaded`](examples/artifact_downloaded.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 event represents an artifact that has been downloaded from the registry. +The `artifact downloaded` event is typically produced by the artifact registry, but it may also be produced by the build system. -- Event Type: __`dev.cdevents.artifact.signed.0.1.0`__ -- Predicate: signed +- Event Type: __`dev.cdevents.artifact.downloaded.0.1.0-draft`__ +- Predicate: downloaded - Subject: [`artifact`](#artifact) | Field | Type | Description | Examples | Required | @@ -142,7 +158,25 @@ An artifact may be signed after it has been packaged or sometimes after it has p | 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` | ✅ | +| 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. ## Objects diff --git a/examples/artifact_deleted.json b/examples/artifact_deleted.json new file mode 100644 index 00000000..a4536829 --- /dev/null +++ b/examples/artifact_deleted.json @@ -0,0 +1,17 @@ +{ + "context": { + "version": "0.4.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "source": "/event/source/123", + "type": "dev.cdevents.artifact.deleted.0.1.0-draft", + "timestamp": "2023-03-20T14:27:05.315384Z" + }, + "subject": { + "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c", + "source": "/event/source/123", + "type": "artifact", + "content": { + "user": "mybot-myapp" + } + } +} diff --git a/examples/artifact_downloaded.json b/examples/artifact_downloaded.json new file mode 100644 index 00000000..94d0f718 --- /dev/null +++ b/examples/artifact_downloaded.json @@ -0,0 +1,17 @@ +{ + "context": { + "version": "0.4.0-draft", + "id": "271069a8-fc18-44f1-b38f-9d70a1695819", + "source": "/event/source/123", + "type": "dev.cdevents.artifact.downloaded.0.1.0-draft", + "timestamp": "2023-03-20T14:27:05.315384Z" + }, + "subject": { + "id": "pkg:golang/mygit.com/myorg/myapp@234fd47e07d1004f0aed9c", + "source": "/event/source/123", + "type": "artifact", + "content": { + "user": "mybot-myapp" + } + } +} diff --git a/examples/artifact_published.json b/examples/artifact_published.json index 854e2d96..462a623f 100644 --- a/examples/artifact_published.json +++ b/examples/artifact_published.json @@ -13,7 +13,8 @@ "content": { "sbom": { "uri": "https://sbom.repo/myorg/234fd47e07d1004f0aed9c.sbom" - } + }, + "user": "mybot-myapp" } } } diff --git a/schemas/artifactdeleted.json b/schemas/artifactdeleted.json new file mode 100644 index 00000000..926333bf --- /dev/null +++ b/schemas/artifactdeleted.json @@ -0,0 +1,101 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.4.0-draft/schema/artifact-deleted-event", + "properties": { + "context": { + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.artifact.deleted.0.1.0-draft" + ], + "default": "dev.cdevents.artifact.deleted.0.1.0-draft" + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "version", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "minLength": 1, + "enum": [ + "artifact" + ], + "default": "artifact" + }, + "content": { + "properties": { + "user": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "type", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} \ No newline at end of file diff --git a/schemas/artifactdownloaded.json b/schemas/artifactdownloaded.json new file mode 100644 index 00000000..b0d97a6f --- /dev/null +++ b/schemas/artifactdownloaded.json @@ -0,0 +1,101 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.4.0-draft/schema/artifact-downloaded-event", + "properties": { + "context": { + "properties": { + "version": { + "type": "string", + "minLength": 1 + }, + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "enum": [ + "dev.cdevents.artifact.downloaded.0.1.0-draft" + ], + "default": "dev.cdevents.artifact.downloaded.0.1.0-draft" + }, + "timestamp": { + "type": "string", + "format": "date-time" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "version", + "id", + "source", + "type", + "timestamp" + ] + }, + "subject": { + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "source": { + "type": "string", + "minLength": 1, + "format": "uri-reference" + }, + "type": { + "type": "string", + "minLength": 1, + "enum": [ + "artifact" + ], + "default": "artifact" + }, + "content": { + "properties": { + "user": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "id", + "type", + "content" + ] + }, + "customData": { + "oneOf": [ + { + "type": "object" + }, + { + "type": "string", + "contentEncoding": "base64" + } + ] + }, + "customDataContentType": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "context", + "subject" + ] +} \ No newline at end of file diff --git a/schemas/artifactpublished.json b/schemas/artifactpublished.json index ae839a66..c66081c0 100644 --- a/schemas/artifactpublished.json +++ b/schemas/artifactpublished.json @@ -73,6 +73,10 @@ "required": [ "uri" ] + }, + "user": { + "type": "string", + "minLength": 1 } }, "additionalProperties": false, diff --git a/spec.md b/spec.md index 61698d9d..d43abb2b 100644 --- a/spec.md +++ b/spec.md @@ -497,8 +497,10 @@ dedicated document in the spec: emitted by changes in source code or by the creation, modification or deletion of new repositories that hold source code. - __[Continuous Integration](continuous-integration.md)__: - includes events related to building, testings, packaging and releasing - software artifacts, usually binaries. + includes events related to building artifacts ad packaging, releasing and managing software artifacts. +- __[Testing](testing.md)__: + includes events related to testings. Sometimes part of continuous + integration, testing may take place in different stages of the workflow. - __[Continuous Deployment](continuous-deployment.md)__: include events related with environments where the artifacts produced by the integration pipelines actually run. These are usually services running in a