Checkout code in your pipelines
Clones a Git repository to the filesystem.
A pipeline can have any number of Git clone steps (even none). You can checkout code from any private or public repository. Cloning a repository is not constrained to the trigger of a pipeline. You can trigger a pipeline from a commit that happened on Git repository A while the pipeline is checking out code from Git Repository B.
Notice that if you are an existing customer before May 2019, Codefresh will automatically checkout the code from a connected Git repository when a pipeline is created on that repository. In this case an implicit Git clone step is included in your pipeline. You can still override it with your own git clone step as explained in this page.
||The free-text display name of the step.||Optional|
||A basic, free-text description of the step.||Optional|
||Parent group of this step. See using stages for more information.||Optional|
||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
||The name of the Git integration you want to use. If left empty, Codefresh will attempt to use the git provider that was used during account sign-up. Note that this might have unexpected results if you are changing your Git integrations.||Required|
||The path of the repository without the domain name in the form of
Note: To clone a GitHub wiki, specify the full URL of the wiki, for example,
||The revision of the repository you are checking out. It can be a revision hash or a branch name. The default value is the branch you have specified in your Git provider (e.g
||The number of commits to pull from the repo to create a shallow clone. Creating a shallow clone truncates the history to the number of commits specified, instead of pulling the entire history.||Optional|
||If set to true the Git clone process will honor
||Credentials to access the repository, if it requires authentication. It can an object containing
||If a step fails and the process is halted. The default value is
||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|
||Define operations to perform upon step completion using a set of predefined Post-Step Operations.||Optional|
||Define retry behavior as described in Retrying a step.||Optional|
- 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.
Basic clone step (project-based pipeline)
The easiest way to use a git clone step is to use your default git provider as configured in built-in Git integrations.
Here is an example of a pipeline that will automatically check out the repository that triggered it (i.e. a commit happened on that repository).
Notice that the name of the clone step is
main_clone. This will automatically set the working directory of all other steps that follow it inside the folder of the project that was checked out. This only applies to built-in Codefresh steps and not custom plugins. This is normally what you want for a pipeline that only checks out a single project. If you use any other name apart from
main_clonethe working directory for all subsequent steps will not be affected and it will default on the shared volume which is the parent folder of checkouts.
The CF values will be automatically filled by Codefresh from the git trigger. See Variables in pipelines for more details.
Choosing a specific git provider (project-based pipeline)
If you don’t want to use the default git provider you can explicitly set the provider by using the same name of the integration as it is shown in the Git integrations page.
Here is an example for an integration with the GitLab provider already connected:
Checkout a specific repository/revision (project based pipeline)
If you want to check out a specific git repository regardless of what repository actually created the trigger
you can just define all values in a non-static manner. For example, if you want your pipeline to always checkout git repository
foo even when the trigger happened from repository
bar you can define the checkout step as below:
In a similar manner you can also define that the pipeline will always checkout master, regardless of the commit that actually triggered it.
Checkout code using the Codefresh Runner
If you are using the Codefresh runner, you need to use the fully qualified path of the Git repository:
For more details, see Checking out code from a private Git repository.
Checking out multiple Git repositories
It is very easy to checkout additional repositories in a single pipeline by adding more
In that case you should use different names for the steps (instead of
main_clone) as this will make the working
folder for all steps the shared volume.
Skip or customize default clone (repository-based pipeline)
If you have existing pipelines connected to repositories (only for Codefresh accounts created before May 2019)
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 behavior, you can choose to skip the automatically added git clone step.
There are 2 ways to do that:
- Add a pipeline environment variable called
CF_SKIP_MAIN_CLONEwith value of
- Add a step with key
main_cloneto 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' steps: main_clone: title: Checking out code image: alpine/git:latest commands: - git clone ... another_step: ...
Reuse a Git token from Codefresh integrations
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' steps: get_git_token: title: Reading GitHub token image: codefresh/cli commands: - cf_export GITHUB_TOKEN=$(codefresh get context github --decrypt -o yaml | yq -r .spec.data.auth.password) main_clone: title: Checking out code image: alpine/git:latest commands: - git clone https://my-github-username:$GITHUB_TOKEN@github.com/my-github-username/my-repo.git another_step: ...
Working with GIT submodules
To check out a Git project including its submodules, you can use the Codefresh submodule plugin. This plugin is already offered as a public docker image at Docke Hub.
To use this module in your pipeline, add a new step like the one shown below.
version: '1.0' steps: updateSubmodules: image: codefresh/cfstep-gitsubmodules environment: - 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.
Here is full pipeline example:
This pipeline does the following:
- Clones the main source code
- Updates submodules
- Creates a docker image
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
cat ~/.ssh/my_ssh_key_file | tr '\n' ','
Then in the pipeline use it like this:
Using Git behind a proxy
If you use the Codefresh Runner and need to use a network proxy in your clone step you need to set the variables
HTTPS_PROXY in the pipeline
and then activate the property
use_proxy: true in the clone step. Example:
For setting the values of the proxy variables you can use any of the supported methods for defining variables such as shared configuration.
For more details, see the behind the firewall page.