Customizing the git checkout process

Clones a Git repository to the filesystem.

Note that this step is completely optional. Codefresh will automatically checkout the code from a connected git repository when a pipeline is created on that repository.



  type: git-clone
  title: Step Title
  description: Step description
  working_directory: /path
  repo: owner/repo
  git: my-git-provider
  revision: abcdef12345
    username: user
    password: credentials
  fail_fast: false
      ignore: [ develop ]


Field Description Required/Optional/Default
title The free-text display name of the step. Optional
description A basic, free-text description of the step. Optional
stage Parent group of this step. See using stages for more information. Optional
working_directory The directory to which the repository is cloned. It can be an explicit path in the container’s file system, or a variable that references another step. The default value is ${{main_clone}}. Default
git The name of the git integration you want to use. You can also use CF-default as a value for the default git provider that was used during Codefresh sign-up Required
repo path of the repository without the domain name in the form of my_username/my_repo Required
revision The revision of the repository you are checking out. It can be a revision hash or a branch name. The default value is master. Default
credentials Credentials to access the repository, if it requires authentication. It can an object containing username and password fields. Optional
fail_fast If a step fails and the process is halted. The default value is true. Default
when Define a set of conditions that need to be satisfied in order to execute this step. You can find more information in the Conditional Execution of Steps article. Optional
on_success, on_fail and on_finish Define operations to perform upon step completion using a set of predefined Post-Step Operations. Optional
retry Define retry behavior as described in Retrying a step. Optional

Exported resources:

  • Working Directory

If you want to extend the git-clone step you can use the freestyle step. Example how to do it you can find here

Skip or customize default clone

A git clone step is transparently added to git attached pipelines without you having to explicitly add a step into the pipeline. This is a convenience to enable easy CI pipelines.
If you do not require git cloning, or you would like to customize the implicit git cloning behaviour, you can choose to skip the automatically added git clone step.

There are 2 ways to do that:

  1. Add a pipeline environment variable called CF_SKIP_MAIN_CLONE with value of true.


  1. Add a step with key main_clone to your pipeline. This step can be of any type and can do any action. This step will override the default clone implementation. for example:
version: '1.0'
    title: Checking out code
    image: alpine/git:latest
      - git clone ...

Reuse a Git token from Codefresh integrations

If you customize the git clone step, you also have the capability to use one of your existing git integrations as an authentication mechanism.

The Codefresh CLI can read one of the connected git authentication contexts and use that token for a custom clone step.

Here is an example for Github

version: '1.0'
    title: Reading Github token
    image: codefresh/cli
      - cf_export GITHUB_TOKEN=$(codefresh get context github --decrypt -o yaml | yq -y
    title: Checking out code
    image: alpine/git:latest
      - git clone https://my-github-username:$

Working with GIT submodules

To checkout a git project including its submodules you can use the Codefresh submodule plugin. This plugin is already offered as a public docker image at Dockerhub.

To use this module in your pipeline add a new step like the one shown below.

version: '1.0'
    image: codefresh/cfstep-gitsubmodules
      - GITHUB_TOKEN=<github_token>
      - CF_SUBMODULE_SYNC=<boolean to determine if modules should be synced>
      - CF_SUBMODULE_UPDATE_RECURSIVE=<boolean to determine if modules should be recursively updated>

The Github token can be either defined in the pipeline on its own as an environment variable, or fetched from the existing GIT integration as shown in the previous section.

Use an SSH key with Git

It is also possible to use an SSH key with git. When creating your pipeline add your SSH key as an encrypted environment variable after processing it with tr:

cat ~/.ssh/my_ssh_key_file | tr '\n' ','

Then in pipeline use it like this:


version: '1.0'
    title: Checking out code
    image: alpine/git:latest
      - mkdir -p ~/.ssh
      - echo "${SSH_KEY}" | tr \'"${SPLIT_CHAR}"\' '\n' > ~/.ssh/id_rsa
      - chmod 600 ~/.ssh/id_rsa
      - git clone
      # can also use go get or other similar command that uses git internally