@cloudsnorkel/cdk-github-runners 0.10.4 → 0.10.6

package/API.md

@@ -4677,8 +4677,8 @@ Any object.
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <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.github">github</a></code> | <code>aws-cdk-lib.aws_secretsmanager.Secret</code> | Authentication secret for GitHub containing either app details or personal access 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 access 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. |
 
@@ -4704,7 +4704,7 @@ public readonly github: Secret;
 
 - *Type:* aws-cdk-lib.aws_secretsmanager.Secret
 
-Authentication secret for GitHub containing either app details or personal authentication token.
+Authentication secret for GitHub containing either app details or personal access token.
 
 This secret is used to register runners and
 cancel jobs when the runner fails to start.
@@ -4721,7 +4721,7 @@ public readonly githubPrivateKey: Secret;
 
 - *Type:* aws-cdk-lib.aws_secretsmanager.Secret
 
-GitHub app private key. Not needed when using personal authentication tokens.
+GitHub app private key. Not needed when using personal access tokens.
 
 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.
 
@@ -8171,9 +8171,9 @@ X86_64.
 
 ### LambdaAccess <a name="LambdaAccess" id="@cloudsnorkel/cdk-github-runners.LambdaAccess"></a>
 
-Access configuration options for Lambda functions like setup and webhook function.
+Access configuration options for Lambda functions like setup and webhook function. Use this to limit access to these functions.
 
-Use this to limit access to these functions.
+If you need a custom access point, you can implement this abstract class yourself. Note that the Lambda functions expect API Gateway v1 or v2 input. They also expect every URL under the constructed URL to point to the function.
 
 #### Initializers <a name="Initializers" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.Initializer"></a>
 
@@ -8188,6 +8188,39 @@ new LambdaAccess()
 
 ---
 
+#### Methods <a name="Methods" id="Methods"></a>
+
+| **Name** | **Description** |
+| --- | --- |
+| <code><a href="#@cloudsnorkel/cdk-github-runners.LambdaAccess.bind">bind</a></code> | Creates all required resources and returns access URL or empty string if disabled. |
+
+---
+
+##### `bind` <a name="bind" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.bind"></a>
+
+```typescript
+public bind(scope: Construct, id: string, lambdaFunction: Function): string
+```
+
+Creates all required resources and returns access URL or empty string if disabled.
+
+###### `scope`<sup>Required</sup> <a name="scope" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.bind.parameter.scope"></a>
+
+- *Type:* constructs.Construct
+
+---
+
+###### `id`<sup>Required</sup> <a name="id" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.bind.parameter.id"></a>
+
+- *Type:* string
+
+---
+
+###### `lambdaFunction`<sup>Required</sup> <a name="lambdaFunction" id="@cloudsnorkel/cdk-github-runners.LambdaAccess.bind.parameter.lambdaFunction"></a>
+
+- *Type:* aws-cdk-lib.aws_lambda.Function
+
+---
 
 #### Static Functions <a name="Static Functions" id="Static Functions"></a>
 
@@ -9669,7 +9702,9 @@ Note that this is not the job log, but the runner itself. It will not contain ou
 
 ---
 
