A few months ago I discovered the Gitlab Gem, which offers a client library for the Gitlab API endpoints. It took me until last week to find out that this Gem ships with a command line tool gitlab that lets you use the Gitlab API from the command line. Here are a few tips and tricks.

Installing the Gitlab CLI

  1. Get yourself Private Token from your Gitlab server ("Account Settings" - "Account")
  2. Edit your `~/.bashrc` or `~/.profile` or `~/.zshrc` or whatever configures the shell you use and add the following lines 
    export GITLAB_API_PRIVATE_TOKEN=YOUR_API_KEY
export GITLAB_API_ENDPOINT=https://YOUR_GITLAB_SERVER_DOMAIN/api/v3
  3. Make sure to "reload" your `.bashrc` (or whatever) file with `source ~/.bashrc`
  4. Install the Gem with `gem install gitlab`. If you are using rbenv, run `rbenv rehash`
  5. Check whether your installation was successful with `gitlab help` and `gitlab projects`. The latter should return a list of projects from your Gitlab server.

Using the Gitlab CLI

Unfortunately, the man pages of the Gitlab CLI that you get with gitlab help are not very concise. The ‘easiest’ way to find out, how to use the tool, is going to the Gitlab Client API Documentation and searching for the corresponding method. There you will find a detailed list of methods, parameters and options that gives you a hint on how to use the command line tool.

Remind that any options (not arguments) given to a method need to be encoded in a YAML-style format on the command line. E.g. if you want to pass the option per_page to the gitlab projects command, you have to use gitlab projects "{per_page: 1000}". Any string values have to be wrapped in '...'.

So here are some examples on how to use the gitlab command line tool:

Gitlab Projects (a.k.a. Repositories)

  • Get a list of the 20 most recent projects: 
    gitlab projects
  • Get a list of all projects: 
    gitlab projects "{per_page: 10000}"
    where `10000` is a big enough number to get all projects from your Gitlab server.
  • Search for a project: 
    gitlab project_search NAME
  • Create a project in your Gitlab userspace: 
    gitlab create_project PROJECT_NAME
  • Create a project in a distinct group:

    First: Find the Gitlab ID of the group you want to add your project to with
    gitlab groups "{per_page: 1000}" | grep GROUP_NAME.

    Then use this ID as in: 
    gitlab create_project PROJECT_NAME "{namespace_id: 'ID'}"
  • Add a deploy key with content DEPLOY_KEY_CONTENT and a description DESCRIPTION to a project with ID PROJECT_ID: 
    gitlab create_deploy_key PROJECT_ID 'DEPLOY_KEY_DESCRIPTION' 'DEPLOY_KEY_CONTENT'
    Heres is an example that reads the key from an existing RSA file: 
    gitlab create_deploy_key 616 'Jenkins Vagrant Development' "`cat ../vagrant-jenkinsmaster/cookbooks/env_jenkins_master_dev/files/id_rsa.pub`"

Gitlab Groups

  • Get a list of all groups: 
    gitlab groups "{per_page: 1000}"
  • Create a group with the name GROUP_NAME and the path PATH: 
    gitlab create_group "GROUP_NAME" "PATH"
  • Add a user with the ID USER_ID to a group with ID GROUP_ID with access level ACCESS_LEVEL: 
    gitlab add_group_member GROUP_ID USER_ID ACCESS_LEVEL
    ACCESS_LEVEL is an integer value, you can look up the values in Gitlab's access.rb file. Here are the current values:
    • GUEST = 10
    • REPORTER = 20
    • DEVELOPER = 30
    • MASTER = 40
    • OWNER = 50

Gitlab Users

  • Search for a user with the name USERNAME: 
    gitlab users "{per_page: 1000}" | grep "USERNAME"
    Remind that the per_page: 1000 option makes sure that "all" users are returned!

Gitlab Merge Requests

  • Given you have a branch SOURCE_BRANCH that you want to merge into master in a project with id PROJECT_ID and assign the merge request to a user with id ASSIGNEE_ID, you can use the following command: 
    gitlab create_merge_request PROJECT_ID 'Titel of the Merge Request' \
    '{source_branch: 'SOURCE_BRANCH', \
      target_branch: 'master', \
      assignee_id: ASSIGNEE_ID}'

Global Parameters

--only=

You can add the --only= parameter to any command and restrict the fields to be shown in the result table. E.g.

gitlab project_search chef_ --only=name,id

+-----+---------------------------------------+
| Gitlab.project_search chef_, --only=name,id |
+-----+---------------------------------------+
| id  | name                                  |
+-----+---------------------------------------+
| 649 | chef_base_freebsd                     |
+-----+---------------------------------------+
| 646 | chef_app_mysql                        |
+-----+---------------------------------------+
| 645 | chef_app_apache                       |
+-----+---------------------------------------+