---
title: "GitHub sync troubleshooting guide"
date: "2026-06-30T14:19:54+00:00"
summary: "Fix GitHub sync errors fast with Source CMS. Resolve popup blocks, auth failures, repo access issues, and connection drops step by step."
image:
type: "page"
url: "/source-cms/github-sync-troubleshooting-guide"
id: "d625f87e-1c73-4625-8d3e-2b234d57d77e"
---

Table of contents will be added

This document is a troubleshooting guide for common issues when connecting a site to GitHub through Source CMS.

Popup blocked
-------------

**Location**: The _Setup GitHub_ dialog box.

**Symptom**: An error message displays with the notification: Popup blocked. Allow popups for this site and try again.

Cause: The browser prevents the GitHub authorization window from opening. Most browsers block popups by default unless they are explicitly allowed.

**Resolution:**

To fix the blocked popup, do the following:

1.  Locate the popup-blocked icon in the address bar of the browser. This icon typically resides on the right side.
2.  Click the icon and choose **Always allow popups from this site**.
3.  Click **Connect GitHub Account** again.

If the popup-blocked icon is not visible, verify the browser settings under **Privacy** or **Content** and add this site to the allowed list.

Popup closed before installation completed
------------------------------------------

**Location**: On the _Installing GitHub App - Waiting for authorization_ dialog box.

**Symptom**: An error message displays with the notification: The popup was closed before installation completed. Try again.

**Cause**: The GitHub authorization window closed before the installation of GitHub App completed. This closure occurs manually or by the browser.

**Resolution**:

To fix the closed popup issue, do the following:

1.  Click **Try** **again**.
2.  Complete the full installation flow in the popup. 
3.  Select the organization and choose repository access
4.  Click **Install**.

Wait for the popup to close after the system confirms the installation.

Installation is taking too long
-------------------------------

**Location**: On the I_nstalling GitHub App — Waiting for authorization_ dialog box.

**Symptom**: An error message displays with the notification: Installation is taking too long. Try again.

Cause: The system waited 5 minutes for the GitHub App installation to complete but did not receive a confirmation. This occurs because of network issues or an idle _GitHub authorization_ dialog box.

**Resolution**:

To fix the installation timeout, do the following:

1.  Click **Try again**.
2.  Complete the authorization promptly in the popup window.

If the problem persists, verify the network connection and try again.

Installation failed or was cancelled
------------------------------------

**Location**: On the _Installing GitHub App - Waiting for authorization_ dialog box.

**Symptom**: An error message displays with the notification: Installation failed or was cancelled. Try again.

**Cause**: GitHub reported an unsuccessful App installation. This occurs if a user clicks **Cancel** on the _GitHub authorization_ dialog box or if an error occurs on the GitHub platform.

**Resolution**:

To fix the failed or cancelled installation, do the following:

1.  Click **Try again**.
    *   Ensure that you click **Install** on the _GitHub authorization_ dialog box. 
    *   Do not click **Cancel**.
    *   If the issue persists, verify the permission to install apps in the target GitHub organization. 
    *   An organization administrator must approve the installation if required.

App lacks access to the repository
----------------------------------

**Location**: During migration from a Personal Access Token (PAT) and after the installation of GitHub App, on the dialog box that displays an access denied error with an **Update permissions on GitHub** link.

**Symptom**: A message displays with the notification: GitHub App doesn't have access to the repository name with a link to update permissions on GitHub.

**Cause**: GitHub App installed successfully but lacks access to the specific repository the site uses. This occurs in the following scenarios:

*   The user clicked **Only select repositories** during installation and excluded the correct repository.
*   The repository resides in a different organization from the organization where the app was installed.

**Resolution**:

To fix the repository access issue, do the following:

1.  Click the **Update permissions on GitHub** link to open the GitHub App installation settings.
2.  Under **Repository access**, click **All repositories** or add the specific repository to the clicked list.
3.  Click **Save**.
4.  Return to the extension and click **Retry**.

To start over and install the app in the correct organization, click **Back**.

GitHub connection lost
----------------------

**Location**: On the dialog box that normally displays recent activity, a GitHub connection lost message displays instead.

**Symptom**: A GitHub connection lost screen lists common causes. For example, token expired, access revoked, network issues, or permissions changed.

**Cause**: The previously working GitHub connection stopped functioning. This indicates the following possibilities:

*   GitHub App was uninstalled from the organization.
*   The access of GitHub App to the repository was revoked.
*   The organization suspended the GitHub App.

**Resolution**:

To fix the lost connection, do the following:

1.  Click **Reconnect GitHub Account** to start a fresh connection.
2.  Reinstall GitHub App when prompted and grant access to the repository.
3.  Configure the repository and branch settings again.

