cloudsnorkel.cdk-github-runners 0.17.0__tar.gz → 0.18.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. {cloudsnorkel_cdk_github_runners-0.17.0/src/cloudsnorkel.cdk_github_runners.egg-info → cloudsnorkel_cdk_github_runners-0.18.0}/PKG-INFO +40 -6
  2. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/README.md +38 -4
  3. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/pyproject.toml +1 -1
  4. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/setup.py +3 -3
  5. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/__init__.py +260 -15
  6. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
  7. cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz +0 -0
  8. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0/src/cloudsnorkel.cdk_github_runners.egg-info}/PKG-INFO +40 -6
  9. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/SOURCES.txt +1 -1
  10. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/requires.txt +1 -1
  11. cloudsnorkel_cdk_github_runners-0.17.0/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.17.0.jsii.tgz +0 -0
  12. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/LICENSE +0 -0
  13. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/MANIFEST.in +0 -0
  14. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/setup.cfg +0 -0
  15. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
  16. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/dependency_links.txt +0 -0
  17. {cloudsnorkel_cdk_github_runners-0.17.0 → cloudsnorkel_cdk_github_runners-0.18.0}/src/cloudsnorkel.cdk_github_runners.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: cloudsnorkel.cdk-github-runners
3
- Version: 0.17.0
3
+ Version: 0.18.0
4
4
  Summary: CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.
5
5
  Home-page: https://github.com/CloudSnorkel/cdk-github-runners.git
6
6
  Author: Amir Szekely<amir@cloudsnorkel.com>
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
24
  Requires-Dist: aws-cdk-lib<3.0.0,>=2.239.0
25
25
  Requires-Dist: constructs<11.0.0,>=10.5.1
26
- Requires-Dist: jsii<2.0.0,>=1.139.0
26
+ Requires-Dist: jsii<2.0.0,>=1.142.0
27
27
  Requires-Dist: publication>=0.0.3
28
28
 
29
29
  # GitHub Self-Hosted Runners CDK Constructs
@@ -36,6 +36,7 @@ Requires-Dist: publication>=0.0.3
36
36
  [![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)
37
37
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
38
38
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
39
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
39
40
 
40
41
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
41
42
 
@@ -50,7 +51,7 @@ Self-hosted runners in AWS are useful when:
50
51
  * You need easy access to internal resources in your actions
51
52
  * You want to pre-install some software for your actions
52
53
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
53
- * You are using GitHub Enterprise Server
54
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
54
55
 
55
56
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) 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.
56
57
 
