Document `~/.netrc` usage

Problem to solve

TLDR; ~/.netrc makes GitLab easier to use (much easier for Pythonistas!), but it's not mentioned in the docs.

Long version

GitLab docs suggests many different ways of authenticating to private resources using Personal Access Tokens. Examples:

  1. Private PyPI docs tells us to use ~/.pypirc (navigating to the actual registry, we also have the pip install <LIBRARY> --extra-index-url https://__token__:<TOKEN>@gitlab.com/api/v4/projects/<PROJECT_ID>/packages/pypi/simple suggestion.)

  2. Container Registry docs advises us to manually input username and token: docker login registry.example.com -u <username> -p <token>

  3. Personal Access Token docs don't even mention how we can clone a private repo using https and tokens.

However, we can solve (1), (2) and (3) by configuring a ~/.netrc file like so:

machine gitlab.com
login oauth2
password <PERSONAL_ACCESS_TOKEN>

After doing that a single time, all the following will work without prompting for credentials:

git clone https://gitlab.com/...
docker login registry.gitlab.com
pip install <LIB_NAME>@git+https://gitlab.com/<...>@<TAG>
pip install <LIB_NAME> --extra-index-url https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/pypi/simple

Moreover, ~/.netrc:

  1. Can be mounted on containers for local development.
  2. Works on Windows (but it's called _netrc), Linux and MacOS (I tested in Windows and Linux using WSL).
  3. Only needs to be configured a single time
  4. I did not test those, but Conan and Terraform Registries also might work. More generally, it might work with aything that uses libcurl behind the scenes.
  5. Can be used in CI/CD (thanks @marcelst!):
echo "machine gitlab.com
login gitlab-ci-token
password $CI_JOB_TOKEN" >> ~/.netrc

Proposal

Add directions for using ~/.netrc when supported.

Other links/references

The .netrc file (GNU Inetutils)

Edited by Carlos Felipe Domingues e Oliveira