cloudsnorkel.cdk-github-runners 0.18.1__tar.gz → 0.18.2__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.18.1/src/cloudsnorkel.cdk_github_runners.egg-info → cloudsnorkel_cdk_github_runners-0.18.2}/PKG-INFO +6 -4
  2. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/README.md +5 -3
  3. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.py +2 -2
  4. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/__init__.py +80 -18
  5. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/_jsii/__init__.py +2 -2
  6. cloudsnorkel_cdk_github_runners-0.18.2/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz +0 -0
  7. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2/src/cloudsnorkel.cdk_github_runners.egg-info}/PKG-INFO +6 -4
  8. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/SOURCES.txt +1 -1
  9. cloudsnorkel_cdk_github_runners-0.18.1/src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.1.jsii.tgz +0 -0
  10. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/LICENSE +0 -0
  11. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/MANIFEST.in +0 -0
  12. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/pyproject.toml +0 -0
  13. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/setup.cfg +0 -0
  14. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel/cdk_github_runners/py.typed +0 -0
  15. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/dependency_links.txt +0 -0
  16. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/src/cloudsnorkel.cdk_github_runners.egg-info/requires.txt +0 -0
  17. {cloudsnorkel_cdk_github_runners-0.18.1 → cloudsnorkel_cdk_github_runners-0.18.2}/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.18.1
3
+ Version: 0.18.2
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>
@@ -660,6 +660,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
660
660
  2. If you see too many errors, make sure you're only sending `workflow_job` events
661
661
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
662
662
  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
663
+ 7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
663
664
 
664
665
  All logs are saved in CloudWatch.
665
666
 
@@ -708,10 +709,11 @@ Other useful metrics to track:
708
709
  1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
709
710
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
710
711
  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.
712
+ 4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
711
713
 
712
- Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
713
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
714
- recent errors from the logs.
714
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
715
+ into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
716
+ mean and which ones to alarm on.
715
717
 
716
718
  ## Known Issues
717
719
 
@@ -632,6 +632,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
632
632
  2. If you see too many errors, make sure you're only sending `workflow_job` events
633
633
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
634
634
  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
635
+ 7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
635
636
 
636
637
  All logs are saved in CloudWatch.
637
638
 
@@ -680,10 +681,11 @@ Other useful metrics to track:
680
681
  1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
681
682
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
682
683
  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.
684
+ 4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
683
685
 
684
- Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
685
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
686
- recent errors from the logs.
686
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
687
+ into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
688
+ mean and which ones to alarm on.
687
689
 
688
690
  ## Known Issues
689
691
 
