Register your plugin - Entire

Entire registers each plugin for you. Send your Entire contact the values below. You choose all of them except the slug, which Entire confirms, and the issuer and receipt audience, which follow from the slug.

Field	What to send	Example
Owning project	The name of the Entire project that owns your plugin. People who manage that project can manage the plugin.	`acme`
Slug	Lowercase letters, digits and single hyphens, at most 40 characters. It can’t change later.	`acme-ci`
Name, description	How your plugin appears to customers in Entire.	Acme CI, “Runs your tests on every push.”
Logo	A URL to an SVG or PNG of your mark with no wordmark. Use a transparent background and ideally a square shape. A PNG must be at least 256×256.	`https://ci.acme.example/logo.svg`
Issuer	The `iss` claim of your plugin JWTs. Always `urn:entire:plugin:{slug}`, so you don’t need to send it.	`urn:entire:plugin:acme-ci`
Receipt audience	The `aud` claim Entire puts in your install receipts. Always `urn:entire:plugin:{slug}`, so you don’t need to send it.	`urn:entire:plugin:acme-ci`
Permissions	`contents:read` to read repository contents, `contents:write` to read and push to them, `checks:write` to report check runs, `discussions:write` to comment on trails, `trails:read` or `trails:write` to read or change trails, `deployments:write` to report deployments such as preview sites, `repositories:create` to create repositories in the customer’s project. Trail events also need `contents:read`. Request only what you use. Only the `contents` permissions reach a repository’s Git data. The others, `repositories:create` included, grant no repository read or write, so a plugin that pushes to the repositories it creates also needs `contents:write`.	`contents:read`
Public keys	Either Ed25519 public keys in PEM form (up to 10, for rotation), or the URL of a JWKS you serve. Never send the private key.	PEM block
Install URL	Optional. HTTPS URL where Entire sends customers who start an install from Entire. It should begin your install flow.	`https://ci.acme.example/install`
Post-install URLs	HTTPS URLs that receive the customer after consent, up to 10. Entire compares them character for character.	`https://ci.acme.example/callback`
Webhook URL	Optional. HTTPS URL for event deliveries. Entire doesn’t follow redirects.	`https://ci.acme.example/webhook`
OAuth redirect URIs	Optional. HTTPS URLs that receive the user after OAuth sign-in, up to 10. Entire compares them character for character.	`https://ci.acme.example/oauth/callback`

To change your permissions later, ask your Entire contact. New installations get the new set right away. Existing installations get it when Entire updates them, and until then a mint that asks for a new permission answers 409 coverage_changed.

Make a key

Make a key with OpenSSL, and send the public half:

openssl genpkey -algorithm ed25519 -out plugin-key.pem
openssl pkey -in plugin-key.pem -pubout

Keep plugin-key.pem in your secret store. Anyone who holds it can act as your plugin on every installation. To rotate, send the new public key, deploy the new private key, then ask Entire to remove the old public key.

PEM keys are simplest. A JWKS URL suits you if you rotate keys often or keep keys in a KMS: your JWTs must then carry a kid header that names the key, and the SDK serves the JWKS for you with App.JWKSHandler.