Getting Started
Guides
Using Humanitec
Connect CI Pipelines
Learn how to connect CI pipelines to Humanitec.
Introduction
CI pipelines define the series of steps that must be performed in order to deliver a new version of software. Typical steps are "build", "test", "validate / compliance", "release", and maybe even "deploy". The "build" step produces an image that is then "pushed" into a registry.
Humanitec as your Internal Developer Platform needs to know about all available builds. This allows users of Humanitec to use these builds in their applications and it's the starting point for further automation.
In most setups, it's sufficient to notify Humanitec at the end of your CI pipeline about a newly available build after it has been pushed to your registry (see also Container Registries for more information).
Humanitec also offers a hosted registry in case you do not have your own registry. Using the hosted registry requires an additional step in your CI pipeline to build the image and to push it to the Humanitec registry. The following picture shows both approaches.
In most cases, the only change needed in existing CI pipelines to integrate with Humanitec is a simple
curl or wget command to notify Humanitec about every new build available.Why does Humanitec offer a hosted registry?
Almost all teams using Humanitec have their own registry either self-managed or managed by their cloud provider. Humanitec still offers a managed container registry that is compartmentalised for each organization in Humanitec. This registry is often used to test Humanitec since it is easy to just push an image with a shell script from a developer's local machine to make it available within Humanitec without already changing existing CI pipelines. The required shell script can be found further down.
Add new 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.
Notify Humanitec
If you are already using your own container registry, the only thing you need to do is inform Humanitec about new builds. This can be done by adding a
curl orwget request to the end of your existing CI pipeline:UI
CLI
API
- 1.
- 2.Click on Connect CI pipeline.
- 3.Chose between using
curlorwgetfor the post request. - 4.Copy and paste the post request at the end of your CI pipeline. Make sure you replace the placeholder variables with the appropriate values.
- 5.As soon as new images are pushed they will be shown in the list below.
Step 1 & 2 of adding a new image source.
Step 3 & 4 of adding a new image source.
Placeholder variables in the example above:
CI_COMMIT_BRANCHis the branch that the image was built from.CI_COMMIT_SHAis the git commit that the image was built from.IMAGE_PATHis the full path to the image in your registry (incl. the image tag).CI_IMAGE_TAGcontains additional git tags associated with the commit. (optional).
Note that you can integrate Humanitec in any CI pipeline by adding the required steps yourself. You can find example bash scripts in Write your own integration.
GitHub Actions Workflow
Humanitec offers a out-of-the-box CI pipeline integration for Github Actions. The source code of the GitHub Action is available in this public GitHub repository: Build and Push to Humanitec.
- 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:
1
# This is a basic workflow to help you get started with Actions.
2
3
name: CI
4
5
# Controls when the action will run. Triggers the workflow on push or pull request
6
# events but only for the master branch
7
on:
8
push:
9
branches: [ master ]
10
pull_request:
11
branches: [ master ]
12
13
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
14
jobs:
15
# This workflow contains a single job called "build"
16
build:
17
# The type of runner that the job will run on
18
runs-on: ubuntu-latest
19
20
# Steps represent a sequence of tasks that will be executed as part of the job
21
steps:
22
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
23
- uses: actions/[email protected]
Copied!
You need to add the
HUMANITEC_TOKEN as a repository secret:- 1.Go to the repository you want to connect.
- 2.Go to Settings, and then go to Secrets > New repository secret.
- 3.Create a secret called
HUMANITEC_TOKEN, and paste in the token.
Write your own Integration
You can integrate Humanitec with any CI pipeline or even use Humanitec from a terminal on your local machine in case you just want to give it a test without changing your existing CI pipelines. This section provides all required information and bash scripts to do that.
Full bash script for local usage
If you want to test Humanitec from your local machine (by pushing a local image to the registry provided by Humanitec), You can use the following shell script:
1
#!/bin/sh
2
3
print_usage ()
4
{
5
cat <<EOF
6
USAGE:
7
8
./local_build_push_notify.sh [options] IMAGE_NAME[:TAG]
9
10
OPTIONS:
11
12
-t, --token
13
The token to pass into the authorization header. Will override the
14
HUMANITEC_TOKEN environment variable if supplied.
15
16
-o, --org
17
The organization in Humanitec that the token belongs to.
18
19
-h, --help
20
Show this help text.
21
22
NOTES:
23
24
IMAGE_NAME is required and must consist only of lowercase letters and numbers
25
and -. It may not start or end with -.
26
27
If TAG is not provided, it will be set to the current commit SHA1.
28
29
By default, the token will be read from the HUMANITEC_TOKEN environment
30
variable.
31
32
EXAMPLE:
33
34
./local_build_push_notify.sh --org my-org my-image:0.3.2-rc5
35
36
EOF
37
}
38
39
key_from_json_obj ()
40
{
41
tr -d '\n' | sed 's/^[ \t\v\f]*{.*"'"${1}"'"[ \t\v\f]*:[ \t\v\f]*"\([^"]*\)"[ \t\v\f]*[,}].*$/\1/'
42
}
43
44
fetch_url ()
45
{
46
method="$1"
47
payload=""
48
if [ "$method" = "POST" ] || [ "$method" = "PUT" ] || [ "$method" = "PATCH" ]
49
then
50
payload="$2"
51
shift
52
fi
53
url="$2"
54
auth_header="Authorization: Bearer $HUMANITEC_TOKEN"
55
if command -v curl &> /dev/null
56
then
57
if [ "$payload" != "" ]
58
then
59
curl --fail -s \
60
-X "$method" \
61
-H "$auth_header" \
62
-H "Content-Type: application/json" \
63
-d "$payload" \
64
"$url"
65
else
66
curl --fail -s \
67
-X "$method" \
68
-H "$auth_header" \
69
"$url"
70
fi
71
elif command -v wget &> /dev/null
72
then
73
if [ "$payload" != "" ]
74
then
75
wget --quiet -O - \
76
--method="$method" \
77
--header="$auth_header" \
78
--header="Content-Type: application/json" \
79
--body-data="$payload" \
80
"$url"
81
else
82
wget --quiet -O - \
83
--method="$method" \
84
--header="$auth_header" \
85
"$url"
86
fi
87
else
88
echo "System does not have the commands wget or curl installed." >&2
89
exit 1
90
fi
91
}
92
93
api_prefix="https://api.humanitec.io"
94
95
while (( $# ))
96
do
97
case "$1" in
98
'-t'|'--token')
99
export HUMANITEC_TOKEN="$2"
100
shift
101
;;
102
'-o'|'--org')
103
export HUMANITEC_ORG="$2"
104
shift
105
;;
106
'--api-prefix')
107
api_prefix="$2"
108
shift
109
;;
110
'-h'|'--help')
111
print_usage
112
exit
113
;;
114
*)
115
if ! echo "$1" | grep -E '^[a-z0-9][a-z0-9-]+[a-z0-9]:[a-zA-Z0-9_.-]+$|^[a-z0-9][a-z0-9-]+[a-z0-9]#x27; > /dev/null
116
then
117
print_usage
118
exit 1
119
fi
120
image_with_tag="$1"
121
image_name=${image_with_tag%:*}
122
image_tag=${image_with_tag#*:}
123
if [ "$image_tag" = "$image_with_tag" ]
124
then
125
image_tag=""
126
fi
127
128
esac
129
shift
130
done
131
132
if [ -z "$HUMANITEC_TOKEN" ]
133
then
134
echo "No token specified as option or via HUMANITEC_TOKEN environment variable." >&2
135
exit 1
136
fi
137
138
if [ -z "$HUMANITEC_ORG" ]
139
then
140
echo "No Organization specified as option or via HUMANITEC_ORG environment variable." >&2
141
exit 1
142
143
fi
144
145
if [ -z "$image_with_tag" ]
146
then
147
echo "No IMAGE_NAME:TAG provided." >&2
148
exit 1
149
fi
150
151
echo "Retrieving registry credentials"
152
registry_json="$(fetch_url GET "${api_prefix}/orgs/${HUMANITEC_ORG}/registries/humanitec/creds")"
153
if [ $? -ne 0 ]
154
then
155
echo "Unable to retrieve credentials for humanitec registry." >&2
156
exit 1
157
fi
158
159
username="$(echo "$registry_json" | key_from_json_obj "username")"
160
password="$(echo "$registry_json" | key_from_json_obj "password")"
161
server="$(echo "$registry_json" | key_from_json_obj "registry")"
162
163
branch="$(git rev-parse --abbrev-ref HEAD)"
164
commit="$(git rev-parse HEAD)"
165
166
if [ "$image_tag" = "" ]
167
then
168
image_tag="$commit"
169
fi
170
171
echo "Logging into docker registry"
172
echo "${password}" | docker login -u "${username}" --password-stdin "${server}"
173
if [ $? -ne 0 ]
174
then
175
echo "Unable to log into humanitec registry." >&2
176
exit 1
177
fi
178
179
echo "Performing docker build"
180
local_tag="${HUMANITEC_ORG}/${image_name}:${image_tag}"
181
if ! docker build -t "$local_tag" .
182
then
183
echo "Docker build failed." >&2
184
exit 1
185
fi
186
187
image_id="$(docker images -q "$local_tag")"
188
remote_tag="${server}/$local_tag"
189
if ! docker tag "$local_tag" "$remote_tag"
190
then
191
echo "Error pushing to remote registry: Cannot retag locally." >&2
192
exit 1
193
fi
194
195
echo "Pushing image to registry: $remote_tag"
196
if ! docker push "$remote_tag"
197
then
198
echo "Error pushing to remote registry: Push failed." >&2
199
exit 1
200
fi
201
202
echo "Notifying Humanitec"
203
payload="{\"commit\":\"${commit}\",\"branch\":\"${branch}\",\"tags\":"[]",\"image\":\"${remote_tag}\"}"
204
if ! fetch_url POST "$payload" "${api_prefix}/orgs/${HUMANITEC_ORG}/images/${image_name}/builds"
205
then
206
echo "Unable to notify Humanitec." >&2
207
exit 1
208
fi
Copied!
The script will perform the following main actions:
- Build a new image locally using docker.
- Push the image to the Humanitec registry.
- Notify Humanitec about the new image.
Obviously, you can tweak the individual steps if needed (e.g., in case you need to add additional
BUILD_ARGS for your docker build). Feel free to reach out to us in case you need support.Last modified 3mo ago