Git Providers

Easily checkout code in your pipelines

Creating an account with Codefresh using one of the supported Git providers (GitHub, GitLab, Bitbucket) gives you immediate access to the repositories of the linked provider.

You can add repositories from the other git providers regardless of the one that you used for sign-up. For example, you can use GitLab to sign up with Codefresh, but still build repositories that exist in Bitbucket.

You can even add multiple accounts from each Git provider (if you have more than one) allowing you to use Codefresh as a central CI/CD solution that can access all your Git repositories regardless of the backing Git provider.

Currently Codefresh supports:

  • GitHub Cloud
  • GitHub On premises
  • Bitbucket
  • GitLab Cloud
  • GitLab On premises
  • Azure DevOps Git
  • Atlassian Stash (old version of Bibucket Server)
  • Bitbucket Server (new version of Stash)

Atlassian Stash/Bitbucket server as well as the on-premises version of GitLab and GitHub are only available to Codefresh enterprise customers.

Adding more Git providers to your Codefresh Account

By default, you have direct access to Git repositories that exist in the Git provider that you used while signing up for Codefresh. You can easily create Codefresh projects that checkout code from that Git provider without any extra configurations.

To add additional Git providers, go to your Account Configuration, by clicking on Account Settings on the left sidebar. On the first section called Integrations click the Configure button next to Git providers.

Codefresh Account Integration

You can add a new Git provider using the Add Git provider drop-down.

Add Git provider

Add Git provider

For each Git provider you need to setup authentication, so Codefresh can get access to the public and private repositories of the respective platform.

The easiest way to setup authentication is with OAuth2 if supported by the Git provider. You only need to name your integration and Codefresh will automatically set it up once you accept the permissions required. If you have problems with OAuth2 or the provider does not support it, you need to manually create credentials by yourself in your git account and then enter them into Codefresh.

In the case of an on-premises GIT provider you also need to fill in the URL where the provider is installed.

SSH Keys

You have the ability to specify whether you want to clone via HTTPS or SSH. Under the General menu, simply toggle to your desired option.

Git SSH Options

Git SSH Options

For SSH, paste your raw, private key into the SSH Key text box and click save.

For more information on generating SSH keys and adding your public key to your VCS provider, see its official documentation:

GitHub

For the OAuth2 method you only need to decide on public/private repository access, enter a name for your connection and click Save. Then accept the permissions dialog. This is the easiest and recommended way to integrate GitHub. Notice that if you used GitHub when you created your Codefresh account, this integration is already setup for you.

For the Access Token method you need

  • A friendly name for the Git context (it can be anything you want)
  • An access token

Note that the access token for an organization should be created by somebody who has Owner role and not just Member role.

To create an access token, go to your GitHub settings and select the Developer settings option from the left sidebar. Then select Personal access tokens from the left menu. For more information see the GitHub Documentation page

The “token description” you enter in your GitHub account in order to create the token is completely arbitrary (use “Codefresh” for an example). Once you have the token, paste it in the Codefresh UI and click Test connection. If everything is OK, you can now save the Git integration.

The minimum permissions for the token are:

  • repo.*
  • admin:repo_hook.*

GitHub permissions

GitHub permissions

For GitHub on-premises you also need to provide the URL of the GitHub server in your organization. If enabled in your account you can setup Pipeline definition restrictions by expanding the YAML Options segment.

Using External Secrets for GitHub Token

If your GitHub installation is behind your firewall, you can also use any external secrets that you have defined (such as Kubernetes secrets) as values by entering a secrets value with the same syntax shown in pipelines.

For example if you already have a token on a resource call git-credentials you can put in the token field the expression ${{secrets.git-credentials.token}}.

Level of Access

When the admin clicks off “Allow access to all users” another toggle appears; “Allow these credentials to be shared within a pipeline for cloning a repository“

  1. When its turned on, the user that runs a pipeline will be able to clone the repo.
  2. When its turned off, the user that runs a pipeline cannot use this integration. In both cases, the user cannot decrypt the token used in Git integration with CLI or API.

Important note: The credentials will be shared only to clone repos using an official git-clone step.

