--- title: "GitHub sync" date: "2026-04-15T15:18:23+00:00" summary: "Set up GitHub bidirectional sync with Acquia Source to auto-commit components and keep your site and repository in sync." image: type: "page" url: "/acquia-source/github-sync" id: "54211522-ea65-4640-9b16-522f2971e324" --- Table of contents will be added GitHub bidirectional synchronization maintains a continuous connection between your Acquia Source site and a GitHub repository. When you publish components in [Drupal Canvas](https://docs.acquia.com/acquia-source/drupal-canvas), the system automatically commits them to the repository, and synchronizes any changes pushed to the repository back to the Acquia Source site. You connect a site to GitHub directly from the Drupal Canvas editor using the GitHub sync extension, which installs the Acquia Source App and handles authentication for you. This guide explains how to configure GitHub bidirectional synchronization for an Acquia Source site. Prerequisites ------------- To set up GitHub synchronization, you must have the following requirements: * An Acquia Source site. * Administrator access to the Acquia Source site, including the **Administer GitHub sync settings** permission. For more information, visit: [Managing roles and permissions](https://docs.acquia.com/acquia-source/managing-roles-and-permissions). * A GitHub account with permission to install the Acquia Source App on the target GitHub organization or personal account. * A public or private GitHub repository to connect to the site. ### Important considerations for repository branches: * Protected branch rules on the GitHub repository, such as requiring pull requests or status checks to merge, are unsupported. * The synchronization workflow must have permission to push directly to the branch. * You must never delete the branch in synchronization with the Acquia Source site because deletion breaks the bidirectional synchronization. Deletion often happens on pull request merges or when a developer deletes the branch locally and pushes to the remote repository. * Ensure that the GitHub repository setting **Automatically delete head branches** remains unchecked to prevent deletion after pull request merges. Note Acquia Source no longer uses a GitHub Personal Access Token (PAT) to connect a site. Authentication is handled by Acquia Source App. Ensure that you do not create, paste, or rotate a token. If the site was previously connected with a PAT, visit [Migrate an existing Personal Access Token connection](#migrate-existing-pat-connection). Connecting a site to GitHub --------------------------- Users can connect a site to GitHub from within the Drupal Canvas editor. The setup wizard installs the Acquia Source App, lets users choose where to connect, and pushes the initial site files to the repository. To connect a site to GitHub: 1. [Access your site](https://docs.acquia.com/node/69836#access-a-site). 2. On the top right, click **Edit** to open Drupal Canvas. 3. Click the puzzle piece icon to open the **Extensions** menu. 4. Click **GitHub Sync** from the list of extensions. The _Setup GitHub_ dialog box opens. 5. On the _Connect to GitHub_ page, review what the connection provides. The connection provides version control, synchronization, and the ability to deploy from the repository. Select **Connect GitHub Account**. 6. After the _Installing GitHub App_ page opens, complete the authorization in the GitHub dialog box. Acquia Source displays **Waiting for authorization** until the process completes. Note If the GitHub dialog box does not open, allow pop-ups for the site and select **Connect GitHub Account** again. 7. On the _Select Organization_ page, choose the GitHub organization or personal account where you want to install the app and connect the repository. 8. Select **Continue**. 9. On the _Select Repository & Branch_ page, choose a Repository.  Note The branch must not already exist in the repository. Do not connect to a branch that already contains files, for example, a main branch with a README. 10. Enter a name for a new branch.  11. Select **Continue**.  On the _Pushing to GitHub_ page, Acquia Source creates the branch, prepares the files, and pushes the initial site files to the repository. After each step displays **Done**, setup is complete. After setup completes, the extension opens the _Recent Activity_ page. This page confirms the connection and displays the synchronized commit history. Reusing a GitHub organization that already has the app ------------------------------------------------------ If the Acquia Source App is already installed on the organization, Acquia Source displays the _GitHub is already connected_ page after you start the connection.  To connect a site to GitHub: 1. [Access your site](https://docs.acquia.com/node/69836#access-a-site). 2. On the top right, click **Edit** to open Drupal Canvas. 3. Click the puzzle piece icon to open the **Extensions** menu. 4. Click **GitHub Sync** from the list of extensions. The Setup GitHub dialog box opens. 5. Select one of the following: * **Use existing organization** (recommended): Connect this site through the GitHub organization you previously authorized. Additional setup is not required.  Acquia Source continues to the _Select Repository & Branch_ page where you select your Repository and provide a name for your branch.  * **Connect a different organization**: Start a new GitHub authorization to use a different organization or account. To review or change the repository access of the app on GitHub, select **View installation settings**. Migrate an existing Personal Access Token connection ---------------------------------------------------- Sites that were previously connected with a Personal Access Token (PAT) are migrated to the Acquia Source App. After you open the GitHub bidirectional sync extension on such a site, Acquia Source attempts the migration and keeps the existing repository and branch. Depending on the state of the app, you can refer to one of the following: * **Legacy token banner**: If the Acquia Source App is not yet installed, Acquia Source notes that the sync uses a legacy Personal Access Token. Select **Install GitHub Sync App** and complete the authorization to switch to the app. * **Repository access notice**: If the app is installed but does not yet have access to the repository, Acquia Source prompts you to update repository permissions. Select **Update permissions on GitHub**, grant the app access to the repository, and select **Retry**. After migration, authentication is handled by the GitHub Sync App and you do not manage a token. Reconnect after a connection error ---------------------------------- If the connection to GitHub is lost, Acquia Source displays the _Connection error_ page with the message **GitHub connection lost**. Common causes include: * The GitHub Sync App was uninstalled. * Repository access was revoked. * Organization permissions changed. To restore synchronization, select **Reconnect GitHub Account**. Acquia Source disconnects the current setup and returns you to the _Connect to GitHub_ page to connect again. View activity and commit attribution ------------------------------------ The _Recent Activity_ page displays the most recent synchronized commits for the connected repository and branch. Each entry lists the author, a relative timestamp, the commit message, and the email address of the author. To access the _Recent Activity_ page:  1. [Access your site](https://docs.acquia.com/node/69836#access-a-site). 2. On the top right, click **Edit** to open Drupal Canvas. 3. Click the puzzle piece icon to open the **Extensions** menu. 4. Click **GitHub Sync** from the list of extensions. The system displays the _Recent Activity_ dialog box. 5. Select **View on GitHub** to open the commit history of the repository on GitHub. The commit history of the repository on GitHub opens in a new browser tab. Note Commits created from Acquia Source are attributed to the user who selected **Publish**, not to a generic account. The commit message describes what changed. Component synchronization behaviors ----------------------------------- To maintain a consistent state between the Acquia Source site and the GitHub repository, be aware of the following workflow triggers: * **Component deletion**: The deletion of a component in an Acquia Source site does not automatically trigger a synchronization event. * If you delete a component and subsequently publish other changes, such as updating an existing component or adding a new one, the next `source-to-github` workflow pulls all current components and removes the deleted component from the repository. * If you delete a component without publishing additional changes, the workflow does not trigger and the component remains in the repository. In this scenario, a subsequent push from GitHub reinstates all components from the repository back to the Acquia Source site, which effectively recreates the deleted component. * **Component addition**: The addition of a new component to the library does not automatically trigger a synchronization event. * After you add a new code component to the Library through the **Add to components** interface, you must select **Publish**. * You must perform this manual publication action even if the global CSS is the only pending change. * This step ensures that the system triggers the `source-to-github` workflow and commits the new component to the repository. Note The synchronization behaviors outlined in this section are temporary and will be addressed in future releases. For further updates, follow the [Known issues and limitations](/acquia-source/known-issues-and-limitations "Known issues and limitations") page. Multi-branch support -------------------- Users can connect different Acquia Source sites to the same GitHub repository through different branches. The system namespaces secrets for each Acquia Source site by branch name to avoid conflicts. For example, the system stores secrets as follows: * **Main branch**: `MAIN__CANVAS_SITE_URL`, `MAIN__CANVAS_CLIENT_ID`, and `MAIN__CANVAS_CLIENT_SECRET` * **Stage branch**: `STAGE__CANVAS_SITE_URL` The workflow files dynamically resolve required secrets based on the active branch, which removes the need for manual configuration for each branch. Disconnecting GitHub sync ------------------------- Disconnect a repository if you migrate to a new GitHub repository, change organization ownership, or stop synchronization for a specific site. With the GitHub Sync App, you disconnect directly from the editor, and you can reconnect afterward. 1. [Access your site](https://docs.acquia.com/node/69836#access-a-site). 2. On the top right, click **Edit** to open Drupal Canvas. 3. Click the puzzle piece icon to open the **Extensions** menu. 4. Click **GitHub Sync** from the list of extensions. The system displays the _Recent Activity_ dialog box. 5. Click the Kebab menu icon. 6.  Select **Disconnect GitHub**. 7. After prompted to confirm, select **Disconnect**. To keep the connection, select **Cancel**. After you disconnect, the extension returns to the _Connect to GitHub_ page. To synchronize the site again, reconnect and select a repository and branch. Important Disconnecting an Acquia Source site from its GitHub repository is a permanent action. After you complete this process, you cannot reconnect the Acquia Source site to the same branch in the same repository. You can connect to a new branch in the same repository.