GitHub bidirectional synchronization maintains a continuous connection between your Acquia Source 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 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.
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.
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.
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.
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.
On the Select Organization page, choose the GitHub organization or personal account where you want to install the app and connect the repository.
Select Continue.
On the page, choose a Repository.
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.
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.
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.
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.
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 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 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.
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 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.
GitHub sync
GitHub bidirectional synchronization maintains a continuous connection between your Acquia Source 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 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.
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.
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.
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.
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.
On the Select Organization page, choose the GitHub organization or personal account where you want to install the app and connect the repository.
Select Continue.
On the page, choose a Repository.
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.
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.
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.
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.
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 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 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.
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 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.
Select Repository & Branch
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 Repository & Branch
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.
Acquia Source