How to install gitlab on windows

You can install the GitLab runner on different operating systems, by installing Git versioning system and creating user account in the GitLab site.

Git is a version control system used for −

• Handling the source code history of projects
• Tracking changes made to files
• Handling small and large projects with speed and efficiency
• To collaborate with other developers on different projects

GitLab is a Git-based platform provides remote access to Git repositories and helpful for software development cycle by creating private and public repositories for managing the code.

GitLab supports different types of operating systems such as Windows, Ubuntu, Debian, CentOS, open SUSE and Raspberry Pi 2. In this chapter, we will discuss about how to install GitLab on Windows and Ubuntu operating systems −

Installation of GitLab on Windows:

Step 1 − First create a folder called ‘GitLab-Runner’ in your system. For instance, you can create in C drive as C:GitLab-Runner.

Step 2 − Now download the binary for x86 or amd64 and copy it in the folder created by you. Rename the downloaded binary to gitlab-runner.exe.

Step 3 − Open the command prompt and navigate to your created folder. Now type the below command and press enter.

C:GitLab-Runner>gitlab-runner.exe register

Step 4 − After running the above command, it will ask to enter the gitlab-ci coordinator URL.

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
https://gitlab.com

Step 5 − Enter the gitlab-ci token for the runner.

Please enter the gitlab-ci token for this runner:
xxxxx

• To get the token, login to your GitLab account −

• Now go to your project −

• Click on the CI/CD option under Settings tab and expand the Runners Settings option.

• Under Runners Settings section, you will get the token as shown in the image below −

Step 6 − Enter the gitlab-ci description for the runner.

Please enter the gitlab-ci description for this runner:
[Admin-PC]: Hello GitLab Runner

Step 7 − It will ask to enter the gitlab-ci tags for the runner.

Please enter the gitlab-ci tags for this runner (comma separated):
tag1, tag2

You can change these tags in the GitLab’s user interface later.

Step 8 − You can lock the Runner to current project by setting it to true value.

Whether to lock the Runner to current project [true/false]:
[true]: true

After completing above steps, you will get the successful message as ‘Registering runner… succeeded’.

Step 9 − Now enter the Runner executor for building the project.

Please enter the executor: parallels, shell, docker+machine, kubernetes, docker-
ssh+machine, docker, docker-ssh, ssh, virtualbox:
docker

We have used the selector as ‘docker’ which creates build environment and manages the dependencies easily for developing the project.

Step 10 − Next it will ask for default image to be set for docker selector.

Please enter the default Docker image (e.g. ruby:2.1):
alpine:latest

Step 11 − After completing the above steps, it will display the message as ‘Runner registered successfully’. The below image will describe the working flow of above commands −

Step 12 − Now go to your project, click on the CI/CD option under Settings section and you will see the activated Runners for the project.

You can see the GitLab Runner configuration in the config.toml file under the GitLab-Runner folder as shown below −

concurrent = 1
check_interval = 0
[[runners]]
  name = "Hello GitLab Runner"
  url = "https://gitlab.com"
  token = "40ceed29eec231fa9e306629cae4d7"
  executor = "docker"
  [runners.docker]
      tls_verify = false
      image = "alpine:latest"
      privileged = false
      disable_cache = false
      volumes = ["/cache"]
      shm_size = 0
  [runners.cache]

Installation of GitLab on Ubuntu

The GitLab can be installed on Ubuntu system by using Omnibus package which provides different services to run GitLab. The Omnibus package provides necessary components of GitLab, establishes the configurations and project metadata which can be used in user’s system.

The following steps describe installation of GitLab on Ubuntu −

Step 1 − First, login to your GitLab server using SSH (Secure Shell).

Step 2 − Next, download the Omnibus package −

wget https://downloads-packages.s3.amazonaws.com/ubuntu-14.04/gitlab-ce_7.10.4~omnibus-1_amd64.deb

Step 3 − Install the postfix −

sudo apt-get install postfix

Postfix is a open source mail transfer agent used to deliver the email notifications.

Step 4 − While installing Postfix, it will ask type of installation; then select the Internet Site option. Next, it will show Postfix configuration along with the system mail name as shown in the image −

Step 5 − Install the dpkg (package manager for debian system) for managing the installed packages −

sudo dpkg -i gitlab-ce_7.10.4~omnibus-1_amd64.deb

Step 6 − To have the changes take effect, you need to reconfigure the GitLab by using the below command −

sudo gitlab-ctl reconfigure

Step 7 − Check the status of the GitLab services by using below command −

sudo gitlab-ctl status

If you want to install GitLab from the source, then install some dependencies on the server and need to setup the database by using the PostgreSQL. It is described in the Environment setup chapter. You can install the coordinator to build a web interface and control build instances. For more information, you can check the Installation of Coordinator chapter.

GitLab is a place where we can manage our git repositories. It can be considered as an alternate of GitHub and Bitbucket. Currently, Gitlab is offering four versions namely Core, Starter, Premium, and Ultimate.

1. Core: For small and personal projects. Free of cost.
2. Starter: For small and personal projects who need professional support. It is paid.
3. Premium: For teams who need high availability, high performance, and/or 24/7 support.
4. Ultimate: For large enterprises who want to align strategy and execution with security and compliance.

In this article, we will use Core version and learn how to setup GitLab Repository on Windows System in order to manage your codes and projects. So let’s start:

1. Create Account on GitLab.

Username or Email:  abc@gmail.com
Password:  **********

2. Create New Project, named as “Test”.

3. Download Git for Windows and install it.

4. Open Cmd and run following command to check the successful installation of Git.

git --version

5. Set username and email

git config  --global user.name ABC

git config --global user.email “abc@gmail.com”

Note: Username and email should be same as your Gitlab Account.

6. Check for Success:

git config --global --list

7. Go to Directory from where you want to upload project. Right Click there and open “Git Bash Here”.

8. Initialize Git here.

git init

9. Add changes from all tracked and untracked files.

git add -A

10. To add a new remote, use Project URL from GitLab:

git remote add origin https://gitlab.com/abc/Test.git

11. Commit changes with message:

git commit -m "Your_Message"

12. Now push project on GitLab

git push origin master

Pull GitLab Repository

13. Go to the master branch to pull the latest changes from there

git checkout master

14. Download the latest changes in the project

git pull REMOTE NAME-OF-BRANCH -u

(REMOTE: origin) (NAME-OF-BRANCH: could be “master” or an existing branch)

Create New Branch

15. Create a branch. Spaces won’t be recognized, so you will need to use a hyphen or underscore.

git checkout -b NAME-OF-BRANCH

16. Work on a branch that has already been created

git checkout NAME-OF-BRANCH

17. View the changes you’ve made

git status

18. Add changes to commit. You’ll see your changes in red when you type “git status”.

git add CHANGES IN RED

git commit -m "DESCRIBE THE INTENTION OF THE COMMIT"

19. Send changes to gitlab.com

git push REMOTE NAME-OF-BRANCH

