From 44a88b3ad232b8ea4c0c187e098fdc4ef0e8fde7 Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Sun, 26 Nov 2023 10:30:16 +0000 Subject: [PATCH] Move artifact events to their own file This commit contains no functional change to the spec. It moves artifact events to their own file (similar to what we did for testing events), in preparation for further artifact events being added. Cleaned up some wrong references, left over when moving test events, added both testing and artifact events to spec.md too. Partially-fixes: #143 Signed-off-by: Andrea Frittoli --- artifacts.md | 80 +++++++++++++++++++++++++++++++++++++++ continuous-integration.md | 66 ++++---------------------------- spec.md | 10 ++++- 3 files changed, 95 insertions(+), 61 deletions(-) create mode 100644 artifacts.md diff --git a/artifacts.md b/artifacts.md new file mode 100644 index 00000000..9c3ced41 --- /dev/null +++ b/artifacts.md @@ -0,0 +1,80 @@ + +# Artifact Events + +Artifact events include the subject and predicates related software artifacts, and are usually produced by build systems and artifact registries. + +## 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. + +| Subject | Description | Predicates | +|---------|-------------|------------| +| [`artifact`](#artifact) | An artifact produced by a build | [`packaged`](#artifact-packaged), [`published`](#artifact-published), [`signed`](#artifact-signed)| + +### `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` | + +## 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. + +- 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 published`](examples/artifact_published.json) + +The event represents an artifact that has been published and it can be advertised for others to use. + +- Event Type: __`dev.cdevents.artifact.published.0.1.1`__ +- 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` | | + +### [`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. + +- 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` | ✅ | diff --git a/continuous-integration.md b/continuous-integration.md index 34daf71c..5882f138 100644 --- a/continuous-integration.md +++ b/continuous-integration.md @@ -10,18 +10,23 @@ 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, producing [artifacts](./artifacts.md) and [running tests](./testing-events.md). ## Subjects +<<<<<<< HEAD This specification defines two subjects in this stage: `build` and `artifact`. 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: `builds`. More subjects, [`artifacts`](./artifacts.md) and [`tests`](./testing-events.md) are defined in dedicated stages. 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. +>>>>>>> 89a0cb4 (Move artifact events to their own file) | 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)| + > `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` @@ -36,18 +41,6 @@ __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` | - ## Events ### [`build queued`](examples/build_queued.json) @@ -92,48 +85,3 @@ 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. - -- 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 published`](examples/artifact_published.json) - -The event represents an artifact that has been published and it can be advertised for others to use. - -- Event Type: __`dev.cdevents.artifact.published.0.1.1`__ -- 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` | | - -### [`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. - -- 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` | ✅ | diff --git a/spec.md b/spec.md index 0c748c4e..c7674a15 100644 --- a/spec.md +++ b/spec.md @@ -492,8 +492,14 @@ 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. +- __[Testing](testing.md)__: + includes events related to testings. Sometimes part of continuous + integration, testing may take place in different stages of the workflow. +- __[Artifacts](artifscts.md)__: + includes events related to packaging, releasing and managing software + artifacts. Often part of continuous integration, artifact activities 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