Evaluate

Evaluate is a script that can be run to gather information from a number of source code management and CI/CD orchestration systems to help prepare for migration or platform consolidation efforts. Currently Evaluate supports gathering data from

• GitLab
• Bitbucket Server/Data Center
• BitBucket Cloud
• GitHub Enterprise Server (GHES)
• github.com (single org)
• Jenkins
• Azure DevOps

TLDR

Evaluate Docker Container Quick Start Guide

Navigation

[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 using our Evaluate support issue template.

Use Case

GitLab Professional Serivces shares this script with Customers 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. For GitLab scans, an .xlsx workbook plus two CSV exports (Raw_Project_Data.csv and Evaluate_Report.csv) are generated; see reading the output.

Install Method

Versioning

• For GitLab versions < 16.0. use Evaluate version <= 0.24.0. Evaluate switched to using GraphQL queries instead of REST API requests, which can cause some issues retrieving data from older GitLab instances
• For GitLab versions >= 16.0 use Evaluate version > 0.24.0, ideally the latest
• Within the supported range, a group scan settles which user fields it can ask for by running the query against the instance and dropping whatever that instance rejects, rather than failing. Two user fields are affected: account types (UserCore.type, added in GitLab 18.0), without which types read as bot or human and internal users cannot be excluded from the user figures; and the last activity date (added in 16.11), which is then left blank

Docker Container

Docker containers with evaluate installed are available to use.

# For GitLab versions older than 16.0. Evaluate versions newer than 0.24.0 switched to using GraphQL queries instead of REST API requests which can cause some issues retrieving data from older GitLab instances
docker pull registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:0.24.0

# For GitLab versions newer than 16.0 (base image without Jenkins support)
docker pull registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:latest

# For GitLab versions newer than 16.0 with Jenkins support (larger image with ML dependencies)
docker pull registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:jenkins-latest

# Spin up container (use base image for GitLab, Bitbucket, ADO, GitHub)
docker run --name evaluate -it registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:latest

On older releases you may have to use append `/bin/bash` as the default command is python3.

# OR spin up container with Jenkins support
docker run --name evaluate -it registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:jenkins-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>  # Requires jenkins image variant
evaluate-bitbucket -s https://bitbucket.example.com -t <access-token> # BETA
evaluate-ado -s https://dev.azure.com/<your-org> -t <personal-access-token> # BETA

What is in the image

The images are deliberately minimal: they carry Python, Evaluate and its runtime dependencies, and little else. Common troubleshooting tools are not installed, because each additional package adds CVEs that Debian frequently has no fix for. If you need one, install it in the running container:

apt-get update && apt-get install -y <package>

The latest and jenkins-latest tags are rebuilt on a weekly schedule (configured under Build → Pipeline schedules in the project) so that Debian security updates are picked up without waiting for a code change. Re-run docker pull to get the patched image.

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
    # variables:
    #   REQUESTS_CA_BUNDLE: "/custom/certs/my-cert.crt"  # If you need a custom Root-ca-certificate
    timeout: 4h
    script:
        - evaluate-gitlab -t $API_TOKEN -s https://<gitlab-hostname> -p <number-of-processes>
    artifacts:
        name: Report
        paths:
            - evaluate_report.xlsx
            - Raw_Project_Data.csv
            - Evaluate_Report.csv
        expire_in: 1 week

NOTES:

• Configure API_TOKEN as CI variable with Admin personal access token and read_api or api scope
• Add Runner tags for using a docker 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

Local (development / troubleshooting)

Running a released version

Installs from PyPI. No clone needed. pipx is recommended, because it keeps Evaluate and its dependencies in their own isolated environment:

# Base package (for GitLab, Bitbucket, ADO, GitHub scanning)
pipx install gitlab-evaluate

# OR with Jenkins support (includes larger ML dependencies)
pipx install "gitlab-evaluate[jenkins]"

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>  # Requires [jenkins] extras
evaluate-bitbucket -s https://bitbucket.example.com -t <access-token> # BETA
evaluate-ado -s https://dev.azure.com/<your-org> -t <personal-access-token> # BETA

pip install gitlab-evaluate also works, but it installs into whichever Python environment happens to be active, which makes it easy to end up running a different copy than you intended.

Running from a local clone

To run your working tree instead — an unreleased branch, or a change you are developing — install with Poetry and prefix the commands with poetry run:

git clone https://gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate.git
# or over SSH: git clone git@gitlab.com:gitlab-org/professional-services-automation/tools/utilities/evaluate.git
cd evaluate

poetry install   # add --extras jenkins for Jenkins support
poetry run evaluate-gitlab -t <access-token-with-api-scope> -s https://gitlab.example.com

The poetry run prefix is required. A bare evaluate-gitlab resolves to whatever is on your PATH, which is the released version rather than your clone, so local changes and unreleased features are silently ignored. As an alternative, pipx install --editable . puts your clone behind the plain evaluate-gitlab command.

If you have previously installed Evaluate globally, remove it first — pipx uninstall gitlab-evaluate, or pip uninstall gitlab-evaluate — so there is no ambiguity about which copy runs.

Usage

GitLab

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

Token Requirements

The required token scopes depend on your GitLab version and how admin mode is configured:

How to provision a token:

1. A GitLab OWNER (ideally system ADMINISTRATOR) should provision an access token:

   • Personal access token for instance-wide evaluation. Select both api and admin_mode scopes.
   • Group access token for group evaluation. Only api scope is needed.

   Note on user data: the Users sheet and the user breakdowns on App Stats are filled from whatever the token can see. An admin token reads the users API, which exposes email addresses, license seat usage, external, admin and auditor flags, but no account type -- only GitLab's derived bot flag. A group scan reads the group's members, where the account type, state, public email and last activity date are available but the admin-only fields are not, and are left blank rather than guessed.

   Service accounts and group or project access token bots are counted, labelled by type. Internal users (the ghost user, GitLab's own bots, import placeholders, security policy bots) are excluded from every user figure: GitLab owns them, they consume no license seat and they are not migrated.

   Troubleshooting: If the App Stats tab in the report shows N/A for all values and you see a warning about being unable to retrieve application info, your token is most likely missing the admin_mode scope. Recreate the token with both api and admin_mode scopes and re-run Evaluate.

2. Install gitlab-evaluate from the Install section above,

3. Run 👇

   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.

   NOTE: If you have configured rate limits on your instance to be more strict than the default settings, start with one process (-p 1) and adjust accordingly up to the recommended number of processes for your sized instance

   NOTE: For a group scan, Evaluate checks the number of projects it enumerated against the number the group itself reports, and records the result in the Enumeration row of the App Stats sheet:

   • COMPLETE -- every project in the namespace was enumerated.
   • INCOMPLETE -- a page could not be retrieved, or fewer projects were enumerated than the group reports. The workbook and CSVs are still written so the partial data is usable, but the run exits non-zero. Pass --allow-partial to exit 0 anyway.
   • NOT VERIFIED -- there was no project count to compare against, which is expected for an instance-wide scan with a non-admin token and for -r report-only runs. This never fails a run.

   On a large namespace the biggest cause of an INCOMPLETE result is the GitLab GraphQL request timeout. Lower --page-size (default 25) and re-run.

   NOTE: If a scan is interrupted, re-run your evaluate command with an additional -r or --generate-report flag to generate a report from the data retrieved so far. Note that a plain re-run without -r deletes gitlab.db before it starts, so copy that file first if you want to keep a partial run.

4. This creates evaluate_report.xlsx plus two CSV exports of the same data, Raw_Project_Data.csv and Evaluate_Report.csv, in the working directory.

   For more information on these files, see reading the output

5. 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:

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-id TEXT    Group ID. Evaluate all group projects (including sub-
                         groups)
  -f, --filename TEXT    XLSX Output File Name. If not set, will default to
                         'evaluate_report.xlsx'
  -p, --processes TEXT   Number of processes. Defaults to number of CPU cores
  -v, --verbose          Set logging level to Debug and output everything to
                         the screen and log file
  -q, --quiet            Set logging level to Warning to reduce output. Useful
                         for large instances or CI pipelines
  -r, --generate-report  Generate full XLSX report from sqlite database.
                         Source and Token are still required for the report to
                         generate
  --page-size INTEGER RANGE
                         Projects requested per GraphQL page. Smaller pages
                         stay further from the GitLab GraphQL request timeout
                         on large namespaces  [default: 25; 1<=x<=100]
  --allow-partial        Exit 0 even when the scan could not enumerate every
                         project. The report is still marked incomplete
  --help                 Show this message and exit.

Jenkins

Evaluate supports scanning a Jenkins instance to retrieve basic metrics about the instance.

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. If the Jenkins jobs config are stored on a SCM repo like Github or Gitlab, you will need a token with read repository access to the SCM repo for a deeper analysis.

1. A Jenkins ADMINISTRATOR should provision an API token for Evaluate to use during the scan.

2. Install gitlab-evaluate from the Install section above,

3. Run 👇

   evaluate-jenkins -s https://jenkins.example.com -u <jenkins-admin-user> -t <access-token-or-password>
   

4. This should create a file called evaluate_jenkins.xlsx

5. If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.

You may see a message similar to the below, if you fail to install/pull a jenkins specific install/image:

================================================================================
ERROR: Jenkins dependencies are not installed!
================================================================================

The Jenkins scanning feature requires additional dependencies that are
not included in the base installation to keep the package size small.

To install Jenkins support, run one of the following commands:

  Via pip:
    pip install 'gitlab-evaluate[jenkins]'

  Via poetry:
    poetry install --extras jenkins

  Via Docker:
    docker pull registry.gitlab.com/gitlab-org/professional-services-automation/tools/utilities/evaluate:jenkins-latest

Missing dependency details:
  Jenkins dependencies are not installed. Install with: pip install 'gitlab-evaluate[jenkins]' or poetry install --extras jenkins. Missing: <package name>

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
  -p, --processes TEXT  Number of processes. Defaults to number of CPU cores
  -i, --insecure        Set to ignore SSL warnings.
  -q, --quiet           Set logging level to Warning to reduce output. Useful
                        for large instances or CI pipelines
  -f, --filename TEXT   XLSX Output File Name (without .xlsx extension).
                        Defaults to 'evaluate_jenkins'
  --gitlab-token TEXT   Optional GitLab token for fetching Jenkinsfile from
                        GitLab repos
  --github-token TEXT   Optional GitHub token for fetching Jenkinsfile from
                        GitHub repos
  --help                Show this message and exit.

[BETA] BitBucket

Evaluate supports scanning a Bitbucket Server/Data Center to retrieve relevant metadata about the server.

You can use either a admin or a non-admin token to do the evaluation but non-admin tokens can't pull users information.

Group scans: users are counted as the distinct accounts with a membership in the scanned group, its sub-groups or its projects. Members inherited from parent groups and members of invited groups are excluded, so the figure describes the namespace itself.

1. A user should provision an access token for Evaluate to use during the scan.

2. Install gitlab-evaluate from the Install section above,

3. Run 👇

   evaluate-bitbucket -s https://bitbucket.example.com -t <access-token>
   

4. This should create a file called evaluate_bitbucket.xlsx

5. 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  [required]
  -t, --token TEXT     Personal Access Token  [required]
  -f, --filename TEXT  XLSX Output File Name (without .xlsx extension).
                       Defaults to 'evaluate_bitbucket'
  -q, --quiet          Set logging level to Warning to reduce output. Useful
                       for large instances or CI pipelines
  --help               Show this message and exit.

[BETA] BitBucket Cloud

Evaluate supports scanning a Bitbucket Cloud workspace to retrieve relevant metadata about the workspace and its repositories, including repository details, pull requests, issues, branches, CI/CD pipeline configuration, and user information.

API Token Scopes

To use Evaluate with Bitbucket Cloud, you must create an API token with the following scopes. All of them are read-only. Evaluate does not need any manage:*, write:*, admin:*, or delete:* scopes.

Read:

• read:account
• read:issue:bitbucket
• read:me
• read:package:bitbucket
• read:permission:bitbucket
• read:pipeline:bitbucket
• read:project:bitbucket
• read:pullrequest:bitbucket
• read:repository:bitbucket
• read:runner:bitbucket
• read:snippet:bitbucket
• read:ssh-key:bitbucket
• read:test:bitbucket
• read:user:bitbucket
• read:webhook:bitbucket
• read:wiki:bitbucket
• read:workspace:bitbucket

Usage

1. A user should provision an API token* with the required scopes listed above. A token with scope must be created and scoped to only BitBucket.

2. Install gitlab-evaluate from the Install section above.

3. Run 👇

   evaluate-bitbucket-cloud -w <workspace-id> -t <api-token> -u <atlassian-account-email>
   

   What goes in -u: the email address of the Atlassian account that created the API token (for example, jane.doe@example.com). Do not use your Bitbucket username or display name. Bitbucket authenticates API tokens with email:token, so passing a username fails with ERROR: Authentication failed.

   Only omit -u if you are using a Bearer-style token instead of an API token (an OAuth access token, or a Workspace/Project/Repository access token).

4. This should create a file called evaluate_bitbucket_cloud.xlsx

5. If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.

_{*While an Oauth token should also work, we highly recommend using an API token instead}

Command help screen

Usage: evaluate-bitbucket-cloud [OPTIONS]

Options:
  -w, --workspace TEXT  Bitbucket Cloud Workspace ID  [required]
  -t, --token TEXT      Atlassian API token, or an OAuth / access token
                        [required]
  -u, --username TEXT   Atlassian account EMAIL (not Bitbucket username).
                        Required with Atlassian API tokens; omit for OAuth or
                        access tokens
  -f, --filename TEXT   Output filename (without .xlsx extension)
  -q, --quiet           Set logging level to Warning to reduce output. Useful
                        for large instances or CI pipelines
  --help                Show this message and exit.

[BETA] Azure DevOps

Evaluate supports scanning an Azure DevOps to retrieve relevant metadata about the organization.

You need to use a Personal Access Token with Read scope for most of the services. Ensure the user who owns the PAT has at least Basic access level to avoid missing repository information.

When running Evaluate for Azure DevOps, the tool retrieves information from the endpoints listed below:

Get Descriptor
Endpoint: /_apis/graph/descriptors/{project_id}
Sub-API: vssps
Scope: Graph (Read)

Get Project Administrators Group
Endpoint: /_apis/graph/groups?scopeDescriptor={scopeDescriptor}
Sub-API: vssps
Scope: Graph (Read)

Get Project Administrators
Endpoint: /_apis/GroupEntitlements/{project_group_id}/members
Sub-API: vsaex
Scope: MemberEntitlementManagement (Read)

Get Work Items
Endpoint: /{project_id}/_apis/wit/wiql
Scope: Work Items (Read)

Get Release Definitions
Endpoint: /{project_id}/_apis/release/definitions
Sub-API: vsrm
Scope: Release (Read)

Get Build Definitions
Endpoint: /{project_id}/_apis/build/definitions
Scope: Build (Read)

Get Commits
Endpoint: /{project_id}/_apis/git/repositories/{repository_id}/commits
Scope: Code (Read)

Get Pull Requests
Endpoint: /{project_id}/_apis/git/repositories/{repository_id}/pullrequests
Scope: Code (Read)

Get Branches
Endpoint: /{project_id}/_apis/git/repositories/{repository_id}/refs
Scope: Code (Read)

Get Repositories
Endpoint: /{project_id}/_apis/git/repositories
Scope: Code (Read)

Get Project
Endpoint: /_apis/project/{project_id}
Scope: Project and Team (Read)

Get Projects
Endpoint: /_apis/projects
Scope: Project and Team (Read)

Get Users
Endpoint: /_apis/graph/users
Sub-API: vssps
Scope: Graph (Read)

Get Agent Pools
Endpoint: /_apis/distributedtask/pools
Scope: Agent Pools (Read)

Variable Groups
Endpoint: /_apis/distributedtask/variablegroups
Scope: Variable Groups (Read)

Test Connection
Endpoint: /_apis/ConnectionData
Scope: Service Connections (Read)

Steps:

1. A user should provision an access token for Evaluate to use during the scan.
2. Install gitlab-evaluate from the Install section above,
3. Run 👇

• For Azure DevOps Service (Cloud):

  evaluate-ado -s https://dev.azure.com/<your-org> -t <personal-access-token>
  

• For Azure DevOps Server:

  evaluate-ado -s {instance_url}/{collection} -t <personal-access-token> --api-version=7.0
  

• For Team Foundation Server (TFS):

  evaluate-ado -s {server_url:port}/tfs/{collection} -t <personal-access-token> --api-version=4.1
  

Note:

When running Evaluate against Azure DevOps Server or Team Foundation Server (TFS), you must specify the correct API version.

To determine the required API version:

1. Click your user icon and select Help > About to view your server information.
2. Refer to the API and TFS version mapping documentation to identify the appropriate API version for your server.
3. Unless the user provides a custom --filename, the report file is named evaluate_ado by default.
4. If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.

Command help screen

Usage: evaluate-ado [OPTIONS]

Options:
  -s, --source TEXT       Source URL  [required]
  -t, --token TEXT        Personal Access Token  [required]
  -p, --processes TEXT    Number of processes. Defaults to number of CPU cores
  --skip-details          Skips details
  --project TEXT          Project ID. Evaluate all data within a given Azure
                          DevOps project (Project ID should be in UUID format)
  --api-version TEXT      API version to use (default: 7.2-preview)
  -f, --filename TEXT     XLSX Output File Name (default: evaluate_ado)
  -i, --insecure          Set to ignore SSL warnings
  -v, --verbose           Set logging level to Debug and output everything to
                          the screen and log file. Shows detailed progress for
                          data fetching including page numbers and item counts.
  -q, --quiet             Set logging level to Warning to reduce output. Useful
                          for large instances or CI pipelines.
  --max-commits INTEGER   Maximum number of commits to fetch per repository.
                          If limit is reached, Excel will show ">X" (e.g. ">100000")
  --help                  Show this message and exit.

[BETA] Github Enterprise / github.com

Evaluate supports scanning either a GitHub Enterprise Server (GHES) instance or a single github.com organization to retrieve relevant metadata.

The same evaluate-github command is used for both. The tool automatically detects whether the source URL is https://github.com (in which case it targets https://api.github.com) or a GHES host (in which case it targets <host>/api/v3).

Token Requirements

Use a classic Personal Access Token (other token types may also work).

Note for github.com: github.com has no instance-wide admin endpoints, so the scan is always scoped to a single org via the required --org flag. The "Users" sheet will only contain that org's members and the "App Stats" sheet will not include a GitHub version (this is expected; github.com does not expose installed_version).

Usage

1. Provision a token as described above.

2. Install gitlab-evaluate from the Install section above.

3. OPTIONAL: If you are using a custom CA, export the CA bundle: export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

4. Run 👇

   For a GitHub Enterprise Server instance:

   evaluate-github -s https://ghe.example.com -t <access-token>
   

   Optionally scope a GHES scan to a single org:

   evaluate-github -s https://ghe.example.com -t <access-token> --org <org-login>
   

   For a github.com organization (org owner PAT, --org is required):

   evaluate-github -s https://github.com -t <access-token> --org <org-login>
   

5. This creates a file called evaluate_github.xlsx in the working directory.

6. If you're coordinating a GitLab PS engagement, email these files to the GitLab account team.

Command help screen

Usage: evaluate-github [OPTIONS]

Options:
  -s, --source TEXT           Source URL (use https://github.com for
                              github.com)  [required]
  -t, --token TEXT            Personal Access Token  [required]
  --org TEXT                  GitHub org login. Required for github.com;
                              optional for GHES to scope the scan to a single
                              org.
  --max-wait-seconds INTEGER  Maximum cumulative time (seconds) to wait out
                              GitHub rate limits for a single request (summed
                              across retries) before returning partial data
                              and continuing.  [default: 3600]
  -f, --filename TEXT         XLSX Output File Name (without .xlsx extension).
                              Defaults to 'evaluate_github'
  -q, --quiet                 Set logging level to Warning to reduce output.
                              Useful for large instances or CI pipelines
  --help                      Show this message and exit.

Migration wave estimation (AI flow)

PS Migration Wave Estimator is a GitLab Duo flow published in the AI Catalog. It turns an Evaluate report into a migration duration estimate, so a wave does not have to be sized by hand.

Triggered on an issue, it reads the report from the repository and posts a single comment containing:

• Estimated duration for Direct Transfer and file-based export/import, both sequential and in parallel.
• For GitLab reports, the projects the report flagged as over a threshold, grouped by the cleanup action each one needs — pipelines, tags, branches, repository and storage size, packages, container registry and LFS objects — each with a link to the tool or API to do it with. Reading the output describes what every flagged component means; the thresholds below summarise the headline limits only.
• The projects contributing most to the estimate.

Bitbucket Server and GitHub reports are supported too. Those reports carry no threshold flags, so no outlier grouping is produced for them.

Usage

Prerequisites: the flow runs in CI/CD, so the project needs an available runner, and pushes by the flow's service account must be allowed by the project's push rules.

1. Enable the flow in the project that tracks the engagement — for example a customer collaboration project. This requires the Maintainer or Owner role and creates a service account for the flow.
2. Commit an Evaluate report to the default branch. The flow estimates from the CSV exports (Raw_Project_Data.csv and Evaluate_Report.csv); if you only have an .xlsx, commit that and the flow opens a merge request with the CSVs split out of it, then estimates without waiting for the merge.
3. Create an issue for the wave. For a GitLab report, list the projects in the wave in the description with their gid://gitlab/Project/<n> IDs — a table of name, ID and URL reads well. Omit the list to estimate every project in the report.
4. Mention the flow's service account in a comment on that issue, for example @ai-ps-migration-wave-estimator-<top-level-group> create report. Autocomplete in the comment box gives the exact handle. Assigning the issue to that account also triggers the flow.

Guidance:

• One report per run. If the repository holds several Evaluate reports, name the file you want in the comment; otherwise the flow asks which one to use rather than guessing.
• Attaching a report to the comment instead of committing it works for a report small enough to be a single wave, but such a run is read-only: it commits nothing and opens no merge request.
• Estimates are directional. Use them to plan waves and set expectations, not to commit to a maintenance window.

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