Scans GitLab instance and ranks projects against a set of criteria. Can be used to identiy projects that may have too much metadata/size to reliably export or import.
Project description
Evaluate
Evaluate is a script that can be run to gather information about all projects of a GitLab
- Instance
- Group (including sub-groups)
This information is useful to the GitLab Professional Services (PS) team to accurately scope migration services.
[[TOC]]
Contributions / Support
This tool is maintained by the Professional Services team and is not included in your GitLab Support if you have a license. For support questions please create an issue from our Evaluate support issue template.
Use Case
GitLab PS plans to share this script with a Customer to run against their GitLab instance or group. Then the customer can send back the output files to enable GitLab engagement managers to scope engagements accurately. There is a single file generated.
Install Method
(Recommended) Docker Container
Docker containers with evaluate installed are also available to use.
docker pull registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:latest
(Optional) pip Install
Requires at least Python 3.8.
pip install gitlab-evaluate
Local Usage
# Spin up container
docker run --name evaluate -it registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:latest /bin/bash
# In docker shell
evaluate-gitlab -t <access-token-with-api-scope> -s https://gitlab.example.com
evaluate-jenkins -s https://jenkins.example.com -u <jenkins-admin-user> -t <access-token-or-password> # BETA
Usage
GitLab
System level data gathering
Evaluate is meant to be run by an OWNER (ideally system ADMINISTRATOR) of a GitLab instance to gather data about every project on the instance or group (including sub-groups).
-
A GitLab OWNER (ideally system ADMINISTRATOR) should provision an access token with
api
scope:- Personal access token for instance
- Group access token for group
-
Install
gitlab-evaluate
from the Install section above, -
Run :point_down:
For evaluating a GitLab instance
evaluate-gitlab -t <access-token-with-api-scope> -s https://gitlab.example.com
For evaluating a GitLab group (including sub-groups)
evaluate-gitlab -t <access-token-with-api-scope> -s https://gitlab.example.com -g 42
See Recommended Processes per Project Count to specify the number of processes to use
-
This should create a file called
evaluate_report.xlsx
For more information on these files, see reading the output
-
If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.
Recommended Processes per Project Count
Evaluate uses 4 processes by default, which is sufficient for smaller GitLab instances, but may result in a slower scan time for larger instances. Below is a table covering recommended processes based on the overall number of projects on an instance:
Number of Projects | Recommended Processes |
---|---|
< 100 | 4 (default) |
< 1000 | 8 |
< 10000 | 16 |
< 100000 | 32 |
> 100000 | 64-128 |
The number of processes is limited by a few factors:
- API rate limits on the GitLab instance itself
- Overall stability of the GitLab instance
- Not as critical as the first two, but overall available memory on the machine running Evaluate is another factor to consider
You can ramp up the number of processes on a smaller instance to speed up the scans, but the performance gains for a large number of processes on a smaller instance will eventually plateau.
Command help screen
Usage: evaluate-gitlab [OPTIONS]
Options:
-s, --source TEXT Source URL: REQ'd
-t, --token TEXT Personal Access Token: REQ'd
-o, --output Output Per Project Stats to screen
-i, --insecure Set to ignore SSL warnings.
-g, --group TEXT Group ID. Evaluate all group projects (including sub-
groups)
-f, --filename TEXT CSV Output File Name. If not set, will default to
'evaluate_output.xlsx'
-p, --processes TEXT Number of processes. Defaults to number of CPU cores
--help Show this message and exit.
[BETA] Jenkins
Evaluate supports scanning a Jenkins instance to retrieve basic metrics about the instance
Usage
Evaluate is meant to be run by an admin of a Jenkins instance to gather data about jenkins jobs and any plugins installed on the instance.
-
A Jenkins ADMINISTRATOR should provision an API token for Evaluate to use during the scan.
-
Install
gitlab-evaluate
from the Install section above, -
Run :point_down:
evaluate-jenkins -s https://jenkins.example.com -u <jenkins-admin-user> -t <access-token-or-password>
-
This should create a file called
evaluate_jenkins.xlsx
-
If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.
Command help screen
Usage: evaluate-jenkins [OPTIONS]
Options:
-s, --source TEXT Source URL: REQ'd
-u, --user TEXT Username associated with the Jenkins API token: REQ'd
-t, --token TEXT Jenkins API Token: REQ'd
--help Show this message and exit.
GitLab Project Thresholds
Below are the thresholds we will use to determine whether a project can be considered for normal migration or needs to have special steps taken in order to migrate
Project Data
- Project Size - 20GB
- Pipelines - 5,000 max
- Issues - 5,000 total (not just open)
- Merge Requests - 5,000 total (not just merged)
- Container images - 20GB per project
- Packages - Any packages present
Repository Data
- Repository Size - 5GB
- Commits - 50K
- Branches - 1K
- Tags - 5K
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gitlab_evaluate-0.18.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | df94069f9c15c70ec0e71c06ab8aa9bcd22daa97bb1ac85b907c46ff2f2524c8 |
|
MD5 | d3c03421f2c8af169b64b1045b2cf3dd |
|
BLAKE2b-256 | 687e7a891637575fde71a016d2b19699e3abbf3a2f9e743045a076ceb91046c8 |