# CI/CD LLMS index: [llms.txt](/llms.txt) --- - [Continuous Integration and Continuous Deployment (CI/CD)](#continuous-integration-and-continuous-deployment-cicd) - [CI/CD pipeline](#cicd-pipeline) - [CI/CD pipeline run](#cicd-pipeline-run) - [CI/CD worker](#cicd-worker) - [Version Control System (VCS)](#version-control-system-vcs) - [VCS repository](#vcs-repository) - [VCS reference](#vcs-reference) See also: - The [Trace semantic conventions for CI/CD](/docs/specs/semconv/cicd/cicd-spans.md) ## Continuous Integration and Continuous Deployment (CI/CD) ### CI/CD pipeline **Status:** ![Development](https://img.shields.io/badge/-development-blue) **type:** `cicd.pipeline` **Description:** A pipeline is a series of automated steps that helps software teams deliver code. > [!warning] > This entity definition contains attributes without a role. > Stable Entities MUST NOT have attributes without a defined role. **Attributes:** | Role | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | | Other | [`cicd.pipeline.name`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | ### CI/CD pipeline run To efficiently set the following attributes for all spans of a pipeline run they should be defined as the following resource. Since this resource is unique for each pipeline run, this means instantiating separate [TracerProviders](/docs/specs/otel/trace/api/#tracerprovider) for each pipeline run in order to be able to configure the resources of any spans emitted through that tracer. Using the CI/CD pipeline run resource with metrics inherently causes high cardinality and may increase costs with some metric storage backends. Thus, using CI/CD pipeline run resource for metrics MUST be opt-in. **Status:** ![Development](https://img.shields.io/badge/-development-blue) **type:** `cicd.pipeline.run` **Description:** A pipeline run is a singular execution of a given pipeline's tasks. > [!warning] > This entity definition contains attributes without a role. > Stable Entities MUST NOT have attributes without a defined role. **Attributes:** | Role | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | | Other | [`cicd.pipeline.run.id`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The unique identifier of a pipeline run within a CI/CD system. | `120912` | | Other | [`cicd.pipeline.run.url.full`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The [URL](https://wikipedia.org/wiki/URL) of the pipeline run, providing the complete address in order to locate and identify the pipeline run. | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763?pr=1075` | ### CI/CD worker **Status:** ![Development](https://img.shields.io/badge/-development-blue) **type:** `cicd.worker` **Description:** A CI/CD worker is a component of the CI/CD system that performs work (eg. running pipeline tasks or performing sync). A single pipeline run may be distributed across multiple workers. Any OpenTelemetry signal associated with a worker should be associated to the worker that performed the corresponding work. For example, when a pipeline run involves several workers, its task run spans may reference the different `cicd.worker` resources corresponding to the workers that executed each task run. The pipeline run's parent span may instead reference the CI/CD controller as the `cicd.worker` resource. > [!warning] > This entity definition contains attributes without a role. > Stable Entities MUST NOT have attributes without a defined role. **Attributes:** | Role | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | | Other | [`cicd.worker.id`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The unique identifier of a worker within a CI/CD system. | `abc123`; `10.0.1.2`; `controller` | | Other | [`cicd.worker.name`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of a worker within a CI/CD system. | `agent-abc`; `controller`; `Ubuntu LTS` | | Other | [`cicd.worker.url.full`](/docs/specs/semconv/registry/attributes/cicd.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` If available | string | The [URL](https://wikipedia.org/wiki/URL) of the worker, providing the complete address in order to locate and identify the worker. | `https://cicd.example.org/worker/abc123` | ## Version Control System (VCS) ### VCS repository **Status:** ![Development](https://img.shields.io/badge/-development-blue) **type:** `vcs.repo` **Description:** A repository in the Version Control System. > [!warning] > This entity definition contains attributes without a role. > Stable Entities MUST NOT have attributes without a defined role. **Attributes:** | Role | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | | Other | [`vcs.repository.name`](/docs/specs/semconv/registry/attributes/vcs.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [1] | `semantic-conventions`; `my-cool-repo` | | Other | [`vcs.repository.url.full`](/docs/specs/semconv/registry/attributes/vcs.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | **[1] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends. **[2] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include the `.git` extension. ### VCS reference **Status:** ![Development](https://img.shields.io/badge/-development-blue) **type:** `vcs.ref` **Description:** A reference to a specific version in the Version Control System. > [!warning] > This entity definition contains attributes without a role. > Stable Entities MUST NOT have attributes without a defined role. **Attributes:** | Role | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | --- | | Other | [`vcs.ref.head.name`](/docs/specs/semconv/registry/attributes/vcs.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | | Other | [`vcs.ref.head.revision`](/docs/specs/semconv/registry/attributes/vcs.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | | Other | [`vcs.ref.type`](/docs/specs/semconv/registry/attributes/vcs.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | **[1] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a given time. **[2] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a given time.The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a commit [commit](https://git-scm.com/docs/git-commit) object. It does not necessarily have to be a hash; it can simply define a [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where it is identical to the `ref.head.name`, it SHOULD still be included. It is up to the implementer to decide which value to set as the revision based on the VCS system and situational context. --- `vcs.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Development](https://img.shields.io/badge/-development-blue) | | `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Development](https://img.shields.io/badge/-development-blue) |