docs: document accepted private key formats for GitHub App auth - #186
Conversation
The GitHub App walkthrough ended at "Carefully save the private key file" and never told the reader which key formats the connector accepts, or that the contents of that file can be supplied instead of a path. loadPrivateKeyFromString accepts PKCS#1 and PKCS#8, so a key from GitHub's Generate a private key button and one produced by OpenSSL 3.0+ both work with no conversion. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Connector PR Review: docs: document accepted private key formats for GitHub App authBlocking Issues: 0 | Suggestions: 0 | Threads Resolved: 0 Review SummaryScanned the full PR diff for security and correctness: it is documentation-only, adding a 7-line note to the GitHub App private-key step in Security IssuesNone found. Correctness IssuesNone found. SuggestionsNone. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
2 participants
Summary
The GitHub App walkthrough ends at "Carefully save the private key file." (
docs/connector.mdx:216) and stops there. Two things an operator needs are absent from the page, and both are now covered by one note on that step.Findings addressed
The accepted key formats —
verifiedin code,measuredagainst a live app.loadPrivateKeyFromStringaccepts PKCS#1 — header-----BEGIN RSA PRIVATE KEY-----, what GitHub's Generate a private key button produces — and PKCS#8 — header-----BEGIN PRIVATE KEY-----, what OpenSSL 3.0+ emits by default (pkg/connector/connector.go:495-508). A PKCS#8 key that is not RSA is rejected withnot an RSA private key(pkg/connector/connector.go:502), which is why the note says RSA explicitly. Both RSA formats were exercised against a live GitHub App on v0.4.1 and each produced a full sync, so the "no conversion is needed" claim is measured rather than inferred.That the key can be supplied by value —
verifiedin code.--app-privatekey/$BATON_APP_PRIVATEKEYtakes the raw PEM contents, andappPrivateKeyPEM(pkg/connector/connector.go:356) prefers it over--app-privatekey-pathwhen both are set.README.md:77-78documents both flags, but on the customer-facing page a reader following the credential walkthrough reaches the configuration step believing the saved file is the only usable artefact.Why it mattered
An operator who generates the key with OpenSSL rather than GitHub's button has no way to tell from this page whether the resulting PKCS#8 file works, and converting it "just in case" is a step nobody needs to take. The second sentence is what connects this step to the configuration step, where either form is accepted.
Scope
One note, on the step where the walkthrough loses the reader. No other section changed. The C1 config form's single-line shape is deliberately out of scope here — it is documented separately in #185, which touches the same file at
:296, well clear of this change.🤖 Generated with Claude Code