# How to Connect GitHub and Deploy Git Projects with xCloud

> Connect the xCloud GitHub App to the right team, deploy a new Git project, add Git to an existing WordPress or PHP site, and recover when a deploy key fails.

This guide shows server owners and team administrators how to connect GitHub to xCloud, deploy a new Git project, add Git to an existing WordPress or Custom PHP site, and recover when a deploy key cannot be configured automatically. GitHub connections are scoped to an xCloud team, so selecting the correct team before connecting or deploying determines which GitHub App installation the server and site use.

## Prerequisites
- An xCloud account with permission to manage the target team, server, and site
- A provisioned xCloud server owned by that team
- Access to the GitHub account or organization that owns the repository
- Permission to install or approve the xCloud GitHub App for that GitHub account or organization
- For a new Git deployment, a reachable repository containing the project
- For Git setup on an existing site, a reachable **empty** repository selected for the xCloud GitHub App
- The branch name, domain, runtime requirements, web root, and any required environment values

## Understand GitHub connection ownership

A GitHub connection belongs to the currently selected xCloud team. A server and its sites use the GitHub connection associated with the **team that owns the server**.

The same GitHub organization can be connected to more than one xCloud team. Each team connection is independent: disconnecting the organization from one xCloud team does not disconnect it from another team.

Before connecting GitHub or starting a deployment, use the team switcher to select the team that owns the target server.

## Step 1: Connect GitHub to the correct xCloud team
1. In xCloud, select the team that owns the target server.

   **Expected result:** The team name in the dashboard header matches the server owner.
2. Go to **Settings → Integrations → Git Provider**.

   **Expected result:** The **Git Integration** page lists the team’s existing connections or shows the option to connect a provider.

![The Git Integration page under Settings, Integrations, Git Provider, listing the team’s connections and the Connect Git Provider button](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-git-provider-page.png)

3. Select **Connect Git Provider**.
4. Choose **GitHub**, enter a recognizable label, and select **Connect GitHub**. GitLab and Bitbucket are marked **Coming Soon** in the current interface.

   **Expected result:** xCloud redirects you to GitHub to install or authorize the xCloud GitHub App.

![The Connect Git Provider dialog with GitHub selected, a label field and the Connect GitHub button; GitLab and Bitbucket marked Coming Soon](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-connect-github.png)

5. In GitHub, choose the account or organization, then choose one access scope:
   - **All repositories** gives the App access to every current and future repository in that account or organization.
   - **Only select repositories** limits the App to the repositories you choose. Return to the GitHub App installation settings later if another repository must be added.
6. Approve the installation and return to xCloud.

   **Expected result:** The connection appears on the **Git Provider** page under the current xCloud team.

> **Access rule:** A repository omitted from an **Only select repositories** installation will not be available to xCloud, even if the same GitHub organization is connected successfully.

## Step 2: Deploy a new Git project
1. Open the target server and start **Deploy via Git** from the new-site flow.
2. Select the connected GitHub provider and repository, or enter a public repository URL where the flow allows it.

   **Expected result:** xCloud can read the repository and branch list. For a private repository, the repository must be included in the GitHub App installation.
3. Select the deployment branch and review the detected application type.
4. Review the deployment settings before creating the site:

| Setting | What to enter |
|---|---|
| **Site User** | The Linux user that owns and runs the site files. Review the generated value and edit it when your naming convention requires a different user. |
| **Domain** | The production or temporary domain for the site. |
| **Web root / Build output directory** | The directory that the web server should serve. Use the framework’s public or build output directory rather than the repository root when required. |
| **Environment file directory** | The subdirectory where xCloud should create the `.env` file. Leave it empty to use the site root. |
| **Push to deploy** | Enable this when a push to the selected branch should trigger deployment. |
| **Deploy script** | Optional commands to run after xCloud pulls the repository. |

5. Add application secrets and environment values in xCloud rather than committing a `.env` file to Git. When writing deployment commands, the interface supports xCloud variables such as `XCLOUD_PHP`,`XCLOUD_NODE`, and `PROJECT_DIR`.
6. Select **Save and Deploy** to save the reviewed settings and start deployment in one action.

   **Expected result:** xCloud creates the site, configures repository access, and starts the first deployment. The deployment log should progress instead of stopping at repository access or deploy-key setup.

## Step 3: Add Git to an existing WordPress or Custom PHP site

Use this flow when the site already exists in xCloud and you want xCloud to place its current files under Git without recreating the site.
1. Confirm that the destination GitHub repository is accessible to the connected GitHub App and is empty.

   **Expected result:** xCloud can complete its preflight checks. Setup does not begin if the repository cannot be reached or already contains content.
