<!--
SPDX-FileCopyrightText: 2020 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)

SPDX-License-Identifier: CC0-1.0
-->

# Software Quality Assurance

---

## CI/CD usage

The following manual describes how to use the Software Quality Assurance with GitLab CI/CD.
It is highly advisable to know how to use git and GitLab when using this method.

> **Note:** It is possible to hook the Software Quality Assurance to GitHub Actions and other code hosting platforms. 

---

## Decide on way to retrieve the report

There are two different ways to get the generated report by the `Software Quality Assurance`.

**Artifact**

When you opt for this option, the report is available via the GitLab web-interface.
You can simply download.
More information available [here](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html)

This option is easier to set up.

**Commit** (recommended)

> **Note:** this option is **required** by certain (future) services. 

---

### 1) Project member permissions
To apply certain changes described below, you need at least `Maintainer` [permissions](https://docs.gitlab.com/ee/user/permissions.html).

### 2) Host the project on any GitLab
How to do that, is described [here](https://docs.gitlab.com/ee/gitlab-basics/create-project.html)

### 3) Enable CI/CD

In the GitLab web-interface from the page of your repository navigate to `config > General > Visibility, project features, permissions`.
Enable `Pipelines` and set them to `Only Project Members`.

### 4) Add GitLab Runner

To have an available Runner is **required** for the Software Quality Assurance to function.
This will not be covered here.
Talk to your local admin get one up and running.

**Runner requirements**
* tag: `sqa`
* executor: docker

> **WARNING:** Be aware that the runtime for the services can go up to several hours, depending on the project size!

Further information are available [here](https://docs.gitlab.com/runner/install/).

---

### 5.1) Retrieve report by Artifact

#### 5.1.1) Set up .gitlab-ci.yml

This yaml block is set up for project without prior GitLab Ci/CD setup.
If you already have `.gitlab-ci.yml` in your project, there should be someone withing your project who can help you adapt.

Copy the content of the following code block to a file named `.gitlab-ci.yml` in the base directory of your project.
Commit and push your changes.

```yaml
stages:
  - sqa

sqa:
  stage: sqa
  image:
    name: "gitext.gfz-potsdam.de:5000/software/services/fair/software-quality-assurance/software-quality-assurance:latest"
    entrypoint: [""]
  tags:
    - sqa
  script:
    - cp -r "$CI_PROJECT_DIR" /repo
    - rm -rf /repo/meta
    - docker-entrypoint.sh --all
    - cp -rT /repo "$CI_PROJECT_DIR"
  only:
    refs:
      - master
  artifacts:
    paths:
      - meta/software-quality-assurance-report.md
    expire_in: 30 days
```

---

### 5.2) Retrieve report by commit

This manual focuses on [UNIX](https://en.wikipedia.org/wiki/Unix) systems like Linux or MacOS.

> **Note:** for Windows the commands can slightly differ, but is fully compatible. 

#### 5.2.1) Set up deploy key

First we need to generate a key pair via the terminal.
It will function as [deploy key](https://docs.gitlab.com/ee/ssh/#deploy-keys).
More information on generating a key pair can be found [here](https://docs.gitlab.com/ee/ssh/#generating-a-new-ssh-key-pair).

```console
ssh-keygen -t rsa -b 4096 -C "[PROJECT_NAME]_software-quality-assurance" -f [OUTPUTFILE] -q -N ""
```

In the GitLab web-interface from the page of your repository navigate to `config > CI/CD > Deploy Keys`.
Paste the content of `[OUTPUTFILE].pub` to the field `key` and give it any unique name (like *PROJECT_NAME*_deploy-key)
Check the 'Write access allowed' checkbox.

Save the changes.

> **Note:** it is recommended to either store `[OUTPUTFILE].pub` securely or delete it.

#### 5.2.2) Set up Variables

We need to tell our CI/CD the identity of the GitLab server we are using.
To do that, we request it from the server via a terminal command.
It returns two lines with the public identity of the GitLab server.

```console
ssh-keyscan -t rsa [GITLAB_DOMAIN]]

# example

ssh-keyscan -t rsa gitext.gfz-potsdam.de
# gitext.gfz-potsdam.de:22 SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3
gitext.gfz-potsdam.de ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsiq5txhABcG9oePf47SCd+w/tfSs6NWKaMRd2BfBi9DGORQX4wwV4CYvSJbMfJvQO5SMGwhnEAXe0bWihC2V8X7lzcePrpjfP+uH2lmipcFbV9g3iQpM7Fusr96IV65v/qQ6HE4+KkHJLR1vEKj1AOaVgDww7CHhVAHCkvqcSwwtfOjBbqyfQ2Su7O6UNzs1ecQcIXnQNO8ebzimv3c8mKdo9j8i5eiWVqzRivmi/R3XIIc2T695mTLyxUplqfyvZpDL90F9VEjr/3HM9/3dASbonaTH8SoMRCxOy8Fpz0Va1MdpSor0uoemQjbu8aZzGB0+tsE5eWjuFaZib8QDF
```

Now open the GitLab web-interface and navigate to `config > CI/CD > Variables` from from the page of your repository.
We need to fill in two variables here.
Click on 'Add Variable'.

As key type in `GITLAB_DEPLOY_KEY`.
As value paste the content of `[OUTPUTFILE]` (was generated in 5.2.1).
Click on 'Add Variable'.

For the second one:
As key type in `SSH_KNOWN_HOSTS_GITLAB`.
As value paste both output lines of the `ssh-keyscan` command (see above).
Click on 'Add Variable'.

#### 5.2.3) Set up .gitlab-ci.yml

This yaml block is set up for project without prior GitLab Ci/CD setup.
If you already have `.gitlab-ci.yml` in your project, there should be someone withing your project who can help you adapt.

Copy the content of the following code block to a file named `.gitlab-ci.yml` in the base directory of your project.
Commit and push your changes.

```yaml
stages:
  - sqa

sqa:
  stage: sqa
  image:
    name: "gitext.gfz-potsdam.de:5000/software/services/fair/software-quality-assurance/software-quality-assurance:latest"
    entrypoint: [""]
  tags:
    - sqa
  before_script:
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$SSH_KNOWN_HOSTS_GITLAB" > ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
  script:
    - eval $(ssh-agent -s)
    - echo "$GITLAB_DEPLOY_KEY" | tr -d '\r' | ssh-add -
    - git config user.name "GitLab CI:${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}"
    - git config user.email "[PROJECT_NAME]_software-quality-assurance"
    - cp -r "$CI_PROJECT_DIR" /repo
    - docker-entrypoint.sh --all
    - cp -rT /repo "$CI_PROJECT_DIR"
    - cd meta
    - find -mindepth 1 -maxdepth 1 -type d -exec rm -r {} \;
    - cd ..
    - git add -f .
    - git commit -m "[AUTOMATIC] generated meta/software-quality-assurance-report.md by gitlab ci"
    - git push "git@${CI_SERVER_HOST}:${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}.git" "HEAD:${CI_COMMIT_REF_NAME}"
  only:
    refs:
      - master
  except:
    changes:
      - "meta/software-quality-assurance-report.md"
```

**Important**
In the yaml file above fill in the line `- git config user.email "[PROJECT_NAME]_software-quality-assurance"`
The content of user.email must be identical with what was entered in 5.2.1)

> **Note:** it is recommended to either store `[OUTPUTFILE]` securely or delete it.

### 6) Examples

An example of both variants applied can be found [here](../.gitlab-ci.yml)