Skip to content

Push to GitHub

Frames imported from a GitHub repository (Import from code) can send their edits back. Feega patches the source files it read (text, style, tokens) and commits them; it never rewrites a file wholesale.

  • Never the default branch. Every push goes to feega/<name> and opens one pull request against the base branch.
  • One pull request per merge cycle. Later pushes update the same pull request. Once it is merged or closed, the next push opens feega/<name>-2.
  • Never force-pushed. If someone rewrote, deleted or protected the branch, the push goes to feega/<name>-sync and opens a pull request from there.
  • One commit, all files. The files of a push land in a single commit; if access is lost mid-push, no branch is created.
  • One push at a time. A second push on the same branch while one runs answers busy.
  • Co-authors. Pass co-authors and they are added to the commit.
  • Files named .env or .env.* are never read nor written.
  • The diff is scanned for secrets (API keys, tokens, private keys) before anything reaches GitHub; a match stops the push.
  • Config files, lockfiles and dotfiles need an explicit confirmation (--confirm-sensitive, confirmSensitive: true).
  • Without write access to the repository, the push answers read_only with the patch, so you can apply it or open a pull request from a fork.

Importing a repository or a git folder links the frame to its source: the first imported page is the entry file, every imported page file joins the link, with the app root (monorepos), the base branch and commit, and the values a dynamic route was opened with (/blog/[slug] → slug). A local folder takes the branch it is on and its current commit. Uploads are not linked. Duplicating a frame does not copy its link.

The frame header shows one GitHub icon per linked frame, checked when the canvas opens and every minute after. The state of a linked frame is computed on request, never stored, with this priority: conflict, orphan (the file is gone upstream), access_lost, newer_upstream, modified, in_pull, in_sync. Files renamed upstream are followed automatically. The answer also carries the pull request and its CI checks.

Click the GitHub icon in a frame header to see its file, the base commit and branch, and the actions its state allows: Update (newer upstream, conflict, orphan) pulls the upstream code into the frame and moves its link to the latest commit of the base branch, View PR opens the pull request, Detach removes the link and keeps the frame. Changes opens the panel: every modified or conflicting linked frame with a checkbox, Create PR (or Update PR once a branch exists) with the branch, the pull request link and its CI state, a confirmation when config files, lockfiles or dotfiles are touched, and Undo last push. Without write access the button becomes Download patch.

Terminal window
feega github detach <projectId> <nodeId>

DELETE /api/v1/projects/:id/github/push?nodeId= (404 not_linked when there is no link), MCP github_detach {nodeId}.

Undoing a push adds a commit that restores only the files that push touched, as they were before it. History is never rewritten.

The versions of a linked frame are the branches, tags and open pull requests of its repo, and the commits that touched its file, newest first, with message and author.

Terminal window
feega github versions <projectId> <nodeId> [--ref <branch|tag|sha>] [--limit 30]

POST /api/v1/projects/:id/github/versions with { nodeId, ref?, limit? } answers { ok, entry, refs, commits, pulls }; MCP github_versions {nodeId,ref?,limit?}. A local folder lists its own branches and tags; pull requests appear when its origin is on GitHub and a token is available.

Click the GitHub state icon on a linked frame or component and choose Compare versions. The picker lists branches, tags, open pull requests and recent commits with message and author; tick up to four and press Compare.

Comparing imports the same page or component at up to four other refs — a branch, a tag, a commit sha, or #12 for a pull request — and places each one beside the original as a version frame. Its header shows the ref (main, feega/x, abc1234, PR #12) with a git icon. A version frame is read-only: its layers are locked, it has no link, and it is never pushed.

Terminal window
feega github compare <projectId> <nodeId> main feega/x '#12'

POST /api/v1/projects/:id/github/compare with { nodeId, refs } answers { ok, versions: [{ frameId, ref, label, sha, entry }] }; MCP github_compare {nodeId,refs}. A ref that does not exist answers 404 not_found. A local folder is checked out at that commit in a separate temporary git worktree, so your branch and uncommitted work stay as they are.

Click the git icon on a version frame to compare it with the frame it came from, or select two frames first to compare those two. Overlay shows the version with the changed regions outlined, found by comparing the two posters pixel by pixel. Slider puts one over the other with a handle to wipe between before and after.

