> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Access repositories

> List an installation's repositories, mint access tokens for them, clone them or read commits and files, and create new ones.

This guide uses your [plugin JWT](https://docs.entire.com/guides/api/authentication.md#plugin-jwts) to list repositories and mint a Plugin installation token on Core. Use the installation token for repository work at the [repository's region](https://docs.entire.com/guides/api/regions-and-routing.md), or for [creating a repository](#create-a-repository) on Core. Read each endpoint's **Accepted credentials** details for supported alternatives.

## List repositories

```http theme={null}
GET https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/repositories
Authorization: Bearer {plugin JWT}
```

The response lists the installation's repositories that have a processing primary. New repositories may be absent during provisioning, but they can also appear before provisioning or grants are ready. List membership and primary metadata are discovery information, not a readiness check:

```json theme={null}
{
  "repositories": [{
    "id": "repo_01M3...",
    "full_name": "acme/api",
    "path": "/et/acme/api",
    "clone_url": "https://aws-us-east-2.entire.io/et/acme/api.git",
    "entire_clone_url": "entire://aws-us-east-2.entire.io/et/acme/api",
    "placements": [
      {"region": "aws-us-east-2", "role": "processing_primary",
       "api_base_url": "https://aws-us-east-2.api.entire.io"},
      {"region": "aws-eu-central-1", "role": "mirror"}
    ]
  }],
  "next_cursor": null
}
```

Store a repository's `id`, which never changes. Names and hosts can change, so list the repositories again rather than caching them for long. Customers can change the selection without notice. Use this list for coverage and routing discovery; token minting and each resource operation still enforce current grants and scope.

`path` is the repository's web path, also sent as `repository.path` on ref events. Native repositories use `/et/{project}/{repository}`; mirrors use `/gh/{owner}/{repository}`. `/et/acme/api` and `/gh/acme/api` can both exist and are different repositories. Use `path` for web links and `id` as your key. Older responses may omit `path`.

Send repository API calls to the placement whose role is `processing_primary`, using its `api_base_url`. Ignore placement roles you don't know. This endpoint returns one page; `next_cursor` is always `null`.

## Mint an access token

```http theme={null}
POST https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/access-tokens
Authorization: Bearer {plugin JWT}
Content-Type: application/json

{"repository_id": "repo_01M3...", "permissions": {"contents": "read"}}
```

A successful mint answers `201`:

```json theme={null}
{"token": "...", "username": "x-access-token", "expires_at": "2026-10-13T20:37:23Z", "permissions": {"contents": "read", "installations": "read"}}
```

Prefer a token scoped to one repository. See [Access tokens](https://docs.entire.com/guides/api/authentication.md#access-tokens) for what each combination of repository and permissions reaches.

## Errors

| Status and code | Meaning | What to do |
| :- | :- | :- |
| `401 unauthorized` | Entire could not verify your plugin JWT: wrong key, issuer, audience or times. | Check the [claims table](https://docs.entire.com/guides/api/authentication.md#plugin-jwts) and your server clock. |
| `404 not_found` | The installation is gone, or the repository is not in it. | Stop acting for it. List the repositories again. |
| `400 unsupported_permission` | You asked for a permission you did not register. | Request only registered permissions. |
| `400 invalid_request` | You asked for `repositories:create` with a `repository_id`. | Mint a create token without a repository. |
| `400 repository_required` | You named no repository, and the permissions are not every accepted permission, only `repositories:create`, or only `installations:read`. | Name a `repository_id`, or request one of those whole-installation sets. |
| `403 permission_not_accepted` | You requested a registered permission this installation has not accepted. | Ask a customer project manager to accept the updated permissions through the install consent flow. |
| `409 coverage_changed` | Repository coverage or grants changed during the mint, or grant reconciliation is incomplete. | Refresh discovery and retry the mint with backoff. If it persists, ask your Entire contact to investigate the grants. |
| `429 rate_limited` | Too many mints for this installation. | Wait for `Retry-After`, in seconds, and cache tokens until shortly before they expire. |
| `403 forbidden` | Entire refused to issue the token. | Don't retry in a loop. If it persists, ask your Entire contact. |
| `503` | A required service is unavailable. | Retry with backoff; investigate persistent failures. |

Error bodies are RFC 9457 problem documents, with a machine-readable `code` member.

## Clone a repository

Install `git-remote-entire` on the machine that will clone. It doesn't need the Entire CLI. Download the current stable release, check it, and put `git-remote-entire` on `PATH`:

```bash theme={null}
curl -fsSLO https://install.entire.com/latest/git-remote-entire-linux-amd64.tar.gz
curl -fsSLO https://install.entire.com/latest/checksums.txt
sha256sum --ignore-missing -c checksums.txt
tar -xzf git-remote-entire-linux-amd64.tar.gz git-remote-entire
```

Archives are named `git-remote-entire-<os>-<arch>.tar.gz` (`.zip` on Windows) for `linux`, `darwin` and `windows` on `amd64` and `arm64`. `/latest/` redirects to the current stable release. For a reproducible build, download from `https://install.entire.com/v<version>/` instead. For up to a minute after a release, the two `/latest/` links can point at different releases, so retry a checksum failure. The [Entire CLI](https://docs.entire.com/installation.md) also includes the helper.

Mint a `contents:read` token for the repository and set it as `ENTIRE_TOKEN` for the Git process. `ENTIRE_TOKEN` overrides the helper's bearer credential. Pass the repository's `entire_clone_url`, unchanged, to `git clone`:

```bash theme={null}
ENTIRE_TOKEN="$TOKEN" git clone "$ENTIRE_CLONE_URL" checkout
```

Here `$TOKEN` and `$ENTIRE_CLONE_URL` are shell variables holding the minted token and the returned URL.

For a native repository, the URL might be `entire://aws-us-east-2.entire.io/et/acme/api`. A mirror might return `entire://aws-us-east-2.entire.io/gh/acme/api`. Accept both. Don't construct the URL from `full_name`, or replace `/gh/` with `/et/`.

Keep the token out of logs, command arguments and Git configuration. Give untrusted code, such as a customer's build, only a token you minted for its repository with `repository_id`. Use `expires_at` to renew the token before later fetches.

Use the returned `entire_clone_url` with `git-remote-entire` for this workflow.

To push to a native repository, your plugin must be registered for `contents:write`, and the token must request it. You can't push to a mirror through Entire. Reading a mirror and [reporting checks](https://docs.entire.com/guides/api/plugins/report-checks.md) use the same APIs as a native repository.

The [Go SDK](https://docs.entire.com/guides/api/plugins/go-sdk.md#clone-with-git) can prepare the helper's environment for you, but it uses the installation's token, which reaches every repository in the installation. Use it only where you trust Git as much as your plugin. For an untrusted build, mint a repository token with the SDK's `RepositoryToken` and set `ENTIRE_TOKEN` yourself.

## Read a commit or file

For a small read, you don't need to clone. Send these requests to the repository's `api_base_url` with a `contents:read` token:

```http theme={null}
GET {api_base_url}/api/v1/repos/{repo_id}/commits/{sha}
Authorization: Bearer {access token}
```

Use the repository's `id` from the list and a full 40- or 64-character commit SHA. The response includes `commit_sha`, `branches`, `default_branch` and a `commit` object with the message, author and nullable changed-file counts.

```http theme={null}
GET {api_base_url}/api/v1/repos/{repo_id}/raw?ref={ref}&path={path}
Authorization: Bearer {access token}
```

URL-encode both query values. `ref` can be a SHA, branch or tag; `HEAD` reads the default branch. `path` is relative to the repository root. The response streams the whole file. It is always `text/plain` and sent as an attachment, whatever the file holds, so decide how to read it from its path, not its `Content-Type`. Compare the received byte count with the `Entire-Size` header to detect an interrupted transfer; retry an incomplete read. Clone instead if you need many files.

An unknown ref or file path answers `404`, as does a path that names a directory. To list a directory, use `GET {api_base_url}/api/v1/repos/{repo_id}/tree?ref={ref}&path={path}`. A token with only `checks:write` cannot read repository contents.

Both raw and tree reads return `404` for refs in the reserved `entire/` namespace, including fully qualified names such as `refs/heads/entire/checkpoints/v1`.

## Create a repository

A plugin registered with `repositories:create` can create repositories in the installation's project once the customer has accepted that permission. The customer sees "Create repositories in this project" on the install page. The permission only creates: it doesn't read or write contents, delete repositories or change settings. To push to a repository you created, register `contents:write` too.

First mint a token with no `repository_id`:

```http theme={null}
POST https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/access-tokens
Authorization: Bearer {plugin JWT}
Content-Type: application/json

{"permissions": {"repositories": "create"}}
```

The response carries `"permissions": {"repositories": "create", "installations": "read"}`. The token reaches no repository. An installation-wide token also creates when it includes `repositories:create`. It must request every effective permission currently accepted by that installation, not pending catalog additions.

Then call the canonical [Create repository endpoint](https://docs.entire.com/api-reference/control-plane/repos/create-repository.md) on the same Core:

```http theme={null}
POST https://{core}/api/v1/repos
Authorization: Bearer {access token}
Content-Type: application/json

{"name": "api", "objectFormat": "sha1"}
```

`objectFormat` is optional: `sha1`, the default, or `sha256`. Leave out `projectId`, and Core uses the installation's project. Any other project answers `404`. Omit `clusterHost` and `mirrorClusterSlugs`; nonempty values are rejected for plugins.

A successful create answers `201` with the repository:

```json theme={null}
{"repositoryId": "repo_01M3...", "name": "api", "owningProjectId": "...", "state": "provisioning", ...}
```

Store `repositoryId` immediately. It is the `id` the repository list, access tokens and webhooks use. The new repository joins the installation, including a selected repository list, but `201` can still be returned when grant reconciliation fails. A subsequent [token mint](#mint-an-access-token) can return `409 coverage_changed` until those grants are repaired. Repository-added events are queued for covering installations; delivery also depends on their webhook configuration and processing.

### Wait for provisioning

The repository response’s `state: "active"` confirms completed repository provisioning. This is separate from an installation’s lifecycle state. If create returns `provisioning`, continue with the saved repository ID:

1. [List the installation's repositories](#list-repositories) until that ID has a `processing_primary` placement and `api_base_url`.
2. [Mint a repository-scoped token](#mint-an-access-token) for the permissions your next operation needs. For `409 coverage_changed`, refresh the repository list to check coverage, then retry minting with backoff. Ask your Entire contact to repair persistent grant reconciliation failures. For `403 permission_not_accepted`, have the customer accept the requested permission before retrying.
3. Call the repository API at the discovered URL. Handle that operation's errors separately from discovery and token minting.

Placement discovery provides the address; it does not confirm activation or grants. Keep the saved ID through discovery, minting and repository-operation failures. Repeat those steps as appropriate instead of repeating the non-idempotent create.

### Create errors

Core answers a refused create with an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document. Branch on its `type`, not on the status alone: `409` and `429` carry other conditions too.

| Status and `type` | Meaning | What to do |
| :- | :- | :- |
| `400` or `422` | The name or body is invalid, or placement fields contain prohibited nonempty values. Schema validation can return `422` before the handler runs. | Fix the request. |
| `401` | The token expired, or the customer uninstalled your plugin. | Mint a new token. Stop if the installation is gone. |
| `403` | The token lacks `repositories:create`. | Mint a token with `{"repositories": "create"}`. |
| `403` `https://entire.com/errors/plugins/installation-suspended` | The installation is suspended. | Stop creating until it is active again. |
| `404` | The project doesn't exist, or isn't the installation's project. | Leave out `projectId`. |
| `409` `https://entire.com/errors/repo/name-in-use` | The project already has a repository with that name. | Pick another name, or list the repositories to find the existing one. |
| `429` `https://entire.com/errors/repo/create-limit-reached` | The installation reached its create limit. | Wait for `Retry-After`, in seconds. |
| `503` | A required service or placement is unavailable. | Investigate persistent failures and reconcile any uncertain create result before retrying. |

A create is not idempotent. If the connection drops before you read the response, list the installation's repositories before you create again: a `409` can mean your own earlier create succeeded.

### Limits and ownership

By default, an installation can create 100 repositories in a rolling 24-hour period; the limit is configurable. To raise the limit, ask your Entire contact.

The customer's project owns every repository you create. The repositories stay when the customer uninstalls your plugin. The customer can remove one from the installation's selection like any other repository, and then you lose access to it.
