@cloudsnorkel/cdk-github-runners 0.0.13 → 0.1.1

package/.jsii

@@ -2995,7 +2995,7 @@
   },
   "name": "@cloudsnorkel/cdk-github-runners",
   "readme": {
-    "markdown": "# GitHub Self-Hosted Runners CDK Constructs\n\n[![NPM](https://img.shields.io/npm/v/@cloudsnorkel/cdk-github-runners?label=npm&logo=npm)][6]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][7]\n[![Maven Central](https://img.shields.io/maven-central/v/com.cloudsnorkel/cdk.github.runners.svg?label=Maven%20Central&logo=java)][8]\n[![Go](https://img.shields.io/github/v/tag/CloudSnorkel/cdk-github-runners?color=red&label=go&logo=go)][11]\n[![Nuget](https://img.shields.io/nuget/v/CloudSnorkel.Cdk.Github.Runners?color=red&&logo=nuget)][12]\n[![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)\n\nUse this CDK construct to create ephemeral [self-hosted GitHub runners][1] on-demand inside your AWS account.\n\n* Easy to configure GitHub integration\n* Customizable runners with decent defaults\n* Supports multiple runner configurations controlled by labels\n* Everything fully hosted in your account\n\nSelf-hosted runners in AWS are useful when:\n\n* You need easy access to internal resources in your actions\n* You want to pre-install some software for your actions\n* You want to provide some basic AWS API access ([aws-actions/configure-aws-credentials][2] has more security controls)\n\nEphemeral runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.\n\n## API\n\nDocumentation of available constructs and their interface is available on [Constructs Hub][13] in all supported programming languages.\n\n## Providers\n\nA runner provider creates compute resources on-demand and uses [actions/runner][5] to start a runner.\n\n| Provider  | Time limit               | vCPUs                    | RAM                               | Storage                      | sudo | Docker |\n|-----------|--------------------------|--------------------------|-----------------------------------|------------------------------|------|--------|\n| CodeBuild | 8 hours (default 1 hour) | 2 (default), 4, 8, or 72 | 3gb (default), 7gb, 15gb or 145gb | 50gb to 824gb (default 64gb) | ✔    | ✔     |\n| Fargate   | Unlimited                | 0.25 to 4 (default 1)    | 512mb to 30gb (default 2gb)       | 20gb to 200gb (default 25gb) | ✔    | ❌    |\n| Lambda    | 15 minutes               | 1 to 6 (default 2)       | 128mb to 10gb (default 2gb)       | Up to 10gb (default 10gb)    | ❌    | ❌     |\n\nThe best provider to use mostly depends on your current infrastructure. When in doubt, CodeBuild is always a good choice. Execution history and logs are easy to view, and it has no restrictive limits unless you need to run for more than 8 hours.\n\nYou can also create your own provider by implementing `IRunnerProvider`.\n\n## Installation\n\n1. Confirm you're using CDK v2\n2. Install the appropriate package\n   1. [Python][6]\n      ```\n      pip install cloudsnorkel.cdk-github-runners\n      ```\n   2. [TypeScript or JavaScript][7]\n      ```\n      npm i @cloudsnorkel/cdk-github-runners\n      ```\n   3. [Java][8]\n      ```xml\n      <dependency>\n      <groupId>com.cloudsnorkel</groupId>\n      <artifactId>cdk.github.runners</artifactId>\n      </dependency>\n      ```\n   4. [Go][11]\n      ```\n      go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n      ```\n   5. [.NET][12]\n      ```\n      dotnet add package CloudSnorkel.Cdk.Github.Runners\n      ```\n3. Use `GitHubRunners` construct in your code (starting with default arguments is fine)\n4. Deploy your stack\n5. Look for the status command output similar to `aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json`\n6. Execute the status command (you may need to specify `--profile` too) and open the resulting `status.json` file\n7. [Setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token\n8. Run status command again to confirm `github.auth.status` and `github.webhook.status` are OK\n9. Trigger a GitHub action that has a `self-hosted` label with `runs-on: [self-hosted, linux, codebuild]` or similar\n10. If the action is not successful, see [troubleshooting](#Troubleshooting)\n\n## Customizing\n\nThe default providers configured by [`GitHubRunners`](https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/v/0.0.11/api/GitHubRunners?lang=typescript) are useful for testing but probably not too much for actual production work. They run in the default VPC or no VPC and have no added IAM permissions. You would usually want to configure the providers yourself.\n\nFor example:\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { aws_ec2 as ec2, aws_s3 as s3 } from 'aws-cdk-lib';\nimport { GitHubRunners, CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(\n  app,\n  'github-runners-test',\n  {\n     env: {\n        account: process.env.CDK_DEFAULT_ACCOUNT,\n        region: process.env.CDK_DEFAULT_REGION,\n     },\n  },\n);\n\nconst vpc = ec2.Vpc.fromLookup(stack, 'vpc', { vpcId: 'vpc-1234567' });\nconst runnerSg = new ec2.SecurityGroup(stack, 'runner security group', { vpc: vpc });\nconst dbSg = ec2.SecurityGroup.fromSecurityGroupId(stack, 'database security group', 'sg-1234567');\nconst bucket = new s3.Bucket(stack, 'runner bucket');\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunner(\n  stack, 'codebuild runner',\n  {\n     label: 'my-codebuild',\n     vpc: vpc,\n     securityGroup: runnerSg,\n  },\n);\n// grant some permissions to the provider\nbucket.grantReadWrite(myProvider);\ndbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database');\n\n// create the runner infrastructure\nnew GitHubRunners(\n  stack,\n  'runners',\n  {\n    providers: [myProvider],\n    defaultProviderLabel: 'my-codebuild',\n  }\n);\n\napp.synth();\n```\n\n## Architecture\n\n![Architecture diagram](architecture.svg)\n\n## Troubleshooting\n\n1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK\n2. Confirm the webhook Lambda was called by visiting the URL in `troubleshooting.webhookHandlerUrl` from `status.json`\n   1. If it's not called or logs errors, confirm the webhook settings on the GitHub side\n   2. If you see too many errors, make sure you're only sending `workflow_job` events\n3. Check execution details of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`\n   1. Use the details tab to find the specific execution of the provider (Lambda, CodeBuild, Fargate, etc.)\n   2. Every step function execution should be successful, even if the runner action inside it failed\n\n## Other Options\n\n1. [philips-labs/terraform-aws-github-runner][3] if you're using Terraform\n2. [actions-runner-controller/actions-runner-controller][4] if you're using Kubernetes\n\n\n[1]: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners\n[2]: https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions\n[3]: https://github.com/philips-labs/terraform-aws-github-runner\n[4]: https://github.com/actions-runner-controller/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://www.npmjs.com/package/@cloudsnorkel/cdk-github-runners\n[7]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[8]: https://search.maven.org/search?q=g:%22com.cloudsnorkel%22%20AND%20a:%22cdk.github.runners%22\n[9]: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps\n[10]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n[11]: https://pkg.go.dev/github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n[12]: https://www.nuget.org/packages/CloudSnorkel.Cdk.Github.Runners/\n[13]: https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/\n[14]: https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling"
+    "markdown": "# GitHub Self-Hosted Runners CDK Constructs\n\n[![NPM](https://img.shields.io/npm/v/@cloudsnorkel/cdk-github-runners?label=npm&logo=npm)][6]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][7]\n[![Maven Central](https://img.shields.io/maven-central/v/com.cloudsnorkel/cdk.github.runners.svg?label=Maven%20Central&logo=java)][8]\n[![Go](https://img.shields.io/github/v/tag/CloudSnorkel/cdk-github-runners?color=red&label=go&logo=go)][11]\n[![Nuget](https://img.shields.io/nuget/v/CloudSnorkel.Cdk.Github.Runners?color=red&&logo=nuget)][12]\n[![Release](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml/badge.svg)](https://github.com/CloudSnorkel/cdk-github-runners/actions/workflows/release.yml)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)\n\nUse this CDK construct to create ephemeral [self-hosted GitHub runners][1] on-demand inside your AWS account.\n\n* Easy to configure GitHub integration with a web-based interface\n* Customizable runners with decent defaults\n* Multiple runner configurations controlled by labels\n* Everything fully hosted in your account\n\nSelf-hosted runners in AWS are useful when:\n\n* You need easy access to internal resources in your actions\n* You want to pre-install some software for your actions\n* You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials][2] has more security controls)\n\nEphemeral (or on-demand) runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.\n\n## API\n\nThe best way to browse API documentation is on [Constructs Hub][13]. It is available in all supported programming languages.\n\n## Providers\n\nA runner provider creates compute resources on-demand and uses [actions/runner][5] to start a runner.\n\n| Provider  | Time limit               | vCPUs                    | RAM                               | Storage                      | sudo | Docker |\n|-----------|--------------------------|--------------------------|-----------------------------------|------------------------------|------|--------|\n| CodeBuild | 8 hours (default 1 hour) | 2 (default), 4, 8, or 72 | 3gb (default), 7gb, 15gb or 145gb | 50gb to 824gb (default 64gb) | ✔    | ✔     |\n| Fargate   | Unlimited                | 0.25 to 4 (default 1)    | 512mb to 30gb (default 2gb)       | 20gb to 200gb (default 25gb) | ✔    | ❌    |\n| Lambda    | 15 minutes               | 1 to 6 (default 2)       | 128mb to 10gb (default 2gb)       | Up to 10gb (default 10gb)    | ❌    | ❌     |\n\nThe best provider to use mostly depends on your current infrastructure. When in doubt, CodeBuild is always a good choice. Execution history and logs are easy to view, and it has no restrictive limits unless you need to run for more than 8 hours.\n\nYou can also create your own provider by implementing `IRunnerProvider`.\n\n## Installation\n\n1. Confirm you're using CDK v2\n2. Install the appropriate package\n   1. [Python][6]\n      ```\n      pip install cloudsnorkel.cdk-github-runners\n      ```\n   2. [TypeScript or JavaScript][7]\n      ```\n      npm i @cloudsnorkel/cdk-github-runners\n      ```\n   3. [Java][8]\n      ```xml\n      <dependency>\n      <groupId>com.cloudsnorkel</groupId>\n      <artifactId>cdk.github.runners</artifactId>\n      </dependency>\n      ```\n   4. [Go][11]\n      ```\n      go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n      ```\n   5. [.NET][12]\n      ```\n      dotnet add package CloudSnorkel.Cdk.Github.Runners\n      ```\n3. Use `GitHubRunners` construct in your code (starting with default arguments is fine)\n4. Deploy your stack\n5. Look for the status command output similar to `aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json`\n6. Execute the status command (you may need to specify `--profile` too) and open the resulting `status.json` file\n7. Open the URL in `github.setup.url` from `status.json` or [manually setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token\n8. Run status command again to confirm `github.auth.status` and `github.webhook.status` are OK\n9. Trigger a GitHub action that has a `self-hosted` label with `runs-on: [self-hosted, linux, codebuild]` or similar\n10. If the action is not successful, see [troubleshooting](#Troubleshooting)\n\n## Customizing\n\nThe default providers configured by [`GitHubRunners`](https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/v/0.0.11/api/GitHubRunners?lang=typescript) are useful for testing but probably not too much for actual production work. They run in the default VPC or no VPC and have no added IAM permissions. You would usually want to configure the providers yourself.\n\nFor example:\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { aws_ec2 as ec2, aws_s3 as s3 } from 'aws-cdk-lib';\nimport { GitHubRunners, CodeBuildRunner } from '@cloudsnorkel/cdk-github-runners';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(\n  app,\n  'github-runners-test',\n  {\n     env: {\n        account: process.env.CDK_DEFAULT_ACCOUNT,\n        region: process.env.CDK_DEFAULT_REGION,\n     },\n  },\n);\n\nconst vpc = ec2.Vpc.fromLookup(stack, 'vpc', { vpcId: 'vpc-1234567' });\nconst runnerSg = new ec2.SecurityGroup(stack, 'runner security group', { vpc: vpc });\nconst dbSg = ec2.SecurityGroup.fromSecurityGroupId(stack, 'database security group', 'sg-1234567');\nconst bucket = new s3.Bucket(stack, 'runner bucket');\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunner(\n  stack, 'codebuild runner',\n  {\n     label: 'my-codebuild',\n     vpc: vpc,\n     securityGroup: runnerSg,\n  },\n);\n// grant some permissions to the provider\nbucket.grantReadWrite(myProvider);\ndbSg.connections.allowFrom(runnerSg, ec2.Port.tcp(3306), 'allow runners to connect to MySQL database');\n\n// create the runner infrastructure\nnew GitHubRunners(\n  stack,\n  'runners',\n  {\n    providers: [myProvider],\n    defaultProviderLabel: 'my-codebuild',\n  }\n);\n\napp.synth();\n```\n\n## Architecture\n\n![Architecture diagram](architecture.svg)\n\n## Troubleshooting\n\n1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK\n2. Confirm the webhook Lambda was called by visiting the URL in `troubleshooting.webhookHandlerUrl` from `status.json`\n   1. If it's not called or logs errors, confirm the webhook settings on the GitHub side\n   2. If you see too many errors, make sure you're only sending `workflow_job` events\n3. When using GitHub app, make sure there are active installation in `github.auth.app.installations`\n4. Check execution details of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`\n   1. Use the details tab to find the specific execution of the provider (Lambda, CodeBuild, Fargate, etc.)\n   2. Every step function execution should be successful, even if the runner action inside it failed\n\n## Other Options\n\n1. [philips-labs/terraform-aws-github-runner][3] if you're using Terraform\n2. [actions-runner-controller/actions-runner-controller][4] if you're using Kubernetes\n\n\n[1]: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners\n[2]: https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions\n[3]: https://github.com/philips-labs/terraform-aws-github-runner\n[4]: https://github.com/actions-runner-controller/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://www.npmjs.com/package/@cloudsnorkel/cdk-github-runners\n[7]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[8]: https://search.maven.org/search?q=g:%22com.cloudsnorkel%22%20AND%20a:%22cdk.github.runners%22\n[9]: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps\n[10]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n[11]: https://pkg.go.dev/github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners\n[12]: https://www.nuget.org/packages/CloudSnorkel.Cdk.Github.Runners/\n[13]: https://constructs.dev/packages/@cloudsnorkel/cdk-github-runners/\n[14]: https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling"
   },
   "repository": {
     "type": "git",
@@ -3743,7 +3743,7 @@
         },
         "locationInModule": {
           "filename": "src/runner.ts",
-          "line": 93
+          "line": 95
         },
         "parameters": [
           {
@@ -3769,7 +3769,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 73
+        "line": 74
       },
       "name": "GitHubRunners",
       "properties": [
@@ -3781,7 +3781,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 83
+            "line": 84
           },
           "name": "defaultProvider",
           "type": {
@@ -3795,7 +3795,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 93
+            "line": 95
           },
           "name": "props",
           "type": {
@@ -3810,7 +3810,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 78
+            "line": 79
           },
           "name": "providers",
           "type": {
@@ -3830,7 +3830,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 88
+            "line": 89
           },
           "name": "secrets",
           "type": {
@@ -3851,7 +3851,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 15
+        "line": 16
       },
       "name": "GitHubRunnersProps",
       "properties": [
@@ -3866,7 +3866,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 22
+            "line": 23
           },
           "name": "defaultProviderLabel",
           "optional": true,
@@ -3885,7 +3885,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 29
+            "line": 30
           },
           "name": "providers",
           "optional": true,
