--- name: linear-multi-env-setup-dd8b48045f3e description: | Configure Linear across development, staging, and production environments. Use when setting up per-environment API keys, secret management, or environment-specific Linear configurations. Trigger: "linear environments", "linear staging", "linear dev prod", "linear environment setup", "multi-environment linear". allowed-tools: Read, Write, Edit, Bash(vault:*), Bash(gcloud:*), Bash(aws:*) version: 1.0.0 license: MIT author: Jeremy Longshore compatible-with: claude-code, codex, openclaw tags: [saas, linear, deployment, api] --- # Linear Multi-Environment Setup ## Overview Configure Linear integrations across dev, staging, and production with isolated API keys, secret management, environment guards, and per-environment webhook routing. Use separate Linear workspaces or at minimum separate API keys per environment. ## Prerequisites - Separate Linear API keys per environment (dev, staging, prod) - Secret management (Vault, AWS Secrets Manager, GCP Secret Manager) - CI/CD pipeline with environment support - Node.js 18+ ## Instructions ### Step 1: Environment Configuration ```typescript // src/config/linear.ts import { LinearClient } from "@linear/sdk"; interface LinearEnvConfig { apiKey: string; webhookSecret: string; defaultTeamKey: string; enableWebhooks: boolean; enableDebugLogging: boolean; cacheEnabled: boolean; } type Environment = "development" | "staging" | "production" | "test"; function getEnvironment(): Environment { const env = process.env.NODE_ENV ?? "development"; if (!["development", "staging", "production", "test"].includes(env)) { throw new Error(`Unknown NODE_ENV: ${env}`); } return env as Environment; } async function loadConfig(): Promise { const env = getEnvironment(); // In production, use secret manager instead of env vars if (env === "production" || env === "staging") { return { apiKey: await getSecret(`linear-api-key-${env}`), webhookSecret: await getSecret(`linear-webhook-secret-${env}`), defaultTeamKey: process.env.LINEAR_DEFAULT_TEAM_KEY ?? "ENG", enableWebhooks: true, enableDebugLogging: env === "staging", cacheEnabled: true, }; } // Dev/test: use environment variables return { apiKey: process.env.LINEAR_API_KEY ?? "", webhookSecret: process.env.LINEAR_WEBHOOK_SECRET ?? "", defaultTeamKey: process.env.LINEAR_DEV_TEAM_KEY ?? "DEV", enableWebhooks: false, // No webhook server in local dev enableDebugLogging: true, cacheEnabled: false, }; } ``` ### Step 2: Secret Manager Integration ```typescript // GCP Secret Manager import { SecretManagerServiceClient } from "@google-cloud/secret-manager"; async function getSecret(name: string): Promise { const client = new SecretManagerServiceClient(); const projectId = process.env.GCP_PROJECT_ID!; const [version] = await client.accessSecretVersion({ name: `projects/${projectId}/secrets/${name}/versions/latest`, }); return version.payload?.data?.toString() ?? ""; } // AWS Secrets Manager import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager"; async function getSecretAWS(name: string): Promise { const client = new SecretsManagerClient({}); const result = await client.send(new GetSecretValueCommand({ SecretId: name })); return result.SecretString ?? ""; } // HashiCorp Vault async function getSecretVault(path: string): Promise { const response = await fetch(`${process.env.VAULT_ADDR}/v1/${path}`, { headers: { "X-Vault-Token": process.env.VAULT_TOKEN! }, }); const data = await response.json(); return data.data.data.value; } ``` ### Step 3: Environment-Aware Client Factory ```typescript let _client: LinearClient | null = null; let _config: LinearEnvConfig | null = null; export async function getLinearClient(): Promise { if (!_client) { _config = await loadConfig(); if (!_config.apiKey) { throw new Error(`LINEAR_API_KEY not configured for ${getEnvironment()}`); } _client = new LinearClient({ apiKey: _config.apiKey }); } return _client; } export async function getConfig(): Promise { if (!_config) await getLinearClient(); // Triggers config load return _config!; } // For tests: inject a mock or test client export function setTestClient(client: LinearClient) { _client = client; } ``` ### Step 4: Environment Guards Prevent dangerous operations from running in the wrong environment. ```typescript function requireProduction(operation: string) { if (getEnvironment() !== "production") { throw new Error(`${operation} is production-only (current: ${getEnvironment()})`); } } function preventProduction(operation: string) { if (getEnvironment() === "production") { throw new Error(`${operation} is forbidden in production`); } } // Usage async function deleteAllTestIssues(teamKey: string) { preventProduction("deleteAllTestIssues"); // Safety guard const client = await getLinearClient(); const issues = await client.issues({ filter: { team: { key: { eq: teamKey } }, title: { startsWith: "[TEST]" }, }, }); for (const issue of issues.nodes) { await issue.delete(); } } // Safe delete: archives in prod, deletes in dev async function safeRemoveIssue(issueId: string) { const client = await getLinearClient(); if (getEnvironment() === "production") { await client.archiveIssue(issueId); } else { await client.deleteIssue(issueId); } } ``` ### Step 5: Per-Environment Webhooks ```typescript // Different webhook configs per environment const webhookConfigs: Record = { development: { resourceTypes: [], // No webhooks in dev — use polling/ngrok manually enabled: false, }, staging: { resourceTypes: ["Issue", "Comment", "Project", "Cycle"], enabled: true, }, production: { resourceTypes: ["Issue", "Comment", "Project", "Cycle", "IssueLabel", "ProjectUpdate"], enabled: true, }, test: { resourceTypes: [], enabled: false, }, }; ``` ### Step 6: CI/CD with Environment Secrets ```yaml # .github/workflows/deploy.yml name: Deploy on: push: branches: [main, release/*] jobs: deploy-staging: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest environment: staging steps: - uses: actions/checkout@v4 - run: npm ci && npm run build - run: npm run deploy:staging env: LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }} LINEAR_WEBHOOK_SECRET: ${{ secrets.LINEAR_WEBHOOK_SECRET }} deploy-production: if: startsWith(github.ref, 'refs/heads/release/') runs-on: ubuntu-latest environment: production steps: - uses: actions/checkout@v4 - run: npm ci && npm run build - run: npm run deploy:production env: LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }} LINEAR_WEBHOOK_SECRET: ${{ secrets.LINEAR_WEBHOOK_SECRET }} ``` ### Step 7: Environment Validation Script ```typescript // scripts/validate-environment.ts async function validateEnvironment() { const env = getEnvironment(); console.log(`Validating Linear config for: ${env}\n`); const config = await loadConfig(); const checks = [ { name: "API Key", ok: config.apiKey.startsWith("lin_api_") }, { name: "Webhook Secret", ok: !config.enableWebhooks || config.webhookSecret.length > 10 }, { name: "Default Team", ok: config.defaultTeamKey.length > 0 }, ]; // Test API connectivity try { const client = new LinearClient({ apiKey: config.apiKey }); const viewer = await client.viewer; const teams = await client.teams(); const team = teams.nodes.find(t => t.key === config.defaultTeamKey); checks.push({ name: "API Auth", ok: true }); checks.push({ name: "Default Team Exists", ok: !!team }); console.log(` User: ${viewer.name} (${viewer.email})`); console.log(` Teams: ${teams.nodes.map(t => t.key).join(", ")}`); } catch (e: any) { checks.push({ name: "API Auth", ok: false }); console.error(` Auth failed: ${e.message}`); } for (const { name, ok } of checks) { console.log(` ${ok ? "PASS" : "FAIL"}: ${name}`); } const failed = checks.filter(c => !c.ok).length; if (failed > 0) process.exit(1); } validateEnvironment(); ``` ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Wrong environment data | API key for wrong workspace | Verify secrets per environment | | Secret not found | Missing in secret manager | Add secret for the target environment | | Team not found | Wrong `defaultTeamKey` | Check team key matches the environment's workspace | | Permission denied | Insufficient API key scope | Regenerate with correct scopes | ## Examples ### Quick Validation ```bash NODE_ENV=staging npx tsx scripts/validate-environment.ts # Output: # Validating Linear config for: staging # User: CI Bot (ci@company.com) # Teams: ENG, PRODUCT, DESIGN # PASS: API Key # PASS: Webhook Secret # PASS: Default Team # PASS: API Auth # PASS: Default Team Exists ``` ## Resources - [Linear API Authentication](https://linear.app/developers/graphql) - [12-Factor Config](https://12factor.net/config) - [GCP Secret Manager](https://cloud.google.com/secret-manager) - [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/) --- Source attribution: Jeremy Longshore Original project: https://github.com/aibot88/sec_skill_store/blob/608120788167d56f99e31449e411e603ed250dc6/skills/claudskills/linear-multi-env-setup/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: Jeremy Longshore Original project: https://github.com/aibot88/sec_skill_store/blob/608120788167d56f99e31449e411e603ed250dc6/skills/claudskills/linear-multi-env-setup/SKILL.md Attribution basis: Source repository record Fields of work: Product Management, Development & Engineering Roles: Growth Product Manager, Backend Developer, DevOps / SRE, Product Manager, Technical Product Manager Specialties: API, Backend, DevOps Tools: Linear, AWS, GCP Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 4e522bf5b21eee57ccd6cebddaec8d2c30d3b2f94f8cc035fc9ccd7ff0b4d990