Are you tired of manually pushing code to production? Are you always searching through your BASH history to find the commands you used to test your code? Do you wish the process to merge code into production had a defined process? Well I have the solution for you! Introducing Gitlab CI/CD pipelines! With Gitlab you can setup Gitlab runners to create a CI/CD pipeline. A CI/CD pipeline will revolutionize your workflow to push code to production.

The purpose of this blog post is to provide instructions on how to setup the necessary components (Gitlab and Gitlab runners) to create a CI/CD pipeline. One of the deliverables from this blog post is Docker composes for Swarm and non-swarm deployments of Gitlab. Additionally, there are manual instructions on how to setup Gitlab runners on Ubuntu 20.04, Ubuntu 20.04 with Docker, Windows 10, Windows 10 with Docker, and macOS Big Sur. In addition, a Docker Registry is setup and integrated into the CI/CD pipeline for custom Docker images. The instructions and the infra-as-code provided in this post will create the foundation for future blogs that will contain a CI/CD component.

Goals

• Setup Gitlab stack with Docker Swarm
• Setup Gitlab runner on Windows
• Setup Gitlab runner on Linux
• Setup Gitlab runner on macOS
• Setup Gitlab runner on Docker Windows
• Setup Gitlab runner on Docker Linux
• Setup a Docker Registry with a self-signed HTTPS certificate

Update log

• September 24th 2021 – Updated Docker from Gitlab v13.8.1 to v14.3.0

Assumptions

• The means to generate DNS A records for each service.
  • These services require DNS records and will NOT work without it!!!
• Docker Swarm or machine running Docker to run Gitlab
• The ability to run VMs but not required
• Access to a macOS machine or VM but not required

Background

What is Gitlab?

GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration and deployment pipeline features, using an open-source license, developed by GitLab Inc.

What is a Gitlab runner?

GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline. You can choose to install the GitLab Runner application on infrastructure that you own or manage. You can install GitLab Runner on several different supported operating systems or GitLab Runner can also run inside a Docker container. A more simplified explanation is a Gitlab runner is essentially a tool that executes the instructions defined in .gitlab-ci.yml and sends the results back to Gitlab.

What is CI/CD?

_{Credit for the creation of this diagram goes to Valentin Despa: Udemy course: GitLab CI: Pipelines, CI/CD and DevOps for Beginners.}

A CI/CD pipeline automates the process of delivering code from a developers machine to production. Obviously that statement is an over simplification of the process because the digram above illustrates numerous steps. This section is going to provide a high overview of the process to help you understand the general process needed for this blog post. CI/CD stands for continuous integration and continuous deployment, which as the acronym and the digram above illustrates is two distinct phases. Continuous integration is the process of integrating new code changes, validating the new code changes can still build/compile the application, and ensuring the new code passes a set of tests.

For example, let’s say you have a web application written in GoLang. As a developer you make some changes to the existing application on your local development machine and push the changes to Gitlab. Next, Gitlab will attempt to compile the existing code base with your changes. Assuming the compilation is successful, Gitlab will perform several tests on the newly compiled application to ensure the application is functioning as intended. If the tests are successful, the developer can merge the changes into the MAIN branch.

Now you might be asking what happens if this phase is unsuccessful? Using the example above, let’s say you initialize a variable that is not used. If you’re a GoLang developer you already know this will fail to compile but for this example let’s say the code is pushed to Gitlab. Gitlab will once again attempt to compile the code that contains your changes. However, the compilation will fail and typically the pipeline will stop running on the first occurrence of an error. Gitlab will provide the developer the ability to review the error produced. Until this issue is resolved Gitlab will not allow the new code to merged.

Continuous deployment is the process of again evaluating/testing the newly committed code, pushing the application to QA for further evaluation, and finally upon manual human interaction the code is pushed to production. Pushing to prod (production) means pushing your code to the environment so that your new code can be utilized by users. Again, as the digram above illustrates there is more to this process but hopefully this provided a high overview of the process. For a more in-depth explanation, I highly recommend checking out the following Udemy course: GitLab CI: Pipelines, CI/CD and DevOps for Beginners.

.gitlab-ci.yml stages

There really aren’t any official stages but the ones listed below outline a typical flow you might see:

• Pre-build – A set of actions to perform before building your application with the newly committed code. During this stage you might install the necessary tools, libraries, or dependencies to build your application.
• Build – A set of actions to build/compile your application with the newly committed code
• Test – A set of actions to run against your newly compiled/built application to ensure everything is functioning as intended
• Deploy – A set of actions that will only run when the build and test stages have successful completed their tasks without any errors. Upon completion, this stage will push the newly committed code to appropriate environment.

Network diagram

Generate OpenSSL private key and public cert

1. git clone https://github.com/CptOfEvilMinions/Gitlab-Automation
2. cd Gitlab-Automation
3. mv conf/tls/tls.conf.example conf/tls/tls.conf
4. vim conf/tls/openssl.conf and set:
   1. Replace {{ base_domain }} with your domain
      1. My base_domain is hackinglab.local
   2. Set the location information under [ my_req_distinguished_name ]
      1. C – Set Coutry
      2. ST – Set state
      3. L – Set City
      4. O – Enter organization name
5. openssl req -x509 -new -nodes -keyout conf/tls/tls.key -out conf/tls/tls.crt -config conf/tls/tls.conf
   1. 1. Generate TLS private key and public certificate

Install Gitlab with Docker-compose v2.x

WARNING

The Docker-compose v2.x setup is for development use ONLY. The setup contains hard-coded credentials in configs and environment variables. For a more secure Docker deployment please skip to the next section to use Docker Swarm which implements Docker secrets.

WARNING

1. vim .env and set

   1. GITLAB_VERSION – OPTIONAL – Set the version of Gitlab to use – Community edition or Enterprise edition
   2. GITLAB_ROOT_PASSWORD – Set the Gitlab root user password
   3. POSTGRES_GITLAB_PASSWORD – Set Postgres Gitlab user password
   4. BASE_DOMAIN – Set this to your domain
2. docker-compose -f docker-compose.yml build
3. docker-compose -f docker-compose.yml up -d

Install Gitlab with Docker-compose v3.x (Swarm)

Create secrets

1. openssl rand -base64 32 | tr -cd '[:alnum:]' | docker secret create gitlab-postgres-gitlab-password -
   1. Create password for Gitlab Postgres password
2. GITLAB_ROOT_PASSWORD=$(openssl rand -base64 32 | tr -cd '[:alnum:]')
   1. Generate Gitlab root password
3. echo $GITLAB_ROOT_PASSWORD
   1. Print Gitlab root password – record for later
4. echo -n $GITLAB_ROOT_PASSWORD | docker secret create gitlab-root-password -
   1. Create Gitlab root password

Docker start stack

1. docker stack deploy -c docker-compose-swarm.yml gitlab
2. docker service logs -f gitlab_nginx
   1. Monitor logs until NGINX prints /docker-entrypoint.sh: Configuration complete; ready for start up

Login into Gitlab WebGUI