@@ -4598,7 +4598,7 @@
         },
         "locationInModule": {
           "filename": "src/secrets.ts",
-          "line": 29
+          "line": 34
         },
         "parameters": [
           {
@@ -4640,7 +4640,7 @@
         },
         {
           "docs": {
-            "remarks": "This secret is meant to be edited by the user after being created.",
+            "remarks": "This secret is meant to be edited by the user after being created. It is separate than the main GitHub secret because inserting private keys into JSON is hard.",
             "stability": "experimental",
             "summary": "GitHub app private key. Not needed when using personal authentication tokens."
           },
@@ -4654,6 +4654,22 @@
             "fqn": "aws-cdk-lib.aws_secretsmanager.Secret"
           }
         },
+        {
+          "docs": {
+            "remarks": "Should be empty after setup has been completed.",
+            "stability": "experimental",
+            "summary": "Setup secret used to authenticate user for our setup wizard."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/secrets.ts",
+            "line": 32
+          },
+          "name": "setup",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_secretsmanager.Secret"
+          }
+        },
         {
           "docs": {
             "stability": "experimental",
@@ -4673,6 +4689,6 @@
       "symbolId": "src/secrets:Secrets"
     }
   },
-  "version": "0.0.13",
-  "fingerprint": "HWkQX0qLnjcLcPlC1yPdvDaoLc3rEPauFhw6KoEa4fg="
+  "version": "0.1.1",
+  "fingerprint": "yldbg+9mKQVf9f26Ci6T0YQ+04c90i5jyGEi+VVliCk="
 }

