Pipeline step types proposal

docs/vocabulary.md

@@ -23,6 +23,7 @@
 - [Mapping of Terms](#mapping-of-terms)
   - [CI/CD Tools and Technologies](#cicd-tools-and-technologies)
   - [Stages](#stages)
+  - [Pipeline Step Types](#pipeline-step-types)
   - [SCM Tools and Technologies](#scm-tools-and-technologies)
 - [Shared Vocabulary](#shared-vocabulary)
 
@@ -452,6 +453,222 @@ In the lists and table below, Software Artifacts includes: Documentation Source
 | Release | I | I | I, O | I, O | I | I | I | O | O | O |
 | Deploy | I | I | I | I | I, O | I | I | O | O | O |
 
+### 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.
+
+| Step Name | Software Source | Binary Source | Generated Software | Generated Binaries | Source Code Reference | Dependency List/Graph | Test Coverage Reports | Packaged Artifacts | Provisioned Resources | Routes to Deployments | Request Link |
+| :-------: | ------------------ | ---------------- | ---------------------- | ------------------- | ------------------------------ | --------------------- | --------------------- | ------------------ | --------------------- | --------------------- | -------------- |
+| Setup | | | | | | | | | O | | |
+| Source | O | O | | | I | | | | | | |
+| Secret Detection | I | I | | | I | | | | | | |
+| Build | I | I | O | O | | | | | | | |
+| Dependency Discovery | I | I | I | I | | O | | | | | |
+| Remediate | I, O | I, O | I, O | I, O | I, O | I, O | | | | | |
+| Test | I | I | I | I | | | O | I | I | I | |
+| Scan | I | I | I | I | | I | | | | | |
+| Bill of Materials | I | I | I | I | | I | | | | | |
+| Package | I | I | I | I | | I | | O | | | |
+| Tag | I | I | I | I | I | | | | | | |
+| Sign | | | | | | | | I, O | | | |
+| Policy | I | I | I | I | I | I | I | I | I | I | I |
+| Publish | | | | | | | | I | | | |
+| Provision | | | | | | | | | O | | |
+| Deploy | I | I | I | I | | I | | I | I | O | |
+| Verify Deployment | | | | | | | | | I | I | |
+| Analyze | I | I | I | I | I | I | I | I | I | I | I |
+| Message | | | | | I | | I | I | I | I | |
+| Create Request | | | | | I | | | | I | I | I, O |
+| Update Record | | | | | I | | | | I | I | I, O |
+| Run | I | I | I | I | | | | I | I | I | |
+| Record Results | I | I | I | I | I | I | I | I | I | I | I |
+| Cleanup | | | | | | | | | I | I | |
+
 ### SCM Tools and Technologies
 
 The table below is an attempt to create a mapping of different terms used