Take an Update Locally

This page covers taking an update in your own checkout. Use it when your app is heavily customized and you want to resolve conflicts in your editor before anything lands on main. What an update changes, and what to check afterwards, is on Updates.

There are two steps on Stardeck, get and prepare, and no closing step. Once the merge reaches main, Stardeck sees the update's commit in main's history and records the update by itself.

RequirementsCopy Anchor Link

• A local checkout (GitHub Access, or get_repo_access from Work Across Every App).
• An org connection (Connect Your AI Tool) authorized at read & write, with a role that has agent:repos:write.
• A GitHub account with Write access on the repository, to open and merge the pull request. Your agent's token can push the update branch but can't merge it. See GitHub Access.
• Agent development enabled on the app (on by default).

1. Check for an updateCopy Anchor Link

Ask your agent to call get_blueprint_update. It only reads.

• No update: returns available: false with a reason (up to date, updates stopped for this app, or nothing released yet).
• Update available: returns the current and target versions, the baseline and target SHAs, the changelog and the change type (major, minor or patch).

If needsAttention is set, an earlier update reached main but couldn't be recorded. See Needs attention.

2. Prepare itCopy Anchor Link

Ask your agent to call prepare_blueprint_update. It runs right away, with no confirmation step:

• creates a ref blueprint-source-<full-commit-sha> in your repo that points at the update's exact commit,
• applies the update's schema changes to your app's data store, before any code changes (the changes only add, so this is safe even if you never merge),
• returns steps: the exact git commands for this update.

Calling it again is safe. It applies only what the store is still missing, so it's also how you retry after a schema error.

3. Merge on a branch and open a pull requestCopy Anchor Link

Your agent follows steps in order. In outline (<sha> is the full target SHA, <short-sha> its first eight characters):

git status --short   # must print nothing
git fetch origin +refs/heads/main:refs/remotes/origin/main refs/heads/blueprint-source-<sha>:refs/remotes/origin/blueprint-source-<sha>
git switch -c agent/blueprint-update-<short-sha> origin/main

git merge --no-ff --no-commit origin/blueprint-source-<sha>

git checkout origin/main -- stardeck.project.json 2>/dev/null || git rm -q -f --ignore-unmatch stardeck.project.json
git checkout origin/main -- apps/web/src/generated/data-store-types.ts

(cd apps/web && npx stardeck-data-store generate-types)
git add apps/web/src/generated
npm run typecheck

git add -A && git commit -m "Merge Stardeck update <version>"
git push origin HEAD:agent/blueprint-update-<short-sha>

steps can include more for your app: restoring the core of Modules you customized with Customize UI, keeping Modules you uninstalled out, porting seed rows you customized, and checking translation overrides.

The pull request's Stardeck-owned files check recognizes the update it merges. It only warns about Stardeck-owned files that differ from that version, and it never blocks the merge.

4. Stardeck records itCopy Anchor Link

Merging the pull request is the last step. On the push to main, Stardeck finds the newest released version that main contains. It checks that main still names this app in stardeck.project.json and keeps your app's Module choices. Then it sets what the standard roles can do in your app to match Stardeck's Modules at that version, moves your app to that version (clearing the indicator), writes a history entry and posts a timeline event in the app's chat that lists any change to what staff or customers can do. An hourly check catches a push it missed.

To drop an update before merging, run git merge --abort or delete the branch. Nothing on Stardeck needs undoing.

Then go through what to check afterwards and deploy a preview before production.

Needs attentionCopy Anchor Link

If the merge reached main but a check failed, Stardeck saves the reason as needs attention. get_blueprint_update returns it as needsAttention, and the agent's reminders show it. Fix main with another pull request. Stardeck checks every push to main again and records the update once main is right.

TroubleshootingCopy Anchor Link