--- title: "GitHub sync" date: "2026-04-15T15:18:23+00:00" summary: "Set up GitHub bidirectional sync with Source CMS to auto-commit components and keep your site and repository in sync." image: type: "page" url: "/source-cms/github-sync" id: "54211522-ea65-4640-9b16-522f2971e324" --- Table of contents will be added GitHub bidirectional synchronization maintains a continuous connection between your Source CMS site and a GitHub repository. When you publish components in [Drupal Canvas](/source-cms/drupal-canvas "Drupal Canvas"), the system automatically commits them to the repository, and synchronizes any changes pushed to the repository back to the Source CMS site. You connect a site to GitHub directly from the Drupal Canvas editor using the GitHub sync extension, which installs the Source CMS App and handles authentication for you. This guide explains how to configure GitHub bidirectional synchronization for a Source CMS site. Prerequisites ------------- To set up GitHub synchronization, you must have the following requirements: * A Source CMS site. * Administrator access to the Source CMS site, including the **Administer GitHub sync settings** permission. For more information, visit: [Managing roles and permissions](/source-cms/managing-roles-and-permissions "Managing roles and permissions"). * A GitHub account with permission to install the Source CMS 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 Source CMS 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 Source CMS no longer uses a GitHub Personal Access Token (PAT) to connect a site. Authentication is handled by Source CMS 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 Source CMS 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. Source CMS 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, Source CMS 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 Source CMS App is already installed on the organization, Source CMS 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.  Source CMS 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 Source CMS App. After you open the GitHub bidirectional sync extension on such a site, Source CMS 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 Source CMS App is not yet installed, Source CMS 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, Source CMS 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, Source CMS 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**. Source CMS 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 Source CMS 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 Source CMS site and the GitHub repository, be aware of the following workflow triggers: * **Component deletion**: The deletion of a component in a Source CMS 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 Source CMS 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](/source-cms/known-issues-and-limitations "Known issues and limitations") page. Multi-branch support -------------------- Users can connect different Source CMS sites to the same GitHub repository through different branches. The system namespaces secrets for each Source CMS 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 a Source CMS site from its GitHub repository is a permanent action. After you complete this process, you cannot reconnect the Source CMS site to the same branch in the same repository. You can connect to a new branch in the same repository.