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:
- An install token with
surfaces:write. See Build an app.
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. titleis optional.markdownshows with the same Markdown as a comment.buttonsis 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 frompull_request.head_shaof thepull_requestwebhook with the actionopenedorsynchronize.state:pending,successorfailure.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
httpsURL in a new tab. - Webhook button: sends your app an
app_cardwebhook with the actionclicked, the pull request, thebutton.idand the person insender. 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_cardwebhook.
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
| Limit | Value |
|---|---|
| Sections | 20 for each card |
| Markdown | 64 KB for each section |
| Buttons | 10 for each section |
| Files | 10 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:
| Route | What 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.