Refactor commit signature docs into a single page
On !103058 (comment 1171214513), we had a proposal to refactor the signature documentation. Let's act on it.
While I added a troubleshooting section to the end of https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/ I am less certain about where to add info in https://docs.gitlab.com/ee/user/project/repository/x509_signed_commits/ because a long troubleshooting section already exists on that page. Where does this info fit into the process?
I think the X.509 troubleshooting won't be applicable for most users, because it has to be done by an admin. While it's not mentioned explicitly in the documentation, X.509 commit signing is technically only available for self-managed GitLab, because it requires an administrator to add the organizations CA certificate to the GitLab trust store. This is an instance-wide change, and it cannot be done on GitLab.com.
Should the x509 page be the SSOT of the table of errors/remedies, or should the GPG page be it?
I would love to consolidate all of the "commit signing" documentation into a single page which is tool-agonistic (GPG, X.509, SSH). What if we have a "commit signing" page, and then a separate "troubleshooting steps for X.509 commit signing" page?
@aqualls: I'd like to get opinions from @sean_carroll and @andr3 about whether or not it makes sense to reorganize this information:
- Current version: a page for GPG signed commits, and a page for x509 signed commits
- Proposed version: a single page to cover all methods of signing commits, and a separate troubleshooting page
To help make your opinion an informed one, here are some details:
- I'm unclear how many other methods we'd need to document. Sounds like at least one - SSH.
- The GPG page is viewed about 16x more frequently than the x509 page.
- If we blend the signing methods together, we'll need to mark the x509 subheadings as being for self-managed only. (We'll need to update the x509 page no matter what, but right now the tier info would be at the top of the page, rather than in subheadings.)
- Troubleshooting pages CAN become something of a dumping ground, but this one hasn't changed much - maybe because not many people are using the x509 method?
Implementation Guide
-
Create a new page:
doc/user/project/repository/sign_commits/index.md
-
Move the contents from GPG signed commits, SSH signed commits, and X.509 signed commits to the new page. Where the pages have identical sections, use tabs in order to separate the content by type. See !99159 (merged) for an example of how to do this.
-
Create redirects from the old pages to the new ones.