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.

Step 1: Create a GitHub Personal Access Token (PAT)

To create a GitHub Personal Access Token (PAT):

1. Log in to your GitHub account.
2. Navigate to Settings and click Developer settings.
3. Click Personal access tokens, and select Fine-grained tokens.
4. Click Generate new token.
5. 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.
6. In the Permissions section, click + Add permissions.
7. 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.
8. Click Generate token.

Step 2: Configure GitHub synchronization in your Acquia Source CMS site

To configure GitHub synchronization in your Acquia Source CMS site:

1. Log in to Acquia Source.
2. In the Sites Dashboard, locate the Acquia Source CMS site that you want to synchronize with GitHub.
3. Click Edit Site.
   Note

   You must have Acquia Source CMS site administrator permissions.

4. On the left navigation menu, click Configuration.
5. Click System and then click GitHub sync settings.
6. 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.

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.

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.

Disconnecting GitHub sync

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.

To permanently disconnect a Acquia Source CMS site from its GitHub repository, you must remove the synchronization configuration directly from GitHub.

1. 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.

2. (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.

3. (Optional) Additionally, you can delete the webhook from the repository settings.

GitHub sync