Table of Contents:
This guide aims to explain how to build your first image on Apertis using the GitLab UI. A comprehensive documentation to manually build a customized image is available at Image building.
This document will explain how to create a GitLab account and how to use its UI and pipelines to modify and create a custom Apertis image.
Create a GitLab account
To build your Apertis image, you first need an account on the Apertis GitLab instance.
To create one, please go on at https://gitlab.apertis.org, then click on
Sign in / Register:
On the next webpage, you will have a
Register now button:
Fill the form, then click on
At this step, you will have to wait until an administrator approves your registration:
You have signed up successfully. However, we could not sign you in because your account is awaiting approval from your GitLab administrator.
Once your account is approved, you will be notified through an email entitled
Welcome to GitLab from
<gitlab at gitlab.apertis.org>.
The next step is to set up your account. A first useful configuration is to add
your SSH key to be able to push/pull without having to give your
username/password for each action.
For this, you need to go into
Then, into the
SSH Keys part:
The instructions to generate a new key
or to add an existing one
Please follow the relevant one to configure your SSH key.
Fork a repository
It is now possible to fork a repository using the GitLab UI.
By forking a repository, you will copy a repository under your
GitLab namespace. That means you will be able to modify files of
the newly forked project, and then later you can eventually do a
Merge request to send your changes back to the upstream (or original) project.
For this example, we will fork the
repository at https://gitlab.apertis.org/demo/image-recipes-sample.
This repository contains a recipe to build a custom Apertis image for a
Raspberry Pi board.
Click on the
A form will be displayed, where you can add information regarding your fork:
By clicking on
Fork project, you will engage the fork process
that it is confirmed by a message saying
Forking in progress.
Then, after few seconds (or minutes depending of the size of the
repository), you will get a
The project was successfully forked
Add new package to this image recipe
In this example, we will add some
.deb packages into our first customized
The recipe to generate an image is a
.yaml file that is read and
used by debos to build the image.
The complete syntax of the debos
.yaml is available on its
or you can have a look at its manpage.
We will modify the
image-rpi64.yaml file in our just forked
image-recipes-sample repository. Scroll down until you see the
Then, click on it and on the
For our example, we will add two additional
flac) to the image, for this we need to add the
following section in
We add it at the end of all apt actions and before the first
The order of the different
action parts is important because these
are run sequentially by
Add the new section, a commit message and then, click on
You should receive a
Your changes have been successfully committed
Build an Apertis image
The GitLab CI uses a recipe to build the Apertis Image. This is configured in the .gitlab-ci.yml file located in the root directory of the repository. Please refer to the official GitLab CI documentation for more information.
The GitLab CI pipeline will generate a new Apertis Image for
each push (or commit through the UI) into the forked
repository. If needed, it is possible to generate an image on demand by
Pipelines in the sidebar.
Then, click on
Run pipeline, select on which branch the pipeline
should be run against and eventually some variables can be defined.
Finally, after another click on
Run pipeline, the process will start.
The progress of the building can be followed in
Once all jobs ran successfully (i.e. they should be in green),
it is possible to download the generated image by clicking on the
Download at the right panel:
The image is also available from an URL, in our example we can
download the last image built for the original
images-recipe-sample repository at
Please refer to these instructions to setup and test your newly built image.