Doc revisions1 (#5621)

* Begin reviewing the basics docs. * Check in delta * More doc revisions. * Split apart basics docs. * Refactor based on building docs * add the files back as markdown. * more conversions to markdown. * more conversions to markdown. * fix markdown formatting. * convert index to markdown. * More docs review * More markdown and doc revisions. * Fix docs. * Update doc build requirements. * fix lint * Fix build with update/upgrade command. * remove useless quickstart and update the commands section. * Fix lint * change ordering of table of contents. * fix changelog duplicate headings. * Start splitting advanced topics. * minor nits * Move some sections from advanced to shell. * remove this section as its stale and kind of off topic. * move scripts out into its own section. * Wrap up revisions1 * fix lint * address PR feedback and other nits. * fix lint * Try improving ordering of table of contents, fix issue with indexes.md file location. * fix lint * PR feedback.
2026-06-05 06:46:15 +00:00 · 2023-03-18 03:44:58 -04:00
parent 08ce3f7d5e
commit 761a03d088
26 changed files with 1424 additions and 1468 deletions
@@ -0,0 +1,60 @@
+# Credentials
+
+## Injecting credentials into Pipfile via environment variables
+
+Pipenv will expand environment variables (if defined) in your Pipfile. Quite
+useful if you need to authenticate to a private PyPI:
+
+    [[source]]
+    url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple"
+    verify_ssl = true
+    name = "pypi"
+
+Luckily - pipenv will hash your Pipfile *before* expanding environment
+variables (and, helpfully, will substitute the environment variables again when
+you install from the lock file - so no need to commit any secrets! Woo!)
+
+If your credentials contain special characters, make sure they are URL-encoded as specified in `rfc3986 <https://datatracker.ietf.org/doc/html/rfc3986>`_.
+
+Environment variables may be specified as `${MY_ENVAR}` or `$MY_ENVAR`.
+
+On Windows, `%MY_ENVAR%` is supported in addition to `${MY_ENVAR}` or `$MY_ENVAR`.
+
+Environment variables in the URL part of requirement specifiers can also be expanded, where the variable must be in the form of `${VAR_NAME}`. Neither `$VAR_NAME` nor `%VAR_NAME%` is acceptable:
+
+    [[package]]
+    requests = {git = "git://${USERNAME}:${PASSWORD}@private.git.com/psf/requests.git", ref = "2.22.0"}
+
+Keep in mind that environment variables are expanded in runtime, leaving the entries in `Pipfile` or `Pipfile.lock` untouched. This is to avoid the accidental leakage of credentials in the source code.
+
+## Injecting credentials through keychain support
+
+Private registries on Google Cloud, Azure and AWS support dynamic credentials using
+the keychain implementation. Due to the way the keychain is structured, it might ask
+the user for input. Asking the user for input is disabled. This will disable the keychain
+support completely, unfortunately.
+
+If you want to work with private registries that use the keychain for authentication, you
+can disable the "enforcement of no input".
+
+**Note:** Please be sure that the keychain will really not ask for
+input. Otherwise, the process will hang forever!:
+
+    [[source]]
+    url = "https://pypi.org/simple"
+    verify_ssl = true
+    name = "pypi"
+
+    [[source]]
+    url = "https://europe-python.pkg.dev/my-project/python/simple"
+    verify_ssl = true
+    name = "private-gcp"
+
+    [packages]
+    flask = "*"
+    private-test-package = {version = "*", index = "private-gcp"}
+
+    [pipenv]
+    disable_pip_input = false
+
+Above example will install `flask` and a private package `private-test-package` from GCP.