The GitHub Panel

There are two ways to think about GitHub in Appsanic:

1. One-time export: getting your code into your own GitHub repository for the first time. Covered in Exporting to GitHub.
2. Day-to-day sync: pushing fresh changes from the agent, pulling edits you made by hand in your local editor. That's the GitHub panel, and this page covers it.

If you've never set up GitHub for your project, start with the export guide first. This page assumes you're already connected.

Where it lives

In the build header (top of the project view), there's a GitHub button. Click it. A small panel pops out showing:

• Your GitHub account: avatar, name, handle.
• The linked repository: name, full path (yourname/your-repo), default branch.
• A changes banner: how many files are new or modified since the last push.
• Action buttons: push, pull, unlink.

The panel closes when you click outside it or press Escape.

What the panel tells you at a glance

"X unpushed changes"

When you (or the agent) have made changes since the last push, you'll see a banner. It splits the count two ways:

• New (green): files that didn't exist on GitHub.
• Modified (yellow): files that exist on GitHub but differ now.

The total at the top tells you how much work is pending.

"Up to date"

When everything's pushed, the banner becomes a green check and "Up to date." Helpful confirmation that nothing's drifted.

Push changes

Click Push changes. A second view appears:

• Commit message: pre-filled with a sensible default, like "Update [app-name] - 42 files" on follow-up pushes, or "Initial commit - [app-name]" on the first push.
• Edit the message if you want something more specific.
• Click Push at the bottom.

What happens:

1. Every file in your project gets uploaded to GitHub on the default branch.
2. A commit lands with your message.
3. The panel returns to the main view with "Up to date."

Pushes are straight commits to the default branch (usually main). There's no PR flow inside Appsanic today. If you want PR-based workflows, you set those up externally (branch protection rules in GitHub, a real local editor for the PR-from-feature-branch dance).

Pull latest

Click Pull latest. You're asking Appsanic to read the latest version of every file from GitHub and replace your project's working copy.

When you'd want this:

• You opened the repo in Cursor or VS Code locally, edited a file by hand, and committed.
• A teammate pushed a change to the repo.
• You want to revert to GitHub's version of a file after a bad agent run.

Pulling overwrites your project's current files with GitHub's. If you have unpushed changes, they're lost. The confirmation step names this explicitly.

After the pull, the project reloads and the live preview updates with the fresh code.

Two-way sync, in practice

The panel is designed for a back-and-forth flow:

1. The agent builds something in Appsanic.
2. You push to GitHub.
3. You open the repo locally in Cursor or VS Code.
4. You make targeted edits (the kinds of changes the agent over-engineers, or you just prefer doing by hand).
5. You commit and push from your local editor.
6. Back in Appsanic, you pull latest.
7. The agent picks up where the local edits left off.

Don't edit the same file in both places at the same time. The agent reads from the latest project state on each turn; manual edits that haven't been pulled in won't be visible to it. Pull first, then ask the agent.

Linking a different repository

If you want to point your project at a different GitHub repo:

1. Open the panel.
2. Click Unlink to detach the current repo.
3. The panel returns to the "no repo linked" view.
4. Create a new repo for the project. Appsanic syncs repositories it created - it doesn't import existing GitHub repos.

Unlinking doesn't delete the repo on GitHub. It just disconnects this Appsanic project from it.

Creating a repo from inside Appsanic

If you haven't linked one yet, the panel's empty state offers Create repository. The form has:

• Name: auto-filled from your project name (lower-case, hyphenated, GitHub-safe).
• Description: auto-filled with your project description or "Built with Appsanic."
• Visibility: public or private. Default is private.

Click Create & push. Appsanic creates the repo in your GitHub account and, if your project has any files, immediately pushes them as the initial commit.

Same flow as the export-to-GitHub step, just initiated from inside the panel.

Disconnecting GitHub entirely

If you want to revoke Appsanic's access to your GitHub account altogether (not just unlink this project):

• In Appsanic: panel → Disconnect at the bottom. Logs out of GitHub across all your Appsanic projects.
• In GitHub: Settings → Applications → Authorized OAuth Apps → find Appsanic → Revoke.

After disconnecting, you can re-connect any time. Linked projects retain their GitHub links. They just need a fresh auth before push/pull will work again.

Common scenarios

"I want to use Cursor for the next feature"

1. Push the current state from the panel.
2. git clone the repo locally.
3. Open in Cursor.
4. Make your changes, commit, push from the terminal.
5. Back in Appsanic, Pull latest.
6. Continue prompting the agent.

"I made a change in Cursor but Appsanic doesn't see it"

You haven't pulled yet. Open the panel, Pull latest.

"I pushed from Appsanic but GitHub shows the old version"

A stale browser tab can show an old GitHub page. Refresh the GitHub page. If the commit really isn't there, the push may have failed silently. Open the panel and check for an error message.

"I want a branch-per-feature workflow"

That's not built into the panel. Options:

• Clone the repo locally and work on branches there using your normal git tools.
• Use the agent's bigger-picture features (like Conversations) to keep your in-Appsanic work organised, then push to main as you go.

A built-in PR mode is on the roadmap.

"I accidentally pulled and lost work"

Pulls overwrite the project's working copy. If the agent's last build was good, it's still in your conversation history. You can re-run the same prompt and reproduce the work. If the lost work was a manual edit you'd already pushed, just pull again.

Things that go wrong

• "Permission denied" on push. Your GitHub auth probably expired. Click Disconnect, then re-connect.
• "Repository not found." Someone deleted the repo on the GitHub side, or it was made private and your token doesn't have the right scope. Re-connect and re-link.
• Push is slow. A huge initial push (large node_modules, big assets, lots of files) takes a moment. The panel shows "Pushing…" while it works.
• Conflict on pull. Pulls always replace your local copy with GitHub's. There's no merge step inside the panel. If you want proper merge, do it in a real local editor.

Under the hood (for engineers)

• The client store (github-store.ts) owns connection state, the linked-repo metadata, the push diff, and the in-flight sync flag.
• The push diff drives the "X unpushed changes" banner only. Push itself sends your full current project to /api/github/push, which builds one commit via GitHub's Git Data API (a single tree + commit, no base_tree - so files you deleted in Appsanic are removed from the repo too) on the default branch.
• Pull reads the branch tip's tree recursively via /api/github/pull and returns every text file (binary blobs are skipped - the in-app model is text-only), replacing the project's working copy. There's no three-way merge.
• The "Up to date" indicator and "X unpushed changes" come from comparing each file's last-modified time against the last push (paths not seen since the last push count as new; paths touched after it count as modified).
• Disconnect revokes the OAuth token via /api/github/disconnect and clears local state.

Next

For the broader story of how Appsanic-and-GitHub interact, read Exporting to GitHub. For working in a real local editor after you've pushed, see Local Development.