GitHub bidirectional synchronization maintains a continuous connection between your Acquia 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 Acquia Source CMS site. This guide explains how to configure GitHub bidirectional synchronization for an Acquia Source CMS site.
Prerequisites
To set up GitHub synchronization, you must have the following requirements:
An Acquia Source CMS site.
A public or private GitHub repository, which must be completely empty.
Administrator access to the Acquia Source CMS site.
Permission to create GitHub Personal Access Tokens (PATs).
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 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.
Before you create your token, note the following constraints regarding its configuration and expiration:
The system locks the PAT form, and you cannot update the PAT through the Acquia Source CMS site administrator form.
You must choose an expiration with ample time, or choose no expiration if the organization permits it.
If the token expires, synchronization stops, and you must disconnect and reconfigure the setup.
To create a GitHub Personal Access Token (PAT):
Log in to your GitHub account.
Navigate to Settings and click Developersettings.
Click Personal access tokens, and select Fine-grained tokens.
Click Generate new token.
Configure the token with the following settings:
Token name: Enter source-github-sync or any descriptive name.
Expiration: Choose an expiration based on your security needs.
Repository access: Choose the option to select repositories only, and select the target repository.
In the Permissions section, click + Add permissions.
Select the following options and provide their corresponding access levels:
Actions: Select Read and write to trigger workflow dispatches from the Acquia Source CMS site.
Contents: Select Read and write to commit workflow files to the repository.
Workflows: Select Read and write to create or update GitHub Actions workflow files.
Webhooks: Select Read and write to register a webhook for synchronization status reporting.
Secrets: Select Read and write to store Drupal Canvas application programming interface (API) credentials as repository secrets.
Click Generate token.
Step 2: Configure GitHub synchronization in your Acquia Source CMS site
To configure GitHub synchronization in your Acquia Source CMS site:
Log in to Acquia Source.
In the Sites Dashboard, locate the Acquia Source CMS site that you want to synchronize with GitHub.
Click Edit Site.
Note
You must have Acquia Source CMS site administrator permissions.
On the left navigation menu, click Configuration.
Click System and then click GitHub sync settings.
Complete the following fields:
GitHub Repository URL: Enter the full URL of your GitHub repository.
For example, https://github.com/your-org/your-repo. Ensure that you replace the your-org and your-repo placeholders with your actual organization and repository names.
Branch: Enter the branch name for synchronization.
The branch must not already exist in the repository because the setup process creates it.
If left empty, the value defaults to main.
If you intend to use the main branch, ensure that the branch does not exist. This scenario requires an empty repository.
Upon save, Acquia Source validates the credentials and automatically configures your GitHub repository for bidirectional sync.
Important
You can submit the form only one time. After a successful setup, the system locks the form fields, and you cannot change them. If you need to disconnect, refer to Disconnecting GitHub Sync.
Component synchronization behaviors
To maintain a consistent state between the Acquia Source CMS site and the GitHub repository, be aware of the following workflow triggers:
Component deletion: The deletion of a component in an Acquia 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 Acquia 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 Acquia Source CMS sites to the same GitHub repository through different branches. The system namespaces secrets for each Acquia 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.
You might need to disconnect a repository if you migrate to a new GitHub repository, change organization ownership, or permanently stop synchronization for a specific site.
Important
Disconnecting a Acquia Source CMS site from its GitHub repository is a permanent action. After you complete this process, you cannot reconnect the Acquia Source CMS site to a repository.
To permanently disconnect a Acquia Source CMS site from its GitHub repository, you must remove the synchronization configuration directly from GitHub.
Delete the following workflow files from the connected branch in the repository:
.github/workflows/source-to-github.yml
.github/workflows/github-to-source.yml
.github/workflows/canvas-init.yml
Note
If multiple Acquia Source CMS sites connect to the same repository on different branches, you must delete the workflow files from each branch that requires disconnection. Deletion from one branch does not affect other branches.
(Optional) Additionally, you can remove the branch-prefixed secrets from the repository settings.
For example: MAIN__CANVAS_SITE_URL, MAIN__CANVAS_CLIENT_ID, and MAIN__CANVAS_CLIENT_SECRET.
(Optional) Additionally, you can delete the webhook from the repository settings.
GitHub sync
GitHub bidirectional synchronization maintains a continuous connection between your Acquia 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 Acquia Source CMS site. This guide explains how to configure GitHub bidirectional synchronization for an Acquia Source CMS site.
Prerequisites
To set up GitHub synchronization, you must have the following requirements:
An Acquia Source CMS site.
A public or private GitHub repository, which must be completely empty.
Administrator access to the Acquia Source CMS site.
Permission to create GitHub Personal Access Tokens (PATs).
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 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.
Before you create your token, note the following constraints regarding its configuration and expiration:
The system locks the PAT form, and you cannot update the PAT through the Acquia Source CMS site administrator form.
You must choose an expiration with ample time, or choose no expiration if the organization permits it.
If the token expires, synchronization stops, and you must disconnect and reconfigure the setup.
To create a GitHub Personal Access Token (PAT):
Log in to your GitHub account.
Navigate to Settings and click Developersettings.
Click Personal access tokens, and select Fine-grained tokens.
Click Generate new token.
Configure the token with the following settings:
Token name: Enter source-github-sync or any descriptive name.
Expiration: Choose an expiration based on your security needs.
Repository access: Choose the option to select repositories only, and select the target repository.
In the Permissions section, click + Add permissions.
Select the following options and provide their corresponding access levels:
Actions: Select Read and write to trigger workflow dispatches from the Acquia Source CMS site.
Contents: Select Read and write to commit workflow files to the repository.
Workflows: Select Read and write to create or update GitHub Actions workflow files.
Webhooks: Select Read and write to register a webhook for synchronization status reporting.
Secrets: Select Read and write to store Drupal Canvas application programming interface (API) credentials as repository secrets.
Click Generate token.
Step 2: Configure GitHub synchronization in your Acquia Source CMS site
To configure GitHub synchronization in your Acquia Source CMS site:
Log in to Acquia Source.
In the Sites Dashboard, locate the Acquia Source CMS site that you want to synchronize with GitHub.
Click Edit Site.
Note
You must have Acquia Source CMS site administrator permissions.
On the left navigation menu, click Configuration.
Click System and then click GitHub sync settings.
Complete the following fields:
GitHub Repository URL: Enter the full URL of your GitHub repository.
For example, https://github.com/your-org/your-repo. Ensure that you replace the your-org and your-repo placeholders with your actual organization and repository names.
Branch: Enter the branch name for synchronization.
The branch must not already exist in the repository because the setup process creates it.
If left empty, the value defaults to main.
If you intend to use the main branch, ensure that the branch does not exist. This scenario requires an empty repository.
Upon save, Acquia Source validates the credentials and automatically configures your GitHub repository for bidirectional sync.
Important
You can submit the form only one time. After a successful setup, the system locks the form fields, and you cannot change them. If you need to disconnect, refer to Disconnecting GitHub Sync.
Component synchronization behaviors
To maintain a consistent state between the Acquia Source CMS site and the GitHub repository, be aware of the following workflow triggers:
Component deletion: The deletion of a component in an Acquia 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 Acquia 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 Acquia Source CMS sites to the same GitHub repository through different branches. The system namespaces secrets for each Acquia 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.
You might need to disconnect a repository if you migrate to a new GitHub repository, change organization ownership, or permanently stop synchronization for a specific site.
Important
Disconnecting a Acquia Source CMS site from its GitHub repository is a permanent action. After you complete this process, you cannot reconnect the Acquia Source CMS site to a repository.
To permanently disconnect a Acquia Source CMS site from its GitHub repository, you must remove the synchronization configuration directly from GitHub.
Delete the following workflow files from the connected branch in the repository:
.github/workflows/source-to-github.yml
.github/workflows/github-to-source.yml
.github/workflows/canvas-init.yml
Note
If multiple Acquia Source CMS sites connect to the same repository on different branches, you must delete the workflow files from each branch that requires disconnection. Deletion from one branch does not affect other branches.
(Optional) Additionally, you can remove the branch-prefixed secrets from the repository settings.
For example: MAIN__CANVAS_SITE_URL, MAIN__CANVAS_CLIENT_ID, and MAIN__CANVAS_CLIENT_SECRET.
(Optional) Additionally, you can delete the webhook from the repository settings.
Important
Copy the token immediately. GitHub displays the plaintext token only upon creation. Afterward, the system securely hashes the token, and it cannot be recovered.
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Important
Copy the token immediately. GitHub displays the plaintext token only upon creation. Afterward, the system securely hashes the token, and it cannot be recovered.