GitHub-App

An alternative way to authenticate with Github is via the App mechanism.

Codefresh Github App

Note: The Codefresh App only has READ permissions to code, commit statuses, issues, metadata, and pull requests. Also, READ and WRITE to repository hooks. If You need additional permission for your integration, use the Manual Creation steps.

Step 1 - Visit https://g.codefresh.io/account-admin/account-conf/integration/git in Codefresh, add a new Git provider, and choose Codefresh Github App from the drop-down menu

Step 2 - Select the text Github Marketplace in the text above the Installation ID field

Step 3 - Follow the instructions on GitHub to install the application.

Step 4 - Once done, the fields will be populated with the information automatically.

Step 5 - Click Test connection to verify your integration and apply your changes with the Save button.

Manual Creation

Step 1 - Log in your Github account and visit https://github.com/settings/apps. Click the New GitHub App button.

Step 2 - On the New app screen

  1. Give an arbitrary name to your app (e.g. codefresh-integration)
  2. Fill Homepage URL with http://www.codefresh.io
  3. Uncheck the Active checkbox under the Webhook section
  4. In the Repository permissions section give the minimum of
    • Contents - read
    • Issues - read
    • Metadata - read
    • Pull requests - read
    • Webhooks - read, write
    • Commit statuses - read, write
    • Email addresses - read
  5. Click the Create GitHub app button.

Step 3 - In the next screen

  1. Note down the App ID number under the About section
  2. Click the Generate a private key button and save the file locally

Step 4 - Click the Install App item from the left sidebar menu and then click the Install button next to your codefresh app

Step 5 - Accept the permissions and in the next screen define the repositories that you need Codefresh to access

Also from the URL of the browser note the ending number (this is your installation id). For example if the URL is https://github.com/settings/installations/10042353 then your installation number is 10042353

Step 6 - Visit https://g.codefresh.io/account-admin/account-conf/integration/git in Codefresh, add a new Git provider and choose Github App from the drop-down menu

For the required fields use:

  • Installation id - found in step 5
  • App ID - found in step 3
  • Private key - the contents of the file your created in step 3 (but convert it to base64 first)

Click Test connection to verify your integration and apply your changes with the Save button. If enabled in your account you can setup Pipeline definition restrictions by expanding the YAML Options segment.

GitLab

For the OAuth2 method you only need to enable private repository access, enter a name for your connection and click Save. Then accept the permissions dialog. This is the easiest and recommended way to integrate GitLab. Notice that if you used GitLab when you created your Codefresh account, this integration is already setup for you.

For the Access Key method you need:

  • A friendly name for the Git context (it can be anything you want.)
  • An access token/key

To create an access token, go to your GitLab settings and select the Access tokens options. For more information see the GitLab Documentation page

The name you enter in order to create the token in the GitLab UI is completely arbitrary (use “Codefresh” for an example)

Once you have the token, paste it in the Codefresh UI and click Test connection. If everything is OK can now save the Git integration.

For GitLab on-premises you also need to provide the URL of the GitLab server in your organization. If enabled in your account you can setup Pipeline definition restrictions by expanding the YAML Options segment.

Using External Secrets for GitLab Token

If your GitLab installation is behind your firewall, you can also use any external secrets that you have defined (such as Kubernetes secrets) as values by entering a secrets value with the same syntax shown in pipelines.

For example if you already have a token on a resource call git-credentials you can put in the token field the expression ${{[email protected]}}.

Bitbucket

For the OAuth2 method you only need to enter a name for your connection and click Save. Then accept the permissions dialog. This is the easiest and recommended way to integrate Bitbucket. Notice that if you used Bitbucket when you created your Codefresh account, this integration is already setup for you.

For the Application Password method you need:

  • A friendly name for the Git context (It can be anything you want.)
  • The name of your Bitbucket account/email address
  • A Bitbucket application password

To create an application password, go to your Bitbucket settings and select App passwords from the sidebar. Click the button to create one. For more information see the Bitbucket Documentation page

The minimum permissions needed by Codefresh are shown below.

Bitbucket permissions

Bitbucket permissions

