Skip to main content

Step: 1 Setup Version Control

When setting up a project in Coalesce, you'll need your repository URL and access token. This guide will walk you through:

  • Creating a repo and getting your URL
  • Creating your access token
  • Adding your version control account to Coalesce by creating a Project.
Quick Instructions

If you have experience with version control and want a quick overview, take a look at Set Up Version Control.

Before You Begin​

Coalesce supports the following Git providers:

Video Guides

Each section includes a video walkthrough of all the steps.

GitHub​

GitHub is a web-based platform that provides version control and collaborative software development services using Git. It allows developers to store, manage, and track changes to their code while facilitating collaboration through features like pull requests, issue tracking, and project management tools.

Create Your GitHub Repo​

  1. Go to https://github.com/.

  2. Click the green New button, to create a new repository. It can be found on the homepage or on your profile page under Repositories.

    The image shows the GitHub organization page for Coalesce-Software-Inc, displaying their public repositories section. The page includes navigation tabs, repository listings with two visible repositories (microk8s-actions and snowflake-connector-nodejs), and organization statistics showing 133 repositories, 1 project, and 11 teams.

  3. On the Create a new repository page, choose the Owner, give the repo a name. The name will become part of your URL.

  4. Optionally add a description.

  5. Choose if it should be Public or Private. If you're an GitHub Enterprise customer, you'll have the option for Internal.

  6. Click Create Repository. You shouldn't add a Readme, use a template, or add a .gitignore.

  7. Once created, you'll see your Git URL. For example https://github.com/Coalesce-Software-Inc/data-transformations.git. Select the HTTPS version to use in Coalesce.

.gitignore

Don't add a .gitignore to your repo when creating it. It should be completely empty of all files. This is so Coalesce can initiate the repo correctly. After the repo is initiated, you can create a .gitignore.

These file paths are protected paths and files and should NOT be in the .gitignore and should not be used for anything else.

  • data.yml
  • locations.yml
  • nodes/
  • subgraphs/
  • packages/
  • macros/
  • nodeTypes/
  • environments/
  • jobs/
How to create a new repo in GitHub.

Get Your GitHub Access Token​

  1. Click on your GitHub profile and go to Settings > Developer Settings.

  2. Click Personal access tokens > Fine-grained tokens.

    The image shows a GitHub interface for creating a new fine-grained personal access token. The form includes fields for token name, description, resource owner (set to GitHub user), expiration period (30 days), repository access options (with All repositories selected), and permission settings with repository and account permissions sections visible at the bottom.

  3. Give the token a name and description.

  4. Set the following based on your company policy.

    1. Resource owner
    2. Expiration date
    3. Repository access should be either All repositories or Only select repositories.

  5. Open Permissions > Repository permissions.

  6. Set Contents to Read and write. GitHub will also automatically grant Metadata, which is required.

    The image shows a section of GitHub permissions settings with three permission categories. The "Contents" category is highlighted with a red rectangle and is marked as "Selected" with "Read and write" access enabled. This section controls permissions for repository contents including commits, branches, downloads, releases, and merges. Above it is "Commit statuses" and below are "Custom properties" and "Dependabot alerts" categories, both showing "No access" permission levels.

  7. Save your access token somewhere secure. You won't be able to recover it.

How to create your access token in GitHub

Add Your GitHub Token and Repo to Coalesce​

Review the steps in Add your URL and Token to Coalesce.

Azure DevOps​

Azure DevOps Git is Microsoft's enterprise-grade Git repository service that provides source code management with branch policies, code reviews, and integrated CI/CD pipelines.

Create Your Azure DevOps Repo and Token​

