Configure Git Sync in Harness

Updated 4 days ago by Michael Cretzman

Harness Git Experience syncs one or more Git repositories with your Harness Projects, including all of their Pipelines and their resources. When you push changes to your Git repository, the changes are pushed to your Harness entities as well, and vice versa.

This topic explains how to configure the integration between your Git repositories and Harness Projects, Pipelines, and resources.

In this topic:

Before You Begin


  • Git Sync in Harness is limited to the following Git providers:
    • GitHub
    • Bitbucket
    Git Management using BitBucket is in Beta and is behind the Feature Flag GIT_SYNC_WITH_BITBUCKET. Contact Harness Support to enable it. Harness only supports BitBucket cloud.
  • In the Git Connectors, all Projects that connect to a given Git repo must use the same Connection Type: SSH or HTTP. For more information, see Connection Type.
    Let us take an example where Project1 and Project2 connect to repo Repo1. In this case, the Git connectors for both projects must use the same Connection Type.
  • Do not change any Types or Identifiers (Account Id, Org Id, Project Id, Connectors, etc) for any Harness entities. Ids are immutable and if they are out of sync, Harness Git Experience will not work.
  • Do not delete the branch that you used to enable Git sync. Deleting this branch will cause inconsistencies in the Harness Git Experience.
  • Harness Git Experience is not enabled for Pipeline Triggers at this time. Pipelines with Harness Git Experience enabled can use default Triggers, but not Triggers added to Pipelines in Git branches.

Review: Git Sync Requirements

  • You can sync the following Harness resources with your Git repo:
    • Pipelines
    • Connectors
    • Input Sets
    • Templates
    • Feature Flags
  • Only the resources created at the Project scope can be synced to Git. Resources created at the Account or Org scope will not be synced.

Review: Harness to Git Sync

For Git-enabled projects, Git is the source of truth. Harness changes don't take effect until they're committed to Git.

Harness to Git flow can be triggered for the following scenarios:

  • When a new entity is created.
  • When an existing entity is modified.
  • When Git is enabled on an existing Project with existing entities.

Review: Git to Harness Sync

When you enable Git to create and manage the config in Harness, any change done in Git is synced to Harness.

  • Git to Harness flow is initiated only for those repos and branches which exist in Harness.
  • You must manually sync every new branch in Git, to push subsequent changes automatically.
  • Git to Harness is synced using the webhook that is automatically registered for each Project when Git Experience is enabled. However, make sure you have the following permissions for the GitHub Personal Access Token for automatic webhook registration to work:
    • Scopes: select all the repouser, and admin:repo_hook options
    You should also be the repo admin.
  • Although Webhooks are applied automatically by Harness, you can do it manually in case the automatic Webhook registration doesn't work.
    You obtain the Webhook to use in your repo by clicking the Webhook icon.
    Log into your repo in the Git provider and navigate to its Webhook settings. For example, here's the Webhooks section of GitHub.
    Add a Webhook.
    In the Webhook settings, paste the Webhook URL you copied from Harness into the payload URL setting in the repo.
    Make sure that you select JSON for the content type. For example, in GitHub, you select application/json in Content type.


  • You must have valid Git credentials and a repo within this Git account.
  • Make sure that you have Project Administrator permissions in Harness to create a Project and enable Git Experience on Projects. See Permissions Reference.
  • Make sure you have a Git Source Code Manager in your Harness account. A Harness SCM is required to sync entities from Harness to Git. For detailed steps to add an SCM, see Add Source Code Managers. If you try to enable Harness Git Experience without first setting up an SCM, Harness will warn you and require you to set one up.

Step 1: Add a Harness SCM

Once you have set up a Harness SCM, you can enable Git Experience in your Harness Project.

This topic uses GitHub as the SCM to explain Git Experience.

Once enabled, you can add your Pipelines and resources and select the repos and folders where their YAML files are stored.

See Add Source Code Managers.

Git Management using BitBucket is behind the Feature Flag GIT_SYNC_WITH_BITBUCKET. Contact Harness Support to enable it. Harness only supports BitBucket cloud.

Step 2: Create a Repo

In the Git provider, you want to use for syncing your Project, create a repo(s) for the Project. If you wish to use an existing repo, skip this step.

  • You can use multiple repos in the Harness Git Experience for a Project. For example, you could add Pipelines to one repo and Connectors to another.
  • Make sure your repo has at least one branch, such as main or master. For most Git providers, you can simply add a README file to the repo, and the branch is created.

Here's a new GitHub repo named GitExpDocExample.

Step 3: Create a New Project

You can enable Git Management for new as well as existing Projects.

If you wish to enable Git Management for an existing Project, skip this step.

