Skip to content
Source
Sign inSign up

Show a card on pull requests

Skills, MCP and apps / Apps and webhooks

Show a card and a status on pull requests

Your app has a result for each pull request, such as a preview link, a package to try, or a list of problems. A bot comment gets lost in the timeline, and reviewers cannot tell if your check passed.

4 min read

Each installed app gets one card on each pull request, next to the CI cards on the Conversation tab. The card has Markdown sections, files and buttons, and an optional status for the head commit: pending, success or failure. A branch rule can make the merge wait for that status.

You need:

Only your app writes its own card.

1. Write a section

curl -X PUT "https://source.tanstack.com/api/v1/repos/alice/app/pulls/7/app-card/sections/preview" \
  -H "Authorization: Bearer $INSTALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Preview","markdown":"Try it: https://pr-7.example.com","buttons":[]}'
  • The last part of the path is the key of the section: a lowercase slug, a-z, digits and -, at most 40 characters.
  • title is optional. markdown shows with the same Markdown as a comment. buttons is required. Send [] for none.
  • A write with the same key replaces the section. The card shows the sections in the order of their first write.
  • DELETE .../app-card/sections/<key> deletes a section.

Each write answers with the whole card: its sections, files and status.

2. Set the status

curl -X PUT "https://source.tanstack.com/api/v1/repos/alice/app/pulls/7/app-card/status" \
  -H "Authorization: Bearer $INSTALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha":"9fceb02d0ae598e95dc970b74767f19372d61af8","state":"pending","text":"Building the preview"}'
  • sha: the full id of the head commit. Take it from pull_request.head_sha of the pull_request webhook with the action opened or synchronize.
  • state: pending, success or failure.
  • text: optional, at most 140 characters.

The status shows on the card, and as app:<slug> on the Checks tab. A status counts only for the commit that it names. After a push, the check shows No status on <commit> yet until you set a status for the new head.

3. Add a file

Send the bytes as the body, with a Content-Length:

curl -X PUT "https://source.tanstack.com/api/v1/repos/alice/app/pulls/7/app-card/files/report.html" \
  -H "Authorization: Bearer $INSTALL_TOKEN" \
  --data-binary @report.html
  • Each file shows on the card as a download link.
  • A file name has letters, digits, ., _ and -, at most 100 characters, and starts with a letter or a digit.
  • DELETE .../app-card/files/<name> deletes a file.

4. Add a button

A section has up to 10 buttons. Each button has an id (a lowercase slug, with the same rules as a key) and a label. There are two kinds:

{
  "title": "Preview",
  "markdown": "The preview is ready.",
  "buttons": [
    { "id": "open", "label": "Open the preview", "url": "https://pr-7.example.com" },
    { "id": "rebuild", "label": "Build again", "webhook": true }
  ]
}
  • URL button: opens an https URL in a new tab.
  • Webhook button: sends your app an app_card webhook with the action clicked, the pull request, the button.id and the person in sender. Every app gets it, with no pick. See Read the body.

Only people click a webhook button. The token of an agent is refused.

What works now

  • Your app writes its own card on each open pull request: sections, files and buttons.
  • It sets a pending, success or failure status for the head commit, which shows on the Checks tab.
  • A click of a person on a webhook button sends your app an app_card webhook.

What reviewers see

  • The card of each app on the Conversation tab, under the description, next to the CI cards.
  • The status of each app on the Checks tab, named app:<slug>.

Only people who can read the CI runs of the pull request (jobs:read) see the cards and the statuses.

To make a merge wait for an app, add app:<slug> to the required checks of a branch rule. A monorepo pull request has no single head commit, so a required app status stays pending there.

When the pull request closes

When the pull request closes or merges, the card loses its sections, its files and its status. After that, each write answers 422. A reopened pull request keeps its card closed.

Limits

LimitValue
Sections20 for each card
Markdown64 KB for each section
Buttons10 for each section
Files10 MB for each file, 50 MB for each card

The routes

All routes are under /api/v1/repos/<owner>/<repo>/pulls/<number>/app-card, with the install token:

RouteWhat it does
PUT /sections/<key>, DELETE /sections/<key>Set or delete a section.
PUT /files/<name>, DELETE /files/<name>Set or delete a file.
PUT /status ({ "sha", "state", "text" })Set the status for a commit.

A person clicks a webhook button over REST with POST /api/v1/repos/<owner>/<repo>/pulls/<number>/app-cards/<slug>/buttons/<button>/click, or with the MCP tool click_app_card_button.