Skip to content

Commit dd9fa04

Browse files
authored
Merge pull request #6530 from stsewd/guide-private-python-packages
Guide: private python packages in .com
2 parents e839813 + 9cdec14 commit dd9fa04

File tree

3 files changed

+114
-0
lines changed

3 files changed

+114
-0
lines changed

docs/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ def get_version():
5454
'python': ('https://docs.python.org/3.6/', None),
5555
'django': ('https://docs.djangoproject.com/en/1.11/', 'https://docs.djangoproject.com/en/1.11/_objects/'),
5656
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
57+
'pip': ('https://pip.pypa.io/en/stable/', None),
5758
}
5859
htmlhelp_basename = 'ReadTheDocsdoc'
5960
latex_documents = [

docs/guides/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,5 @@ These guides are specific to :doc:`/commercial/index`.
5656
.. toctree::
5757
:maxdepth: 1
5858

59+
private-python-packages
5960
private-submodules
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
Installing Private Python Packages
2+
==================================
3+
4+
.. warning::
5+
6+
This guide is for :doc:`/commercial/index`.
7+
8+
Read the Docs uses :doc:`pip <pip:index>` to install your Python packages.
9+
If you have private dependencies, you can install them from
10+
a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
11+
a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
12+
13+
From a Git repository
14+
---------------------
15+
16+
Pip supports installing packages from a :ref:`Git repository <pip:vcs support>` using the URI form:
17+
18+
.. code::
19+
20+
git+https://gitprovider.com/user/project.git@{version}
21+
22+
Or if your repository is private:
23+
24+
.. code::
25+
26+
git+https://{token}@gitprovider.com/user/project.git@{version}
27+
28+
Where ``version`` can be a tag, a branch, or a commit.
29+
And ``token`` is a personal access token with read only permissions from your provider.
30+
31+
.. TODO: We should add the git+ssh form when we support running the ssh-agent in the build step.
32+
33+
To install the package,
34+
you need to add the URI in your :ref:`requirements file <config-file/v2:Requirements file>`.
35+
Pip will automatically expand environment variables in your URI,
36+
so you don't have to hard code the token in the URI.
37+
See :doc:`using environment variables in Read the Docs </guides/environment-variables>` for more information.
38+
39+
Bellow you can find how to get a personal access token from our supported providers.
40+
We will be using environment variables for the token.
41+
42+
GitHub
43+
~~~~~~
44+
45+
You need to create a personal access token with the ``repo`` scope.
46+
Check the `GitHub documentation <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token>`__
47+
on how to create a personal token.
48+
49+
URI example:
50+
51+
.. code::
52+
53+
git+https://${GITHUB_TOKEN}@github.com/user/project.git@{version}
54+
55+
.. warning::
56+
57+
GitHub doesn't support tokens per repository.
58+
A personal token will grant read and write access to all repositories the user has access to.
59+
You can create a `machine user <https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users>`__
60+
to give read access only to the repositories you need.
61+
62+
GitLab
63+
~~~~~~
64+
65+
You need to create a deploy token with the ``read_repository`` scope for the repository you want to install the package from.
66+
Check the `GitLab documentation <https://docs.gitlab.com/ee/user/project/deploy_tokens/#creating-a-deploy-token>`__
67+
on how to create a deploy token.
68+
69+
URI example:
70+
71+
.. code::
72+
73+
git+https://${GITLAB_TOKEN_USER}:${GITLAB_TOKEN}@gitlab.com/user/project.git@{version}
74+
75+
Here ``GITLAB_TOKEN_USER`` is the user from the deploy token you created, not your GitLab user.
76+
77+
Bitbucket
78+
~~~~~~~~~
79+
80+
You need to create an app password with ``Read repositories`` permissions.
81+
Check the `Bitbucket documentation <https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html>`__
82+
on how to create an app password.
83+
84+
URI example:
85+
86+
.. code::
87+
88+
git+https://${BITBUCKET_USER}:${BITBUCKET_APP_PASSWORD}@bitbucket.org/user/project.git@{version}'
89+
90+
Here ``BITBUCKET_USER`` is your Bitbucket user.
91+
92+
.. warning::
93+
94+
Bitbucket doesn't support app passwords per repository.
95+
An app password will grant read access to all repositories the user has access to.
96+
97+
From a repository manager other than PyPI
98+
-----------------------------------------
99+
100+
Pip by default will install your packages from `PyPI <https://pypi.org/>`__.
101+
If you are using a repository manager like *pypiserver*, or *Nexus Repository*,
102+
you need to set the :option:`pip:--index-url` option.
103+
You have two ways of set that option:
104+
105+
- Set the ``PIP_INDEX_URL`` :doc:`environment variable in Read the Docs </guides/environment-variables>` with the index URL.
106+
See :ref:`pip:using environment variables`.
107+
- Put ``--index-url=https://my-index-url.com/`` at the top of your requirements file.
108+
See :ref:`pip:requirements file format`.
109+
110+
.. note::
111+
112+
Check your repository manager's documentation to obtain the appropriate index URL.

0 commit comments

Comments
 (0)