Skip to content

Protect GitHub tutorial: correct the credential request and username mapping - #569

Open
J-Hunter-Hawke wants to merge 1 commit into
mainfrom
hunter/pro-606-docs-four-incorrect-items-in-the-tutorial-protect-github
Open

J-Hunter-Hawke wants to merge 1 commit into
mainfrom
hunter/pro-606-docs-four-incorrect-items-in-the-tutorial-protect-github

Conversation

@J-Hunter-Hawke

Copy link
Copy Markdown
Contributor

This PR corrects the tutorial Protect GitHub with SSH Certificates. It changes one file: tutorials/protect-github-ssh.mdx.

  • Step 1, credential request. The request now uses Create Endpoint Configuration (POST /api/endpoint-configurations) with kind: account. This is the request that creates an SSH user credential. It matches the request in the GitHub SSH guide that we already share with customers. The field list below the request uses the new field names.
  • Step 1, authority. This PR removes the paragraph that tells the reader to copy the Authority ID. It also removes the authorityID field from the request. With no authority in the request, Smallstep issues the certificates from the SSH authority of the team. Smallstep SSH uses the same authority. Thus the credential works with Smallstep SSH. In Step 2, the reader already copies the user CA key of that authority.
  • GitHub username. The page said in five places that the username is a certificate principal. The places are the diagram, the introduction, the field list, the end of Step 1, and Step 2. GitHub identifies the user from the login@github.com extension. Smallstep puts the githubUsername attribute in that extension. The text for SSH.Principals now says what it holds: POSIX usernames and SSH group principals.
  • Commit signing. The user.signingkey command now has the prefix key::. Without the prefix, Git reads the value as a file path, unless the value starts with ssh-. The default key of the agent is ECDSA P-256 (ecdsa-sha2-nistp256 ...).
  • Verify and troubleshoot. This PR removes the line that tells the reader to confirm an issued SSH certificate in the dashboard. The ssh-add -l check above that line is sufficient.
  • Date. updated_at is now October 13, 2026.

For review

  • The API reference marks Create Endpoint Configuration as deprecated. PRO-606 gives the background and the open question about which request this page shows.
  • A test used git 2.56.0 and an ECDSA P-256 key. The value without the prefix failed. The value with the prefix key:: signed the commit.
  • A review compared the fields and the values of the request with the 2025-01-01 API schema.

Related links/other PRs/issues:

…mapping

Create the SSH credential with the Create Endpoint Configuration request,
and leave the authority out so certificates come from the team's SSH
authority, the one Smallstep SSH uses.

Say that the GitHub username reaches the certificate in the
login@github.com extension, not in the principals, and describe what
SSH.Principals holds.

Add the key:: prefix to the user.signingkey command, so Git reads the
value as a public key and not as a file path.

Drop the dashboard check from the troubleshooting list; ssh-add -l
already covers it.

Refs PRO-606

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@J-Hunter-Hawke
J-Hunter-Hawke requested a review from a team as a code owner October 13, 2026 19:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant