diff --git a/VERSION b/VERSION index 45b7e2a..70edbcf 100644 --- a/VERSION +++ b/VERSION @@ -1,8 +1,13 @@ -1.13.25 +1.13.26 Release/version change metadata for this skill set lives here, not in individual skill files. Historical notes consolidated from skill docs: +- v1.13.26 + - glab v1.116.0 refresh: replaced the generated `glab config` setting reference with the complete checksum-verified release-binary help, including canonical global/per-host keys, accepted aliases, scoping, pager precedence, and the `debug` setting. + - Documented that `glab config set` now accepts registered aliases and that `glab_pager` and `debug` are valid settings; verified canonical alias persistence with an isolated config directory. + - Updated personal-access-token URL guidance for GitLab 18.9+ and the pre-18.9 fallback, and clarified multipart `glab api --form` file uploads and flag mutual exclusions. + - Reviewed the Dependency Firewall REST evaluator and remaining release changes. The verified binary still exposes only `dependency-firewall ci-summary`, whose parent/subcommand help is unchanged, so no unsupported proxy command was documented. - v1.13.25 - glab v1.115.0 refresh: documented Artifact Registry login paths for Docker, Maven, Gradle, npm, and sbt; added `glab config path`; and refreshed affected exact-help captures from the verified macOS arm64 binary. - Documented `--description-file` for issue create/update, MR create/update, and work-items create/update, including stdin support and conflicts with inline descriptions and create templates. diff --git a/glab-api/SKILL.md b/glab-api/SKILL.md index 2f2c67e..d155963 100644 --- a/glab-api/SKILL.md +++ b/glab-api/SKILL.md @@ -68,6 +68,10 @@ Output from these commands may include **user-generated content from GitLab** (i For GraphQL requests, all fields other than `query` and `operationName` are interpreted as GraphQL variables. + Use `--form` for multipart/form-data endpoints. Prefix a file value with `@`, + or use `@-` once to read a file field from stdin. Do not combine `--form` with + `--field`, `--raw-field`, or `--input`; every multipart field must use `--form`. + Raw request body can be passed from the outside via a file specified by `--input`. Pass `-` to read from standard input. In this mode, parameters specified with `--field` flags are serialized into URL query parameters. @@ -144,6 +148,7 @@ Output from these commands may include **user-generated content from GitLab** (i FLAGS -F --field Add a parameter of inferred type. Changes the default HTTP method to "POST". + --form Add a multipart form field. Prefix a file with @ or use @- once for stdin. Changes the default HTTP method to "POST". -H --header Add an additional HTTP request header. -h --help Show help for this command. --hostname The GitLab hostname for the request. Defaults to 'gitlab.com', or the authenticated host in the current Git directory. @@ -230,13 +235,16 @@ Do **not** confuse it with: - `--raw-field` / `-f` for string parameters - `--input` for supplying a raw request body from a file or stdin -Illustrative example pattern: +Unlike `--field file=@path`, which reads the file into a text field, `--form file=@path` sends an actual multipart file part. Upload endpoints commonly reject the text-field form with HTTP 400. Every field in the multipart request must use `--form`. ```bash -# Example pattern only — replace the endpoint and field names with the API's actual multipart contract -glab api projects/:fullpath/uploads \ - --method POST \ - --form file=@./artifact.zip +# Project upload +glab api projects/:fullpath/uploads --method POST \ + --form "file=@./screenshot.png" + +# Wiki attachment: both fields use --form +glab api projects/:fullpath/wikis/attachments --method POST \ + --form "file=@./screenshot.png" --form "branch=main" ``` If the endpoint does not explicitly require multipart form data, prefer `--field`, `--raw-field`, or `--input` rather than `--form`. diff --git a/glab-auth/SKILL.md b/glab-auth/SKILL.md index d14e928..04f5871 100644 --- a/glab-auth/SKILL.md +++ b/glab-auth/SKILL.md @@ -42,6 +42,8 @@ glab auth logout > > Example: API hostname `gitlab.company.com`, SSH hostname `ssh.company.com` +For personal access tokens, glab requires at least `api` and `write_repository`. GitLab 18.9 introduced `https:///-/user_settings/personal_access_tokens/legacy/new?scopes=api,write_repository`; that route does not exist on earlier releases. GitLab 18.8 and earlier use `https:///-/user_settings/personal_access_tokens?scopes=api,write_repository` instead. Use the URL for the target instance rather than assuming the current GitLab.com route exists on an older self-managed server. + ### Login flag examples ```bash diff --git a/glab-config/SKILL.md b/glab-config/SKILL.md index 8866377..cc28afb 100644 --- a/glab-config/SKILL.md +++ b/glab-config/SKILL.md @@ -11,24 +11,15 @@ description: Manage glab CLI configuration settings including defaults, preferen Manage key/value strings. Current respected settings: - - branch_prefix: Prefix used by glab stack for generated branch names. Defaults to the operating system account username, then `glab-stack` if user lookup fails. - - browser: If unset, uses the default browser. Override with environment variable $BROWSER. - - check_update: Notify about new glab versions. Override with $GLAB_CHECK_UPDATE. - - display_hyperlinks: Enable terminal hyperlinks. Override with $FORCE_HYPERLINKS. - - duo_cli_auto_download / duo_cli_auto_run: Skip Duo CLI download/run prompts. - - editor: If unset, uses the default editor. Override with environment variable $EDITOR. - - git_protocol: Git protocol, ssh or https. - - glab_pager: Pager command, such as less -R. - - glamour_style: Markdown renderer style: dark, light, notty, or a custom glamour style. - - host: If unset, defaults to `https://gitlab.com`. - - no_prompt: Disable interactive prompts. Prefer the $GLAB_NO_PROMPT override in automation. - - notify_skill_updates: Show installed agent-skill update notices. Override with $GLAB_NOTIFY_SKILL_UPDATES. - - orbit_local_auto_download / orbit_local_auto_run: Skip Orbit local CLI download/run prompts. - - remote_alias: Preferred Git remote name when multiple remotes exist. - - show_whats_new: Show the one-time post-upgrade glab whatsnew banner. Override with $GLAB_SHOW_WHATS_NEW. - - telemetry: Enable usage data to the GitLab instance. Override with $GLAB_SEND_TELEMETRY. - - token: Your GitLab access token. Defaults to environment variables. - - visual: Takes precedence over editor. Override with $VISUAL. + - Global behavior: branch_prefix, browser, check_update, debug, display_hyperlinks, + duo_cli_auto_download, duo_cli_auto_run, editor, git_protocol, glab_pager, + glamour_style, host, no_prompt, notify_skill_updates, orbit_local_auto_download, + orbit_local_auto_run, remote_alias, show_whats_new, and telemetry. + - Per-host behavior: api_host, api_protocol, artifact_registry_domains, ca_cert, + client_cert, client_id, client_key, container_registry_domains, custom_headers, + job_token, proxy, skip_tls_verify, ssh_host, subfolder, token, and use_keyring. + - Accepted aliases include visual/glab_editor for editor, gitlab_host/gitlab_uri/gl_host + for host, prompt_disabled for no_prompt, and the full alias list in references/commands.md. USAGE glab config [command] [--flags] COMMANDS @@ -47,22 +38,19 @@ description: Manage glab CLI configuration settings including defaults, preferen glab config --help ``` -## Per-host HTTPS proxy configuration +## Per-host proxy configuration -You can configure an HTTPS proxy on a per-host basis. This is useful when different GitLab instances (for example gitlab.com vs a self-hosted instance) require different proxy settings. +Configure `proxy` for each GitLab host that requires a fixed proxy. This is useful when different GitLab instances (for example gitlab.com versus a self-hosted instance) require different proxy settings. ```bash -# Set HTTPS proxy for a specific host -glab config set https_proxy "http://proxy.example.com:8080" --host gitlab.mycompany.com - -# Set globally (applies to all hosts without a specific override) -glab config set https_proxy "http://proxy.example.com:8080" --global +# Set the proxy for a specific host +glab config set proxy "http://proxy.example.com:8080" --host gitlab.mycompany.com # Verify -glab config get https_proxy --host gitlab.mycompany.com +glab config get proxy --host gitlab.mycompany.com ``` -**Precedence:** Per-host config overrides global config. Global config overrides the `HTTPS_PROXY` / `https_proxy` environment variables. +**Precedence:** A configured per-host `proxy` replaces environment-based proxy selection for that host. When it is unset, glab falls back to Go's standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` handling. `proxy` is host-scoped; use `--host` rather than writing a top-level value with `--global`. ## Dynamic custom headers for authenticating proxies @@ -142,6 +130,10 @@ GLAB_NO_PROMPT=1 glab repo prune --dry-run `glab config set` validates keys against the canonical config schema. If a set operation fails, check the spelling and whether the setting is host-scoped (`--host`) or global (`--global`) rather than forcing an unknown key into the config file. +Registered aliases are accepted case-insensitively and persist under their canonical key. For example, `glab config set visual nano --global` updates `editor`; both `glab config get visual --global` and `glab config get editor --global` then resolve the same value. Prefer canonical names in new automation even though aliases remain supported. + +`glab_pager` and `debug` are valid global settings. `GLAB_PAGER` takes precedence over `glab_pager`, which takes precedence over `PAGER`; `GLAB_DEBUG` can override the persisted debug setting. + ## Common Settings ```bash @@ -154,6 +146,9 @@ glab config set editor vim --global # Set pager glab config set glab_pager "less -R" --global +# Enable detailed glab/Git/DNS diagnostics +glab config set debug true --global + # Disable update checks glab config set check_update false --global diff --git a/glab-config/references/commands.md b/glab-config/references/commands.md index 56cc460..4711a3b 100644 --- a/glab-config/references/commands.md +++ b/glab-config/references/commands.md @@ -1,6 +1,6 @@ # glab config help -> Help output captured from the checksum-verified glab v1.115.0 macOS arm64 release binary. Terminal padding and trailing whitespace are removed. +> Help output captured from the checksum-verified glab v1.116.0 macOS arm64 release binary. Terminal padding and trailing whitespace are removed. ## config @@ -10,36 +10,76 @@ Current respected settings: + - `api_host`: Configure host for API endpoint. Defaults to the host itself. Also accepted as: `gitlab_api_host`. + Scoped per host; set it with `--host`. + - `api_protocol`: What protocol to use to access the API endpoint. Supported values: `http`, `https`. Scoped per host; + set it with `--host`. + - `artifact_registry_domains`: The domains of associated Artifact Registries. These are used to configure the Docker + credential helper. Only list a domain here if it is actually backed by GitLab Artifact Registry: the credential helper + tries this key first, and a successful token exchange is used as-is, with no fallback to container_registry_domains. A + container-registry domain listed here by mistake gets an artifact-registry token the registry rejects, and `docker + pull` hard-fails. Scoped per host; set it with `--host`. - `branch_prefix`: Prefix used by `glab stack` when naming generated branches. Defaults to the current user's username (from `os/user.Current`), falling back to `glab-stack` if unavailable. - - `browser`: If unset, uses the default browser. Override with environment variable `$BROWSER`. - - `check_update`: If true, notifies of new versions of glab. Defaults to `true`. Override with environment variable - `$GLAB_CHECK_UPDATE`. - - `display_hyperlinks`: If `false`, disables hyperlinks in terminal output. Defaults to `true`. Override with - environment variable `$FORCE_HYPERLINKS`. - - `duo_cli_auto_download`: If `true`, automatically downloads the Duo CLI binary without prompting. - - `duo_cli_auto_run`: If `true`, automatically runs GitLab Duo CLI without prompting. - - `editor`: If unset, uses the default editor. Override with environment variable `$EDITOR`. - - `git_protocol`: Protocol used for Git operations. Supported values: `ssh`, `https`. Defaults to `ssh`. - - `glab_pager`: Your desired pager command to use, such as `less -R`. - - `glamour_style`: Your desired Markdown renderer style. Options are dark, light, notty. Custom styles are available - using glamour. - - `host`: If unset, defaults to `https://gitlab.com`. - - `no_prompt`: If `true`, disables interactive prompts. Defaults to `false`. Override with environment variable - `$NO_PROMPT`. - - `notify_skill_updates`: If `true`, shows a notice when an installed agent skill has updates available. Defaults to - `true`. Override with environment variable `$GLAB_NOTIFY_SKILL_UPDATES`. - - `orbit_local_auto_download`: If `true`, automatically downloads the Orbit local CLI binary without prompting. - - `orbit_local_auto_run`: If `true`, automatically runs Orbit local CLI without prompting. + - `browser`: What browser glab should run when opening links. This global config cannot be overridden by hostname. + - `ca_cert`: Path to a CA certificate (PEM) used to verify the GitLab server's TLS certificate. Useful for self-signed + or private certificate authorities. Scoped per host; set it with `--host`. + - `check_update`: Allow glab to automatically check for updates and notify you when there are new updates. + - `client_cert`: Path to a client certificate (PEM) used for mutual TLS authentication. Scoped per host; set it with + `--host`. + - `client_id`: OAuth application client ID. Required when authenticating with OAuth against a self-managed GitLab + instance. Scoped per host; set it with `--host`. + - `client_key`: Path to the private key (PEM) that matches client_cert. Scoped per host; set it with `--host`. + - `container_registry_domains`: The domains of associated container registries. These are used to configure the Docker + credential helper. Scoped per host; set it with `--host`. + - `custom_headers`: Custom HTTP headers to add to all HTTP requests made by glab. Each header must use exactly one of + value, valueFromEnv, or valueFromCommand. A command must print the complete header value on one line. glab runs it + once for each process. Scoped per host; set it with `--host`. + - `debug`: Output more logging information, including underlying Git commands, expanded aliases, and DNS error + details. + - `display_hyperlinks`: Whether or not to display hyperlinks in terminal output. Defaults to true (enabled for TTYs). + Set to false to disable. Force hyperlinks in non-TTY environments by setting FORCE_HYPERLINKS=1. + - `duo_cli_auto_download`: Automatically download Duo CLI binary without prompting (true/false). + - `duo_cli_auto_run`: Automatically run GitLab Duo CLI without prompting (true/false). Set to true to skip the + confirmation prompt. + - `editor`: What editor glab should run when creating issues, merge requests, etc. This global config cannot be + overridden by hostname. Also accepted as: `visual`, `glab_editor`. + - `git_protocol`: What protocol to use when performing Git operations. Supported values: `ssh`, `https`. + - `glab_pager`: Your desired pager command to use, such as `less -R`. Takes precedence over the PAGER environment + variable. GLAB_PAGER takes precedence over both. + - `glamour_style`: Set your desired Markdown renderer style. Available options are [dark, light, notty]. To set a + custom style, refer to https://github.com/charmbracelet/glamour#styles. + - `host`: Default GitLab hostname to use. Also accepted as: `gitlab_host`, `gitlab_uri`, `gl_host`. + - `job_token`: CI job token used for Job-Token authentication. Typically populated automatically from CI_JOB_TOKEN + when CI auto-login is enabled. Scoped per host; set it with `--host`. + - `no_prompt`: Set to true (1) to disable prompts, or false (0) to enable them. Also accepted as: `prompt_disabled`. + - `notify_skill_updates`: Show a notice when an installed agent skill (bundled or remote) has updates available. + - `orbit_local_auto_download`: Automatically download Orbit local CLI binary without prompting (true/false). + - `orbit_local_auto_run`: Automatically run Orbit local CLI without prompting (true/false). Set to true to skip the + confirmation prompt. + - `proxy`: Custom proxy for this host. Overrides environment proxy settings when set. Scoped per host; set it with `-- + host`. - `remote_alias`: Name of the `git remote` that points at the GitLab repository. Used to resolve which remote to - operate against when multiple are configured. - - `show_whats_new`: If true, shows a one-time post-upgrade banner pointing at `glab whatsnew` when a new version is - detected. Defaults to `true`. Override with environment variable `$GLAB_SHOW_WHATS_NEW`. - - `telemetry`: If `false`, disables sending usage data to your GitLab instance. Defaults to `true`. Override with - environment variable `$GLAB_SEND_TELEMETRY`. - - `token`: Your GitLab access token. Defaults to environment variables. - - `visual`: Takes precedence over `editor`. If unset, uses the default editor. Override with environment variable - `$VISUAL`. + operate against when multiple are configured. Also accepted as: `git_remote_url_var`, `git_remote_alias`, + `remote_nickname`, `git_remote_nickname`. + - `show_whats_new`: Show a one-time post-upgrade banner pointing at `glab whatsnew` when a new version is detected. + - `skip_tls_verify`: Skip TLS certificate verification when talking to this host (true/false). Empty is treated as + false. Use only for development; do not enable in production. Scoped per host; set it with `--host`. + - `ssh_host`: Alternate hostname for SSH Git operations (e.g., `ssh.example.com` or `git.example.com`). Use this when + SSH uses a different hostname than HTTP/API operations. Only affects SSH cloning and Git operations. Also accepted as: + `gitlab_ssh_host`. Scoped per host; set it with `--host`. + - `subfolder`: Subfolder where GitLab is installed (e.g., `gitlab` for https://example.com/gitlab/). Use this when + GitLab is hosted at a subfolder rather than domain root. Supports nested paths (e.g., `apps/gitlab` for + https://example.com/apps/gitlab/). Slashes are automatically trimmed, so `gitlab`, `/gitlab`, and `gitlab/` are + equivalent. Only applies to HTTP/HTTPS operations (API and Git clone). Also accepted as: `gitlab_subfolder`. Scoped + per host; set it with `--host`. + - `telemetry`: Set to false (0) to disable sending usage data to your GitLab instance or true (1) to enable. See + https://docs.gitlab.com/administration/settings/usage_statistics/ for more information. + - `token`: Your GitLab access token. To get one, read https://docs.gitlab.com/user/profile/personal_access_tokens/. + Also accepted as: `gitlab_token`, `oauth_token`. Scoped per host; set it with `--host`. + - `use_keyring`: Store the host's credentials in the operating system's keyring (true/false). Set automatically by + `glab auth login`, which defaults to `true` when a keyring backend is available. Empty is treated as false (plaintext + file storage). Scoped per host; set it with `--host`. Configuration file locations follow the XDG Base Directory specification. For the full search order and platform-specific paths, see configuration.