package/API.md

@@ -924,6 +924,7 @@ Any object.
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets.property.node">node</a></code> | <code>constructs.Node</code> | The tree node. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets.property.github">github</a></code> | <code>aws-cdk-lib.aws_secretsmanager.Secret</code> | Authentication secret for GitHub containing either app details or personal authentication token. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets.property.githubPrivateKey">githubPrivateKey</a></code> | <code>aws-cdk-lib.aws_secretsmanager.Secret</code> | GitHub app private key. Not needed when using personal authentication tokens. |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets.property.setup">setup</a></code> | <code>aws-cdk-lib.aws_secretsmanager.Secret</code> | Setup secret used to authenticate user for our setup wizard. |
 | <code><a href="#@cloudsnorkel/cdk-github-runners.Secrets.property.webhook">webhook</a></code> | <code>aws-cdk-lib.aws_secretsmanager.Secret</code> | Webhook secret used to confirm events are coming from GitHub and nowhere else. |
 
 ---
@@ -967,7 +968,21 @@ public readonly githubPrivateKey: Secret;
 
 GitHub app private key. Not needed when using personal authentication tokens.
 
-This secret is meant to be edited by the user after being created.
+This secret is meant to be edited by the user after being created. It is separate than the main GitHub secret because inserting private keys into JSON is hard.
+
+---
+
+##### `setup`<sup>Required</sup> <a name="setup" id="@cloudsnorkel/cdk-github-runners.Secrets.property.setup"></a>
+
+```typescript
+public readonly setup: Secret;
+```
+
+- *Type:* aws-cdk-lib.aws_secretsmanager.Secret
+
+Setup secret used to authenticate user for our setup wizard.
+
+Should be empty after setup has been completed.
 
 ---
 