In Harness, create a new Project. See Create Organizations and Projects.

Here's a new Project named GitExp Doc Example.

Add any team members as contributors.

When you're done you'll have a new Project containing the modules according to your license.

Step 4: Enable Harness Git Experience

In your Project, select a module such as CI or CD.

Click Project Setup, and then click Git Management.

The Enable Git Experience settings appear.

Click Enable Git Experience.

Step 5: Configure Harness Folder

Harness requires a Git folder to sync your projects and resources. All the configurations are stored in the Harness Folder. The Harness Folder is created in the Git directory you select and is named .harness.

You can have multiple Harness Folders to store configs.

For example: If you have two Connectors in a single Project you can have one Harness folder for each Connector or a common Harness Folder for the entire Project.

Later, when you add Pipelines and resources to this Project, you can specify their default folders. When a Pipeline in one repo needs to access a Connector/Secret/etc in another repo at runtime, the Pipeline will always use the Connector/Secret/etc in their default branch and folder.

You can add the Project's Harness Folder at the root of your repo or in a subfolder.

Create the folder in your repo before setting up the Harness Folder. You will enter the name of the folder in Harness. Harness does not create the folder for you.

In Repository Display Name, enter a name for the repo. It doesn't have to be the same as the Git repo name. The name you enter here will appear in Harness only. It will identify the Project repo.

For example, here's the Repository Display Name GitExpDocExample after Harness Git Experience is enabled:

In Select the Connector to your GitHub, select, or create a Git Connector to the repo for your Project. For steps, see Code Repo Connectors.

Important: The Connector must use the Enable API access option and Username and Token authentication. Harness requires the token for API access. Generate the token in your account on the Git provider and add it to Harness as a Secret. Next, use the token in the credentials for the Git Connector.

Here's an example of a GitHub Connector with all the correct settings:

Once you add a Connector, enter the Repository Name with which you want to establish a connection.

You should see the Repo URL below the repository name.

Click Test Connection. Once Harness verifies the connection, you will see Connection Successful.

In Select Harness Folder, enter the name of the folder in your repo where you want to sync.

In Select Default Branch, select the branch that you want to use, such as main.

Click Continue.

Step 6: Select Connectivity Mode

In Select Connectivity Mode, you have two options:

  • Connect Through Manager: Harness SaaS will connect to your Git repo whenever you make a change and Git and Harness sync.
  • Connect Through Delegate: Harness will make all connections using the Harness Delegate. This option is used for Harness On-Prem frequently, but can be used for Harness SaaS as well. See Harness On-Premise Overview.
Secrets: If you select Connect Through Manager, the secrets are decrypted on the Delegate and are available on the Harness Manager. This is different from Connect Through Delegate where the Harness Delegate decrypts the secrets. The secrets are then used in the context of the Delegate that sits in your private network. See Harness Secrets Manager Overview.

If you select Connect Through Manager then click Save and Continue.

If you select Connect Through Delegate, select/add the Delegate you want to use. See Delegate Installation Overview.

Harness Git Experience is enabled and the new repo and folder are listed.

Step 7: Select the Branch to Sync

Perform this step if you are enabling Git Experience for an existing Project that already has Pipeline or Harness resources. This will establish a full sync of your Harness Project and its resources with Git.

The settings for this stage will not be available if you are enabling Git Experience for a new Project.

You can select or create a specific branch in your Git repo to sync these resources. You can also start a pull request to merge these changes. Click Save.

The SCM user profile credentials of the user who initiated the sync will be used to sync all resources to Git.

If you use a Git connector at Project scope to enable Git experience, then the connector will be synced as well. Make sure you merge this connector to the default branch so that it is not accidentally deleted in the non-default branch.

To view the sync status, click Config in Git Management.

You can check the status of any entity's sync under Sync Status. An entity can have any of the following sync statuses:


Your Harness entities will appear in the Harness Folder under the selected branch in your Git Repo after the sync is complete.

To resync any entities that failed to sync, click Resync.

Step 8: Review the Harness Git Experience in your Project

Harness does not automatically add a folder to your repo until you create a Pipeline or resource like a Connector in your Project.

You can see the repo setting in your Project before creating Pipelines and resources.

In your Project, click one of your modules. In this example, we'll use Builds.

Click Pipelines.

At the top of the page, you can see All Repositories.

Click All Repositories and select the name of the repo you entered in the Repository name earlier.

You can now select any branch from the repo.

Harness Git Experience is enabled.

Next Steps

Now that you've enabled Harness Git Experience in your Project, you can start creating Pipelines and resources and syncing them with Git.

See Git Experience How-tos.

Please Provide Feedback