GitHub App documentation should contain clear examples of how to use keys in AKV as sign-only

[MattHyman]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

• https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#storing-private-keys)
• https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app#private-keys

What part(s) of the article would you like to see updated?

In two places in GitHub app docs, here and here, there is a statement that "Consider storing your GitHub App's private key in a key vault, such as Azure Key Vault, and making it sign-only." As previously discussed, this information is provided without an example of how to do this.

This can now be done with az keyvault key sign, likely due to a recent fix in this space. This documentation should be updated with clear examples of how to do this, comparable to what already exists for JWT tokens.

Additional information

This is a documentation improvement related to GitHub app security.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Sharra-writes]

@MattHyman Thanks for opening an issue! I'll bring this up with the relevant teams and let you know how they want to handle it.

[Sharra-writes]

@MattHyman I brought this up to the docs team, and they're wary of documenting something that isn't our product, where we have no control over when the steps for doing things change, and no advance warning. JWTs aren't entirely comparable because that isn't tied to a specific product. An alternative might be linking to more comprehensive Microsoft documentation of the subject, if you happen to know of any.

[MattHyman]

I agree that there can be better documentation here on the AKV signing. The closet they currently have is for JavaScript. I have filled a feedback item on producing the documentation you are requesting.

[Sharra-writes]

@MattHyman I'll mark this issue as never-stale and keep it open so we can keep an eye on if that happens.

[Renher11]

Hi, I’m new here. The docs say to store private keys in Azure Key Vault as sign-only, but I don’t see an example. Can you add one using az keyvault key sign? Btw nevermind, i might not be interested in this topic sometime haha

[Sharra-writes]

@Renher11 The docs team is wary of documenting products that don't belong to GitHub, since we have no way of monitoring upcoming changes to how they're used. Matt is hoping Microsoft can provide some documentation that we can then link to, because we would love to be able to link to Microsoft's documentation, and that's what this issue is open to keep an eye on.

[omenaijessica17]

I am new here and I don't really understand things here please can you help me out a little

[subatoi]

@MattHyman I'm going to go ahead and close this one out per the above comment from last year, but please feel free to open a new issue to revisit this in future. Thank you very much