My GitLab Check Instance

🇫🇷 Version française

Easily test all the features of your self-hosted GitLab instance with a continuous integration pipeline. You will be sure that your forge is fully functional if the pipeline executes correctly.

Project Purpose

The project allows any GitLab instance administrator to quickly test the activated features with a simple pipeline.

The key word is simplicity.

Each feature test can be activated with a variable in Settings > CI/CD.

Using the Project

Installation Steps

1. Create an empty project on your instance.

2. Clone this repository:

   git clone git@gitlab.com:froggit/tools/mgci.git

3. Set up a mirror origin on your instance:

   git remote add mirror git@gitlab.example.com:group/project.git

4. Update your instance:

   git push mirror && git push mirror --tags

5. Set the MGCI_VERSION variable in the CI variables to either main for the latest version or the tag of the version to use.

6. Set the CI variables corresponding to the features activated on your GitLab to true. By default, they are all set to false. See the list of variables below.

Recommended Method

Create a project access token to generate a bot not linked to a project member.

General Configuration

By default, no tests are run except for the information job that lists the project's configuration.

Configuration Variables

Each tested feature can be activated with a MGCI_TEST_<FEATURE> variable that you need to set to true.

List of Available Variables

MGCI_API_TOKEN

For all jobs to work, a token must have been generated on your Gitlab instance. It can be a project access token, personal access token or group access token. It must have Owner access and must have the api, create_runner and manage_runner scopes. You will then need to enter it in the MGCI_API_TOKEN variable in the CI variables.

Updating the Project

Keeping Up with Releases

Follow the project's releases to stay updated.

Initial Configuration

Clone this project, add a mirror origin to your clone. Then, fetch the source and push it to the mirror.

git clone git@gitlab.com:froggit/tools/mgci.git
cd mgci
git remote add mirror git@gitlab.example.com:group/project.git

Manual Update

Update your mirror with each new version and change the version variable if you have set it to a specific version.

git pull
git push mirror
git push mirror --tags 

Automatic Update

There is a simpler way!

We can do it automatically for you by setting up a push mirror on our side.

By sponsoring us for €150/year, we will add your remote repository to the list of mirrors automatically updated by our project. This will save you from manually managing a mirror and help us maintain the project.

Additionally, you will be added to the project's newsletter to be informed of each new version.

Coding Principles

Each feature to be tested must be coded in a single template file.

Naming Convention

Job Names

If a feature requires multiple jobs to be tested, each job must start with the feature name and be named service:action_for_test.

Example:

• cache:push
• cache:pull

Variable Names

All variables must have the MGCI_ prefix.

The variable name that triggers a test is MGCI_TEST_<FEATURE>. Jobs must have a condition set to an environment variable that defaults to false and is set to true in the CI variables.

Example:

• MGCI_TEST_CACHE

Job Structure

Here is the typical structure of a job:

---
# templates/function.yml

function:
  script:
    - echo "Test function OK"
  rules:
    - if: $MGCI_TEST_FUNCTION == "true"

How-to

How to run test jobs on a specific runner?

To run a job on a particular runner, you need to use runner tags. MGCI allows you to associate test jobs with specific tags using a dedicated variable. Each test has its own variable, named after the test activation variable with the _JOB_TAGS suffix. This variable should contain a comma-separated list of tags, for example, tag1, tag2.

Example

You can activate the cache test on runners with the cache tag by setting the following variables:

MGCI_TEST_CACHE=true
MGCI_TEST_CACHE_JOB_TAGS=cache

Tests

🛠️ Already Tested

• Pipeline execution
• Runners' cache
• Parallel jobs
• Static code analysis
• GitLab pages
• API: create and delete an issue
• Registry: Container
• Registry: Container cleanup
• Registry: Generic
• Registry: NPM
• Dependency proxy
• Releases
• Runners: expected tags
• Runners: register and delete
• Health check (only available for self-hosted Gitlab)
• Mattermost: Health check
• Environment: creation and deletion

🏗️ Upcoming

• Terraform module
• Terraform state

API Test

• File name: templates/api.yml
• Job names: api:issue
• Description: the API test involves creating and deleting an issue.

Mattermost Test

• File name: templates/mattermost.yml
• Job names: mattermost:healthcheck
• Description: the Mattermost test involves checking the health check of the Mattermost API. If your GitLab instance does not have a self-hosted Mattermost, there is no need to enable this feature as the job may fail. If you enable this test, you also need to create the MATTERMOST_URL variable, which is empty by default. This variable contains the URL of your self-hosted Mattermost, for example: https://mattermost.example.com.

Cache Test

• File name: templates/cache.yml
• Job names: cache:push and cache:pull
• Description: the cache test involves creating a test_cache.txt file containing the text "Hello word". It then checks in another job that the file contains the correct text.

GitLab Pages Test

• File name: templates/pages.yml
• Job names: pages and pages:check
• Description: the GitLab Pages test involves creating an HTML page with the content being the date when the job created the page. The page content is saved in an artifact (in the /public directory). The second job performs a curl on the HTML page to verify that the date matches the pipeline in which the job was run.

Docker Test

• File name: templates/docker.yml
• Job names: docker:dind
• Description: the Docker test checks the proper functioning of Docker-in-Docker on the machine running the runners by executing the docker info command.

Parallel Jobs Test

• File name: templates/parallel.yml
• Job names: parallel:short and parallel:long
• Description: the parallel jobs test involves running multiple simple jobs in parallel to verify that they all execute correctly simultaneously.

Container Registry Tests

• File name: templates/registry_container.yml
• Job names: registry:container:build, registry:container:purge, and registry:container:security
• Description: the container registry tests verify the building, security, and cleanup of container images in the CI/CD pipeline.

Generic Package Registry Tests

• File name: templates/registry_generic.yml
• Job names: registry:generic:build and registry:generic:check
• Description: the generic package registry tests handle publishing and verifying packages in the generic package registry.

NPM Package Registry Test

• File name: templates/registry_npm.yml
• Job names: registry:npm
• Description: the registry:npm job handles publishing NPM packages in the private GitLab npm registry.

Dependency Proxy Test

• File name: templates/dependency_proxy.yml
• Job names: dependency_proxy:container
• Description: the dependency_proxy:container job tests the proper functioning of the dependency proxy. This job will download the tianon/true image from the docker hub and then cache it in the dependency proxy.

Release Test

• File name: templates/release.yml
• Job names: release
• Description: the release job tests the functionality of creating a release and a tag.

Runner Tags Tests

• File name: templates/runner_tags.yml
• Job names: runners:tags
• Description: the runners:tags job runs the bin/test_runners_tags bash script. This script queries the GitLab API, retrieves all available runners with an "online" status, and compares the tags of these runners with the tags in the $MGCI_RUNNERS_TAGS variable. If it does not find all the tags among the runners, the job fails.

Runner Register Tests

• File name: templates/runner_register.yml
• Job names: runners:register
• Description: the runners:register job tests the functionality of registering and deleting a runner. It will register a runner for the project with the test-runner tag and then delete it immediately after.

Contributing

This project is licensed under GPL3, and contributions are welcome to bring improvements, new features, etc.

• Our contribution guide will tell you more about the many benefits of contributing to the project.
• Our code of conduct guide will provide more information on the behavior expected when contributing to the project.

License

.

My GitLab Check Instance (mgci) is created by Chaudier Christophe (Froggit) and published under the GPL3 license.

Thanks to all the contributors.