Above the diff, a scrubber runs over the commits that touched the frame’s file, oldest on the left. Releasing it on a commit moves the version frame to that commit, in the same place.

Terminal window
feega github version-ref <projectId> <versionId> <ref>

POST /api/v1/projects/:id/github/compare with { versionId, ref }; MCP github_version_ref {versionId,ref}.

  • Restore this version: the files of the version become changes of the linked frame. It shows as modified in Changes and goes out with the next push, as a pull request like any edit. The default branch is never written.
  • Make variant: an editable copy of the version below it, not linked to the code.
  • Open code diff: the line diff of every file of the frame between the version and the base branch.
Terminal window
feega github restore <projectId> <versionId>
feega github version-variant <projectId> <versionId>
feega github code-diff <projectId> <versionId>

POST /api/v1/projects/:id/github/version-actions with { versionId, action: "restore" | "variant" | "code_diff" }; MCP github_version_action.

Terminal window
feega github push <projectId> <nodeId...> --name hero
feega github status <projectId> <nodeId>
feega github undo <projectId> <nodeId>
MethodPathBody or query
POST/api/v1/projects/:id/github/push{ name, nodeIds, title?, body?, base?, confirmSensitive? }
GET/api/v1/projects/:id/github/push?nodeId=—
POST/api/v1/projects/:id/github/push/undo{ nodeId }
POST/api/v1/projects/:id/github/versions{ nodeId, ref?, limit? }
POST/api/v1/projects/:id/github/compare{ nodeId, refs }

Refusals answer { ok: false, refusal }: not_connected, read_only (403, with patch), secret and env_file (422), needs_confirm (428), busy (423), unauthorized (401), forbidden (403).

github_push, github_push_status, github_undo, github_versions and github_compare, with the same inputs.

An import links its frame to every page it captured, one link per route, each carrying the route’s whole import graph: a change upstream to any file a page imports marks that frame as newer. Components from your library that those pages use get a main link to their own file and one instance link per page that uses them. The first poster saved after import is kept as the “before” thumbnail, shown next to the current one in the Changes panel.

An edit on a main component changes the component file: every page using it changes, and the Changes panel says how many pages are affected before you push. An edit on an instance stays at that usage site: a text that comes from a prop rewrites that prop, a style becomes a style override when the component accepts one. When no prop fits, the edit is not written and the status lists it under proposals, for the agent to add the prop. Tick Apply instance edits to main component (or pass mains / --main) to write them to the component file instead.

Duplicate gives an unlinked copy. Make variant (the GitHub popover, github_variant, feega github variant <projectId> <canvasId> <nodeId>) gives a copy linked as a variant of the original. Its first push answers variant_choice with a suggested route; pick Replace original (writes the original files), New route (writes the edited page at the new route’s file, following the page’s convention, e.g. app/pricing-b/page.tsx) or Keep on canvas (pushes nothing). The API and MCP take variants: [{ nodeId, choice: replace | new_route | keep, route? }]; the CLI takes --variant <nodeId>:<choice>[:<route>].

When a file you edited on the canvas also changed on GitHub, the frame shows a conflict. Resolve opens a split view with the canvas and GitHub versions of each file, and three ways out:

  • Keep canvas: the canvas version wins; the next push writes it over the GitHub change.
  • Take GitHub: runs Update, pulling GitHub’s version into the frame.
  • Resolve with agent: copies a merge prompt holding the base, canvas and GitHub versions, to hand to the agent.

API: GET /api/v1/projects/:id/github/push/conflicts?nodeId= and POST with { nodeId, choice: keep_canvas | agent }. MCP: github_conflicts, github_resolve. CLI: feega github conflicts, feega github resolve. A property-level three-way merge, which would settle most conflicts on its own, is not built yet.

A frame imported from a local folder (desktop app, local dev) pushes through git in that folder: Feega commits with a private index, so your current branch, uncommitted work and history stay untouched. The branch goes to origin with your git credentials; the pull request opens when a GitHub token is available, otherwise the answer carries pull: null and the branch is left for you. The live preview is your own dev server.

A connected GitHub App, or GITHUB_PUSH_TOKEN (fine-grained token) with GITHUB_API_URL for GitHub Enterprise. Permissions: Contents: read and write, Pull requests: read and write, Checks: read, Metadata: read. Details in the self-hosting guide.