Connecting a repo

Tandem deploys from Git. Before you can deploy a service, the platform needs to know where its source lives. There are three ways to connect a repo — pick whichever matches where the code already lives (or should live):

  • Tandem Git — Tandem hosts the repo itself: first-class git hosting, zero GitHub account needed. This is the portal’s default for new projects and the fastest zero-dependency path. Full guide: Tandem Git.
  • GitHub App — Tandem authenticates as a GitHub App with scoped access to specific repos on GitHub.
  • Clone URL — Tandem stores a URL it can git clone from: a public repo, or a private one reached via a deploy key.

What each source enables

Capability Tandem Git GitHub App Clone URL
Manual deploys from the portal yes yes yes
Auto-deploy on push to the default branch (or deployBranch) yes yes no
Import services from platform.yml on connect no — the “template” init mode seeds a starter platform.yml instead yes no
Repository Mutation API (no-clone read/commit — powers the MCP git tools, and the future in-portal editor) yes no no
Drive-style sharing / access grants on the repo itself yes (share_git_repo, the Share dialog) no (GitHub’s own collaborator model governs the repo; Tandem only holds an installation token) no
Migrate in from an existing GitHub repo, or any public URL yes (import_repository / “Copy to Tandem Git” / “Import from URL”) n/a (it’s already there) n/a
Export to GitHub / continuous Mirror to GitHub n/a (it’s the source) n/a n/a
GitHub commit status / check runs (planned) no yes no

If you connect via clone URL, you can still define services manually from the portal’s Services tab and trigger deployments by hand. You just won’t get platform.yml import or push-driven deploys — for either of those, use Tandem Git or the GitHub App.

Connecting via Tandem Git

Tandem Git is a first-class, self-hosted git host inside the platform — a private repo with a standard HTTPS clone URL and an access token, no GitHub account required anywhere in the chain. See Tandem Git for the full guide (creating repos, PATs, credential-helper setup, the mutation API, sharing, migrate in/out, and continuous Mirror to GitHub). The short version:

  1. Creating a project: pick Host code on Tandem in the “New project” form (the default) — choose “Start from a template” (seeds a deployable platform.yml) or “Empty repository”, name the project, and create. Both the project and its repo are created together, already wired up as the deploy source.
  2. Adding to an existing project: from the project’s Code tab, either create a repo (auto-attached as the deploy source) or, if the project already has a linked Tandem repo that isn’t yet the source, use Make this the deploy source.
  3. Clone it: the URL is on the Code tab; mint a PAT from Settings → Git access tokens. Or skip cloning entirely — edit files directly through the Repository Mutation API or the read_git_repository / commit_git_changes MCP tools.
  4. MCP, zero portal clicks: create_git_repo with asProjectSource: { newProject: "<name>" } (new project) or { projectId: "<id>" } (existing project) creates the repo and wires up the deploy source in one call.

Already have code elsewhere? Migrate it in — see the “Migrating between GitHub and Tandem Git” section of Tandem Git (import_repository / “Copy to Tandem Git” / “Import from URL”).

Connecting via GitHub App

  1. From the portal, go to Settings → GitHub and click Install GitHub App.
  2. GitHub takes you through its install flow — pick whether to grant access to all repos or specific ones in your account/org. You can change this later from GitHub’s app settings.
  3. When the install completes, GitHub redirects you back to the portal with the installation linked to your user.
  4. Open a project, click Connect repository, and pick the repo from the list. Only repos covered by the install will appear.
  5. If the repo has a platform.yml at the root of the default branch, the portal offers to import its services in one click. Otherwise, define services manually.

After connection, every push to the repo’s default branch (or the deploy_branch override on the project, if set) automatically queues a deployment for each service in the project.

Already hosting on Tandem Git and want a GitHub-side copy instead of migrating away? Use Export to GitHub or continuous Mirror to GitHub from the Tandem repo’s Source tab — see Tandem Git — rather than starting a fresh GitHub App connection.

Connecting via clone URL

  1. Open a project and click Connect repository → Use a clone URL.
  2. Enter the HTTPS or SSH URL and the default branch name.
  3. For private repos you’ll need to give the host machine SSH access — talk to a platform admin for the deploy-key flow.

You’ll then need to add services from the Services tab. Each service config (path, type, build/start commands) is stored in the portal rather than imported from platform.yml.

Doing this over MCP

Tandem Git

create_git_repo (with or without asProjectSource), read_git_repository, commit_git_changes, share_git_repo, import_repository, export_repository_to_github, get_source_status, configure_git_mirror — see the Tandem Git guide and the MCP tool reference for full parameters.

GitHub App / clone URL

An agent connects a GitHub-backed repo entirely through MCP tools — no portal clicks:

  1. list_github_installations — find the GitHub App installations visible to your org. (A human still performs the one-time GitHub App install; the agent picks it up from here.)
  2. list_installation_repositories with the installationId — see the repos that install grants.
  3. connect_repository with installationId + githubRepoNodeId — connect the repo into the org (needs manage + developer). list_repositories shows repos already connected and their ids.
  4. set_project_repository with projectId + repositoryId (+ optional deployBranch) — attach the repo to an existing project.
  5. read_platform_yml with the repositoryId — fetch + parse the repo’s platform.yml into service definitions, then import_services to bulk-create them.

list_repositories reports hasInstallation per repo — true means platform.yml reads and push-driven auto-deploy are available; false (clone-URL only) means you define services manually and deploy by hand.

Switching between sources

  • Clone URL → GitHub App: install the GitHub App if you haven’t already (Settings → GitHub), then from the project’s Settings choose Re-link repository via GitHub App and pick the matching repo. Existing services keep their config; only the connection mode changes. Auto-deploy and platform.yml import become available immediately.
  • GitHub → Tandem Git (zero-migration): “Copy to Tandem Git” from the project’s Source tab (or import_repository with source: { githubRepositoryId }) clones the GitHub repo’s full history into a new Tandem repo; pass repointProject: true to switch the project’s deploy source over once the copy finishes. Nothing about env vars or deploys changes — they’re stored outside git either way.
  • Tandem Git → GitHub: “Export to GitHub” (one-time copy into an empty repo you create) or continuous “Mirror to GitHub” (keeps a GitHub copy live) — both covered in the “Migrating between GitHub and Tandem Git” section of Tandem Git.

Common errors

  • no_installation_linked — you tried to import or refresh platform.yml on a repo connected via clone URL. Re-link via the GitHub App, or define services manually.
  • platform_yml_not_found — the App is installed but the file isn’t on the branch Tandem fetched. Check the file is at the repo root and committed to the default branch. See Writing platform.yml.
  • Push webhook received but no deployment — confirm the project’s deploy_branch (or the repo’s default branch, if unset) matches the branch the push was on. Pushes to other branches are recorded but don’t auto-deploy. This applies identically to GitHub-connected and Tandem Git projects.