Book a demo
Book a demo
Login

Troubleshooting Git Deployments: Stuck, Failed or Not Triggering

Updated September 27, 2026 · 6 min read

A Git deployment can go wrong in a few different ways — stuck in progress, failing partway through, or simply not starting when you push. Each one has a different fix, and the deployment logs usually tell you which one you’re looking at.

Start with the deployment logs

Before trying anything else, open the site’s deployment logs. They show which stage failed — cloning the repository, running the build, or starting the app — and that determines which section below applies.

Stuck “in progress”

If a deployment still shows in progress after about five minutes, it’s likely hung rather than genuinely still running. Use the site’s Check & Deploy action: it checks whether the previous deployment process has actually stopped. If it has, xCloud marks that attempt as failed, releases the deployment lock, and starts a fresh deployment.

Clone fails

A failed clone falls into one of three categories, and they need different fixes:

  1. Missing branch — the log shows something like “Remote branch … not found.” Fix: set the deployment to point at a branch that actually exists in the repository.
  2. Access error — the log shows “Permission denied (publickey)” or “repository not found.” This is not a branch problem, and changing the branch will not fix it. Fix the deploy key or reconnect the Git provider instead (see below).
  3. Network error with no Git-specific message — retry the deployment once. If it fails again the same way, the problem is the server’s outbound connection to the Git host, not the repository or credentials.

Fixing a missing or rejected deploy key

  1. Open the site’s Git settings.
  2. Click the button to configure the deploy key.
  3. If xCloud can add the key to the repository automatically, it will. If it can’t (for example, you don’t have admin rights on the repository), copy the public key it shows you and add it to the repository yourself as a read-only deploy key.
  4. Click Verify connection.
  5. Redeploy.

Confirm the server can reach the Git host over SSH on port 22 — a network block there produces the same kind of access error as a bad key.

Build or start fails

  • .env file path points at a folder, not a file. The path is joined to /var/www/<site>/ and needs to resolve to an actual file — .env for a normal project, or something like backend/.env for a monorepo. Pointing it at a bare folder name such as backend fails with an error like “Is a directory.”
  • Build commands. Check the build command for typos, a missing dependency install step, or a script that assumes a different working directory than the one xCloud runs it from.

Auto-deploy not triggering on push

If pushes to the branch aren’t kicking off a deployment at all:

  • Check that the webhook is still registered on the Git provider’s side — it can be removed if repository permissions changed or the app was disconnected and reconnected.
  • Reconnect the Git provider integration if the connection itself looks stale.
  • Confirm you’re pushing to the branch the site is actually configured to deploy from.

What you can’t change after the site exists

Site type, repository, domain and database can’t be edited on an existing site. If any of those needs to change, the fix is to delete the site and create it again with the right settings from the start — not to try to work around it in the current site.

What to send support

  • The site domain and which app type it is (static, Node.js, Laravel, custom Docker).
  • The exact error text from the deployment log.
  • Which stage failed: clone, build, or start.
  • Whether this ever worked before, and if so, what changed (branch, repository access, server).

Still stuck? Contact our support team for any of your queries.

Frequently asked questions

My deployment says ‘Permission denied (publickey)’. What do I do?

This is an access error, not a branch problem — changing the branch won’t help. Go to the site’s Git settings, configure the deploy key (or add the public key to the repository yourself as a read-only deploy key if xCloud can’t add it automatically), click Verify connection, then redeploy.

My build fails with ‘Is a directory’. What’s wrong?

Your .env file path points at a folder instead of a file. It’s joined to /var/www//, so it needs to end in a file name — .env, or something like backend/.env for a monorepo — not just a folder name like backend.

Can I change the repository or branch on an existing site after it’s created?

Site type, repository, domain and database can’t be changed on an existing site. If you need a different repository or a different site type, delete the site and create it again with the correct settings.