Pipeline Terminology

Introduction

The purpose of this document is to collect the names and types of common pipeline stages and steps.

If you are looking for the terminology used by various CI/CD tools, please consult the tools terminology document which is located next to this document.

Pipeline Terminology

Pipeline Stages

The list below is an attempt to create a mapping of common names for Stages, where a Stage is defined here as the unit of work one degree smaller than a Pipeline. (The effort of proposing a common vocabulary across CI/CD Tools and Technologies is not yet performed, but we’ll use the most common term from the table above as the working term.)

While CI/CD Tools and Technologies generally give developers broad leeway in naming and implementing their Stages, agreeing upon some common terms will help develop more pluggable Pipelines.

The concepts below can be re-ordered in Pipeline implementations. For example, it is often the case that software linting (logically a test) is done prior to the Build Stage. Also, deployment to a staging environment is often done prior to the Release Stage, while the deployment for production often happens after the Release Stage.

In Pipeline implementations, there may also be other Stages preceding or following the ones listed below.

In the lists and table below, Software Artifacts includes: Documentation Source Files, Source Code, Baseline/Composition/Dependency Information, Infrastructure as Code.

“Software Source” refers to human-readable source files that are inputs to the pipeline, such as: Source Code, Configuration Files, Documentation Source Files, Declared Dependencies, Baseline/Composition Information (i.e. lock files in source control)

“Binary Source” refers to executables that are inputs to the pipeline, such as: Executable Software Dependencies, Container Images, Virtual Machine Images

“Generated Software” refers to human-readable files that are outputs of the pipeline, such as: Compiled Software, Generated Configuration Files, Compiled Documentation, Baseline/Composition Information generated by the pipeline.

“Generated Binaries” refers to executables that are outputs of the pipeline, such as: Executable Software, Container Images, Virtual Machine Images

Any Stage

• Semantics: Some inputs and outputs are used across any and all stages. They’re listed here once, rather than repeating them for each stage.
• Aliases: N/A
• Inputs: Secrets, Pipeline Environment, Pipeline Workspace, Pipeline Utility Tools
• Outputs: Stage Results and Return Codes, Logs

Build Stage

• Semantics: Download, retrieve, assemble, and/or compile software into an executable and testable format. Download, retrieve, assemble, and/or compile documentation into a consumable format.
• Aliases: Compile
• Inputs: Software Source, Binary Source
• Outputs: Generated Software, Generated Binaries
• Other Results and Side Effects: The Build stage may also capture and store point-in-time details about the pipeline environment and tools (compiler versions, package manager versions, task container versions in tekton, OS versions etc.). While the pipeline configuration should ideally be in source code, in reality some settings will likely depend on external factors. Storing this information in an immutable data store facilitates debugging, rebuilds, pipeline verification, audit records, and forensics.

Test Stage

• Semantics: Test, scan, verify, and lint software and documentation.
• Aliases: Verify
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries
• Outputs: Test/Lint/Scan Records, Test/Lint/Scan Reports, Test/Lint/Scan Coverage Reports
• Other Results and Side Effects: N/A

Release Stage

• Semantics: Package, version, sign, and publish software artifacts and documentation.
• Aliases: Deliver, Publish
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Release Approvals
• Outputs: Release Records, Release Reports, Generated Software, Generated Binaries
• Other Results and Side Effects: Documentation and Software: packaged, signed, and published to a repository.

Deploy Stage

• Semantics: Deploy software artificats and documentation to any environment other than the pipeline environment. Verify successful deployment.
• Aliases: Install
• Inputs: Deployment Configuration, Software Source, Binary Source, Generated Software, Generated Binaries, Deployment KPIs
• Outputs: Deployment Records, Deployment Reports, Secrets to access deployed resources
• Other Results and Side Effects: Documentation hosted in a review, staging or production environment. Software running in a review, staging or production environment. Deployment KPIs might influence how the deployment proceeds; for example, for Canary or Blue/Green deployments.

Operations Stage

• Semantics: monitoring of deployed assets
• Aliases: Steady state, Production, Production Management
• Inputs: Deployment and Monitoring Configuration, Artifact Versions, Operational Metrics, Vulnerability and Security Updates
• Outputs: Operational Metrics, Alerts, Bug Reports, Logs
• Other Results and Side Effects: Automated Rollbacks, Vulnerability Mitigation via Rebuild / Redeploy, Human Interventions

Inputs and Outputs for Pipeline Stages

Pipeline Step Types

The table below is an attempt to create a mapping of common names for the various types of Pipeline Steps (the unit of work two degrees smaller than a Pipeline). (The effort of proposing a common vocabulary across CI/CD Tools and Technologies is not yet performed, but we’ll use the most common term from the table above as the working term.)

While CI/CD tools and technologies generally give developers broad leeway in naming and implementing their Pipeline Steps, agreeing upon some common terms will help develop more pluggable pipelines. This list is not meant to be exhaustive.

