---
title: "GitHub sync"
date: "2026-04-15T15:18:23+00:00"
summary:
image:
type: "page"
url: "/acquia-source/github-sync"
id: "54211522-ea65-4640-9b16-522f2971e324"
---

GitHub bidirectional synchronization maintains a continuous connection between your Acquia Source CMS site and a GitHub repository. When you publish components in [Drupal Canvas](https://docs.acquia.com/acquia-source/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)
---------------------------------------------------

Important

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):

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

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.
    *   **Personal Access Token (PAT)**: Enter the PAT copied in [Step 1: Create a GitHub Personal Access Token (PAT)](#create-github-pat).
7.  Click **Save configuration**.

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](#disconnect-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](/acquia-source/known-issues-and-limitations "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.

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.

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.

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.