README
¶
Gitlab CLI written in Go 
This project provides a Command Line Interface (CLI) for Gitlab written in Go. The project uses the go-gitlab client for the communication with Gitlab.
It allows you to run Gitlab administration tasks from your command line.
Table of Contents
Usage
Examples
-
create a user
golab user create --email username@company.com --username username --password 12341234 --name "User McArthur" --skipConfirmation -
modify a user
golab user modify -i 41 --admin true -
create a new project / repository
golab project create -g my-group -n my-project -
add an ssh key for a user
golab user ssh-keys add --key "`cat ~/.ssh/id_rsa.pub`" --title "my dsa key" -
create commits from the command line
golab commits create --id 30 --actions "`cat cmd/fixtures/commit-actions.json`" --branch new-branch --start_branch master --commit_message "committed with golab" -
query your json output with jq
golab project list | jq ".[] | {name: .name, id: .id}
For a complete documentation of features, check the generated documentation
Installation
Install the CLI tool with
go get -u github.com/michaellihs/golab
go install github.com/michaellihs/golab
or download a binary release.
Configuration
Login with Username and Password
Run the following command to login with your username and password
golab login --host <hostname> --user <username> [--password <password>]
If --password is omitted, you'll be prompted to enter your password interactively.
According to this discussion the login with username and password might not work with newer Gitlab versions.
Login with Access Token
First create a Gitlab personal access token for your user in Gitlab (most likely an admin user).
Create a file .golab.yml in either ~/ or the directory you want to use golab with the following content:
---
url: "http(s)://<gitlab url>"
token: "<access token>"
Test your configuration - e.g. by running golab project to get a list of projects from your Gitlab server.
ZSH auto-completion
The auto-completion file for ZSH can be generated with
golab zsh-completion --path zsh/_golab
TODO: After the #compdef header, add a #autoload - see http://zsh.sourceforge.net/Doc/Release/Completion-System.html
Check where to add your auto-complete files with echo $FPATH and copy the generated file there with
cp zsh/_golab /usr/local/share/zsh/site-functions/_golab
Don't forget to reload / restart your ZSH shell after changing the auto-complete file (e.g. source ~/.zshrc).
Development
API Debugging
Run curl requests against the API:
curl --header "PRIVATE-TOKEN: FqBiTTJ4oRPdskWDTktr" -H "Content-Type: application/json" -X PUT -d '{"admin": true}' http://localhost:8080/api/v4/users/41
Build and test the application
There is a makefile included that can build and test the application and render the automatically generated documentation:
-
make- build the application -
make test- run the tests. Before you run the tests, you have to set the environment variables -
GITLAB_HOST -
GITLAB_ROOT_USER -
GITLAB_ROOT_PASSWORD -
make gendoc- render the documentation
Ginkgo Tests
Run Ginkgo tests with
cd cmd
ginkgo -v
Update vendored dependencies
govendor fetch github.com/spf13/cobra
Translate API Doc into Flag Structs
Regular expression for replace in IntelliJ
(\s+)([^\s]+?)\s+([^\s]+?)\s+([^\s]+?)\s+(.+)
$1$2 *$3 `flag_name:"$2" type:"$3" required:"$4" description:"$5"`
Gitlab Docker Image
For local development, you can use a Gitlab Docker image. There are some pitfalls, when using Gitlab Docker image on a Mac:
- You cannot properly mount the
/var/opt/gitlabdirectory due to issues with NFS mounts on Mac - The ssh port
22is already in use on the Mac, if a ssh server is running
Therefore adapt the provided run command to the following:
sudo docker run --detach \
--hostname gitlab.example.com \
--publish 443:443 --publish 8080:80 --publish 8022:22 \
--name gitlab \
--volume /tmp/gitlab/config:/etc/gitlab \
--volume /tmp/gitlab/logs:/var/log/gitlab \
gitlab/gitlab-ce:9.5.10-ce.0
On my machine:
{bind /Users/mimi/docker/gitlab/config /etc/gitlab true rprivate} {bind /Users/mimi/docker/gitlab/logs /var/log/gitlab true rprivate} {bind /Users/mimi/docker/gitlab/data /var/opt/gitlab true rprivate}]
Afterwards you can start the (existing) container with:
sudo docker start gitlab
Attention we are currently testing against Gitlab version 9.5.10-ce.0. Make sure to pin the version of the Docker image instead of using latest.
Troubleshooting
panic: trying to get string value of flag of type int
If you see panic: trying to get string value of flag of type int, most likely you used a flag type other than *string for a flag that needs transformation, e.g.
GroupAccess *string `flag_name:"group_access" short:"a" type:"integer" transform:"str2AccessLevel" required:"yes" description:"..."`
Remember: you only can use *string as field type, when you need a transformation of the value!
json: Unmarshal(non-pointer []*gitlab.ProtectedBranch)
If you see json: Unmarshal(non-pointer []*gitlab.ProtectedBranch), most likely you forgot to use the pointer of a return value in the XyzService, e.g.
var p []*ProtectedBranch
resp, err := s.client.Do(req, p)
instead of
var p []*ProtectedBranch
resp, err := s.client.Do(req, &p)
TODOs
Support multiple Targets
golab login should take a parameter -e that sets an environment which we can later on select with -e in each command or read from $golab_env.
Therefore we also need to change the structure of the .golab.yml like this:
---
gitlab.com:
url: "https://gitlab.com"
token: "gitlab_com_token"
localhost:
url: "http://localhost:12345"
token: "localhost_token"
This allows working with multiple Gitlab servers at the same time.
Support GPG keys in user command
Currently the go-gitlab library provides no support for GPG keys, neither does this to.
Support for nested groups
Currently there is no support for nested groups since this feature is only available in Gitlab >= 10.3
Fix password issue on Windows
Currently, when logging in with username and password (on Cygwin) on Windows, the password is not hidden (as it is on MacOS).
Further Resources
Documentation
¶
There is no documentation for this package.
Source Files
Directories