STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG STG - STG - STG

Skip to content
Snippets Groups Projects
README.md 7.71 KiB
Newer Older
# My GitLab Check Instance
[🇫🇷 Version française](README_fr.md)

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:
    ```bash
    git clone git@gitlab.com:froggit/tools/mgci.git
    ```
3. Set up a mirror origin on your instance:
    ```bash
    git remote add mirror git@gitlab.example.com:group/project.git
    ```
4. Update your instance:
    ```bash
    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](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) to generate a bot not linked to a [project member](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects).

## 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

| Variable                       | Description                                                | Default Value |
|--------------------------------|------------------------------------------------------------|---------------|
| `MGCI_VERSION`                 | Version of the **My GitLab Check Instance** project to use | `main`        |
| `MGCI_TEST_API`                | Run the API test                                           | `false`       |
| `MGCI_TEST_PAGES`              | Run the GitLab Pages test                                  | `false`       |
| `MGCI_TEST_CACHE`              | Run the runners cache test                                 | `false`       |
| `MGCI_TEST_DOCKER`             | Run the Docker commands test (Docker in Docker)            | `false`       |
| `MGCI_TEST_RELEASE`            | Run the release creation test                              | `false`       |
| `MGCI_TEST_PARALLEL`           | Run the parallel jobs test                                 | `false`       |
| `MGCI_TEST_REGISTRY_NPM`       | Run the NPM registry test                                  | `false`       |
| `MGCI_TEST_REGISTRY_GENERIC`   | Run the generic packages registry test                     | `false`       |
| `MGCI_TEST_REGISTRY_CONTAINER` | Run the container registry test                            | `false`       |
| `MGCI_TEST_RUNNERS_TAGS`       | Run the runner tags test                                   | `false`       |
| `MGCI_RUNNERS_TAGS`            | List of runner tags to test, format <tag1,tag2...>         | ``            |
| `MGCI_API_TOKEN`               | `Owner` access token to the repository for API testing     | ``            |

## 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.

```bash
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.

```bash
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.

[![Contact Us](https://img.shields.io/badge/Contact-Us-green?style=for-the-badge)](https://froggit.fr/contacts)

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:

```yml
---
# 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:
```yaml
MGCI_TEST_CACHE=true
MGCI_TEST_CACHE_JOB_TAGS=cache
```

## Tests

### 🛠️ Already Tested
- [x] Runners' cache
- [x] Parallel jobs
- [x] GitLab pages
- [x] API: create and delete an issue
- [x] Registry: Container
- [x] Registry: Container cleanup
- [x] Registry: Generic
- [x] Registry: NPM
- [X] Runners: expected tags
- [ ] [Healthcheck](https://gitlab.com/froggit/tools/mgci/-/issues/39)
- [ ] [Register and remove a runner](https://gitlab.com/froggit/tools/mgci/-/issues/40)
- [ ] [Test all runner types managed with tags](https://gitlab.com/froggit/tools/mgci/-/issues/22)
- [ ] [Terraform module](https://gitlab.com/froggit/tools/mgci/-/issues/16)
- [ ] [Terraform state](https://gitlab.com/froggit/tools/mgci/-/issues/13)
- [ ] [Environment (create and destroy)](https://gitlab.com/froggit/tools/mgci/-/issues/41)
- [ ] [Dependency proxy](https://gitlab.com/froggit/tools/mgci/-/issues/43) [(docs.gitlab.com)](https://docs.gitlab.com/ee/user/packages/dependency_proxy/)
- [ ] [Static code analysis](https://gitlab.com/froggit/tools/mgci/-/issues/42) [(sast)](https://docs.gitlab.com/ee/user/application_security/sast/)
## API Test

The API test involves [creating and deleting an issue](https://docs.gitlab.com/ee/api/issues.html#new-issue).
To connect, the job needs a [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) to be set in the `GL_API_TOKEN` CI variable. The token must have `Owner` access to delete the issue.

## License

[![Copyright 2024-present Chaudier Christophe (Froggit)](https://www.gnu.org/graphics/gplv3-with-text-136x68.png)](https://choosealicense.com/licenses/gpl-3.0/).

**My GitLab Check Instance (mgci)** is created by Chaudier Christophe ([Froggit](https://froggit.fr)) and published under the [GPL3 license](https://www.gnu.org/licenses/gpl.html).

Thanks to [all the contributors.](/-/graphs/main?ref_type=heads)