Report deployments

A plugin registered with deployments:write can report the resources it deployed for a commit, such as a preview site, with their status and links. Entire attaches them to the commit’s Change, whose detail lists them with a ready count, such as 3 of 4 ready. The Deployments section on entire.com is still being built. The Deployments API only reports deployments: it doesn’t create them, and it never blocks a merge.

Deployments are on Entire’s v0 API. Field names may change before the contract is final.

What you need

deployments:write, on your plugin’s installation token. Ask Entire to add it when you register your plugin. It grants nothing else. checks:write, contents permissions and user tokens don’t grant it.
The project’s acceptance. Adding the permission to your plugin doesn’t grant it to existing installations. It stays pending until a project manager accepts it. Until then, writes for that project’s repositories answer 403, so keep reporting there through check runs or trail comments.

Send every call below to the repository’s api_base_url, under /api/v0 rather than /api/v1, with the installation’s access token as bearer token. Use the public repo_… repository ID and the full 40- or 64-character commit SHA. The Go SDK does the minting and routing for you.

Report a resource

POST /api/v0/repos/{repo_id}/commits/{sha}/deployments
Authorization: Bearer {access token}
Content-Type: application/json

{
  "branch": "feature-x",
  "deployments": [{
    "key": "preview-site",
    "name": "Preview site",
    "status": "completed",
    "conclusion": "success",
    "environment_url": "https://preview.example.com",
    "external_updated_at": "2026-10-24T09:12:00Z"
  }]
}

Set external_updated_at to when the state changed on your side, in UTC, not to when you send the request. Keep each resource’s key the same across updates and across commits.

Field	Required	Notes
`branch`	Yes	The branch name, without `refs/heads/`.
`deployments`	Yes	1 to 1,000 resources, each with a different `key`. The body is limited to 1 MiB.
`key`	Yes	Your stable ID for the resource, up to 255 characters. Keys are per plugin: another plugin’s `preview-site` is a different resource.
`name`	Yes	Shown on the Change, up to 255 characters.
`status`	Yes	`queued`, `in_progress`, `completed` or `inactive`. See Keep it current.
`conclusion`	With `completed`	`success`, `failure`, `cancelled` or `skipped`. Omit it for every other status.
`external_updated_at`	Yes	UTC, no more than 60 seconds in the future.
`environment`	No	Defaults to `preview`, the only environment Entire documents in v0. Other values, up to 64 characters, are stored and returned but treated the same way.
`environment_url`	No	The deployed resource, as an `https` URL without credentials, up to 2,048 bytes.
`logs_url`	No	The deployment’s logs, with the same rules.
`type`	No	A free-form kind, such as `site` or `function`, up to 64 characters.
`group`	No	`{"key": "...", "name": "..."}`, both required, to show related resources under one heading.
`started_at`, `completed_at`	No	UTC. `completed_at` can’t be before `started_at`.
`deadline_at`	No	UTC, at most 24 hours ahead. A queued or in-progress resource past its deadline is marked stale.

The response has one result per resource, in request order:

{"results": [{"deployment": {"id": "...", "key": "preview-site", "status": "completed", "conclusion": "success"}, "outcome": "created"}]}

outcome is created, updated, unchanged or ignored_stale. deployment is the stored state, whether or not your write applied.

Keep it current

Report queued, then in_progress, then completed with a conclusion.
Report inactive when you remove the deployed resource, such as a torn-down preview, and omit conclusion, so its links stop being offered.
Retries are safe. Entire orders writes by external_updated_at, so an older report never overwrites a newer one. At an equal time, a write never moves a resource back to an earlier status, so a late retry can’t revive a torn-down preview. Reuse the same external_updated_at when you retry.
Report each commit you deploy. A Change shows only the deployments on its head commit, never an earlier commit’s.

Deployments never gate a merge. If you use check runs for merge gating, keep publishing them separately. Using the same key for a check and a deployment is a convention, not a link Entire makes.

Read your reports

GET on the same URL returns your plugin’s current report for each key on that commit, ordered by key. It returns only your plugin’s deployments:

{"deployments": [{"id": "...", "plugin": "acme-previews", "key": "preview-site", "name": "Preview site", "environment": "preview", "status": "completed", "conclusion": "success", ...}], "next_cursor": "..."}

Pass ?per_page= (1 to 100, default 30). While the response has a next_cursor, pass it back unchanged as ?cursor= for the next page.

Errors

Errors are application/problem+json. Branch on code, not on the status.

Status	`code`	Meaning	Retry?
`401`	`unauthenticated`	The token is missing or invalid.	After minting a new token.
`403`	`forbidden`	The token lacks `deployments:write`, or the project hasn’t accepted it.	No.
`403`	`repo_not_covered`	The installation doesn’t cover this repository.	No.
`409`	`wrong_cell`	The repository moved to another region.	Yes, at its new `api_base_url`.
`409`	`deployment_owner_conflict`	Another live installation of your plugin owns a key in the batch.	No.
`413`	`request_too_large`	The body is over 1 MiB.	Split the batch.
`422`	`validation_error`	The body, SHA, `per_page` or `cursor` is invalid. `detail` says which.	No.
`503`	`service_unavailable`	Deployment storage is unreachable.	Yes, with backoff.

With the Go SDK

Add Deployments: plugin.Write to Config.Permissions, matching your registration. inst.Deployments then reports and reads deployments:

func reportPreview(ctx context.Context, inst *plugin.Installation, repoID, sha, branch, url string, deployedAt time.Time) error {
	_, err := inst.Deployments.Upsert(ctx, repoID, sha, plugin.DeploymentsRequest{
		Branch: branch,
		Deployments: []plugin.Deployment{{
			Key:               "preview-site",
			Name:              "Preview site",
			Status:            plugin.Completed,
			Conclusion:        plugin.Success,
			EnvironmentURL:    url,
			ExternalUpdatedAt: deployedAt,
		}},
	})
	return err
}

The SDK validates a write as Entire does before sending it, sends it to the repository’s region, retries it with the same body, and follows a repository that moved to another region. Report a removed resource with Status: plugin.Inactive. inst.Deployments.List returns one page of your current reports, and inst.Deployments.All iterates over all of them. A refusal is an *entire.HTTPError: check it with entire.HasCode, for example entire.HasCode(err, entire.CodeForbidden) for a project that hasn’t accepted deployments:write yet.

Documentation

Accounts and projects

Git

Trails

Sessions and checkpoints

Webhooks

Report deployments

What you need

Report a resource

Keep it current

Read your reports

Errors

With the Go SDK

​What you need

​Report a resource

​Keep it current

​Read your reports

​Errors

​With the Go SDK

What you need

Report a resource

Keep it current

Read your reports

Errors

With the Go SDK