Skip to content

Commit

Permalink
Add artifact downloaded and deleted events
Browse files Browse the repository at this point in the history
Cleaned up some wrong references, left over when moving test events,
added testing events to spec.md too.

Partially-fixes: cdevents#143

Signed-off-by: Andrea Frittoli <[email protected]>
  • Loading branch information
afrittoli committed Jan 15, 2024
1 parent dac26c8 commit bb61766
Show file tree
Hide file tree
Showing 9 changed files with 296 additions and 14 deletions.
5 changes: 5 additions & 0 deletions .spellcheck-en-custom.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ NGua
NIST
Notational
README
SBOM
SBOMs
SCM
SIG
SRE
Expand Down Expand Up @@ -54,6 +56,8 @@ lifecycle
markdownlint
md
modelled
myapp
mybot
mydata
myvalue
namespace
Expand All @@ -70,6 +74,7 @@ quicktime
rfc
rolledback
runtime
sbom
somewherelse
specversion
src
Expand Down
56 changes: 45 additions & 11 deletions continuous-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

Expand Down Expand Up @@ -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
Expand All @@ -126,23 +142,41 @@ 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 |
|-------|------|-------------|----------|----------------------------|
| 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

Expand Down
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.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"
}
}
}
17 changes: 17 additions & 0 deletions examples/artifact_downloaded.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.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"
}
}
}
3 changes: 2 additions & 1 deletion examples/artifact_published.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
"content": {
"sbom": {
"uri": "https://sbom.repo/myorg/234fd47e07d1004f0aed9c.sbom"
}
},
"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"
]
}
101 changes: 101 additions & 0 deletions schemas/artifactdownloaded.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-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"
]
}
4 changes: 4 additions & 0 deletions schemas/artifactpublished.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@
"required": [
"uri"
]
},
"user": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
Expand Down
Loading

0 comments on commit bb61766

Please sign in to comment.