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 Installing 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.

GitHub sync troubleshooting guide