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