switchroom 0.5.0

package/skills/buildkite-agent-infrastructure/references/pipeline-templates.md

@@ -0,0 +1,73 @@
+# Pipeline Templates
+
+Pipeline templates (Enterprise-only) standardize pipeline YAML across the organization. Templates define a base configuration that pipelines inherit, ensuring consistency for security, compliance, or organizational standards.
+
+## Create a template
+
+```graphql
+mutation {
+  pipelineTemplateCreate(input: {
+    organizationId: "org-id"
+    name: "Standard CI Template"
+    description: "Organization-standard CI pipeline with security scanning and artifact signing"
+    available: true
+    configuration: """
+steps:
+  - label: ":pipeline: Upload"
+    command: buildkite-agent pipeline upload
+
+  - wait
+
+  - label: ":shield: Security Scan"
+    command: "scripts/security-scan.sh"
+    agents:
+      queue: "security-scanners"
+
+  - wait
+
+  - label: ":rocket: Deploy"
+    command: "scripts/deploy.sh"
+    branches: "main"
+    concurrency: 1
+    concurrency_group: "deploy/production"
+"""
+  }) {
+    pipelineTemplate {
+      id
+      uuid
+      name
+      available
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `organizationId` | Yes | Organization GraphQL ID |
+| `name` | Yes | Template name |
+| `description` | No | What this template provides |
+| `configuration` | Yes | Pipeline YAML string |
+| `available` | No | Whether teams can select this template (default: `false`) |
+
+## Update a template
+
+```graphql
+mutation {
+  pipelineTemplateUpdate(input: {
+    id: "template-id"
+    name: "Standard CI Template v2"
+    configuration: "..."
+    available: true
+  }) {
+    pipelineTemplate { id name }
+  }
+}
+```
+
+## Template strategy
+
+- Create a small number of templates (3-5) covering common patterns: basic CI, CI + deploy, CI + security scan + deploy
+- Set `available: true` only for templates ready for teams to adopt
+- Templates use standard pipeline YAML — test the YAML as a regular pipeline before promoting to a template
+- Assign templates to pipelines via the Buildkite UI or API

package/skills/buildkite-agent-infrastructure/references/self-hosted-agents.md

@@ -0,0 +1,137 @@
+# Self-Hosted Agent Configuration and Lifecycle Hooks
+
+## Self-Hosted Agent Configuration
+
+Self-hosted agents run on your own infrastructure and connect to Buildkite using an agent token. Configure them via `buildkite-agent.cfg` or environment variables.
+
+### Key configuration settings
+
+```ini
+# /etc/buildkite-agent/buildkite-agent.cfg
+
+# Authentication
+token="your-agent-token"
+
+# Agent identity
+name="backend-agent-%hostname-%n"
+tags="queue=linux-large,team=backend,os=linux"
+priority=1
+
+# Job execution
+build-path="/var/lib/buildkite-agent/builds"
+hooks-path="/etc/buildkite-agent/hooks"
+plugins-path="/etc/buildkite-agent/plugins"
+
+# Concurrency
+spawn=4
+
+# Security
+no-command-eval=true
+no-local-hooks=false
+no-plugins=false
+allowed-repositories="git@github.com:my-org/*"
+
+# Lifecycle
+disconnect-after-job=true
+cancel-grace-period=30
+
+# Experiments
+experiment="normalised-upload-paths,resolve-commit-after-checkout"
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `token` | — | Agent registration token (required) |
+| `name` | `%hostname-%n` | Agent name template (`%hostname`, `%n` for spawn index) |
+| `tags` | — | Comma-separated `key=value` pairs for routing |
+| `priority` | `0` | Higher priority agents pick up jobs first |
+| `spawn` | `1` | Number of parallel agents to run |
+| `build-path` | varies | Directory where builds execute |
+| `hooks-path` | varies | Path to agent-level hook scripts |
+| `disconnect-after-job` | `false` | Disconnect after each job (for ephemeral/autoscaled agents) |
+| `cancel-grace-period` | `10` | Seconds to wait for graceful shutdown |
+| `no-command-eval` | `false` | Restrict to script-only execution (security hardening) |
+| `allowed-repositories` | — | Glob patterns for repos this agent can build |
+
+### Clustered vs. unclustered agents
+
+**Clustered agents** belong to a cluster and target a single queue:
+
+```ini
+token="cluster-agent-token"
+tags="queue=linux-large"
+```
+
+Clustered agents use a cluster-scoped token and can only have one `queue` tag.
+
+**Unclustered agents** use an organization-level token and can have multiple tags:
+
+```ini
+token="org-agent-token"
+tags="queue=default,os=linux,size=large"
+```
+
+Prefer clustered agents for new deployments. Clusters provide secret scoping, queue isolation, and better organizational control.
+
+## Agent Lifecycle Hooks
+
+Hooks are shell scripts that execute at specific points during the agent and job lifecycle. Use them for secret injection, environment setup, security validation, and cleanup.
+
+### Hook execution order (per job)
+
+```
+environment        → Set environment variables for the job
+pre-checkout       → Runs before git checkout
+checkout           → The git checkout itself (override to customize)
+post-checkout      → Runs after git checkout (e.g., submodule init)
+pre-command        → Runs before the step command (secret injection, validation)
+command            → The step command itself (override to customize execution)
+post-command       → Runs after the step command (cleanup, notifications)
+pre-exit           → Runs before the agent exits the job (final cleanup)
+pre-artifact       → Runs before artifact upload
+```
+
+### Hook scopes
+
+| Scope | Location | Applies to |
+|-------|----------|------------|
+| Agent-level | `hooks-path` in `buildkite-agent.cfg` | All jobs on this agent |
+| Repository-level | `.buildkite/hooks/` in the repo | Jobs from this repo only |
+| Plugin-level | Inside the plugin directory | Jobs using the plugin |
+
+Agent-level hooks run first, then repository hooks, then plugin hooks.
+
+### Environment hook — secret injection
+
+The `environment` hook is the most common agent-level hook. Use it to inject secrets from external providers:
+
+```bash
+#!/bin/bash
+# /etc/buildkite-agent/hooks/environment
+
+set -euo pipefail
+
+# Inject secrets from AWS Secrets Manager
+if [[ "${BUILDKITE_PIPELINE_SLUG}" == "deploy-"* ]]; then
+  export AWS_ACCESS_KEY_ID=$(aws secretsmanager get-secret-value \
+    --secret-id "buildkite/deploy/aws-key" --query SecretString --output text)
+fi
+```
+
+### Environment hook — security validation
+
+Lock down which repositories, commands, and plugins agents execute:
+
+```bash
+#!/bin/bash
+# /etc/buildkite-agent/hooks/environment
+
+set -euo pipefail
+
+# Restrict to allowed repositories
+ALLOWED_REPOS="^git@github\.com:my-org/"
+if [[ ! "${BUILDKITE_REPO}" =~ ${ALLOWED_REPOS} ]]; then
+  echo "Unauthorized repository: ${BUILDKITE_REPO}"
+  exit 1
+fi
+```

