> 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/code-repository/use-harness-code/manage-repositories/link-repo.md).

# Link Repositories

Link a Harness Code repository to an external GitHub repository so Harness keeps a synced, read-only copy.

{% hint style="success" %}
This feature is in [Limited GA](#user-content-fn-1)[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="code-repository" pagePath="code-repository/use-harness-code/manage-repositories/link-repo" pageTitle="Link%20a%20Repository" featureFlags="%5B%7B%22name%22%3A%22Link%20repository%22%2C%22key%22%3A%22CODE\_LINK\_REPOS\_ENABLED%22%2C%22status%22%3A%22LIMITED\_GA%22%2C%22description%22%3A%22Adds%20a%20Link%20repository%20action%20that%20attaches%20a%20Harness%20Code%20repository%20to%20an%20external%20Git%20repository%20through%20a%20connector%2C%20and%20keeps%20a%20read-only%20copy%20of%20its%20branches%20and%20tags%20in%20sync.%22%7D%5D" %}
{% endhint %}

A linked repository is a Harness Code repository that stays attached to an external Git repository through a Harness Git connector. Harness copies branches and tags in, then keeps that copy updated. The copy in Harness is read-only, so people keep committing on the external repository.

Use a linked repository when Harness needs a current copy of an external repository, and commits must stay on that provider. For example, you can browse and clone the code in Harness, use the repository as a pipeline codebase, or use it as a configuration-file source.

## How linking differs from importing and mirroring <a href="#how-linking-differs" id="how-linking-differs"></a>

|                 | [Import](https://developer.harness.io/code-repository/use-harness-code/manage-repositories/import-repo.md) | Link                                        | [Mirror](https://developer.harness.io/code-repository/use-harness-code/manage-repositories/mirror.md) |
| --------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| What it does    | Copies Git data once                                                                                       | Keeps a read-only copy of branches and tags | A CI pipeline you build that can push commits between repositories                                    |
| After setup     | Becomes a normal Harness repository you can push to                                                        | Stays attached to the connector             | Runs whenever you trigger it                                                                          |
| Source of truth | Harness, after the copy                                                                                    | The external repository                     | Whichever repository the pipeline pushes to                                                           |

## Supported connectors <a href="#supported-connectors" id="supported-connectors"></a>

Linked repositories use Harness [Git connectors](https://developer.harness.io/harness-platform/use-harness-platform/connectors/code-repositories/add-a-github-connector.md). The connector can be defined at the account, organization, or project scope.

| Item            | Supported values                                                                                                                                   |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Provider        | GitHub connectors only                                                                                                                             |
| Connection type | HTTP/HTTPS only. SSH connectors are not supported.                                                                                                 |
| Authentication  | Username and token, username and password, GitHub OAuth, and GitHub App. Anonymous connectors are not supported.                                   |
| Connector type  | Repository-level connectors, which point to a single repository, and account-level connectors, which let you choose a repository from the provider |

The connector must be able to read the remote repository. Harness Code verifies access when you link the repository and fails the request if it cannot reach it.

## Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before you link repositories ensure you have:

* **Create permission:** You need **Create** on Code repositories, the same permission required to [create a repository](https://developer.harness.io/code-repository/use-harness-code/manage-repositories/create-repo.md).
* **A GitHub connector:** You need a GitHub connector that can clone the repository and manage webhooks on it. The connector credential needs read access to the repository and webhook read and write permission on it.

## Link a repository <a href="#link-a-repository" id="link-a-repository"></a>

1. In Code, open **Repositories**.
2. Select the dropdown next to **Create repository**, and then select **Link repository**.
3. Select **Connector**, and then select a GitHub connector. The connector panel is limited to the scope you are in (Account, Organization, or Project), and lists GitHub connectors only.
4. If you selected an account-level connector, Harness lists the repositories that connector can see. Select **Repository on Git provider** to choose the repository to link. Harness fills **Name** from the last segment of the provider path.
5. Enter a **Name** for the Harness repository. Names can contain letters, numbers, dashes, dots, and underscores.
6. Optionally, enter a **Description**.
7. Select **Link repository**.

While the request is in flight, the button label changes to **Linking repository…**. On success, you return to the repository list, where the row shows **Linking…** until the initial copy finishes. When it finishes, the row shows a **Linked** badge.

The link form does not include a public-access toggle. New linked repositories are private.

{% hint style="info" %}
Harness registers a webhook on the source repository before it creates the Harness repository. If registration fails, no Harness repository is created. Go to [Troubleshooting](#troubleshooting) for the two most common errors. This webhook is also what drives the branch sync described in [Sync a branch](#sync-a-branch).
{% endhint %}

**What Harness copies:** The initial copy brings in `refs/heads/*` and `refs/tags/*`. It does not import issues, wikis, or branch rules. Harness mirrors pull requests and status checks separately. Go to [Pull requests and status checks](#pull-requests-and-status-checks). The copy job times out after 45 minutes and does not retry. The same repository count and storage limits apply as for any other repository you create.

## Sync a branch <a href="#sync-a-branch" id="sync-a-branch"></a>

On a linked repository, Harness shows:

* A **Linked** badge next to the repository name.
* An information banner: "This repository is linked from an external source. Content is synced automatically and cannot be edited directly."
* A **Sync now** icon on that banner, when you are viewing a branch. **Sync now** requires **Push** on the Harness repository, and syncs only the branch you are viewing. The icon is hidden when you are viewing a tag.

A push on the source repository triggers a sync for that branch through the webhook Harness registered when you linked the repository. A background job also refreshes branches and tags across up to 1,000 linked repositories every 4 hours, as a fallback for syncs the webhook misses.

Selecting **Sync now** shows a success toast, "Sync started successfully", or a failure toast, "Failed to start sync", with the Harness error message.

Keyword search is indexed after the initial copy, and again whenever a sync updates the default branch.

## Pull requests and status checks <a href="#pull-requests-and-status-checks" id="pull-requests-and-status-checks"></a>

Harness Code mirrors pull requests opened on the provider into the linked repository, so you can see them in the **Pull Requests** tab. It also copies the pull request refs and recomputes the merge base when the source or target commits change.

Harness Code also imports status checks reported through GitHub check runs and commit statuses, and shows them on the pull request. GitHub results map to Harness Code check statuses as follows:

| GitHub result                                          | Harness Code status |
| ------------------------------------------------------ | ------------------- |
| `success`, `neutral`, `skipped`                        | Success             |
| `failure`, `timed_out`, `action_required`, `cancelled` | Failure             |
| `startup_failure`, `error`                             | Error               |
| `pending`, `stale`, `queued`                           | Pending             |
| `in_progress`                                          | Running             |

Checks that arrive without a commit SHA, identifier, or link are skipped.

{% hint style="info" %}
Pull request and status check synchronization is enabled per account. If pull requests or checks from GitHub do not appear, contact [Harness Support](mailto:support@harness.io) to enable it.
{% endhint %}

## What stays read-only <a href="#what-stays-read-only" id="what-stays-read-only"></a>

A linked repository mirrors its source. Harness rejects the following actions:

| Action                                 | Result                                                                        |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| `git push` to the Harness repository   | Rejected: "Push not allowed to a linked repository."                          |
| Create a pull request in it            | Rejected: "Pull request creation is not allowed in a linked repository."      |
| Fork it                                | Rejected: "A linked repository can't be forked."                              |
| Edit the description                   | Rejected. The description mirrors the source repository and cannot be edited. |
| Change branches, tags, files, or rules | Rejected: "Changes are not allowed to a linked repository."                   |

You can still:

* View and clone the repository.
* Change public access, if your scope allows public repositories and you have **Edit** permission.
* Delete the Harness repository, if you have **Delete** permission.

## Remove a linked repository <a href="#remove-a-linked-repository" id="remove-a-linked-repository"></a>

Delete the Harness repository to remove the linked copy. Deleting the Harness repository does not delete or change the source repository on the external provider, and does not remove the webhook Harness registered on it, the same as deleting a Harness trigger does not remove its source webhook.

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Link repository is missing from the Create repository menu</summary>

**Link repository** is not yet enabled for your account.

</details>

<details>

<summary>Failed to use connector to access the remote repository</summary>

The connector cannot clone the source repository. Confirm the connector's credentials and URL are correct and still have read access to the repository. For account-level connectors, confirm that you selected a repository. For repository-level connectors, do not specify a separate repository.

</details>

<details>

<summary>Failed to register webhook for the linked repository</summary>

The connector's token does not have webhook read and write permission on the target repository. Update the token's permissions on the source provider, then try again.

</details>

<details>

<summary>The repository list still shows Linking… for a large repository</summary>

The initial copy can take time for a large repository. The copy job times out after 45 minutes and does not retry. If the row still shows **Linking…** after that, link the repository again.

</details>

## Next steps <a href="#next-steps" id="next-steps"></a>

* [Import repositories](https://developer.harness.io/code-repository/use-harness-code/manage-repositories/import-repo.md)
* [Mirror repositories](https://developer.harness.io/code-repository/use-harness-code/manage-repositories/mirror.md)

{% @harness-feedback/feedback module="code-repository" pagePath="code-repository/use-harness-code/manage-repositories/link-repo" %}

[^1]: On by default, ready for production use and rolling out to every Harness environment incrementally. If you want it before it reaches your environment, request access and Harness will turn it on for your account. Rollout happens in stages, so a feature can reach some environments a week or two before others. Harness can also turn it off via the same **Request access** process for your account if you need it off.
