github.com/michaellihs/golab@v0.1.0-beta3.0.20180726222757-f5cdabc76dfd/README.md (about) 1 Gitlab CLI written in Go [](https://travis-ci.org/michaellihs/golab) 2 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fmichaellihs%2Fgolab?ref=badge_shield) 3 ======================== 4 5 This project provides a Command Line Interface (CLI) for Gitlab written in Go. The project uses the [go-gitlab client](https://github.com/xanzy/go-gitlab) for the communication with Gitlab. 6 7 It allows you to run Gitlab administration tasks from your command line. 8 9 [TOC levels=1-3]: # "## Table of Contents" 10 11 ## Table of Contents 12 - [Usage](#usage) 13 - [Examples](#examples) 14 - [Installation](#installation) 15 - [Configuration](#configuration) 16 - [Login with Username and Password](#login-with-username-and-password) 17 - [Login with Access Token](#login-with-access-token) 18 - [ZSH auto-completion](#zsh-auto-completion) 19 - [Development](#development) 20 - [API Debugging](#api-debugging) 21 - [Build and test the application](#build-and-test-the-application) 22 - [Ginkgo Tests](#ginkgo-tests) 23 - [Update vendored dependencies](#update-vendored-dependencies) 24 - [Translate API Doc into Flag Structs](#translate-api-doc-into-flag-structs) 25 - [Gitlab Docker Image](#gitlab-docker-image) 26 - [Troubleshooting](#troubleshooting) 27 - [`panic: trying to get string value of flag of type int`](#panic-trying-to-get-string-value-of-flag-of-type-int) 28 - [`json: Unmarshal(non-pointer []*gitlab.ProtectedBranch)`](#json-unmarshalnon-pointer-gitlabprotectedbranch) 29 - [TODOs](#todos) 30 - [Support multiple Targets](#support-multiple-targets) 31 - [Support GPG keys in user command](#support-gpg-keys-in-user-command) 32 - [Support for nested groups](#support-for-nested-groups) 33 - [Fix password issue on Windows](#fix-password-issue-on-windows) 34 - [Further Resources](#further-resources) 35 36 37 Usage 38 ===== 39 40 Examples 41 -------- 42 43 * create a user 44 45 ``` bash 46 golab user create --email username@company.com --username username --password 12341234 --name "User McArthur" --skipConfirmation 47 ``` 48 49 * modify a user 50 51 ``` bash 52 golab user modify -i 41 --admin true 53 ``` 54 55 * create a new project / repository 56 57 ``` bash 58 golab project create -g my-group -n my-project 59 ``` 60 61 * add an ssh key for a user 62 63 ``` bash 64 golab user ssh-keys add --key "`cat ~/.ssh/id_rsa.pub`" --title "my dsa key" 65 ``` 66 67 * create commits from the command line 68 69 ``` bash 70 golab commits create --id 30 --actions "`cat cmd/fixtures/commit-actions.json`" --branch new-branch --start_branch master --commit_message "committed with golab" 71 ``` 72 73 * query your json output with [jq](https://stedolan.github.io/jq/) 74 75 ``` bash 76 golab project list | jq ".[] | {name: .name, id: .id} 77 ``` 78 79 For a complete documentation of features, check the [generated documentation](doc/golab.md) 80 81 82 Installation 83 ------------ 84 85 Install the CLI tool with 86 87 go get -u github.com/michaellihs/golab 88 go install github.com/michaellihs/golab 89 90 or download a [binary release](https://github.com/michaellihs/golab/releases). 91 92 93 Configuration 94 ------------- 95 96 ### Login with Username and Password 97 98 Run the following command to login with your username and password 99 100 golab login --host <hostname> --user <username> [--password <password>] 101 102 If `--password` is omitted, you'll be prompted to enter your password interactively. 103 104 According to [this discussion](https://github.com/xanzy/go-gitlab/issues/267) the login with username and password might not work with newer Gitlab versions. 105 106 107 ### Login with Access Token 108 109 First create a Gitlab [personal access token for your user](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) in Gitlab (most likely an admin user). 110 111 Create a file `.golab.yml` in either `~/` or the directory you want to use golab with the following content: 112 113 --- 114 url: "http(s)://<gitlab url>" 115 token: "<access token>" 116 117 Test your configuration - e.g. by running `golab project` to get a list of projects from your Gitlab server. 118 119 120 ZSH auto-completion 121 ------------------- 122 123 The auto-completion file for ZSH can be generated with 124 125 golab zsh-completion --path zsh/_golab 126 127 TODO: After the `#compdef` header, add a `#autoload` - see http://zsh.sourceforge.net/Doc/Release/Completion-System.html 128 129 Check where to add your auto-complete files with `echo $FPATH` and copy the generated file there with 130 131 cp zsh/_golab /usr/local/share/zsh/site-functions/_golab 132 133 Don't forget to reload / restart your ZSH shell after changing the auto-complete file (e.g. `source ~/.zshrc`). 134 135 136 Development 137 =========== 138 139 API Debugging 140 ------------- 141 142 Run `curl` requests against the API: 143 144 curl --header "PRIVATE-TOKEN: FqBiTTJ4oRPdskWDTktr" -H "Content-Type: application/json" -X PUT -d '{"admin": true}' http://localhost:8080/api/v4/users/41 145 146 147 Build and test the application 148 ------------------------------ 149 150 There is a `makefile` included that can build and test the application and render the automatically generated documentation: 151 152 * `make` - build the application 153 154 * `make test` - run the tests. Before you run the tests, you have to set the environment variables 155 156 * `GITLAB_HOST` 157 * `GITLAB_ROOT_USER` 158 * `GITLAB_ROOT_PASSWORD` 159 160 * `make gendoc` - render the documentation 161 162 163 Ginkgo Tests 164 ------------ 165 166 Run Ginkgo tests with 167 168 cd cmd 169 ginkgo -v 170 171 172 Update vendored dependencies 173 ---------------------------- 174 175 govendor fetch github.com/spf13/cobra 176 177 178 Translate API Doc into Flag Structs 179 ----------------------------------- 180 181 Regular expression for replace in IntelliJ 182 183 (\s+)([^\s]+?)\s+([^\s]+?)\s+([^\s]+?)\s+(.+) 184 $1$2 *$3 `flag_name:"$2" type:"$3" required:"$4" description:"$5"` 185 186 187 Gitlab Docker Image 188 ------------------- 189 190 For local development, you can use a [Gitlab Docker image](https://docs.gitlab.com/omnibus/docker/README.html). There are some pitfalls, when using Gitlab Docker image on a Mac: 191 192 * You cannot properly mount the `/var/opt/gitlab` directory due to issues with NFS mounts on Mac 193 * The ssh port `22` is already in use on the Mac, if a ssh server is running 194 195 Therefore adapt the provided run command to the following: 196 197 sudo docker run --detach \ 198 --hostname gitlab.example.com \ 199 --publish 443:443 --publish 8080:80 --publish 8022:22 \ 200 --name gitlab \ 201 --volume /tmp/gitlab/config:/etc/gitlab \ 202 --volume /tmp/gitlab/logs:/var/log/gitlab \ 203 gitlab/gitlab-ce:9.5.10-ce.0 204 205 On my machine: 206 207 {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}] 208 209 Afterwards you can start the (existing) container with: 210 211 sudo docker start gitlab 212 213 **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`. 214 215 216 Troubleshooting 217 --------------- 218 219 ### `panic: trying to get string value of flag of type int` 220 221 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. 222 223 ```` 224 GroupAccess *string `flag_name:"group_access" short:"a" type:"integer" transform:"str2AccessLevel" required:"yes" description:"..."` 225 ```` 226 227 Remember: you only can use `*string` as field type, when you need a transformation of the value! 228 229 230 ### `json: Unmarshal(non-pointer []*gitlab.ProtectedBranch)` 231 232 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. 233 234 ```` golang 235 var p []*ProtectedBranch 236 resp, err := s.client.Do(req, p) 237 ```` 238 239 instead of 240 241 ```` golang 242 var p []*ProtectedBranch 243 resp, err := s.client.Do(req, &p) 244 ```` 245 246 247 TODOs 248 ===== 249 250 Support multiple Targets 251 ------------------------ 252 253 `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`. 254 255 Therefore we also need to change the structure of the `.golab.yml` like this: 256 257 --- 258 gitlab.com: 259 url: "https://gitlab.com" 260 token: "gitlab_com_token" 261 262 localhost: 263 url: "http://localhost:12345" 264 token: "localhost_token" 265 266 This allows working with multiple Gitlab servers at the same time. 267 268 269 Support GPG keys in user command 270 -------------------------------- 271 272 Currently the [go-gitlab library](https://github.com/xanzy/go-gitlab) provides no support for GPG keys, neither does this to. 273 274 275 Support for nested groups 276 ------------------------- 277 278 Currently there is no support for [nested groups](https://docs.gitlab.com/ce/api/groups.html#list-a-groups-39-s-subgroups) since this feature is only available in Gitlab >= 10.3 279 280 281 Fix password issue on Windows 282 ----------------------------- 283 284 Currently, when logging in with username and password (on Cygwin) on Windows, the password is not hidden (as it is on MacOS). 285 286 287 Further Resources 288 ================= 289 290 * [Gitlab API Documentation](https://docs.gitlab.com/ee/api/README.html) 291 * [Cobra Library (Go CLI Library)](https://github.com/spf13/cobra) 292 * [Viper Library (Go Flags Library)](https://github.com/spf13/viper) 293 * [Sling (Go HTTP Library)](https://github.com/dghubble/sling) 294 * [Ginkgo (Go Testing Library)](https://onsi.github.io/ginkgo/) 295 * [GoMock (Go Mocking Library)](https://github.com/golang/mock) 296 * [go-gitlab (Go Gitlab Library)](https://github.com/xanzy/go-gitlab) 297 * [govendor on Heroku](https://devcenter.heroku.com/articles/go-dependencies-via-govendor) 298 299 300 ## License 301 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fmichaellihs%2Fgolab?ref=badge_large)