Save your code to GitHub
Watch it done (real recording)
Watch: opening GitHub from the project toolbar and clicking Connect GitHub, the authorize window opens.
GitHub is the source of truth for your project's code. Once connected, FlutterGo pushes your work to a private repository in your own GitHub account at safe points, after agent changes, on save, before deploys, and when you close the project. Nothing is ever trapped in the platform.
Connecting takes about a minute and is a one-time step per account. After that, syncing is automatic and silent; a small branch chip in the toolbar shows you the live status.
Here we walk through connecting, explains exactly when pushes happen, tours the branch chip, and shows how to use your GitHub commit history as version history.
What you need#
- You have a GitHub account (a free one is fine). Brand-new accounts sometimes need a one-time unflag step, see Troubleshooting.
- Your project is open in the workspace.
- Pop-ups are allowed for the studio, the GitHub authorize window opens as a pop-up.
What happens when you connect#
If you've already installed the FlutterGo GitHub app, it is detected automatically, you never see the install page.
How to do it#
1. Find the GitHub banner#
When a project has no linked repository you'll see the GitHub banner at the top of the workspace (callout ① on the workspace tour). Its status line reads "Connect GitHub to save your code."
The banner: choose Create or Link, name the repo, and push.
2. Choose Create or Link#
The banner has two tabs:
- Create, make a new private repo. The name field is pre-filled from your project name.
- Link, pick a repository you already have on GitHub.
3. Click Create & push (or Link & push)#
Click Create & push (on the Link tab: Link & push; if GitHub is not connected yet the button reads Connect & create or Connect). A GitHub window opens, click Authorize when asked; this identifies your GitHub account. The banner shows progress: "Creating repo and pushing…".
4. Install the FlutterGo app (first time only)#
Only if the FlutterGo app isn't installed on your account yet, GitHub shows its install page. The banner's Install tips say it plainly:
- Select All repositories on GitHub (recommended), and keep Administration: Read & write enabled so repositories can be created for you.
- Click Save, then return here.
5. Confirm you are synced#
Done. The banner switches to Synced to owner/repo with a link to your repository. From now on, if the app is already installed and able to create repos, new projects provision their repo silently, no extra clicks.
Success: Your first commit is already in the repo, with the message "FlutterGo: initial project setup".
6. Meet the branch chip#
In the project toolbar, the GitHub chip now shows repo@branch (for example my-flutter-app@main). When you have unpushed work, a badge shows the number of changes ("{n} changes to push"). Click the chip to open the sync panel:
- Your repo name at the top links to GitHub; ↻ ("Refresh status & branches") reloads the status.
- Branches, click any branch to switch to it (the current one is checked ✓). Type a name in "New branch name" and click Create to branch off.
- A status line: "✓ Up to date with {branch}", or "{n} changes to push (+added ~modified −deleted)", or "Checking for changes…".
- Pull, download the branch into your project ("Downloading {branch} into your project…").
- Push, upload now; the button shows the count, e.g. Push (3) ("Uploading {n} changes to {branch}…").
The chip stays live on its own, it refreshes after every sync, mode switch, and when the tab regains focus.
What gets synced, and when, safe points#
Pushes happen at safe points, never on every keystroke. Rapid triggers within a few seconds are combined into a single push. Each safe point writes a clean commit message:
| Safe point | When it fires | Commit message |
|---|---|---|
| Initial | Repo is created and first code is pushed | FlutterGo: initial project setup |
| AI change | An agent run completes successfully | FlutterGo: apply AI changes |
| Save | You save a file in the code editor | FlutterGo: save changes |
| Mode switch | Before switching run mode | FlutterGo: sync before switching mode |
| Before deploy | Right before a deploy starts | FlutterGo: sync before deploy |
| Close | You close or leave the project (also when the tab is hidden) | FlutterGo: save session |
| Build fix | After a successful build repair | FlutterGo: fix build errors |
| Manual | You click Push in the branch chip | FlutterGo: update project |
And in the other direction: opening a project pulls the latest commit first, so edits made from your own machine are respected.
Tip: Because "before deploy" and "on close" are flushed immediately (not debounced), you can close the tab without worrying, your work is pushed first.
Version history, restore any commit#
Your version history is your GitHub commit history. There is no separate history screen in the studio; every safe point above is a commit in your repo.
To go back:
- Easiest: tell the agent "revert the last change", it undoes the last edit for you.
- For anything older, open your repository on GitHub (click the repo name in the branch chip), open Commits, and find the commit you want.
- Restore it either by asking the agent ("restore the project to commit abc1234") or with git on your machine (
git revert/git checkout), then Pull in the branch chip, or simply reopen the project, which pulls automatically.
Important: Pushes from FlutterGo assume the linked branch is yours to write to. If you rewrite history on GitHub while the project is open, click Pull before continuing.
Re-authorizing GitHub#
You normally never have to think about tokens: user authorizations are refreshed automatically in the background.
If you revoke the authorization on GitHub (or it expires), the next repo operation shows: "Your GitHub authorization expired or was revoked. Click "Create & push" again to re-authorize, it takes one click." Do exactly that, the same one-click authorize window reappears, and the stale token is replaced.
To review or remove access at any time, go to GitHub, then Settings, then Applications, then FlutterGo.
Working outside FlutterGo#
The repo is a standard Flutter project: clone it, run it locally, push commits from your IDE. FlutterGo pulls your commits the next time the project opens (or when you click Pull).
Permissions we ask for, and why#
| Permission | Why it's needed |
|---|---|
| Administration (read & write) | Create the private repository for a new project. |
| Contents (read & write) | Push and pull your project code. |
| Actions | Trigger and monitor deploy workflows. |
Troubleshooting#
Problem: The GitHub window shows a 404. Possible causes: The GitHub account is usually the problem, not FlutterGo. New GitHub accounts are sometimes flagged by GitHub's spam systems and can't install any app until unflagged. Solution:
- Open your GitHub settings and follow the "account flagged" banner to appeal.
- Or use another GitHub account.
- Then click Retry in the banner.
Problem: Stuck on "Connecting…". Possible causes: The connection window was closed early, or GitHub was slow to confirm. After ~3 minutes you'll see "GitHub did not confirm the installation. If you already installed the FlutterGo app, click Try again, we will detect it automatically." Solution:
- Click Retry, an existing installation is detected automatically.
- Make sure your browser did not block the pop-up.
Problem: "Auto-create needs server OAuth." Possible causes: Personal GitHub account on a server without OAuth configured, repos cannot be created for you automatically. Solution:
- Switch to Link existing in the banner or branch chip.
- Use the "create an empty repo on GitHub" link (it pre-fills a private repo), grant FlutterGo access to it, then pick it and click Link & push code.
Problem: Pushes suddenly fail after working fine. Possible causes: The GitHub authorization was revoked or rotated. Solution:
- Read the error, if it is the re-authorize message, click Create & push (or Push) again and approve the one-click authorize window.
- If you removed the FlutterGo app entirely on GitHub, reconnect from the banner.
FAQ#
Is my repository public? No. Repositories created by FlutterGo are always private, in your own account.
Does every keystroke create a commit? No. Pushes only happen at safe points (see the table above), and quick bursts are combined into one commit.
Can I use a branch other than main? Yes. Open the branch chip, create a branch with New branch name, then Create, or click any existing branch to switch. Syncs then target that branch.
Where is the version history button? There isn't one in the studio, your history is the commit list on GitHub. Every safe point is a commit; restore any of them (see "Version history" above).
Can my teammate's pushes reach my project? Yes, opening the project pulls the latest commit, and you can click Pull any time to get new commits immediately.
What if I already have a Flutter repo? Use Link (or Clone from GitHub when creating a project, only Flutter projects with pubspec.yaml and a lib/ entry point are accepted).
Where to go next#
- Deploying your app, deploys run in your repository via GitHub Actions.
- Working with the AI agent, every agent change becomes a safe-point commit.
- Troubleshooting & FAQ, more GitHub connect fixes.