> ## 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. From that point your service holds an installation ID and nothing else: no customer passwords, no long-lived tokens. Whenever you need to act, you sign a short JWT with your own key and exchange it for an access token that lasts about 45 minutes.

A plugin registered for it can also create repositories in the customer's project. Each new repository joins the installation, so you act on it like any repository the customer selected.

Build on the [Go SDK](https://docs.entire.com/guides/api/plugins/go-sdk.md) if you can. It implements every step in this guide. The rest of the guide explains the flow so you know what the SDK does, and so you can implement it in another language.

> [!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. Install, receipts, repository lists, access tokens and check runs work in production today. Webhooks, trail comments, deployments and repository creation are rolling out, and their contracts may change. Field names in this guide are stable unless marked otherwise.

## 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. [Act for an installation](https://docs.entire.com/guides/api/plugins/act-for-an-installation.md): list its repositories, mint access tokens and, if you need to, create repositories.
4. [Sign users in with OAuth](https://docs.entire.com/guides/api/plugins/user-oauth-flow.md), if you need to know which installations and repositories a user can use.
5. [Build it with the Go SDK](https://docs.entire.com/guides/api/plugins/go-sdk.md), and [receive webhooks](https://docs.entire.com/guides/api/plugins/go-sdk.md#receive-events) when installations or refs change, and [trail events](https://docs.entire.com/guides/api/plugins/trail-events.md) when trails change.
6. [Comment on trails](https://docs.entire.com/guides/api/plugins/trail-comments.md) to report your results where people review the change.

## 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 proves the installation exists and carries its ID. |
| 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 you registered, 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.