GitHub App: add docs#12114
Closed
stsewd wants to merge 4 commits into
Closed
Conversation
stsewd
added a commit
that referenced
this pull request
May 14, 2025
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).
humitos
reviewed
May 19, 2025
Member
humitos
left a comment
humitos
left a comment
There was a problem hiding this comment.
Looks good with some suggestions.
Comment on lines
+11
to
+16
| 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. |
Member
There was a problem hiding this comment.
I would finish taking about SSH keys and submodules first and then explain the GitHub case.
Suggested change
| 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. |
| #. Click the |:heavy_plus_sign:| button to the right of your ``rtd-tutorial`` project. If the list of repositories is empty, click the |:arrows_counterclockwise:| button. | ||
| #. Click on :guilabel:`Install GitHub App on repository`, and choose your account and select the repository you created in the previous step. | ||
|
|
||
| .. figure:: /_static/images/tutorial/rtd-import-projects.gif |
Member
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.
Member
Author
|
This is blocked until we ship the app to everyone, but ported the content about the app to #12217. |
Member
Author
|
Superseded by #12452 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Extracted from #11942
Closes #12129
📚 Documentation previews 📚
docs): https://docs--12114.org.readthedocs.build/12114/dev): https://dev--12114.org.readthedocs.build/12114/