Skip to main content

A restful web service for querying the repository sizes of a GitLab registry.

Project description



GitLab-Registry-Usage-REST is a package that periodically collects repository information (names, tags, sizes) of a GitLab registry server and offers the data via a secured RESTful HAL api. For the initial authentication a LDAP server is needed. Subsequent queries are secured by JSON Web Tokens (JWT).


The latest version can be obtained from PyPI:

pip install gitlab-registry-usage-rest
gitlab-registry-usage-rest --help

or from DockerHub:

docker run sciapp/gitlab-registry-usage-rest:latest --help

or from the AUR for Arch Linux based systems:

yay -S gitlab-registry-usage-rest


Gitlab-Registry-Usage-REST needs a configuration file in order to run. The default path is /etc/gitlab_registry_usage_rest.conf but can be altered with the -c command line switch. To get started, you can run

gitlab-registry-usage-rest --print-default-config

and edit this default configuration to fit your environment.

If you would like to use the docker repository, you can bind mount a local configuration file with the -v switch:

docker run -v "$(pwd)/gitlab_registry_usage_rest.conf:/etc/gitlab_registry_usage_rest.conf" sciapp/gitlab-registry-usage-rest:latest

Note: Docker expects an absolute path for the local configuration file.

The server offers these api endpoints:

  • /auth_token: Accepts a request with basic auth (and valid LDAP credentials) and returns an auth token for further api usage. All other endpoints only accept requests with a valid Bearer authorization header:

    Authorization: Bearer <token>
  • /repositories: Lists attributes of the repositories collection. Currently, only the timestamp of the last data refresh is contained:

        "timestamp": 1521796487.7021387
  • /repositories/<repository_name>: Queries attributes of a specific repository:

        "name": "scientific-it-systems/administration/gitlab-registry-usage-rest",
        "size": 39899199,
        "disk_size": 39898911
  • /repositories/<repository_name>/tags: Endpoint for the collection of repository tags, currently without any content.

  • /repositories/<repository_name>/tags/<tag_name>: Lists attributes of a tagged image stored in a repository:

        "name": "latest",
        "size": 39899199,
        "disk_size": 39898911

Additionally, all api endpoints (except /auth_token) offer an _embedded and a _links attribute if requested with the query string:


Instead of a boolean value, the embed key can also take an integer number to only request a specific level of embedded resources.

Links can be used to easily navigate between related resources. Embedded resources are convenient to query a complete hierarchy of resources with one GET request. Accordingly, the request


returns all resources at once.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gitlab-registry-usage-rest-0.3.2.tar.gz (11.1 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page