Deploy from GitHub

Link a repository and a branch to one of your apps, and every push to that branch builds and deploys it. A git deploy is an ordinary deploy — the same build settings, the same limits, the same deployment history and the same rollbacks as ghayma deploy.

The link is per app: one site is bound to one repository + branch. A project with several apps links each one separately, and several apps may deploy from the same repository.

Connect your GitHub account

Link a repository and a branch

With an account connected, the panel shows a picker:

Click Link repository. The panel then shows the repository, the branch and an auto-deploy on chip, plus the account the link goes through.

Linking needs the project write role — a link is a standing permission to deploy, so it is the same bar as a deploy itself. With read you see the link but cannot change it.

What happens on a push

A push to the linked branch creates a deployment immediately:

• The commit’s code is fetched and built with the app’s build settings.
• The commit’s first line becomes the deploy message.
• The deployment appears on the project’s Deployments tab with a git push badge next to the short commit sha, the branch and the repository.
• It is a production deploy when the linked site is a production site — the same rule every other deploy follows. Link a development site’s repository and its pushes are development deploys.

Everything else about it is an ordinary deploy: it waits its turn in the build queue, it counts against your plan’s daily deployment limit, a failed build leaves the previous one serving, and you can roll back to it or from it.

Only the linked branch deploys. Pushes to any other branch, tag pushes, and branch deletions are ignored — nothing is built and nothing is charged.

Git deploys run as the person who linked the repository, not as whoever pushed: the pusher is a GitHub identity with no Ghayma account behind it. The pusher’s login and the commit are still recorded on the deployment.

Where the build settings come from

A git deploy carries no .ghayma.json — that file is read by the CLI on your machine, not from inside the repository. A pushed build uses:

1. the settings saved on that site (the site’s Settings page), then
2. auto-detection.

So for a monorepo, set the site’s root directory in its Settings before linking — otherwise detection sees the workspace root and the build fails. The same goes for an app that builds from its own Dockerfile: Build with: My Dockerfile has to be saved on the site (see Custom Dockerfile). A previous ghayma deploy will already have written its .ghayma.json build fields onto the site, in which case there is nothing to do. See Where build settings live.

For the same reason, a git deploy never touches your cron jobs — the crons array is applied by ghayma deploy only.

Several apps from one repository

The same repository — and the same branch — may be linked to as many apps as you like. That is how a monorepo deploys: each site carries its own root directory, and one push deploys all of them, one after another, from the same commit.

Private repositories

Private repositories work exactly like public ones. The app’s installation is what grants read access: the platform mints a one-hour token per fetch and drops it, and no user token, password or SSH key is ever stored. Your source is downloaded for the build and treated like an uploaded tarball — nothing of the repository is kept beyond the build.

Deploy on demand

A linked site can be deployed from its repository whenever you ask, without a push:

POST /api/v1/projects/:id/sites/:siteId/repo/deploy

Body (optional):

{ "sha": "9f2c1b8e4a7d0c3f6b5e2a1d8c7b4f3e0a9d6c2b" }

With no body — or no sha — the linked branch’s head is resolved live from GitHub and deployed, and that commit’s message becomes the deployment’s label. A sha deploys that exact commit instead; it must be a 40-character hash.

Response: 202

{ "deployment": { "id": "dpl_abc123", "status": "queued" } }

The fetch and the build run in the background, so poll Get Deployment for the outcome — a GitHub-side failure lands on the deployment row as failed, with the reason in the build logs, exactly like any other failed deploy.

auto_deploy is ignored. That switch says whether a push deploys itself; this route is a person or an orchestrator asking. A link with auto-deploy off deploys here perfectly well — which is the whole point of turning it off.

The deployment is tagged with the git_manual trigger, so the history tells an on-demand deploy apart from a pushed one. It is an ordinary deploy in every other respect: the build queue, the daily limit, the rollback window.

This route takes an account token or a dashboard session. A project API key answers 403: a key that could deploy a site’s linked branch could run arbitrary code as that site’s owner.

Turning auto-deploy off

Turn off auto-deploy keeps the link and stops building. Pushes to the branch are recorded on the panel and nothing else happens, and you can still deploy that app with ghayma deploy — or on demand — meanwhile. Turn on auto-deploy puts it back.

Unlinking

Unlink asks once, then removes the link:

Stops deploying on push. Deployments already made stay as they are.

Nothing else changes. The app keeps running its current build, every past deployment stays where it is, and you can deploy it from the CLI or link another repository whenever you like.

Managing your installations

Settings → GitHub in the console lists every GitHub account and organization you have installed the app on: the account login and type, when you connected it, how many linked sites run through it, and a revoked chip once the installation is gone from GitHub.

Uninstall

Uninstall takes the whole installation out, on both sides, after a two-click confirmation showing what it will unlink:

1. The app is removed on GitHub.
2. Every site linked through that installation is unlinked — the sites keep running their current build and their deployment history is untouched.
3. The installation is marked revoked here.

DELETE /api/v1/github/installations/:installationId

Response: 200

{ "removed": true, "unlinked_sites": 2, "github_uninstalled": true }

GitHub is called first: if it refuses, nothing local changes and the call answers 502 github_uninstall_failed — the message tells you to retry or uninstall from GitHub → Settings → Applications. The reverse order would leave your links deleted for an app that is still installed.

It is idempotent and forgiving: uninstalling twice answers 200 with unlinked_sites: 0, and if you already removed the app on github.com you can still call this to clear the links it left behind — which is the main reason to.

One installation, one Ghayma account

A GitHub installation belongs to the Ghayma account that connected it. If someone else runs the install flow for the same installation, they are refused:

{
  "code": "installation_claimed",
  "error": "this GitHub installation is already connected to another Ghayma account; uninstall it there first (Settings → GitHub) or install the app on a different GitHub account"
}

Re-running the flow as the same account is fine — it is idempotent. To move an installation to another Ghayma account, uninstall it from the first one; a revoked installation is claimable by anyone again.

When a push doesn’t deploy

The Git panel keeps the outcome of the last push — Last push 4 minutes ago — deployed, ignored, or a red Last push failed: …. Work down this list:

A push whose repository was renamed on GitHub still deploys: the link follows the repository’s id, not its name.

Related

• Builds — the queue, the limits, and why a build fails
• Deploy & Manage — ghayma deploy, rollbacks, and .ghayma.json
• Sites — several apps in one project
• Environments — what makes a pushed deploy a production one