diff --git a/README.md b/README.md index f969916..4337932 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,28 @@ jobs: body: "Hello, World!" ``` +### Create a token for an enterprise installation + +```yaml +on: [workflow_dispatch] + +jobs: + hello-world: + runs-on: ubuntu-latest + steps: + - uses: actions/create-github-app-token@v2 + id: app-token + with: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.PRIVATE_KEY }} + enterprise: my-enterprise-slug + - name: Call enterprise management REST API with gh + run: | + gh api /enterprises/my-enterprise-slug/apps/installable_organizations + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} +``` + ### Create a token with specific permissions > [!NOTE] @@ -335,6 +357,13 @@ steps: > [!NOTE] > If `owner` is set and `repositories` is empty, access will be scoped to all repositories in the provided repository owner's installation. If `owner` and `repositories` are empty, access will be scoped to only the current repository. +### `enterprise` + +**Optional:** The slug of the enterprise to generate a token for enterprise-level app installations. + +> [!NOTE] +> The `enterprise` input is mutually exclusive with `owner` and `repositories`. GitHub Apps can be installed on enterprise accounts with permissions that let them call enterprise management APIs. Enterprise installations do not grant access to organization or repository resources. + ### `permission-` **Optional:** The permissions to grant to the token. By default, the token inherits all of the installation's permissions. We recommend to explicitly list the permissions that are required for a use case. This follows GitHub's own recommendation to [control permissions of `GITHUB_TOKEN` in workflows](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token). The documentation also lists all available permissions, just prefix the permission key with `permission-` (e.g., `pull-requests` → `permission-pull-requests`). diff --git a/tests/main-enterprise-installation-not-found.test.js b/tests/main-enterprise-installation-not-found.test.js new file mode 100644 index 0000000..ca27b31 --- /dev/null +++ b/tests/main-enterprise-installation-not-found.test.js @@ -0,0 +1,39 @@ +import { test } from "./main.js"; +delete process.env.INPUT_OWNER; +delete process.env.INPUT_REPOSITORIES; + +// Verify `main` handles when no enterprise installation is found. +await test((mockPool) => { + process.env.INPUT_ENTERPRISE = "test-enterprise"; + + + // Mock the /app/installations endpoint to return only non-enterprise installations + mockPool + .intercept({ + path: "/app/installations", + method: "GET", + headers: { + accept: "application/vnd.github.v3+json", + "user-agent": "actions/create-github-app-token", + // Intentionally omitting the `authorization` header, since JWT creation is not idempotent. + }, + }) + .reply( + 200, + [ + { + id: "111111", + app_slug: "github-actions", + target_type: "Organization", + account: { login: "some-org" } + }, + { + id: "222222", + app_slug: "github-actions", + target_type: "User", + account: { login: "some-user" } + } + ], + { headers: { "content-type": "application/json" } } + ); +}); diff --git a/tests/main-enterprise-mutual-exclusivity-both.test.js b/tests/main-enterprise-mutual-exclusivity-both.test.js new file mode 100644 index 0000000..f4b5e3b --- /dev/null +++ b/tests/main-enterprise-mutual-exclusivity-both.test.js @@ -0,0 +1,16 @@ +import { DEFAULT_ENV } from "./main.js"; + +// Verify `main` exits with an error when `enterprise` is used with both `owner` and `repositories` inputs. +try { + // Set up environment with enterprise, owner, and repositories all set + for (const [key, value] of Object.entries(DEFAULT_ENV)) { + process.env[key] = value; + } + process.env.INPUT_ENTERPRISE = "test-enterprise"; + process.env.INPUT_OWNER = "test-owner"; + process.env.INPUT_REPOSITORIES = "repo1,repo2"; + + await import("../main.js"); +} catch (error) { + console.error(error.message); +} diff --git a/tests/main-enterprise-mutual-exclusivity-owner.test.js b/tests/main-enterprise-mutual-exclusivity-owner.test.js new file mode 100644 index 0000000..59ec637 --- /dev/null +++ b/tests/main-enterprise-mutual-exclusivity-owner.test.js @@ -0,0 +1,15 @@ +import { DEFAULT_ENV } from "./main.js"; + +// Verify `main` exits with an error when `enterprise` is used with `owner` input. +try { + // Set up environment with enterprise and owner both set + for (const [key, value] of Object.entries(DEFAULT_ENV)) { + process.env[key] = value; + } + process.env.INPUT_ENTERPRISE = "test-enterprise"; + process.env.INPUT_OWNER = "test-owner"; + + await import("../main.js"); +} catch (error) { + console.error(error.message); +} diff --git a/tests/main-enterprise-mutual-exclusivity-repositories.test.js b/tests/main-enterprise-mutual-exclusivity-repositories.test.js new file mode 100644 index 0000000..893c7de --- /dev/null +++ b/tests/main-enterprise-mutual-exclusivity-repositories.test.js @@ -0,0 +1,15 @@ +import { DEFAULT_ENV } from "./main.js"; + +// Verify `main` exits with an error when `enterprise` is used with `repositories` input. +try { + // Set up environment with enterprise and repositories both set + for (const [key, value] of Object.entries(DEFAULT_ENV)) { + process.env[key] = value; + } + process.env.INPUT_ENTERPRISE = "test-enterprise"; + process.env.INPUT_REPOSITORIES = "repo1,repo2"; + + await import("../main.js"); +} catch (error) { + console.error(error.message); +} diff --git a/tests/main-enterprise-only-success.test.js b/tests/main-enterprise-only-success.test.js new file mode 100644 index 0000000..dae89bc --- /dev/null +++ b/tests/main-enterprise-only-success.test.js @@ -0,0 +1,34 @@ +import { test } from "./main.js"; + +// Verify `main` successfully obtains a token when only the `enterprise` input is set. +await test((mockPool) => { + process.env.INPUT_ENTERPRISE = "test-enterprise"; + delete process.env.INPUT_OWNER; + delete process.env.INPUT_REPOSITORIES; + + // Mock the /app/installations endpoint to return an enterprise installation + const mockInstallationId = "123456"; + const mockAppSlug = "github-actions"; + mockPool + .intercept({ + path: "/app/installations", + method: "GET", + headers: { + accept: "application/vnd.github.v3+json", + "user-agent": "actions/create-github-app-token", + // Intentionally omitting the `authorization` header, since JWT creation is not idempotent. + }, + }) + .reply( + 200, + [ + { + id: mockInstallationId, + app_slug: mockAppSlug, + target_type: "Enterprise", + account: { login: "test-enterprise" } + } + ], + { headers: { "content-type": "application/json" } } + ); +}); diff --git a/tests/main-enterprise-token-success.test.js b/tests/main-enterprise-token-success.test.js new file mode 100644 index 0000000..197348e --- /dev/null +++ b/tests/main-enterprise-token-success.test.js @@ -0,0 +1,34 @@ +import { test } from "./main.js"; + +// Verify `main` successfully generates enterprise token with basic functionality. +await test((mockPool) => { + process.env.INPUT_ENTERPRISE = "test-enterprise"; + delete process.env.INPUT_OWNER; + delete process.env.INPUT_REPOSITORIES; + + // Mock the /app/installations endpoint to return an enterprise installation + const mockInstallationId = "123456"; + const mockAppSlug = "github-actions"; + mockPool + .intercept({ + path: "/app/installations", + method: "GET", + headers: { + accept: "application/vnd.github.v3+json", + "user-agent": "actions/create-github-app-token", + // Intentionally omitting the `authorization` header, since JWT creation is not idempotent. + }, + }) + .reply( + 200, + [ + { + id: mockInstallationId, + app_slug: mockAppSlug, + target_type: "Enterprise", + account: { login: "test-enterprise" } + } + ], + { headers: { "content-type": "application/json" } } + ); +}); diff --git a/tests/main-enterprise-token-with-permissions.test.js b/tests/main-enterprise-token-with-permissions.test.js new file mode 100644 index 0000000..ab2a160 --- /dev/null +++ b/tests/main-enterprise-token-with-permissions.test.js @@ -0,0 +1,36 @@ +import { test } from "./main.js"; + +// Verify `main` successfully generates enterprise token with specific permissions. +await test((mockPool) => { + process.env.INPUT_ENTERPRISE = "test-enterprise"; + delete process.env.INPUT_OWNER; + delete process.env.INPUT_REPOSITORIES; + process.env["INPUT_PERMISSION-ENTERPRISE-ORGANIZATIONS"] = "read"; + process.env["INPUT_PERMISSION-ENTERPRISE-PEOPLE"] = "write"; + + // Mock the /app/installations endpoint to return an enterprise installation + const mockInstallationId = "123456"; + const mockAppSlug = "github-actions"; + mockPool + .intercept({ + path: "/app/installations", + method: "GET", + headers: { + accept: "application/vnd.github.v3+json", + "user-agent": "actions/create-github-app-token", + // Intentionally omitting the `authorization` header, since JWT creation is not idempotent. + }, + }) + .reply( + 200, + [ + { + id: mockInstallationId, + app_slug: mockAppSlug, + target_type: "Enterprise", + account: { login: "test-enterprise" } + } + ], + { headers: { "content-type": "application/json" } } + ); +}); diff --git a/tests/snapshots/index.js.md b/tests/snapshots/index.js.md index e419536..dfd7473 100644 --- a/tests/snapshots/index.js.md +++ b/tests/snapshots/index.js.md @@ -39,6 +39,99 @@ Generated by [AVA](https://avajs.dev). POST /api/v3/app/installations/123456/access_tokens␊ {"repositories":["create-github-app-token"]}` +## main-enterprise-only-success.test.js + +> stderr + + '' + +> stdout + + `Creating enterprise installation token for enterprise "test-enterprise".␊ + ### Found enterprise installation: {␊ + "id": "123456",␊ + "app_slug": "github-actions",␊ + "target_type": "Enterprise",␊ + "account": {␊ + "login": "test-enterprise"␊ + }␊ + }␊ + ::add-mask::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=installation-id::123456␊ + ␊ + ::set-output name=app-slug::github-actions␊ + ::save-state name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ::save-state name=expiresAt::2016-07-11T22:14:10Z␊ + --- REQUESTS ---␊ + GET /app/installations␊ + POST /app/installations/123456/access_tokens␊ + null` + +## main-enterprise-token-success.test.js + +> stderr + + '' + +> stdout + + `Creating enterprise installation token for enterprise "test-enterprise".␊ + ### Found enterprise installation: {␊ + "id": "123456",␊ + "app_slug": "github-actions",␊ + "target_type": "Enterprise",␊ + "account": {␊ + "login": "test-enterprise"␊ + }␊ + }␊ + ::add-mask::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=installation-id::123456␊ + ␊ + ::set-output name=app-slug::github-actions␊ + ::save-state name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ::save-state name=expiresAt::2016-07-11T22:14:10Z␊ + --- REQUESTS ---␊ + GET /app/installations␊ + POST /app/installations/123456/access_tokens␊ + null` + +## main-enterprise-token-with-permissions.test.js + +> stderr + + '' + +> stdout + + `Creating enterprise installation token for enterprise "test-enterprise".␊ + ### Found enterprise installation: {␊ + "id": "123456",␊ + "app_slug": "github-actions",␊ + "target_type": "Enterprise",␊ + "account": {␊ + "login": "test-enterprise"␊ + }␊ + }␊ + ::add-mask::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ␊ + ::set-output name=installation-id::123456␊ + ␊ + ::set-output name=app-slug::github-actions␊ + ::save-state name=token::ghs_16C7e42F292c6912E7710c838347Ae178B4a␊ + ::save-state name=expiresAt::2016-07-11T22:14:10Z␊ + --- REQUESTS ---␊ + GET /app/installations␊ + POST /app/installations/123456/access_tokens␊ + {"permissions":{"enterprise_organizations":"read","enterprise_people":"write"}}` + ## main-missing-owner.test.js > stderr diff --git a/tests/snapshots/index.js.snap b/tests/snapshots/index.js.snap index 773f4b1..edde164 100644 Binary files a/tests/snapshots/index.js.snap and b/tests/snapshots/index.js.snap differ