1. Open web browser to https://<Docker IP addr>:8443
   1. Enter root as username
   2. Enter <Gitlab root password> for password
   3. Select “Sign in”

Use Docker Registry

Push image to Registry

1. cd Gitlab-Automation
2. Add self-signed certificate for the Docker Registry to your certificate store
   1. MacOS
   2. Windows
   3. Linux
3. Instructions for macOS
   1. security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain conf/tls/tls.crt
      1. Add Registry certificate to the user’s local keychain
      2. Enter password
      3. Restart Docker Desktop on macOS
4. docker build -f docker/Dockerfile-ubuntu-custom -t ubuntu-custom .
5. docker image ls | grep ubuntu-custom
   1. Grab image ID
6. docker tag <custom Ubuntu image ID> registry.hackinglab.local:5000/custom-ubuntu
7. docker push registry.hackinglab.local:5000/custom-ubuntu

Pull image from Registry

Since the certificate for the Registry is self-signed Docker will NOT pull the image. The instructions below are how to add the self-signed certificate for the Docker Registry to the OS root cert store.

1. SSH into Docker Swarm node
2. sudo su
3. openssl s_client -connect registry.<base_domain>:5000 2>/dev/null </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /usr/local/share/ca-certificates/ca.crt
   1. Obtain the public certificate from the remote server
4. update-ca-certificates --fresh
   1. Instruct Ubuntu to add the new cert to the cert root store
5. systemctl restart docker
6. docker pull registry.<base_domain>:5000/custom-ubuntu

Install/Setup Gitlab runner

This section will cover how to setup a Gitlab runner on Windows 10, Windows 10 with Docker, Ubuntu 20.04, Ubuntu 20.04 with Docker, and macOS Big Sur. It should be noted that setting up a Gitlab runner on Docker is the optimal setup. Running a Gitlab runner on a VM will not provide a clean state between CI/CD runs. Meaning that if you have an Ubuntu 20.04 VM and the first CI/CD run installs Java 8 but the second run requires Java 7 you will have to uninstall Java 8 first to avoid dependency conflicts.

However, the other side of this coin is you can have a Gitlab runner with a pre-defined environment. Therefore the runs can assume that the correct Java version is installed and you just need to build and run the code. Docker containers provide the advantage that each container is a blank canvas ready to be crafted to the need of the run.

Obtain Gitlab runner register token

1. Login in as a Gitlab admin
2. Admin area > Overview > Runners
3. Copy runners token
4. Copy Gitlab runner URL

Install/Setup Gitlab runner on Docker