In this step, you'll create your repo and get your URL.

  1. Log in to your organization, for example, https://dev.azure.com/<Your_Organization>.

  2. If needed, create a new Project. Give it a name and description.

    The image shows the Azure DevOps interface with a "Create new project" modal dialog open. In the background, a user profile page for "tjperry07" is visible with tabs for Projects, My work items, and My pull requests, showing a "Coalesce Demo" project with the initials "CD". The dialog prompts for a project name (required field marked with an asterisk), description, and visibility settings. The Private option is selected, with a note indicating "Public projects are disabled for your organization." Git is selected for version control and Basic for work item process.

  3. Then click on Repos.

  4. You'll see your HTTPS repo URL. Save this for use in Coalesce.

  5. You can generate your Git Credentials on this page, but make sure to update the permissions as listed starting in Step 7.

  6. Scroll down to Initialize main branch with a Read or gitignore and uncheck the box.

    The image shows an Azure DevOps repository page for an empty project called "Coalesce Demo." The main content area displays "Coalesce Demo is empty. Add some code!" with several options for getting started: cloning to a local computer (with HTTPS/SSH options), pushing an existing repository from command line, importing a repository, or initializing the main branch with a Readme or gitignore file. The left sidebar contains navigation links for project features like Overview, Boards, Repos, Files, Commits, and Pipelines. The breadcrumb navigation at the top shows the path: Azure DevOps > tjperry07 > Coalesce Demo > Repos > Files.

  7. Go to User settings > Personal access tokens.

  8. If you have an existing token, click Edit on the token you want to use in Coalesce. If there are no tokens, click New Token.

  9. Set the expiration date based on company policy.

  10. Change the Scopes to Custom defined.

  11. Select the following:

    1. Work Items: Read, write, & manage
    2. Code: Read, write, & manage
    3. Packaging: Read, write, & manage

  12. Click Create or Save.

.gitignore

Don't add a .gitignore to your repo when creating it. It should be completely empty of all files. This is so Coalesce can initiate the repo correctly. After the repo is initiated, you can create a .gitignore.

These file paths are protected paths and files and should NOT be in the .gitignore and should not be used for anything else.

  • data.yml
  • locations.yml
  • nodes/
  • subgraphs/
  • packages/
  • macros/
  • nodeTypes/
  • environments/
  • jobs/
How to create a project and add create your PAT.

Add Your Azure Token and Repo to Coalesce​

Review the steps in Add your URL and Token to Coalesce.

Bitbucket​

Bitbucket is Atlassian's Git-based code hosting and collaboration platform. It offers both cloud and self-hosted options with features for code review and CI/CD pipelines.

Create Your Bitbucket Repo and URL​

  1. From the Workspace Overview, click Create and select Repository.

    The image shows a Bitbucket dashboard interface with the "Your work" tab selected. The page displays "coalesce-demo-docs" at the top, followed by a "Recent repositories" section showing two repositories: "demo" and "coalesce-data-pipeline," both under the coalesce-demo-docs project. A "Pull requests" section appears at the bottom, and a dropdown menu from the "Create" button in the top-right corner shows options to create a Repository, Project, or Snippet.

  2. On the Create a new repository page, fill out the repo details.

    1. Include a README? is No.
    2. Include .gitignore? is No.
    The image shows a Bitbucket Create a new repository form. The workspace is set to coalesce-demo-docs with fields for selecting a project, entering a repository name, and configuring settings. The form includes options for privacy (Private is checked), adding a Readme (No), specifying a default branch name, and including a .gitignore file (No). There's also a collapsible Advanced settings section and buttons for Create repository and Cancel.

  3. On the Repo page, you can find the URL in the HTTPS box or under Step 2: Connect your existing repository to Bitbucket.

    The image shows a Bitbucket repository page for a newly created demo repository. The main area displays Let's put some bits in your bucket with instructions for getting started. It shows options to clone the repository via HTTPS, create a Readme or .gitignore file, and provides step-by-step commands for connecting a local Git repository to Bitbucket. The left sidebar contains navigation links for Source, Pipelines, Deployments, Jira issues, and other repository management options.
Create your repo and get your repo URL
.gitignore

Don't add a .gitignore to your repo when creating it. It should be completely empty of all files. This is so Coalesce can initiate the repo correctly. After the repo is initiated, you can create a .gitignore.

These file paths are protected paths and files and should NOT be in the .gitignore and should not be used for anything else.

  • data.yml
  • locations.yml
  • nodes/
  • subgraphs/
  • packages/
  • macros/
  • nodeTypes/
  • environments/
  • jobs/

Get Your Bitbucket API Token​

Bitbucket requires an API Token.

Bitbucket Cloud Removing App Passwords

As of September 9, 2025 Bitbucket no longer allows the creating of app passwords. New integrations will require an API token. On June 9, 2026 all existing app passwords will stop working.

