You can sync your Paragon project with GitHub using Git Sync, allowing you to easily incorporate Paragon into your version control and code review processes. When Git Sync is enabled, any changes made to your integrations or workflows in the Paragon dashboard will automatically sync to your connected Git repository as Paragraph files.

​
How Syncing Works

Git Sync works by automating CLI commands with GitHub Actions, in response to change events in Paragon or in your Git repository. You can opt into a bidirectional sync or a one-way sync, depending on what works best for your team:
  • Bidirectional Sync: Both engineering and non-engineering team members will be working on integrations development, editing in both code and the workflow editor.
  • One-Way Sync from Git -> Paragon: Paragraph code will be the source of truth, and updates to integrations will strictly be made in code. Works best when only engineering team members will be working on integrations development, or where advanced patterns like higher-order steps or modular workflow fragments are required.
  • One-Way Sync from Paragon -> Git: Paragon dashboard will be the source of truth, and updates will sync back to Git as a more fine-grained form of version control.
Limitations
  • If you are using advanced patterns in Paragraph, such as reusable steps, higher-order steps, or modular workflow fragments, Git Sync currently cannot recover the use of these abstractions in code.
  • When making updates in a dashboard to a workflow that is using advanced patterns in Paragraph, the advanced pattern will be a replaced with an inline representation of the resulting steps.
  • If these limitations affect you, you can opt in to a one-way Git Sync from Git -> Paragon.

​
Setup

​
Repository Setup

First, we’ll need to set up a GitHub repository to sync your integrations with.
  1. If you don’t already have one, create a new GitHub repository. This repository can be public or private.
  2. Push the contents of your initialized Paragraph project to your repository: Exporting from Paragon.
  3. Add and commit new files called .github/workflows/paragraph-push.yml and .github/workflows/paragraph_pull_runner.yml at the root of your repository with the contents of the GitHub Actions Workflow Files below.
  4. Navigate to your GitHub repository and select Settings. Navigate to Secrets and Variables > Actions.
  5. Create a repository secret for PARAGON_CLI_KEY. You can find this value on your machine in the file ~/.paragon/credentials.json. It will be the value within token in this file.

​
Token Setup

Next, you’ll need to generate a GitHub Personal Access Token (PAT) to use in the Paragon dashboard.
  1. In GitHub Developer Settings, click the Fine-grained Tokens section in the Personal Access Tokens sidebar.
  2. Generate a new token. Specify a descriptive name like “Paragon Git Sync” and desired expiration.
  3. Select the repository owner/organization as the Resource Owner of the token. If your organization is not appearing in the list of available Resource Owners, you may need to ask your GitHub organization admin to allow PATs in your organization (see GitHub docs).
  4. Select your intended integrations repository in Repository Access.
  5. Select the following Permissions: Actions: Read and write Contents: Read only Metadata: Read only Members: Read only The Overview of the Permissions should look like:
  1. Generate the token.
  2. In the Paragon dashboard, click “Sync Git Branch” in the top navigation bar.
  3. Paste your PAT and press Connect.
  4. Select a repository to sync Paragon with.
  5. Select which branch of your Git repository your Paragon project should sync with. Each Paragon project can be associated with a different branch in your Git repository.
Note: If your fine-grained PAT requires admin approval, you will immediately receive a generated token value, but the permissions will not be granted until the admin approves the token. Please verify that your token has been approved before proceeding.
Git Sync works with both classic and fine-grained PATs, but we recommend using a fine-grained PAT to generate a token with least-access privileges. See below for classic token instructions.

​
Syncing Changes

As you make changes to your integrations in the Paragon dashboard, your changes will be synced as commits to your connected Git repository. Workflow changes can be synced immediately by clicking Options > Save Version in the Workflow Editor. You can view the sync history for your Paragon project by clicking the Sync Status icon in the navigation bar of the Paragon dashboard.
If you are not seeing changes appear in the dashboard or in your Git repository, verify your token permissions in Token Setup.

​
Resetting the Repository

If you need to reset the original repository you chose for syncing with Paragon, please contact our support team. You can reach us at [email protected].