@cloudsnorkel/cdk-github-runners 0.9.0 → 0.9.2

package/.jsii

@@ -3138,7 +3138,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)][7]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][6]\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* Automatically updated build environment with latest runner version\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|                  | EC2               | CodeBuild                  | Fargate        | Lambda        |\n|------------------|-------------------|----------------------------|----------------|---------------|\n| **Time limit**   | Unlimited         | 8 hours                    | Unlimited      | 15 minutes    |\n| **vCPUs**        | Unlimited         | 2, 4, 8, or 72             | 0.25 to 4      | 1 to 6        |\n| **RAM**          | Unlimited         | 3gb, 7gb, 15gb, or 145gb   | 512mb to 30gb  | 128mb to 10gb |\n| **Storage**      | Unlimited         | 50gb to 824gb              | 20gb to 200gb  | Up to 10gb    |\n| **Architecture** | x86_64, ARM64     | x86_64, ARM64              | x86_64, ARM64  | x86_64, ARM64 |\n| **sudo**         | ✔                 | ✔                         | ✔              | ❌           |\n| **Docker**       | ✔                 | ✔ (Linux only)            | ❌              | ❌           |\n| **Spot pricing** | ✔                 | ❌                         | ✔              | ❌           |\n| **OS**           | Linux, Windows    | Linux, Windows             | Linux, Windows | Linux         |\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[![Demo](demo-thumbnail.jpg)](https://youtu.be/wlyv_3V8lIw)\n\n## Customizing\n\nThe default providers configured by `GitHubRunners` 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\nlet vpc: ec2.Vpc;\nlet runnerSg: ec2.SecurityGroup;\nlet dbSg: ec2.SecurityGroup;\nlet bucket: s3.Bucket;\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunnerProvider(this, 'codebuild runner', {\n  label: 'my-codebuild',\n  vpc: vpc,\n  securityGroup: runnerSg,\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(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nAnother way to customize runners is by modifying the image used to spin them up. The image contains the [runner][5], any required dependencies, and integration code with the provider. You may choose to customize this image by adding more packages, for example.\n\n```typescript\nconst myBuilder = CodeBuildRunnerProvider.imageBuilder(this, 'image builder', {\n   dockerfilePath: FargateRunner.LINUX_X64_DOCKERFILE_PATH,\n   runnerVersion: RunnerVersion.specific('2.291.0'),\n   rebuildInterval: Duration.days(14),\n});\nmyBuilder.addComponent(\n  RunnerImageComponent.custom({ commands: ['apt install -y nginx xz-utils'] })\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   label: 'customized-fargate',\n   vpc: vpc,\n   securityGroup: runnerSg,\n   imageBuilder: myBuilder,\n});\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nYour workflow will then look like:\n\n```yaml\nname: self-hosted example\non: push\njobs:\n  self-hosted:\n    runs-on: [self-hosted, customized-fargate]\n    steps:\n      - run: echo hello world\n```\n\nWindows images can also be customized the same way.\n\n```typescript\nconst myWindowsBuilder = FargateRunnerProvider.imageBuilder(this, 'Windows image builder', {\n  architecture: Architecture.X86_64,\n  os: Os.WINDOWS,\n  runnerVersion: RunnerVersion.specific('2.291.0'),\n  rebuildInterval: Duration.days(14),\n});\nmyWindowsBuilder.addComponent(\n  RunnerImageComponent.custom({\n    name: 'Ninja',\n    commands: [\n      'Invoke-WebRequest -UseBasicParsing -Uri \"https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip\" -OutFile ninja.zip',\n      'Expand-Archive ninja.zip -DestinationPath C:\\\\actions',\n      'del ninja.zip',\n    ],\n  })\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n  label: 'customized-windows-fargate',\n  vpc: vpc,\n  securityGroup: runnerSg,\n  imageBuidler: myWindowsBuilder,\n});\n\nnew GitHubRunners(this, 'runners', {\n  providers: [myProvider],\n});\n```\n\nThe runner OS and architecture is determined by the image it is set to use. For example, to create a Fargate runner provider for ARM64 set the `architecture` property for the image builder to `Architecture.ARM64` in the image builder properties.\n\n```typescript\nnew GitHubRunners(this, 'runners', {\n  providers: [\n    new FargateRunnerProvider(this, 'fargate runner', {\n      labels: ['arm64', 'fargate'],\n      imageBuidler: FargateRunnerProvider.imageBuilder(this, 'image builder', {\n        architecture: Architecture.ARM64,\n        os: Os.LINUX,\n      }),\n    }),\n  ],\n});\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. If jobs are stuck on pending:\n   1. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider\n   2. If it happens every time, cancel the job and start it again\n4. 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\n5. When using GitHub app, make sure there are active installation in `github.auth.app.installations`\n6. 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/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/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[7]: https://www.npmjs.com/package/@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\n"
+    "markdown": "# GitHub Self-Hosted Runners CDK Constructs\n\n[![NPM](https://img.shields.io/npm/v/@cloudsnorkel/cdk-github-runners?label=npm&logo=npm)][7]\n[![PyPI](https://img.shields.io/pypi/v/cloudsnorkel.cdk-github-runners?label=pypi&logo=pypi)][6]\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* Automatically updated build environment with latest runner version\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|                  | EC2               | CodeBuild                  | Fargate        | ECS            | Lambda        |\n|------------------|-------------------|----------------------------|----------------|----------------|---------------|\n| **Time limit**   | Unlimited         | 8 hours                    | Unlimited      | Unlimited      | 15 minutes    |\n| **vCPUs**        | Unlimited         | 2, 4, 8, or 72             | 0.25 to 4      | Unlimited      | 1 to 6        |\n| **RAM**          | Unlimited         | 3gb, 7gb, 15gb, or 145gb   | 512mb to 30gb  | Unlimited      | 128mb to 10gb |\n| **Storage**      | Unlimited         | 50gb to 824gb              | 20gb to 200gb  | Unlimited      | Up to 10gb    |\n| **Architecture** | x86_64, ARM64     | x86_64, ARM64              | x86_64, ARM64  | x86_64, ARM64  | x86_64, ARM64 |\n| **sudo**         | ✔                 | ✔                         | ✔              | ✔              | ❌           |\n| **Docker**       | ✔                 | ✔ (Linux only)            | ❌              | ✔              | ❌           |\n| **Spot pricing** | ✔                 | ❌                         | ✔              | ✔              | ❌           |\n| **OS**           | Linux, Windows    | Linux, Windows             | Linux, Windows | Linux, Windows | Linux         |\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\n* EC2 is useful when you want runners to have complete access to the host\n* ECS is useful when you want to control the infrastructure, like leaving the runner host running for faster startups\n* Lambda is useful for short jobs that can work within time, size and readonly system constraints\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[![Demo](demo-thumbnail.jpg)](https://youtu.be/wlyv_3V8lIw)\n\n## Customizing\n\nThe default providers configured by `GitHubRunners` 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\nlet vpc: ec2.Vpc;\nlet runnerSg: ec2.SecurityGroup;\nlet dbSg: ec2.SecurityGroup;\nlet bucket: s3.Bucket;\n\n// create a custom CodeBuild provider\nconst myProvider = new CodeBuildRunnerProvider(this, 'codebuild runner', {\n  label: 'my-codebuild',\n  vpc: vpc,\n  securityGroup: runnerSg,\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(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nAnother way to customize runners is by modifying the image used to spin them up. The image contains the [runner][5], any required dependencies, and integration code with the provider. You may choose to customize this image by adding more packages, for example.\n\n```typescript\nconst myBuilder = CodeBuildRunnerProvider.imageBuilder(this, 'image builder', {\n   dockerfilePath: FargateRunner.LINUX_X64_DOCKERFILE_PATH,\n   runnerVersion: RunnerVersion.specific('2.291.0'),\n   rebuildInterval: Duration.days(14),\n});\nmyBuilder.addComponent(\n  RunnerImageComponent.custom({ commands: ['apt install -y nginx xz-utils'] })\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n   label: 'customized-fargate',\n   vpc: vpc,\n   securityGroup: runnerSg,\n   imageBuilder: myBuilder,\n});\n\n// create the runner infrastructure\nnew GitHubRunners(this, 'runners', {\n   providers: [myProvider],\n});\n```\n\nYour workflow will then look like:\n\n```yaml\nname: self-hosted example\non: push\njobs:\n  self-hosted:\n    runs-on: [self-hosted, customized-fargate]\n    steps:\n      - run: echo hello world\n```\n\nWindows images can also be customized the same way.\n\n```typescript\nconst myWindowsBuilder = FargateRunnerProvider.imageBuilder(this, 'Windows image builder', {\n  architecture: Architecture.X86_64,\n  os: Os.WINDOWS,\n  runnerVersion: RunnerVersion.specific('2.291.0'),\n  rebuildInterval: Duration.days(14),\n});\nmyWindowsBuilder.addComponent(\n  RunnerImageComponent.custom({\n    name: 'Ninja',\n    commands: [\n      'Invoke-WebRequest -UseBasicParsing -Uri \"https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip\" -OutFile ninja.zip',\n      'Expand-Archive ninja.zip -DestinationPath C:\\\\actions',\n      'del ninja.zip',\n    ],\n  })\n);\n\nconst myProvider = new FargateRunnerProvider(this, 'fargate runner', {\n  label: 'customized-windows-fargate',\n  vpc: vpc,\n  securityGroup: runnerSg,\n  imageBuidler: myWindowsBuilder,\n});\n\nnew GitHubRunners(this, 'runners', {\n  providers: [myProvider],\n});\n```\n\nThe runner OS and architecture is determined by the image it is set to use. For example, to create a Fargate runner provider for ARM64 set the `architecture` property for the image builder to `Architecture.ARM64` in the image builder properties.\n\n```typescript\nnew GitHubRunners(this, 'runners', {\n  providers: [\n    new FargateRunnerProvider(this, 'fargate runner', {\n      labels: ['arm64', 'fargate'],\n      imageBuidler: FargateRunnerProvider.imageBuilder(this, 'image builder', {\n        architecture: Architecture.ARM64,\n        os: Os.LINUX,\n      }),\n    }),\n  ],\n});\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. If jobs are stuck on pending:\n   1. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider\n   2. If it happens every time, cancel the job and start it again\n4. 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\n5. When using GitHub app, make sure there are active installation in `github.auth.app.installations`\n6. 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/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/actions-runner-controller\n[5]: https://github.com/actions/runner\n[6]: https://pypi.org/project/cloudsnorkel.cdk-github-runners\n[7]: https://www.npmjs.com/package/@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\n"
   },
   "repository": {
     "type": "git",
@@ -3828,6 +3828,86 @@
       ],
       "symbolId": "src/providers/image-builders/aws-image-builder/deprecated/ami:AmiBuilderProps"
     },
