Connect CI Pipelines

Learn how to connect existing CI Pipelines to Humanitec.

Introduction

Humanitec allows you to build Internal Developer Platforms that integrate directly with your existing CI pipelines. This section explains how to connect your existing CI pipelines to Humanitec. We currently offer out-of-the-box solutions for the following CI tools:

If you happen to use any other CI tool (such as Jenkins, Codefresh, etc.) then please contact us for more information and we are happy to provide the required steps and code snippets for an integration. Alternatively, have a look at writing your own integration.

Review and Edit Image Sources

In the context of Humanitec, a CI pipeline is an image source. An image source provides Humanitec with container images which can then be deployed to the Environments of your Apps as Workloads.

You can review and edit all of your organization's image sources in the Organization Settings.

Example for Images within Organization Settings

You can connect new image sources by following the instructions provided when clicking on one of the CI pipeline logos. The following sections also describe the process in detail.

Bitbucket Pipeline

For each repository whose image you want to push to Humanitec, you must have Bitbucket Pipelines enabled. If you don’t have Pipelines set up, then follow the instructions in the Atlassian documentation.

Add Humanitec Token and Snippet

  1. Click the profile icon in the top right.

  2. Select Organization Settings.

  3. Select the Images tab.

  4. Click the Bitbucket Pipelines button.

Follow the instructions that appear in the modal. Humanitec will provide you with an access token for connecting to Humanitec's registry and a code snippet to add to your pipeline configuration to push the image.

First, add the token as a repository variable:

  1. Go to the repository you want to connect.

  2. Go to Settings, and then go to Pipelines > Repository variables.

  3. Create a variable called HUMANITEC_TOKEN, and paste the token from the modal as the value.

Click Next to perform the second step:

  1. Copy the snippet from the modal and add it to the end of your bitbucket-pipelines.yml file.

  2. Commit the changes and initiate your pipeline. If the build is successful, your image will appear in the images list on Humanitec.

Learn more about the official Humanitec Pipe on Bitbucket: Build and push to Humanitec.

GitHub Actions Workflow

Here is a short video explaining how to connect your GitHub Actions workflow to Humanitec to retrieve your container images from your repositories.

Humanitec Connect Github Action

The Humanitec GitHub Action

Humanitec is providing a GitHub Action Build and Push to Humanitec which is available from a public GitHub repository. Using this GitHub Actions allows for simple and convenient integration between GitHub and Humanitec.

Create a New Workflow

If you do not have a GitHub Actions workflow set up, you will need to create one.

  1. Go to the GitHub repository you want to connect.

  2. Click the Actions tab.

  3. Click the Set up a workflow yourself button in the top right corner.

  4. Remove all of the lines after the line that says: - uses: actions/[email protected]. The resulting file should look like this:

# This is a basic workflow to help you get started with Actions.
name: CI
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/[email protected]

Note that this file is not yet committed to the repository. In the next step, you will add the necessary configurations to connect to Humanitec.

Add Humanitec Snippet and Token

  1. Click the profile icon in the top right.

  2. Select Organization Settings.

  3. Select the Images tab.

  4. Click the GitHub Actions button.

From there, Humanitec will provide you with an access token for connecting to Humanitec's registry and a code snippet to add to your workflow configuration in order to push the image. Instructions will appear in the modal.

CircleCI Pipeline

Here is a short video explaining how to connect your CircleCI Pipeline with a Circle CI Orb to Humanitec to retrieve your container images from your repositories.

Humanitec Connect with CircleCI

The Humanitec Orb

Humanitec is providing a CircleCI Orb Humanitec that is available from the CircleCI Orb Registry. Using this CircleCI Orb allows for simple and convenient integration between CircleCI and Humanitec.

Create a New Pipeline

If you do not have a CircleCI Pipeline set up, you will need to create one.

  1. Go to the Git Repository you want to connect.

  2. Create a new folder called .circleci.

  3. Create a new file called config.yml.

  4. The new file looks like this, where YOUR-HUMANITEC-ORGANIZATION is the name of your organization in Humanitec:

# Use the latest 2.1 version of CircleCI pipeline process engine. See: https://circleci.com/docs/2.0/configuration-reference
version: 2.1
# Use a package of configuration called an orb.
orbs:
humanitec: humanitec/[email protected]
# Orchestrate or schedule a set of jobs
workflows:
build-push-and-notify-humanitec:
jobs:
- humanitec/build-push-and-notify-humanitec:
organization: YOUR-HUMANITEC-ORGANIZATION

Note that you will need to commit this file to your Git repository and establish a connection between the repository and your CircleCI account. Follow the explanations in the CircleCI app to create the connection. You will need to have third-party orbs support enabled in your Organization Settings in CircleCI.

Add Humanitec Token

In order to finalize the connection between CircleCI and Humanitec, you will need to add a token to the CircleCI project. This requires the following steps:

  1. Click the profile icon in the top right.

  2. Select Organization Settings.

  3. Select the Images tab.

  4. Click the CircleCI button.

From there, Humanitec will provide you with an access token for connecting to Humanitec’s registry. Instructions will appear in the modal.

First, add the token as an Environment Variable in your CircleCI project:

  1. Go to the project you want to connect.

  2. Go to Project Settings, and then go to Environment Variables > Add Variable.

  3. Create a variable called HUMANITEC_TOKEN, and paste the token from the modal as the value.

Then, add the snippet from the modal to the end of your config.yml file and commit the changes.

The last step is to trigger a build of your image. If the build is successful, then your image will become available on Humanitec as a workload that can be added to your environments.

Gitlab Job

There is no official integration for Gitlab available but you can use the following job build by Antoine Rogeout: https://gitlab.com/rougeot-antoine/build-push-to-humanitec.

Feel free to reach out to us in case of any questions.

Write your own Integration

Using the out-of-the-box integrations available is definitely the most convenient way to integrate your CI pipelines with Humanitec. However, you can also write your own integration if you want/need to. Please contact us for more information.