2. Open the site, then select **Git** in the site navigation.
3. If xCloud asks for a connection, select **Manage Git Providers**, connect GitHub to the server’s owning team, and return to the site.

![The Git tab of an existing site asking for a connection, with the Manage Git Providers link](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-existing-site-git.png)

4. Select the connected GitHub App installation and the empty repository presented by the setup flow.
5. Review the generated `.gitignore`. Keep environment files,`.env.*` variants,`/.htpasswd`, caches, and other sensitive or generated files excluded. Removing those defaults can commit secrets or password hashes to the repository.
6. Confirm the setup.

   **Expected result:** xCloud creates the initial commit from the current site, configures the deploy key and webhook, and enables push-to-deploy after setup completes.

## Step 4: Recover from a deploy-key setup failure

A private repository needs a deploy key before the site can clone or pull it. If xCloud cannot add the key automatically, the deployment stops before cloning and shows recovery instructions. This prevents a deployment from continuing with incomplete repository access.
1. Open the affected site and select **Git**.
2. In **Deploy Key Required**, select **Generate Deploy Key** or **Re-register Deploy Key**, as shown.

![The Deploy Key Required panel with Generate Deploy Key, the SSH public key to copy, and Verify Connection](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-deploy-key-recovery.png)

3. If xCloud displays an **SSH Public Key** for manual setup, copy the complete displayed key.
4. In GitHub, open the repository and go to **Settings → Deploy keys → Add deploy key**. Paste the displayed public key and save it.
5. Return to xCloud and select **Verify Connection**.

   **Expected result:** Verification succeeds, the **Deploy Key Required** panel clears, and deployment controls become available.
6. Review the Git branch, web root,`.env` file directory, pull script, and deploy script. If the site was cloned, also check for a warning that a copied script still references the source site’s path.
7. Save the settings, then start the deployment. Where available, use **Save and Deploy** to do both in one action.

## Git pull script and deploy script (advanced)

In this step, you can customize how your application pulls code from your Git repository and define actions to run after deployment.

### Available Variables

You can use the following variables in both Git Pull Script and Deploy Script:

**Project variables (all sites)**  
• PROJECT\_DIR — absolute path to your site root  
• XCLOUD\_SITE\_PATH — absolute path to your site root  
• XCLOUD\_SITE\_BRANCH — current Git branch used for deployment

**PHP variables (PHP sites only)**  
• XCLOUD\_PHP\_VERSION — PHP version (e.g. 8.2)  
• XCLOUD\_PHP — full path to PHP binary  
• XCLOUD\_COMPOSER — PHP-prefixed Composer path

**Node.js variables (all sites)**  
• XCLOUD\_NODE — path to Node.js binary  
• XCLOUD\_NODE\_VERSION — installed Node.js version  
• XCLOUD\_NPM — path to npm binary

**PM2 variable (Node.js sites only)**  
• PM2\_PROCESS\_NAME — the PM2 process name for the site

### Git Pull Script

The Git Pull Script allows you to control how the code is fetched from your Git repository during deployment. You can go to the ‘Git Pull Script’ section and enter your custom script. If you leave this field empty, xCloud will use the default pull process.

![](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-screen-shot-2026-03-30-at-14.44.37.png)

### Deploy Script

The ‘Deploy Script’ runs after your code is successfully pulled from the repository. To access this, make sure the “Run this script after every site deployment” option is turned on. Enter your scripts under the ‘Deploy Script’ section.

After configuring your scripts, click on the ‘Save Changes’ button to continue.

![](/_landing/docs/how-to-integrate-a-git-provider-with-xcloud-screen-shot-2026-03-30-at-14.46.54.png)

## Options and settings reference

| Option | Behavior |
|---|---|
| **GitHub App: All repositories** | Makes all repositories in the selected GitHub account or organization available to this App installation. |
| **GitHub App: Only select repositories** | Makes only the selected repositories available. Add access in GitHub before attempting to deploy another private repository. |
| **Connection label** | Helps distinguish multiple GitHub connections in one xCloud team. |
| **Git branch** | The branch xCloud pulls and, when enabled, watches for push-to-deploy. |
| **Enable push to deploy** | Creates or uses the deployment webhook so a push can trigger deployment. |
| **Environment file directory** | Controls where xCloud writes the `.env` file for supported non-WordPress deployments. |
| **Git pull script** | Overrides the default repository pull commands. Leave it empty to use xCloud’s default. |
| **Deploy script** | Runs after code is pulled when post-deployment execution is enabled. |
| **Deploy key** | Gives the site SSH access to a private repository. Public repositories cloned over HTTPS do not require one. |