+    "@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps": {
+      "assembly": "@cloudsnorkel/cdk-github-runners",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental"
+      },
+      "fqn": "@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/access.ts",
+        "line": 9
+      },
+      "name": "ApiGatewayAccessProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "If not specified on public API Gateway, all IP addresses are allowed.\n\nIf not specified on private API Gateway, no IP addresses are allowed (but specified security groups are).",
+            "stability": "experimental",
+            "summary": "List of IP addresses in CIDR notation that are allowed to access the API Gateway."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 17
+          },
+          "name": "allowedIps",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Only works for private API Gateways with {@link allowedVpc}.",
+            "stability": "experimental",
+            "summary": "List of security groups that are allowed to access the API Gateway."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 29
+          },
+          "name": "allowedSecurityGroups",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "fqn": "aws-cdk-lib.aws_ec2.ISecurityGroup"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Creates a private API Gateway and allows access from the specified VPC."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 22
+          },
+          "name": "allowedVpc",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.IVpc"
+          }
+        }
+      ],
+      "symbolId": "src/access:ApiGatewayAccessProps"
+    },
     "@cloudsnorkel/cdk-github-runners.Architecture": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "docs": {
@@ -5115,7 +5195,7 @@
         {
           "abstract": true,
           "docs": {
-            "default": "CodeBuildRunnerProviderProps.imageBuilder()",
+            "default": "CodeBuildRunnerProvider.imageBuilder()",
             "remarks": "The image builder must contain the {@link RunnerImageComponent.dockerInDocker} component unless `dockerInDocker` is set to false.\n\nThe image builder determines the OS and architecture of the runner.",
             "stability": "experimental",
             "summary": "Runner image builder used to build Docker images containing GitHub Runner and all requirements."
@@ -6585,7 +6665,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 321
+          "line": 356
         },
         "parameters": [
           {
@@ -6612,7 +6692,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 510
+        "line": 519
       },
       "name": "FargateRunner",
       "symbolId": "src/providers/fargate:FargateRunner"
@@ -6632,7 +6712,7 @@
         },
         "locationInModule": {
           "filename": "src/providers/fargate.ts",
-          "line": 321
+          "line": 356
         },
         "parameters": [
           {
@@ -6662,7 +6742,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/providers/fargate.ts",
-        "line": 207
+        "line": 242
       },
       "methods": [
         {
@@ -6673,7 +6753,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 241
+            "line": 276
           },
           "name": "imageBuilder",
           "parameters": [
@@ -6751,7 +6831,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 405
+            "line": 440
           },
           "name": "getStepFunctionTask",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6780,7 +6860,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 459
+            "line": 494
           },
           "name": "grantStateMachine",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6849,7 +6929,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 462
+            "line": 497
           },
           "name": "status",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -6881,7 +6961,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 228
+            "line": 263
           },
           "name": "LINUX_ARM64_DOCKERFILE_PATH",
           "static": true,
@@ -6900,7 +6980,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 217
+            "line": 252
           },
           "name": "LINUX_X64_DOCKERFILE_PATH",
           "static": true,
