diff --git a/SKILL.md b/SKILL.md index 8bfb16a..bd812ca 100644 --- a/SKILL.md +++ b/SKILL.md @@ -77,8 +77,8 @@ This skill routes to specialized sub-skills by GitLab domain: - `glab-schedule` - Scheduled pipelines and cron jobs - `glab-variable` - CI/CD variables and secrets - `glab-securefile` - Secure files for pipelines -- `glab-runner` - Runner management: list, pause, delete (added v1.87.0) -- `glab-runner-controller` - Runner controller and token management (EXPERIMENTAL, admin-only) +- `glab-runner` - Runner management: list, assign/unassign, inspect jobs/managers, pause/unpause, delete (added v1.87.0; expanded in v1.90.0) +- `glab-runner-controller` - Runner controller, scope, and token management (EXPERIMENTAL, admin-only) **Collaboration:** - `glab-user` - User profiles and information @@ -105,6 +105,15 @@ This skill routes to specialized sub-skills by GitLab domain: - `glab-duo` - GitLab Duo AI assistant - `glab-mcp` - Model Context Protocol server for AI assistant integration (EXPERIMENTAL) +## v1.90.0 Updates + +Key user-facing changes in `glab` v1.90.0 that affect this skill set: + +- **`glab-auth`**: `glab auth login` adds `--web`, `--container-registry-domains`, and `--ssh-hostname`; CI auto-login is now GA. +- **`glab-mr`**: `glab mr create` adds `--auto-merge`; `glab mr note` now has `list`, `resolve`, and `reopen` subcommands in addition to note-posting flags. +- **`glab-runner`**: adds `jobs`, `managers`, and `update --pause|--unpause`. +- **`glab-runner-controller`**: adds `get` and shifts runner scope management under `scope list|create|delete`. + ## v1.89.0 Updates > **v1.89.0+:** 18 commands across 12 sub-skills now support `--output json` / `-F json` for structured output — raw GitLab API responses ideal for agent/automation parsing. Affected sub-skills: `glab-release`, `glab-ci`, `glab-milestone`, `glab-schedule`, `glab-mr`, `glab-repo`, `glab-label`, `glab-deploy-key`, `glab-ssh-key`, `glab-gpg-key`, `glab-cluster`, `glab-opentofu`. diff --git a/glab-auth/SKILL.md b/glab-auth/SKILL.md index 42107eb..b7636fb 100644 --- a/glab-auth/SKILL.md +++ b/glab-auth/SKILL.md @@ -13,6 +13,9 @@ Manage GitLab CLI authentication. # Interactive login glab auth login +# Browser/OAuth login without the prompt (v1.90.0+) +glab auth login --hostname gitlab.com --web + # Check current auth status glab auth status @@ -32,10 +35,33 @@ glab auth logout 3. Follow prompts for your GitLab instance 4. Verify with `glab auth status` -> **v1.89.0+:** When connecting to a **self-hosted GitLab instance**, `glab auth login` now prompts for the **SSH hostname separately** from the API hostname. This allows your SSH remote to use a different host than the API endpoint — useful when your company routes SSH and HTTPS traffic differently. +> **v1.90.0+:** `glab auth login` supports a more complete setup flow: +> - `--ssh-hostname` to explicitly set a different SSH endpoint for self-hosted instances +> - `--web` to skip the login-type prompt and go straight to browser/OAuth auth +> - `--container-registry-domains` to preconfigure registry / dependency-proxy domains during login > > Example: API hostname `gitlab.company.com`, SSH hostname `ssh.company.com` +### v1.90.0 Login Flag Examples + +```bash +# Self-managed GitLab with separate API and SSH endpoints +glab auth login \ + --hostname gitlab.company.com \ + --ssh-hostname ssh.company.com + +# Skip prompts and go straight to browser/OAuth auth +glab auth login --hostname gitlab.com --web + +# Preconfigure multiple registry / dependency proxy domains during login +glab auth login \ + --hostname gitlab.com \ + --web \ + --container-registry-domains "registry.gitlab.com,gitlab.com" +``` + +**CI auto-login (GA in v1.90.0):** when enabled, token environment variables such as `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` still take precedence over stored credentials and `CI_JOB_TOKEN`. + ### Switching accounts/instances 1. **Logout from current:** diff --git a/glab-auth/references/commands.md b/glab-auth/references/commands.md index 5668b63..bbbbc6a 100644 --- a/glab-auth/references/commands.md +++ b/glab-auth/references/commands.md @@ -7,14 +7,21 @@ Source: ## login ``` -Authenticate with a GitLab instance. - You can pass in a token on standard input by using `--stdin`. - The minimum required scopes for the token are: `api`, `write_repository`. - Configuration and credentials are stored in the global configuration file (default `~/.config/glab-cli/config.yml`) +Authenticates with a GitLab instance. - When running in interactive mode inside a Git repository, `glab` will automatically detect - GitLab instances from your Git remotes and present them as options, saving you from having to - manually type the hostname. + Stores your credentials in the global configuration file + (default `~/.config/glab-cli/config.yml`). + To store your token in your operating system's keyring instead, use `--use-keyring`. + After authentication, all `glab` commands use the stored credentials. + + If `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` are set, + they take precedence over the stored credentials. + When CI auto-login is enabled, these variables also override `CI_JOB_TOKEN`. + + To pass a token on standard input, use `--stdin`. + + In interactive mode, `glab` detects GitLab instances from your Git remotes + and lists them as options, so you do not have to type the hostname manually. USAGE @@ -25,34 +32,40 @@ Authenticate with a GitLab instance. # Start interactive setup # (If in a Git repository, glab will detect and suggest GitLab instances from remotes) - $ glab auth login + glab auth login # Authenticate against `gitlab.com` by reading the token from a file - $ glab auth login --stdin < myaccesstoken.txt + glab auth login --stdin < myaccesstoken.txt # Authenticate with GitLab Self-Managed or GitLab Dedicated - $ glab auth login --hostname salsa.debian.org + glab auth login --hostname salsa.debian.org # Non-interactive setup - $ glab auth login --hostname gitlab.example.org --token glpat-xxx --api-host gitlab.example.org:3443 --api-prot… + glab auth login --hostname gitlab.example.org --token glpat-xxx --api-host gitlab.example.org:3443 --api-protoc… # Non-interactive setup reading token from a file - $ glab auth login --hostname gitlab.example.org --api-host gitlab.example.org:3443 --api-protocol https --git-p… + glab auth login --hostname gitlab.example.org --api-host gitlab.example.org:3443 --api-protocol https --git-pro… + + # Semi-interactive OAuth login, skipping all prompts except browser auth + glab auth login --hostname gitlab.com --web --git-protocol ssh --container-registry-domains "gitlab.com,gitlab.… # Non-interactive CI/CD setup - $ glab auth login --hostname $CI_SERVER_HOST --job-token $CI_JOB_TOKEN + glab auth login --hostname $CI_SERVER_HOST --job-token $CI_JOB_TOKEN FLAGS - -a --api-host Api host url. - -p --api-protocol Api protocol: https, http - -g --git-protocol Git protocol: ssh, https, http - -h --help Show help for this command. - --hostname The hostname of the GitLab instance to authenticate with. - -j --job-token Ci job token. - --stdin Read token from standard input. - -t --token Your GitLab access token. - --use-keyring Store token in your operating system's keyring. + -a --api-host Api host url. + -p --api-protocol Api protocol: https, http + --container-registry-domains Container registry and image dependency proxy domains (comma-separated). + -g --git-protocol Git protocol: ssh, https, http + -h --help Show help for this command. + --hostname The hostname of the GitLab instance to authenticate with. + -j --job-token Ci job token. + --ssh-hostname Ssh hostname for instances with a different SSH endpoint. + --stdin Read token from standard input. + -t --token Your GitLab access token. + --use-keyring Store token in your operating system's keyring. + --web Skip the login type prompt and use web/OAuth login. ``` ## logout diff --git a/glab-mr/SKILL.md b/glab-mr/SKILL.md index 8667cca..5111bf9 100644 --- a/glab-mr/SKILL.md +++ b/glab-mr/SKILL.md @@ -32,6 +32,9 @@ glab mr merge 123 --when-pipeline-succeeds --remove-source-branch **From current branch:** ```bash glab mr create --fill --label bugfix --assignee @reviewer + +# Create now, merge automatically when checks pass (v1.90.0+) +glab mr create --fill --auto-merge ``` **From issue:** @@ -61,11 +64,18 @@ glab mr create --draft --title "WIP: Feature X" ```bash glab mr note 123 -m "Looks good, one question about the cache logic" - # Resolve a discussion thread while adding a note (v1.88.0+) - glab mr note 123 --resolve -m "Fixed, addressed in latest commit." + # List discussion threads on the MR (v1.90.0+, experimental) + glab mr note list 123 - # Reopen a resolved thread - glab mr note 123 --unresolve + # Resolve a discussion by note/discussion ID (v1.90.0+, experimental) + glab mr note resolve 3107030349 123 + + # Reopen a resolved discussion (v1.90.0+, experimental) + glab mr note reopen 3107030349 123 + + # If you need to change thread state in v1.90.0, use the explicit subcommands + glab mr note resolve 123 + glab mr note reopen 123 ``` 4. **Approve:** @@ -133,7 +143,7 @@ glab mr merge 123 **CI/CD integration:** - See `glab-ci` for pipeline status before merging -- Use `glab mr merge --when-pipeline-succeeds` for auto-merge +- Use `glab mr create --auto-merge` to request auto-merge up front, or `glab mr merge --when-pipeline-succeeds` on an existing MR **Automation:** - Script: `scripts/mr-review-workflow.sh` for automated review + test workflow @@ -326,6 +336,12 @@ glab mr list \ --created-after 2026-01-01 ``` +## v1.90.0 Updates + +- `glab mr create` adds `--auto-merge` to set merge-when-ready during MR creation +- `glab mr note` adds `list`, `resolve`, and `reopen` subcommands for discussion management (EXPERIMENTAL) +- For discussion state changes in v1.90.0, prefer `glab mr note resolve` / `glab mr note reopen`; do not imply `--resolve` / `--unresolve` can be combined with `-m` + ## v1.89.0 Updates > **v1.89.0+:** `glab mr approvers` supports `--output json` / `-F json` for structured output, ideal for agent automation. @@ -338,7 +354,7 @@ glab mr approvers 123 -F json ## v1.88.0 Changes -- `glab mr note`: Added `--resolve ` and `--unresolve ` flags to resolve/reopen discussion threads while adding a note +- `glab mr note`: Added `--resolve ` and `--unresolve ` flags for discussion state changes; in v1.90.0 docs should prefer the explicit `note resolve` / `note reopen` subcommands for user-facing guidance - `glab mr view`: Added `--resolved` and `--unresolved` flags to filter displayed discussion threads by resolution status ## Command reference @@ -355,7 +371,7 @@ For complete command documentation and all flags, see [references/commands.md](r - `for` - Create MR for an issue - `list` - List merge requests - `merge` - Merge/accept MR -- `note` - Add comment to MR +- `note` - Add comment to MR; includes `list`, `resolve`, and `reopen` subcommands in v1.90.0 - `rebase` - Rebase source branch - `reopen` - Reopen merge request - `revoke` - Revoke approval diff --git a/glab-mr/references/commands.md b/glab-mr/references/commands.md index 31d3b6c..929964d 100644 --- a/glab-mr/references/commands.md +++ b/glab-mr/references/commands.md @@ -27,20 +27,20 @@ ``` - Create, view, and manage merge requests. - - USAGE - - glab mr [command] [--flags] - - EXAMPLES - - $ glab mr create --fill --label bugfix - $ glab mr merge 123 - $ glab mr note -m "needs to do X before it can be merged" branch-foo - - COMMANDS - + Create, view, and manage merge requests. + + USAGE + + glab mr [command] [--flags] + + EXAMPLES + + $ glab mr create --fill --label bugfix + $ glab mr merge 123 + $ glab mr note -m "needs to do X before it can be merged" branch-foo + + COMMANDS + approve { | } [--flags] Approve merge requests. approvers [ | ] [--flags] List eligible approvers for merge requests in any state. checkout [ | | ] [--flags] Check out an open merge request. @@ -61,9 +61,9 @@ unsubscribe [ | ] Unsubscribe from a merge request. update [ | ] [--flags] Update a merge request. view { | } [--flags] Display the title, body, and other information about a merge request. - - FLAGS - + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -72,24 +72,24 @@ ``` - Approve merge requests. - - USAGE - - glab mr approve { | } [--flags] - - EXAMPLES - - $ glab mr approve 235 - $ glab mr approve 123 345 - $ glab mr approve branch-1 - $ glab mr approve branch-2 branch-3 - - # Finds open merge request from current branch and approves it - $ glab mr approve - - FLAGS - + Approve merge requests. + + USAGE + + glab mr approve { | } [--flags] + + EXAMPLES + + $ glab mr approve 235 + $ glab mr approve 123 345 + $ glab mr approve branch-1 + $ glab mr approve branch-2 branch-3 + + # Finds open merge request from current branch and approves it + $ glab mr approve + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. -s --sha Sha, which must match the SHA of the HEAD commit of the merge request. @@ -99,14 +99,14 @@ ``` - List eligible approvers for merge requests in any state. - - USAGE - - glab mr approvers [ | ] [--flags] - - FLAGS - + List eligible approvers for merge requests in any state. + + USAGE + + glab mr approvers [ | ] [--flags] + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -115,25 +115,25 @@ ``` - Check out an open merge request. - - USAGE - - glab mr checkout [ | | ] [--flags] - - EXAMPLES - - $ glab mr checkout 1 - $ glab mr checkout branch - $ glab mr checkout 12 --branch todo-fix - $ glab mr checkout new-feature --set-upstream-to=upstream/main - $ glab mr checkout https://gitlab.com/gitlab-org/cli/-/merge_requests/1234 - - # Uses the checked-out branch - $ glab mr checkout - - FLAGS - + Check out an open merge request. + + USAGE + + glab mr checkout [ | | ] [--flags] + + EXAMPLES + + $ glab mr checkout 1 + $ glab mr checkout branch + $ glab mr checkout 12 --branch todo-fix + $ glab mr checkout new-feature --set-upstream-to=upstream/main + $ glab mr checkout https://gitlab.com/gitlab-org/cli/-/merge_requests/1234 + + # Uses the checked-out branch + $ glab mr checkout + + FLAGS + -b --branch Check out merge request with name . -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. @@ -144,28 +144,28 @@ ``` - Close a merge request. - - USAGE - - glab mr close [ | ] [--flags] - - EXAMPLES - - $ glab mr close 1 - - # Close multiple merge requests at once - $ glab mr close 1 2 3 4 - - # Use the checked-out branch - $ glab mr close - - $ glab mr close branch - $ glab mr close username:branch - $ glab mr close branch -R another/repo - - FLAGS - + Close a merge request. + + USAGE + + glab mr close [ | ] [--flags] + + EXAMPLES + + $ glab mr close 1 + + # Close multiple merge requests at once + $ glab mr close 1 2 3 4 + + # Use the checked-out branch + $ glab mr close + + $ glab mr close branch + $ glab mr close username:branch + $ glab mr close branch -R another/repo + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -174,24 +174,25 @@ ``` - Create a new merge request. - - USAGE - - glab mr create [--flags] - - EXAMPLES - - $ glab mr new - $ glab mr create -a username -t "fix annoying bug" - $ glab mr create -f --draft --label RFC - $ glab mr create --fill --web - $ glab mr create --fill --fill-commit-body --yes - - FLAGS - + Create a new merge request. + + USAGE + + glab mr create [--flags] + + EXAMPLES + + $ glab mr new + $ glab mr create -a username -t "fix annoying bug" + $ glab mr create -f --draft --label RFC + $ glab mr create --fill --web + $ glab mr create --fill --fill-commit-body --yes + + FLAGS + --allow-collaboration Allow commits from other members. -a --assignee Assign merge request to people by their `usernames`. Multiple usernames can be comma-separated or specified by repeating the flag. + --auto-merge Set the merge request to merge when all merge checks pass. --copy-issue-labels Copy labels from issue to the merge request. Used with --related-issue. --create-source-branch Create a source branch if it does not exist. -d --description Supply a description for the merge request. Set to "-" to open an editor. @@ -223,27 +224,27 @@ ``` - Delete a merge request. - - USAGE - - glab mr delete [ | ] [--flags] - - EXAMPLES - - $ glab mr delete 123 - - # Delete multiple merge requests by ID and branch name - $ glab mr delete 123 branch-name 789 - - # Delete merge requests !1, !2, !3, !4, !5 - $ glab mr delete 1,2,branch-related-to-mr-3,4,5 - - $ glab mr del 123 - $ glab mr delete branch - - FLAGS - + Delete a merge request. + + USAGE + + glab mr delete [ | ] [--flags] + + EXAMPLES + + $ glab mr delete 123 + + # Delete multiple merge requests by ID and branch name + $ glab mr delete 123 branch-name 789 + + # Delete merge requests !1, !2, !3, !4, !5 + $ glab mr delete 1,2,branch-related-to-mr-3,4,5 + + $ glab mr del 123 + $ glab mr delete branch + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -252,24 +253,24 @@ ``` - View changes in a merge request. - - USAGE - - glab mr diff [ | ] [--flags] - - EXAMPLES - - $ glab mr diff 123 - $ glab mr diff branch - - # Get merge request from current branch - $ glab mr diff - - $ glab mr diff 123 --color=never - - FLAGS - + View changes in a merge request. + + USAGE + + glab mr diff [ | ] [--flags] + + EXAMPLES + + $ glab mr diff 123 + $ glab mr diff branch + + # Get merge request from current branch + $ glab mr diff + + $ glab mr diff 123 --color=never + + FLAGS + --color Use color in diff output: always, never, auto. (auto) -h --help Show help for this command. --raw Use raw diff format that can be piped to commands @@ -281,25 +282,25 @@ ``` Command "for" is deprecated, use `glab mr create --related-issue ` - Create a new merge request for an issue. - - USAGE - - glab mr for [--flags] - - EXAMPLES - - # Create merge request for issue 34 - $ glab mr for 34 - - # Create merge request for issue 34 and mark as work in progress - $ glab mr for 34 --wip - - $ glab mr new-for 34 - $ glab mr create-for 34 - - FLAGS - + Create a new merge request for an issue. + + USAGE + + glab mr for [--flags] + + EXAMPLES + + # Create merge request for issue 34 + $ glab mr for 34 + + # Create merge request for issue 34 and mark as work in progress + $ glab mr for 34 --wip + + $ glab mr new-for 34 + $ glab mr create-for 34 + + FLAGS + --allow-collaboration Allow commits from other members. -a --assignee Assign merge request to people by their IDs. Multiple values should be comma-separated. --draft Mark merge request as a draft. (true) @@ -317,23 +318,23 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Get issues related to a particular merge request. - - USAGE - - glab mr issues [ | ] [--flags] - - EXAMPLES - - # List issues for merge request 46 - $ glab mr issues 46 - $ glab mr issues branch - - # Use the checked-out branch - $ glab mr issues - - FLAGS - + Get issues related to a particular merge request. + + USAGE + + glab mr issues [ | ] [--flags] + + EXAMPLES + + # List issues for merge request 46 + $ glab mr issues 46 + $ glab mr issues branch + + # Use the checked-out branch + $ glab mr issues + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -342,29 +343,29 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - List merge requests. - - USAGE - - glab mr list [--flags] - - EXAMPLES - - $ glab mr list --all - $ glab mr ls -a - $ glab mr list --assignee=@me - $ glab mr list --reviewer=@me - $ glab mr list --source-branch=new-feature - $ glab mr list --target-branch=main - $ glab mr list --search "this adds feature X" - $ glab mr list --label needs-review - $ glab mr list --not-label waiting-maintainer-feedback,subsystem-x - $ glab mr list -M --per-page 10 - $ glab mr list --draft - $ glab mr list --not-draft - - FLAGS - + List merge requests. + + USAGE + + glab mr list [--flags] + + EXAMPLES + + $ glab mr list --all + $ glab mr ls -a + $ glab mr list --assignee=@me + $ glab mr list --reviewer=@me + $ glab mr list --source-branch=new-feature + $ glab mr list --target-branch=main + $ glab mr list --search "this adds feature X" + $ glab mr list --label needs-review + $ glab mr list --not-label waiting-maintainer-feedback,subsystem-x + $ glab mr list -M --per-page 10 + $ glab mr list --draft + $ glab mr list --not-draft + + FLAGS + -A --all Get all merge requests. -a --assignee Get only merge requests assigned to users. Multiple users can be comma-separated or specified by repeating the flag. --author Filter merge request by author . @@ -395,23 +396,23 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Merge or accept a merge request. - - USAGE - - glab mr merge { | } [--flags] - - EXAMPLES - - # Merge a merge request - $ glab mr merge 235 - $ glab mr accept 235 - - # Finds open merge request from current branch - $ glab mr merge - - FLAGS - + Merge or accept a merge request. + + USAGE + + glab mr merge { | } [--flags] + + EXAMPLES + + # Merge a merge request + $ glab mr merge 235 + $ glab mr accept 235 + + # Finds open merge request from current branch + $ glab mr merge + + FLAGS + --auto-merge Set auto-merge. (true) -h --help Show help for this command. -m --message Custom merge commit message. @@ -428,56 +429,68 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Add a comment or note to a merge request. - - USAGE - - glab mr note [ | ] [--flags] - - EXAMPLES - - # Add a comment to merge request with ID 123 - $ glab mr note 123 -m "Looks good to me!" - - # Add a comment to the merge request for the current branch - $ glab mr note -m "LGTM" - - # Open your editor to compose a multi-line comment - $ glab mr note 123 - - FLAGS - - -h --help Show help for this command. - -m --message Comment or note message. - -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. - --unique Don't create a comment or note if it already exists. + Manage comments and discussions on a merge request. + + USAGE + + glab mr note [command] [ | ] [--flags] + + EXAMPLES + + # Add a comment to merge request with ID 123 + glab mr note 123 -m "Looks good to me!" + + # Add a comment to the merge request for the current branch + glab mr note -m "LGTM" + + # Open your editor to compose a multi-line comment + glab mr note 123 + + # Resolve a discussion by note ID + glab mr note 123 --resolve 3107030349 + + # Unresolve a discussion by note ID + glab mr note 123 --unresolve 3107030349 + + COMMANDS + + list [ | ] [--flags] List merge request discussions. (EXPERIMENTAL) + reopen [ | ] Reopen a discussion on a merge request. (EXPERIMENTAL) + resolve [ | ] Resolve a discussion on a merge request. (EXPERIMENTAL) + + FLAGS + + -h --help Show help for this command. + -m --message Comment or note message. + -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. + --unique Don't create a comment or note if it already exists. ``` ## mr rebase ``` - If you don't have permission to push to the merge request's source branch, you'll get a 403 Forbidden response. - - - USAGE - - glab mr rebase [ | ] [--flags] - - EXAMPLES - - # Rebase merge request 123 - $ glab mr rebase 123 - - # Rebase current branch - $ glab mr rebase - - # Rebase merge request from branch - $ glab mr rebase branch - $ glab mr rebase branch --skip-ci - - FLAGS - + If you don't have permission to push to the merge request's source branch, you'll get a 403 Forbidden response. + + + USAGE + + glab mr rebase [ | ] [--flags] + + EXAMPLES + + # Rebase merge request 123 + $ glab mr rebase 123 + + # Rebase current branch + $ glab mr rebase + + # Rebase merge request from branch + $ glab mr rebase branch + $ glab mr rebase branch --skip-ci + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. --skip-ci Rebase merge request while skipping CI/CD pipeline. @@ -487,25 +500,25 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Reopen a merge request. - - USAGE - - glab mr reopen [... | ...] [--flags] - - EXAMPLES - - # Reopen merge request 123 - $ glab mr reopen 123 - - # Reopen merge requests 123, 456, and 789 - $ glab mr reopen 123 456 789 - - # Reopen merge requests from branches branch-1 and branch-2 - $ glab mr reopen branch-1 branch-2 - - FLAGS - + Reopen a merge request. + + USAGE + + glab mr reopen [... | ...] [--flags] + + EXAMPLES + + # Reopen merge request 123 + $ glab mr reopen 123 + + # Reopen merge requests 123, 456, and 789 + $ glab mr reopen 123 456 789 + + # Reopen merge requests from branches branch-1 and branch-2 + $ glab mr reopen branch-1 branch-2 + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -514,26 +527,26 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Revoke approval on a merge request. - - USAGE - - glab mr revoke [ | ] [--flags] - - EXAMPLES - - # Revoke approval on a merge request - $ glab mr revoke 123 - $ glab mr unapprove 123 - $ glab mr revoke branch - - # Revoke approval on the currently checked out branch - $ glab mr revoke - # Revoke approval on merge request 123 on branch 456 - $ glab mr revoke 123 branch 456 - - FLAGS - + Revoke approval on a merge request. + + USAGE + + glab mr revoke [ | ] [--flags] + + EXAMPLES + + # Revoke approval on a merge request + $ glab mr revoke 123 + $ glab mr unapprove 123 + $ glab mr revoke branch + + # Revoke approval on the currently checked out branch + $ glab mr revoke + # Revoke approval on merge request 123 on branch 456 + $ glab mr revoke 123 branch 456 + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -542,24 +555,24 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Subscribe to a merge request. - - USAGE - - glab mr subscribe [ | ] [--flags] - - EXAMPLES - - # Subscribe to a merge request - $ glab mr subscribe 123 - $ glab mr sub 123 - $ glab mr subscribe branch - - # Subscribe to multiple merge requests - $ glab mr subscribe 123 branch - - FLAGS - + Subscribe to a merge request. + + USAGE + + glab mr subscribe [ | ] [--flags] + + EXAMPLES + + # Subscribe to a merge request + $ glab mr subscribe 123 + $ glab mr sub 123 + $ glab mr subscribe branch + + # Subscribe to multiple merge requests + $ glab mr subscribe 123 branch + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -568,14 +581,14 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Add a to-do item to merge request. - - USAGE - - glab mr todo [ | ] [--flags] - - FLAGS - + Add a to-do item to merge request. + + USAGE + + glab mr todo [ | ] [--flags] + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -584,24 +597,24 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Unsubscribe from a merge request. - - USAGE - - glab mr unsubscribe [ | ] [--flags] - - EXAMPLES - - # Unsubscribe from a merge request - $ glab mr unsubscribe 123 - $ glab mr unsub 123 - $ glab mr unsubscribe branch - - # Unsubscribe from multiple merge requests - $ glab mr unsubscribe 123 branch - - FLAGS - + Unsubscribe from a merge request. + + USAGE + + glab mr unsubscribe [ | ] [--flags] + + EXAMPLES + + # Unsubscribe from a merge request + $ glab mr unsubscribe 123 + $ glab mr unsub 123 + $ glab mr unsubscribe branch + + # Unsubscribe from multiple merge requests + $ glab mr unsubscribe 123 branch + + FLAGS + -h --help Show help for this command. -R --repo Select another repository. Can use either `OWNER/REPO` or `GROUP/NAMESPACE/REPO` format. Also accepts full URL or Git URL. ``` @@ -610,28 +623,28 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Update a merge request. - - USAGE - - glab mr update [ | ] [--flags] - - EXAMPLES - - # Mark a merge request as ready - $ glab mr update 23 --ready - - # Mark a merge request as draft - $ glab mr update 23 --draft - - # Updates the merge request for the current branch - $ glab mr update --draft - - # Update merge request with commit information - $ glab mr update 23 --fill --fill-commit-body --yes - - FLAGS - + Update a merge request. + + USAGE + + glab mr update [ | ] [--flags] + + EXAMPLES + + # Mark a merge request as ready + $ glab mr update 23 --ready + + # Mark a merge request as draft + $ glab mr update 23 --draft + + # Updates the merge request for the current branch + $ glab mr update --draft + + # Update merge request with commit information + $ glab mr update 23 --fill --fill-commit-body --yes + + FLAGS + -a --assignee Assign users via username. Prefix with '!' or '-' to remove from existing assignees, '+' to add. Otherwise, replace existing assignees with given users. Multiple usernames can be comma-separated or specified by repeating the flag. -d --description Merge request description. Set to "-" to open an editor. --draft Mark merge request as a draft. @@ -659,14 +672,14 @@ Command "for" is deprecated, use `glab mr create --related-issue ` ``` - Display the title, body, and other information about a merge request. - - USAGE - - glab mr view { | } [--flags] - - FLAGS - + Display the title, body, and other information about a merge request. + + USAGE + + glab mr view { | } [--flags] + + FLAGS + -c --comments Show merge request comments and activities. -h --help Show help for this command. -F --output Format output as: text, json. (text) diff --git a/glab-runner-controller/SKILL.md b/glab-runner-controller/SKILL.md index 3ee9e08..51a1480 100644 --- a/glab-runner-controller/SKILL.md +++ b/glab-runner-controller/SKILL.md @@ -1,6 +1,6 @@ --- name: glab-runner-controller -description: Manage GitLab runner controllers and authentication tokens. Create, update, delete controllers; generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, experimental runner, admin runner. +description: Manage GitLab runner controllers and authentication tokens. Create, inspect, update, delete controllers; manage scopes; and generate, rotate, and revoke tokens. Admin-only experimental feature for managing runner controller lifecycle. Triggers on runner controller, controller token, controller scope, experimental runner, admin runner. --- # glab-runner-controller @@ -19,7 +19,9 @@ Manage GitLab runner controllers and their authentication tokens. Runner controllers manage the orchestration of GitLab Runners in your infrastructure. This skill provides commands to: - Create and configure runner controllers -- Manage controller lifecycle (list, update, delete) +- Inspect controller details and connection status +- Manage controller lifecycle (list, get, update, delete) +- Manage controller scopes (instance-level or runner-level) - Generate and rotate authentication tokens - Revoke compromised tokens @@ -54,6 +56,11 @@ glab runner-controller list --page 2 --per-page 50 # Output as JSON glab runner-controller list --output json + +# Get one controller with status details (v1.90.0+) +glab runner-controller get 42 + +glab runner-controller get 42 --output json ``` ### Update Controller @@ -79,6 +86,46 @@ glab runner-controller delete 42 glab runner-controller delete 42 --force ``` +## Scope Management (v1.90.0+) + +Runner controller scopes determine what the controller is allowed to evaluate. + +### List Scopes + +```bash +# List all scopes for controller 42 +glab runner-controller scope list 42 + +# JSON output +glab runner-controller scope list 42 --output json +``` + +### Add Scopes + +```bash +# Allow the controller to evaluate all instance runners +glab runner-controller scope create 42 --instance + +# Allow the controller to evaluate a specific runner +glab runner-controller scope create 42 --runner 5 + +# Add multiple runner scopes +glab runner-controller scope create 42 --runner 5 --runner 10 +glab runner-controller scope create 42 --runner 5,10 +``` + +### Remove Scopes + +```bash +# Remove the instance-level scope +glab runner-controller scope delete 42 --instance + +# Remove a specific runner-level scope +glab runner-controller scope delete 42 --runner 5 --force +``` + +> **Note:** Older docs/examples may refer to `glab runner-controller runner ...` subcommands. In v1.90.0, the user-facing surface is `glab runner-controller scope ...` plus `glab runner-controller get`. + ## Token Management Workflows ### Token Lifecycle @@ -193,57 +240,16 @@ Do you need the controller active? - Use `--force` to override (⚠️ destructive) **Experimental feature not available:** -- Verify glab version: `glab version` (requires v1.83.0+) +- Verify glab version: `glab version` (requires a recent glab build) - Check if feature flag is enabled on GitLab instance - Confirm GitLab instance version supports runner controllers -**Pagination not working:** -- Default page size is 30 -- Use `--per-page` to adjust (max varies by instance) -- Use `--page` to navigate through results - -## v1.87.0 Changes: Runner Scope Subcommands - -As of v1.87.0, runner controllers support a `runner` scope for managing the runners associated with a controller. - -### List Runners in Scope - -```bash -# List all runners managed by controller 42 -glab runner-controller runner list 42 - -# Output as JSON -glab runner-controller runner list 42 --output json - -# Paginate -glab runner-controller runner list 42 --page 2 --per-page 50 -``` - -### Add Runner to Scope - -```bash -# Add runner to controller 42's scope -glab runner-controller runner create 42 --runner-id -``` - -### Remove Runner from Scope - -```bash -# Remove runner from controller 42's scope (with confirmation) -glab runner-controller runner delete 42 - -# Remove without confirmation -glab runner-controller runner delete 42 --force -``` - -**Use case:** Runner scope management lets you explicitly define which runners are orchestrated by a given controller, giving you fine-grained control over runner assignment in multi-controller environments. - ## Related Skills **CI/CD & Runners:** - `glab-ci` - View and manage CI/CD pipelines and jobs - `glab-job` - Retry, cancel, view logs for individual jobs -- `glab-runner` - Manage individual runners (list, pause, delete) — added v1.87.0 +- `glab-runner` - Manage individual runners (list, assign, jobs, managers, update, delete) **Repository Management:** - `glab-repo` - Manage repositories (runner controllers are instance-level) @@ -251,6 +257,12 @@ glab runner-controller runner delete 42 --force **Authentication:** - `glab-auth` - Login and authentication management +## v1.90.0 Changes + +- Added `glab runner-controller get ` — inspect one controller and its connection status +- Reworked scope management under `glab runner-controller scope list|create|delete` +- Older `glab runner-controller runner ...` scope examples should be treated as pre-v1.90.0 guidance + ## Command Reference For complete command syntax and all available flags, see: diff --git a/glab-runner-controller/references/commands.md b/glab-runner-controller/references/commands.md index ec316e5..f8f59b1 100644 --- a/glab-runner-controller/references/commands.md +++ b/glab-runner-controller/references/commands.md @@ -7,9 +7,15 @@ Complete command syntax and help output for all runner-controller commands. - [glab runner-controller](#glab-runner-controller) - [Controller Management](#controller-management) - [create](#create) + - [get](#get) - [list](#list) - [update](#update) - [delete](#delete) +- [Scope Management](#scope-management) + - [scope](#scope) + - [scope list](#scope-list) + - [scope create](#scope-create) + - [scope delete](#scope-delete) - [Token Management](#token-management) - [token create](#token-create) - [token list](#token-list) @@ -21,13 +27,12 @@ Complete command syntax and help output for all runner-controller commands. ## glab runner-controller ``` -Manages runner controllers. This is an admin-only feature. +Manages runner controllers. This is an administrator-only feature. - This feature is experimental. It might be broken or removed without any prior notice. - Read more about what experimental features mean at - https://docs.gitlab.com/policy/development_stages_support/ - - Use experimental features at your own risk. + This feature is an experiment and is not ready for production use. + It might be unstable or removed at any time. + For more information, see + https://docs.gitlab.com/policy/development_stages_support/. USAGE @@ -37,7 +42,9 @@ COMMANDS create [--flags] Create a runner controller. (EXPERIMENTAL) delete [--flags] Delete a runner controller. (EXPERIMENTAL) + get [--flags] Get details of a runner controller. (EXPERIMENTAL) list [--flags] List runner controllers. (EXPERIMENTAL) + scope [command] [--flags] Manage runner controller scopes. (EXPERIMENTAL) token [command] [--flags] Manage runner controller tokens. (EXPERIMENTAL) update [--flags] Update a runner controller. (EXPERIMENTAL) @@ -78,6 +85,35 @@ FLAGS --state State of the runner controller: disabled, enabled, dry_run. ``` +### get + +``` +Retrieves details of a single runner controller, including its + connection status. This is an administrator-only feature. + + This feature is an experiment and is not ready for production use. + It might be unstable or removed at any time. + For more information, see + https://docs.gitlab.com/policy/development_stages_support/. + +USAGE + + glab runner-controller get [--flags] + +EXAMPLES + + # Get runner controller with ID 42 + glab runner-controller get 42 + + # Get runner controller as JSON + glab runner-controller get 42 --output json + +FLAGS + + -h --help Show help for this command. + -F --output Format output as: text, json. (text) +``` + ### list ``` @@ -156,6 +192,146 @@ FLAGS --- +## Scope Management + +### scope + +``` +Manages runner controller scopes. This is an administrator-only feature. + + This feature is an experiment and is not ready for production use. + It might be unstable or removed at any time. + For more information, see + https://docs.gitlab.com/policy/development_stages_support/. + +USAGE + + glab runner-controller scope [command] [--flags] + +COMMANDS + + create [--flags] Create a scope for a runner controller. (EXPERIMENTAL) + delete [--flags] Delete a scope from a runner controller. (EXPERIMENTAL) + list [--flags] List scopes for a runner controller. (EXPERIMENTAL) + +FLAGS + + -h --help Show help for this command. +``` + +### scope list + +``` +List scopes for a runner controller. (EXPERIMENTAL) + +USAGE + + glab runner-controller scope list [--flags] + +EXAMPLES + + # List all scopes for runner controller 42 + glab runner-controller scope list 42 + + # List scopes as JSON + glab runner-controller scope list 42 --output json + +FLAGS + + -h --help Show help for this command. + -F --output Format output as: text, json. (text) +``` + +### scope create + +``` +Creates a scope for a runner controller. This is an administrator-only feature. + + Use one of the following flags to specify the scope type: + + - --instance: Add an instance-level scope, allowing the runner controller + to evaluate jobs for all runners in the GitLab instance. + - --runner : Add a runner-level scope, allowing the runner controller + to evaluate jobs for a specific instance-level runner. Multiple IDs can + be comma-separated or specified by repeating the flag. + + This feature is an experiment and is not ready for production use. + It might be unstable or removed at any time. + For more information, see + https://docs.gitlab.com/policy/development_stages_support/. + +USAGE + + glab runner-controller scope create [--flags] + +EXAMPLES + + # Add an instance-level scope to runner controller 42 + glab runner-controller scope create 42 --instance + + # Add a runner-level scope for runner 5 to runner controller 42 + glab runner-controller scope create 42 --runner 5 + + # Add runner-level scopes for multiple runners + glab runner-controller scope create 42 --runner 5 --runner 10 + glab runner-controller scope create 42 --runner 5,10 + + # Add a runner-level scope and output as JSON + glab runner-controller scope create 42 --runner 5 --output json + +FLAGS + + -h --help Show help for this command. + --instance Add an instance-level scope. + -F --output Format output as: text, json. (text) + --runner Add a runner-level scope for the specified runner ID. Multiple IDs can be comma-separated or specified by repeating the flag. +``` + +### scope delete + +``` +Deletes a scope from a runner controller. This is an administrator-only feature. + + Use one of the following flags to specify the scope type: + + - --instance: Remove an instance-level scope from the runner controller. + - --runner : Remove a runner-level scope for a specific runner. Multiple IDs + can be comma-separated or specified by repeating the flag. + + This feature is an experiment and is not ready for production use. + It might be unstable or removed at any time. + For more information, see + https://docs.gitlab.com/policy/development_stages_support/. + +USAGE + + glab runner-controller scope delete [--flags] + +EXAMPLES + + # Remove an instance-level scope from runner controller 42 (with confirmation) + glab runner-controller scope delete 42 --instance + + # Remove an instance-level scope without confirmation + glab runner-controller scope delete 42 --instance --force + + # Remove a runner-level scope for runner 5 from runner controller 42 + glab runner-controller scope delete 42 --runner 5 --force + + # Remove runner-level scopes for multiple runners + glab runner-controller scope delete 42 --runner 5 --runner 10 --force + glab runner-controller scope delete 42 --runner 5,10 --force + +FLAGS + + -f --force Skip confirmation prompt. + -h --help Show help for this command. + --instance Remove an instance-level scope. + --runner Remove a runner-level scope for the specified runner ID. Multiple IDs can be comma-separated or specified by repeating the flag. +``` + +--- + ## Token Management ### glab runner-controller token diff --git a/glab-runner/SKILL.md b/glab-runner/SKILL.md index b72ed2b..963238a 100644 --- a/glab-runner/SKILL.md +++ b/glab-runner/SKILL.md @@ -1,6 +1,6 @@ --- name: glab-runner -description: Manage GitLab CI/CD runners — list, assign, unassign, pause, and delete runners at project, group, or instance level. Use when viewing runner status, assigning runners to projects, temporarily pausing a runner, or removing a decommissioned runner. Triggers on runner, glab runner, list runners, assign runner, unassign runner, pause runner, delete runner, CI runner. +description: Manage GitLab CI/CD runners — list, assign, unassign, inspect recent jobs and managers, pause/unpause via update, and delete runners at project, group, or instance level. Use when viewing runner status, assigning runners to projects, checking what jobs a runner handled, seeing manager processes, temporarily pausing a runner, or removing a decommissioned runner. Triggers on runner, glab runner, list runners, assign runner, unassign runner, runner jobs, runner managers, pause runner, unpause runner, delete runner, CI runner. --- # glab runner @@ -15,8 +15,8 @@ Manage GitLab CI/CD runners from the command line. # List runners for current project glab runner list -# Pause a runner -glab runner pause +# Pause a runner (v1.90.0+: via update) +glab runner update --pause # Delete a runner glab runner delete @@ -51,20 +51,23 @@ import sys, json runners = json.load(sys.stdin) paused = [r for r in runners if r.get('paused')] for r in paused: - print(f\"{r['id']}: {r.get('description','(no description)')} — {r.get('status')}\") + print(f"{r['id']}: {r.get('description','(no description)')} — {r.get('status')}") " ``` -### Pause a Runner +### Pause or Resume a Runner (v1.90.0+) Pausing a runner prevents it from picking up new jobs without removing it. ```bash # Pause runner 123 -glab runner pause 123 +glab runner update 123 --pause + +# Resume a paused runner +glab runner update 123 --unpause # Pause in a specific project context -glab runner pause 123 --repo owner/project +glab runner update 123 --pause -R owner/project ``` **When to pause:** @@ -73,6 +76,35 @@ glab runner pause 123 --repo owner/project - Temporarily reducing runner capacity - Before decommissioning (verify no jobs are running first) +> **Note:** Older docs/examples may mention `glab runner pause`, but in v1.90.0 the supported command surface uses `glab runner update --pause` / `--unpause`. + +### Inspect Jobs Processed by a Runner (v1.90.0+) + +```bash +# List recent jobs for runner 9 +glab runner jobs 9 + +# Show only running jobs +glab runner jobs 9 --status running + +# JSON output for automation +glab runner jobs 9 --output json +``` + +Useful for checking whether a runner is currently busy before pausing or deleting it. + +### Inspect Runner Managers (v1.90.0+) + +```bash +# List managers attached to a runner +glab runner managers 9 + +# JSON output +glab runner managers 9 --output json +``` + +Use this when you need to understand which runner manager processes/backends are associated with a runner. + ### Delete a Runner ```bash @@ -94,7 +126,7 @@ glab runner delete 123 --repo owner/project Do you need the runner gone permanently? ├─ No → Pause it (recoverable) └─ Yes → Is it actively running jobs? - ├─ Yes → Pause first, wait for jobs to finish, then delete + ├─ Yes → Check `glab runner jobs `, then pause first and wait for jobs to finish └─ No → Delete with --force ``` @@ -116,9 +148,10 @@ Do you need the runner gone permanently? - Instance-level runner management requires GitLab admin privileges. - Project runners can be managed by project maintainers. -**Runner won't pause:** +**Runner won't pause or unpause:** - Verify runner ID with `glab runner list`. - Check permissions (must be at least Maintainer on the project). +- Use `glab runner update --pause` or `--unpause`. **Runner stuck "online" after pause:** - The runner process is still running on the host — it just won't accept new jobs. @@ -158,6 +191,12 @@ glab runner unassign --repo owner/project - `glab-ci` — View and manage CI/CD pipelines and jobs - `glab-job` — Retry, cancel, trace logs for individual jobs +## v1.90.0 Changes + +- Added `glab runner jobs ` — list jobs processed by a runner +- Added `glab runner managers ` — list runner managers +- Added `glab runner update --pause|--unpause` — pause or resume a runner + ## v1.88.0 Changes - Added `glab runner assign ` — assign a runner to a project @@ -169,11 +208,13 @@ glab runner unassign --repo owner/project glab runner [--flags] Commands: - list Get a list of runners available to the user assign Assign a runner to a project (v1.88.0+) - unassign Unassign a runner from a project (v1.88.0+) - pause Pause a runner delete Delete a runner + jobs List jobs processed by a runner (v1.90.0+) + list Get a list of runners available to the user + managers List runner managers (v1.90.0+) + unassign Unassign a runner from a project (v1.88.0+) + update Update runner settings, including pause/unpause (v1.90.0+) Flags (list): --all List all runners (instance-level, admin only) @@ -182,9 +223,4 @@ Flags (list): --per-page Number of items per page --repo Select a repository -h, --help Show help - -Flags (pause / delete): - --force Skip confirmation prompt (delete only) - --repo Select a repository - -h, --help Show help ```