The GitLab Performance Tool (
gpt) is built and maintained by the GitLab Quality Engineering - Enablement team to provide performance testing of any GitLab instance. The tool has itself been built upon the industry-leading open-source tool k6 and provides numerous tests that are designed to effectively performance test GitLab.
GitLab recommends running GPT against your GitLab environment to get an effective performance test. We do not recommend running on a production instance. Only run on production if it’s really required. If so, then run it at the quietest possible time. Depending on your system environment, the test may take up at least 4 hours.
NOTE: This quick start was written and adopted based on documentation for
GPT v2 (2.10.0). Please always check the the official GitLab Project documentation: GitLab Performance Tool for latest changes.
On your workstation with Docker installed, please run the following in your terminal:
# clone the gpt project git clone https://gitlab.com/gitlab-org/quality/performance cd performance mkdir results
This will generate the data that will be used for the test later. More details on GPT Project:
Next, edit your environment file under
./k6/config/environment/. In this example, we will use the 2k users environment. Hence, it will be the
2k.json. Replace the values for
"url" with the URL of your GitLab instance and
"user" with the username of the Admin user created in the above step.
Edit the following lines:
"url": "<your gitlab url>", "user": "<username that the access token belong to>",
NOTE: If you have a top-level group named
gpt, please replace the value for
"root_group" with another unique top-level group name.
Run the following docker command to generate the data needed for the performance test:
docker run -it -e ACCESS_TOKEN=<TOKEN> -v $(pwd)/k6/config:/config -v $(pwd)/results:/results gitlab/gpt-data-generator --environment 2k.json
Full details and explanation are available at GPT project
Run the following Docker command:
docker run -it -e ACCESS_TOKEN=<TOKEN> -v $(pwd)/k6/config:/config -v $(pwd)/k6/tests:/tests -v $(pwd)/results:/results gitlab/gitlab-performance-tool --environment 2k.json --options <OPTIONS-FILE>.json
NOTE: Please replace
<TOKEN> with your personal access token, then replace
60s_40rps.json to run against 2k users testing. [Optional] You may replace
<OPTIONS-FILE> with the following recommended options files based on your target environment user count:
After starting the tool you will see it running each test in order. Once all tests have completed you will be presented with a results summary. As an example, here is a test summary you can view.
For your reference, here are the test runs from GitLab:
There are known issues when running the GitLab Performance Tool. Some tests run against parts of the product which are known to be non-performant.
For more details on other possible problems see Troubleshooting section
This step will delete the test data generated.
Method 1: Run the following Docker command
docker run -it -e ACCESS_TOKEN=<TOKEN> -v $(pwd)/k6/config:/config -v $(pwd)/results:/results gitlab/gpt-data-generator --environment 2k.json --clean-up
Method 2: Delete the top-level group
gpt (or the unique name you've replaced at your environment json) from GitLab UI.
NOTE: There is no preference of one method over the other as both will delete the top-level group.
Customers often ask for their GPT results to be reviewed as part of building out a Reference Architecture.
#gitlab-performance-toolchannel on Slack.