@@ -6916,7 +6996,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 290
+            "line": 325
           },
           "name": "assignPublicIp",
           "type": {
@@ -6931,7 +7011,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 260
+            "line": 295
           },
           "name": "cluster",
           "type": {
@@ -6946,7 +7026,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 300
+            "line": 335
           },
           "name": "connections",
           "overrides": "aws-cdk-lib.aws_ec2.IConnectable",
@@ -6962,7 +7042,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 270
+            "line": 305
           },
           "name": "container",
           "type": {
@@ -6977,7 +7057,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 295
+            "line": 330
           },
           "name": "grantPrincipal",
           "overrides": "aws-cdk-lib.aws_iam.IGrantable",
@@ -6994,7 +7074,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 310
+            "line": 345
           },
           "name": "image",
           "type": {
@@ -7009,7 +7089,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 275
+            "line": 310
           },
           "name": "labels",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7031,7 +7111,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 317
+            "line": 352
           },
           "name": "logGroup",
           "overrides": "@cloudsnorkel/cdk-github-runners.IRunnerProvider",
@@ -7047,7 +7127,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 305
+            "line": 340
           },
           "name": "spot",
           "type": {
@@ -7062,7 +7142,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 265
+            "line": 300
           },
           "name": "task",
           "type": {
@@ -7077,7 +7157,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 285
+            "line": 320
           },
           "name": "subnetSelection",
           "optional": true,
@@ -7093,7 +7173,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/fargate.ts",
-            "line": 280
+            "line": 315
           },
           "name": "vpc",
           "optional": true,
@@ -7109,7 +7189,7 @@
       "datatype": true,
       "docs": {
         "stability": "experimental",
-        "summary": "Properties for FargateRunner."
+        "summary": "Properties for FargateRunnerProvider."
       },
       "fqn": "@cloudsnorkel/cdk-github-runners.FargateRunnerProviderProps",
       "interfaces": [
@@ -7200,7 +7280,7 @@
         {
           "abstract": true,
           "docs": {
-            "default": "FargateRunnerProviderProps.imageBuilder()",
+            "default": "FargateRunnerProvider.imageBuilder()",
             "remarks": "The image builder determines the OS and architecture of the runner.",
             "stability": "experimental",
             "summary": "Runner image builder used to build Docker images containing GitHub Runner and all requirements."
@@ -7393,7 +7473,7 @@
         },
         "locationInModule": {
           "filename": "src/runner.ts",
-          "line": 191
+          "line": 218
         },
         "parameters": [
           {
@@ -7420,7 +7500,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 172
+        "line": 199
       },
       "methods": [
         {
@@ -7431,7 +7511,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 565
+            "line": 607
           },
           "name": "metricFailed",
           "parameters": [
@@ -7457,7 +7537,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 510
+            "line": 552
           },
           "name": "metricJobCompleted",
           "parameters": [
@@ -7483,7 +7563,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 556
+            "line": 598
           },
           "name": "metricSucceeded",
           "parameters": [
@@ -7509,7 +7589,7 @@
           },
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 572
+            "line": 614
           },
           "name": "metricTime",
           "parameters": [
@@ -7538,7 +7618,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 176
+            "line": 203
           },
           "name": "providers",
           "type": {
@@ -7558,7 +7638,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 181
+            "line": 208
           },
           "name": "secrets",
           "type": {
@@ -7572,7 +7652,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 191
+            "line": 218
           },
           "name": "props",
           "optional": true,
@@ -7594,7 +7674,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 29
+        "line": 30
       },
       "name": "GitHubRunnersProps",
       "properties": [
@@ -7609,7 +7689,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 52
+            "line": 53
           },
           "name": "allowPublicSubnet",
           "optional": true,
@@ -7627,7 +7707,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 82
+            "line": 83
           },
           "name": "extraCertificates",
           "optional": true,
@@ -7646,7 +7726,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 89
+            "line": 90
           },
           "name": "idleTimeout",
           "optional": true,
@@ -7664,7 +7744,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 96
+            "line": 97
           },
           "name": "logOptions",
           "optional": true,
@@ -7683,7 +7763,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 35
+            "line": 36
           },
           "name": "providers",
           "optional": true,
@@ -7706,7 +7786,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 57
+            "line": 58
           },
           "name": "securityGroup",
           "optional": true,
@@ -7714,6 +7794,44 @@
             "fqn": "aws-cdk-lib.aws_ec2.ISecurityGroup"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "LambdaAccess.lambdaUrl()",
+            "remarks": "Once you finish the setup process, you can set this to `LambdaAccess.noAccess()` to remove access to the setup function. You can also use `LambdaAccess.apiGateway({ allowedIps: ['my-ip/0']})` to limit access to your IP only.",
+            "stability": "experimental",
+            "summary": "Access configuration for the setup function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/runner.ts",
+            "line": 104
+          },
+          "name": "setupAccess",
+          "optional": true,
+          "type": {
+            "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "LambdaAccess.noAccess()",
+            "remarks": "This function returns a lot of sensitive information about the runner, so you should only allow access to it from trusted IPs, if at all.",
+            "stability": "experimental",
+            "summary": "Access configuration for the status function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/runner.ts",
+            "line": 123
+          },
+          "name": "statusAccess",
+          "optional": true,
+          "type": {
+            "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -7724,7 +7842,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 40
+            "line": 41
           },
           "name": "vpc",
           "optional": true,
@@ -7742,13 +7860,32 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 45
+            "line": 46
           },
           "name": "vpcSubnets",
           "optional": true,
           "type": {
             "fqn": "aws-cdk-lib.aws_ec2.SubnetSelection"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "LambdaAccess.lambdaUrl()",
+            "remarks": "This function is called by GitHub when a new workflow job is scheduled. For an extra layer of security, you can set this to `LambdaAccess.apiGateway({ allowedIps: LambdaAccess.githubWebhookIps() })`.\n\nYou can also set this to `LambdaAccess.privateApiGateway()` if your GitHub Enterprise Server is hosted in a VPC. This will create an API Gateway endpoint that's only accessible from within the VPC.\n\n*WARNING*: changing access type may change the URL. When the URL changes, you must update GitHub as well.",
+            "stability": "experimental",
+            "summary": "Access configuration for the webhook function."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/runner.ts",
+            "line": 116
+          },
+          "name": "webhookAccess",
+          "optional": true,
+          "type": {
+            "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+          }
         }
       ],
       "symbolId": "src/runner:GitHubRunnersProps"
@@ -8566,6 +8703,116 @@
       ],
       "symbolId": "src/providers/image-builders/aws-image-builder/builder:ImageBuilderComponentProperties"
     },
+    "@cloudsnorkel/cdk-github-runners.LambdaAccess": {
+      "abstract": true,
+      "assembly": "@cloudsnorkel/cdk-github-runners",
+      "docs": {
+        "remarks": "Use this to limit access to these functions.",
+        "stability": "experimental",
+        "summary": "Access configuration options for Lambda functions like setup and webhook function."
+      },
+      "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        }
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/access.ts",
+        "line": 35
+      },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "This is the most secure option, but requires additional configuration. It allows you to limit access to specific IP addresses and even to a specific VPC.\n\nTo limit access to GitHub.com use:\n\n```\nLambdaAccess.apiGateway({\n  allowedIps: LambdaAccess.githubWebhookIps(),\n});\n```\n\nAlternatively, get and manually update the list manually with:\n\n```\ncurl https://api.github.com/meta | jq .hooks\n```",
+            "stability": "experimental",
+            "summary": "Provide access using API Gateway."
+          },
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 67
+          },
+          "name": "apiGateway",
+          "parameters": [
+            {
+              "name": "props",
+              "optional": true,
+              "type": {
+                "fqn": "@cloudsnorkel/cdk-github-runners.ApiGatewayAccessProps"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "remarks": "Note that downloading dynamic data during deployment is not recommended in CDK. This is a workaround for the lack of a better solution.",
+            "stability": "experimental",
+            "summary": "Downloads the list of IP addresses used by GitHub.com for webhooks."
+          },
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 76
+          },
+          "name": "githubWebhookIps",
+          "returns": {
+            "type": {
+              "collection": {
+                "elementtype": {
+                  "primitive": "string"
+                },
+                "kind": "array"
+              }
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "remarks": "This is the default and simplest option. It puts no limits on the requester, but the Lambda functions themselves authenticate every request.",
+            "stability": "experimental",
+            "summary": "Provide access using Lambda URL."
+          },
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 46
+          },
+          "name": "lambdaUrl",
+          "returns": {
+            "type": {
+              "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+            }
+          },
+          "static": true
+        },
+        {
+          "docs": {
+            "remarks": "This is useful for the setup function after setup is done.",
+            "stability": "experimental",
+            "summary": "Disables access to the configured Lambda function."
+          },
+          "locationInModule": {
+            "filename": "src/access.ts",
+            "line": 39
+          },
+          "name": "noAccess",
+          "returns": {
+            "type": {
+              "fqn": "@cloudsnorkel/cdk-github-runners.LambdaAccess"
+            }
+          },
+          "static": true
+        }
+      ],
+      "name": "LambdaAccess",
+      "symbolId": "src/access:LambdaAccess"
+    },
     "@cloudsnorkel/cdk-github-runners.LambdaRunner": {
       "assembly": "@cloudsnorkel/cdk-github-runners",
       "base": "@cloudsnorkel/cdk-github-runners.LambdaRunnerProvider",
@@ -9045,7 +9292,7 @@
         {
           "abstract": true,
           "docs": {
-            "default": "LambdaRunnerProviderProps.imageBuilder()",
+            "default": "LambdaRunnerProvider.imageBuilder()",
             "remarks": "The image builder must contain the {@link RunnerImageComponent.lambdaEntrypoint} component.\n\nThe image builder determines the OS and architecture of the runner.",
             "stability": "experimental",
             "summary": "Runner image builder used to build Docker images containing GitHub Runner and all requirements."
@@ -9552,7 +9799,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/runner.ts",
-        "line": 102
+        "line": 129
       },
       "name": "LogOptions",
       "properties": [
@@ -9566,7 +9813,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 113
+            "line": 140
           },
           "name": "includeExecutionData",
           "optional": true,
@@ -9584,7 +9831,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 120
+            "line": 147
           },
           "name": "level",
           "optional": true,
@@ -9601,7 +9848,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 106
+            "line": 133
           },
           "name": "logGroupName",
           "optional": true,
@@ -9620,7 +9867,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/runner.ts",
-            "line": 129
+            "line": 156
           },
           "name": "logRetention",
           "optional": true,
@@ -10822,7 +11069,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 419
+            "line": 420
           },
           "name": "extraCertificates",
           "parameters": [
@@ -10923,7 +11170,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 469
+            "line": 470
           },
           "name": "lambdaEntrypoint",
           "returns": {
@@ -10975,7 +11222,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 518
+            "line": 519
           },
           "name": "getAssets",
           "parameters": [
@@ -11012,7 +11259,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 513
+            "line": 514
           },
           "name": "getCommands",
           "parameters": [
@@ -11048,7 +11295,7 @@
           },
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 527
+            "line": 528
           },
           "name": "getDockerCommands",
           "parameters": [
@@ -11089,7 +11336,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/providers/image-builders/components.ts",
-            "line": 508
+            "line": 509
           },
           "name": "name",
           "type": {
@@ -11974,6 +12221,6 @@
       "symbolId": "src/providers/image-builders/aws-image-builder/deprecated/windows-components:WindowsComponents"
     }
   },
-  "version": "0.9.0",
-  "fingerprint": "iA/JYmn5LOUf/PZGdxu6acPsYqAa+U0Sw4uLolC9598="
+  "version": "0.9.2",
+  "fingerprint": "zmHG8ogvxM4UnuobG3q57zcoNzxuIu+sExYrdG2uOo8="
 }