The “label” you enter in your Bitbucket account in order to create the application password is completely arbitrary (use “Codefresh” for an example). Once you have the token, paste it in the Codefresh UI and click Test connection. If everything is OK you can now save the Git integration.

If enabled in your account you can setup Pipeline definition restrictions by expanding the YAML Options segment.

Azure DevOps

For Azure you need to create a personal access token. Sign in your Azure DevOps account and click on your profile icon on the top right corner. Then select Security:

Azure DevOps Security

Azure DevOps Security

On the screen that will appear click the New token Button. Enter an arbitrary name for the token and select the correct Organization from the drop-down menu. Remember your organization name as you will use it later in the Codefresh side. Select an expiration date for your token

At the time of writing Azure DevOps does not have the option to create a token that is valid for ever. Choose a large time period and make sure that you have a policy in place for renewing your tokens so that Codefresh can continue to read your Git repo.

Azure DevOps Token

Azure DevOps Token

From the Scope section choose the option Show all scopes and choose the following:

  • Code - read
  • Code - status
  • Graph - read
  • Project and Team - read
  • User profile - read

Finally click the Create button and copy your token (it will never be shown again).

Then at the Codefresh configuration enter your organization name and your token.

Codefresh integration with Azure Devops

Codefresh integration with Azure Devops

Click on Test connection to verify your settings and finally click save. Now you can create pipelines that use Azure DevOps Git repos.

Codefresh integration with Azure Devops

Codefresh integration with Azure Devops

Your Azure DevOps repositories will be available when creating a new project in Codefresh.

If enabled in your account you can setup Pipeline definition restrictions by expanding the YAML Options segment.

Atlassian Stash

Atlassian stash is only available for an on-premises connection. Follow the same instructions as Bitbucket. You also need to provide the URL of the Stash server in your organization.

This option is only for Atlassian stash until version 3.10 which is the old version. It was then renamed to Bitbucket server.

Bitbucket Server

Bitbucket server is the new and current name of Atlassian Stash. Again, it is only available for an on-premises installation.

Codefresh supports Bitbucket server versions 5.4.0+ since those expose the API used by the integration.

Using External Secrets for BitBucket Token

If your Bitbucket Server installation is behind your firewall, you can also use any external secrets that you have defined (such as Kubernetes secrets) as values by entering a secrets value with the same syntax shown in pipelines.

For example if you already have a token on a resource call git-credentials you can put in the token field the expression ${{[email protected]}}.

Using your Git provider

Once your provider is active, you can add a new project into Codefresh and then during the repository selection screen you will have access to the additional Git providers.

Select Git provider

Select Git provider

Notice that for all supported Git providers Codefresh will automatically create all the webhooks needed for triggering pipelines when a commit (or another event) happens.

After adding the repository Codefresh will behave exactly the same, regardless of the selected Git provider. You will be able to create pipelines for different Git providers in exactly the same manner.

ABAC for Git Contexts

Account Level: Pro and above

At this time, you will need to reach out to support to enable ABAC for Git Context and Pipeline Execution Context.

ABAC for Git Context gives the ability to restrict using and handling of Git Contexts. We use tags on the git context to limit Teams and Execution Contexts for access control. There are four actions controlled by ABAC: Creating, Updating, Deleting, and Using Git Contexts.

The Using means the following use cases:

  • Creating trigger
  • Getting YAML from a repository
  • Using the Git Context in a pipeline (git clone step etc.) via Execution Context.

You will get an error of Permission Denied or Forbidden to a Git Context that you do not have the correct permissions for that action.

Tagging the Git Context

  1. Navigate to Account Settings > Integrations > Configure for Git.
  2. Hovering over the integration name (Git Context), you will see “Edit Tags” just before the edit symbol.
  3. Select “Edit Tags,” and you can add and remove tags.
  4. Click Save when done.

Setting the Permissions

  1. Navigate to Account Settings > Permissions > Teams or Execution Context.
  2. Scroll to Git Contexts.
  3. Here, you can set permissions similar to other ABAC rules for Teams or Execution Context to Create or Use, Update, and Delete actions.
  4. Click Add Rule when done.