|
| 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