Each type of Pipeline Step will generally have several implementations that are tool specific. For example, Source will have implementations for various Source Code Management (SCM) tools. Publish will have implementations for each type of repository, and so on.

Any Step

• Semantics: Some inputs and outputs are used across any and all steps. They’re listed here once, rather than repeating them for each step.
• Aliases: N/A
• Inputs: Secrets, Pipeline Environment, Pipeline Workspace, Parameters for the Step
• Outputs: Return Codes, Results, Records and Reports, Logs
• Other Results and Side Effects: N/A

Setup

• Semantics: Provision pipeline resources, set up the pipeline workspace. It’s possible to have one Setup step at the beginning of each pipeline run, and additional Setup steps as the pipeline progresses.
• Aliases: Initialize, Start, Prepare, Workspace, Orchestrate
• Inputs: Pipeline Request Parameters, Pipeline Container Image Name and Version
• Outputs: Secrets, Pipeline Environment, Pipeline Workspace
• Other Results and Side Effects: May set up persistent storage or another method for pipeline steps to share inputs and outputs with each other.

Source

• Semantics: Download, retrieve or copy software, images, and documentation into the pipeline workspace. Fetch configuration data.
• Aliases: Clone, Fetch
• Inputs: Source Code Reference (Repository, Branch, Commit)
• Outputs: Software Source, Binary Source
• Other Results and Side Effects: N/A

Secret Detection

• Semantics: Detect secrets in the source code, other software, or documentation. Examples include passwords, SSH keys, API keys, and so on.
• Aliases: N/A
• Inputs: Source Code Reference (Repository, Branch, Commit), Software Source, Binary Source
• Outputs: Secret Detection Report
• Other Results and Side Effects: Revoked Secrets

Build

• Semantics: Assemble and/or compile software and documentation into an executable and usable format.
• Aliases: Compile, Install, Assemble, Generate
• Inputs: Software Source, Binary Source
• Outputs: Generated Software, Generated Binaries
• Other Results and Side Effects: N/A

Dependency Discovery

• Semantics: Perform deep discovery to identify all dependencies (including transitive dependencies) in the software and documentation as packaged.
• Aliases: Dependencies
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries
• Outputs: Dependency List/Graph
• Other Results and Side Effects: N/A

Remediate

• Semantics: Find and automatically fix known vulnerabilities for application package dependencies, container base images and os packages.
• Aliases: Fix, Update
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Source Code Reference (Repository, Branch, Commit), Dependency List/Graph
• Outputs: Remediated Software or Documentation, Container Images, Binaries, Source Code Reference (Repository, Branch, Commit), Dependency List/Graph
• Other Results and Side Effects: May also update the Source Code Repository with new dependencies, create a pull request with the updates, use APIs to request an update, open an issue requesting the updates. In the case of mutable infrastructure, this step could update a running system.

Test

• Semantics: Run a test suite. Examples includes unit tests, integration tests, acceptance tests, performance tests, canary tests, A/B tests, smoke tests, code coverage checks.
• Aliases: Validate
• Inputs: Any
• Outputs: Test Results, Test Reports, Test Coverage Reports
• Other Results and Side Effects: N/A

Scan

• Semantics: Use a tool to do verification of software and documenation other than testing. Examples include static code analysis, linting, checking for known vulnerabilities in code or binaries, dynamic security scans, license checks, and code smells.
• Aliases: Check
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Dependency List/Graph
• Outputs: Scan Results, Scan Reports, Scan Coverage Reports
• Other Results and Side Effects: N/A

Bill of Materials

• Semantics: Create a Software Bill of Materials (SBoM) for a given repository that captures pedigree of all the dependencies and is collected at different granularities.
• Aliases: BOM, SBOM
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Dependency List/Graph, Packaged Artifacts
• Outputs: Build BOM
• Other Results and Side Effects: N/A

Package

• Semantics: Create the software artifact(s) that will be published. To specify the version of the software this pipeline is producing, the package step(s) may use a software version that’s specified in the source code, or calculate and automatically update the version using semver logic.
• Aliases: Containerize
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Dependency List/Graph
• Outputs: Packaged Artifacts (Software, Documentation or Binaries), Container Images, Image Tags, Image Digests, Archives
• Other Results and Side Effects: N/A

Tag

• Semantics: Annotate source code, artifacts/images, and so on with information, such as the version number and a description.
• Aliases: Annotate, Version
• Inputs: Source Code Reference (Repository, Branch, Commit), Software Source, Binary Source, Generated Software, Generated Binaries
• Outputs: Tag/annotation metadata
• Other Results and Side Effects: Tags/annotations have been added to the software.

Sign

• Semantics: Use a cryptographic method to authenticate the software. The signature may also include information about the source of the software, how or where it was built, and what level of approval it has received (staging, production, etc.).
• Aliases: N/A
• Inputs: Packaged Artifacts
• Outputs: Signed Artifacts, Signing Record(s)
• Other Results and Side Effects: N/A

Policy

