Skip to content

Commit

Permalink
Add artifact pulled and artifact deleted events
Browse files Browse the repository at this point in the history
Signed-off-by: Andrea Frittoli <[email protected]>
  • Loading branch information
afrittoli committed Nov 27, 2023
1 parent 89a0cb4 commit 6981691
Show file tree
Hide file tree
Showing 7 changed files with 294 additions and 14 deletions.
55 changes: 46 additions & 9 deletions artifacts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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
Expand All @@ -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)

Expand All @@ -62,19 +82,36 @@ 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 |
|-------|------|-------------|----------|----------------------------|
| 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` | |
17 changes: 17 additions & 0 deletions examples/artifact_deleted.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
6 changes: 4 additions & 2 deletions examples/artifact_published.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
}
17 changes: 17 additions & 0 deletions examples/artifact_pulled.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
101 changes: 101 additions & 0 deletions schemas/artifactdeleted.json
Original file line number Diff line number Diff line change
@@ -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"
]
}
11 changes: 8 additions & 3 deletions schemas/artifactpublished.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -59,7 +59,12 @@
"default": "artifact"
},
"content": {
"properties": {},
"properties": {
"user": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"type": "object"
}
Expand Down
101 changes: 101 additions & 0 deletions schemas/artifactpulled.json
Original file line number Diff line number Diff line change
@@ -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"
]
}

0 comments on commit 6981691

Please sign in to comment.