-##### `retryableErrors`<sup>Required</sup> <a name="retryableErrors" id="@cloudsnorkel/cdk-github-runners.IRunnerProvider.property.retryableErrors"></a>
+##### ~~`retryableErrors`~~<sup>Required</sup> <a name="retryableErrors" id="@cloudsnorkel/cdk-github-runners.IRunnerProvider.property.retryableErrors"></a>
+
+- *Deprecated:* do not use
 
 ```typescript
 public readonly retryableErrors: string[];

package/README.md

@@ -299,7 +299,7 @@ Other useful metrics to track:
 
 
 [1]: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners
-[2]: https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions
+[2]: https://github.com/marketplace/actions/configure-aws-credentials-for-github-actions
 [3]: https://github.com/philips-labs/terraform-aws-github-runner
 [4]: https://github.com/actions/actions-runner-controller
 [5]: https://github.com/actions/runner

package/SETUP_GITHUB.md

@@ -7,14 +7,16 @@ Integration with GitHub can be done using an [app](#app-authentication) or [pers
 ### 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
+2. Choose whether you're integrating with GitHub.com or GitHub Enterprise Server
+3. Next choose New GitHub App
+4. If you want to create an app for your personal repositories, choose User app
+5. If you want to create an app for your organization:
+   1. Choose Organization app
+   2. Type in the organization slug (ORGANIZATION from https://github.com/ORGANIZATION/REPO)
+6. Click Create GitHub App to take you to GitHub to finish the setup
+7. Follow the instructions on GitHub
+8. When brought back to the setup wizard, click the install link
+9. Install the new app on your desired repositories
 
 ### Manually
 
@@ -37,7 +39,7 @@ Integration with GitHub can be done using an [app](#app-authentication) or [pers
 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`)
-    6. Ignore/delete `dummy` and **leave `personalAuthToken` empty**
+    3. 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
     2. Copy the text from the private key as-is into the secret
@@ -56,14 +58,16 @@ Integration with GitHub can be done using an [app](#app-authentication) or [pers
 #### 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
+2. Choose whether you're integrating with GitHub.com or GitHub Enterprise Server
+3. Next choose Personal Access Token
+4. Enter your personal access token
+5. Click the Setup 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`
+3. Put the generated token in `personalAuthToken` (**not** `personalAccessToken`)
 4. Ignore all other values
 
 ### Setup Webhook

package/TESTING.md

@@ -0,0 +1,61 @@
+## Unit Tests
+
+Unit tests are executed with `npm run build` and `npm run test`. GitHub Actions won't let PRs merge if the tests fail.
+
+To run on Windows, use:
+
+```
+jest --testMatch */**/*.test.ts
+```
+
+## Integration Test
+
+We have one set of [integration tests](test/default.integ.ts). It is a CDK app that creates a set of runners. Once deployed, the runners should be tested using the [self-hosted.yml](.github/workflows/self-hosted.yml) workflow. This should tell us GitHub integration and all runner provider types are working properly.
+
+We keep a snapshot of the CloudFormation template generated by the integration test in [test/default.integ.snapshot](test/default.integ.snapshot). During build time and PR validation, we validate the integration test still results in the same CloudFormation template as the snapshot. GitHub Actions won't let PRs merge if the tests fail.
+
+If the snapshot changes, you should commit it as part of your PR. You should ideally deploy and test it. The PR should mention whether the integration test was actually deployed and tested.
+
+To assert the snapshot hasn't changed, use:
+
+```
+npm run integ:default:assert
+```
+
+To deploy the integration test, use:
+
+```
+npm run integ:default:deploy
+```
+
+To update the snapshot, use:
+
+```
+npm run integ:default:snapshot
+```
+
+## Manual Tests 
+
+Integration tests check the happy paths. We should also test the unhappy paths manually. This is a list of scenarios we should manually test before releasing a new version:
+
+* Setup page
+  * GitHub app
+  * Personal access token
+  * GitHub Enterprise Server
+* Idle reaper
+  * Confirm idle runner is stopped automatically
+  * Confirm runner doesn't stay registered in GitHub
+  * Confirm runner is not retried
+  * Step function result is aborted and not failed
+* Retries
+  * Confirm runner errors are retried
+  * Confirm failed runner doesn't stay registered in GitHub
+
+The last two scenarios can be tested with the following test cases: 
+
+* Start step function without a job actually pending (e.g. by duplicating input from a previous job, or cancelling a job before a runner picks it up)
+   * The step function should be aborted as an idle runner
+   * No runner should be registered on GitHub at the end
+* Let Lambda runner timeout by starting a job that lasts longer than 15 minutes
+   * The runner should be retried and eventually the step function should be aborted as an idle runner
+   * No runner should be registered on GitHub at the end