Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

feat(cli): allow options from CLI args or environment variables#1296

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
JohnVillalovos merged 1 commit intomainfromfeat/merge-cli-env-file-config
Jan 2, 2022
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 50 additions & 7 deletionsdocs/cli-usage.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,17 +3,60 @@
####################

``python-gitlab`` provides a :command:`gitlab` command-line tool to interact
with GitLab servers. It uses a configuration file to define how to connect to
the servers. Without a configuration file, ``gitlab`` will default to
https://gitlab.com and unauthenticated requests.
with GitLab servers.

This is especially convenient for running quick ad-hoc commands locally, easily
interacting with the API inside GitLab CI, or with more advanced shell scripting
when integrating with other tooling.

.. _cli_configuration:

Configuration
=============

Files
-----
``gitlab`` allows setting configuration options via command-line arguments,
environment variables, and configuration files.

For a complete list of global CLI options and their environment variable
equivalents, see :doc:`/cli-objects`.

With no configuration provided, ``gitlab`` will default to unauthenticated
requests against `GitLab.com <https://gitlab.com>`__.

With no configuration but running inside a GitLab CI job, it will default to
authenticated requests using the current job token against the current instance
(via ``CI_SERVER_URL`` and ``CI_JOB_TOKEN`` environment variables).

.. warning::
Please note the job token has very limited permissions and can only be used
with certain endpoints. You may need to provide a personal access token instead.

When you provide configuration, values are evaluated with the following precedence:

1. Explicitly provided CLI arguments,
2. Environment variables,
3. Configuration files:

a. explicitly defined config files:

i. via the ``--config-file`` CLI argument,
ii. via the ``PYTHON_GITLAB_CFG`` environment variable,

b. user-specific config file,
c. system-level config file,

4. Environment variables always present in CI (``CI_SERVER_URL``, ``CI_JOB_TOKEN``).

Additionally, authentication will take the following precedence
when multiple options or environment variables are present:

1. Private token,
2. OAuth token,
3. CI job token.


Configuration files
-------------------

``gitlab`` looks up 3 configuration files by default:

Expand All@@ -35,8 +78,8 @@ You can use a different configuration file with the ``--config-file`` option.
If the environment variable is defined and the target file cannot be accessed,
``gitlab`` will fail explicitly.

Content
-------
Configuration file format
-------------------------

The configuration file uses the ``INI`` format. It contains at least a
``[global]`` section, and a specific section for each GitLab server. For
Expand Down
108 changes: 103 additions & 5 deletionsgitlab/cli.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -19,6 +19,7 @@

import argparse
import functools
import os
import re
import sys
from types import ModuleType
Expand DownExpand Up@@ -112,17 +113,25 @@ def _get_base_parser(add_help: bool = True) -> argparse.ArgumentParser:
"-v",
"--verbose",
"--fancy",
help="Verbose mode (legacy format only)",
help="Verbose mode (legacy format only) [env var: GITLAB_VERBOSE]",
action="store_true",
default=os.getenv("GITLAB_VERBOSE"),
)
parser.add_argument(
"-d", "--debug", help="Debug mode (display HTTP requests)", action="store_true"
"-d",
"--debug",
help="Debug mode (display HTTP requests) [env var: GITLAB_DEBUG]",
action="store_true",
default=os.getenv("GITLAB_DEBUG"),
)
parser.add_argument(
"-c",
"--config-file",
action="append",
help="Configuration file to use. Can be used multiple times.",
help=(
"Configuration file to use. Can be used multiple times. "
"[env var: PYTHON_GITLAB_CFG]"
),
)
parser.add_argument(
"-g",
Expand DownExpand Up@@ -151,7 +160,86 @@ def _get_base_parser(add_help: bool = True) -> argparse.ArgumentParser:
),
required=False,
)
parser.add_argument(
"--server-url",
help=("GitLab server URL [env var: GITLAB_URL]"),
required=False,
default=os.getenv("GITLAB_URL"),
)
parser.add_argument(
"--ssl-verify",
help=(
"Whether SSL certificates should be validated. [env var: GITLAB_SSL_VERIFY]"
),
required=False,
default=os.getenv("GITLAB_SSL_VERIFY"),
)
parser.add_argument(
"--timeout",
help=(
"Timeout to use for requests to the GitLab server. "
"[env var: GITLAB_TIMEOUT]"
),
required=False,
default=os.getenv("GITLAB_TIMEOUT"),
)
parser.add_argument(
"--api-version",
help=("GitLab API version [env var: GITLAB_API_VERSION]"),
required=False,
default=os.getenv("GITLAB_API_VERSION"),
)
parser.add_argument(
"--per-page",
help=(
"Number of entries to return per page in the response. "
"[env var: GITLAB_PER_PAGE]"
),
required=False,
default=os.getenv("GITLAB_PER_PAGE"),
)
parser.add_argument(
"--pagination",
help=(
"Whether to use keyset or offset pagination [env var: GITLAB_PAGINATION]"
),
required=False,
default=os.getenv("GITLAB_PAGINATION"),
)
parser.add_argument(
"--order-by",
help=("Set order_by globally [env var: GITLAB_ORDER_BY]"),
required=False,
default=os.getenv("GITLAB_ORDER_BY"),
)
parser.add_argument(
"--user-agent",
help=(
"The user agent to send to GitLab with the HTTP request. "
"[env var: GITLAB_USER_AGENT]"
),
required=False,
default=os.getenv("GITLAB_USER_AGENT"),
)

