How to integrate Codefresh with other systems
Codefresh offers a comprehensive API that you can use to integrate with any other application or solution you already have.
The full details of the API are documented at https://g.codefresh.io/api/
You can use the API in various ways:
- From your local workstation with any tool that speaks HTTP (such as postman, httpie, curl etc.).
- From another HTTP enabled system such as Jenkins. You can trigger Codefresh pipelines from Jenkins jobs.
- Using the Codefresh command line interface which itself uses the API .
- Calling it programmatically from any other system. You can use your favorite programming language to make HTTP calls to Codefresh.
The Codefresh API is updated when new features are added in the Codefresh platform so you can expect any new functionality to appear to the API as well.
Ways to use the Codefresh API
There are several ways to use the API. Some of the most popular ones are:
- Triggering builds from another system. You can start a Codefresh pipeline from any other internal system that you already have in your organization.
- Getting the status of builds in another system.
- Creating pipelines externally. You don’t have to use the Codefresh GUI to create pipelines. You can create them programmatically using your favorite template mechanism. You can reuse pipelines using your own custom implementation if you have special needs in your organization.
You can browse the current API at https://g.codefresh.io/api/.
For each call you will also see an example with
Before you can use the API from your application you need an authentication key that will give programmatic access to Codefresh from an external application.
In order to create your own API key, click User Settings on the left sidebar and scroll down until you find the API Keys section. Click the generate button and copy your key.
From the same screen you can also revoke keys if you don’t need them anymore.
The following scopes are available:
- Build - Full access to all build information
- Build Read - Get all information from builds
- Build Read status - Get build status
- Build Write - Change Build information
- Cluster - Full access to Kubernetes cluster integrations
- Cluster Read - Read information from Kubernetes integrations
- Cluster Write - Change Kubernetes integrations
- Pipeline - Full access to pipelines
- Pipeline Approve - Ability to approve pipeline
- Pipeline Read - Read information from pipelines
- Pipeline Run - Execute/Run pipelines
- Pipeline write - Edit pipeline information
- Project - Full access to projects
- Project Read - Get information from projects
- Project Write - Change project information
- Step-type - Full access to steps
- Step-type Read - Read information from existing steps
- Step-type Write - Change/Edit custom steps.
Check that ones that you wish to use with this key
Using the API Key with the Codefresh CLI
Once you have the key use it in the Codefresh Cli like this
Now the Codefresh CLI is fully authenticated. The key is stored in
~/.cfconfig so you only need to run this command once. The CLI
can also work with multiple authentication contexts so it is possible to manage multiple Codefresh accounts at the same time.
Example - Triggering pipelines
You can trigger any pipeline in Codefresh and even pass extra environment variables (even if they are not declared in the UI)
Triggering a pipeline via the Codefresh CLI
You can pass extra environment variables as well:
For the API you can trigger a pipeline by finding its serviceId from the UI
You can also pass extra environment variables using an array
Example - getting status from builds
You can get the status of a build from the cli by using its ID:
Same thing with the API
Example - creating Codefresh pipelines externally
Codefresh has a great UI for creating pipelines for each of your projects. If you wish, you can also create pipelines programmatically in an external manner. This allows you to use your own templating solution for re-using pipelines and creating them from an external system.
First you need a yaml file that defines the pipeline. This is a pipeline specification.
It is also very to create a a dummy pipeline in the Codefresh Web UI and then get its specification by running
codefresh get pipeline my-project/my-pipeline -o yaml > my-pipeline-spec.yml
Here is an example
Save this spec into a file with an arbitrary name like
my-pipeline-spec.yml. First create the new project (if it doesn’t exist already):
Then you can create the pipeline with the cli
And your pipeline will be available in the GUI
Notice that you must prefix the name of the pipeline with your username and repository so that it becomes visible in the GUI under the correct project.
Using Codefresh from within Codefresh
For example, you can easily call pipeline B from pipeline A
with the following step:
codefresh.yml of pipeline A
This step only calls pipeline B when a pull request is opened for the branch named
Note that when you use the Codefresh CLI in a pipeline step, it is already configured, authenticated and ready for use. No additional authentication is required.