If reconnecting fails, verify the installed apps dialog box of the GitHub organization to confirm the Acquia GitHub App remains active and maintains access to the correct repository.

Setup failed when creating the branch
-------------------------------------

**Location**: On the dialog box where users choose a repository and branch name. After clicking **Continue**, the system returns to this dialog box with an error.

**Symptom**: After clicking a repository and branch name and clicking Continue, the Pushing to GitHub screen displays briefly. The system then returns to the repository/branch form with an error message. For example, Setup failed: unable to create branch. Previous selections are preserved.

**Cause and Resolution**:

*   **Branch already exists**: A branch with that name already exists in the repository. Choose a different branch name and click **Continue** again.
*   **No write access**: GitHub App lacks write permission to the repository. Navigate to the app installation settings of the GitHub organization, ensure the repository is included, and verify the app possesses read/write access. Then retry.
*   **Branch protection rules**: The repository enforces rules that prevent the creation of new branches. Request a repository administrator to adjust branch protection settings, or choose a different repository.

If none of these apply, click **Back** to return to the connect screen and start over.

GitHub displays Configure instead of Install for the account or organization
----------------------------------------------------------------------------

**Location**: In the GitHub popup that opens after clicking Connect GitHub Account or Connect a new organization.

**Symptom**: The popup opens to the _Install \[App Name\]_ dialog box of GitHub, listing accounts and organizations. Next to one or more options, **Configure** displays instead of a clickable option to install. Clicking **Configure** navigates to the installation settings dialog box of GitHub, which does not redirect back to the site. The extension remains stuck on Installing GitHub App - Waiting for authorization.

**Cause**: GitHub App is already installed in that account or organization. GitHub restricts app installation to one per account or organization. This typically happens when:

*   A user previously connected a different site that triggered an installation of the app in that GitHub organization.
*   An organization administrator installed the app directly from GitHub Marketplace.

Because no new installation occurs, GitHub never redirects back to Source CMS, and the extension never receives the required confirmation.

**Resolution**:

To fix the configuration loop, do the following:

1.  Do not click **Configure**. Close the popup window.
2.  Close the GitHub Sync extension panel.
3.  Reopen the GitHub Sync extension. The extension detects the existing installation and displays the GitHub is already connected screen with the organization name.
4.  Click **Use existing organization** to proceed.

To install the app in a different organization, click that organization from the list in the dialog box instead of closing it.

Cannot add repository to an existing installation
-------------------------------------------------

**Location**: On the dialog box where users choose a repository, after clicking **Don't see your repository?**.

**Symptom**: After clicking **Use existing organization**, the repository selection dialog box does not list the repository. Clicking **Don't see your repository?** results in one of the following:

*   Opens GitHub installation settings, but the user lacks permission to change them.
*   Displays a 404 page not found error because the installation belongs to a different user or organization.
*   Displays a permission error because the user lacks administrator access to manage the app installation for the organization.

**Cause**: GitHub App is already installed in the organization, but it was configured with **Only select repositories** and excludes the needed repository. Only the user who installed the app or a GitHub organization administrator can modify the repositories the app can access. If the installation was created by another user or from a different Acquia site, visibility into the installation may be restricted.

**Resolution**:

To fix the repository addition error, do the following:

1.  Request the GitHub organization administrator or the original installer to add the required repository under the app installation settings within **Repository access**.
2.  After the repository is added, return to the extension and click **Refresh** next to the repository list.

Alternatively, if administrator access exists for a different organization that contains the repository, click **Back** to clear the current installation. Then click **Connect GitHub Account** and choose **Connect** **a new organization to install the app** in that organization.

Repository is missing in the list
---------------------------------

**Location**: On the dialog box where users choose a repository and branch name.

**Symptom**: The Click Repository & Branch screen loads but excludes the repository.

**Cause**: GitHub App only accesses repositories explicitly granted during installation. If the user chose **Only select repositories**, unlisted repositories do not appear.

**Resolution**:

To fix the missing repository issue, do the following:

1.  Click the **Don't see your repository?** link below the list.
2.  This action opens the GitHub App installation settings.
3.  Add the missing repository under Repository access.
4.  Click **Save** on GitHub.
5.  Return to the extension and click **Refresh** next to the repository list.

App installed in the wrong organization
---------------------------------------

**Location**: On the dialog box where users choose a repository, but the listed repositories are incorrect.

**Symptom**: Installation completes, but the listed repositories belong to an unintended organization.

**Resolution**:

To fix the incorrect organization installation, do the following:

1.  Click **Back** on the repository selection screen.
    
    This action clears the current installation.
    
2.  Click **Connect GitHub Account** again.
3.  In the popup, ensure that you click the correct organization before clicking Install.

If the app was previously installed and the GitHub is already connected screen displays, choose **Connect a new organization** instead of **Use existing organization**.