GitHub sync

GitHub sync reads a committed PlanQ project into a Workspace. GitHub is always the source of truth—the web workbench is strictly read-only and will never edit your .plan files or write commits.

Prerequisites

• Commit a valid plan.manifest.json and every declared entry.
• Commit all includes at the same revision.
• Commit resources.plan and any accepted resources.lock.json when used.
• Run planq project validate before pushing.
• Ignore .plan/ and keep Account CLI tokens outside Git.

Permissions and roles

The GitHub App requests Metadata: Read-only and Contents: Read-only only. A Workspace owner installs the App and creates, changes, or reconnects a binding. Owners and editors can request a sync. Viewers can read status and results.

First sync

If the Workspace has no visible plans, an owner can select Connect GitHub repository directly from Plans. The same flow is available at /w/<workspaceId>/settings/github?setup=connect; opening the Workspace menu first is not required.

1. Install or update the GitHub App for only the repositories you intend to sync. The installation callback returns to the same Workspace setup flow.
2. Select the installation and repository. A single active installation and the repository default branch are selected automatically when unambiguous.
3. Confirm the branch and manifest path. At repository root, use plan.manifest.json.
4. Inspect the manifest and confirm the current HEAD commit, normalized path, and ordered entries.
5. Connect the repository. The URL changes to the stable ?setup=<bindingId> state and shows persisted first-sync progress.

If you change the installation, repository, branch, or manifest path, you'll need to inspect it again before connecting. A missing or invalid manifest keeps the current selection and reports a stable code. Use the offered repair prompt in the local Git checkout, commit and push the repair, then inspect again. The prompt never includes credentials or repository file contents.

Each run reads the current branch HEAD, resolves the manifest, validates every entry, and stores normalized read-only results. We don't store the raw .plan source permanently.

The first valid active source is opened automatically in manifest order. Other entries continue independently, so one invalid entry does not block the first usable Gantt. Refreshing or reopening ?setup=<bindingId> restores progress from the server and does not create another binding.

Status and recovery

Status	Action
pending or syncing	Keep the setup page open; it polls while visible and resumes after refresh.
valid or synced	No action is required.
invalid	Fix diagnostics locally, validate, commit, and push.
source-missing	Restore the manifest path or update the binding as owner.
partial-failure	Valid entries still advance; repair only the failed entries.
failed	Waiting stops immediately. Check the binding and source diagnostics, then retry or inspect the configuration.
disconnected	Restore App access, then reconnect the existing binding as owner.

Reconnection preserves the binding identity and previous valid results. Do not create a duplicate binding for the same Workspace, repository, and branch. If a completed first sync has no valid source, setup remains open with diagnostics, Sync now, and a path back to the connection configuration. It does not substitute the example plan or report success.

See Troubleshooting for recovery and Diagnostics for stable code categories.

Read-only boundary

The workbench can filter, navigate, and display synchronized results. It cannot edit plans, change a repository, or push a correction. Make every source change locally and send it through the normal Git review process.