> ## 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.

# Building a Plugin

> How customers install your plugin, and how your service acts on their repositories.

An Entire plugin is your service, acting on the repositories a customer chose to share with it. A customer installs your plugin on one of their Entire projects and picks the repositories it may reach. Entire then sends the customer back to you with a signed install receipt. Keep the installation ID as your durable identifier. Background work needs no customer password or long-lived installation bearer: sign a short JWT with your own key and exchange it for an access token that lasts about 45 minutes. The optional [user OAuth flow](https://docs.entire.com/guides/api/plugins/user-oauth-flow.md) has its own refresh tokens.

A plugin registered for it can also create repositories in the customer's project. Each new repository joins the installation; [provisioning and grant reconciliation](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md#wait-for-provisioning) may still need to finish before you can use it.

Build using our [Go SDK](https://docs.entire.com/guides/api/plugins/go-sdk.md) or call the APIs directly. These guides explain the requests and responses for either approach.

> [!NOTE]
>
> Plugins are currently available to selected partners only. If you want to build one, talk to your Entire contact first.
>
> The plugin system and the SDK package are in early access. Check each endpoint's version and Experimental notice for contract guidance. Field names in this guide are stable unless marked otherwise.

## Find the right guide

These guides are for building an Entire service integration. To connect an existing CI integration, see [Continuous Integration](https://docs.entire.com/guides/ci/overview.md). For executable extensions to the local CLI, see [`entire plugin`](https://docs.entire.com/cli-reference/plugin).

Use the shared [API Reference](https://docs.entire.com/guides/api/getting-started.md) for endpoint schemas, [Authentication](https://docs.entire.com/guides/api/authentication.md) for accepted credentials, and [Regions and routing](https://docs.entire.com/guides/api/regions-and-routing.md) for hosts.

The API Reference groups each endpoint once by resource. For example, [trail comments](https://docs.entire.com/guides/api/plugins/trail-comments.md) links to the canonical [create discussion endpoint](https://docs.entire.com/api-reference/trails/trail-discussions/start-a-new-discussion-repo_id-addressing.md), with plugin permissions and ownership restrictions explained in the guide.

## Who can use each API?

Each endpoint has its own audience. The [Plugin APIs](https://docs.entire.com/guides/api/plugins/apis.md) page lists endpoints explicitly tagged for plugin use as service annotations become available, including APIs shared with account callers. Building a plugin also involves account management calls:

| Audience | Who calls it | Example |
| :- | :- | :- |
| Users | Your own account, including supported service accounts. | [List your projects](https://docs.entire.com/api-reference/control-plane/projects/list-projects-accessible-to-the-caller-or-one-by-name.md) before managing a customer installation. |
| Plugins | Your registered plugin, using the credential accepted by that operation. | [Mint an installation token](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md#mint-an-access-token) with a plugin JWT for background work. |

An endpoint that supports both contexts shows both badges. For example, [create a repository](https://docs.entire.com/api-reference/control-plane/repos/create-repository.md) under your own account or through the [plugin create flow](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md#create-a-repository), with the permissions and scope required for that context.

Read the endpoint's **Accepted credentials** details to choose a User token, Plugin JWT, Plugin installation token or Plugin OAuth user token. An audience label does not grant access: permissions, customer acceptance, installation scope and ownership checks still apply. See the [authentication legend](https://docs.entire.com/guides/api/authentication.md#read-endpoint-labels) for the credential distinctions.

## Steps

1. [Register your plugin](https://docs.entire.com/guides/api/plugins/register.md) with Entire.
2. [Send customers through the install flow](https://docs.entire.com/guides/api/plugins/install-flow.md) and verify the receipt.
3. [Access repositories](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md): list an installation's repositories, mint access tokens, clone or read files and, if you need to, create repositories.
4. [Receive webhooks](https://docs.entire.com/guides/api/plugins/webhooks.md) when installations, refs or trails change.
5. [Report checks](https://docs.entire.com/guides/api/plugins/report-checks.md), [comment on trails](https://docs.entire.com/guides/api/plugins/trail-comments.md), [report findings](https://docs.entire.com/guides/api/plugins/trail-findings.md) or [report deployments](https://docs.entire.com/guides/api/plugins/deployments.md), depending on what your plugin does.

If your plugin also needs to know which installations and repositories a user can access, add [user sign-in with OAuth](https://docs.entire.com/guides/api/plugins/user-oauth-flow.md). Background work doesn't need it.

## Concepts

| Term | Meaning |
| :- | :- |
| Plugin | Your service, registered with Entire under a **slug** such as `acme-ci`. |
| Installation | One customer project that installed your plugin, with the repositories the customer selected: all of the project's repositories, or a list. Identified by an ID such as `ins_01M4...`. |
| Install receipt | A JWT that Entire signs and returns to your post-install URL. It identifies the installation at the time the receipt was issued; it does not prove ongoing access. |
| Plugin JWT | A short JWT your service signs with its Ed25519 key. You send it to Entire to list repositories and to mint access tokens. |
| Access token | A bearer token Entire mints for an installation. It carries the permissions you ask for, out of those registered and accepted by the customer for that installation, such as reading repositories or commenting on trails. It lasts about 45 minutes. |
| Core | Entire's control plane. One runs in each jurisdiction, such as `https://us.auth.entire.io`. Any Core serves any installation. |
| Region | Where a repository's data lives. Repository calls go to the API host of the repository's processing primary region. |

## Security checklist

* Keep the private key in a secret store or KMS, never in source control or images.
* Tie every install state to the browser session that started it, and verify every receipt fully before you store anything.
* Request the narrowest token that does the job: one repository, fewest permissions.
* Never log tokens, JWTs or receipts.
* Treat a 404 for an installation or repository as revoked access, and stop.
* Keep tokens out of URLs, command lines and files a build can read.
