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
Open the app’s Git panel
In the console , open your project → the site → Connections. The Deploy from GitHub panel sits under the connected services.
Install the Ghayma Deploy app
Click Connect GitHub. You land on github.com, where you install the Ghayma Deploy app on your personal account or on an organization, and choose which repositories it may see — all of them, or a list you pick.
The app asks for read access to the contents and metadata of those repositories, and for push events. It cannot write to them, and it sees nothing you did not select.
Come back to the console
GitHub sends you back and the account is connected. The connect link is good for 15 minutes — if you take longer, start again from the Git panel.
Installing on an organization you don’t own asks an owner to approve the app instead. Nothing is connected until they do; come back to the Git panel afterwards and link the repository.
Link a repository and a branch
With an account connected, the panel shows a picker:
| Field | What it does |
|---|---|
| GitHub account | Only shown when you have connected more than one account or organization |
| Repository | The repositories that installation may read. Private ones are marked (private) |
| Branch | Defaults to the repository’s default branch — type another to deploy from it instead |
| Deploy automatically on every push to this branch | On by default. Off means the link exists but pushes build nothing |
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.
One repository link per app. Linking again replaces the existing link rather than adding a second one, so switching branch or repository is just linking again.
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:
- the settings saved on that site (the site’s Settings page), then
- 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. 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.
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 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.
Removing the Ghayma Deploy app on GitHub stops deploys immediately — for every app linked through that installation, and without warning here. GitHub simply stops sending the pushes. Reinstalling creates a new installation, so you have to link each app’s repository again afterwards.
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:
| What you see | What to check |
|---|---|
| Nothing at all on the panel | The push went to another branch, or GitHub no longer has the app — check the branch on the link, and the app’s installation on github.com |
auto-deploy off chip, ignored | Turn auto-deploy back on |
Last push failed: deploy refused | The person who linked the repository lost the project write role — or their write access is restricted to other sites — the project is suspended, or the plan’s daily deployment limit is used up. Relink as someone with write access on this site, or wait out the limit |
Last push failed: fetch | The commit could not be downloaded — usually the repository was removed from the installation on GitHub. Add it back, then push again |
| A failed deployment with logs | The build itself failed. Read the log on the Deployments tab like any other failed deploy — see Builds |
A push whose repository was renamed on GitHub still deploys: the link follows the repository’s id, not its name.
If the panel says GitHub deploys are not configured on this platform yet, the platform this console belongs to has no GitHub app set up. Nothing you can fix from here — deploy with the CLI meanwhile.
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