@@ -67,6 +68,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
67
68
  * [Examples](#examples)
68
69
  * [Architecture](#architecture)
69
70
  * [Troubleshooting](#troubleshooting)
71
+
72
+ * [Rebuilding runner images](#rebuilding-runner-images)
70
73
  * [Monitoring](#monitoring)
71
74
  * [Getting Help](#getting-help)
72
75
  * [Contributing](#contributing)
@@ -620,7 +623,9 @@ If you have more to share, please open a PR adding examples to the `examples` fo
620
623
 
621
624
  ## Troubleshooting
622
625
 
623
- Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
626
+ Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
627
+
628
+ Configuration problems that we can detect up-front fail the orchestrator with a `RunnerConfigurationError` before any instance, build, or task is started. The error message says what needs to be fixed. These are still retried like any other error, so a configuration fixed within the 24 hours GitHub keeps the job queued still gets a runner and the job still runs.
624
629
 
625
630
  1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
626
631
  2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider
@@ -634,6 +639,7 @@ Runners are started in response to a webhook coming in from GitHub. If there are
634
639
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
635
640
  2. If you see too many errors, make sure you're only sending `workflow_job` events
636
641
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
642
+ 6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
637
643
 
638
644
  All logs are saved in CloudWatch.
639
645
 
@@ -646,12 +652,36 @@ To get `status.json`, check out the CloudFormation stack output for a command th
646
652
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
647
653
  ```
648
654
 
655
+ ### Rebuilding runner images
656
+
657
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
658
+
659
+ ```sh
660
+ STACK=my-runners-stack
661
+ resources() {
662
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
663
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
664
+ }
665
+ for project in $(resources AWS::CodeBuild::Project); do
666
+ # skip runner projects of CodeBuild providers, we only want image builders
667
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
668
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
669
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
670
+ done
671
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
672
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
673
+ done
674
+ ```
675
+
676
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
677
+
649
678
  ## Monitoring
650
679
 
651
- There are two important ways to monitor your runners:
680
+ There are three important ways to monitor your runners:
652
681
 
653
682
  1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.
654
- 2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
683
+ 2. Make sure our management functions don't fail. When that happens, webhooks may be dropped and jobs may never get a runner. Use `GitHubRunners.metricLambdaErrors()` to get a metric for the number of failed invocations across all management Lambda functions. You should use this metric to trigger an alarm.
684
+ 3. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
655
685
 
656
686
  Other useful metrics to track:
657
687
 
@@ -659,6 +689,10 @@ Other useful metrics to track:
659
689
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
660
690
  3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
661
691
 
692
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
693
+ completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
694
+ recent errors from the logs.
695
+
662
696
  ## Known Issues
663
697
 
664
698
  1. Runner images built during a failed deployment are not rolled back. If your stack fails to deploy after an image was already built, the new image will stay in use. The image will be automatically replaced on the next build interval, but that might take up to 7 days with default settings (`rebuildInterval`). It's recommended to not leave stacks in `UPDATE_ROLLBACK_COMPLETE` state. Deploying again with the configuration you want will rebuild the images and get everything back in sync.
@@ -8,6 +8,7 @@
8
8
  [![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)
9
9
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
10
10
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
11
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
11
12
 
12
13
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
13
14
 
@@ -22,7 +23,7 @@ Self-hosted runners in AWS are useful when:
22
23
  * You need easy access to internal resources in your actions
23
24
  * You want to pre-install some software for your actions
24
25
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
25
- * You are using GitHub Enterprise Server
26
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
26
27
 
27
28
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) 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.
28
29
 
@@ -39,6 +40,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
39
40
  * [Examples](#examples)
40
41
  * [Architecture](#architecture)
41
42
  * [Troubleshooting](#troubleshooting)
43
+
44
+ * [Rebuilding runner images](#rebuilding-runner-images)
42
45
  * [Monitoring](#monitoring)
43
46
  * [Getting Help](#getting-help)
44
47
  * [Contributing](#contributing)
@@ -592,7 +595,9 @@ If you have more to share, please open a PR adding examples to the `examples` fo
592
595
 
593
596
  ## Troubleshooting
594
597
 
595
- Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
598
+ Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
599
+
600
+ Configuration problems that we can detect up-front fail the orchestrator with a `RunnerConfigurationError` before any instance, build, or task is started. The error message says what needs to be fixed. These are still retried like any other error, so a configuration fixed within the 24 hours GitHub keeps the job queued still gets a runner and the job still runs.
596
601
 
597
602
  1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
598
603
  2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider
@@ -606,6 +611,7 @@ Runners are started in response to a webhook coming in from GitHub. If there are
606
611
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
607
612
  2. If you see too many errors, make sure you're only sending `workflow_job` events
608
613
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
614
+ 6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
609
615
 
610
616
  All logs are saved in CloudWatch.
611
617
 
@@ -618,12 +624,36 @@ To get `status.json`, check out the CloudFormation stack output for a command th
618
624
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
619
625
  ```
620
626
 
627
+ ### Rebuilding runner images
628
+
629
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
630
+
631
+ ```sh
632
+ STACK=my-runners-stack
633
+ resources() {
634
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
635
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
636
+ }
637
+ for project in $(resources AWS::CodeBuild::Project); do
638
+ # skip runner projects of CodeBuild providers, we only want image builders
639
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
640
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
641
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
642
+ done
643
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
644
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
645
+ done
646
+ ```
647
+
648
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
649
+
621
650
  ## Monitoring
622
651
 
623
- There are two important ways to monitor your runners:
652
+ There are three important ways to monitor your runners:
624
653
 
625
654
  1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.
626
- 2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
655
+ 2. Make sure our management functions don't fail. When that happens, webhooks may be dropped and jobs may never get a runner. Use `GitHubRunners.metricLambdaErrors()` to get a metric for the number of failed invocations across all management Lambda functions. You should use this metric to trigger an alarm.
656
+ 3. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
627
657
 
628
658
  Other useful metrics to track:
629
659
 
@@ -631,6 +661,10 @@ Other useful metrics to track:
631
661
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
632
662
  3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
633
663
 
664
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
665
+ completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
666
+ recent errors from the logs.
667
+
634
668
  ## Known Issues
635
669
 
636
670
  1. Runner images built during a failed deployment are not rolled back. If your stack fails to deploy after an image was already built, the new image will stay in use. The image will be automatically replaced on the next build interval, but that might take up to 7 days with default settings (`rebuildInterval`). It's recommended to not leave stacks in `UPDATE_ROLLBACK_COMPLETE` state. Deploying again with the configuration you want will rebuild the images and get everything back in sync.
@@ -1,5 +1,5 @@
1
1
  [build-system]
2
- requires = ["setuptools~=75.3.2", "build~=1.5.0"]
2
+ requires = ["setuptools~=75.3.2", "build~=1.6.1"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [tool.pyright]
@@ -5,7 +5,7 @@ kwargs = json.loads(
5
5
  """
6
6
  {
7
7
  "name": "cloudsnorkel.cdk-github-runners",
8
- "version": "0.17.0",
8
+ "version": "0.18.0",
9
9
  "description": "CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.",
10
10
  "license": "Apache-2.0",
11
11
  "url": "https://github.com/CloudSnorkel/cdk-github-runners.git",
@@ -26,7 +26,7 @@ kwargs = json.loads(
26
26
  ],
27
27
  "package_data": {
28
28
  "cloudsnorkel.cdk_github_runners._jsii": [
29
- "cdk-github-runners@0.17.0.jsii.tgz"
29
+ "cdk-github-runners@0.18.0.jsii.tgz"
30
30
  ],
31
31
  "cloudsnorkel.cdk_github_runners": [
32
32
  "py.typed"
@@ -36,7 +36,7 @@ kwargs = json.loads(
36
36
  "install_requires": [
37
37
  "aws-cdk-lib>=2.239.0, <3.0.0",
38
38
  "constructs>=10.5.1, <11.0.0",
39
- "jsii>=1.139.0, <2.0.0",
39
+ "jsii>=1.142.0, <2.0.0",
40
40
  "publication>=0.0.3"
41
41
  ],
42
42
  "classifiers": [
@@ -9,6 +9,7 @@ r'''
9
9
  [![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)
10
10
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
11
11
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
12
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
12
13
 
13
14
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
14
15
 
@@ -23,7 +24,7 @@ Self-hosted runners in AWS are useful when:
23
24
  * You need easy access to internal resources in your actions
24
25
  * You want to pre-install some software for your actions
25
26
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
26
- * You are using GitHub Enterprise Server
27
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
27
28
 
28
29
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) 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.
29
30
 
@@ -40,6 +41,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
40
41
  * [Examples](#examples)
41
42
  * [Architecture](#architecture)
42
43
  * [Troubleshooting](#troubleshooting)
44
+
45
+ * [Rebuilding runner images](#rebuilding-runner-images)
43
46
  * [Monitoring](#monitoring)
44
47
  * [Getting Help](#getting-help)
45
48
  * [Contributing](#contributing)
@@ -593,7 +596,9 @@ If you have more to share, please open a PR adding examples to the `examples` fo
593
596
 
594
597
  ## Troubleshooting
595
598
 
596
- Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
599
+ Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
600
+
601
+ Configuration problems that we can detect up-front fail the orchestrator with a `RunnerConfigurationError` before any instance, build, or task is started. The error message says what needs to be fixed. These are still retried like any other error, so a configuration fixed within the 24 hours GitHub keeps the job queued still gets a runner and the job still runs.
597
602
 
598
603
  1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
599
604
  2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider
@@ -607,6 +612,7 @@ Runners are started in response to a webhook coming in from GitHub. If there are
607
612
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
608
613
  2. If you see too many errors, make sure you're only sending `workflow_job` events
609
614
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
615
+ 6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
610
616
 
611
617
  All logs are saved in CloudWatch.
612
618
 
@@ -619,12 +625,36 @@ To get `status.json`, check out the CloudFormation stack output for a command th
619
625
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
620
626
  ```
621
627
 
628
+ ### Rebuilding runner images
629
+
630
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
631
+
632
+ ```sh
633
+ STACK=my-runners-stack
634
+ resources() {
635
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
636
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
637
+ }
638
+ for project in $(resources AWS::CodeBuild::Project); do
639
+ # skip runner projects of CodeBuild providers, we only want image builders
640
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
641
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
642
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
643
+ done
644
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
645
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
646
+ done
647
+ ```
648
+
649
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
650
+
622
651
  ## Monitoring
623
652
 
624
- There are two important ways to monitor your runners:
653
+ There are three important ways to monitor your runners:
625
654
 
626
655
  1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.
627
- 2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
656
+ 2. Make sure our management functions don't fail. When that happens, webhooks may be dropped and jobs may never get a runner. Use `GitHubRunners.metricLambdaErrors()` to get a metric for the number of failed invocations across all management Lambda functions. You should use this metric to trigger an alarm.
657
+ 3. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
628
658
 
629
659
  Other useful metrics to track:
630
660
 
@@ -632,6 +662,10 @@ Other useful metrics to track:
632
662
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
633
663
  3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
634
664
 
665
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
666
+ completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
667
+ recent errors from the logs.
668
+
635
669
  ## Known Issues
636
670
 
637
671
  1. Runner images built during a failed deployment are not rolled back. If your stack fails to deploy after an image was already built, the new image will stay in use. The image will be automatically replaced on the next build interval, but that might take up to 7 days with default settings (`rebuildInterval`). It's recommended to not leave stacks in `UPDATE_ROLLBACK_COMPLETE` state. Deploying again with the configuration you want will rebuild the images and get everything back in sync.
@@ -1413,6 +1447,7 @@ class Architecture(
1413
1447
 
1414
1448
  @jsii.python.classproperty
1415
1449
  @jsii.member(jsii_name="ARM64")
1450
+ @builtins.classmethod
1416
1451
  def ARM64(cls) -> "Architecture":
1417
1452
  '''(experimental) ARM64.
1418
1453
 
@@ -1422,6 +1457,7 @@ class Architecture(
1422
1457
 
1423
1458
  @jsii.python.classproperty
1424
1459
  @jsii.member(jsii_name="X86_64")
1460
+ @builtins.classmethod
1425
1461
  def X86_64(cls) -> "Architecture":
1426
1462
  '''(experimental) X86_64.
1427
1463
 
@@ -2747,7 +2783,7 @@ class GitHubRunners(
2747
2783
  :param security_groups: (experimental) Security groups attached to all management functions. Use this to provide outbound access from management functions to GitHub Enterprise Server hosted inside a VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting. **Note:** Defining inbound rules on this security group does nothing. This security group only controls outbound access FROM the management functions. To limit access TO the webhook or setup functions, use {@link webhookAccess} and {@link setupAccess} instead.
2748
2784
  :param setup_access: (experimental) Access configuration for the setup function. 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. Default: LambdaAccess.lambdaUrl()
2749
2785
  :param status_access: (experimental) Access configuration for the status function. 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. Default: LambdaAccess.noAccess()
2750
- :param vpc: (experimental) VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting and will run outside the VPC. Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints: - GitHub Enterprise Server - Secrets Manager - SQS - Step Functions - CloudFormation (status function only) - EC2 (status function only) - ECR (status function only)
2786
+ :param vpc: (experimental) VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting and will run outside the VPC. Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints: - GitHub Enterprise Server - Secrets Manager - SQS - Step Functions - CloudFormation (status function only) - EC2 - ECR (status function only)
2751
2787
  :param vpc_subnets: (experimental) VPC subnets used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
2752
2788
  :param webhook_access: (experimental) Access configuration for the webhook function. 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() })``. You can also set this to ``LambdaAccess.apiGateway({allowedVpc: vpc, allowedIps: ['GHES.IP.ADDRESS/32']})`` 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. *WARNING*: changing access type may change the URL. When the URL changes, you must update GitHub as well. Default: LambdaAccess.lambdaUrl()
2753
2789
 
@@ -2777,6 +2813,39 @@ class GitHubRunners(
2777
2813
 
2778
2814
  jsii.create(self.__class__, self, [scope, id, props])
2779
2815
 
2816
+ @jsii.member(jsii_name="createDashboard")
2817
+ def create_dashboard(
2818
+ self,
2819
+ name: typing.Optional[builtins.str] = None,
2820
+ ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Dashboard":
2821
+ '''(experimental) Creates a CloudWatch dashboard with the metrics you need to know if your runners are healthy.
2822
+
2823
+ It answers the questions you're most likely to ask:
2824
+
2825
+ - Are jobs running and passing? See "Jobs completed by status".
2826
+ - Which runner is broken? See "Failed jobs by runner label".
2827
+ - Are jobs stuck because runners fail to start? See "Runner executions".
2828
+ - Why were runners stopped before getting a job? See "Stopped runners by reason".
2829
+ - Why are runners failing to start? See "Recent failed attempts".
2830
+ - How long do runners take (and therefore cost)? See "Runner time".
2831
+ - Is GitHub reaching the webhook at all? See "Webhook".
2832
+ - Is any of our code failing? See "Lambda errors".
2833
+ - What exactly went wrong? See "Recent errors".
2834
+
2835
+ **WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners} and {@link metricStoppedRunners} which create metric filters.
2836
+ These resources may incur cost.
2837
+
2838
+ This dashboard is very basic. Pull requests and issues are welcome to improve it.
2839
+
2840
+ :param name: Name of the dashboard. Defaults to "GitHub-Runners".
2841
+
2842
+ :stability: experimental
2843
+ '''
2844
+ if __debug__:
2845
+ type_hints = cached_type_hints(_typecheckingstub__c6c824929ac2b172d81f1ca6d3f77b08aca419fe4769d0c13dc162a760e13372)
2846
+ check_type(argname="argument name", value=name, expected_type=type_hints["name"])
2847
+ return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Dashboard", jsii.invoke(self, "createDashboard", [name]))
2848
+
2780
2849
  @jsii.member(jsii_name="createLogsInsightsQueries")
2781
2850
  def create_logs_insights_queries(
2782
2851
  self,
@@ -2931,6 +3000,45 @@ class GitHubRunners(
2931
3000
 
2932
3001
  return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricJobCompleted", [props]))
2933
3002
 
3003
+ @jsii.member(jsii_name="metricLambdaErrors")
3004
+ def metric_lambda_errors(
3005
+ self,
3006
+ *,
3007
+ color: typing.Optional[builtins.str] = None,
3008
+ label: typing.Optional[builtins.str] = None,
3009
+ period: typing.Optional["_aws_cdk_ceddda9d.Duration"] = None,
3010
+ search_account: typing.Optional[builtins.str] = None,
3011
+ search_region: typing.Optional[builtins.str] = None,
3012
+ ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.MathExpression":
3013
+ '''(experimental) Metric for the number of failed invocations of the management Lambda functions.
3014
+
3015
+ These are the functions that handle webhooks, retrieve runner tokens, stop idle runners, replace stolen runners, etc. Anything over zero means
3016
+ jobs may not have gotten a runner. You should use this metric to trigger an alarm.
3017
+
3018
+ Only unhandled errors are counted here, as reported by Lambda itself. Errors that are handled and logged, like a webhook with a bad signature,
3019
+ are not failed invocations. Use the "Webhook errors" and "Orchestration errors" queries created by {@link createLogsInsightsQueries} to find
3020
+ those.
3021
+
3022
+ Management functions created after this method is called are not included. Call it last if you use warm runners.
3023
+
3024
+ :param color: Color for this metric when added to a Graph in a Dashboard. Default: - Automatic color
3025
+ :param label: Label for this expression when added to a Graph in a Dashboard. If this expression evaluates to more than one time series (for example, through the use of ``METRICS()`` or ``SEARCH()`` expressions), each time series will appear in the graph using a combination of the expression label and the individual metric label. Specify the empty string (``''``) to suppress the expression label and only keep the metric label. You can use `dynamic labels <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html>`_ to show summary information about the displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph's legend. If the math expression produces more than one time series, the maximum will be shown for each individual time series produce by this math expression. Default: - Expression value is used as label
3026
+ :param period: The period over which the math expression's statistics are applied. This period overrides all periods in the metrics used in this math expression. Default: Duration.minutes(5)
3027
+ :param search_account: Account to evaluate search expressions within. Specifying a searchAccount has no effect to the account used for metrics within the expression (passed via usingMetrics). Default: - Deployment account.
3028
+ :param search_region: Region to evaluate search expressions within. Specifying a searchRegion has no effect to the region used for metrics within the expression (passed via usingMetrics). Default: - Deployment region.
3029
+
3030
+ :stability: experimental
3031
+ '''
3032
+ props = _aws_cdk_aws_cloudwatch_ceddda9d.MathExpressionOptions(
3033
+ color=color,
3034
+ label=label,
3035
+ period=period,
3036
+ search_account=search_account,
3037
+ search_region=search_region,
3038
+ )
3039
+
3040
+ return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.MathExpression", jsii.invoke(self, "metricLambdaErrors", [props]))
3041
+
2934
3042
  @jsii.member(jsii_name="metricStolenRunners")
2935
3043
  def metric_stolen_runners(
2936
3044
  self,
@@ -2995,6 +3103,69 @@ class GitHubRunners(
2995
3103
 
2996
3104
  return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricStolenRunners", [props]))
2997
3105
 
3106
+ @jsii.member(jsii_name="metricStoppedRunners")
3107
+ def metric_stopped_runners(
3108
+ self,
3109
+ *,
3110
+ account: typing.Optional[builtins.str] = None,
3111
+ color: typing.Optional[builtins.str] = None,
3112
+ dimensions_map: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
3113
+ id: typing.Optional[builtins.str] = None,
3114
+ label: typing.Optional[builtins.str] = None,
3115
+ period: typing.Optional["_aws_cdk_ceddda9d.Duration"] = None,
3116
+ region: typing.Optional[builtins.str] = None,
3117
+ stack_account: typing.Optional[builtins.str] = None,
3118
+ stack_region: typing.Optional[builtins.str] = None,
3119
+ statistic: typing.Optional[builtins.str] = None,
3120
+ unit: typing.Optional["_aws_cdk_aws_cloudwatch_ceddda9d.Unit"] = None,
3121
+ visible: typing.Optional[builtins.bool] = None,
3122
+ ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Metric":
3123
+ '''(experimental) Metric for the number of runners we stopped on purpose before they got a job.
3124
+
3125
+ These step function executions end up as aborted and not failed, so they don't show up in {@link metricFailed}.
3126
+
3127
+ This metric has one dimension, ``Reason``, which is the error the step function was stopped with:
3128
+
3129
+ - ``IdleRunner``: the runner was idle for longer than its idle timeout and was reaped. This is usually a runner whose job was taken by
3130
+ another runner, or a job that was canceled before it started.
3131
+ - ``StaleWarmRunner``: a warm runner was replaced because its configuration changed.
3132
+ - ``WarmRunnerExpired``: a warm runner reached the end of its duration.
3133
+ - ``WarmRunnerBadDeadline``: a warm runner had an invalid deadline and was stopped.
3134
+
3135
+ **WARNING:** this method creates a metric filter. This resource may incur cost.
3136
+
3137
+ :param account: Account which this metric comes from. Default: - Deployment account.
3138
+ :param color: The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. The ``Color`` class has a set of standard colors that can be used here. Default: - Automatic color
3139
+ :param dimensions_map: Dimensions of the metric. Default: - No dimensions.
3140
+ :param id: Unique identifier for this metric when used in dashboard widgets. The id can be used as a variable to represent this metric in math expressions. Valid characters are letters, numbers, and underscore. The first character must be a lowercase letter. Default: - No ID
3141
+ :param label: Label for this metric when added to a Graph in a Dashboard. You can use `dynamic labels <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html>`_ to show summary information about the entire displayed time series in the legend. For example, if you use:: [max: ${MAX}] MyMetric As the metric label, the maximum value in the visible range will be shown next to the time series name in the graph's legend. Default: - No label
3142
+ :param period: The period over which the specified statistic is applied. Default: Duration.minutes(5)
3143
+ :param region: Region which this metric comes from. Default: - Deployment region.
3144
+ :param stack_account: Account of the stack this metric is attached to. Default: - Deployment account.
3145
+ :param stack_region: Region of the stack this metric is attached to. Default: - Deployment region.
3146
+ :param statistic: What function to use for aggregating. Use the ``aws_cloudwatch.Stats`` helper class to construct valid input strings. Can be one of the following: - "Minimum" | "min" - "Maximum" | "max" - "Average" | "avg" - "Sum" | "sum" - "SampleCount | "n" - "pNN.NN" - "tmNN.NN" | "tm(NN.NN%:NN.NN%)" - "iqm" - "wmNN.NN" | "wm(NN.NN%:NN.NN%)" - "tcNN.NN" | "tc(NN.NN%:NN.NN%)" - "tsNN.NN" | "ts(NN.NN%:NN.NN%)" Default: Average
3147
+ :param unit: Unit used to filter the metric stream. Only refer to datums emitted to the metric stream with the given unit and ignore all others. Only useful when datums are being emitted to the same metric stream under different units. The default is to use all matric datums in the stream, regardless of unit, which is recommended in nearly all cases. CloudWatch does not honor this property for graphs. Default: - All metric datums in the given metric stream
3148
+ :param visible: Whether this metric should be visible in dashboard graphs. Setting this to false is useful when you want to hide raw metrics that are used in math expressions, and show only the expression results. Default: true
3149
+
3150
+ :stability: experimental
3151
+ '''
3152
+ props = _aws_cdk_aws_cloudwatch_ceddda9d.MetricOptions(
3153
+ account=account,
3154
+ color=color,
3155
+ dimensions_map=dimensions_map,
3156
+ id=id,
3157
+ label=label,
3158
+ period=period,
3159
+ region=region,
3160
+ stack_account=stack_account,
3161
+ stack_region=stack_region,
3162
+ statistic=statistic,
3163
+ unit=unit,
3164
+ visible=visible,
3165
+ )
3166
+
3167
+ return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricStoppedRunners", [props]))
3168
+
2998
3169
  @jsii.member(jsii_name="metricSucceeded")
2999
3170
  def metric_succeeded(
3000
3171
  self,
@@ -3200,7 +3371,7 @@ class GitHubRunnersProps:
3200
3371
  :param security_groups: (experimental) Security groups attached to all management functions. Use this to provide outbound access from management functions to GitHub Enterprise Server hosted inside a VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting. **Note:** Defining inbound rules on this security group does nothing. This security group only controls outbound access FROM the management functions. To limit access TO the webhook or setup functions, use {@link webhookAccess} and {@link setupAccess} instead.
3201
3372
  :param setup_access: (experimental) Access configuration for the setup function. 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. Default: LambdaAccess.lambdaUrl()
3202
3373
  :param status_access: (experimental) Access configuration for the status function. 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. Default: LambdaAccess.noAccess()
3203
- :param vpc: (experimental) VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting and will run outside the VPC. Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints: - GitHub Enterprise Server - Secrets Manager - SQS - Step Functions - CloudFormation (status function only) - EC2 (status function only) - ECR (status function only)
3374
+ :param vpc: (experimental) VPC used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting and will run outside the VPC. Make sure the selected VPC and subnets have access to the following with either NAT Gateway or VPC Endpoints: - GitHub Enterprise Server - Secrets Manager - SQS - Step Functions - CloudFormation (status function only) - EC2 - ECR (status function only)
3204
3375
  :param vpc_subnets: (experimental) VPC subnets used for all management functions. Use this with GitHub Enterprise Server hosted that's inaccessible from outside the VPC. **Note:** This only affects management functions that interact with GitHub. Lambda functions that help with runner image building and don't interact with GitHub are NOT affected by this setting.
3205
3376
  :param webhook_access: (experimental) Access configuration for the webhook function. 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() })``. You can also set this to ``LambdaAccess.apiGateway({allowedVpc: vpc, allowedIps: ['GHES.IP.ADDRESS/32']})`` 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. *WARNING*: changing access type may change the URL. When the URL changes, you must update GitHub as well. Default: LambdaAccess.lambdaUrl()
3206
3377
 
@@ -3471,7 +3642,7 @@ class GitHubRunnersProps:
3471
3642
  - SQS
3472
3643
  - Step Functions
3473
3644
  - CloudFormation (status function only)
3474
- - EC2 (status function only)
3645
+ - EC2
3475
3646
  - ECR (status function only)
3476
3647
 
3477
3648
  :stability: experimental
@@ -4711,6 +4882,7 @@ class LambdaRunnerProvider(
4711
4882
 
4712
4883
  @jsii.python.classproperty
4713
4884
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
4885
+ @builtins.classmethod
4714
4886
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
4715
4887
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirement for Lambda runner.
4716
4888
 
@@ -4729,6 +4901,7 @@ class LambdaRunnerProvider(
4729
4901
 
4730
4902
  @jsii.python.classproperty
4731
4903
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
4904
+ @builtins.classmethod
4732
4905
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
4733
4906
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirement for Lambda runner.
4734
4907
 
@@ -5143,6 +5316,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5143
5316
 
5144
5317
  @jsii.python.classproperty
5145
5318
  @jsii.member(jsii_name="LINUX")
5319
+ @builtins.classmethod
5146
5320
  def LINUX(cls) -> "Os":
5147
5321
  '''(deprecated) Linux.
5148
5322
 
@@ -5154,6 +5328,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5154
5328
 
5155
5329
  @jsii.python.classproperty
5156
5330
  @jsii.member(jsii_name="LINUX_AMAZON_2")
5331
+ @builtins.classmethod
5157
5332
  def LINUX_AMAZON_2(cls) -> "Os":
5158
5333
  '''(experimental) Amazon Linux 2.
5159
5334
 
@@ -5163,6 +5338,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5163
5338
 
5164
5339
  @jsii.python.classproperty
5165
5340
  @jsii.member(jsii_name="LINUX_AMAZON_2023")
5341
+ @builtins.classmethod
5166
5342
  def LINUX_AMAZON_2023(cls) -> "Os":
5167
5343
  '''(experimental) Amazon Linux 2023.
5168
5344
 
@@ -5172,6 +5348,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5172
5348
 
5173
5349
  @jsii.python.classproperty
5174
5350
  @jsii.member(jsii_name="LINUX_UBUNTU")
5351
+ @builtins.classmethod
5175
5352
  def LINUX_UBUNTU(cls) -> "Os":
5176
5353
  '''(experimental) Ubuntu Linux.
5177
5354
 
@@ -5181,6 +5358,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5181
5358
 
5182
5359
  @jsii.python.classproperty
5183
5360
  @jsii.member(jsii_name="LINUX_UBUNTU_2204")
5361
+ @builtins.classmethod
5184
5362
  def LINUX_UBUNTU_2204(cls) -> "Os":
5185
5363
  '''(experimental) Ubuntu Linux 22.04.
5186
5364
 
@@ -5190,6 +5368,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5190
5368
 
5191
5369
  @jsii.python.classproperty
5192
5370
  @jsii.member(jsii_name="LINUX_UBUNTU_2404")
5371
+ @builtins.classmethod
5193
5372
  def LINUX_UBUNTU_2404(cls) -> "Os":
5194
5373
  '''(experimental) Ubuntu Linux 24.04.
5195
5374
 
@@ -5199,6 +5378,7 @@ class Os(metaclass=jsii.JSIIMeta, jsii_type="@cloudsnorkel/cdk-github-runners.Os
5199
5378
 
5200
5379
  @jsii.python.classproperty
5201
5380
  @jsii.member(jsii_name="WINDOWS")
5381
+ @builtins.classmethod
5202
5382
  def WINDOWS(cls) -> "Os":
5203
5383
  '''(experimental) Windows.
5204
5384
 
@@ -7924,7 +8104,7 @@ class AmiBuilder(
7924
8104
  if __debug__:
7925
8105
  type_hints = cached_type_hints(_typecheckingstub__8088868062a70621aab7b900883cf52d9c930de8a458039564d69a7d0cc80f52)
7926
8106
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
7927
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
8107
+ jsii.set(self, "components", value)
7928
8108
 
7929
8109
 
7930
8110
  @jsii.implements(IRunnerImageBuilder)
@@ -8340,6 +8520,7 @@ class CodeBuildRunnerProvider(
8340
8520
 
8341
8521
  @jsii.python.classproperty
8342
8522
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
8523
+ @builtins.classmethod
8343
8524
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
8344
8525
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner.
8345
8526
 
@@ -8362,6 +8543,7 @@ class CodeBuildRunnerProvider(
8362
8543
 
8363
8544
  @jsii.python.classproperty
8364
8545
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
8546
+ @builtins.classmethod
8365
8547
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
8366
8548
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner.
8367
8549
 
@@ -9102,7 +9284,7 @@ class ContainerImageBuilder(
9102
9284
  if __debug__:
9103
9285
  type_hints = cached_type_hints(_typecheckingstub__f4c47d52e3f51709153fc49a53f833f06b1fd2ba44d3c86696b418a3bf88a972)
9104
9286
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
9105
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
9287
+ jsii.set(self, "components", value)
9106
9288
 
9107
9289
 
9108
9290
  @jsii.implements(IRunnerProvider, _constructs_77d1e7e8.IConstruct)
@@ -9158,7 +9340,7 @@ class Ec2RunnerProvider(
9158
9340
  :param storage_size: (experimental) Size of volume available for launched runner instances. This modifies the boot volume size and doesn't add any additional volumes. Default: 30GB
9159
9341
  :param subnet: (deprecated) Subnet where the runner instances will be launched. Default: default subnet of account's default VPC
9160
9342
  :param subnet_selection: (experimental) Where to place the network interfaces within the VPC. Only the first matched subnet will be used. Default: default VPC subnet
9161
- :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may override the built-in tags. Default: no additional tags
9343
+ :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``, and ``GitHubRunners:Runner``. You may only override ``Name``. Tags prefixed ``GitHubRunners:`` are reserved and rejected. Some of our reserved tags are used for house-keeping purposes. Default: no additional tags
9162
9344
  :param vpc: (experimental) VPC where runner instances will be launched. Default: default account VPC
9163
9345
  :param default_labels: (experimental) Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like ``self-hosted``, ``linux``, ``x64``, and ``arm64``. Default: true
9164
9346
  :param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
@@ -9410,7 +9592,7 @@ class Ec2RunnerProviderProps(RunnerProviderProps):
9410
9592
  :param storage_size: (experimental) Size of volume available for launched runner instances. This modifies the boot volume size and doesn't add any additional volumes. Default: 30GB
9411
9593
  :param subnet: (deprecated) Subnet where the runner instances will be launched. Default: default subnet of account's default VPC
9412
9594
  :param subnet_selection: (experimental) Where to place the network interfaces within the VPC. Only the first matched subnet will be used. Default: default VPC subnet
9413
- :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may override the built-in tags. Default: no additional tags
9595
+ :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``, and ``GitHubRunners:Runner``. You may only override ``Name``. Tags prefixed ``GitHubRunners:`` are reserved and rejected. Some of our reserved tags are used for house-keeping purposes. Default: no additional tags
9414
9596
  :param vpc: (experimental) VPC where runner instances will be launched. Default: default account VPC
9415
9597
 
9416
9598
  :stability: experimental
@@ -9699,8 +9881,9 @@ class Ec2RunnerProviderProps(RunnerProviderProps):
9699
9881
  def tags(self) -> typing.Optional[typing.Mapping[builtins.str, builtins.str]]:
9700
9882
  '''(experimental) Additional tags to apply to launched runner instances and their volumes.
9701
9883
 
9702
- These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``.
9703
- You may override the built-in tags.
9884
+ These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``, and
9885
+ ``GitHubRunners:Runner``. You may only override ``Name``. Tags prefixed ``GitHubRunners:`` are reserved and rejected. Some of our reserved tags are
9886
+ used for house-keeping purposes.
9704
9887
 
9705
9888
  :default: no additional tags
9706
9889
 
@@ -9776,6 +9959,7 @@ class EcsRunnerProvider(
9776
9959
  storage_options: typing.Optional[typing.Union["StorageOptions", typing.Dict[builtins.str, typing.Any]]] = None,
9777
9960
  storage_size: typing.Optional["_aws_cdk_ceddda9d.Size"] = None,
9778
9961
  subnet_selection: typing.Optional[typing.Union["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection", typing.Dict[builtins.str, typing.Any]]] = None,
9962
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
9779
9963
  vpc: typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"] = None,
9780
9964
  default_labels: typing.Optional[builtins.bool] = None,
9781
9965
  log_retention: typing.Optional["_aws_cdk_aws_logs_ceddda9d.RetentionDays"] = None,
@@ -9806,6 +9990,7 @@ class EcsRunnerProvider(
9806
9990
  :param storage_options: (experimental) Options for runner instance storage volume.
9807
9991
  :param storage_size: (experimental) Size of volume available for launched cluster instances. This modifies the boot volume size and doesn't add any additional volumes. Each instance can be used by multiple runners, so make sure there is enough space for all of them. Default: default size for AMI (usually 30GB for Linux and 50GB for Windows)
9808
9992
  :param subnet_selection: (experimental) Subnets to run the runners in. Default: ECS default
9993
+ :param tags: (experimental) Additional tags to apply to launched runner tasks. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may not override tags with the ``GitHubRunners:`` prefix. Default: no additional tags
9809
9994
  :param vpc: (experimental) VPC to launch the runners in. Default: default account VPC
9810
9995
  :param default_labels: (experimental) Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like ``self-hosted``, ``linux``, ``x64``, and ``arm64``. Default: true
9811
9996
  :param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
@@ -9840,6 +10025,7 @@ class EcsRunnerProvider(
9840
10025
  storage_options=storage_options,
9841
10026
  storage_size=storage_size,
9842
10027
  subnet_selection=subnet_selection,
10028
+ tags=tags,
9843
10029
  vpc=vpc,
9844
10030
  default_labels=default_labels,
9845
10031
  log_retention=log_retention,
@@ -10039,6 +10225,7 @@ class EcsRunnerProvider(
10039
10225
  "storage_options": "storageOptions",
10040
10226
  "storage_size": "storageSize",
10041
10227
  "subnet_selection": "subnetSelection",
10228
+ "tags": "tags",
10042
10229
  "vpc": "vpc",
10043
10230
  },
10044
10231
  )
@@ -10071,6 +10258,7 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10071
10258
  storage_options: typing.Optional[typing.Union["StorageOptions", typing.Dict[builtins.str, typing.Any]]] = None,
10072
10259
  storage_size: typing.Optional["_aws_cdk_ceddda9d.Size"] = None,
10073
10260
  subnet_selection: typing.Optional[typing.Union["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection", typing.Dict[builtins.str, typing.Any]]] = None,
10261
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
10074
10262
  vpc: typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"] = None,
10075
10263
  ) -> None:
10076
10264
  '''(experimental) Properties for EcsRunnerProvider.
@@ -10100,6 +10288,7 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10100
10288
  :param storage_options: (experimental) Options for runner instance storage volume.
10101
10289
  :param storage_size: (experimental) Size of volume available for launched cluster instances. This modifies the boot volume size and doesn't add any additional volumes. Each instance can be used by multiple runners, so make sure there is enough space for all of them. Default: default size for AMI (usually 30GB for Linux and 50GB for Windows)
10102
10290
  :param subnet_selection: (experimental) Subnets to run the runners in. Default: ECS default
10291
+ :param tags: (experimental) Additional tags to apply to launched runner tasks. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may not override tags with the ``GitHubRunners:`` prefix. Default: no additional tags
10103
10292
  :param vpc: (experimental) VPC to launch the runners in. Default: default account VPC
10104
10293
 
10105
10294
  :stability: experimental
@@ -10137,6 +10326,7 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10137
10326
  check_type(argname="argument storage_options", value=storage_options, expected_type=type_hints["storage_options"])
10138
10327
  check_type(argname="argument storage_size", value=storage_size, expected_type=type_hints["storage_size"])
10139
10328
  check_type(argname="argument subnet_selection", value=subnet_selection, expected_type=type_hints["subnet_selection"])
10329
+ check_type(argname="argument tags", value=tags, expected_type=type_hints["tags"])
10140
10330
  check_type(argname="argument vpc", value=vpc, expected_type=type_hints["vpc"])
10141
10331
  self._values: typing.Dict[builtins.str, typing.Any] = {}
10142
10332
  if default_labels is not None:
@@ -10189,6 +10379,8 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10189
10379
  self._values["storage_size"] = storage_size
10190
10380
  if subnet_selection is not None:
10191
10381
  self._values["subnet_selection"] = subnet_selection
10382
+ if tags is not None:
10383
+ self._values["tags"] = tags
10192
10384
  if vpc is not None:
10193
10385
  self._values["vpc"] = vpc
10194
10386
 
@@ -10529,6 +10721,20 @@ class EcsRunnerProviderProps(RunnerProviderProps):
10529
10721
  result = self._values.get("subnet_selection")
10530
10722
  return typing.cast(typing.Optional["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection"], result)
10531
10723
 
10724
+ @builtins.property
10725
+ def tags(self) -> typing.Optional[typing.Mapping[builtins.str, builtins.str]]:
10726
+ '''(experimental) Additional tags to apply to launched runner tasks.
10727
+
10728
+ These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``.
10729
+ You may not override tags with the ``GitHubRunners:`` prefix.
10730
+
10731
+ :default: no additional tags
10732
+
10733
+ :stability: experimental
10734
+ '''
10735
+ result = self._values.get("tags")
10736
+ return typing.cast(typing.Optional[typing.Mapping[builtins.str, builtins.str]], result)
10737
+
10532
10738
  @builtins.property
10533
10739
  def vpc(self) -> typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"]:
10534
10740
  '''(experimental) VPC to launch the runners in.
@@ -10585,6 +10791,7 @@ class FargateRunnerProvider(
10585
10791
  security_groups: typing.Optional[typing.Sequence["_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup"]] = None,
10586
10792
  spot: typing.Optional[builtins.bool] = None,
10587
10793
  subnet_selection: typing.Optional[typing.Union["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection", typing.Dict[builtins.str, typing.Any]]] = None,
10794
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
10588
10795
  vpc: typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"] = None,
10589
10796
  default_labels: typing.Optional[builtins.bool] = None,
10590
10797
  log_retention: typing.Optional["_aws_cdk_aws_logs_ceddda9d.RetentionDays"] = None,
@@ -10606,6 +10813,7 @@ class FargateRunnerProvider(
10606
10813
  :param security_groups: (experimental) Security groups to assign to the task. Default: a new security group
10607
10814
  :param spot: (experimental) Use Fargate spot capacity provider to save money. - Runners may fail to start due to missing capacity. - Runners might be stopped prematurely with spot pricing. Default: false
10608
10815
  :param subnet_selection: (experimental) Subnets to run the runners in. Default: Fargate default
10816
+ :param tags: (experimental) Additional tags to apply to launched runner tasks. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may not override tags with the ``GitHubRunners:`` prefix. Default: no additional tags
10609
10817
  :param vpc: (experimental) VPC to launch the runners in. Default: default account VPC
10610
10818
  :param default_labels: (experimental) Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like ``self-hosted``, ``linux``, ``x64``, and ``arm64``. Default: true
10611
10819
  :param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
@@ -10631,6 +10839,7 @@ class FargateRunnerProvider(
10631
10839
  security_groups=security_groups,
10632
10840
  spot=spot,
10633
10841
  subnet_selection=subnet_selection,
10842
+ tags=tags,
10634
10843
  vpc=vpc,
10635
10844
  default_labels=default_labels,
10636
10845
  log_retention=log_retention,
@@ -10752,6 +10961,7 @@ class FargateRunnerProvider(
10752
10961
 
10753
10962
  @jsii.python.classproperty
10754
10963
  @jsii.member(jsii_name="LINUX_ARM64_DOCKERFILE_PATH")
10964
+ @builtins.classmethod
10755
10965
  def LINUX_ARM64_DOCKERFILE_PATH(cls) -> builtins.str:
10756
10966
  '''(deprecated) Path to Dockerfile for Linux ARM64 with all the requirement for Fargate runner.
10757
10967
 
@@ -10770,6 +10980,7 @@ class FargateRunnerProvider(
10770
10980
 
10771
10981
  @jsii.python.classproperty
10772
10982
  @jsii.member(jsii_name="LINUX_X64_DOCKERFILE_PATH")
10983
+ @builtins.classmethod
10773
10984
  def LINUX_X64_DOCKERFILE_PATH(cls) -> builtins.str:
10774
10985
  '''(deprecated) Path to Dockerfile for Linux x64 with all the requirement for Fargate runner.
10775
10986
 
@@ -10935,6 +11146,7 @@ class FargateRunnerProvider(
10935
11146
  "security_groups": "securityGroups",
10936
11147
  "spot": "spot",
10937
11148
  "subnet_selection": "subnetSelection",
11149
+ "tags": "tags",
10938
11150
  "vpc": "vpc",
10939
11151
  },
10940
11152
  )
@@ -10958,6 +11170,7 @@ class FargateRunnerProviderProps(RunnerProviderProps):
10958
11170
  security_groups: typing.Optional[typing.Sequence["_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup"]] = None,
10959
11171
  spot: typing.Optional[builtins.bool] = None,
10960
11172
  subnet_selection: typing.Optional[typing.Union["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection", typing.Dict[builtins.str, typing.Any]]] = None,
11173
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
10961
11174
  vpc: typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"] = None,
10962
11175
  ) -> None:
10963
11176
  '''(experimental) Properties for FargateRunnerProvider.
@@ -10978,6 +11191,7 @@ class FargateRunnerProviderProps(RunnerProviderProps):
10978
11191
  :param security_groups: (experimental) Security groups to assign to the task. Default: a new security group
10979
11192
  :param spot: (experimental) Use Fargate spot capacity provider to save money. - Runners may fail to start due to missing capacity. - Runners might be stopped prematurely with spot pricing. Default: false
10980
11193
  :param subnet_selection: (experimental) Subnets to run the runners in. Default: Fargate default
11194
+ :param tags: (experimental) Additional tags to apply to launched runner tasks. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may not override tags with the ``GitHubRunners:`` prefix. Default: no additional tags
10981
11195
  :param vpc: (experimental) VPC to launch the runners in. Default: default account VPC
10982
11196
 
10983
11197
  :stability: experimental
@@ -11004,6 +11218,7 @@ class FargateRunnerProviderProps(RunnerProviderProps):
11004
11218
  check_type(argname="argument security_groups", value=security_groups, expected_type=type_hints["security_groups"])
11005
11219
  check_type(argname="argument spot", value=spot, expected_type=type_hints["spot"])
11006
11220
  check_type(argname="argument subnet_selection", value=subnet_selection, expected_type=type_hints["subnet_selection"])
11221
+ check_type(argname="argument tags", value=tags, expected_type=type_hints["tags"])
11007
11222
  check_type(argname="argument vpc", value=vpc, expected_type=type_hints["vpc"])
11008
11223
  self._values: typing.Dict[builtins.str, typing.Any] = {}
11009
11224
  if default_labels is not None:
@@ -11038,6 +11253,8 @@ class FargateRunnerProviderProps(RunnerProviderProps):
11038
11253
  self._values["spot"] = spot
11039
11254
  if subnet_selection is not None:
11040
11255
  self._values["subnet_selection"] = subnet_selection
11256
+ if tags is not None:
11257
+ self._values["tags"] = tags
11041
11258
  if vpc is not None:
11042
11259
  self._values["vpc"] = vpc
11043
11260
 
@@ -11283,6 +11500,20 @@ class FargateRunnerProviderProps(RunnerProviderProps):
11283
11500
  result = self._values.get("subnet_selection")
11284
11501
  return typing.cast(typing.Optional["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection"], result)
11285
11502
 
11503
+ @builtins.property
11504
+ def tags(self) -> typing.Optional[typing.Mapping[builtins.str, builtins.str]]:
11505
+ '''(experimental) Additional tags to apply to launched runner tasks.
11506
+
11507
+ These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``.
11508
+ You may not override tags with the ``GitHubRunners:`` prefix.
11509
+
11510
+ :default: no additional tags
11511
+
11512
+ :stability: experimental
11513
+ '''
11514
+ result = self._values.get("tags")
11515
+ return typing.cast(typing.Optional[typing.Mapping[builtins.str, builtins.str]], result)
11516
+
11286
11517
  @builtins.property
11287
11518
  def vpc(self) -> typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"]:
11288
11519
  '''(experimental) VPC to launch the runners in.
@@ -12041,7 +12272,7 @@ class RunnerImageBuilder(
12041
12272
  if __debug__:
12042
12273
  type_hints = cached_type_hints(_typecheckingstub__705c18a1eedaa490aebad511aac32a801519a57162e30be4673a8ab87ca434dc)
12043
12274
  check_type(argname="argument value", value=value, expected_type=type_hints["value"])
12044
- jsii.set(self, "components", value) # pyright: ignore[reportArgumentType]
12275
+ jsii.set(self, "components", value)
12045
12276
 
12046
12277
 
12047
12278
  class _RunnerImageBuilderProxy(RunnerImageBuilder):
@@ -12222,7 +12453,7 @@ class Ec2Runner(
12222
12453
  :param storage_size: (experimental) Size of volume available for launched runner instances. This modifies the boot volume size and doesn't add any additional volumes. Default: 30GB
12223
12454
  :param subnet: (deprecated) Subnet where the runner instances will be launched. Default: default subnet of account's default VPC
12224
12455
  :param subnet_selection: (experimental) Where to place the network interfaces within the VPC. Only the first matched subnet will be used. Default: default VPC subnet
12225
- :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may override the built-in tags. Default: no additional tags
12456
+ :param tags: (experimental) Additional tags to apply to launched runner instances and their volumes. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``, and ``GitHubRunners:Runner``. You may only override ``Name``. Tags prefixed ``GitHubRunners:`` are reserved and rejected. Some of our reserved tags are used for house-keeping purposes. Default: no additional tags
12226
12457
  :param vpc: (experimental) VPC where runner instances will be launched. Default: default account VPC
12227
12458
  :param default_labels: (experimental) Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like ``self-hosted``, ``linux``, ``x64``, and ``arm64``. Default: true
12228
12459
  :param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
@@ -12287,6 +12518,7 @@ class FargateRunner(
12287
12518
  security_groups: typing.Optional[typing.Sequence["_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup"]] = None,
12288
12519
  spot: typing.Optional[builtins.bool] = None,
12289
12520
  subnet_selection: typing.Optional[typing.Union["_aws_cdk_aws_ec2_ceddda9d.SubnetSelection", typing.Dict[builtins.str, typing.Any]]] = None,
12521
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
12290
12522
  vpc: typing.Optional["_aws_cdk_aws_ec2_ceddda9d.IVpc"] = None,
12291
12523
  default_labels: typing.Optional[builtins.bool] = None,
12292
12524
  log_retention: typing.Optional["_aws_cdk_aws_logs_ceddda9d.RetentionDays"] = None,
@@ -12308,6 +12540,7 @@ class FargateRunner(
12308
12540
  :param security_groups: (experimental) Security groups to assign to the task. Default: a new security group
12309
12541
  :param spot: (experimental) Use Fargate spot capacity provider to save money. - Runners may fail to start due to missing capacity. - Runners might be stopped prematurely with spot pricing. Default: false
12310
12542
  :param subnet_selection: (experimental) Subnets to run the runners in. Default: Fargate default
12543
+ :param tags: (experimental) Additional tags to apply to launched runner tasks. These additional tags are set on top of ``Name``, ``GitHubRunners:Provider``, ``GitHubRunners:Repo``, and ``GitHubRunners:Labels``. You may not override tags with the ``GitHubRunners:`` prefix. Default: no additional tags
12311
12544
  :param vpc: (experimental) VPC to launch the runners in. Default: default account VPC
12312
12545
  :param default_labels: (experimental) Add default labels based on OS and architecture of the runner. This will tell GitHub Runner to add default labels like ``self-hosted``, ``linux``, ``x64``, and ``arm64``. Default: true
12313
12546
  :param log_retention: (experimental) The number of days log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. Default: logs.RetentionDays.ONE_MONTH
@@ -12333,6 +12566,7 @@ class FargateRunner(
12333
12566
  security_groups=security_groups,
12334
12567
  spot=spot,
12335
12568
  subnet_selection=subnet_selection,
12569
+ tags=tags,
12336
12570
  vpc=vpc,
12337
12571
  default_labels=default_labels,
12338
12572
  log_retention=log_retention,
@@ -12675,6 +12909,12 @@ def _typecheckingstub__c1a45de07d09ed9f4fd0b9051aeff4571ceda633f49c0b30a5058ad6d
12675
12909
  """Type checking stubs"""
12676
12910
  pass
12677
12911
 
12912
+ def _typecheckingstub__c6c824929ac2b172d81f1ca6d3f77b08aca419fe4769d0c13dc162a760e13372(
12913
+ name: typing.Optional[builtins.str] = None,
12914
+ ) -> None:
12915
+ """Type checking stubs"""
12916
+ pass
12917
+
12678
12918
  def _typecheckingstub__e3d8d4287a56d393e1fe438a511f3c5c95bcb80987e93de575d61fc0507cb7f1(
12679
12919
  prefix: typing.Optional[builtins.str] = None,
12680
12920
  ) -> None:
@@ -13636,6 +13876,7 @@ def _typecheckingstub__c520325dd0289bf8c6670ecdce77df4b229a0a2681957e61665818d2f
13636
13876
  storage_options: typing.Optional[typing.Union[StorageOptions, typing.Dict[builtins.str, typing.Any]]] = None,
13637
13877
  storage_size: typing.Optional[_aws_cdk_ceddda9d.Size] = None,
13638
13878
  subnet_selection: typing.Optional[typing.Union[_aws_cdk_aws_ec2_ceddda9d.SubnetSelection, typing.Dict[builtins.str, typing.Any]]] = None,
13879
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
13639
13880
  vpc: typing.Optional[_aws_cdk_aws_ec2_ceddda9d.IVpc] = None,
13640
13881
  default_labels: typing.Optional[builtins.bool] = None,
13641
13882
  log_retention: typing.Optional[_aws_cdk_aws_logs_ceddda9d.RetentionDays] = None,
@@ -13704,6 +13945,7 @@ def _typecheckingstub__73c1978e12dcea1bd69ce0927a80bd887d7f7d1b6573831942495e9d5
13704
13945
  storage_options: typing.Optional[typing.Union[StorageOptions, typing.Dict[builtins.str, typing.Any]]] = None,
13705
13946
  storage_size: typing.Optional[_aws_cdk_ceddda9d.Size] = None,
13706
13947
  subnet_selection: typing.Optional[typing.Union[_aws_cdk_aws_ec2_ceddda9d.SubnetSelection, typing.Dict[builtins.str, typing.Any]]] = None,
13948
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
13707
13949
  vpc: typing.Optional[_aws_cdk_aws_ec2_ceddda9d.IVpc] = None,
13708
13950
  ) -> None:
13709
13951
  """Type checking stubs"""
@@ -13726,6 +13968,7 @@ def _typecheckingstub__f7098876c10584a4cc58e16d23fd86ffe1fc50f2b55ca60549136d051
13726
13968
  security_groups: typing.Optional[typing.Sequence[_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup]] = None,
13727
13969
  spot: typing.Optional[builtins.bool] = None,
13728
13970
  subnet_selection: typing.Optional[typing.Union[_aws_cdk_aws_ec2_ceddda9d.SubnetSelection, typing.Dict[builtins.str, typing.Any]]] = None,
13971
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
13729
13972
  vpc: typing.Optional[_aws_cdk_aws_ec2_ceddda9d.IVpc] = None,
13730
13973
  default_labels: typing.Optional[builtins.bool] = None,
13731
13974
  log_retention: typing.Optional[_aws_cdk_aws_logs_ceddda9d.RetentionDays] = None,
@@ -13785,6 +14028,7 @@ def _typecheckingstub__26cdeb87df1adf5c49e0f9c1c061c7138af674da9af221212e1505fc1
13785
14028
  security_groups: typing.Optional[typing.Sequence[_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup]] = None,
13786
14029
  spot: typing.Optional[builtins.bool] = None,
13787
14030
  subnet_selection: typing.Optional[typing.Union[_aws_cdk_aws_ec2_ceddda9d.SubnetSelection, typing.Dict[builtins.str, typing.Any]]] = None,
14031
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
13788
14032
  vpc: typing.Optional[_aws_cdk_aws_ec2_ceddda9d.IVpc] = None,
13789
14033
  ) -> None:
13790
14034
  """Type checking stubs"""
@@ -13978,6 +14222,7 @@ def _typecheckingstub__e507aa08f983fcd409ec9cf4ba5e0e6312ce72778cbbb2f9b5b016fde
13978
14222
  security_groups: typing.Optional[typing.Sequence[_aws_cdk_aws_ec2_ceddda9d.ISecurityGroup]] = None,
13979
14223
  spot: typing.Optional[builtins.bool] = None,
13980
14224
  subnet_selection: typing.Optional[typing.Union[_aws_cdk_aws_ec2_ceddda9d.SubnetSelection, typing.Dict[builtins.str, typing.Any]]] = None,
14225
+ tags: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
13981
14226
  vpc: typing.Optional[_aws_cdk_aws_ec2_ceddda9d.IVpc] = None,
13982
14227
  default_labels: typing.Optional[builtins.bool] = None,
13983
14228
  log_retention: typing.Optional[_aws_cdk_aws_logs_ceddda9d.RetentionDays] = None,
@@ -19,9 +19,9 @@ import constructs._jsii
19
19
 
20
20
  __jsii_assembly__ = jsii.JSIIAssembly.load(
21
21
  "@cloudsnorkel/cdk-github-runners",
22
- "0.17.0",
22
+ "0.18.0",
23
23
  __name__[0:-6],
24
- "cdk-github-runners@0.17.0.jsii.tgz",
24
+ "cdk-github-runners@0.18.0.jsii.tgz",
25
25
  )
26
26
 
27
27
  __all__ = [
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: cloudsnorkel.cdk-github-runners
3
- Version: 0.17.0
3
+ Version: 0.18.0
4
4
  Summary: CDK construct to create GitHub Actions self-hosted runners. Creates ephemeral runners on demand. Easy to deploy and highly customizable.
5
5
  Home-page: https://github.com/CloudSnorkel/cdk-github-runners.git
6
6
  Author: Amir Szekely<amir@cloudsnorkel.com>
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
24
  Requires-Dist: aws-cdk-lib<3.0.0,>=2.239.0
25
25
  Requires-Dist: constructs<11.0.0,>=10.5.1
26
- Requires-Dist: jsii<2.0.0,>=1.139.0
26
+ Requires-Dist: jsii<2.0.0,>=1.142.0
27
27
  Requires-Dist: publication>=0.0.3
28
28
 
29
29
  # GitHub Self-Hosted Runners CDK Constructs
@@ -36,6 +36,7 @@ Requires-Dist: publication>=0.0.3
36
36
  [![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)
37
37
  [![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/vdrTUTqQKv)
38
38
  [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/CloudSnorkel/cdk-github-runners/blob/main/LICENSE)
39
+ [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners)
39
40
 
40
41
  Use this CDK construct to create ephemeral [self-hosted GitHub runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) on-demand inside your AWS account.
41
42
 
@@ -50,7 +51,7 @@ Self-hosted runners in AWS are useful when:
50
51
  * You need easy access to internal resources in your actions
51
52
  * You want to pre-install some software for your actions
52
53
  * You want to provide some basic AWS API access (but [aws-actions/configure-aws-credentials](https://github.com/marketplace/actions/configure-aws-credentials-action-for-github-actions) has more security controls)
53
- * You are using GitHub Enterprise Server
54
+ * You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with [just-in-time configurations](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners))
54
55
 
55
56
  Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling) 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.
56
57
 
@@ -67,6 +68,8 @@ Ephemeral (or on-demand) runners are the [recommended way by GitHub](https://doc
67
68
  * [Examples](#examples)
68
69
  * [Architecture](#architecture)
69
70
  * [Troubleshooting](#troubleshooting)
71
+
72
+ * [Rebuilding runner images](#rebuilding-runner-images)
70
73
  * [Monitoring](#monitoring)
71
74
  * [Getting Help](#getting-help)
72
75
  * [Contributing](#contributing)
@@ -620,7 +623,9 @@ If you have more to share, please open a PR adding examples to the `examples` fo
620
623
 
621
624
  ## Troubleshooting
622
625
 
623
- Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. Configuration issue related errors like pointing to a missing AMI will not be retried. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
626
+ Runners are started in response to a webhook coming in from GitHub. If there are any issues starting the runner like missing capacity or transient API issues, the provider will keep retrying for 24 hours. GitHub itself will cancel the job if it can't find a runner for 24 hours. If your jobs don't start, follow the steps below to examine all parts of this workflow.
627
+
628
+ Configuration problems that we can detect up-front fail the orchestrator with a `RunnerConfigurationError` before any instance, build, or task is started. The error message says what needs to be fixed. These are still retried like any other error, so a configuration fixed within the 24 hours GitHub keeps the job queued still gets a runner and the job still runs.
624
629
 
625
630
  1. Always start with the status function, make sure no errors are reported, and confirm all status codes are OK
626
631
  2. Make sure `runs-on` in the workflow matches the expected labels set in the runner provider
@@ -634,6 +639,7 @@ Runners are started in response to a webhook coming in from GitHub. If there are
634
639
  1. If it's not called or logs errors, confirm the webhook settings on the GitHub side
635
640
  2. If you see too many errors, make sure you're only sending `workflow_job` events
636
641
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
642
+ 6. If runners start but never pick up a job and get stopped with `IdleRunner`, their runner version may be too old. Runners can't update themselves, and GitHub stops sending jobs to runners that are not updated within 30 days of a new runner release, or right away for a critical security update. [Rebuild your runner images](#rebuilding-runner-images) to fix it
637
643
 
638
644
  All logs are saved in CloudWatch.
639
645
 
@@ -646,12 +652,36 @@ To get `status.json`, check out the CloudFormation stack output for a command th
646
652
  aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json
647
653
  ```
648
654
 
655
+ ### Rebuilding runner images
656
+
657
+ Runner images are rebuilt every `rebuildInterval` (7 days by default). To rebuild all of them right now, run this with the name of the every stack your runners are built in. It starts every image builder in the stack and prints the build ids. Runners pick up the new images as soon as the builds finish.
658
+
659
+ ```sh
660
+ STACK=my-runners-stack
661
+ resources() {
662
+ aws cloudformation list-stack-resources --stack-name "$STACK" --output text \
663
+ --query "StackResourceSummaries[?ResourceType=='$1'].PhysicalResourceId"
664
+ }
665
+ for project in $(resources AWS::CodeBuild::Project); do
666
+ # skip runner projects of CodeBuild providers, we only want image builders
667
+ aws codebuild batch-get-projects --names "$project" --output text --query 'projects[0].description' \
668
+ | grep -q '^Build docker image for self-hosted GitHub runner' \
669
+ && aws codebuild start-build --project-name "$project" --output text --query 'build.id'
670
+ done
671
+ for pipeline in $(resources AWS::ImageBuilder::ImagePipeline); do
672
+ aws imagebuilder start-image-pipeline-execution --image-pipeline-arn "$pipeline" --output text --query 'imageBuildVersionArn'
673
+ done
674
+ ```
675
+
676
+ Make sure you use `failedImageBuildsTopic()` to get notified of any failed builds.
677
+
649
678
  ## Monitoring
650
679
 
651
- There are two important ways to monitor your runners:
680
+ There are three important ways to monitor your runners:
652
681
 
653
682
  1. Make sure runners don't fail to start. When that happens, jobs may sit and wait. Use `GitHubRunners.metricFailed()` to get a metric for the number of failed runner starts. You should use this metric to trigger an alarm.
654
- 2. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
683
+ 2. Make sure our management functions don't fail. When that happens, webhooks may be dropped and jobs may never get a runner. Use `GitHubRunners.metricLambdaErrors()` to get a metric for the number of failed invocations across all management Lambda functions. You should use this metric to trigger an alarm.
684
+ 3. Make sure runner images don't fail to build. Failed runner image builds mean you will get stuck with out-of-date software on your runners. It may lead to security vulnerabilities, or it may lead to slower runner start-ups as the runner software itself needs to be updated. Use `GitHubRunners.failedImageBuildsTopic()` to get SNS topic that gets notified of failed runner image builds. You should subscribe to this topic.
655
685
 
656
686
  Other useful metrics to track:
657
687
 
@@ -659,6 +689,10 @@ Other useful metrics to track:
659
689
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
660
690
  3. Use `GitHubRunners.metricStolenRunners()` to get a metric for number of runners detected as stolen by another job. Anything over zero can indicate a misconfiguration or GitHub webhook issues.
661
691
 
692
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
693
+ completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
694
+ recent errors from the logs.
695
+
662
696
  ## Known Issues
663
697
 
664
698
  1. Runner images built during a failed deployment are not rolled back. If your stack fails to deploy after an image was already built, the new image will stay in use. The image will be automatically replaced on the next build interval, but that might take up to 7 days with default settings (`rebuildInterval`). It's recommended to not leave stacks in `UPDATE_ROLLBACK_COMPLETE` state. Deploying again with the configuration you want will rebuild the images and get everything back in sync.
@@ -11,4 +11,4 @@ src/cloudsnorkel.cdk_github_runners.egg-info/top_level.txt
11
11
  src/cloudsnorkel/cdk_github_runners/__init__.py
12
12
  src/cloudsnorkel/cdk_github_runners/py.typed
13
13
  src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py
14
- src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.17.0.jsii.tgz
14
+ src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.0.jsii.tgz
@@ -1,4 +1,4 @@
1
1
  aws-cdk-lib<3.0.0,>=2.239.0
2
2
  constructs<11.0.0,>=10.5.1
3
- jsii<2.0.0,>=1.139.0
3
+ jsii<2.0.0,>=1.142.0
4
4
  publication>=0.0.3