Skip to main content

Set Up Version Control

You’ll set up version control when creating a new project in Coalesce.

Git Requirements

Review Coalesce Git Requirements before starting.

Get an Authentication Token

Many cloud Git providers have transitioned from traditional username and password authentication for remote repository access to a more secure method known as token authentication or Personal Access Tokens (PAT). Coalesce requires a PAT.

Git Fields

You’ll need the following information ready to connect your account.

FieldDescriptionExample
Account NicknameFriendly description of this git accountGitHub
Git UsernameYour git username/account namejack-bauer
TokenThe git user's authorization tokenghp_abcdefghijklmnopqrstuvwxyz0123456789
Author NameName of the git userJack Bauer
Author EmailThe git user's emailjack.bauer@example.com

Git Username in Repo URL

By default, some Git providers include a Git username in the repo URL. Example https://myusername@bitbucket.org/customer_projects/my-edw.git.

While URLs like this are currently allowed, any authentication information in them is ignored since git URLs can be shared across multiple Coalesce users.

Coalesce will instead use the value of Git Account when authenticating.

Git Author Information

The Author Name and Email in your Git Settings do not have to match the name and email that are registered on your Git Account. No verification is completed on these values. These two values, Author Name and Author Email, are used when making commits to your Git repository to identify the person who made the commit.

The Git username you input in your Git Settings must match your username in your Git provider.

Self-Hosted Git Repo

Your self-hosted repository used with Coalesce must be accessible on the public internet.

Git Requirements

Before setting up self-hosted repository, review the Coalesce Git Requirements.

Allowed IP Addresses For Your Git Provider

If you are using allowed IP addresses or using a self-hosted instance with a firewall, review Network Requirements to allow inbound traffic from Coalesce.

New Repository and Project

Follow these steps if you want to add a new repository to Coalesce

Step 1: Create a Repository

Follow the instructions for your Version Control Provider. Make sure to skip the step to create a Readme or add a .gitignore. The repo must be empty.

Repository Must Be Empty

When adding a new repository to Coalesce, it must be empty. This includes Readme and .gitignores.

When you make your first commit to Coalesce, it will include Node metadata. Do not delete this data. Review What Gets Committed.

Step 2: Create a New Project

  1. Go to the Project page. If you are on the Build page , click the back arrow.

  2. Click the plus sign(+) next to Projects.

    Projects interface showing 'Default Project' with two workspaces: Development (branch: main) and Docs Testing (branch: understanding_commits). Each workspace has Launch button and settings icons. Top navigation includes Project Settings and Create Workspace options.
  3. Enter the Project name and description. Click Next.

    Project creation form (Step 1 of 3) showing required Name field with validation error and optional Description field. Navigation buttons for Previous and Next steps shown at bottom.
  4. Enter you version control repository URL. You can Skip and Create to start using the project, but you won't be able to deploy.

    1. Coalesce supports many providers.
    Version control setup page (Step 2 of 3) for Coalesce project creation. Shows required Git repository URL input field with explanation that repository will be shared across workspaces and users. Includes 'Skip and Create' option and Previous/Next navigation buttons.
  5. Then select an account to use. It should be able to view and make requests to the Git repo in the previous step.

    Git account configuration page (Step 3 of 3) showing repository URL, Git account dropdown set to 'Coalesce Docs', and options to add new account or test existing account. Includes Previous and Finish buttons.
  6. If you don't a repo configured, then click Add New Account.

    1. Enter an account nickname. This will displayed in the interface.
    2. Enter the Git username and token. This will be either the GitLab, Git, Azure, or Bitbucket App Password.
    3. Enter the Author Name, which identifies the committer.
    4. Enter the Author Email, which identifies the committer email.
    5. Click Add.
    6. Select the Git account you just created in the drop down, then click Test Account.
  7. Once successful, click Finish.

  8. Now that you've added a Project, you need to add a Workspace.

Existing Project

There are two places you can add Git to an existing project, either through the Problem Scanner or the Project Dashboard.

What Is an Existing Project?

An existing project is one that was created with Coalesce. Attempting to add data from other sources will result in an error.

Add Git Using the Problem Scanner

Go to your Development Workspace, click the relevant Problem Scanner entry, then follow on-screen prompts to edit URL and select the desired git account for that Workspace Project.

Coalesce problem scanner

Add Through the Project Dashboard

Next to Create Workspace, select the ellipses and Configure Git Account.

Add Git through the dashboard