package/skills/buildkite-agent-infrastructure/references/sso-saml.md

@@ -0,0 +1,92 @@
+# SSO/SAML Configuration
+
+Configure SSO to centralize authentication for the organization. Buildkite supports SAML 2.0 providers (Okta, Azure AD, Google Workspace, OneLogin, etc.).
+
+## Set up a SAML provider
+
+**Step 1 — Create the provider:**
+
+```graphql
+mutation {
+  ssoProviderCreate(input: {
+    organizationId: "org-id"
+    type: SAML
+    emailDomain: "example.com"
+    emailDomainVerificationAddress: "admin@example.com"
+  }) {
+    ssoProvider {
+      id
+      state
+      serviceProvider {
+        metadata { url }
+        ssoURL     # ACS URL — configure in IdP
+        issuer     # Entity ID — configure in IdP
+      }
+    }
+  }
+}
+```
+
+**Step 2 — Configure the IdP** with the returned `ssoURL` (ACS URL) and `issuer` (Entity ID).
+
+**Step 3 — Update with IdP metadata:**
+
+```graphql
+# Option A: Metadata URL (preferred — auto-updates)
+mutation {
+  ssoProviderUpdate(input: {
+    id: "sso-provider-id"
+    identityProvider: {
+      metadata: { url: "https://idp.example.com/saml/metadata" }
+    }
+  }) {
+    ssoProvider { id state }
+  }
+}
+
+# Option B: Manual configuration
+mutation {
+  ssoProviderUpdate(input: {
+    id: "sso-provider-id"
+    identityProvider: {
+      ssoURL: "https://idp.example.com/saml/sso"
+      issuer: "https://idp.example.com"
+      certificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
+    }
+  }) {
+    ssoProvider { id state }
+  }
+}
+```
+
+**Step 4 — Verify the email domain** (Buildkite sends a verification email to the address specified).
+
+**Step 5 — Enable the provider** once verification completes and IdP is configured.
+
+## Query SSO providers
+
+```graphql
+query {
+  organization(slug: "my-org") {
+    ssoProviders(first: 10) {
+      edges {
+        node {
+          id
+          type
+          state
+          emailDomain
+          enabledAt
+          ... on SSOProviderSAML {
+            identityProvider { ssoURL issuer certificate metadata { url xml } }
+          }
+          ... on SSOProviderGoogleGSuite {
+            googleHostedDomain
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Provider states: `PENDING` (created, awaiting config), `DISABLED` (configured but off), `ENABLED` (active).