tokens = parser.add_mutually_exclusive_group()
tokens.add_argument(
"--private-token",
help=("GitLab private access token [env var: GITLAB_PRIVATE_TOKEN]"),
required=False,
default=os.getenv("GITLAB_PRIVATE_TOKEN"),
)
tokens.add_argument(
"--oauth-token",
help=("GitLab OAuth token [env var: GITLAB_OAUTH_TOKEN]"),
required=False,
default=os.getenv("GITLAB_OAUTH_TOKEN"),
)
tokens.add_argument(
"--job-token",
help=("GitLab CI job token [env var: CI_JOB_TOKEN]"),
required=False,
)
return parser


Expand DownExpand Up@@ -243,13 +331,23 @@ def main() -> None:
"whaction",
"version",
"output",
"fields",
"server_url",
"ssl_verify",
"timeout",
"api_version",
"pagination",
"user_agent",
"private_token",
"oauth_token",
"job_token",
):
args_dict.pop(item)
args_dict = {k: _parse_value(v) for k, v in args_dict.items() if v is not None}

try:
gl = gitlab.Gitlab.from_config(gitlab_id, config_files)
if gl.private_token or gl.oauth_token or gl.job_token:
gl = gitlab.Gitlab.merge_config(vars(options),gitlab_id, config_files)
if gl.private_token or gl.oauth_token:
gl.auth()
except Exception as e:
die(str(e))
Expand Down
82 changes: 82 additions & 0 deletionsgitlab/client.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,6 +16,7 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""Wrapper for the GitLab API."""

import os
import time
from typing import Any, cast, Dict, List, Optional, Tuple, TYPE_CHECKING, Union

Expand DownExpand Up@@ -256,6 +257,87 @@ def from_config(
retry_transient_errors=config.retry_transient_errors,
)

@classmethod
def merge_config(
cls,
options: dict,
gitlab_id: Optional[str] = None,
config_files: Optional[List[str]] = None,
) -> "Gitlab":
"""Create a Gitlab connection by merging configuration with
the following precedence:

1. Explicitly provided CLI arguments,
2. Environment variables,
3. Configuration files:
a. explicitly defined config files:
i. via the `--config-file` CLI argument,
ii. via the `PYTHON_GITLAB_CFG` environment variable,
b. user-specific config file,
c. system-level config file,
4. Environment variables always present in CI (CI_SERVER_URL, CI_JOB_TOKEN).

Args:
options: A dictionary of explicitly provided key-value options.
gitlab_id: ID of the configuration section.
config_files: List of paths to configuration files.
Returns:
(gitlab.Gitlab): A Gitlab connection.

Raises:
gitlab.config.GitlabDataError: If the configuration is not correct.
"""
config = gitlab.config.GitlabConfigParser(
gitlab_id=gitlab_id, config_files=config_files
)
url = (
options.get("server_url")
or config.url
or os.getenv("CI_SERVER_URL")
or gitlab.const.DEFAULT_URL
)
private_token, oauth_token, job_token = cls._merge_auth(options, config)

return cls(
url=url,
private_token=private_token,
oauth_token=oauth_token,
job_token=job_token,
ssl_verify=options.get("ssl_verify") or config.ssl_verify,
timeout=options.get("timeout") or config.timeout,
api_version=options.get("api_version") or config.api_version,
per_page=options.get("per_page") or config.per_page,
pagination=options.get("pagination") or config.pagination,
order_by=options.get("order_by") or config.order_by,
user_agent=options.get("user_agent") or config.user_agent,
)

@staticmethod
def _merge_auth(options: dict, config: gitlab.config.GitlabConfigParser) -> Tuple:
"""
Return a tuple where at most one of 3 token types ever has a value.
Since multiple types of tokens may be present in the environment,
options, or config files, this precedence ensures we don't
inadvertently cause errors when initializing the client.

This is especially relevant when executed in CI where user and
CI-provided values are both available.
"""
private_token = options.get("private_token") or config.private_token
oauth_token = options.get("oauth_token") or config.oauth_token
job_token = (
options.get("job_token") or config.job_token or os.getenv("CI_JOB_TOKEN")
)

if private_token:
return (private_token, None, None)
if oauth_token:
return (None, oauth_token, None)
if job_token:
return (None, None, job_token)

return (None, None, None)

def auth(self) -> None:
"""Performs an authentication using private token.

Expand Down
4 changes: 2 additions & 2 deletionsgitlab/config.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,7 @@
from pathlib import Path
from typing import List, Optional, Union

from gitlab.const importDEFAULT_URL,USER_AGENT
from gitlab.const import USER_AGENT

_DEFAULT_FILES: List[str] = [
"/etc/python-gitlab.cfg",
Expand DownExpand Up@@ -119,7 +119,7 @@ def __init__(
self.retry_transient_errors: bool = False
self.ssl_verify: Union[bool, str] = True
self.timeout: int = 60
self.url: str =DEFAULT_URL
self.url:Optional[str] =None
self.user_agent: str = USER_AGENT

self._files = _get_config_files(config_files)
Expand Down
Loading
[8]ページ先頭
©2009-2025 Movatter.jp