package/README.md

@@ -10,22 +10,22 @@
 
 Use this CDK construct to create ephemeral [self-hosted GitHub runners][1] on-demand inside your AWS account.
 
-* Easy to configure GitHub integration
+* Easy to configure GitHub integration with a web-based interface
 * Customizable runners with decent defaults
-* Supports multiple runner configurations controlled by labels
+* Multiple runner configurations controlled by labels
 * Everything fully hosted in your account
 
 Self-hosted runners in AWS are useful when:
 
 * You need easy access to internal resources in your actions
 * You want to pre-install some software for your actions
-* You want to provide some basic AWS API access ([aws-actions/configure-aws-credentials][2] has more security controls)
+* You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials][2] has more security controls)
 
-Ephemeral runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
+Ephemeral (or on-demand) runners are the [recommended way by GitHub][14] for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.
 
 ## API
 
-Documentation of available constructs and their interface is available on [Constructs Hub][13] in all supported programming languages.
+The best way to browse API documentation is on [Constructs Hub][13]. It is available in all supported programming languages.
 
 ## Providers
 
@@ -72,7 +72,7 @@ You can also create your own provider by implementing `IRunnerProvider`.
 4. Deploy your stack
 5. Look for the status command output similar to `aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json`
 6. Execute the status command (you may need to specify `--profile` too) and open the resulting `status.json` file
