GitHub bidirectional synchronization maintains a continuous connection between your Source CMS site and a GitHub repository. When you publish components in 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.
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.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The Setup GitHub dialog box opens.
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.
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.
On the Select Organization page, choose the GitHub organization or personal account where you want to install the app and connect the repository.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The Setup GitHub dialog box opens.
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.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The system displays the Recent Activity dialog box.
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 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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The system displays the Recent Activity dialog box.
Click the Kebab menu icon.
Select Disconnect GitHub.
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.
GitHub sync
GitHub bidirectional synchronization maintains a continuous connection between your Source CMS site and a GitHub repository. When you publish components in 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.
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.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The Setup GitHub dialog box opens.
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.
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.
On the Select Organization page, choose the GitHub organization or personal account where you want to install the app and connect the repository.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The Setup GitHub dialog box opens.
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.
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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The system displays the Recent Activity dialog box.
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 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.
On the top right, click Edit to open Drupal Canvas.
Click the puzzle piece icon to open the Extensions menu.
Click GitHub Sync from the list of extensions.
The system displays the Recent Activity dialog box.
Click the Kebab menu icon.
Select Disconnect GitHub.
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.
Select Continue.
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.
Enter a name for a new branch.
Select Continue.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Select Continue.
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.
Enter a name for a new branch.
Select Continue.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Source CMS