Comment on trails

A plugin registered with discussions:write can start a discussion on a trail, reply to one, and edit or delete its own messages. The usual pattern is one summary comment per trail that your plugin keeps current. For example, a deploy-preview plugin posts a table of preview URLs when a trail opens, and edits the same comment as each deployment finishes.

Trail comments are experimental. Field names may change before the contract is final.

What you need

discussions:write, to post and edit. Ask Entire to add it when you register your plugin. It grants nothing else: no read access to the repository, and no push.
contents:read, to list a trail’s discussions. You need it to find your comment again if you don’t store its IDs.

An access token scoped to the repository, with both permissions. Mint it with this body:

{"repository_id": "repo_01M3...", "permissions": {"contents": "read", "discussions": "write"}}

Send every call below to the repository’s api_base_url, under /api/v1, with the access token as bearer token. The Go SDK does the minting and routing for you.

Post the comment

Start a discussion on the trail:

POST /api/v1/repos/{repo_id}/trails/{number}/discussions
Content-Type: application/json

{"title": "Deploy previews", "body": "| App | Status |\n| :-- | :-- |\n| web | Building |"}

The title is optional, up to 512 characters. The body is required, up to 65,536 characters, and entire.com renders it as Markdown. A 201 returns the new discussion and its first message:

{"discussion": {"id": "...", "title": "Deploy previews", ...}, "message": {"id": "...", "body": "...", ...}}

Store discussion.id and message.id with the trail. You need both to edit the comment.

Keep it current

Edit the message whenever your state changes. The new body replaces the old one, so send all of it:

PATCH /api/v1/repos/{repo_id}/trails/{number}/discussions/{discussion_id}/messages/{message_id}
Content-Type: application/json

{"body": "| App | Status |\n| :-- | :-- |\n| web | [Ready](https://preview.acme.example) |"}

Edit the comment you already posted rather than posting a new one for each update. You can also reply in the discussion, and delete a message that no longer applies.

Find your comment again

If you lost the IDs, list the trail’s discussions with GET /api/v1/repos/{repo_id}/trails/{number}/discussions. While the response has a next_cursor, pass it back as ?cursor= for the next page. Yours is the one whose created_by_identity names your installation:

"created_by_identity": {
  "kind": "automation",
  "account_id": null,
  "automation": {"plugin": "acme-ci", "installation_id": "ins_01M4..."}
}

Then get the discussion for its messages. Each message’s identity has the same shape. Match on installation_id, not on author: for a plugin, author is an empty string and created_by is null.

Who can change your comment

A message belongs to the installation that posted it, not to the token. Any later token for the same installation can edit or delete it, so your comment stays editable for as long as the installation exists. Nobody else can. Another installation of your plugin, or a person, gets 404 for your messages, and entire.com doesn’t offer people an edit or delete option on them. Your plugin, in turn, can’t change anyone else’s messages. On entire.com, your messages appear under your slug in title case, followed by “(plugin)”: a plugin with the slug deploy-previews appears as “Deploy Previews (plugin)”.

Where your comment appears

A repository’s trail is a change on a project trail. Your comment belongs to that change, so open the change on entire.com to find it. The trail’s own discussions list shows only discussions on the project trail, so your comment isn’t there.

What discussions:write doesn’t cover

Resolving, reopening or retitling a discussion. These need contents:write.
Starting a review, which also needs contents:write.
Review comments and approvals.
Discussions on a project trail. Only trails on a repository accept plugin comments.
Reading discussions, which needs contents:read.

Errors

These are specific to discussions. For errors when minting the token, see Act for an installation.

Status and detail	Meaning
`403 no discussion write access to repo`	The token doesn’t carry `discussions:write` for this repository. Entire gives the same answer for a repository that doesn’t exist.
`403 no read access to repo`	You listed or read discussions without `contents:read`.
`403 no write access to repo`	You tried to resolve or retitle a discussion.
`403 automation principals cannot perform this action`	The trail belongs to a project, not a repository.
`404 Message not found`	The message is gone, or another installation or a person posted it.
`400`	The title or body is empty or too long. The `detail` names the limit.

With the Go SDK

Add Discussions: plugin.Write to Config.Permissions, matching your registration. inst.RepositoryClient then returns a client whose Trails methods post and edit comments. This keeps one summary comment per trail current, from a trail event:

func updateSummary(ctx context.Context, inst *plugin.Installation, change *plugin.TrailChange, summary string) error {
	client, repoID, err := inst.RepositoryClient(ctx, change.Repository.ID,
		plugin.Permissions{Contents: plugin.Read, Discussions: plugin.Write})
	if err != nil {
		return err
	}
	trail := int64(change.Trail.Number)
	comment, ok := loadComment(change.Trail.ID)
	if !ok {
		created, err := client.Trails.CreateDiscussion(ctx, repoID, trail,
			entire.DiscussionCreateRequest{Title: "Deploy previews", Body: summary})
		if err != nil {
			return err
		}
		return saveComment(change.Trail.ID, created.Data.ID, created.Data.Messages[0].ID)
	}
	_, err = client.Trails.UpdateMessage(ctx, repoID, trail, comment.DiscussionID, comment.MessageID,
		entire.MessageRequest{Body: summary})
	return err
}

loadComment and saveComment are your own functions. Key them on the trail’s ID, which never changes. To find a comment you didn’t store, range over client.Trails.ListDiscussionsAll and match CreatedByIdentity.Automation.InstallationID against inst.ID().

Documentation

Accounts and projects

Git

Trails

Sessions and checkpoints

Webhooks

Comment on trails

What you need

Post the comment

Keep it current

Find your comment again

Who can change your comment

Where your comment appears

What discussions:write doesn’t cover

Errors

With the Go SDK

​What you need

​Post the comment

​Keep it current

​Find your comment again

​Who can change your comment

​Where your comment appears

​What discussions:write doesn’t cover

​Errors

​With the Go SDK

What you need

Post the comment

Keep it current

Find your comment again

Who can change your comment

Where your comment appears

What discussions:write doesn’t cover

Errors

With the Go SDK