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
# 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
evaluate-bitbucket -s https://bitbucket.example.com -t <access-token> # BETA
Local
Requires at least Python 3.8.
git clone https://gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate.git # or SSH
cd evaluate
pip install gitlab-evaluate
poetry install
# In local terminal
poetry run evaluate-gitlab -t <access-token-with-api-scope> -s https://gitlab.example.com
poetry run evaluate-jenkins -s https://jenkins.example.com -u <jenkins-admin-user> -t <access-token-or-password> # BETA
poetry run evaluate-bitbucket -s https://bitbucket.example.com -t <access-token> # 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
orread_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.
Example pipeline schedule
To schedule Evaluate to run on a regular basis we recommend using the following pipeline:
image: registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:latest
stages:
- evaluate
run-evaluate:
stage: evaluate
# tags:
# - docker
# - linux
timeout: 4h
script:
- evaluate-gitlab -t $API_TOKEN -s https://<gitlab-hostname> -p <number-of-processes>
artifacts:
name: Report
paths:
- evaluate_report.xlsx
expire_in: 1 week
NOTES:
- Configure
API_TOKEN
as CI variable with Admin personal access token andread_api
orapi
scope - Add Runner
tags
for using adocker
executor and Linux Runner - Adjust the number of processes based on recommendation
- Adjust
timeout
after the 1st run - Create pipeline schedule under Build -> Pipeline schedules
[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.
[BETA] BitBucket
Evaluate supports scanning a Bitbucket Server/Data Center to retrieve relevant metadata about the server
Usage
You can use either a admin or a non-admin token to do the evaluation but non-admin tokens can't pull users information.
-
A user should provision an access token for Evaluate to use during the scan.
-
Install
gitlab-evaluate
from the Install section above, -
Run :point_down:
evaluate-bitbucket -s https://bitbucket.example.com -t <access-token>
-
This should create a file called
evaluate_bitbucket.xlsx
-
If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.
Command help screen
Usage: evaluate-bitbucket [OPTIONS]
Options:
-s, --source TEXT Source URL: REQ'd
REQ'd
-t, --token TEXT Bitbucket access 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.22.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 95c21b24012022b5ae1ad3d713941361fe18453926add94b20d33c416705c573 |
|
MD5 | e8debe45670d4d37f07410b6e9135933 |
|
BLAKE2b-256 | 4e462483838ea9e09ddc29e2c82aeefecd734e9f60a8171da52c97b5ce52d622 |