{"id":22394065,"url":"https://github.com/flant/glaball","last_synced_at":"2025-04-09T12:06:10.080Z","repository":{"id":38206141,"uuid":"491567520","full_name":"flant/glaball","owner":"flant","description":"A CLI tool to manage self-hosted GitLab instances in bulk.","archived":false,"fork":false,"pushed_at":"2024-11-25T18:46:47.000Z","size":283,"stargazers_count":73,"open_issues_count":2,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T06:49:59.305Z","etag":null,"topics":["gitlab","gitlab-ce","gitlab-cli"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-12T15:22:01.000Z","updated_at":"2025-03-14T19:05:29.000Z","dependencies_parsed_at":"2022-09-12T19:03:17.334Z","dependency_job_id":"967c18ae-bb3e-49c2-b9d0-ac72defea8a9","html_url":"https://github.com/flant/glaball","commit_stats":{"total_commits":85,"total_committers":5,"mean_commits":17.0,"dds":0.09411764705882353,"last_synced_commit":"97da624530e230c82bfb326e5aff0b26dfa58b01"},"previous_names":["flant/gitlaball"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fglaball","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fglaball/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fglaball/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flant%2Fglaball/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flant","download_url":"https://codeload.github.com/flant/glaball/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036063,"owners_count":21037092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitlab","gitlab-ce","gitlab-cli"],"created_at":"2024-12-05T05:08:48.719Z","updated_at":"2025-04-09T12:06:10.058Z","avatar_url":"https://github.com/flant.png","language":"Go","readme":"[![Go](https://github.com/flant/glaball/actions/workflows/go.yml/badge.svg)](https://github.com/flant/glaball/actions/workflows/go.yml)\n[![Docker Image](https://github.com/flant/glaball/actions/workflows/docker.yml/badge.svg)](https://github.com/flant/glaball/actions/workflows/docker.yml)\n\nGlaball is a CLI tool to manage multiple self-hosted GitLab instances at the same time. [This announcement](https://blog.flant.com/glaball-to-manage-gitlab-instances-in-bulk/) tells the story why it was created.\n\n**Contents**:\n* [Features](#features)\n* [Installing](#installing)\n  * [Building](#building)\n  * [Configuring](#configuring)\n  * [How to add a GitLab host?](#how-to-add-a-gitlab-host)\n  * [Important note on security](#important-note-on-security)\n* [Usage](#usage)\n  * [Autocompletion](#autocompletion)\n  * [Usage examples](#usage-examples)\n* [Community](#community)\n* [License](#license)\n\n## Features\n\nGlaball currently supports the following features:\n\n* Creating/blocking/deleting/modifying users (`users [create|block|delete|modify]`)\n* Displaying a list of users with sorting/grouping/filtering options (`users list`)\n* Searching for a specific user (`users search`)\n* Displaying a list of repositories with sorting/grouping/filtering options (`projects list`)\n* Editing some repository options (`projects edit`)\n* Searching for scheduled jobs in repositories and filtering by active/inactive status (`projects pipelines schedules`)\n* Searching for the regex pattern in the specified files in the repositories (`projects files search`)\n* Displaying a list of current GitLab instance versions with information on whether an update is necessary (up to date|update available|update asap)\n* Displaying information about the current API user (`whoami`)\n\n## Installing\n\nYou can get the compiled binary at [the releases page](https://github.com/flant/glaball/releases).\n\n### Building\n\n```\n$ git clone https://github.com/flant/glaball.git\n$ cd glaball\n$ go build -v -o build/glaball *.go\n```\n\n### Configuring\n\n```\n$ cat ~/.config/glaball/config.yaml\n\n# Cache settings\ncache:\n  # HTTP request cache is enabled by default\n  enabled: true\n  # The cache is stored in the user's cache directory by default\n  # $HOME/.cache/glaball\n  path: \"\"\n  # The default cache size is 100MB\n  size: 100MB\n  # GZIP cache compression is enabled by default\n  compression: true\n  # By default, the cache is valid for 1 day\n  ttl: 24h\n\n# By default, operations are performed for all hosts.\n# You can use a regexp command/project filter (e.g., \"main.*\" or \"main.example-project\")\n# at the config level or use the --filter flag (-f)\nfilter: \".*\"\n\n# By default, count of hosts in grouped output is limited to 5.\n# If you want to show all hosts, set this option to true or use the --all flag (-a).\nall: false\n\n# The number of simultaneous HTTP connections\nthreads: 100\n\n# Host list (required)\n# The project name is generated as follows: \"\u003cteam\u003e.\u003cproject\u003e.\u003cname\u003e\"\nhosts:\n  # The team (e.g., main)\n  team:\n    # The project name (e.g., example-project)\n    project:\n      # The GitLab name\n      name:\n        # Link to the project's GitLab repo\n        url: https://gitlab.example.com\n        # Custom IP address of host\n        # If you want to override IP address resolved by the default resolver, use this option.\n        ip: 127.0.0.1\n        # The user's token the client will use to connect to the API\n        # API token - provides full permissions, including user creation/deletion\n        # Read API token - provides read-only access without permissions to create/modify users or filtering the list of users by their email address\n        token: \u003capi|read_api token\u003e\n        # Rate limit check\n        # This one is disabled by default if a cache is used because it generates additional non-cacheable requests.\n        # It only makes sense to enable it if the rate limit in GitLab is enabled\n        # https://docs.gitlab.com/ee/security/rate_limits.html\n        rate_limit: false\n```\n\n### How to add a GitLab host?\n- Go to https://gitlab.example.com/-/profile/personal_access_tokens as a user;\n- Create a **Personal Access Token** named `glaball` with the following scope:\n  - `read_api` - if only read access is required;\n  - `api` - if full access is required. This one allows you to create users and so forth (note that the user must have the admin privileges);\n- Add your host and a token to the `config.yaml` file and copy it to the glaball directory (or specify the path to the config file via the `--config=path` parameter).\n\nExample:\n```\nhosts:\n  main:\n    example-project:\n      primary:\n        url: https://gitlab-primary.example.com\n        token: api_token\n      secondary:\n        url: https://gitlab-secondary.example.com\n        token: api_token\n```\n\nLet's check that the host is in the config:\n```\n$ glaball config list\n[main.example-project.secondary] https://gitlab-secondary.example.com\n[main.example-project.primary]   https://gitlab-primary.example.com\nTotal: 2\n```\n\n### Important note on security\n\nCurrently, all access tokens are simply stored in the glaball configuration file from where they can be used to access relevant GitLab instances. Remember to set appropriate permissions on your config, use `read_api` tokens only (if possible), and apply a strict expiry policy for your tokens.\n\n## Usage\n\n```\n$ glaball -h\nGitlab bulk administration tool\n\nUsage:\n  glaball [flags]\n  glaball [command]\n\nAvailable Commands:\n  cache       Cache management\n  completion  Generate the autocompletion script for the specified shell\n  config      Information about the current configuration\n  help        Help about any command\n  info        Information about the current build\n  projects    Projects API\n  users       Users API\n  versions    Retrieve version information for GitLab instances\n  whoami      Current API user\n\nFlags:\n  -a, --all                Show all hosts in grouped output\n      --config string      Path to the configuration file. (default \"$HOME/.config/glaball/config.yaml\")\n  -f, --filter string      Select Gitlab(s) by regexp filter (default \".*\")\n  -h, --help               help for glaball\n      --log_level string   Only log messages with the given severity or above. Valid levels: [debug, info, warn, error, off] (default \"info\")\n      --threads int        Number of concurrent processes. (default: one process for each Gitlab instances in config file) (default 100)\n      --ttl duration       Override cache TTL set in config file (default 24h0m0s)\n  -u, --update             Refresh cache\n  -v, --verbose            Verbose output\n\nUse \"glaball [command] --help\" for more information about a command.\n```\n\n### Autocompletion\n\n#### Bash\n```\n$ glaball completion bash -h\n\nGenerate the autocompletion script for the bash shell.\n\nThis script depends on the 'bash-completion' package.\nIf it is not installed already, you can install it via your OS's package manager.\n\nTo load completions in your current shell session:\n$ source \u003c(glaball completion bash)\n\nTo load completions for every new session, execute once:\nLinux:\n  $ glaball completion bash \u003e /etc/bash_completion.d/glaball\nMacOS:\n  $ glaball completion bash \u003e /usr/local/etc/bash_completion.d/glaball\n\nYou will need to start a new shell for this setup to take effect.\n```\n\n#### Zsh\n\n```\n$ glaball completion zsh -h\n\nGenerate the autocompletion script for the zsh shell.\n\nIf shell completion is not already enabled in your environment you will need\nto enable it.  You can execute the following once:\n\n$ echo \"autoload -U compinit; compinit\" \u003e\u003e ~/.zshrc\n\nTo load completions for every new session, execute once:\n# Linux:\n$ glaball completion zsh \u003e \"${fpath[1]}/_glaball\"\n# macOS:\n$ glaball completion zsh \u003e /usr/local/share/zsh/site-functions/_glaball\n\nYou will need to start a new shell for this setup to take effect.\n```\n\n## Usage examples\n\n### Create a user\nHere is how you can create a new user in `main` team projects:\n\n```\n$ glaball users create --filter \"main.*\" --email=test@test.com --username=test-glaball --name=\"test glaball\" --password=\"qwerty\"\n```\n\n### Block a user\n```\n$ glaball users block --by=username test-glaball\n```\n\nDisplay the list of projects in which this user exists:\n```\n$ glaball users block --by=username test-glaball --hosts\n```\n\n### Edit projects options\n```\n$ glaball projects edit --search_namespaces=true --search mygroup/ --ci_forward_deployment_enabled=false\n```\n\n### List opened merge requests\n```\n$ glaball projects mr list\n```\n\n### Protect main branch in all projects\n```\n$ glaball projects branches protected protect --name=\"main\" --merge_access_level=30\n```\n\n### Search for a pattern in the files\n*You can search through several files at once, but that (at least) doubles the search time.*\n\n*You can search for several patterns at once; it does not affect the search time.*\n\n```\n$ glaball projects files search --filepath=\"werf.yaml,werf.yml\" --pattern=\"mount\" --show\n```\n\n### Search for scheduled pipelines\nThe command below displays a list of projects with inactive scheduled pipelines:\n```\n$ glaball -f \"main.*\" projects pipelines schedules --active=false\n```\n\n### List and create [werf](https://github.com/werf/werf) cleanup [schedules](https://werf.io/documentation/v1.2/advanced/ci_cd/gitlab_ci_cd.html#cleaning-up-images)\nList all cleanup schedules including non-existent:\n```\n$ glaball projects pipelines cleanups\n```\n\nCreate cleanup schedules in all projects (only **one** gitlab host):\n```\n$ glaball projects pipelines cleanups -f \"main.example-project.primary\" --create --setowner ${WERF_IMAGES_CLEANUP_PASSWORD}\n```\n\nChange the owner of existing cleanup scheduled pipelines (only **one** gitlab host):\n```\n$ glaball projects pipelines cleanups -f \"main.example-project.primary\" --setowner ${WERF_IMAGES_CLEANUP_PASSWORD}\n```\n\n### Get information about the projects' container registries\n```\n$ glaball projects registry list --size | sort -k 4 -h\n```\n\n### Search for a user\n```\n$ glaball users search --by=username docker\n```\n\n### List users\nDisplay the list of users grouped by the username:\n```\n$ glaball users list --group_by=username\n```\n\nShow only those users who are active in *n* projects:\n```\n$ glaball users list --group_by=username --count n --all\n```\n\nDisplay the list of administrators:\n```\n$ glaball users list --group_by=username --admins=true\n```\n\n### Show the list of hosts specified in the config\n```\n$ glaball config list\n```\n\n### Clear the cache\n```\n$ glaball cache clean\n```\n\n### Show the list of current versions\n```\n$ glaball versions\n```\n\n### Show the active user\n```\n$ glaball whoami\n```\n\n# Community\n\nOriginally created in [Flant](https://flant.com/).\n\nPlease, feel free to reach developers/maintainers and users via [GitHub Discussions](https://github.com/flant/glaball/discussions) for any questions.\n\nYou're welcome to follow [@flant_com](https://twitter.com/flant_com) to stay informed about all our Open Source initiatives.\n\n# License\n\nApache License 2.0, see [LICENSE](LICENSE).\n\nGITLAB, the GitLab logo and all other GitLab trademarks herein are the registered and unregistered trademarks of [GitLab, Inc.](https://about.gitlab.com/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflant%2Fglaball","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflant%2Fglaball","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflant%2Fglaball/lists"}