> 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/internal-developer-portal/use-idp/git-experience/convert-inline-to-remote.md).

# Convert inline entities to remote

Convert Harness IDP inline Catalog entities and Workflows to remote Git-backed entities

Inline entities store YAML in the Harness database. Remote entities store YAML in your Git repository and use Git Experience for bi-directional sync. Use this guide when you need to move existing inline Catalog entities or Workflows to Git.

{% hint style="info" %}
**One entity per YAML file**

Each remote entity must use its own YAML file. Go to [Catalog YAML](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/catalog-yaml.md) for the Harness-native entity schema.
{% endhint %}

***

## What you will learn from this topic

* **Inline vs remote:** When entity YAML lives in Harness versus Git.
* **Convert in the UI:** Move one entity to Git from the Edit page.
* **Convert with the API:** Call Move Entity with `INLINE_TO_REMOTE` for a single entity.
* **Convert in bulk:** Run a script that lists entities and calls the same API for each one.

***

## Before you begin

* **Git connector:** A connector for the target repository. Go to [Git Experience for Harness IDP](https://developer.harness.io/internal-developer-portal/use-idp/git-experience/gitx-journey.md) for supported providers.
* **Repository and branch:** The repo and branch where entity YAML files will be written.
* **Permissions:** IDP Catalog Create/Edit (and Workflow Create/Edit when converting Workflows). For API or script conversion, use an API key with those permissions.
* **Tools (API and script):** `curl` and `jq` on the machine that runs the requests.

Go to [Git Experience for Harness IDP](https://developer.harness.io/internal-developer-portal/use-idp/git-experience/gitx-journey.md) for how remote entities sync after conversion.

***

## Convert with the UI

Convert one entity at a time from the entity **Edit** page.

1. Open the inline entity in the Software Catalog or Workflows view.
2. Open **Edit**.
3. Configure Git settings: connector, repository, branch, and YAML file path.
4. Save. Harness moves the entity YAML to Git and enables Git-based tracking.

{% embed url="<https://app.arcade.software/share/WfHVDUmMfoY4pL8hJWId>" %}

***

## Convert one entity with the Move Entity API

Use the [Move an Entity](https://apidocs.harness.io/entities/move-entity) API to convert a single inline entity to remote.

**Endpoint:**

```bash
POST /v1/entities/move/{scope}/{kind}/{identifier}
```

**Example request:**

```bash
curl -s -X POST \
  "https://app.harness.io/v1/entities/move/account.org.proj/component/my_service" \
  -H "Harness-Account: ${HARNESS_ACCOUNT}" \
  -H "x-api-key: ${X_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "git_details": {
      "branch_name": "main",
      "repo_name": "my-idp-repo",
      "connector_ref": "account.my_git_connector",
      "file_path": ".harness/idp/component/my_service.yaml"
    },
    "entity_move_operation_type": "INLINE_TO_REMOTE"
  }'
```

Replace `scope` with `account`, `account.orgId`, or `account.orgId.projectId` as appropriate. Set `kind` to the entity kind (for example `component`, `api`, `resource`, or `workflow`).

***

## Convert in bulk with a script

For larger migrations, use the following script. It lists entities with `GET /v1/entities`, builds a scoped file path under `.harness/idp`, and calls Move Entity with `INLINE_TO_REMOTE` for each entity.

{% hint style="info" %}
**Prerequisites**

Set `HARNESS_ACCOUNT`, `X_API_KEY`, `CONNECTOR_REF`, `REPO_NAME`, and `BRANCH_NAME` before you run the script. Adjust `KIND` for the entity kinds you want to convert (comma-separated values are supported).
{% endhint %}

{% code title="inline-to-remote-bulk.sh" overflow="wrap" %}

```bash
#!/bin/bash

# API Call details (UPDATE REQUIRED)
API_BASE_URL="https://app.harness.io"  # Can also be yourcompany.harness.io if you have vanity URL
HARNESS_ACCOUNT="{HARNESS_ACCOUNT}"   # Harness Account ID
X_API_KEY="{X_API_KEY}"               # API Key with IDP Catalog Create/Edit permissions

# Git Details (UPDATE REQUIRED)
CONNECTOR_REF="${CONNECTOR_REF}"       # e.g. account.connector_id
REPO_NAME="${REPO_NAME}"
BRANCH_NAME="${BRANCH_NAME}"

# Multiple kinds can be provided as comma-separated values
# Example: component,api,resource,workflow
KIND="component"

BASE_FILE_PATH=".harness/idp"

PAGE_SIZE=10
PAGE=0
HAS_MORE=true

while [ "$HAS_MORE" = true ]; do
  echo "Fetching page: $PAGE"

  response=$(curl -s -X GET \
    "$API_BASE_URL/v1/entities?kind=$KIND&limit=$PAGE_SIZE&page=$PAGE" \
    -H "Harness-Account: $HARNESS_ACCOUNT" \
    -H "x-api-key: $X_API_KEY" \
    -H "Content-Type: application/json")

  entities=$(echo "$response")

  if [ -z "$entities" ]; then
    echo "No more entities found."
    break
  fi

  echo "$entities" | jq -c '.[]' | while read -r entity; do
    entity_ref=$(echo "$entity" | jq -r '.entity_ref')

    # Example: service:account.org.proj/identifier
    kind=$(echo "$entity_ref" | cut -d':' -f1)
    ref_part=$(echo "$entity_ref" | cut -d':' -f2)

    identifier=$(echo "$ref_part" | awk -F'/' '{print $2}')
    scope_part=$(echo "$ref_part" | awk -F'/' '{print $1}')

    IFS='.' read -r account orgIdentifier projectIdentifier <<< "$scope_part"

    echo "Processing entity:"
    echo "  Identifier: $identifier"
    echo "  Kind: $kind"
    echo "  OrgIdentifier: $orgIdentifier"
    echo "  ProjectIdentifier: $projectIdentifier"

    if [[ -z "$orgIdentifier" && -z "$projectIdentifier" ]]; then
      # Account scope
      filepath="$BASE_FILE_PATH/$kind/${identifier}.yaml"
    elif [[ -n "$orgIdentifier" && -z "$projectIdentifier" ]]; then
      # Org scope
      filepath="$BASE_FILE_PATH/$kind/orgs/${orgIdentifier}/${identifier}.yaml"
    else
      # Project scope
      filepath="$BASE_FILE_PATH/$kind/orgs/${orgIdentifier}/projects/${projectIdentifier}/${identifier}.yaml"
    fi

    echo "File path: $filepath"

    json_payload=$(jq -n \
      --arg branch "$BRANCH_NAME" \
      --arg repo "$REPO_NAME" \
      --arg connector "$CONNECTOR_REF" \
      --arg path "$filepath" \
      '{
        git_details: {
          branch_name: $branch,
          repo_name: $repo,
          connector_ref: $connector,
          file_path: $path
        },
        entity_move_operation_type: "INLINE_TO_REMOTE"
      }')

    move_entity_response=$(curl -s -X POST \
      "$API_BASE_URL/v1/entities/move/$scope_part/$kind/$identifier" \
      -H "Harness-Account: $HARNESS_ACCOUNT" \
      -H "x-api-key: $X_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$json_payload")

    status=$(echo "$move_entity_response" | jq -r '.status')

    if [[ "ERROR" == "$status" ]]; then
      echo "$move_entity_response"
    else
      echo "Entity moved successfully: $entity_ref"
    fi

    echo "-----------------------------------------------------------------------------"
  done

  entity_count=$(echo "$entities" | jq -c '. | length')

  if [ "$entity_count" -lt "$PAGE_SIZE" ]; then
    echo "Last page reached"
    HAS_MORE=false
  else
    PAGE=$((PAGE + 1))
  fi
done
```

{% endcode %}

The script:

1. Retrieves entities with `GET /v1/entities`.
2. Iterates over the returned entities.
3. Determines entity scope from `entity_ref`.
4. Constructs a Git file path under `.harness/idp`.
5. Calls `POST /v1/entities/move/{scope}/{kind}/{identifier}` with `entity_move_operation_type: "INLINE_TO_REMOTE"`.

***

## Next steps

* [Git Experience for Harness IDP](https://developer.harness.io/internal-developer-portal/use-idp/git-experience/gitx-journey.md): Configure bi-directional sync and branch workflows after conversion.
* [Move an Entity API](https://apidocs.harness.io/entities/move-entity): Review request fields for single-entity conversion.
* [Catalog YAML](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/catalog-yaml.md): Confirm the Harness-native YAML shape written to Git.
