> 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/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md).

# Configure codebase

CI pipelines build and test code that is pulled from Git code repositories.

CI pipelines build and test code that is pulled from a Git code repository. In Harness CI, you can configure a 'Codebase' for your pipeline, to define the Git repository your Build stage(s) will automatically clone during runtime (unless you stage is set to not clone the codebase). When you add a Build stage to a CI pipeline, if not already set, you will have to option to configure your codebase. This topic explains how to configure codebase settings for pipeline to be used by its Build stages.

This topic assumes you have an understanding of the [CI pipeline creation process](/continuous-integration/3.0/use-harness-ci/use-harness-ci/prep-ci-pipeline-components.md).

### Configure the default codebase <a href="#configure-the-default-codebase" id="configure-the-default-codebase"></a>

When you add a **Build** stage to a CI pipeline, you specify where your build code is stored. This becomes the pipeline's *default codebase*.

1. In the Pipeline Studio, select **Add Stage**, and then select **Build**.
2. Enter a **Stage Name**. **Description** and **Tags** are optional.
3. Make sure **Clone Codebase** is enabled. This tells Harness to clone the codebase into the build environment before running the steps in the stage.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>In VM runners and cloud infrastructure, the step to clone your codebase runs in a container by default. Enable the <code>CI_GIT_CLONE_CONTAINERLESS</code> feature flag to run it on the host, which is recommended for faster cloning on Windows by eliminating image download time.</p></div>
4. Configure your codebase connection.
   * To clone a repo from the [Harness Code Repository module](https://developer.harness.io/code-repository/), select **Harness Code Repository**, and then select the repo to clone.
   * To clone a repo from a third-party Git provider, select **Third-party Git provider**, select the relevant [code repo connector](/harness-platform/3.0/harness-platform-resources/connectors/code-repositories.md), and enter the name of the repo to clone, if **Repository Name** is not automatically populated.
5. Select **Set Up Stage**.

If you need to change the connector or other default codebase settings, go to [Edit the default codebase configuration](#edit-the-default-codebase-configuration). If you don't want every stage to clone the default codebase, go to [Disable Clone Codebase for specific stages](#disable-clone-codebase-for-specific-stages). You can also [clone multiple repositories in a stage](/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline.md).

<details>

<summary>YAML example: Default codebase configuration</summary>

```yaml
pipeline:
  name: tutorial example
  identifier: tutorial_example
  projectIdentifier: default
  orgIdentifier: default
  tags: {}
  properties:
    ci:
      codebase:
        connectorRef: YOUR_CODEBASE_CONNECTOR_ID
        build: <+input>
```

</details>

<details>

<summary>YAML example: Harness Code Repository codebase configuration</summary>

This configuration is for repositories in the [Harness Code Repository module](https://developer.harness.io/code-repository/).

```yaml
pipeline:
  name: tutorial example
  identifier: tutorial_example
  projectIdentifier: default
  orgIdentifier: default
  tags: {}
  properties:
    ci:
      codebase:
        repoName: YOUR_HARNESS_CODE_REPO_NAME
        build: <+input>
```

</details>

### Disable Clone Codebase for specific stages <a href="#disable-clone-codebase-for-specific-stages" id="disable-clone-codebase-for-specific-stages"></a>

After defining the default codebase in the first Build stage, when you add subsequent stages to the pipeline, you can disable **Clone Codebase** for individual stages. You can also disable cloning the default codebase, if necessary.

You might disable **Clone Codebase** if the codebase is not needed for the stage's operations, or you need to use specific `git clone` arguments (such as to [clone a subdirectory instead of an entire repo](/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/clone-subdirectory.md)). You can also [clone multiple code repos in a pipeline](/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/clone-and-process-multiple-codebases-in-the-same-pipeline.md).

In the Visual editor, you can disable **Clone Codebase** in the stage's **Overview** tab.

In the YAML editor, set `cloneCodebase` to `false` in the `stage.spec`.

```yaml
- stage:
    name: build
    identifier: build
    description: ""
    type: CI
    spec:
      cloneCodebase: false
```

For more information about Build stage settings, go to [CI Build stage settings](/continuous-integration/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md).

### Edit the default codebase configuration <a href="#edit-the-default-codebase-configuration" id="edit-the-default-codebase-configuration"></a>

{% hint style="info" %}
Git Clone enhancements listed below are now Generally Available (GA)

Harness has introduced several powerful enhancements to Git clone operations, available in both the Git Clone step and the native Clone Codebase functionality. These include:

* Git LFS - Allows users to clone repositories with large file storage (LFS) efficiently.
* Fetch Tags - Enables fetching of tags during the clone operation.
* Sparse Checkout - Enables cloning specific subdirectories.
* Clone Submodules - Adds options for including and recursively cloning Git submodules.
* Clone Path Customization - Exposes the clone path in the codebase section, allowing users to specify a custom clone directory.
* Additional Pre-Fetch Command - Ability to specify any additional Git commands to run before fetching the code.

If these capabilities are not yet enabled in your account, please reach out to [Harness Support](mailto:support@harness.io) for assistance.
{% endhint %}

{% tabs %}
{% tab title="Visual" %}
To edit a pipeline's default codebase configuration, select **Codebase** on the right side panel of the Pipeline Studio's Visual editor.
{% endtab %}

{% tab title="YAML" %}
To edit a pipeline's default codebase configuration in the YAML editor, edit the `codebase` section. For example:

```yaml
pipeline:
  name: tutorial example
  identifier: tutorial_example
  projectIdentifier: tutorial_test
  orgIdentifier: default
  tags: {}
  properties:
    ci:
      codebase:
        connectorRef: YOUR_CODEBASE_CONNECTOR_ID
        build: <+input>
        depth: 0
        sslVerify: true
        prCloneStrategy: MergeCommit
```

{% endtab %}
{% endtabs %}

In addition to changing the **Connector** (`connectorRef`) or **Repository Name** (`repoName`), you can edit the following **Advanced** settings.

#### Depth <a href="#depth" id="depth"></a>

The number of commits to fetch when the pipeline clones the codebase repo.

The default depth varies by build and trigger type:

* For manually-triggered branch and tag builds, the default depth is `50`. This means 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`. This means each `git clone` operation fetches all commits from the relevant branch.

For more information, go to the [git clone documentation](https://git-scm.com/docs/git-clone).

#### Pull Request Clone Strategy <a href="#pull-request-clone-strategy" id="pull-request-clone-strategy"></a>

When a build is triggered by a pull request, this setting determines the branch to use for the artifact after the repo is cloned.

If this is set to **Merge Commit** (which is the default setting), the pipeline tries to merge the pull request branch with the target branch before building the artifact. This guarantees that the artifact includes all commits in both the pull request and the target branch. The disadvantage is that this can take more time and result in build failures: If the merge fails, then the build fails.

If this is set to **Source Branch**, the pipeline builds the artifact from the latest commit in the pull request branch. This can be faster and less likely to result in build failures; however, it might not include some commits in the target branch.

#### Clone Directory <a href="#clone-directory" id="clone-directory"></a>

An optional target path in the pipeline workspace where you want to clone the repo.

You can't specify `/harness/` as a target directory for a **Git Clone** step because this folder is reserved for the **Build** stage's codebase. You can specify **Shared Paths** in your [CI Build stage settings](/continuous-integration/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/ci-stage-settings.md) to share data across steps in your **Build** stage.

{% 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`; both paths work). If you use macOS infrastructure, specify clone directory paths using either the full macOS workspace path (for example, `/tmp/harness/my-repo`) or a relative path (for example, `./my-repo`). For more information, go to [How can I share cache between different OS types?](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-can-i-share-cache-between-different-os-types-linuxmacos).
{% endhint %}

#### Persist Credentials (Optional) <a href="#persist-credentials-optional" id="persist-credentials-optional"></a>

When selected, Harness persists the Git credentials used during the clone step so they remain available for subsequent steps in the same build.

This is useful when:

* You need to run Git commands (for example, fetching submodules, tagging, or pushing commits) after the clone step.
* You’re using a private Harness Code Repository or authenticated third-party repository, and you want to avoid re-authenticating in every step.

{% hint style="info" %}
The persisted credentials remain available only within the scope of the build environment (container or VM) for the duration of the build. They are not stored or reused after the build completes.
{% endhint %}

#### Fetch Tags <a href="#fetch-tags" id="fetch-tags"></a>

Determines whether to fetch all tags when performing a shallow clone (depth > 0). Setting this to `true` is equivalent to adding the `--tags` flag.

#### Download LFS Files <a href="#download-lfs-files" id="download-lfs-files"></a>

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. Default is `false`.

#### Sparse Checkout <a href="#sparse-checkout" id="sparse-checkout"></a>

Do a sparse checkout on given patterns. The subset of files is chosen by providing a list of directories in cone mode. Refer to [git documentation](https://git-scm.com/docs/git-sparse-checkout#_internalscone_pattern_set) for more details.

#### Include Submodules <a href="#include-submodules" id="include-submodules"></a>

Determines whether to include submodules in the clone. Default is `false`. Set to `true` to include submodules or recursive to clone submodules recursively.

#### Pre Fetch Command <a href="#pre-fetch-command" id="pre-fetch-command"></a>

Specify any additional Git commands to run before fetching the code. This field is for Git commands only; separate each command with a new line.

This could be used, for example, to set additional LFS configurations or clone specific submodules. For example,

```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 those files are accessed. 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 performed by `git bisect`, trigger on-demand blob downloads as the files they touch are accessed. The initial fetch size for large repositories is reduced.

Partial clone works with the [Harness Code Repository module](https://developer.harness.io/code-repository/) and any third-party Git provider that supports the partial clone protocol (GitHub, GitLab, Bitbucket, and others).

To enable partial clone, set `depth: 0` so the clone is not shallow, then add a `preFetchCommand` that runs `git fetch` with a `--filter` flag:

```yaml
properties:
  ci:
    codebase:
      connectorRef: YOUR_CODEBASE_CONNECTOR_ID
      build: <+input>
      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, and combining a shallow clone with a partial-clone filter is not supported and may produce unexpected results.

The expression `<+codebase.branch>` resolves to the 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. If you need 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.

Go to the [`git rev-list --filter` reference](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt) to review all supported filter values.

To verify that partial clone is active inside a build step, add a **Run** step that prints the following Git configuration values:

```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 are materialized in the working tree. This further reduces disk usage when only a subset of the repository is needed for the build.
{% endhint %}

Blobs that were not fetched upfront are downloaded on demand the first time they are accessed, for example by `git checkout`, `git show`, or `git blame`.

<details>

<summary>Partial clone filter is ignored or produces errors when depth is greater than 0</summary>

Set depth to 0. Shallow clones (depth > 0) are incompatible with partial clone filters. Remove the depth setting or set it explicitly to 0, then re-run the pipeline.

</details>

**Example: Conditional Git clean and reset**

When you run builds on persistent workspaces, for example a [shared path](/continuous-integration/3.0/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 may want to control whether each run discards untracked files or resets the working tree back to the remote branch. You can drive this behavior from `preFetchCommand` using pipeline variables and conditional expressions, so a single pipeline supports both warm and clean runs without editing 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
properties:
  ci:
    codebase:
      connectorRef: YOUR_CODEBASE_CONNECTOR_ID
      build: <+input>
      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">
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 to remove build artifacts and restore a clean working tree.
* **`resetVar == "TRUE"`:** Runs `git fetch origin <branch>` followed by `git reset --hard origin/<branch>`, 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 is strict string matching. Only the literal value `TRUE` triggers the command. Values such as `true`, `True`, or `1` are treated as false.
* **Independent toggles:** `cleanVar` and `resetVar` are evaluated 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/3.0/harness-platform-resources/triggers/triggers-overview.md), or pin them through an input set.
* **No-op fallback:** The `git --version` placeholder is required so the ternary expression always produces a valid command line when the condition is false.

#### SSL Verify <a href="#ssl-verify" id="ssl-verify"></a>

If **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 are willing to run your builds anyway.

If you want 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/3.0/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates.md)

#### Set Container Resources <a href="#set-container-resources" id="set-container-resources"></a>

Set maximum resource limits for the containers that clone the codebase at runtime:

* **Limit Memory:** The maximum memory that the container can use. You can express memory as a plain integer or as a fixed-point number using the suffixes `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 are measured in CPU units. Fractional requests are allowed; for example, you can specify one hundred millicpu as `0.1` or `100m`. The default is `400m`. For more information, go to [Resource units in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-units-in-kubernetes).

### Troubleshoot codebases <a href="#troubleshoot-codebases" id="troubleshoot-codebases"></a>

Go to the [Harness CI Knowledge Base](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md) for common questions and issues related to codebases, such as:

* [How do I improve codebase clone time?](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#how-can-i-reduce-clone-codebase-time)
* [The same Git commit is not used in all stages.](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#the-same-git-commit-is-not-used-in-all-stages)
* [Git fetch fails with invalid index-pack output when cloning large repos.](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#git-fetch-fails-with-invalid-index-pack-output-when-cloning-large-repos)
* [Clone codebase fails due to missing plugin.](/continuous-integration/3.0/troubleshooting-and-resources/ci-articles-and-faqs/continuous-integration-faqs.md#clone-codebase-fails-due-to-missing-plugin)

For information about branch protection and status checks for codebases associated with Harness CI pipelines, go to [SCM status checks](/continuous-integration/3.0/use-harness-ci/use-harness-ci/codebase-configuration/scm-status-checks.md).

For troubleshooting information for Git event (webhook) triggers, go to [Troubleshoot Git event triggers](/harness-platform/3.0/harness-platform-resources/triggers/triggering-pipelines.md#troubleshoot-git-event-triggers).

{% @harness-feedback/feedback %}