• Semantics: Verifies that policies are followed, for example: software is from a trusted source, source repositories are configured correctly, Kubernetes manifests are configured securely, dependencies are signed, code standards are followed, code reviews are completed, there is a secure chain of custody, or appropriate work items or change requests are associated with the change.
• Aliases: Check, Provenance
• Inputs: Policies, Outputs of other steps
• Outputs: Policy and/or Provenance Reports
• Other Results and Side Effects: Side effects could include blocking a PR/commit so it can’t be merged, discarding or approving an artifact/image.

Publish

• Semantics: Upload software artifacts and documentation to another repository. May also update catalogs, mirrors, release notes, etc.
• Aliases: Push, Upload, Release
• Inputs: Packaged (Signed) Artifacts
• Outputs: Repository URLs
• Other Results and Side Effects: Repositories are updated.

Provision

• Semantics: Request that a new physical or virtual server, network, or other resource be allocated or created. Examples include a test cluster or object storage.
• Aliases: Obtain, Request, Allocate
• Inputs: Resource Request Parameters
• Outputs: Provisioned Resources (with connection info)
• Other Results and Side Effects: Resources are provisioned.

Deploy

• Semantics: Make changes to any environment other than the pipeline environment. Configure the environment. Deploy dependencies, software artificts and/or documentation.
• Aliases: Install, Configure
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Dependency List/Graph, Packaged Artifacts, Provisioned Resources
• Outputs: Routes to Deployments (with connection info). Deployment Records. Secrets to access deployed resources.
• Other Results and Side Effects: Software running in another environment. Documentation hosted in another environment.

Verify Deployment

• Semantics: Verify successful deployment of software or documentation.
• Aliases: Smoke Test
• Inputs: Provisioned Resources, Routes to Deployments, Secrets to access deployed resources.
• Outputs: Deployment Verification Results, Deployment Verification Records
• Other Results and Side Effects: N/A

Analyze

• Semantics: Perform additional processing and analytics based on the results of a previous activity.
• Aliases: Metrics, Score, Grade, Parse
• Inputs: Any
• Outputs: Analysis Results, Analysis Reports
• Other Results and Side Effects: N/A

Message

• Semantics: Send a message to another system; for example, a Slack message or an Email. This is different from “Create Request” because the pipeline doesn’t need to store a link/handle for the message.
• Aliases: N/A
• Inputs: Output of previous steps.
• Outputs: Message Return Code / Results
• Other Results and Side Effects: Message sent.

Create Request

• Semantics: Create a request in another system; for example, create a Change Request that must be approved for a deployment to production. This is different from “Message” because we need to get a link/reference for the new request, and store it, so we can potentially update it later.
• Aliases: Approval, Ticket, Issue, Work Item
• Inputs: Source Code Reference (Repository, Branch, Commit), Link to Previous Work Item, Provisioned Resources, Routes to Deployments
• Outputs: Request Return Code/Results, Link to New Request
• Other Results and Side Effects: Request created.

Update Record

• Semantics: Update a record in another system; for example, update and close a Change Request after a deployment to production; or, update a Github issue with the results of a policy check.
• Aliases: Editor
• Inputs: Source Code Reference (Repository, Branch, Commit), Link to Previous Request, Provisioned Resources, Routes to Deployments
• Outputs: Update Return Code/Results, Link to Request
• Other Results and Side Effects: Request record updated.

Run

• Semantics: Run a script or program that doesn’t fall into one of the other categories. Often executes in another container.
• Aliases: Execute
• Inputs: Software Source, Binary Source, Generated Software, Generated Binaries, Packaged Artifacts, Provisioned Resources, Routes to Deployments
• Outputs: Output or results of the script or program.
• Other Results and Side Effects: Whatever the script or program has done.

Record Results

• Semantics: Record and report pipeline results and compliance evidence. Store pipeline artifacts for long-term archival.
• Aliases: Audit, Attestation, Evidence, Report
• Inputs: Any
• Outputs: Compliance Reports, Archive Files, Return Code/Results
• Other Results and Side Effects: Results, logs, reports, compliance evidence, and other pipeline artifacts are uploaded and/or archived.

Cleanup

• Semantics: Release pipeline resources, de-provision environments, delete pipeline workspace and pipeline container(s).
• Aliases: Finalize, Finish
• Inputs: Pipeline Environment, Pipeline Workspace, Provisioned Resources, Routes to Deployments
• Outputs: Return Code/Results
• Other Results and Side Effects: Deleted Pipeline Environment and Pipeline Workspace, De-provisioned Resources, Deleted Deployments

Inputs and Outputs for Pipeline Steps

The inputs and outputs listed in this table are the ones that are used by more than one step. These inputs and outputs need to be in a location and/or format that the pipeline steps expect so they can be processed correctly.

With the exception of the Setup and Cleanup steps, all steps have the following inputs: Secrets, Pipeline Environment, Pipeline Workspace, Parameters for the Step; and the following outputs: Return Codes, Results, Records and Reports, Logs.