Continuous Integration (CI) Best Practices with SAP – Source Code Versioning System
Continuous Integration (CI) Best Practices with SAP – Source Code Versioning System
Part 3.1 – Setting up a Git/Gerrit Instance.
The purpose of this guide is to enable you to do first steps in designing your own CI processes using components like Gerrit, Jenkins and Nexus. These setup instructions for these components serve educational purposes only and are not meant as reference setup for productive purposes; for productive use, refer to the official component documentation.
What we offer in this part is not more than a basic recipe to set up a minimum installation including only those components on Linux that we consider as absolutely necessary to run a CI/CD process for development with SAP. However, the setup best suited to your concrete requirements cannot be part of this document because it highly depends on your concrete local situation, the network setup, the overall landscape into which the CI/CD process will be embedded, and so on. Therefore, we will restrict ourselves here to showing only the principles and the core elements.
If you are interested in other examples of CI/CD processes with a focus on specific needs and local conditions, just follow the references we provide to the official documentation for the described components. For each component, we provide hints to how the described setup could be improved. This concerns the professional and reliable operation, for example, further security activities and operational refinements.
Note: This document is restricted to the description of component installation on Linux. For installation on Windows, we refer to the installation documentation on the web.
1. Introduction
The interface between local (single developer) and collaborative (team) development is the source code management (SCM) tool together with a code review system. As already described in CI/CD Practices, the SCM tools plays a key role in the CI process. It only makes the development process reproducible. The SCM tool is also the interface to any sequel step, most importantly, the build step in the overall CI process.
There are many different possible choices for a SCM and review system. In this document, we show how to use Git as SCM tool and Gerrit as Git repository server and code review tool. These tools are very frequently used.
Git is a distributed SCM tool that has already a high adoption in the open source community and is more and more used in commercial environments. Gerrit is a repository server that can host and maintain Git repositories centrally. In a collaborative development scenario, changes are shared among developers through a Gerrit hosted central Git repository. In addition, Gerrit offers features for code review and voter builds which help to keep the main line (which is in Git usually called master
) clean.
Git is part of most Linux distribution and can be seen as a standard tool on a developer’s PC. Gerrit is offered as open source tool.
Gerrit Download
Gerrit Documentation
Gerrit quick get started guide
As part of the CI landscape, identify a Linux machine that will act as the host of the central Gerrit installation.
Our example is based on Gerrit release 2.13.3. In other releases, the front ends and the installation procedure may differ. In case of doubt, refer to the official component documentation.
2. Prerequisites
- Java JDK 1.7.0 or higher is installed on the machine.
- Git is installed on the machine
For installation of Git, see
3. Installation of Gerrit
Procedure
-
On the hosting machine, log on as user
root
. -
Create an OS user
gerrit
:useradd -d /home/gerrit -m -s /bin/bash gerrit
-
Create a Gerrit installation directory. In this document, we call it
/data/gerrit
, but any other directory that follows the respective conventions will work as well. The file partition of the directory must be large enough to store all the Gerrit data, especially the database. The usergerrit
must be the owner of the directory.mkdir -p /data/gerrit chown gerrit /data/gerrit/
-
Log on as
gerrit
. -
Download the Gerrit installation (
gerrit.war
file) from the download site and save it to/data/gerrit
. -
Execute the following commands to do the installation and to prepare the Gerrit database:
cd /data/gerrit java -jar gerrit.war init -d /data/gerrit java -jar gerrit.war reindex -d /data/gerrit
During the installation procedure of the Gerrit instance, you may decide for the default settings in the questionnaire in a first run, but it is recommended to approve the installation of the
download-commands
plugin. It enables the display of the clone URL in the Gerrit frontend. -
To get the server up quickly with the ability to administer it, open the Gerrit configuration file
/data/gerrit/etc/gerrit.config
and set the authentication method to:[auth] type = DEVELOPMENT_BECOME_ANY_ACCOUNT
For security reasons, you should change this to an appropriate authentication method as soon as possible.
-
Start the Gerrit daemon.
cd /data/gerrit/bin ./gerrit.sh start
-
The Gerrit application should now be accessible with a browser on port 8080.
-
In the Gerrit front end, click on Become and sign up. This first account has admin rights by default. Enter
admin
as Full Name and Username. Press Save Changes and Select Username.Since they require administrative rights, some of the following actions must be executed by this user. For day-by-day working with Gerrit, individual users with restricted permissions should be used.
-
In the same way, create a working user, which is used to perform Git operations like
pull
andpush
. We usesampleuser
further in this example. -
As first action, you can create a new project. Still logged in as
admin
, select Projects > Create New Project, enterFirstProject
as Project Name and select Create initial empty commit. Press Create Project.
4. Working with a Git Repository Hosted by Gerrit
It is recommended to use the SSH protocol for working with Gerrit. We describe here an example how to create and configure an SSH key to work with Gerrit from a local computer. Your permanent setup may differ according to your security policies.
Prerequisites
Git is installed on your local computer. If the computer is running on Linux, install Git using the package installer of your distribution and refer to the Git documentation that was mentioned before. If your computer is running on Windows, the Git installation includes Git Bash
, which shows a Linux-like user experience.
Procedure
-
On your local computer, create an SSH key pair, if it does not yet exist. On Linux or on Git Bash on Windows, execute
ssh-keygen
and enter<path to your home directory on your computer>/.ssh/id_rsa_sample
to create an SSH key pair for this demo purpose. In<path to your home directory on your computer>/.ssh/
there is now a file pairid_rsa_sample
/id_rsa_sample.pub
available. This key pair is by default issued for your operating system user on your computer. Nevertheless, it can be used by your Gerrit usersampleuser
. -
Log in to Gerrit with user
sampleuser
, click your name on the right upper corner and select Settings > SSH Public Keys. -
Select Add Key… and paste the contents of the file
id_rsa_sample.pub
into the field.Git requests through SSH to Gerrit are now authorized provided the request uses the generated sample key. This is done in the next step.
-
Open
<path to your home directory>/.ssh/config
. Add The following lines:Host <Full qualified hostname of Gerrit> IdentityFile <path to your home directory>/.ssh/id_rsa_sample
Check that the right key is taken by executing:
ssh -p 29418 -v sampleuser@<Full qualified hostname of Gerrit>
A frequent pitfall may be that the
HOME
environment variable is not correctly set. -
You are now able to locally clone the Git repository of the project
FirstProject
by executinggit clone <SSH-based URL of the FirstProject repository hosted on Gerrit>
-
Change into the directory of your cloned repository. For enabling Gerrit to apply the review process, a change ID must be generated into Git commits. This is done by a Git hook that can be downloaded directly from Gerrit by issuing:
gitdir=$(git rev-parse --git-dir); scp -p -P 29418 sampleuser@<Full qualified hostname of Gerrit>:hooks/commit-msg ${gitdir}/hooks/
- Do a change in the repository by creating a new file. Then add it and create a commit:
touch test.txt git add . git commit -m "My first commit" git push origin master:refs/for/master
You should be able to execute all the steps. If not, check the SSH key settings.
5. Further Enhancements
-
So far, there is no authentication and authorization concept in place yet. You must not take Gerrit into productive usage in this state.
-
Choose an appropriate authentication method and implement it.
-
Choose an appropriate permission concept for Gerrit and implement it.
For details, we refer to the official documentation.
-
-
The default database installation used by Gerrit is H2. For larger installations, you can use MySQL or Postgres.
-
Encapsulate the
gerrit.sh
into startup scripts in a way that Gerrit starts automatically with machine reboot. -
The
gerrit.war
package includes a standalone Jetty servlet container. Deployment on other JEE run times is possible.
The content of this document is for guidance purposes only. No warranty or guarantees are provided.