Skip to content

feat: guide users through GitHub signature verification during auths init #143

@bordumb

Description

@bordumb

Summary

After auths init completes, prompt users to set up GitHub signature verification so their commits show the "Verified" badge. This is the most common next step after init and currently requires users to discover it in the docs.

Motivation

  • Most auths users sign commits for GitHub repos
  • Without adding the public key to GitHub, commits show as "Unverified" despite being properly signed
  • Users don't realize they need this step until they push and see no badge
  • This is a natural continuation of auths init, similar to how we proposed CI signing setup in feat: integrate CI signing setup into auths init #142

Proposed UX

Interactive prompt at end of auths init

Identity created successfully. Git signing configured.

Would you like to set up GitHub signature verification? (y/N)

If yes:

  1. Export the public key automatically
  2. Detect the GitHub username (from gh auth status or git config)
  3. Attempt to add the key via gh ssh-key add --type signing if gh CLI is available
  4. Fall back to printing the key and opening the GitHub settings URL if gh is unavailable

Standalone: auths init --github

For users who skipped during init or set up a new GitHub account later. Assumes an existing identity.

Standalone: auths github setup (or similar)

Dedicated command for adding the signing key to GitHub at any time.

Design questions to resolve

1. Platform detection

Similar to #142, this should support multiple forges:

  • GitHubgh ssh-key add --type signing or manual instructions
  • GitLabglab CLI or manual instructions (Settings > SSH Keys > Usage type: Signing)
  • Other — print the public key and explain where to add it

Auto-detect from git remote URL, or ask interactively.

2. Email matching

GitHub requires git config user.email to match the email on the GitHub account. The init flow should:

  • Check git config user.email is set
  • Warn if it doesn't match the GitHub account email (detectable via gh api user)

3. Key already added

If the signing key is already on GitHub, skip gracefully rather than erroring.

4. Multiple remotes / accounts

Users may have personal and work GitHub accounts. The flow should handle this or at minimum not break.

Implementation plan

  1. SDK workflow: GitHubVerificationWorkflow — export public key, detect forge from remote URL, validate email config. Returns the public key and instructions.
  2. Platform adapters: Trait for adding signing keys, with implementations for GitHub (gh), GitLab (glab), and manual (print key + URL).
  3. CLI integration: Add --github flag to auths init. Add auths github setup command. Add interactive prompt at end of init.

References

  • Related: feat: integrate CI signing setup into auths init #142 (CI signing setup during init)
  • Current docs: docs/guides/git/signing-configuration.md ("GitHub Signature Verification" section)
  • GitHub docs: Settings > SSH and GPG keys > New SSH key (key type: Signing Key)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions