@cloudsnorkel/cdk-github-runners 0.14.14 → 0.14.16

package/README.md

@@ -296,6 +296,155 @@ new GitHubRunners(this, 'runners', {
 });
 ```
 
+### Composite Providers
+
+Composite providers allow you to combine multiple runner providers with different strategies. There are two types:
+
+**Fallback Strategy**: Try providers in order until one succeeds. Useful for trying spot instances first, then falling back to on-demand if spot capacity is unavailable.
+
+```typescript
+// Try spot instances first, fall back to on-demand if spot is unavailable
+const ecsFallback = CompositeProvider.fallback(this, 'ECS Fallback', [
+  new EcsRunnerProvider(this, 'ECS Spot', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: true,
+    // ... other config
+  }),
+  new EcsRunnerProvider(this, 'ECS On-Demand', {
+    labels: ['ecs', 'linux', 'x64'],
+    spot: false,
+    // ... other config
+  }),
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [ecsFallback],
+});
+```
+
+**Weighted Distribution Strategy**: Randomly select a provider based on weights. Useful for distributing load across multiple availability zones or instance types.
+
+```typescript
+// Distribute 60% of traffic to AZ-1, 40% to AZ-2
+const distributedProvider = CompositeProvider.distribute(this, 'Fargate Distribution', [
+  {
+    weight: 3, // 3/(3+2) = 60%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-1', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[0]],
+      }),
+      // ... other config
+    }),
+  },
+  {
+    weight: 2, // 2/(3+2) = 40%
+    provider: new FargateRunnerProvider(this, 'Fargate AZ-2', {
+      labels: ['fargate', 'linux', 'x64'],
+      subnetSelection: vpc.selectSubnets({
+        availabilityZones: [vpc.availabilityZones[1]],
+      }),
+      // ... other config
+    }),
+  },
+]);
+
+new GitHubRunners(this, 'runners', {
+  providers: [distributedProvider],
+});
+```
+
+**Important**: All providers in a composite must have the exact same labels. This ensures any provisioned runner can match the labels requested by the GitHub workflow job.
+
+### Custom Provider Selection
+
+By default, providers are selected based on label matching: the first provider that has all the labels requested by the job is selected. You can customize this behavior using a provider selector Lambda function to:
+
+* Filter out certain jobs (prevent runner provisioning)
+* Dynamically select a provider based on job characteristics (repository, branch, time of day, etc.)
+* Customize labels for the runner (add, remove, or modify labels dynamically)
+
+The selector function receives the full GitHub webhook payload, a map of all available providers and their labels, and the default provider/labels that would have been selected. It returns the provider to use (or `undefined` to skip runner creation) and the labels to assign to the runner.
+
+**Example: Route jobs to different providers based on repository**
+
+```typescript
+import { ComputeType } from 'aws-cdk-lib/aws-codebuild';
+import { Function, Code, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { GitHubRunners, CodeBuildRunnerProvider } from '@cloudsnorkel/cdk-github-runners';
+
+const defaultProvider = new CodeBuildRunnerProvider(this, 'default', {
+  labels: ['custom-runner', 'default'],
+});
+const productionProvider = new CodeBuildRunnerProvider(this, 'production', {
+  labels: ['custom-runner', 'production'],
+  computeType: ComputeType.LARGE,
+});
+
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, providers, defaultProvider, defaultLabels } = event;
+      
+      // Route production repos to dedicated provider
+      if (payload.repository.name.includes('prod')) {
+        return {
+          provider: '${productionProvider.node.path}',
+          labels: ['custom-runner', 'production', 'modified-via-selector'],
+        };
+      }
+      
+      // Filter out draft PRs
+      if (payload.workflow_job.head_branch?.startsWith('draft/')) {
+        return { provider: undefined }; // Skip runner provisioning
+      }
+      
+      // Use default for everything else
+      return {
+        provider: defaultProvider,
+        labels: defaultLabels,
+      };
+    };
+  `),
+});
+
+new GitHubRunners(this, 'runners', {
+   providers: [defaultProvider, productionProvider],
+   providerSelector: providerSelector,
+});
+```
+
+**Example: Add dynamic labels based on job metadata**
+
+```typescript
+const providerSelector = new Function(this, 'provider-selector', {
+  runtime: Runtime.NODEJS_LATEST,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      const { payload, defaultProvider, defaultLabels } = event;
+      
+      // Add branch name as a label
+      const branch = payload.workflow_job.head_branch || 'unknown';
+      const labels = [...(defaultLabels || []), 'branch:' + branch];
+      
+      return {
+        provider: defaultProvider,
+        labels: labels,
+      };
+    };
+  `),
+});
+```
+
+**Important considerations:**
+
+* ⚠️ **Label matching responsibility**: You are responsible for ensuring the selected provider's labels match what the job requires. If labels don't match, the runner will be provisioned but GitHub Actions won't assign the job to it.
+* ⚠️ **No guarantee of assignment**: Provider selection only determines which provider will provision a runner. GitHub Actions may still route the job to any available runner with matching labels. For reliable provider assignment, consider repo-level runner registration (the default).
+* ⚡ **Performance**: The selector runs synchronously during webhook processing. Keep it fast and efficient—the webhook has a 30-second timeout total.
+
 ## Examples
 
 Beyond the code snippets above, the fullest example available is the [integration test](test/default.integ.ts).

package/SETUP_GITHUB.md

@@ -1,6 +1,102 @@
 # Setup GitHub
 
-Integration with GitHub can be done using an [app](#app-authentication) or [personal access token](#personal-access-token). Using an app allows more fine-grained access control. Using an app is easier with the setup wizard.
+## Overview of Options
+
+You will need to make several decisions during setup. Here's a quick guide to help you choose:
+
+### 1. Authentication Method
+
+**Choose between:**
+- **GitHub App** (recommended) - More fine-grained permissions, easier setup with wizard, better security
+- **Personal Access Token (PAT)** - Simpler but less flexible, requires manual webhook setup
+
+**When to use App:** Almost always. Use PAT only if you have specific constraints that prevent using an app.
+
+**When to use PAT:** If you need a quick setup and don't need fine-grained permissions, or if your organization has policies preventing app creation.
+
+> **⚠️ IT/DevOps Help May Be Required:** Installing a GitHub app on repositories or organizations may require repository administrator or organization owner permissions. You may need to coordinate with your IT/devops team to install the app on the desired repositories.
+
+### 2. GitHub Instance
+
+**Choose between:**
+- **GitHub.com** - Public GitHub
+- **GitHub Enterprise Server** - Self-hosted GitHub instance
+
+**When to use Enterprise Server:** If your organization uses a self-hosted GitHub Enterprise Server instance.
+
+> **⚠️ IT/DevOps Help Required:** Setting up with GitHub Enterprise Server requires coordination with your IT/devops team to obtain the correct domain and ensure network connectivity.
+
+### 3. App Scope (if using App)
+
+**Choose between:**
+- **User App** - For personal repositories
+- **Organization App** - For organization repositories
+
+**When to use User App:** If you only need to run workflows for your personal repositories.
+
+**When to use Organization App:** If you need to run workflows for repositories in an organization.
+
+> **⚠️ IT/DevOps Approval Required:** Creating an organization app may require organization owner or administrator permissions. You may need to request approval from your IT/devops team or organization administrators.
+
+### 4. Runner Registration Level
+
+**Choose between:**
+- **Repository-level** (recommended) - Runners registered to specific repositories
+- **Organization-level** - Runners registered to the entire organization
+
+> **Note:** This determines where on-demand runners will be registered dynamically each time they are provisioned. This is independent of where the GitHub app is installed. Organization-level registration makes runners available to **all repositories in the organization**, regardless of app installation.
+
+**When to use Repository-level:**
+- You want better isolation between repositories
+- You want to reduce the risk of jobs being accidentally assigned to the wrong runners
+- You're okay with requiring the `administration` permission
+
+**When to use Organization-level:**
+- You need to minimize permissions (only requires `organization_self_hosted_runners`)
+- You fully trust all repositories in your organization
+- You want all repositories to share the same pool of runners
+
+> **⚠️ IT/DevOps Approval May Be Required:** Organization-level registration affects all repositories in the organization. Your organization may have policies requiring approval before enabling organization-wide runner registration.
+
+#### Registration Level Recommendation
+
+This determines where on-demand runners will be registered dynamically each time they are provisioned. This is independent of where the GitHub app is installed.
+
+Repository-level registration is recommended over organization-level registration for better control and security:
+
+* **Reduced risk of accidental job assignment**: Runners are dynamically registered to the repository matching the job that triggered them. This ensures jobs are only assigned to runners intended for that specific repository, reducing the risk of accidental assignment when using multiple runner configurations.
+* **Better isolation**: Each repository only sees runners that are explicitly registered to it, providing better isolation between different projects or teams.
+* **Trade-off**: Repository-level registration requires the `administration` permission, which is broader than the `organization_self_hosted_runners` permission required for organization-level registration. If you need to minimize permissions and fully trust all repositories in your organization, organization-level registration may be acceptable.
+
+Organization-level registration registers runners to the entire organization, making them available to **all repositories in the organization**, regardless of whether the app is installed on those repositories. This can lead to jobs being routed to runners that weren't intended for them. Runners may be assigned jobs from repositories where this app isn't even installed.
+
+### 5. Setup Method
+
+**Choose between:**
+- **Setup Wizard** (recommended) - Interactive web interface, guides you through the process
+- **Manual Setup** - Step-by-step instructions, more control over each step
+
+**When to use Setup Wizard:** If you prefer a guided, interactive experience.
+
+**When to use Manual Setup:** If you need more control, want to understand each step in detail, or the wizard isn't available.
+
+### 6. Webhook Scope (if using PAT)
+
+**Choose between:**
+- **Organization/Enterprise webhook** - Single webhook for all repositories
+- **Repository-level webhooks** - One webhook per repository
+
+**When to use Organization/Enterprise webhook:** If you want to manage a single webhook for multiple repositories.
+
+**When to use Repository-level webhooks:** If you only need runners for a few specific repositories.
+
+> **⚠️ IT/DevOps Approval Required:** Creating organization or enterprise-level webhooks requires organization owner or enterprise administrator permissions. Repository-level webhooks only require repository admin permissions.
+
+---
+
+## Setup GitHub
+
+Integration with GitHub can be done using an [app](#app-authentication) or [personal access token](#personal-access-token-authentication). Using an app allows more fine-grained access control. Using an app is easier with the setup wizard.
 
 ## App Authentication
 
@@ -49,7 +145,7 @@ Integration with GitHub can be done using an [app](#app-authentication) or [pers
     1. Open the downloaded private key with any text editor
     2. Copy the text from the private key as-is into the secret
 
-## Personal Access Token
+## Personal Access Token Authentication
 
 ### Create Token
 
@@ -79,7 +175,7 @@ Integration with GitHub can be done using an [app](#app-authentication) or [pers
 
 1. For organizations go to https://github.com/organizations/MY_ORG/settings/hooks after replacing `MY_ORG` with your GitHub organization name
 2. For enterprise go to https://github.com/enterprises/MY_ENTERPRISE/settings/hooks after replacing `MY_ENTERPRISE` with your GitHub enterprise name
-3. Otherwise, you can create one per repository in your repository settings under Webhooks
+3. Otherwise, you can create one webhook per repository in your repository settings under Webhooks
 4. Configure the webhook:
     1. For Webhook URL use the value of `github.webhook.url` from `status.json`
     2. Open the URL in `github.webhook.secretUrl` from `status.json`, retrieve the secret value, and use it for webhook secret