GitHub App: add docs #12114
GitHub App: add docs #12114
Conversation
First I wanted to pass the env var just in the clone step, but we don't allow passing additional env vars once the environment is created, so it's available in the whole "clone" environment. The access token we create is read-only, and should be scoped to just one project as well (waiting on PyGithub/PyGithub#3287). Once the clone is done, the token is stored in the .git/config file, so that token isn't always kept secret from the rest of the build like ssh keys, but since the token is read-only and scoped to the current project, and temporary (1 hour). It should be fine. Additionally, the token is only created for private repos, meaning that only people with explicit access to the repo may be able to extract the token, but again, since they already have access to the repo, there is no additional permissions the token is granting to the user (will document this in #12114).
| Read the Docs uses SSH keys (with read only permissions) for GitLab and Bitbucket in order to clone private repositories, | ||
| this key is added to your main repository, but not to your submodules. | ||
| For GitHub we make use of a temporary token generated using our :ref:`GitHub App <reference/git-integration:GitHub App>`. | ||
|
|
||
| When a project is created, a SSH key is automatically generated. | ||
| You can use this SSH key to give Read the Docs access to clone your private submodules. |
There was a problem hiding this comment.
I would finish taking about SSH keys and submodules first and then explain the GitHub case.
| Read the Docs uses SSH keys (with read only permissions) for GitLab and Bitbucket in order to clone private repositories, | |
| this key is added to your main repository, but not to your submodules. | |
| For GitHub we make use of a temporary token generated using our :ref:`GitHub App <reference/git-integration:GitHub App>`. | |
| When a project is created, a SSH key is automatically generated. | |
| You can use this SSH key to give Read the Docs access to clone your private submodules. | |
| When adding a private GitLab and/or a Bitbucket project, | |
| Read the Docs will generate a SSH key (with read only permissions) and add it to the repository to be able to clone. This SSH key is not added to the submodules of the repository. | |
| In case you need to clone the private submodules, you can add this SSH key on those repositories as well. | |
| When adding a GitHub project, Read the Docs make use of a temporary token generated using our :ref:`GitHub App <reference/git-integration:GitHub App>` instead of SSH keys. |
| In case of GitHub, | ||
| check that you have granted access to the Read the Docs `OAuth App`_ to your organization. |
There was a problem hiding this comment.
Don't we still need to mention this but pointing to our GitHub Application instead?
There was a problem hiding this comment.
There are no webhook creation related errors when using the github app.
There was a problem hiding this comment.
Yeah, I don't refer to webhooks but to the authorization of our GitHub App. The user still have to grant access to it, right?
I'm taking about this https://github.com/settings/connections/applications/Iv23liE6t9Wm8swttujH
There was a problem hiding this comment.
That authorization is done when you log in. But isn't needed as long as the app is installed in the repo. But again, users are never presented with this error when using a GH app.
|
|
||
| .. figure:: /_static/images/tutorial/rtd-import-projects.gif |
There was a problem hiding this comment.
Just to note that we are deleting an image here. I know that @agjohnson wanted to re-new/re-take them using the new dashboard.
Extracted from #11942
Closes #12129
📚 Documentation previews 📚
docs): https://docs--12114.org.readthedocs.build/12114/dev): https://dev--12114.org.readthedocs.build/12114/