From 265a1dc4e61abf9ed76e05df66743e13504811d0 Mon Sep 17 00:00:00 2001 From: Bryan Gin-ge Chen Date: Tue, 23 Jun 2026 22:40:56 -0400 Subject: [PATCH 1/2] docs: some edits to github-apps-setup --- docs/github-apps/github-apps-setup.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/github-apps/github-apps-setup.md b/docs/github-apps/github-apps-setup.md index dbad380..99aac82 100644 --- a/docs/github-apps/github-apps-setup.md +++ b/docs/github-apps/github-apps-setup.md @@ -6,14 +6,18 @@ - Record its App ID. - Generate one [private key PEM](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) (from GitHub App settings). You need this once to seed the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). - 2. Put the app signing key in Azure Key Vault. + 2. (Optional) Create an [Environment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) in the repo via the repo settings. + - Set up deployment branches and tags that you want the app to be able to run from. (For scheduled jobs, or jobs triggered by `wokrflow_dispatch`, typically `master`.) + - Later, we will add some secrets or variables to the environment (see step 6). + + 3. Put the app signing key in Azure Key Vault. - Create/import a key. Conventionally we name them `-app-pk`. - Import the GitHub PEM into a Key Vault key. - If you want strict pinning/rotation control, note the key version and pass key-version in workflow later. - Delete your local version of the key - 3. Create (or pick an existing) [Entra app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). + 4. Create (or pick an existing) [Entra app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). - Reuse an existing entra app if appropriate or create a new one. See [entra-apps.md](entra-apps.md) for details on existing Entra apps. - Add [federated credentials for GitHub Actions](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect): @@ -21,15 +25,24 @@ - Audience: api://AzureADTokenExchange - Use flexible claim matching for your repo/workflow/ref scope (recommended). - 4. Grant [Key Vault RBAC](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) to that Entra app. + If you created an environment: + - For the entity type, choose "Environment" and enter the name of the environment you created in step 2. + + Otherwise, you probably want to use "Branch" and input the name of the branch that's allowed (typically `master`). + + 5. Grant [Key Vault RBAC](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) to that Entra app. - Grant the [Key Vault Crypto User](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) role (this allows signing). - Scope as tightly as possible: grant permission only for the particular key rather than the whole Key Vault. + - To do this, navigate to the Key Vault, then Keys, then select the specific Key and add via the "Access Control (IAM)" page - 5. Add GitHub repo config + 6. Add GitHub repo config - Secret: `_APP_ID` (repo convention keeps app IDs in secrets). - - Variable: `GH_APP_AZURE_CLIENT_ID_` (new or existing grouping variable). Consider adding it as an [organization-wide variable](https://github.com/organizations/leanprover-community/settings/variables/actions) if it might be reused by other repos (e.g., `mathlib4-nightly-testing`) + - Variable: `GH_APP_AZURE_CLIENT_ID_` (new or existing grouping variable). This is the "Application (client) ID" of the Entra App you registered in step 4. + Consider adding it as an [organization-wide variable](https://github.com/organizations/leanprover-community/settings/variables/actions) if it might be reused by other repos (e.g., `mathlib4-nightly-testing`). + + If you created an environment in step 2, you can put these in the environment you created instead of the repo secrets. These: - Secret: `LPC_AZ_TENANT_ID` @@ -37,7 +50,7 @@ should already be available as [organization-wide values](https://github.com/organizations/leanprover-community/settings/variables/actions). - 6. Update workflow to mint token via Azure action. + 7. Update workflow to mint token via Azure action. ``` permissions: @@ -60,4 +73,4 @@ # repositories: mathlib4 # jwt-expiration-seconds: "540" ``` - 7. Validate. + 8. Validate. From ae470b94c462c4e4f127f0781ff61c22d7970bde Mon Sep 17 00:00:00 2001 From: Bryan Gin-ge Chen Date: Thu, 25 Jun 2026 14:02:01 -0400 Subject: [PATCH 2/2] address review --- docs/github-apps/github-apps-setup.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/github-apps/github-apps-setup.md b/docs/github-apps/github-apps-setup.md index 99aac82..7db7754 100644 --- a/docs/github-apps/github-apps-setup.md +++ b/docs/github-apps/github-apps-setup.md @@ -6,10 +6,17 @@ - Record its App ID. - Generate one [private key PEM](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps) (from GitHub App settings). You need this once to seed the [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview). - 2. (Optional) Create an [Environment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) in the repo via the repo settings. + 2. (Recommended) Create an [Environment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) in the repo via the repo settings. - Set up deployment branches and tags that you want the app to be able to run from. (For scheduled jobs, or jobs triggered by `wokrflow_dispatch`, typically `master`.) - Later, we will add some secrets or variables to the environment (see step 6). + In the GitHub workflow that will use the GitHub app, add the following: +```yaml +environment: + name: + deployment: false +``` + 3. Put the app signing key in Azure Key Vault. - Create/import a key. Conventionally we name them `-app-pk`. @@ -52,7 +59,7 @@ 7. Update workflow to mint token via Azure action. -``` +```yaml permissions: id-token: write contents: read # only if this job needs checkout/ repo reads