## Verification

The integration is ready when all of the following are true:
- The GitHub connection appears under the team that owns the server.
- The intended repository appears when that connection is selected.
- The site’s **Git** page no longer shows **Deploy Key Required**.
- **Verify Connection** succeeds when manual deploy-key recovery was required.
- The first deployment completes and the deployment history records it.
- If push-to-deploy is enabled, a commit pushed to the selected branch starts a new deployment.
- The deployed site serves from the intended web root and receives its environment values without a committed `.env` file.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| The repository does not appear | The GitHub App uses **Only select repositories**, and this repository was not granted | Open the GitHub App installation settings, add the repository, then refresh the repository list in xCloud. |
| A connection exists, but the server cannot use it | GitHub was connected to a different xCloud team | Switch to the team that owns the server and connect or select GitHub there. |
| Existing-site setup rejects the repository | The repository is unreachable or is not empty | Grant the App access and use an empty repository for the existing-site setup. |
| **Deploy Key Required** remains visible | xCloud could not register the key automatically, or the displayed key has not been added to GitHub | Add the displayed public key under the repository’s deploy keys, then select **Verify Connection**. |
| Cloning does not begin | Deploy-key configuration failed | Complete the deploy-key recovery first. xCloud intentionally does not start cloning after this failure. |
| The deployed page returns a 403 or serves the wrong directory | The web root or build output directory points to the wrong location | Set it to the framework’s public/build directory, then save and redeploy. |
| The app starts without required configuration | Environment values or the `.env` file directory are incomplete | Add the values in xCloud, confirm the environment file directory, and redeploy. Do not commit secrets. |
| A cloned site runs commands against the source path | A copied pull or deploy script contains the old site path | Replace the source path with the current site path before deploying. |

## Common mistakes
- **Connecting GitHub while the wrong xCloud team is selected.** The connection is team-scoped, not account-wide.
- **Assuming organization access grants every repository.** An installation limited to selected repositories exposes only those repositories.
- **Using a non-empty repository for existing-site setup.** xCloud checks the repository before setup to avoid overwriting existing history.
- **Continuing after deploy-key failure.** Repository cloning is blocked until the key is configured and verified.
- **Removing sensitive**`.gitignore`**defaults.** This can expose environment files or basic-auth password hashes.
- **Serving the repository root for frameworks with a public/build directory.** This can expose private files or cause a 403 response.
- **Committing**`.env`**to Git.** Store environment values in xCloud instead.

## Frequently asked questions

### Can one GitHub organization be connected to multiple xCloud teams?

Yes. Each xCloud team keeps an independent connection. Removing one team’s connection does not remove the others.

### Which GitHub connection does a site use?

The site uses a GitHub connection from the xCloud team that owns its server.

### Are GitLab and Bitbucket available?

Not in the current connection dialog. They are shown as **Coming Soon**; GitHub is the available provider documented here.

### Why does xCloud need an empty repository for an existing site?

xCloud pushes the site’s current files as the initial repository content. The empty-repository check prevents that operation from colliding with existing Git history.

### Does a public repository need a deploy key?

No. Public repositories can be cloned over HTTPS. Private repositories require authenticated access, normally through the GitHub App and a deploy key.

## Related documentation
- [Deploy Git projects in one click with xCloud](/docs/deploy-git-projects-in-one-click-with-xcloud/): the single-screen new-site flow with app detection, DNS check and SSL
- [Set up Git integration for an existing WordPress or PHP site](/docs/set-up-git-integration-for-existing-wordpress-or-php-site/): the existing-site flow in more detail
- [Clone a website from a Git repository](/docs/clone-a-website-from-git-repository-with-xcloud/)
- [Deploy custom PHP applications with xCloud](/docs/deploy-custom-php-applications-with-xcloud/)
- [Deploy a custom Docker application from a Git repository](/docs/how-to-deploy-custom-docker-application-from-git-repository/)
- Release notes for the behaviour described here: [v2.6.7](/changelog/v2-6-7/), [v2.7.5](/changelog/v2-7-5/), [v2.7.7](/changelog/v277/), [v2.7.8](/changelog/v2-7-8/), [v2.8.2](/changelog/v2-8-2/) and [v2.8.4](/changelog/v2-8-4/)

If you run into any issues connecting GitHub or deploying, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/).