Newer
Older
# My GitLab Check Instance
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
[🇫🇷 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.
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
```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.
[](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"
```
Christophe Chaudier
committed
## 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] Pipeline execution
- [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
### 🏗️ Upcoming
- [ ] [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
[](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)