# README
GitLab Sanity CLI
GitLab Sanity CLI is a command line tool to cleanup GitLab server.
Motivation
Why this tool ?
This CLI was made to automate sanity jobs (like remove old unused GitLab Runners registrations) which is currently not possible by GitLab server WebUI.
The main purpose was to save time for cleanup tousend of runners, group-runners registrations and old projects.
Features
The CLI is able to list, remove and archive a set of resources.
Parameter Matrix
| Parameter | Type | Default Value | Description |
|---|---|---|---|
| -u, --url | string | '' | The Gitlab API URL |
| --insecure | boolean | false | Skip certificate Verfication for Gitlab API URL |
| -t, --token | string | '' | The GitLab API Access Token |
| -o, --operation | string | '' | Action to run (see below) |
| -r, --resource | string | '' | GitLab Resource to interact with |
| -p, --project-type | string | internal | Set the project visibility filter (internal, private, public) |
| -i, --identifier | int | '' | Specific Resource ID |
| -a, --age | int | 36 | Filter by last activity in months |
| -q, --query | string | '' | Search by name |
| -s, --state | string | '' | Filter list by state |
| -d, --dry-run | boolean | false | Dry run, does not change/delete any resources |
| -n, --num-concurrent-api-calls | int | 10 | Limit the amount of concurrent go routines to call the GitLab API |
| Action | Resource | Query filter applicable | Age filter applicable | Status filter applicable | Example |
|---|---|---|---|---|---|
| list | user | YES | - | - | List user with name admin: gitlab-sanity-cli -o list -r user -q admin |
| list | project | YES | YES | - | List internal projects older two years: gitlab-sanity-cli -o list -r project -a 24 -p public |
| list | runner | YES | - | YES | List docker based runner: gitlab-sanity-cli -o list -r runner -q docker |
| list | groupRunner | YES | - | YES | List online kubernetes based runner: gitlab-sanity-cli -o list -r groupRunner -q kubernetes -s online |
| list | pipeline | - | YES | - | List all Pipelines from specific project id: gitlab-sanity-cli -o list -r pipeline -i 1337 -a 0 |
| delete | user | - | - | - | Delete is not capable on users |
| delete | project | - | - | - | Remove project with ID 123: gitlab-sanity-cli -o delete -r project -i 123 |
| delete | runner | - | - | - | Remove runner with ID 123: gitlab-sanity-cli -o delete -r runner -i 123 |
| delete | groupRunner | - | - | - | Remove runner with ID 123: gitlab-sanity-cli -o delete -r groupRunner -i 123 |
| delete | pipeline | - | - | - | Remove Pipeline with ID 123 from project: gitlab-sanity-cli -o delete -r pipeline -i 1337 --pipelineId 123 |
| delete-all | user | - | - | - | Delete-All is not capable on users |
| delete-all | project | YES | YES | - | Remove all projects with name testing: gitlab-sanity-cli -o delete-all -r project -a 0 -q testing Remove all projects older than five years: gitlab-sanity-cli -o delete-all -r project -a 60 |
| delete-all | runner | YES | - | YES | Remove all offline runner: gitlab-sanity-cli -o delete-all -r runner -s offline |
| delete-all | groupRunner | YES | - | YES | Remove all groupRunner (offline and online): gitlab-sanity-cli -o delete-all -r groupRunner |
| delete-all | pipeline | - | YES | - | Remove all Pipelines from project: gitlab-sanity-cli -o delete-all -r pipeline -i 1337 |
| archive | project | - | - | - | Archive project with ID 123:gitlab-sanity-cli -o archive -r project -i 123 |
| archive-all | project | YES | YES | - | Archive project with name testing:gitlab-sanity-cli -o archive-all -r project -q testing -a 0 -p private |
How to run
Requirements
1. Download binary version
On Linux/MacOS/FreeBSD
export OS=`uname -s | tr '[A-Z]' '[a-z]'`
curl -L -O https://github.com/iteratec/gitlab-sanity-cli/releases/latest/download/gitlab-sanity-cli.${OS}.amd64.tar.gz
curl -L -O https://github.com/iteratec/gitlab-sanity-cli/releases/latest/download/gitlab-sanity-cli.${OS}.amd64.tar.gz.sha256
On Windows (open Powershell or Cmd and run follow commands)
curl -L -O https://github.com/iteratec/gitlab-sanity-cli/releases/latest/download/gitlab-sanity-cli.windows.amd64.zip
curl -L -O https://github.com/iteratec/gitlab-sanity-cli/releases/latest/download/gitlab-sanity-cli.windows.sha256
2. Verify Download
On Linux
sha256sum -c gitlab-sanity-cli.${OS}.amd64.tar.gz.sha256
On MacOS/FreeBSD
shasum -a 256 -c gitlab-sanity-cli.${OS}.amd64.tar.gz.sha256
On Windows
CertUtil -hashfile gitlab-sanity-cli.windows.amd64.zip.sha256 SHA256
Get-FileHash gitlab-sanity-cli.windows.amd64.zip.sha256 -Algorithm SHA256
Security Note: Please continue only if the hash verification was OK, otherwise don't use the tool!
3. Extract Binary from archive
On Linux/MacOS/FreeBSD
tar xvzf gitlab-sanity-cli.${OS}.amd64.tar.gz
mv gitlab-sanity-cli.${OS} gitlab-sanity-cli
chmod 0755 ./gitlab-sanity-cli
On Windows
powershell -command "Expand-Archive -Force 'gitlab-sanity-cli.windows.amd64.zip' '.'"
Check binary version
./gitlab-sanity-cli -v
Gitlab Sanity CLI (@iteratec)
VERSION: x.y.z
Test
./gitlab-sanity-cli -u gitlabserver.tld -t apitoken -o list -r project
See Parameter Matrix from above for examples
How to run from source
Requirements
First Run
go get -d -v ./...
Run command without building binary
go run cmd/main.go -h
How to build
Requirements
Use make to create the binaries
For Windows x86_64
make windows
For Linux x86_64
make linux
For MacOS x86_64
make darwin
For FreeBSD x86_64
make freebsd
For any other OS and Architecture:
See https://golang.org/doc/install/source#environment)
#
# MacOS (M1/arm64) Example
#
export target_os="darwin"
export target_arch="arm64"
env GOOS=${target_os} GOARCH=${target_arch} go build -ldflags "-extldflags '-static'" -o ./gitlab-sanity-cli.${target_os}.${target_arch} cmd/main.go
Update go modules
# List all used modules
go list -m all
# List all available versions from module
go list -m -versions github.com/xanzy/go-gitlab
# Get specific version from module
go get github.com/xanzy/[email protected]