GitHub & source control.

Connect a GitHub account, link a repository to a published project, and put a desktop project under Git to commit, push, and pull. Your GitHub credentials are scoped to your account and never leave the machine or server that holds them.

Two surfaces, two mechanisms

“GitHub” shows up in two places in Orchid, and they work differently. Knowing which one you're in keeps the steps below straight:

• Published viewer & dashboard Git tab (orchidide.com and <slug>.orchidide.com) — uses a GitHub OAuth connection to link a repository to a published project and commit single-file edits back as yourself. It does not run local git. This is the connect flow most people meet first.
• Desktop app — uses your machine's local git together with a connected GitHub account. You initialize a repository, publish it to GitHub, and run commit / push / pull from the Source Control panel. This is a different mechanism from the web flow, covered as a cross-reference below.

Start with Connect on the web. The desktop source-control workflow is covered under On the desktop.

Prerequisites

• A signed-in Orchid account. GitHub access is tied to your user — Orchid scopes every GitHub request to the signed-in account, so a connection you make is only ever usable by you.
• A GitHub account you can authorize. You'll grant Orchid access to your repositories once, on an explicit connect.
• Git installed (desktop only). Orchid drives your system git binary. If it isn't installed, source-control actions report “Git is not installed” — install Git and restart Orchid.

Connect a GitHub account

Connecting is a separate, deliberate step. Signing in to Orchid with GitHub is not the same as connecting your repositories — the plain sign-in requests no repository access. To push, pull, list repos, or commit back, you grant the broader scope once.

On the web (dashboard or viewer)

1. Open a project's Settings → Git tab on the dashboard, or the Source control pane in a published viewer.
2. Click Connect GitHub. You're sent to GitHub to authorize access, then back to the page (in the viewer, this opens a new tab — return to the original tab, which detects the connection automatically).
3. Once connected, search your repositories, pick one, choose a branch, and click Connect repository. Private repos show a lock icon; the branch list defaults to the repo's default branch.

On the desktop

1. Open the account menu (your avatar, top-right).
2. Choose Sign in with GitHub and authorize Orchid in the browser.
3. You're returned to the app with GitHub connected. Source-control actions that talk to GitHub (Publish, Push, Pull) are now unlocked.

Until you do this, GitHub-backed actions prompt: “Connect GitHub first — sign in with GitHub from the account menu.”

What access Orchid requests, and why

Connecting requests the GitHub repo OAuth scope. That scope lets Orchid:

• list and clone the repositories you own, collaborate on, or share through an org;
• read branch and commit history; and
• push commits and commit single-file edits back on your behalf.

Orchid also reads your GitHub login once, so it can show which account is connected. It requests no more than it needs to run the source-control actions on this page.

Initialize or create a repository (desktop)

A brand-new Orchid project isn't a Git repository yet. Two desktop commands get you from nothing to a repo on GitHub. Both live under the Source Control menu and act on the active project (never “whatever folder is open”).

1. Initialize Repository — runs git init in the project directory and writes a curated .gitignore tuned for Orchid projects (it ignores the per-project virtual environment and other local noise). Once initialized, Orchid's built-in Source Control panel lights up — staging, committing, diffs, and history are handled there.
2. Publish to GitHub — gated on a connected GitHub account. In one step it creates a new GitHub repository, sets it as the project's origin remote, and pushes your first commit. You pick Private or Public when prompted, then Orchid offers to open the new repo in your browser.

Already have a repo on GitHub? Skip create and just set the remote to it.

Set the remote (desktop)

The remote is the GitHub URL Orchid pushes to and pulls from. Publish to GitHub sets it for you. To point an already-initialized project at an existing GitHub repository, add the remote with standard Git:

# Add "origin" pointing at your existing repo
git remote add origin https://github.com/<owner>/<repo>.git

# Or update an origin that already exists
git remote set-url origin https://github.com/<owner>/<repo>.git

# Confirm it
git remote -v

With a remote in place, the push and pull actions below have somewhere to talk to. Without one, they report no_remote (see Error states).

Commit (desktop)

Committing happens in the Source Control panel (the branch icon in the activity bar), backed by Orchid's bundled Git integration:

1. Open the Source Control panel.
2. Review the changed files. Stage the ones you want (or stage everything).
3. Type a commit message in the message box.
4. Click Commit. The new commit appears in the graph and in the history view.

The expanded Source Control view shows the commit graph alongside a Commit / Push panel and the current branch.

Push and pull (desktop)

Once a remote is set, you can move commits between your machine and GitHub:

• Push — sends your local commits to GitHub. It's available as a button in the Commit / Push panel of the expanded Source Control view, and as a Push command in the Source Control menu. If the current branch doesn't have an upstream yet (for example, a branch you just created outside Orchid), Orchid sets one automatically on the first push.
• Pull — fetches and integrates commits from GitHub into your current branch. Run it from the Pull command in the Source Control menu. If a pull produces conflicts, the conflicted files show up in the Source Control panel to resolve.

Push and pull both authenticate with your connected GitHub account, so they work for private repositories. If the connection is missing or expired, you'll see one of the error states below rather than a silent hang.

Error states

Source-control actions return a typed error instead of failing silently, so the app can tell you exactly what to do. The ones you're most likely to see:

• no_token — GitHub isn't connected. You triggered a GitHub action (push, pull, publish) without a connected account. Fix: connect GitHub (Connect GitHub on the web; account menu → Sign in with GitHub on desktop), then retry.
• github_reauth_required — your GitHub connection expired. GitHub rejected the stored credential (revoked or expired). Fix: reconnect GitHub and try again — Orchid drops the stale credential and asks you to re-authorize. On the web, the repo list returns to the “Connect GitHub” state when this happens.
• no_remote — no GitHub remote is configured. The project isn't pointed at a GitHub repository yet. Fix: Publish to GitHub to create one, or set the remote to an existing repo.
• git_not_found — Git isn't installed. Orchid couldn't find your system git binary. Fix: install Git and restart Orchid.
• not_a_repo — the project hasn't been initialized. The active project isn't a Git repository yet. Fix: run Initialize Repository first.

The published-viewer connect flow, in short

On a published project, collaborators can connect their own GitHub account and commit single-file edits back as themselves — each person commits with their own token, scoped to their own account. If the Connect GitHub button doesn't appear to do anything, allow the new browser tab (it may be blocked) and use the I've connected action to re-check. “No repositories found” usually means the repo scope wasn't granted — re-run Connect and approve the access.

What's next

Connected and committing? Publish the project so collaborators can see it — Publishing. New to Orchid's data connections? Start with Connect a source.