switchroom 0.13.2 → 0.13.4

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

@@ -1,73 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-# 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

@@ -1,92 +0,0 @@
-# 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).