Learn more in Bitbucket Cloud enters phase two of app password deprecation

  1. Go to Settings and select Atlassian account settings.
  2. Select Security.
  3. Scroll to API tokens.
  4. Click Create and manage API tokens.
  5. Click Create API token with scopes.
  6. Select Bitbucket as the app.
  7. In the search box type repository. Select:
    1. read:repository:bitbucket
    2. write:repository:bitbucket
  8. Review the information is correct and click Create token.
  9. Copy the token since it won't be shown again.
Bitbucket account settings page highlighting Atlassian account settings option under personal settings Atlassian account security settings page showing change password fields two step verification option and link to create and manage API tokens
Create your API token in Bitbucket

Add Your Bitbucket API Token and Repo to Coalesce​

Review the steps in Add your URL and Token to Coalesce.

GitLab​

GitLab is an open-core DevOps platform that provides a complete software development lifecycle tool with integrated Git repository management, CI/CD, monitoring, and security features.

Create Your GitLab Repo and URL​

  1. From the Projects page, click New Project.

  2. Create a Blank project.

  3. On the Create blank project page, make sure to uncheck Initialize repository with a Readme.

  4. Click Create project.

    A GitLab interface showing the "Create blank project" form with "coalesce-demo" entered as the project name. The form includes fields for project URL, slug, deployment target, visibility level (with Private selected), and project configuration options with a highlighted section about initializing the repository with a Read e.

  5. On the project page, scroll down to Add files, and change the tab to HTTPS. Copy your repo URL.

    A GitLab project setup page for a newly created "coalesce-demo" repository. The page shows Git configuration commands, repository setup instructions with tabs for SSH and HTTPS methods, and code snippets for creating a new repository or pushing an existing folder. The right panel displays project information, team invitation options, and file creation shortcuts.
.gitignore

Don't add a .gitignore to your repo when creating it. It should be completely empty of all files. This is so Coalesce can initiate the repo correctly. After the repo is initiated, you can create a .gitignore.

These file paths are protected paths and files and should NOT be in the .gitignore and should not be used for anything else.

  • data.yml
  • locations.yml
  • nodes/
  • subgraphs/
  • packages/
  • macros/
  • nodeTypes/
  • environments/
  • jobs/
Create your repo and get your URL in GitLab

Get Your GitLab Access Token​

  1. Click your avatar and select Preferences.

  2. Select Access tokens.

  3. Under Personal access tokens, click Add new token.

    A GitLab user settings page displaying the Personal access tokens section. The interface shows "This user has no active personal access tokens" in the table, with Access tokens highlighted in the left sidebar and an "Add new token" button highlighted in red on the right side.

  4. Give the token a name.

  5. Select the scopes:

    1. read_repository
    2. write_repository
    A GitLab page showing the form to add a personal access token. The form includes fields for token name, description, expiration date, and scope selection options. The read_repository and write_repository permissions are checked, with create and cancel buttons at the bottom.

  6. Create personal access token. Make sure to save this some where secure.

How to get your GitLab access token.

Add Your GitLab Token and Repo to Coalesce​

Review the steps in Add your URL and Token to Coalesce.

Add Your Token and Repo To Coalesce​

These instructions show you how to add your token and repo URL to your Project in Coalesce. The steps are the same for each provider.

After you have your access token, you need to add it to Coalesce and connect your Git account. You can do this as part of creating a project or by adding it your User Settings. In this example, we'll add it while creating a 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 your Version control repository URL.

    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. On the next page, Click Add New Account.

    1. Enter an account nickname. This will displayed in the interface.
    2. Enter your token. This will be either the GitLab token, Git token, Azure token, or Bitbucket App Password.
    3. Enter the Author Name, which identifies the committer. This doesn't have to match your version control account.
    4. Enter the Author Email, which identifies the committer email. This doesn't have to match your version control account.
    5. Click Add.
    A form interface for adding a version control account with empty input fields. The form includes required fields for Account Nickname, Username, Token, Name, and Email, with explanatory text beneath each field and Cancel and Add Account buttons at the bottom.

  6. Select the Git account you just created in the drop down, then click Test Account.

    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.

  7. Then click Finish to create your Project.

How to create a project and add your version control information.
tip

You can move to Step 3: Create a Workspace since you've already created a Project in this step.

What's Next​

  • Make sure each user is added to the repo.
  • Each user needs to create an access token and update their Git Account in Coalesce. They can follow the instructions for each provider on creating a token. They can go to User Settings > Version Control Accounts.