From fc361a2287a953e9a274d1b2d37fa6fc3360ad8e Mon Sep 17 00:00:00 2001 From: Kyle Fazzari Date: Tue, 26 May 2020 13:25:58 -0700 Subject: [PATCH] Document authentication behavior in README Signed-off-by: Kyle Fazzari --- README.rst | 38 +++++++++++++++++++++++++++++++++++++ vcstool/clients/vcs_base.py | 12 +++++++++--- 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index a068eb51..7e04aea9 100644 --- a/README.rst +++ b/README.rst @@ -138,6 +138,44 @@ The set of repositories to operate on can optionally be restricted by the type: If the command should work on multiple repositories make sure to pass only generic arguments which work for all of these repository types. +Access repositories that require authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vcstool supports authenticated access to repositories by parsing files with a netrc-like format. +It will first look for login information in the `~/.netrc` file, used by ftp, git, and similar programs if it exists. +If it doesn't exist (or doesn't contain login infomation for the URL in question), it moves to vcstool-specific locations. +In these locations vcstool will look for credentials in either an `auth.conf` file, or `.conf` files inside an `auth.conf.d` directory. +These locations are (in order of precedence): + +1. User config directory. + - On Linux, abides by XDG spec: `~/.config/vcstool/` + - On macOS: `~/Library/Application Support/vcstool/` + - On Windows: `C:\\Users\\\\AppData\\Local\\vcstool\\vcstool\\` +2. Site config directory. + - On Linux: `vcstool/` subdirectory in any directory within `$XDG_CONFIG_DIRS`, or `/etc/xdg/vcstool/` if unset + - On macOS: `/Library/Application Support/vcstool/` + - On Windows: `C:\\ProgramData\\vcstool\\vcstool\\` + +The netrc-like format consists of a few different tokens separated by whitespace (spaces, tabs, or newlines): + +- `machine `: Credentials are retrieved by matching the repository URL to this token +- `login `: Login username +- `password `: Login password + +For example, to access private github repositories:: + + machine github.com + login mylogin + password myaccesstoken + +Accessing private gitlab repositories looks similar, although no `login` is required:: + + machine gitlab.com + password myaccesstoken + +A word of caution: these files are not encrypted. +Ensure that their permissions do not exceed that which is required. + How to install vcstool? ======================= diff --git a/vcstool/clients/vcs_base.py b/vcstool/clients/vcs_base.py index 2af3751c..ae36727b 100644 --- a/vcstool/clients/vcs_base.py +++ b/vcstool/clients/vcs_base.py @@ -222,9 +222,15 @@ def _credentials_for_machine(machine): if credentials: return credentials - # Finally, check the system-wide auth directory for vcstool - return _credentials_for_machine_in_dir( - appdirs.site_config_dir(_APPDIRS_PROJECT_NAME), machine) + # Finally, check the system-wide auth directories for vcstool, in order + auth_path = appdirs.site_config_dir(_APPDIRS_PROJECT_NAME, multipath=True) + for site_config_dir in auth_path.split(':'): + credentials = _credentials_for_machine_in_dir( + site_config_dir, machine) + if credentials: + return credentials + + return None def _credentials_for_machine_in_dir(directory, machine):