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
Get yourself Private Token from your Gitlab server ("Account Settings" - "Account")
Edit your `~/.bashrc` or `~/.profile` or `~/.zshrc` or whatever configures the shell you use and add the following lines
Make sure to "reload" your `.bashrc` (or whatever) file with `source ~/.bashrc`
Install the Gem with `gem install gitlab`. If you are using rbenv, run `rbenv rehash`
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.
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.