> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-integration/3.0/new-to-harness-ci/key-concepts.md). # Key Concepts Basic terminology and concepts related to CI pipelines Harness CI organizes your build work into pipelines, stages, and steps. This page explains how these components work together to clone source code, run commands and tests, and publish build outputs. ### What you will learn from this topic By the end of this topic, you will be able to understand: * How pipelines, stages, steps, and step groups fit together. * How stages access source code and share files. * How to select steps for tests, images, artifacts, and caching. * How to select where your build runs. ### Pipeline A CI pipeline is an end-to-end integration workflow that pulls a codebase, builds an artifact, and publishes it to a registry or storage location. You can run a pipeline manually or configure triggers to start it automatically on a schedule or in response to Git events such as a pull request or merge. [Pipelines](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/pipelines) are made up of [stages](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/pipelines/stages), and stages are made up of [steps](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/pipelines/steps). ### Stage A stage represents a major segment of the pipeline workflow. A **Build** stage contains the steps that build, test, and push your code. #### Workspace and shared paths A CI stage provides a workspace for source code and build files. When implicit cloning is enabled, the stage clones its configured codebase during initialization. The default working directory is `/harness`; a step can specify a different working directory. Steps within the same stage share files through the workspace filesystem. Do not rely on a stage workspace persisting across executions or being available automatically to another stage. If steps need access to paths outside the default workspace root, you can add Shared Paths. Each path must begin with a forward slash, for example `/root/.m2` for a Maven cache directory. For more information on choose a file-sharing or persistence strategy, see S[hare CI data across steps and stages](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/caching-ci-data/share-ci-data-across-steps-and-stages). ### Step A stage contains one or more steps. Each step performs a specific task. Choose a step based on the work you need to perform, then configure its inputs in the visual editor or YAML editor. The common CI tasks are: * **Run**: Execute shell commands. * **Run Test**: Execute tests and use Test Intelligence when enabled and supported. * **Background**: Start a long-running service that your other steps need. * **Git Clone**: Clone another repository at a specific point in the stage. * **Build and push**: Build an image and publish it to a registry. * **Upload artifacts**: Publish files produced by the build. * **Save and restore cache**: Reuse files from previous executions. * **Language setup**: Prepare tools required by your build. For more information, see [Use CI Run steps](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/run-step-settings) to configure commands, or [Run tests](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/run-tests/run-tests-in-ci) to configure your test workflow. Registry-specific and upload guides document the inputs for those steps. #### Step references in V1 YAML A Run step uses `run.script`. Some other steps use a reference under `template:` or a supported task key such as `build:`. The reference has a `uses` value and can supply inputs through `with`. These keys describe YAML authoring, not a separate step-selection workflow. The following is a reference-syntax illustration, not a runnable step. Replace the placeholders with the reference and inputs from the specific step guide: ```yaml steps: - template: uses: with: : ``` Do not put `uses` directly under an item in the stage's `steps` list. *** ### Inputs and expressions V1 YAML supports `${{ inputs. }}` references to declared inputs and Harness `<+...>` expressions in supported fields. For example, an external repository clone can use `<+trigger.sourceBranch>` for its branch. Use the syntax documented for the field and expression context. Do not assume that all expressions resolve at the same time or replace one syntax with the other throughout a pipeline. For more information on input configuration, see [CI pipeline creation overview](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/prep-ci-pipeline-components). *** ### Background services Use a **Background** step when your pipeline requires a running service alongside your build steps. A common example is a unit test suite that needs a live Redis or database instance during execution. A **Background** step starts a service and allows execution to continue. Verify service readiness before a dependent step sends requests. The service address depends on the runtime and whether the service runs in a container or directly on the host. Do not assume the step identifier is always a hostname. For more information on configuring connectivity for your runtime, see [Background step settings](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/manage-dependencies/background-step-settings). *** ### Test Intelligence Test Intelligence speeds up your test cycles by running only the unit tests required to confirm the quality of the code changes that triggered a build. Instead of running your full test suite on every commit, Test Intelligence selects the relevant subset based on the code that changed. Use the **Run Test** step and enable Test Intelligence for a supported test configuration. Adding the step alone does not mean that test selection is enabled. *** ### Git clone CI supports three clone scopes: * **Pipeline-level implicit clone:** Define the default repository and ref for stages that inherit the pipeline settings. * **Stage-level implicit clone:** Override repository or ref settings for a stage, or set `clone.enabled: false` to skip its implicit clone. Enabled implicit clones run during stage initialization. * **Explicit Git Clone step:** Clone at a particular point in the step sequence. Choose the Harness Code or external Git provider step and configure its destination directory. You can mix these scopes within a pipeline. A stage can inherit the pipeline-level clone for its primary repository and add an explicit clone step for a second repository. Use separate destination directories to avoid overwriting files. For more information on configuring repositories and clone settings, see [Configure codebases](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase). Connector setup, authentication, and provider-specific requirements belong to the [Platform connectors](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/connectors). *** ### Build and push Select the build-and-push step for your registry. Each registry-specific guide describes authentication, image names, tags, and other inputs, required to configure the step: | Step guide | Registry | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | [Build and push to Docker](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-docker-registry) | Docker Hub | | [Build and push to ACR](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-acr) | Azure Container Registry | | [Build and push to ECR](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-ecr-step-settings) | Amazon Elastic Container Registry | | [Build and push to GAR](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-push/build-and-push-to-gar) | Google Artifact Registry | | [CI integration with Harness Artifact Registry](https://developer.harness.io/artifact-registry/use-artifact-registry/platform-integrations/ci-ar-integrations) | Harness Artifact Registry | *** ### Step groups Use a step group to organize related steps inside a stage. In pipeline YAML, an inline group is an item in the stage's `steps` list: ```yaml pipeline: id: ci_example name: CI example clone: enabled: false stages: - id: build name: Build runtime: cloud steps: - group: id: checks name: Checks steps: - id: hello name: Hello run: script: echo "CI 3.0" ``` This example prints `CI 3.0` without cloning a repository. A reusable step-group template definition is a separate document rooted at `template: group:`; it is not the inline group syntax shown here. *** ### Artifact repos After a build, you can upload artifacts to an artifact repository or object storage using upload steps. Supported destinations include Amazon S3, Google Cloud Storage, and JFrog Artifactory. Upload steps are configured in the same stage as your build steps and run after the artifact is produced. *** ### Caching Caching reduces build time by reusing data from previous runs, for example, dependency packages that are expensive to download on every build. Choose the caching feature for the data you need to reuse: * **Cache Intelligence:** Automatically restore and save dependency caches. Go to Cache Intelligence to configure dependency caching. * **Build Intelligence:** Reuse build outputs with supported tools such as Gradle, Bazel, and Maven. This is distinct from dependency caching. Go to Build Intelligence to review supported tools and configuration. * **Manual cache steps:** Control which paths are saved and restored and which storage to use. Go to Share and cache CI data to select a cache step. If you need manual control over what is cached and where, cache steps are available for saving and restoring caches from S3, GCS, Azure, and Harness storage. You can also use caching to share data across stages by saving output from one stage and restoring it in a later stage. *** ### Unified platform and runtime Select your stage's execution environment through its `runtime` settings, such as `runtime: cloud` or a Kubernetes configuration with a connector and namespace. Stage `platform` settings specify the operating system and architecture where supported. For more information on prerequisites and environment choices, see [Set up build infrastructure](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/which-build-infrastructure-is-right-for-me). *** ### Platform components Harness CI uses several components that are common to the Harness Platform. #### Connectors [Connectors](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/connectors) contain the information needed to integrate with third-party tools such as Git providers, container registries, and artifact repositories. Harness uses connectors at pipeline runtime to authenticate and run operations in external systems. For example, a build-and-push step uses a container registry connector to authenticate and push an image. #### Delegates The Harness [Delegate](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/delegates/delegate-closed-beta/delegate-overview) is a service you install in your environment, such as a Kubernetes cluster, that connects to the Harness Manager and executes pipeline tasks. The delegate uses the credentials configured in your connectors and requires permissions in the target environment to perform build operations. #### Variables You can define and reference built-in and custom [variables](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/variables-and-expressions/runtime-inputs) in pipelines and stages. Variables are available across the pipeline, and you can propagate or override their values in later stages. #### Triggers You can run pipelines manually or configure [triggers](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/triggers/triggers-overview) to start them automatically based on Git events such as commits and pull requests, or on a schedule. #### Dashboards [Dashboards](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/dashboards) give you a high-level view of all your builds across statuses: **successful**, **failed**, **cancelled**, and **expired**. You can see the percentage of successful builds per codebase and drill into individual builds to review logs and troubleshoot failures. *** ### Next steps * [Get Started](https://developer.harness.io/continuous-integration/3.0/new-to-harness-ci/onboarding-guide#interactive-guide): Run your first CI 3.0 pipeline. * [Configure codebases](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase): Set up repositories and clone settings. * [Set up build infrastructure](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/which-build-infrastructure-is-right-for-me): Choose where your builds run. * [Run tests](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/run-tests/run-tests-in-ci): Configure test steps and Test Intelligence. * [Build and push](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/build-and-upload-artifacts/build-and-upload-an-artifact): Build an image and publish it to a registry. * [Share and cache CI data](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/caching-ci-data/share-ci-data-across-steps-and-stages): Reuse data across builds and stages.