@@ -5,7 +5,7 @@ kwargs = json.loads(
5
5
  """
6
6
  {
7
7
  "name": "cloudsnorkel.cdk-github-runners",
8
- "version": "0.18.1",
8
+ "version": "0.18.2",
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.18.1.jsii.tgz"
29
+ "cdk-github-runners@0.18.2.jsii.tgz"
30
30
  ],
31
31
  "cloudsnorkel.cdk_github_runners": [
32
32
  "py.typed"
@@ -633,6 +633,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
633
633
  2. If you see too many errors, make sure you're only sending `workflow_job` events
634
634
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
635
635
  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
636
+ 7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
636
637
 
637
638
  All logs are saved in CloudWatch.
638
639
 
@@ -681,10 +682,11 @@ Other useful metrics to track:
681
682
  1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
682
683
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
683
684
  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.
685
+ 4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
684
686
 
685
- Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
686
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
687
- recent errors from the logs.
687
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
688
+ into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
689
+ mean and which ones to alarm on.
688
690
 
689
691
  ## Known Issues
690
692
 
@@ -2796,7 +2798,7 @@ class GitHubRunners(
2796
2798
  :param idle_timeout: (experimental) Time to wait before stopping a runner that remains idle. If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources. Default: 5 minutes
2797
2799
  :param log_options: (experimental) Logging options for the state machine that manages the runners. Default: no logs
2798
2800
  :param providers: (experimental) List of runner providers to use. At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job. Default: CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
2799
- :param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
2801
+ :param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider in the selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
2800
2802
  :param require_self_hosted_label: (experimental) Whether to require the ``self-hosted`` label. If ``true``, the runner will only start if the workflow job explicitly requests the ``self-hosted`` label. Be careful when setting this to ``false``. Avoid setting up providers with generic label requirements like ``linux`` as they may match workflows that are not meant to run on self-hosted runners. Default: true
2801
2803
  :param retry_options: (experimental) Options to retry operation in case of failure like missing capacity, or API quota issues. GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours. Retries use full jitter, so total time spent waiting is about half the sum of min(interval * backoffRate ^ attempt, maxDelay) over all attempts. Default: retry 210 times over a bit more than 24 hours
2802
2804
  :param security_group: (deprecated) Security group attached to all management functions. Use this with to provide access 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.
@@ -2840,20 +2842,16 @@ class GitHubRunners(
2840
2842
  ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Dashboard":
2841
2843
  '''(experimental) Creates a CloudWatch dashboard with the metrics you need to know if your runners are healthy.
2842
2844
 
2843
- It answers the questions you're most likely to ask:
2845
+ It's split into sections, each with a short explanation of what its numbers mean and which ones to watch:
2844
2846
 
2845
- - Are jobs running and passing? See "Jobs completed by status".
2846
- - Which runner is broken? See "Failed jobs by runner label".
2847
- - Are jobs stuck because runners fail to start? See "Runner executions".
2848
- - Why were runners stopped before getting a job? See "Stopped runners by reason".
2849
- - Why are runners failing to start? See "Recent failed attempts".
2850
- - How long do runners take (and therefore cost)? See "Runner time".
2851
- - Is GitHub reaching the webhook at all? See "Webhook".
2852
- - Is any of our code failing? See "Lambda errors".
2853
- - What exactly went wrong? See "Recent errors".
2847
+ - **Jobs**: are jobs running and passing, and which runner is failing them?
2848
+ - **Runners**: do runners start, how long do they take (and therefore cost), and why do they fail to start?
2849
+ - **Runner assignment**: are runners taken by jobs they weren't started for, do jobs match more than one provider, and why
2850
+ were runners stopped before getting a job?
2851
+ - **Management functions (orchestration)**: is GitHub reaching the webhook, and is any of our code failing?
2854
2852
 
2855
- **WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners} and {@link metricStoppedRunners} which create metric filters.
2856
- These resources may incur cost.
2853
+ **WARNING:** this method calls {@link metricJobCompleted}, {@link metricStolenRunners}, {@link metricStoppedRunners} and
2854
+ {@link metricJobsMatchingMultipleProviders} which create metric filters. These resources may incur cost.
2857
2855
 
2858
2856
  This dashboard is very basic. Pull requests and issues are welcome to improve it.
2859
2857
 
@@ -2877,6 +2875,7 @@ class GitHubRunners(
2877
2875
  - "Ignored webhook" helps understand why runners aren't started
2878
2876
  - "Ignored jobs based on labels" helps debug label matching issues
2879
2877
  - "Webhook started runners" helps understand which runners were started
2878
+ - "Jobs matching multiple providers" lists jobs that need more labels so they match only one provider
2880
2879
  - "Warm runner status" and "Warm runner errors" (when warm runners are configured)
2881
2880
 
2882
2881
  :param prefix: Prefix for the query definitions. Defaults to "GitHub Runners".
@@ -2899,6 +2898,9 @@ class GitHubRunners(
2899
2898
 
2900
2899
  If you want to be sure you are using the latest runner version, you can use this topic to be notified when a build fails.
2901
2900
 
2901
+ Email subscribers get a short summary with the failure reason and a link to the logs. Other subscribers get the original
2902
+ JSON notification from CodeBuild or EC2 Image Builder.
2903
+
2902
2904
  When the image builder is defined in a separate stack (e.g. in a split-stacks setup), pass that stack or construct
2903
2905
  as the optional scope so the topic and failure-notification aspects are created in the same stack as the image
2904
2906
  builder. Otherwise the aspects may not find the image builder resources.
@@ -3020,6 +3022,66 @@ class GitHubRunners(
3020
3022
 
3021
3023
  return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricJobCompleted", [props]))
3022
3024
 
3025
+ @jsii.member(jsii_name="metricJobsMatchingMultipleProviders")
3026
+ def metric_jobs_matching_multiple_providers(
3027
+ self,
3028
+ *,
3029
+ account: typing.Optional[builtins.str] = None,
3030
+ color: typing.Optional[builtins.str] = None,
3031
+ dimensions_map: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None,
3032
+ id: typing.Optional[builtins.str] = None,
3033
+ label: typing.Optional[builtins.str] = None,
3034
+ period: typing.Optional["_aws_cdk_ceddda9d.Duration"] = None,
3035
+ region: typing.Optional[builtins.str] = None,
3036
+ stack_account: typing.Optional[builtins.str] = None,
3037
+ stack_region: typing.Optional[builtins.str] = None,
3038
+ statistic: typing.Optional[builtins.str] = None,
3039
+ unit: typing.Optional["_aws_cdk_aws_cloudwatch_ceddda9d.Unit"] = None,
3040
+ visible: typing.Optional[builtins.bool] = None,
3041
+ ) -> "_aws_cdk_aws_cloudwatch_ceddda9d.Metric":
3042
+ '''(experimental) Metric for the number of jobs whose labels matched more than one provider.
3043
+
3044
+ We start a runner from the first matching provider, but GitHub may give such a job a runner from any of them, including one started for
3045
+ another job. Stolen runner detection starts another runner for the job left behind, but the job itself may run on a provider you didn't
3046
+ expect. Anything over zero means some workflows ask for too few labels. Add labels to those jobs so they match only one provider. Use the
3047
+ "Jobs matching multiple providers" CloudWatch Logs Insights query created by {@link createLogsInsightsQueries} to find them.
3048
+
3049
+ Jobs routed by a provider selector are not counted, as the selector picks the provider.
3050
+
3051
+ **WARNING:** this method creates a metric filter. This resource may incur cost.
3052
+
3053
+ :param account: Account which this metric comes from. Default: - Deployment account.
3054
+ :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
3055
+ :param dimensions_map: Dimensions of the metric. Default: - No dimensions.
3056
+ :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
3057
+ :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
3058
+ :param period: The period over which the specified statistic is applied. Default: Duration.minutes(5)
3059
+ :param region: Region which this metric comes from. Default: - Deployment region.
3060
+ :param stack_account: Account of the stack this metric is attached to. Default: - Deployment account.
3061
+ :param stack_region: Region of the stack this metric is attached to. Default: - Deployment region.
3062
+ :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
3063
+ :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
3064
+ :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
3065
+
3066
+ :stability: experimental
3067
+ '''
3068
+ props = _aws_cdk_aws_cloudwatch_ceddda9d.MetricOptions(
3069
+ account=account,
3070
+ color=color,
3071
+ dimensions_map=dimensions_map,
3072
+ id=id,
3073
+ label=label,
3074
+ period=period,
3075
+ region=region,
3076
+ stack_account=stack_account,
3077
+ stack_region=stack_region,
3078
+ statistic=statistic,
3079
+ unit=unit,
3080
+ visible=visible,
3081
+ )
3082
+
3083
+ return typing.cast("_aws_cdk_aws_cloudwatch_ceddda9d.Metric", jsii.invoke(self, "metricJobsMatchingMultipleProviders", [props]))
3084
+
3023
3085
  @jsii.member(jsii_name="metricLambdaErrors")
3024
3086
  def metric_lambda_errors(
3025
3087
  self,
@@ -3384,7 +3446,7 @@ class GitHubRunnersProps:
3384
3446
  :param idle_timeout: (experimental) Time to wait before stopping a runner that remains idle. If the user cancelled the job, or if another runner stole it, this stops the runner to avoid wasting resources. Default: 5 minutes
3385
3447
  :param log_options: (experimental) Logging options for the state machine that manages the runners. Default: no logs
3386
3448
  :param providers: (experimental) List of runner providers to use. At least one provider is required. Provider will be selected when its label matches the labels requested by the workflow job. Default: CodeBuild, Lambda and Fargate runners with all the defaults (no VPC or default account VPC)
3387
- :param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
3449
+ :param provider_selector: (experimental) Optional Lambda function to customize provider selection logic and label assignment. - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput } - The function returns a selected provider and its labels as {@link ProviderSelectorResult } - You can decline to provision a runner by returning undefined as the provider in the selector result - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.) - Labels don't have to match the labels originally configured for the provider, but see warnings below - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total) **WARNING: It is your responsibility to ensure the selected provider's labels match the job's required labels. If you return the wrong labels, the runner will be created but GitHub Actions will not assign the job to it.** **WARNING: Provider selection is not a guarantee that a specific provider will be assigned for the job. GitHub Actions may assign the job to any runner with matching labels. The provider selector only determines which provider's runner will be *created*, but GitHub Actions may route the job to any available runner with the required labels.** **For reliable provider assignment based on job characteristics, consider using repo-level runner registration where you can control which runners are available for specific repositories. This information is also available while using the setup wizard.
3388
3450
  :param require_self_hosted_label: (experimental) Whether to require the ``self-hosted`` label. If ``true``, the runner will only start if the workflow job explicitly requests the ``self-hosted`` label. Be careful when setting this to ``false``. Avoid setting up providers with generic label requirements like ``linux`` as they may match workflows that are not meant to run on self-hosted runners. Default: true
3389
3451
  :param retry_options: (experimental) Options to retry operation in case of failure like missing capacity, or API quota issues. GitHub jobs time out after not being able to get a runner for 24 hours. You should not retry for more than 24 hours. Retries use full jitter, so total time spent waiting is about half the sum of min(interval * backoffRate ^ attempt, maxDelay) over all attempts. Default: retry 210 times over a bit more than 24 hours
3390
3452
  :param security_group: (deprecated) Security group attached to all management functions. Use this with to provide access 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.
@@ -3542,7 +3604,7 @@ class GitHubRunnersProps:
3542
3604
 
3543
3605
  - The function receives the webhook payload along with default provider and its labels as {@link ProviderSelectorInput }
3544
3606
  - The function returns a selected provider and its labels as {@link ProviderSelectorResult }
3545
- - You can decline to provision a runner by returning undefined as the provider selector result
3607
+ - You can decline to provision a runner by returning undefined as the provider in the selector result
3546
3608
  - You can fully customize the labels for the about-to-be-provisioned runner (add, remove, modify, dynamic labels, etc.)
3547
3609
  - Labels don't have to match the labels originally configured for the provider, but see warnings below
3548
3610
  - This function will be called synchronously during webhook processing, so it should be fast and efficient (webhook limit is 30 seconds total)
@@ -19,9 +19,9 @@ import constructs._jsii
19
19
 
20
20
  __jsii_assembly__ = jsii.JSIIAssembly.load(
21
21
  "@cloudsnorkel/cdk-github-runners",
22
- "0.18.1",
22
+ "0.18.2",
23
23
  __name__[0:-6],
24
- "cdk-github-runners@0.18.1.jsii.tgz",
24
+ "cdk-github-runners@0.18.2.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.18.1
3
+ Version: 0.18.2
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>
@@ -660,6 +660,7 @@ Configuration problems that we can detect up-front fail the orchestrator with a
660
660
  2. If you see too many errors, make sure you're only sending `workflow_job` events
661
661
  5. When using GitHub app, make sure there are active installations in `github.auth.app.installations`
662
662
  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
663
+ 7. If organization-level runners never pick up jobs from public repositories, check the runner group settings. By default, only private repositories can use runners in a runner group. You can allow public repositories in the [runner group repository access settings](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group), but make sure you understand the [security risks](#job-isolation) first
663
664
 
664
665
  All logs are saved in CloudWatch.
665
666
 
@@ -708,10 +709,11 @@ Other useful metrics to track:
708
709
  1. Use `GitHubRunners.metricJobCompleted()` to get a metric for the number of completed jobs broken down by labels and job success.
709
710
  2. Use `GitHubRunners.metricTime()` to get a metric for the total time a runner is running. This includes the overhead of starting the runner.
710
711
  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.
712
+ 4. Use `GitHubRunners.metricJobsMatchingMultipleProviders()` to get a metric for the number of jobs whose labels matched more than one provider and may run on any of them. Anything over zero means some workflows should ask for more labels.
711
713
 
712
- Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It shows
713
- completed jobs by status, failed jobs by runner label, runners that failed to start, runner time, webhook activity, and
714
- recent errors from the logs.
714
+ Use `GitHubRunners.createDashboard()` to get a CloudWatch dashboard with all of these metrics in one place. It's split
715
+ into sections for jobs, runners, runner assignment and management functions. Each section explains what its numbers
716
+ mean and which ones to alarm on.
715
717
 
716
718
  ## Known Issues
717
719
 
@@ -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.18.1.jsii.tgz
14
+ src/cloudsnorkel/cdk_github_runners/_jsii/cdk-github-runners@0.18.2.jsii.tgz