-7. [Setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token
+7. Open the URL in `github.setup.url` from `status.json` or [manually setup GitHub](SETUP_GITHUB.md) integration as an app or with personal access token
 8. Run status command again to confirm `github.auth.status` and `github.webhook.status` are OK
 9. Trigger a GitHub action that has a `self-hosted` label with `runs-on: [self-hosted, linux, codebuild]` or similar
 10. If the action is not successful, see [troubleshooting](#Troubleshooting)
@@ -140,8 +140,9 @@ app.synth();
 1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
 2. Confirm the webhook Lambda was called by visiting the URL in `troubleshooting.webhookHandlerUrl` from `status.json`
    1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
-   2. If you see too many errors, make sure you're only sending `workflow_job` events 
-3. Check execution details of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`
+   2. If you see too many errors, make sure you're only sending `workflow_job` events
+3. When using GitHub app, make sure there are active installation in `github.auth.app.installations`
+4. Check execution details of the orchestrator step function by visiting the URL in `troubleshooting.stepFunctionUrl` from `status.json`
    1. Use the details tab to find the specific execution of the provider (Lambda, CodeBuild, Fargate, etc.)
    2. Every step function execution should be successful, even if the runner action inside it failed
 

package/SETUP_GITHUB.md

@@ -1,9 +1,23 @@
 # Setup GitHub
 
-Integration with GitHub can be done using an [app][9] or [personal access token][10]. Using an app allows more fine-grained access control. Personal access tokens are easier to set up but belong to a user instead of an organization.
+Integration with GitHub can be done using an [app](#app-authentication) or [personal access token](#personal-access-token). Using an app allows more fine-grained access control. Using an app is easier with the setup wizard.
 
 ## App Authentication
 
+### Setup Wizard
+
+1. Open the URL in `github.setup.url` from `status.json`
+2. If you want to create an app for your personal repositories, click the Create button under New Personal App
+3. If you want to create an app for your organization:
+   1. Find the New Organization App section
+   2. Type in the organization name in organization slug (ORGANIZATION from https://github.com/ORGANIZATION/REPO)
+   3. Click the Create button
+4. Follow the instructions on GitHub
+5. When brought back to the setup wizard, click the install link
+6. Install the new app on your desired repositories
+
+### Manually
+
 1. Decide if you want to create a personal app or an organization app
     1. For a personal app use https://github.com/settings/apps/new
     2. For an organization app use https://github.com/organizations/MY_ORG/settings/apps/new after replacing `MY_ORG` with your GitHub organization name
@@ -18,19 +32,11 @@ Integration with GitHub can be done using an [app][9] or [personal access token]
     1. Workflow job
 6. Under "Where can this GitHub App be installed?" select "Only on this account"
 7. Click the Create button
-8. From the new app page:
-    1. Write down the app id and client id
-    2. Click generate new client secret and write it down
-    3. Generate a private key and save the downloaded key
-9. On the top left go to Install App page and:
-    1. Install the app on the desired account or organization
-    2. Copy the installation id number from the URL and write it down (e.g. if the URL is https://github.com/settings/installations/123456, your installation id is 123456)
+8. From the new app page generate a private key and save the downloaded key
+9. On the top left go to Install App page and install the app on the desired account or organization
 10. Open the URL in `github.auth.secretUrl` from `status.json` and edit the secret value
     1. If you're using a self-hosted GitHub instance, put its domain in `domain` (e.g. `github.mycompany.com`)
     2. Put the new application id in `appId` (e.g. `34789562`)
-    3. Put the client id in `clientId` (e.g. `Iv1.0beef123456`)
-    4. Put the client secret in `clientSecret` (e.g. `4e2b66fab69065001500697b0d751beb033a3deb`)
-    5. Put the installation id you copied from the URL in `installationId` (e.g. `123456`)
     6. Ignore/delete `dummy` and **leave `personalAuthToken` empty**
 11. Open the URL in `github.auth.privateKeySecretUrl` from `status.json` and edit the secret value
     1. Open the downloaded private key with any text editor
@@ -38,21 +44,44 @@ Integration with GitHub can be done using an [app][9] or [personal access token]
 
 ## Personal Access Token
 
-1. Create a new token
-    1. Go to https://github.com/settings/tokens/new
-    2. Choose your expiration date (you will need to replace the token if it expires)
-    3. Under scopes select `repo`
-    4. Copy the generated token
-2. Open the URL in `github.auth.secretUrl` from `status.json` and edit the secret value
-    1. If you're using a self-hosted GitHub instance, put its domain in `domain` (e.g. `github.mycompany.com`)
-    2. Put the generated token in `personalAuthToken`
-    3. Ignore all other values
-3. Create a webhook
-    1. For organizations go to https://github.com/organizations/MY_ORG/settings/hooks after replacing `MY_ORG` with your GitHub organization name
-    2. For enterprise go to https://github.com/enterprises/MY_ENTERPRISE/settings/hooks after replacing `MY_ENTERPRISE` with your GitHub enterprise name
-    3. Otherwise, you can create one per repository in your repository settings under Webhooks
-    4. Configure the webhook:
-        1. For Webhook URL use the value of `github.webhook.url` from `status.json`
-        2. Open the URL in `github.webhook.secretUrl` from `status.json`, retrieve the secret value, and use it for webhook secret
-        3. Make sure content type is set to JSON
-        4. Select individual jobs and select only Workflow jobs
+### Create Token
+
+1. Go to https://github.com/settings/tokens/new
+2. Choose your expiration date (you will need to replace the token if it expires)
+3. Under scopes select `repo`
+4. Copy the generated token
+
+### Set Token
+
+#### Setup Wizard
+
+1. Open the URL in `github.setup.url` from `status.json`
+2. Enter your personal access token under Using Personal Access Token
+3. Click the Set button
+
+#### Manually
+
+1. Open the URL in `github.auth.secretUrl` from `status.json` and edit the secret value
+2. If you're using a self-hosted GitHub instance, put its domain in `domain` (e.g. `github.mycompany.com`)
+3. Put the generated token in `personalAuthToken`
+4. Ignore all other values
+
+### Setup Webhook
+
+1. For organizations go to https://github.com/organizations/MY_ORG/settings/hooks after replacing `MY_ORG` with your GitHub organization name
+2. For enterprise go to https://github.com/enterprises/MY_ENTERPRISE/settings/hooks after replacing `MY_ENTERPRISE` with your GitHub enterprise name
+3. Otherwise, you can create one per repository in your repository settings under Webhooks
+4. Configure the webhook:
+    1. For Webhook URL use the value of `github.webhook.url` from `status.json`
+    2. Open the URL in `github.webhook.secretUrl` from `status.json`, retrieve the secret value, and use it for webhook secret
+    3. Make sure content type is set to JSON
+    4. Select individual jobs and select only Workflow jobs
+
+## Resetting Setup Wizard
+
+If the setup wizard tells you setup has already been completed or if `github.setup.status` is completed, or if `github.setup.url` is empty:
+
+1. Open the URL in `github.setup.secretUrl` from `status.json`
+2. Edit the secret
+3. Put a new random value in `token`
+4. Run status function again to get the new URL

package/changelog.md

@@ -1,7 +1,7 @@
 
-### [0.0.13](https://github.com/CloudSnorkel/cdk-github-runners/compare/v0.0.12...v0.0.13) (2022-05-31)
+### [0.1.1](https://github.com/CloudSnorkel/cdk-github-runners/compare/v0.1.0...v0.1.1) (2022-06-04)
 
 
-### Bug Fixes
+### Features
 
-* Support building on Apple Silicon / Arm64 platforms ([#22](https://github.com/CloudSnorkel/cdk-github-runners/issues/22)) ([544bae0](https://github.com/CloudSnorkel/cdk-github-runners/commit/544bae0752729d4ba657b575023c483b141b6906))
+* Setup wizard for GitHub integration ([#30](https://github.com/CloudSnorkel/cdk-github-runners/issues/30)) ([38ce153](https://github.com/CloudSnorkel/cdk-github-runners/commit/38ce1538de0fd46c8f9dfec5ef17e3cd58cfbd3b)), closes [#6](https://github.com/CloudSnorkel/cdk-github-runners/issues/6)

package/lib/lambdas/delete-runner/index.js

@@ -12509,33 +12509,42 @@ var require_dist_node15 = __commonJS({
 // src/lambdas/github.ts
 var import_auth_app = __toESM(require_dist_node12());
 var import_core = __toESM(require_dist_node15());
+
+// src/lambdas/helpers.ts
 var AWS = __toESM(require("aws-sdk"));
 var sm = new AWS.SecretsManager();
+async function getSecretValue(arn) {
+  if (!arn) {
+    throw new Error("Missing secret ARN");
+  }
+  const secret = await sm.getSecretValue({ SecretId: arn }).promise();
+  if (!secret.SecretString) {
+    throw new Error(`No SecretString in ${arn}`);
+  }
+  return secret.SecretString;
+}
+async function getSecretJsonValue(arn) {
+  return JSON.parse(await getSecretValue(arn));
+}
+
+// src/lambdas/github.ts
 function baseUrlFromDomain(domain) {
   if (domain == "github.com") {
     return "https://api.github.com";
   }
   return `https://${domain}/api/v3`;
 }
-async function getOctokit() {
+async function getOctokit(installationId) {
   if (!process.env.GITHUB_SECRET_ARN || !process.env.GITHUB_PRIVATE_KEY_SECRET_ARN) {
     throw new Error("Missing environment variables");
   }
-  const secret = await sm.getSecretValue({
-    SecretId: process.env.GITHUB_SECRET_ARN
-  }).promise();
-  if (!secret.SecretString) {
-    throw new Error(`No secret string in ${process.env.GITHUB_SECRET_ARN}`);
-  }
-  const githubSecrets = JSON.parse(secret.SecretString);
+  const githubSecrets = await getSecretJsonValue(process.env.GITHUB_SECRET_ARN);
   let baseUrl = baseUrlFromDomain(githubSecrets.domain);
   let token;
   if (githubSecrets.personalAuthToken) {
     token = githubSecrets.personalAuthToken;
   } else {
-    const privateKey = (await sm.getSecretValue({
-      SecretId: process.env.GITHUB_PRIVATE_KEY_SECRET_ARN
-    }).promise()).SecretString;
+    const privateKey = await getSecretValue(process.env.GITHUB_PRIVATE_KEY_SECRET_ARN);
     const appOctokit = new import_core.Octokit({
       baseUrl,
       authStrategy: import_auth_app.createAppAuth,
@@ -12546,7 +12555,7 @@ async function getOctokit() {
     });
     token = (await appOctokit.auth({
       type: "installation",
-      installationId: githubSecrets.installationId
+      installationId
     })).token;
   }
   const octokit = new import_core.Octokit({
@@ -12580,7 +12589,7 @@ async function getRunnerId(octokit, owner, repo, name) {
   }
 }
 exports.handler = async function(event) {
-  const { octokit } = await getOctokit();
+  const { octokit } = await getOctokit(event.installationId);
   await octokit.request("POST /repos/{owner}/{repo}/actions/runs/{runId}/cancel", {
     owner: event.owner,
     repo: event.repo,