@cloudsnorkel/cdk-github-runners 0.0.9 → 0.0.12

package/.jsii

@@ -2,7 +2,6 @@
   "author": {
     "email": "amir@cloudsnorkel.com",
     "name": "Amir Szekely",
-    "organization": "CloudSnorkel",
     "roles": [
       "author"
     ]
@@ -2996,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\n## API\n\nSee [API.md](API.md) for full interface documentation.\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) | ✔    | TBD    |\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`](API.md#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`](API.md#CodeBuildRunner) construct in your code (starting with defaults 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`](API.md#CodeBuildRunner) 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/"
+    "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"
   },
   "repository": {
     "type": "git",
@@ -3031,7 +3030,7 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "Creates a project that gets started for each job.",
+        "remarks": "Creates a project that gets started for each job.\n\nThis construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.",
         "stability": "experimental",
         "summary": "GitHub Actions runner provider using CodeBuild to execute the actions."
       },
@@ -3042,7 +3041,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/codebuild.ts",
-          "line": 77
+          "line": 97
         },
         "parameters": [
           {
@@ -3071,22 +3070,26 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/codebuild.ts",
-        "line": 69
+        "line": 71
       },
       "methods": [
         {
           "docs": {
+            "remarks": "Called by GithubRunners and shouldn't be called manually.",
             "stability": "experimental",
-            "summary": "Generate step function tasks that execute the runner."
+            "summary": "Generate step function task(s) to start a new runner."
           },
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 148
+            "line": 175
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
           "parameters": [
             {
+              "docs": {
+                "summary": "workflow job details."
+              },
               "name": "parameters",
               "type": {
                 "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
@@ -3110,7 +3113,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 185
+            "line": 215
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -3121,12 +3124,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "The principal to grant permissions to."
+            "summary": "Grant principal used to add permissions to the runner role."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 75
+            "line": 95
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -3137,12 +3140,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "GitHub Actions label associated with this runner provider."
+            "summary": "Label associated with this provider."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 72
+            "line": 80
           },
           "name": "label",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -3152,12 +3155,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "CodeBuild project hosting the runner."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 70
+            "line": 75
           },
           "name": "project",
           "type": {
@@ -3167,12 +3171,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "Security group associated with runners."
+            "summary": "Security group attached to the task."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 74
+            "line": 90
           },
           "name": "securityGroup",
           "optional": true,
@@ -3184,12 +3188,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "VPC network in which runners will be placed."
+            "summary": "VPC used for hosting the project."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/codebuild.ts",
-            "line": 73
+            "line": 85
           },
           "name": "vpc",
           "optional": true,
@@ -3335,7 +3339,7 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "Creates a task definition with a single container that gets started for each job.",
+        "remarks": "Creates a task definition with a single container that gets started for each job.\n\nThis construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.",
         "stability": "experimental",
         "summary": "GitHub Actions runner provider using Fargate to execute the actions."
       },
@@ -3346,7 +3350,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 114
+          "line": 155
         },
         "parameters": [
           {
@@ -3375,22 +3379,26 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 102
+        "line": 109
       },
       "methods": [
         {
           "docs": {
+            "remarks": "Called by GithubRunners and shouldn't be called manually.",
             "stability": "experimental",
-            "summary": "Generate step function tasks that execute the runner."
+            "summary": "Generate step function task(s) to start a new runner."
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 161
+            "line": 209
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
           "parameters": [
             {
+              "docs": {
+                "summary": "workflow job details."
+              },
               "name": "parameters",
               "type": {
                 "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
@@ -3408,12 +3416,13 @@
       "properties": [
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Whether task will have a public IP."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 110
+            "line": 143
           },
           "name": "assignPublicIp",
           "type": {
@@ -3422,12 +3431,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Cluster hosting the task hosting the runner."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 103
+            "line": 113
           },
           "name": "cluster",
           "type": {
@@ -3442,7 +3452,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 112
+            "line": 153
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -3452,12 +3462,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Container definition hosting the runner."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 105
+            "line": 123
           },
           "name": "container",
           "type": {
@@ -3467,12 +3478,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "The principal to grant permissions to."
+            "summary": "Grant principal used to add permissions to the runner role."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 111
+            "line": 148
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -3483,12 +3494,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "GitHub Actions label associated with this runner provider."
+            "summary": "Label associated with this provider."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 107
+            "line": 128
           },
           "name": "label",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -3498,12 +3509,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Fargate task hosting the runner."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 104
+            "line": 118
           },
           "name": "task",
           "type": {
@@ -3513,12 +3525,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "Security group associated with runners."
+            "summary": "Security group attached to the task."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 109
+            "line": 138
           },
           "name": "securityGroup",
           "optional": true,
@@ -3530,12 +3542,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "VPC network in which runners will be placed."
+            "summary": "VPC used for hosting the task."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 108
+            "line": 133
           },
           "name": "vpc",
           "optional": true,
@@ -3551,7 +3563,8 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "datatype": true,
       "docs": {
-        "stability": "experimental"
+        "stability": "experimental",
+        "summary": "Properties for FargateRunner."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.FargateRunnerProps",
       "interfaces": [
@@ -3560,7 +3573,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 14
+        "line": 17
       },
       "name": "FargateRunnerProps",
       "properties": [
@@ -3568,13 +3581,14 @@
           "abstract": true,
           "docs": {
             "default": "true",
+            "remarks": "Make sure the task will have access to GitHub. A public IP might be required unless you have NAT gateway.",
             "stability": "experimental",
             "summary": "Assign public IP to the runner task."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 48
+            "line": 53
           },
           "name": "assignPublicIp",
           "optional": true,
@@ -3592,7 +3606,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 41
+            "line": 44
           },
           "name": "cluster",
           "optional": true,
@@ -3611,7 +3625,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 67
+            "line": 72
           },
           "name": "cpu",
           "optional": true,
@@ -3630,7 +3644,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 94
+            "line": 99
           },
           "name": "ephemeralStorageGiB",
           "optional": true,
@@ -3648,7 +3662,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 20
+            "line": 23
           },
           "name": "label",
           "optional": true,
@@ -3667,7 +3681,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 85
+            "line": 90
           },
           "name": "memoryLimitMiB",
           "optional": true,
@@ -3685,7 +3699,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 34
+            "line": 37
           },
           "name": "securityGroup",
           "optional": true,
@@ -3703,7 +3717,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 27
+            "line": 30
           },
           "name": "vpc",
           "optional": true,
@@ -3718,7 +3732,9 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "stability": "experimental"
+        "remarks": "It creates a webhook, secrets, and a step function to orchestrate all runs. Secrets are not automatically filled. See README.md for instructions on how to setup GitHub integration.\n\nBy default, this will create a runner provider of each available type with the defaults. This is good enough for the initial setup stage when you just want to get GitHub integration working.\n\n```typescript\nnew GitHubRunners(stack, 'runners', {});\n```\n\nUsually you'd want to configure the runner providers so the runners can run in a certain VPC or have certain permissions.\n\n```typescript\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```",
+        "stability": "experimental",
+        "summary": "Create all the required infrastructure to provide self-hosted GitHub runners."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.GitHubRunners",
       "initializer": {
@@ -3727,7 +3743,7 @@
         },
         "locationInModule": {
           "filename": "src/runner.ts",
-          "line": 29
+          "line": 93
         },
         "parameters": [
           {
@@ -3753,18 +3769,19 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 21
+        "line": 73
       },
       "name": "GitHubRunners",
       "properties": [
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Default provider as set by {@link GitHubRunnersProps.defaultProviderLabel}."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 24
+            "line": 83
           },
           "name": "defaultProvider",
           "type": {
@@ -3778,7 +3795,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 29
+            "line": 93
           },
           "name": "props",
           "type": {
@@ -3787,12 +3804,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Configured runner providers."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 23
+            "line": 78
           },
           "name": "providers",
           "type": {
@@ -3806,12 +3824,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Secrets for GitHub communication including webhook secret and runner authentication."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 25
+            "line": 88
           },
           "name": "secrets",
           "type": {
@@ -3826,7 +3845,7 @@
       "datatype": true,
       "docs": {
         "stability": "experimental",
-        "summary": "Properties of the GitHubRunners."
+        "summary": "Properties for GitHubRunners."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.GitHubRunnersProps",
       "kind": "interface",
@@ -3839,12 +3858,15 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "default": "'codebuild'",
+            "remarks": "A provider with that label must be configured.",
+            "stability": "experimental",
+            "summary": "Label of default provider in case the workflow job doesn't specify any known label."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 16
+            "line": 22
           },
           "name": "defaultProviderLabel",
           "optional": true,
@@ -3855,12 +3877,15 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "default": "CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)",
+            "remarks": "At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job.",
+            "stability": "experimental",
+            "summary": "List of runner providers to use."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 18
+            "line": 29
           },
           "name": "providers",
           "optional": true,
@@ -3879,7 +3904,9 @@
     "@cloudsnorkel/cdk-github-runners.IRunnerProvider": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
-        "stability": "experimental"
+        "remarks": "Implementations create all required resources and return a step function task that starts those resources from {@link getStepFunctionTask}.",
+        "stability": "experimental",
+        "summary": "Interface for all runner providers."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
       "interfaces": [
@@ -3889,18 +3916,19 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 42
+        "line": 89
       },
       "methods": [
         {
           "abstract": true,
           "docs": {
+            "remarks": "Called by GithubRunners and shouldn't be called manually.",
             "stability": "experimental",
             "summary": "Generate step function tasks that execute the runner."
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 63
+            "line": 112
           },
           "name": "getStepFunctionTask",
           "parameters": [
@@ -3932,7 +3960,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 46
+            "line": 93
           },
           "name": "label",
           "type": {
@@ -3948,7 +3976,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 56
+            "line": 103
           },
           "name": "securityGroup",
           "optional": true,
@@ -3965,7 +3993,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 51
+            "line": 98
           },
           "name": "vpc",
           "optional": true,
@@ -3980,7 +4008,7 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "Creates a Docker-based function that gets executed for each job.",
+        "remarks": "Creates a Docker-based function that gets executed for each job.\n\nThis construct is not meant to be used by itself. It should be passed in the providers property for GitHubRunners.",
         "stability": "experimental",
         "summary": "GitHub Actions runner provider using Lambda to execute the actions."
       },
@@ -3991,7 +4019,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/lambda.ts",
-          "line": 83
+          "line": 103
         },
         "parameters": [
           {
@@ -4020,22 +4048,26 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/lambda.ts",
-        "line": 75
+        "line": 77
       },
       "methods": [
         {
           "docs": {
+            "remarks": "Called by GithubRunners and shouldn't be called manually.",
             "stability": "experimental",
-            "summary": "Generate step function tasks that execute the runner."
+            "summary": "Generate step function task(s) to start a new runner."
           },
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 120
+            "line": 150
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
           "parameters": [
             {
+              "docs": {
+                "summary": "workflow job details."
+              },
               "name": "parameters",
               "type": {
                 "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters"
@@ -4059,7 +4091,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 116
+            "line": 139
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -4069,12 +4101,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "The function hosting the GitHub runner."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 76
+            "line": 81
           },
           "name": "function",
           "type": {
@@ -4084,12 +4117,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "The principal to grant permissions to."
+            "summary": "Grant principal used to add permissions to the runner role."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 81
+            "line": 101
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -4100,12 +4133,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "GitHub Actions label associated with this runner provider."
+            "summary": "Label associated with this provider."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 78
+            "line": 86
           },
           "name": "label",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -4116,12 +4149,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "Security group associated with runners."
+            "summary": "Security group attached to the function."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 80
+            "line": 96
           },
           "name": "securityGroup",
           "optional": true,
@@ -4133,12 +4166,12 @@
         {
           "docs": {
             "stability": "experimental",
-            "summary": "VPC network in which runners will be placed."
+            "summary": "VPC used for hosting the function."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/lambda.ts",
-            "line": 79
+            "line": 91
           },
           "name": "vpc",
           "optional": true,
@@ -4302,13 +4335,14 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "datatype": true,
       "docs": {
-        "stability": "experimental"
+        "stability": "experimental",
+        "summary": "Common properties for all runner providers."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.RunnerProviderProps",
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 16
+        "line": 32
       },
       "name": "RunnerProviderProps",
       "properties": [
@@ -4323,7 +4357,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 31
+            "line": 47
           },
           "name": "logRetention",
           "optional": true,
@@ -4341,7 +4375,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 22
+            "line": 38
           },
           "name": "runnerVersion",
           "optional": true,
@@ -4356,25 +4390,29 @@
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "datatype": true,
       "docs": {
-        "stability": "experimental"
+        "remarks": "```sh\n./config.sh --unattended --url \"https://${GITHUB_DOMAIN}/${OWNER}/${REPO}\" --token \"${RUNNER_TOKEN}\" --ephemeral --work _work --labels \"${RUNNER_LABEL}\" --name \"${RUNNER_NAME}\" --disableupdate\n```\n\nAll parameters are specified as step function paths and therefore must be used only in step function task parameters.",
+        "stability": "experimental",
+        "summary": "Workflow job parameters as parsed from the webhook event. Pass these into your runner executor and run something like:."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.RunnerRuntimeParameters",
       "kind": "interface",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 34
+        "line": 59
       },
       "name": "RunnerRuntimeParameters",
       "properties": [
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "remarks": "Most of the time this will be github.com but for self-hosted GitHub instances, this will be different.",
+            "stability": "experimental",
+            "summary": "Path to GitHub domain."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 37
+            "line": 73
           },
           "name": "githubDomainPath",
           "type": {
@@ -4384,12 +4422,13 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Path to repostiroy owner name."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 38
+            "line": 78
           },
           "name": "ownerPath",
           "type": {
@@ -4399,12 +4438,13 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Path to repository name."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 39
+            "line": 83
           },
           "name": "repoPath",
           "type": {
@@ -4414,12 +4454,14 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "remarks": "We specifically set the name to make troubleshooting easier.",
+            "stability": "experimental",
+            "summary": "Path to desired runner name."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 36
+            "line": 68
           },
           "name": "runnerNamePath",
           "type": {
@@ -4429,12 +4471,13 @@
         {
           "abstract": true,
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Path to runner token used to register token."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 35
+            "line": 63
           },
           "name": "runnerTokenPath",
           "type": {
@@ -4447,7 +4490,8 @@
     "@cloudsnorkel/cdk-github-runners.RunnerVersion": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
-        "stability": "experimental"
+        "stability": "experimental",
+        "summary": "Defines desired GitHub Actions runner version."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.RunnerVersion",
       "initializer": {
@@ -4456,7 +4500,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/common.ts",
-          "line": 12
+          "line": 25
         },
         "parameters": [
           {
@@ -4471,16 +4515,17 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/common.ts",
-        "line": 3
+        "line": 6
       },
       "methods": [
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Use the latest version available at the time the runner provider image is built."
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 4
+            "line": 10
           },
           "name": "latest",
           "returns": {
@@ -4492,15 +4537,20 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "see": "https://github.com/actions/runner/releases",
+            "stability": "experimental",
+            "summary": "Use a specific version."
           },
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 8
+            "line": 21
           },
           "name": "specific",
           "parameters": [
             {
+              "docs": {
+                "summary": "GitHub Runner version."
+              },
               "name": "version",
               "type": {
                 "primitive": "string"
@@ -4524,7 +4574,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/common.ts",
-            "line": 12
+            "line": 25
           },
           "name": "version",
           "type": {
@@ -4548,7 +4598,7 @@
         },
         "locationInModule": {
           "filename": "src/secrets.ts",
-          "line": 13
+          "line": 29
         },
         "parameters": [
           {
@@ -4574,12 +4624,14 @@
       "properties": [
         {
           "docs": {
-            "stability": "experimental"
+            "remarks": "This secret is used to register runners and\ncancel jobs when the runner fails to start.\n\nThis secret is meant to be edited by the user after being created.",
+            "stability": "experimental",
+            "summary": "Authentication secret for GitHub containing either app details or personal authentication token."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/secrets.ts",
-            "line": 10
+            "line": 20
           },
           "name": "github",
           "type": {
@@ -4588,12 +4640,14 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "remarks": "This secret is meant to be edited by the user after being created.",
+            "stability": "experimental",
+            "summary": "GitHub app private key. Not needed when using personal authentication tokens."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/secrets.ts",
-            "line": 11
+            "line": 27
           },
           "name": "githubPrivateKey",
           "type": {
@@ -4602,12 +4656,13 @@
         },
         {
           "docs": {
-            "stability": "experimental"
+            "stability": "experimental",
+            "summary": "Webhook secret used to confirm events are coming from GitHub and nowhere else."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/secrets.ts",
-            "line": 9
+            "line": 12
           },
           "name": "webhook",
           "type": {
@@ -4618,6 +4673,6 @@
       "symbolId": "src/secrets:Secrets"
     }
   },
-  "version": "0.0.9",
-  "fingerprint": "fvzT5UM7kSxcyQ2sVtMoZWsxdoACTLxvI8F1XCLQONY="
+  "version": "0.0.12",
+  "fingerprint": "MUMnZhHPeAm9OvQoxoctrTRoDKE7vywznQ1B7UsKVVg="
 }