> 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/use-harness-ci/use-harness-ci/codebase-configuration/git-clone-step.md).
# Git Clone step in CI
Use the Git Clone step to clone additional repositories into the CI stage's workspace.
The **Git Clone** step in Harness Continuous Integration (CI) pipelines clones a repository into the CI stage's workspace. In addition to the pipeline's default [clone codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md), you can use **Git Clone**, **Run**, and **Plugin** steps to clone additional code repos into the pipeline's workspace.
For example, assume the default codebase is a repo that contains app code files, and the Dockerfile that builds the app image is in a different repo. You can use a **Git Clone** or **Run** step to clone the second repo into the workspace. Then, you can use a **Build and Push** step to build and push an image with files from both repos.
## What you will learn in this topic
By the end of this topic, you will learn how to:
* Add a **Git Clone** step to clone a second repo into the pipeline's workspace.
* Configure the step settings and additional configuration options.
* Troubleshoot common **Git Clone** step issues.
## Before you begin
Before you use the Git Clone step, make sure you have:
* A CI pipeline with a Build stage.
* A code repository connector for the source control provider that hosts the repo you want to clone. If you use the [Harness Code Repository](/code-repository/2.0/new-to-harness-code/overview.md), you do not need a connector.
## Add a Git clone step
Add a **Git Clone** step to clone a second repo into the pipeline's workspace.
```yaml
- step:
type: GitClone
name: clone second repo
identifier: clone_second_repo
spec:
connectorRef: account.git2
build:
type: branch
spec:
branch: main
```
{% hint style="info" %}
In VM runners and cloud infrastructure, the step that clones your codebase runs in a container by default. Enable the `CI_GIT_CLONE_CONTAINERLESS` feature flag to run it on the host. Running it on the host is recommended for faster cloning on Windows because it eliminates image download time. To understand the limitation of this setting, go to [Parallel container-less Git Clone steps are not supported](#parallel-container-less-git-clone-steps-are-not-supported).
{% endhint %}
## Step settings
The **Git Clone** step has the following settings. Depending on the stage's build infrastructure, some settings might be unavailable.
### Name, id, and description
Enter a **Name** that summarizes the step's purpose. Harness automatically assigns an **Id** ([Entity Identifier Reference](/harness-platform/use-harness-platform/references/entity-identifier-reference.md)) based on the **Name**. You can change the **Id**.
The **Description** is an optional text string.
### Connector
If you use the [Harness Code Repository (Code)](/code-repository/2.0/new-to-harness-code/overview.md), you do not need to configure a connector.
For a third-party Git provider, select a connector for the source control provider that hosts the code repo you want the step to clone.
To configure code repository connectors, go to:
* Azure Repos: [Connect to Azure Repos](/harness-platform/use-harness-platform/connectors/code-repositories/add-an-azure-repos-connector.md)
* Bitbucket: [Bitbucket connector settings reference](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-bitbucket-connector/bitbucket-connector-settings-reference.md)
* GitHub: [GitHub connector settings reference](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector/git-hub-connector-settings-reference.md)
* GitLab: [GitLab connector settings reference](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-gitlab-connector/git-lab-connector-settings-reference.md)
* Other Git providers:
* [Git connector settings reference](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-git-connector/git-connector-settings-reference.md)
* [Connect to an AWS CodeCommit Repo](/harness-platform/use-harness-platform/connectors/code-repositories/code-repositories-connectors-overview.md)
{% hint style="warning" %}
To use a connector with an SSH credential that uses a passphrase with Kubernetes build infrastructure, you must have delegate version 25.02.85201 or later. This configuration does not work with earlier delegate versions.
{% endhint %}
### Repository name
If the connector's [URL Type](/harness-platform/use-harness-platform/connectors/code-repositories/add-a-git-connector/git-connector-settings-reference.md#url-type) is **Repository**, Harness automatically populates **Repository Name** based on the repository defined in the connector's configuration.
If the connector's URL Type is **Account**, specify the name of the code repo that you want to clone into the pipeline workspace.
### Build type, branch name, and tag name
For **Build Type**, select **Git Branch** to clone code from a specific branch within the repo, or select **Git Tag** to clone code from a specific commit tag. Based on your selection, specify a **Branch Name** or **Tag Name**.
{% hint style="info" %}
You can use [fixed values, runtime input, or variable expressions](/harness-platform/use-harness-platform/variables-and-expressions/runtime-inputs.md) for the branch and tag names. For example, enter `<+input>` for the branch or tag name to supply a value at runtime. You can also use expressions to match the pipeline's [codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md) branch or tag, so that the pipeline and the Git Clone step both pull code from the same environment. For example, both pull `production` when a production build runs, or `development` when a development build runs.
{% endhint %}
This setting applies only to the repo that this **Git Clone** step specifies. It is separate from the `codebase` object for the pipeline's **Build** stage. To make this step's repo use the same branch or commit as the primary codebase, specify `<+codebase.branch>` or `<+codebase.tag>` for **Branch Name** or **Tag Name**. These expressions pull runtime input from the pipeline. For example, if the pipeline's primary codebase uses the `development` branch, the **Git Clone** step clones the `development` branch from its repo. To reference CI codebase variables, go to the [CI codebase variables reference](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/built-in-cie-codebase-variables-reference.md).
### Clone directory
An optional target path in the pipeline workspace where you want to clone the repo.
You cannot specify `/harness/` as a target directory for a **Git Clone** step because this folder is reserved for the **Build** stage's [codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md). To share data across steps in your **Build** stage, specify **Shared Paths** in your [CI Build stage settings](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md).
{% hint style="info" %}
**macOS workspace path**
On Harness macOS build infrastructure, `/harness` is a protected system directory. The workspace is `/tmp/harness` instead. `/tmp/harness` is a symlink to `/private/tmp/harness`, and both paths work. If you use macOS infrastructure, specify clone directory paths with either the full macOS workspace path, such as `/tmp/harness/my-repo`, or a relative path, such as `./my-repo`. To share cache across operating systems, go to [How can I share cache between different OS types?](/continuous-integration/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-can-i-share-cache-between-different-os-types-linuxmacos).
{% endhint %}
## Additional configuration
The following settings are available when you select **Additional Configuration**.
### Privileged
When you enable this setting, Harness runs all containers with the Docker `--privileged` flag enabled. This option is disabled by default.
This option grants the container elevated privileges within the underlying host environment. The container has access to all Linux kernel capabilities and devices, similar to running processes outside the container. It effectively removes the isolation that the container runtime provides and can pose security risks if you do not use it carefully.
### Depth
The number of commits to fetch when the step clones the repo.
The default depth varies by build and trigger type:
* For manually triggered branch and tag builds, the default depth is `50`. Each `git clone` operation fetches the 50 most recent commits.
* For manually triggered PR builds and all auto-triggered builds, such as webhook triggers, the default depth is `0`. Each `git clone` operation fetches all commits from the relevant branch.
Go to the [git clone documentation](https://git-scm.com/docs/git-clone) for more information.
### Fetch tags
Determines whether to fetch all tags when you perform a shallow clone (depth > 0). Setting this to `true` is equivalent to adding the `--tags` flag.
### Pull request clone strategy
When a pull request triggers a build, this setting determines the branch that Harness uses for the artifact after it clones the repo.
If you set this to **Merge Commit**, which is the default, the pipeline tries to merge the pull request branch with the target branch before it builds the artifact. This strategy guarantees that the artifact includes all commits in both the pull request and the target branch. The disadvantage is that the merge can take more time and cause build failures: if the merge fails, the build fails.
If you set this to **Source Branch**, the pipeline builds the artifact from the latest commit in the pull request branch. This strategy can be faster and less likely to cause build failures. However, the artifact might not include some commits in the target branch.
### Download LFS files
The [Git Large File Storage (LFS)](https://git-lfs.com/) client is an extension for versioning large files, such as audio, video, datasets, and graphics. Set **Download LFS Files** to `true` to download Git LFS files. The default is `false`. To run `git lfs` commands in a **Run** step instead, go to [Git Large File Storage](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/gitlfs.md).
### Sparse checkout
Performs a sparse checkout on the patterns you provide. You choose the subset of files by providing a list of directories in cone mode. To review cone pattern sets, go to the [git sparse-checkout documentation](https://git-scm.com/docs/git-sparse-checkout#_internalscone_pattern_set).
### Include submodules
Determines whether to include submodules in the clone. The default is `false`. Set this to `true` to include submodules, or to `recursive` to clone submodules recursively.
### Pre fetch command
Specifies additional Git commands to run before Harness fetches the code. This field accepts Git commands only. Separate each command with a new line.
For example, you can use this field to set additional LFS configurations or to clone specific submodules:
```bash
git config lfs.fetchexclude ".jpg"
```
**Example: Partial clone**
[Git partial clone](https://git-scm.com/docs/partial-clone) downloads commit and tree objects upfront but defers blob (file content) downloads until Git accesses those files. The full commit history is available for `git log` with no extra network calls. Operations that read file content, such as `git blame`, `git show`, and the checkout step that `git bisect` performs, trigger on-demand blob downloads as they access the files. Partial clone reduces the initial fetch size for large repositories.
Partial clone works with the [Harness Code Repository module](https://app.gitbook.com/s/oTP6ysjQCQlt5GlFHRfs/README) and any third-party Git provider that supports the partial clone protocol, such as GitHub, GitLab, and Bitbucket.
To enable partial clone, set `depth: 0` so the clone is not shallow, and then add a `preFetchCommand` that runs `git fetch` with a `--filter` flag:
```yaml
- step:
type: GitClone
name: clone repo
identifier: clone_repo
spec:
connectorRef: YOUR_CONNECTOR_ID
build:
type: branch
spec:
branch: <+codebase.branch>
depth: 0
preFetchCommand: git fetch --filter=blob:none origin <+codebase.branch>
```
`depth: 0` is required. If `depth` is greater than `0`, the clone is shallow. Combining a shallow clone with a partial-clone filter is not supported and might produce unexpected results.
The expression `<+codebase.branch>` resolves to the pipeline codebase branch at runtime. You can also use a literal branch name, such as `main` or `master`. For pull request triggers, `<+codebase.branch>` resolves to the source branch of the PR. To fetch from the target branch instead, use `<+codebase.targetBranch>`.
You can substitute any `--filter` value that Git supports. For example:
* **Defer all blobs:** `git fetch --filter=blob:none origin <+codebase.branch>` downloads no blobs upfront and fetches each one on first access.
* **Defer large blobs only:** `git fetch --filter=blob:limit=100k origin <+codebase.branch>` downloads blobs smaller than 100 KB upfront and defers the rest.
To review all supported filter values, go to the [`git rev-list --filter` reference](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt).
To verify that partial clone is active after the **Git Clone** step, add a **Run** step that prints the following Git configuration values from inside the cloned directory:
```bash
git config --get remote.origin.promisor # expected: true
git config --get remote.origin.partialclonefilter # expected: your filter value, for example blob:none
git rev-parse --is-shallow-repository # expected: false
```
{% hint style="info" %}
Combine partial clone with [sparse checkout](https://git-scm.com/docs/git-sparse-checkout) to limit which directories Git materializes in the working tree. This combination further reduces disk usage when the build needs only a subset of the repository.
{% endhint %}
Git downloads blobs that it did not fetch upfront on demand the first time you access them, for example with `git checkout`, `git show`, or `git blame`.
Partial clone filter is ignored or produces errors when depth is greater than 0
Set depth to 0. Shallow clones (depth > 0) are incompatible with partial clone filters. Remove the depth setting or set it explicitly to 0, and then re-run the pipeline.
**Example: Conditional Git clean and reset**
When you run builds on persistent workspaces, you might want to control whether each run discards untracked files or resets the working tree to the remote branch. An example is a [shared path](/continuous-integration/use-harness-ci/use-harness-ci/prep-ci-pipeline-components.md#shared-paths) on a self-managed build infrastructure that retains the cloned repository across executions. You can drive this behavior from `preFetchCommand` with pipeline variables and conditional expressions, so a single pipeline supports both warm and clean runs without changes to the pipeline structure.
Declare two string pipeline variables and reference them in `preFetchCommand` with the ternary operator. If the variable resolves to the literal string `"TRUE"`, the prefetch phase runs the corresponding Git command. Otherwise, it runs `git --version` as a no-op so the expression remains valid.
```yaml
- step:
type: GitClone
name: clone repo
identifier: clone_repo
spec:
connectorRef: YOUR_CONNECTOR_ID
build:
type: branch
spec:
branch: <+codebase.branch>
preFetchCommand: |-
<+<+pipeline.variables.cleanVar>=="TRUE"?"git clean -fdx":"git --version">
<+<+pipeline.variables.resetVar>=="TRUE"?"git fetch origin <+pipeline.variables.branch> && git reset --hard origin/<+pipeline.variables.branch>":"git --version">
```
Declare the supporting pipeline variables alongside your other pipeline-level variables:
```yaml
variables:
- name: cleanVar
type: String
value: <+input>.default(TRUE)
- name: resetVar
type: String
value: <+input>.default(TRUE)
- name: branch
type: String
value: <+input>.default(<+codebase.branch>)
```
**Behavior:**
* **`cleanVar == "TRUE"`:** Runs `git clean -fdx`, which removes all untracked files and directories, including ignored files. Use this setting to remove build artifacts and restore a clean working tree.
* **`resetVar == "TRUE"`:** Runs `git fetch origin ` followed by `git reset --hard origin/`, which moves the local branch pointer to the remote tip and discards any local commits or uncommitted changes.
* **Neither variable set to `"TRUE"`:** Both expressions resolve to `git --version`, which leaves the existing workspace untouched.
**Important callouts:**
* **Case-sensitive matching:** The comparison uses strict string matching. Only the literal value `TRUE` triggers the command. Harness treats values such as `true`, `True`, or `1` as false.
* **Independent toggles:** Harness evaluates `cleanVar` and `resetVar` separately. You can enable one, both, or neither per execution.
* **Runtime overrides:** Because the variables use `<+input>.default(...)`, you can override `cleanVar`, `resetVar`, or `branch` at runtime from the **Run Pipeline** form or from a [trigger](/harness-platform/use-harness-platform/triggers/triggers-overview.md), or pin them through an input set.
* **No-op fallback:** The pipeline requires the `git --version` placeholder so the ternary expression always produces a valid command line when the condition is false.
### SSL verify
If you set this to **True**, which is the default value, the pipeline verifies your Git SSL certificates. The build fails if the certificate check fails. Set this to **False** only if you have a known issue with the certificate and you want to run your builds anyway.
To use self-signed certificates in a Kubernetes cluster build infrastructure, go to [Configure a Kubernetes Build Farm to use Self-Signed Certificates](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates.md).
### Run as user
This setting is available for Kubernetes cluster build infrastructures only.
All Git clone steps, including the default clone codebase step and any additional **Git Clone** steps, use user 1000 by default for Kubernetes.
If necessary, specify a user ID in **Run as User** to run all processes in the pod when the pod runs in containers. Go to [Set the security context for a pod](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) for more information.
Specifying **Run as User** at the step level overrides **Run as User** in the [build infrastructure settings](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md#infrastructure), if you also specified it there.
### Set container resources
Set maximum resource limits for the resources that the container uses at runtime:
* **Limit Memory:** The maximum memory that the container can use. Express memory as a plain integer or as a fixed-point number with the suffix `G` or `M`. You can also use the power-of-two equivalents `Gi` and `Mi`. The default is `500Mi`.
* **Limit CPU:** The maximum number of cores that the container can use. CPU limits use CPU units. Fractional values are allowed. For example, specify one hundred millicpu as `0.1` or `100m`. The default is `400m`. Go to [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes) for more information.
### Timeout
Set the timeout limit for the step. When the step reaches the timeout limit, the step fails and pipeline execution continues. To set skip conditions or failure handling for steps, go to:
* [Step Skip Condition settings](/harness-platform/use-harness-platform/pipelines/step-skip-condition-settings.md)
* [Step Failure Strategy settings](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md)
## Troubleshooting
SSH-keyscan timeout
If your [connector](#connector) uses SSH authentication, add a `PLUGIN_SSH_KEYSCAN_TIMEOUT` [stage variable](/harness-platform/use-harness-platform/pipelines/add-a-stage.md#stage-variables) to override the timeout limit of the `ssh-keyscan` command. The default is `5s`. Configure stage variables in stage settings, not step settings.
Parallel container-less Git Clone steps are not supported
Harness CI does not support container-less git steps in parallel. Running them in parallel can cause intermittent build failures. Keep your Git Clone steps in sequence when you use container-less build infrastructure.
## Next steps
* [Configure codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md): Configure the default codebase that your pipeline clones.
* [Clone multiple code repos in one pipeline](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline.md): Clone additional repos with Git Clone steps.
* [Clone a subdirectory](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/clone-subdirectory.md): Clone a subdirectory instead of an entire repo.
* [CI codebase variables reference](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/built-in-cie-codebase-variables-reference.md): Reference Git codebase attributes with built-in expressions.
{% @harness-feedback/feedback %}