1. GITLAB_RUNNER_DOCKER_TOKEN=$(curl -k -s -X POST https://gitlab.<base_domain>:8443/api/v4/runners --form "token=<Gitlab runner registration token>" --form "description=Docker" | jq -r .token | tr -d 'n' )
   1. Generate Gitlab runner token
2. echo $GITLAB_RUNNER_DOCKER_TOKEN
3. cp conf/gitlab-runner/docker-gitlab-runner.toml.example conf/gitlab-runner/docker-gitlab-runner.toml
4. cat conf/gitlab-runner/docker-gitlab-runner.toml | sed 's#{{ gitlab_runner_url }}#https://gitlab.<base_domain>:8443/#g' | sed "s#{{ gitlab_runner_token }}#${GITLAB_RUNNER_DOCKER_TOKEN}#g" | docker secret create gitlab-runner-config -
   1. Create Gitlab runner config containing Gitlab runner token
5. docker stack deploy -c docker-compose-swarm-gitlab-runners.yml gitlab-runner
   
6. docker service logs -f gitlab-runner_gitlab-runner
   
7. Admin area > Overview > Runners
8. Select “Edit” for the runner
   1. Enter linux,docker into the tags field
   2. Select “Save changes”

Install/Setup Gitlab runner on Windows 10

Install GIT

1. Log into Windows
2. Open Powershell as Administrator
3. Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
   1. Install Chocolately 
4. choco install git
   1. Install GIT

Install/Setup Gitlab runner

1. Log into Windows
2. Open Powershell as Administrator
3. mkdir 'C:Program Filesgitlab-runner'
   1. Make a directory for Gitlab
4. cd 'C:Program Filesgitlab-runner'
5. $ProgressPreference = 'SilentlyContinue'
   1. Download executable without status bar – faster download
6. Invoke-WebRequest -Uri https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe -OutFile gitlab-runner.exe
   1. Download Gitlab runner
7. Open Chrome
8. Browse to Gitlab homepage
9. Select the “Not secure” button next to the address bar then “Certificate”
   1. Select. “Details” tab
   2. Select “Copy to file”
   3. Follow the instructions to export the certificate to the Desktop
      1. Select “Base-64 encoded X.509 (.CER)” for format
10. Move the public certificate to  C:Program Filesgitlab-runner
11. Return to Powershell terminal
12. .gitlab-runner.exe register --tls-ca-file .gitlab.cer
    1. Register Gitlab runner
    2. Enter https://gitlab.<base_domain>:8443
    3. Enter <registration token>
    4. Enter WindowsVM for description
    5. Enter windows, win10_1909 for tags
    6. Enter shell for executor
13. .gitlab-runner.exe install
    1. Install Gitlab runner as a service
14. .gitlab-runner.exe start
    1. Start Gitlab runner service

Install/Setup Gitlab runner on Windows 10 with Docker

Install Hyper-V

1. Log into Windows
2. Open Powershell as Administrator
3. Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
   1. Install Hyper-V
4. Reboot

Install WSL v2 with Linux kernel

1. Log into Windows
2. Open Powershell as Administrator
3. dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   1. Enable the Windows Subsystem for Linux
4. Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
   1. Enable Virtual Machine feature
5. cd $ENV:TMP
6. $ProgressPreference = 'SilentlyContinue'
7. Invoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile wsl_update_x64.msi
   1. Download the Linux kernel update package
8. msiexec.exe /i "wsl_update_x64.msi" /quiet /qn /norestart
   1. Install updated Linux kernel
9. wsl --set-default-version 2
   1. Set WSL 2 as default

Install Docker

1. Log into Windows
2. Open Powershell as Administrator
3. cd $ENV:TEMP
   1. Enter user’s temporary directory
4. $ProgressPreference = 'SilentlyContinue'
   1. Download executable without status bar – faster download
5. Invoke-WebRequest -Uri https://desktop.docker.com/win/stable/Docker%20Desktop%20Installer.exe -OutFile DockerDesktopInstaller.exe
   1. Download Docker
6. .DockerDesktopInstaller.exe install --quiet
   1. Install Docker
7. Logout and Sign back in
8. Start Docker if has no started on it’s own
   1. & 'C:Program FilesDockerDockerDocker Desktop.exe'

Install and register Gitlab-runner

1. mkdir 'C:Program Filesgitlab-runner'
   1. Make a directory for Gitlab
2. cd 'C:Program Filesgitlab-runner'
3. Invoke-WebRequest -Uri https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe -OutFile gitlab-runner.exe
   1. Download Gitlab runner
4. Open Chrome
5. Browse to Gitlab homepage
6. Select the “Not secure” button next to the address bar then “Certificate”
7. Select. “Details” tab
8. Select “Copy to file”
9. Follow the instructions to export the certificate to the Desktop
   1. Select “Base-64 encoded X.509 (.CER)” for format
10. Move the public certificate to  C:Program Filesgitlab-runner
11. Return to Powershell terminal
12. .gitlab-runner.exe register --tls-ca-file .gitlab.cer
    1. Register Gitlab runner
    2. Enter https://gitlab.<base_domain>:8443
    3. Enter <registration token>
    4. Accept the VM’s hostname as the Gitlab runner’s name
    5. Enter windows, docker for tags
    6. Enter docker-windows for executor
    7. Accept default Windows image
13. docker pull mcr.microsoft.com/windows/servercore:1809
14. docker pull gitlab/gitlab-runner-helper: x86_64-775dd39d-servercore1909 
    1. Download Windows image
15. In the Windows system tray right-click Docker and select “Switch to Windows Containers”
    1. Select “Switch” on the pop-up
16. .gitlab-runner.exe install
    1. Install Gitlab runner as a service
17. .gitlab-runner.exe start
    1. Start Gitlab runner service

Install/Setup Gitlab runner on Ubuntu 20.04

1. SSH into Ubuntu
2. sudo su
3. apt update -y && apt install curl openssl -y
4. cd /tmp && curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb"
   1. Download Gitlab runner
5. dpkg -i gitlab-runner_amd64.deb
   1. Install Gitlab runner
6. mkdir /etc/gitlab-runner/certs
   1. Create a directory to store the Gitlab cert
7. openssl s_client -connect gitlab.<base_domain>:8443 2>/dev/null </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /etc/gitlab-runner/certs/gitlab.crt
   1. Grab a copy of the public cert for Gitlab
8. gitlab-runner register --tls-ca-file /etc/gitlab-runner/certs/gitlab.crt
   1. Register Gitlab runner
   2. Enter https://gitlab.<base_domain>:8443
   3. Enter <registration token>
   4. Enter ubuntuvm
   5. Enter linux, ubuntu2004 for tags
   6. Enter shell for executor
9. rm -rd /home/gitlab-runner/* 
   1. Delete all the dotfiles which are executed on every job run
10. systemctl restart gitlab-runner
11. systemctl enable gitlab-runner

Install/Setup Gitlab runner on macOS Big Sur

1. Log into macOS
2. Open terminal
3. sudo su
4. cd /tmp && curl https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64 --output gitlab-runner-darwin-amd64.bin
   1. Download Gitlab runner
5. mv gitlab-runner-darwin-amd64.bin /usr/local/bin/gitlab-runner
6. chmod +x /usr/local/bin/gitlab-runner
   1. Install Gitlab runner
7. mkdir -p /etc/gitlab-runner/certs
8. cd /etc/gitlab-runner/certs
9. openssl s_client -connect gitlab.<base_domain>:8443 2>/dev/null </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /etc/gitlab-runner/certs/gitlab.crt
   1. Grab a copy of the public cert for Gitlab
10. gitlab-runner register --tls-ca-file /etc/gitlab-runner/certs/gitlab.crt
    1. Register Gitlab runner
    2. Enter https://gitlab.<base_domain>:8443
    3. Enter <registration token>
    4. Enter macosvm for description
    5. Enter macos, macos11for tags
    6. Enter shell for executor
11. gitlab-runner install
12. gitlab-runner start
    

Ensure all agents have checked in

1. Login in as a Gitlab admin
2. Admin area > Overview > Runners

Create Gitlab pipeline

Step 1: Create example repo

1. From the Gitlab user homepage
2. Select “New Project”
3. Select “Create blank project”
   1. Enter Test-gitlab-runner as Project name
   2. Select “Create project”

Step 2: Create .gitlab-ci.yml

1. Select “Project overview” in the top left
2. Select “New file” and select it again
3. Enter .gitlab-ci.yml as the file name
4. Open a web browser to https://github.com/CptOfEvilMinions/Gitlab-Automation/blob/main/gitlab-ci-example.yml
   1. Copy the contents
5. Paste the contents into .gitlab-ci.yml
6. Select “Commit” in bottom left
7. Select “Commit” again in the bottom left

Step 3: Review pipeline jobs

Pipeline jobs

1. Go to the Test-gitlab-runner repo
2. CI/CD > Pipelines
3. Select the latest pipeline run

test_linux_runner

test_macos_runner

test_win_runner

test_docker_runner

test_win_docker_runner

Shoutout

A personal shout out to Valentin Despa’s Gitlab course on Udemy: GitLab CI: Pipelines, CI/CD and DevOps for Beginners. I would highly recommend taking this class to learn more about Gitlab, Gitlab runners, and creating Gitlab CI/CD pipelines in-depth.

Lessons learned

New skills/knowledge

• Learned how to use environment variables in NGINX configs per this StackOverFlow post
• Learned about how to the utility sv to interact with services
• How to use Windows Docker containers
• Learned how to setup Gitlab runners
• Learned how to create a Gitlab CI/CD pipeline
• Learned how to push and pull images to the Docker Registry

What You’d Do Differently

• Build our Ansible playbooks for each Gitlab runner
• In an enterprise environment I would implement PKI to ensure all certificates are trusted

References

• Substitute environment variables in NGINX config from docker-compose
• Install GitLab Runner manually on GNU/Linux
• Install Hyper-V on Windows 10
• Powershell – Why is Using Invoke-WebRequest Much Slower Than a Browser Download?
• Silent installation of a MSI package
• How to Install WSL 2 on Windows 10 (Updated)
• Get started: Prep Windows for containers
• Docker Registry HTTP API V2
• Using openssl to get the certificate from a server
• Self-signed certificates or custom Certification Authorities

Вы можете установить GitLab Runner в разных операционных системах, установив систему контроля версий Git и создав учетную запись пользователя на сайте GitLab.

Git – система контроля версий, используемая для –

• Обработка исходного кода истории проектов
• Отслеживание изменений, внесенных в файлы
• Быстрая и эффективная работа с небольшими и большими проектами.
• Сотрудничать с другими разработчиками в разных проектах

GitLab – это основанная на Git платформа, предоставляющая удаленный доступ к репозиториям Git и полезная для цикла разработки программного обеспечения, создавая частные и публичные репозитории для управления кодом.

GitLab поддерживает различные типы операционных систем, таких как Windows, Ubuntu, Debian, CentOS, open SUSE и Raspberry Pi 2. В этой главе мы обсудим, как установить GitLab в операционных системах Windows и Ubuntu.

Установка GitLab на Windows:

Шаг 1 – Сначала создайте папку с именем «GitLab-Runner» в вашей системе. Например, вы можете создать на диске C как C: GitLab-Runner.

Шаг 2 – Теперь скачайте бинарный файл для x86 или amd64 и скопируйте его в созданную вами папку. Переименуйте загруженный бинарный файл в gitlab-runner.exe .

Шаг 3 – Откройте командную строку и перейдите в созданную папку. Теперь введите приведенную ниже команду и нажмите ввод.

C:GitLab-Runner>gitlab-runner.exe register

Шаг 4 – После выполнения вышеупомянутой команды она попросит ввести URL-адрес координатора gitlab-ci.

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
https://gitlab.com

Шаг 5 – Введите токен gitlab-ci для бегуна.

Please enter the gitlab-ci token for this runner:
xxxxx

• Чтобы получить токен, войдите в свою учетную запись GitLab –

Чтобы получить токен, войдите в свою учетную запись GitLab –

• Теперь перейдите к вашему проекту –

Теперь перейдите к вашему проекту –

• Нажмите на опцию CI / CD на вкладке Настройки и разверните опцию Настройки бегунов .

Нажмите на опцию CI / CD на вкладке Настройки и разверните опцию Настройки бегунов .

• В разделе « Настройки бегунов » вы получите токен, как показано на рисунке ниже –

В разделе « Настройки бегунов » вы получите токен, как показано на рисунке ниже –

Шаг 6 – Введите описание gitlab-ci для бегуна.

Please enter the gitlab-ci description for this runner:
[Admin-PC]: Hello GitLab Runner

Шаг 7 – Он попросит ввести теги gitlab-ci для бегуна.

Please enter the gitlab-ci tags for this runner (comma separated):
tag1, tag2

Вы можете изменить эти теги в пользовательском интерфейсе GitLab позже.

Шаг 8 – Вы можете привязать Runner к текущему проекту, установив для него значение true.

Whether to lock the Runner to current project [true/false]:
[true]: true

После выполнения описанных выше шагов вы получите сообщение об успешной регистрации: «Регистрация участника … выполнена успешно».

Шаг 9 – Теперь введите Runner executor для построения проекта.

Please enter the executor: parallels, shell, docker+machine, kubernetes, docker-
ssh+machine, docker, docker-ssh, ssh, virtualbox:
docker

Мы использовали селектор как «докер», который создает среду сборки и легко управляет зависимостями для разработки проекта.

Шаг 10 – Затем он попросит установить изображение по умолчанию для селектора докеров.

Please enter the default Docker image (e.g. ruby:2.1):
alpine:latest

Шаг 11 – После выполнения вышеуказанных шагов на экране появится сообщение «Бегун успешно зарегистрирован». На изображении ниже будет описан рабочий процесс вышеуказанных команд –

Шаг 12 – Теперь перейдите к своему проекту, нажмите на опцию CI / CD в разделе « Настройки », и вы увидите активированных бегунов для проекта.

Вы можете увидеть конфигурацию GitLab Runner в файле config.toml в папке GitLab-Runner, как показано ниже –

concurrent = 1
check_interval = 0
[[runners]]
  name = "Hello GitLab Runner"
  url = "https://gitlab.com"
  token = "40ceed29eec231fa9e306629cae4d7"
  executor = "docker"
  [runners.docker]
      tls_verify = false
      image = "alpine:latest"
      privileged = false
      disable_cache = false
      volumes = ["/cache"]
      shm_size = 0
  [runners.cache]

Установка GitLab на Ubuntu

GitLab может быть установлен в системе Ubuntu с помощью пакета Omnibus , который предоставляет различные сервисы для запуска GitLab. Пакет Omnibus предоставляет необходимые компоненты GitLab, устанавливает конфигурации и метаданные проекта, которые можно использовать в системе пользователя.

Следующие шаги описывают установку GitLab в Ubuntu –

Шаг 1 – Сначала войдите на ваш сервер GitLab с помощью SSH (Secure Shell).

Шаг 2 – Затем загрузите пакет Omnibus –

wget https://downloads-packages.s3.amazonaws.com/ubuntu-14.04/gitlab-ce_7.10.4~omnibus-1_amd64.deb

Шаг 3 – Установите постфикс –

sudo apt-get install postfix

Postfix – это агент передачи почты с открытым исходным кодом, используемый для доставки уведомлений по электронной почте.

Шаг 4 – При установке Postfix, он спросит тип установки; затем выберите вариант Интернет-сайта . Далее он покажет конфигурацию Postfix вместе с системным почтовым именем, как показано на рисунке –

Шаг 5 – Установите dpkg (менеджер пакетов для системы Debian) для управления установленными пакетами –

sudo dpkg -i gitlab-ce_7.10.4~omnibus-1_amd64.deb

Шаг 6 – Чтобы изменения вступили в силу, вам нужно перенастроить GitLab с помощью следующей команды:

sudo gitlab-ctl reconfigure

Шаг 7 – Проверьте состояние сервисов GitLab с помощью команды ниже –

sudo gitlab-ctl status

Если вы хотите установить GitLab из исходного кода, установите некоторые зависимости на сервере и вам необходимо настроить базу данных с помощью PostgreSQL. Это описано в главе Настройка среды . Вы можете установить координатор для создания веб-интерфейса и управления экземплярами сборки. Для получения дополнительной информации вы можете проверить главу Установка координатора .

По натуре своей многие разработчики слишком ленивые не любят делать одно и то же действие много раз. Нам проще научить компьютер, чтобы он делал монотонные действия за нас.

Как только кто-либо из нашей команды вносит изменения в код (читай «мерджит feature-ветку в develop»), наш билд-сервер:

• Собирает исходный код и установщик приложения
  • проставляет номер сборки, каждый раз увеличивая последнюю цифру. Например, текущая версия нашего ПО 3.3.0.202 – часть 3.3.0 когда-то ввёл разработчик (привет, SemVer), а «202» проставляется в процессе сборки.
  • В процессе анализирует качество кода (с использованием SonarQube) – и отправляет отчёт во внутренний SonarQube,
• Сразу после сборки запускает автотесты (xUnit) и анализирует покрытие тестами (OpenCover),

Также, в зависимости от ветки, в которую были внесены изменения, могут быть выполнены:

• отправка сборки (вместе с changelog-ом) в один или несколько телеграм-каналов (иногда удобнее брать сборки оттуда).
• публикация файлов в систему автообновления ПО.

Под катом о том, как мы научили Gitlab CI делать за нас бОльшую часть этой муторной работы.

Оглавление

1. Устанавливаем и регистрируем Gitlab Runner.
2. Что нужно знать про .gitlab-ci.yml и переменные сборки.
3. Активируем режим Developer PowerShell for VS.
4. Используем CI для проставления версии во все сборки решения.
5. Добавляем отправку данных в SonarQube.
6. «Причёсываем» автотесты xUnit + добавляем вычисление покрытия тестами через OpenCover.
7. Послесловие.

Перед началом

Чтобы быть уверенными, что написанное ниже работает, мы взяли на github небольшой проект, написанный на WPF и имеющий unit-тесты, и воспроизвели на нём описанные в статье шаги. Самые нетерпеливые могут сразу зайти в созданный на сайте gitlab.com репозиторий и посмотреть, как это выглядит.

Устанавливаем и регистрируем Gitlab Runner

Для того чтобы Gitlab CI мог что-либо собрать, сначала установите и настройте Gitlab Runner на машине, на которой будет осуществляться сборка. В случае проекта на .Net Framework это будет машина с ОС Windows.

Чтобы настроить Gitlab Runner, выполните следующие шаги:

1. Установите Git для Windows с сайта git.
2. Установите Visual Studio с сайта Microsoft. Мы поставили себе Build Tools для Visual Studio 2019. Чтобы скачать именно его, разверните список Инструменты для Visual Studio 2019.
3. Создайте папку C:GitLab-Runner и сохраните в неё программу gitlab runner. Скачать её можно со страницы [документации Gitlab] (https://docs.gitlab.com/runner/install/windows.html) — ссылки скрыты прямо в тексте: «Download the binary for x86 or amd64».
4. Запустите cmd или powershell в режиме администратора, перейдите в папку C:GitLab-Runner и запустите скачанный файл с параметром install (Gitlab runner установится как системная служба).

       .gitlab-runner.exe install

5. Посмотрите токен для регистрации Runner-а. В зависимости от того, где будет доступен ваш Runner:
   • только в одном проекте — смотрите токен в меню проекта Settings > CI/CD в разделе Runners,
   • в группе проектов — смотрите токен в меню группы Settings > CI/CD в разделе Runners,
   • для всех проектов Gitlab-а — смотрите токен в секции администрирования, меню Overview > Runners.
6. Выполните регистрацию Runner-а, с помощью команды

       .gitlab-runner.exe register

Далее надо ввести ответы на вопросы мастера регистрации Runner-а:

• coordinator URL — http или https адрес вашего сервера gitlab;
• gitlab-ci token — введите токен, полученный на предыдущем шаге;
• gitlab-ci description — описание Runner-а, которое будет показываться в интерфейсе Gitlab-а;
• gitlab-ci tags — через запятую введите тэги для Runner-а. Если вы не знакомы с этим механизмом, оставьте поле пустым — отредактировать его можно позднее через интерфейс самого gitlab-а. Тэги можно использовать для того, чтобы определённые задачи выполнялись на определённых Runner-ах (например, чтобы настроить сборку ПО на Runner-е, развёрнутом на копьютере ОС Windows, а подготовку документации на Runner-е с ОС Linux);
• enter the executor — ответьте shell. На этом шаге указывается оболочка, в которой будут выполняться команды; при указании значения shell под windows выбирается оболочка powershell, а последующие скрипты написаны именно для неё.

Что нужно знать про .gitlab-ci.yml и переменные сборки

В процессе своей работы Gitlab CI берёт инструкции о том, что делать в процессе сборки того или иного репозитория из файла .gitlab-ci.yml, который следует создать в корне репозитория.

Вбив в поиске содержимое .gitlab-ci.yml для сборки приложения .NET Framework можно найти несколько шаблонов: 1, 2. Выглядят они примерно так:

variables:
  # Максимальное количество параллельно собираемых проектов при сборке решения; зависит от количества ядер ПК, выбранного для сборки
  MSBUILD_CONCURRENCY: 4
  # Тут куча путей до утилит, которые просто обязаны лежать там, где ожидается
  NUGET_PATH: 'C:ToolsNugetnuget.exe'
  MSBUILD_PATH: 'C:Program Files (x86)Microsoft Visual Studio2017BuildToolsMSBuild15.0Binmsbuild.exe'
  XUNIT_PATH: 'C:Toolsxunit.runner.console.2.3.1xunit.console.exe'
  TESTS_OUTPUT_FOLDER_PATH: '.testsCiCdExample.TestsbinRelease'

# Тут указываются стадии сборки. Указывайте любые названия которые вам нравятся, но по умолчанию используют три стадии: build, test и deploy.
# Стадии выполняются именно в такой последовательности.
stages:
  - build
  - test

# Далее описываются задачи (job-ы)

build_job:
  stage: build # указание, что задача принадлежит этапу build
  # tags: windows # если тут указать тэг, задача будет выполняться только на Runner-е с указанным тэгом 
  only: # для каких сущностей требуется выполнять задачу
    - branches
  script: # код шага
    - '& "$env:NUGET_PATH" restore'
    - '& "$env:MSBUILD_PATH" /p:Configuration=Release /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly' # сборка; ключ clp:ErrorsOnlyоставляет только вывод ошибок; ключ nr:false завершает инстансы msbuild 
  artifacts: # где по завершении задачи будут результаты, которые надо сохранить в gitlab (т.н. артефакты) и которые можно будет передать другим задачам по цепочке
    expire_in: 2 days # сколько хранить артефакты
    paths: # список путей, по которым находятся файлы для сохранения
      - '$env:TESTS_OUTPUT_FOLDER_PATH'

test_job:
  stage: test
  only:
    - branches
  script:
    - '& "$env:XUNIT_PATH" "$env:TESTS_OUTPUT_FOLDER_PATHCiCdExample.Tests.dll"'
  dependencies: # указание, что для запуска этой задачи требуется успешно завершенная задача build_job
    - build_job

И последнее: если нам требуется передавать в скрипт значение параметра, который мы не хотим хранить в самом скрипте (например, пароль для подключения куда-либо), мы можем использовать для этого объявление параметров в gitlab. Для этого зайдите в проекте (или в группе проекта) в Settings > CI/CD и найдите раздел Variables. Прописав в нём параметр с именем (key) SAMPLE_PARAMETER, вы сможете получить его значение в в скрипте .gitlab-ci.yml через обращение $env:SAMPLE_PARAMETER.

Также в этом разделе можно настроить передачу введенных параметров только при сборке защищённых веток (галочка Protected) и/или скрытие значения параметра из логов (галочка Masked).

Подробнее о параметрах окружения сборки смотрите в документации к Gitlab CI.

Активируем режим Developer PowerShell for VS

Скрипт, приведённый выше, уже можно использовать для сборки и вызова тестов. Правда, присутствует НО: крайне неудобно прописывать абсолютные пути к разным установкам Visual Studio. К примеру, если на одной билд-машине стоит Visual Studio 2017 BuildTools, а на другой Visual Studio Professional 2019, то такой скрипт будет работать только для одной из двух машин.

К счастью, с версии Visual Studio 2017 появился способ поиска всех инсталляций Visual Studio на компьютере. Для этого существует утилита vswhere, путь к которой не привязан ни к версии Visual Studio, ни к её редакции. А в Visual Studio 2019 (в версии 16.1 или более новой) есть библиотека, которая умеет «трансформировать» консоль Powershell в режим Developer Powershell, в котором уже прописаны пути к утилитам из поставки VS.

Как применить

Дописываем переменную к секции Variables:

variables:
  VSWHERE_PATH: '%ProgramFiles(x86)%Microsoft Visual StudioInstallervswhere.exe'

Затем создаём новую секцию before_msbuild якорем enter_vsdevshell и следующим текстом:

.before_msbuild: &enter_vsdevshell
  before_script:
    - '$vsWherePath = [System.Environment]::ExpandEnvironmentVariables($env:VSWHERE_PATH)'
    - '& $vsWherePath -latest -format value -property installationPath -products Microsoft.VisualStudio.Product.BuildTools | Tee-Object -Variable visualStudioPath'
    - 'Join-Path "$visualStudioPath" "Common7ToolsMicrosoft.VisualStudio.DevShell.dll" | Import-Module'
    - 'Enter-VsDevShell -VsInstallPath:"$visualStudioPath" -SkipAutomaticLocation'

И всюду, где нам надо использовать утилиты Visual Studio, добавляем этот якорь. После этого задача сборки начинает выглядеть намного более опрятно:

build_job:
  <<: *enter_vsdevshell
  stage: build
  only:
    - branches
  script:
    - 'msbuild /t:restore /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
    - 'msbuild /p:Configuration=Release /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
  artifacts:
    expire_in: 2 days
    paths:
      - '$env:TESTS_OUTPUT_FOLDER_PATH'

Результат: мы получили полноценную консоль Developer Powershell с прописанными путями к msbuild и многим другим утилитам, которые можно использовать при сборке.

Используем CI для проставления версии во все сборки решения

Раньше мы использовали t4 шаблоны для проставления версий: номер версии собиралась из содержимого файла в формате <major>.<minor>.<revision>, далее к ней добавлялся номер сборки из Gitlab CI и он передавался в tt-шаблон, добавляющий в решение везде, где требуется, номер версии. Однако некоторое время назад был найден более оптимальный способ — использование команд git tag и git describe.

Команда git tag устанавливает коммиту метку (тэг). Отметить таким образом можно любой коммит в любой момент времени. В отличие от веток, метка не меняется. То есть если после помеченного коммита вы добавите ещё один, метка останется на помеченном коммите. Если попробуете переписать отмеченный коммит командами git rebase или git commit —amend, метка также продолжит указывать на исходный коммит, а не на изменённый. Подробнее о метках смотрите в git book.

Команда git describe, к сожалению, в русскоязычном gitbook не описана. Но работает она примерно так: ищет ближайшего помеченного родителя текущего коммита. Если такого коммита нет — команда возвращает ошибку fatal: No tags can describe '<тут хэш коммита>'. А вот если помеченный коммит нашёлся — тогда команда возвращает строку, в которой участвует найденная метка, а также количество коммитов между помеченным и текущим.

На заметку: чтобы данная команда работала корректно во всех случаях, автор gitflow даже чуть-чуть поменял скрипты finish hotfix и finish release. Если кому интересно посмотреть обсуждение с автором gitflow, а также увидеть что изменилось (картинка с актуальной схемой в последнем сообщении в треде).

Кстати, по этой же причине если вы используете gitflow, после вливания feature-ветки в develop требуется удалить влитую локальную ветку, после чего пересоздать её от свежего develop:

(обратите внимание на историю git в левой части картинки: из-за отсутствия пути из текущего коммита до коммита с меткой 1.0.5, команда git describe выдаст неверный ответ)

Но вернёмся к автопроставлению версии. В нашем репозитории царит gitflow (точнее его rebase-версия), метки расставляются в ветке master и мы не забываем пересоздавать feature-ветки от develop, а также merge-ить master в develop после каждого релиза или хотфикса.

Тогда получить версию для любого коммита и сразу передать её в msbuild можно добавив всего пару строк к задаче сборки:

build_job:
  <<: *enter_vsdevshell
  stage: build
  only:
    - branches
  script:
    - 'msbuild /t:restore /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
    - '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+).(?<minor>[0-9]*).(?<patch>[0-9]*)-(?<commit>[0-9]+)-g[0-9a-f]+" | Select-Object -First 1'
    - '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'
    - '[string]$version = "$major.$minor.$patch.$commit"'
    - 'msbuild /p:Configuration=Release /p:AssemblyVersionNumber=$version /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
  artifacts:
    expire_in: 2 days
    paths:
      - '$env:TESTS_OUTPUT_FOLDER_PATH'

Как это работает:

1. Мы проставляем метки в формате <major>.<minor>.<revision>.
2. Тогда git describe --long возвращает нам строку, описывающую версию в формате <major>.<minor>.<revision>-<количество новых коммитов>-g<хэш текущего коммита>.
3. Парсим полученную строку через регулярные выражения, выделяя нужные нам части — и записывем части в $versionGroup.
4. Преобразовываем четыре найденные подстроки в 4 числа и пишем их в переменные $major, $minor, $patch, $commit, после чего собираем из них строку уже в нужном нам формате.
5. Передаём указанную строку в msbuild чтобы он сам проставил версию файлов при сборке.

Обратите внимание: если вы, согласно gitflow, будете отмечать (тэгировать) ветку master после вливания в неё release или hofix, будьте внимательны: до простановки метки автосборка будет вестись относительно последней существующей ветки. Например, сейчас опубликована версия 3.4, а вы создаёте release-ветку для выпуска версии 3.5. Так вот: всё время существования этой ветки, а также после её вливания в master, но до простановки тэга, автосборка будет проставлять версию 3.4.

Добавляем отправку данных в SonarQube

SonarQube — это мощный инструмент контроля качества кода.

SonarQube имеет бесплатную Community-версию, которая способна проводить полный анализ. Правда, только одной ветки. Чтобы настроить её на контроль качества ветки разработки (develop), требуется выполнить следующие шаги (разумеется, помимо установки и развёртывания сервера SonarQube):

1. Создайте в SonarQube новый проект, после чего запомните его ключ.
2. Скачайте SonarScanner for MSBuild (с сайта sonarqube.org)[https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-msbuild/] — мы используем версию .NET Framework 4.6+.
3. Распакуйте содержимое архива в папку. Например, в C:ToolsSonarScanner.
   На заметку: эту утилиту также можно скачать на сборочную машину через NuGet, но тогда надо будет чуть по-иному указывать её путь.
4. Зайдите в параметры CI/CD в свойствах проекта Gitlab и добавьте следующие параметры:
   • SONARQUBE_PROJECT_KEY — ключ проекта,
   • SONARQUBE_AUTH_TOKEN — токен авторизации.

     Прописывать параметр ключа проекта необходимо для каждого проекта отдельно (ведь у каждого проекта свой уникальный ключ). А параметр токена авторизации желательно скрыть (отметить как Masked) чтобы он не был доступен всем, кто имете доступ к репозиторию или логам сборки.

5. Допишите переменные к секции Variables:

       variables:
         SONARSCANNER_MSBUILD_PATH: 'C:ToolsSonarScannerSonarScanner.MSBuild.exe'
         SONARQUBE_HOST_URL: 'url вашего сервера SonarQube'

6. Допишите в задачу тестирования ветки разработки (test_job) команды для запуска анализа кода и уберите зависимость от задачи build_job:

       test_job:
         stage: test
         only:
           - /^develop$/
         <<: *enter_vsdevshell
         script:
           - '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+).(?<minor>[0-9]*).(?<patch>[0-9]*)-(?<commit>[0-9]+)-g[0-9a-f]+" | Select-Object -First 1'
           - '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'
           - '[string]$version = "$major.$minor.$patch.$commit"'
           - '& "$env:SONARSCANNER_MSBUILD_PATH" begin /key:$env:SONARQUBE_PROJECT_KEY /d:sonar.host.url=$env:SONARQUBE_HOST_URL /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN /d:sonar.gitlab.project_id=$CI_PROJECT_PATH /d:sonar.gitlab.ref_name=develop /v:$version /d:sonar.dotnet.excludeGeneratedCode=true'
           - 'msbuild /t:rebuild /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
           - '& "$env:SONARSCANNER_MSBUILD_PATH" end /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN'
           - '& "$env:XUNIT_PATH" "$env:TESTS_OUTPUT_FOLDER_PATHCiCdExample.Tests.dll"'

Теперь при каждой сборке ветки develop в SonarQube будет отправляться подробный анализ нашего кода.

На заметку: вообще команда msbuild /t:rebuild полностью пересобирает решение. Вероятно, в большинстве проектов анализ можно было бы встроить прямо в стадию сборки. Но сейчас у нас анализ в отдельной задаче.

Пара слов об использованных параметрах:

• key — ключ проекта на сервере SonarQube,
• v — собираемая версия. Отлично комбинируется с предыдущим шагом автопроставления версии,
• sonar.gitlab.project_id — ID проекта на сервере Gitlab,
• sonar.gitlab.ref_name — название ветки, которое получает сервер SonarQube при передаче результатов анализа,
• sonar.dotnet.excludeGeneratedCode — не включать в анализ объекты, отмеченные атрибутом System.CodeDom.Compiler.GeneratedCode (чтобы не оценивать качество автосгенерированного кода).

«Причёсываем» автотесты xUnit + добавляем вычисление покрытия тестами через OpenCover

Со сборкой более-менее разобрались — теперь приступаем к тестам. Доработаем код прогона тестов, чтобы он:

• сам находил библиотеки с тестами,
• прогонял их пачкой через xUnit,
• вычислял тестовое покрытие через OpenConver,
• отправлял результаты покрытия тестами в SonarQube.

На заметку: обычно в паре с OpenCover используют ReportGenerator, но при наличии SonarQube мы с тем же успехом можем смотреть результаты через его интерфейс.

Для настройки выполним следующие шаги:

1. Скачайте OpenCover в виде zip-файла с сайта github.
2. Распакуйте содержимое архива в папку. Например, в C:ToolsOpenCover.
   На заметку: эту утилиту также можно скачать на сборочную машину через NuGet, но тогда надо будет чуть по-иному указывать её путь.
3. Допишите переменные к секции Variables:

       variables:
         OBJECTS_TO_TEST_REGEX: '^Rt[^n]*.(dll|exe)$'
         OPENCOVER_PATH: 'C:Toolsopencover-4.7.922xunit.console.exe'
         OPENCOVER_FILTER: '+[Rt.*]* -[*UnitTests]* -[*AssemblyInfo]*'
         OPENCOVER_REPORT_FILE_PATH: '.cover.xml'

4. Модифицируйте задачу тестирования ветки разработки (test_job), чтобы она включала и команды вызова OpenCover:

       test_job:
         stage: test
         only:
           - /^develop$/
         <<: *enter_vsdevshell
         script:
           - '$versionGroup = git describe --long | Select-String -Pattern "(?<major>[0-9]+).(?<minor>[0-9]*).(?<patch>[0-9]*)-(?<commit>[0-9]+)-g[0-9a-f]+" | Select-Object -First 1'
           - '[int]$major, [int]$minor, [int]$patch, [int]$commit = $versionGroup.Matches[0].Groups["major", "minor", "patch", "commit"].Value'
           - '[string]$version = "$major.$minor.$patch.$commit"'
           - '& "$env:SONARSCANNER_MSBUILD_PATH" begin /key:$env:SONARQUBE_PROJECT_KEY /d:sonar.host.url=$env:SONARQUBE_HOST_URL /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN /d:sonar.gitlab.project_id=$CI_PROJECT_PATH /d:sonar.gitlab.ref_name=develop /v:$version /d:sonar.cs.opencover.reportsPaths="$env:OPENCOVER_REPORT_FILE_PATH" /d:sonar.dotnet.excludeGeneratedCode=true'
           - 'msbuild /t:rebuild /m:$env:MSBUILD_CONCURRENCY /nr:false /clp:ErrorsOnly'
           - '$dllsToRunUnitTesting = @(Get-ChildItem "$env:TESTS_OUTPUT_FOLDER_PATH" -Recurse) | Where-Object {$_.Name -match $env:OBJECTS_TO_TEST_REGEX} | ForEach-Object { """""$_""""" } | Join-String -Separator " "'
           - '& "$env:OPENCOVER_PATH" -register -target:"$env:XUNIT_PATH" -targetargs:"$dllsToRunUnitTesting -noshadow" -filter:"$env:OPENCOVER_FILTER" -output:"$env:OPENCOVER_REPORT_FILE_PATH" | Write-Host'
           - 'if ($?) {'
           - '[xml]$coverXml = Get-Content "$env:OPENCOVER_REPORT_FILE_PATH"'
           - '$sequenceCoverage = $coverXml.CoverageSession.Summary.sequenceCoverage'
           - '$branchCoverage = $coverXml.CoverageSession.Summary.branchCoverage'
           - 'Write-Host "Total Sequence Coverage <!<$sequenceCoverage>!>"'
           - 'Write-Host "Total Branch Coverage [![$branchCoverage]!]"'
           - '} else {'
           - 'Write-Host "One or more tests failed!"'
           - 'Throw'
           - '}'
           - '& "$env:SONARSCANNER_MSBUILD_PATH" end /d:sonar.login=$env:SONARQUBE_AUTH_TOKEN'

   Обратите внимание: в begin-команде запуска sonar scanner-а появился дополнительный параметр — /d:sonar.cs.opencover.reportsPaths.

   (необязательный пункт) Ненадолго возвращаемся в Gitlab, заходим в меню проекта Settings > CI/CD и находим на странице настроек параметр Test coverage parsing. Указываем в нём регулярное выражение, которое позволит Gitlab-у также получать информацию о покрытии тестами приложения:

   • если хочется видеть значение покрытия тестов по строкам кода (его ешё называют Sequence Coverage или Statement Coverage), указываем выражение <!<([^>]+)>!>,
   • если хочется видеть значение покрытия тестов по веткам условных операторов (его называют Decision Coverage или Branch Coverage), указываем выражение [![([^>]+)]!].

Какие примеры использования автосборки/автопубликации вам интересны?

Проголосовали 10 пользователей.

Воздержались 2 пользователя.