@@ -93,6 +93,8 @@ Only one of ``private_token``, ``oauth_token`` or ``job_token`` should be
9393defined. If neither are defined an anonymous request will be sent to the Gitlab
9494server, with very limited permissions.
9595
96+ We recommend that you use `Credential helpers `_ to securely store your tokens.
97+
9698..list-table ::GitLab server options
9799:header-rows: 1
98100
@@ -119,22 +121,50 @@ server, with very limited permissions.
119121 * - ``http_password ``
120122 - Password for optional HTTP authentication
121123
122- For all settings, which contain secrets (``http_password ``,
124+
125+ Credential helpers
126+ ------------------
127+
128+ For all configuration options that contain secrets (``http_password ``,
123129``personal_token ``, ``oauth_token ``, ``job_token ``), you can specify
124- a helper program to retrieve the secret indicated by ``helper: ``
125- prefix. You can only specify a path to a program without any
126- parameters. You may use ``~ `` for expanding your homedir in helper
127- program's path. It is expected, that the program prints the secret
128- to standard output.
130+ a helper program to retrieve the secret indicated by a ``helper: ``
131+ prefix. This allows you to fetch values from a local keyring store
132+ or cloud-hosted vaults such as Bitwarden. Environment variables are
133+ expanded if they exist and ``~ `` expands to your home directory.
134+
135+ It is expected that the helper program prints the secret to standard output.
136+ To use shell features such as piping to retrieve the value, you will need
137+ to use a wrapper script; see below.
129138
130139Example for a `keyring <https://github.com/jaraco/keyring >`_ helper:
131140
132- ..code-block ::bash
141+ ..code-block ::ini
133142
134- #! /bin/bash
135- keyring get Service Username
143+ [global]
144+ default = somewhere
145+ ssl_verify = true
146+ timeout = 5
147+
148+ [somewhere]
149+ url = http://somewhe.re
150+ private_token = helper: keyring get Service Username
151+ timeout = 1
152+
153+ Example for a `pass <https://www.passwordstore.org >`_ helper with a wrapper script:
154+
155+ ..code-block ::ini
156+
157+ [global]
158+ default = somewhere
159+ ssl_verify = true
160+ timeout = 5
161+
162+ [somewhere]
163+ url = http://somewhe.re
164+ private_token = helper: /path/to/helper.sh
165+ timeout = 1
136166
137- Example for a ` pass < https://www.passwordstore.org >`_ helper :
167+ In ` /path/to/helper.sh ` :
138168
139169..code-block ::bash
140170