diff --git a/artifacts.md b/artifacts.md index 9c3ced41..649c99f6 100644 --- a/artifacts.md +++ b/artifacts.md @@ -14,11 +14,11 @@ Artifact events include the subject and predicates related software artifacts, a ## Subjects -This specification defines one subjects in this stage: `artifacts`. Events associated with these subjects are typically generated either by a CI system that orchestrates the process or by a specific build or test tool directly. Some artifact events may be generated by the system that stores the artifact as well. +This specification defines one subjects in this stage: `artifacts`. Events associated with these subjects are typically generated either by a CI system that orchestrates the process, by a specific build or test tool directly, or by the by the system that stores the artifact as well. | Subject | Description | Predicates | |---------|-------------|------------| -| [`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), [`pulled`](#artifact-pulled)| ### `artifact` @@ -31,12 +31,14 @@ An `artifact` is usually produced as output of a build process. Events need to b | 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. The actual format 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. | `mybot-myapp` | ## Events ### [`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 @@ -49,11 +51,29 @@ The event represents an artifact that has been packaged for distribution; this a | 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.1.1`__ +- Event Type: __`dev.cdevents.artifact.published.0.2.0-draft`__ - Predicate: published - Subject: [`artifact`](#artifact) @@ -62,14 +82,15 @@ The event represents an artifact that has been published and it can be advertise | 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. The actual format 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. | `mybot-myapp` | | -### [`artifact signed`](examples/artifact_signed.json) +### [`artifact pulled`](examples/artifact_pulled.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 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.signed.0.1.0`__ -- Predicate: signed +- Event Type: __`dev.cdevents.artifact.pulled.0.1.0-draft`__ +- Predicate: pulled - Subject: [`artifact`](#artifact) | Field | Type | Description | Examples | Required | @@ -77,4 +98,20 @@ 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 pulled from the artifact registry. The actual format 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 pull operation, the user depends on the protocol used, a typically useful value would be the IP address of the client performing the read. | `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. The actual format 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. | `mybot-myapp` | | \ No newline at end of file diff --git a/examples/artifact_deleted.json b/examples/artifact_deleted.json new file mode 100644 index 00000000..98e955b5 --- /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.pulled.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 43d94b74..97c43a02 100644 --- a/examples/artifact_published.json +++ b/examples/artifact_published.json @@ -3,13 +3,15 @@ "version": "0.4.0-draft", "id": "271069a8-fc18-44f1-b38f-9d70a1695819", "source": "/event/source/123", - "type": "dev.cdevents.artifact.published.0.1.1", + "type": "dev.cdevents.artifact.published.0.2.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": {} + "content": { + "user": "mybot-myapp" + } } } diff --git a/examples/artifact_pulled.json b/examples/artifact_pulled.json new file mode 100644 index 00000000..98e955b5 --- /dev/null +++ b/examples/artifact_pulled.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.pulled.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/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/artifactpublished.json b/schemas/artifactpublished.json index fc56f008..ee125649 100644 --- a/schemas/artifactpublished.json +++ b/schemas/artifactpublished.json @@ -20,9 +20,9 @@ "type": { "type": "string", "enum": [ - "dev.cdevents.artifact.published.0.1.1" + "dev.cdevents.artifact.published.0.2.0-draft" ], - "default": "dev.cdevents.artifact.published.0.1.1" + "default": "dev.cdevents.artifact.published.0.2.0-draft" }, "timestamp": { "type": "string", @@ -59,7 +59,12 @@ "default": "artifact" }, "content": { - "properties": {}, + "properties": { + "user": { + "type": "string", + "minLength": 1 + } + }, "additionalProperties": false, "type": "object" } diff --git a/schemas/artifactpulled.json b/schemas/artifactpulled.json new file mode 100644 index 00000000..edd95e57 --- /dev/null +++ b/schemas/artifactpulled.json @@ -0,0 +1,101 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdevents.dev/0.4.0-draft/schema/artifact-pulled-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.pulled.0.1.0-draft" + ], + "default": "dev.cdevents.artifact.pulled.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