Tutorial: How to Set Up Linear 2026 for Your Engineering Team With GitHub Actions 2026, Slack 2026, and Sentry 24.0 Integrations

// linear-setup-verify.js
// Verifies Linear 2026 API credentials, lists available workspaces, and registers a webhook endpoint
// Requirements: Node.js 22+, linear-api-2026 SDK v3.1.0, express v5.0.0, dotenv v16.4.0

import 'dotenv/config';
import { LinearClient } from '@linear/sdk-2026';
import express from 'express';
import crypto from 'node:crypto';
import { logger } from './logger.js'; // Assume structured logger per 2026 best practices

// Validate required environment variables
const requiredEnvVars = ['LINEAR_API_KEY', 'LINEAR_WEBHOOK_SECRET', 'WEBHOOK_PORT'];
for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

// Initialize Linear 2026 client with rate limiting (100 req/min per Linear 2026 docs)
const linearClient = new LinearClient({
  apiKey: process.env.LINEAR_API_KEY,
  maxRetries: 3,
  retryDelayMs: 1000,
  rateLimit: {
    maxRequests: 100,
    perMs: 60000
  }
});

const app = express();
const PORT = process.env.WEBHOOK_PORT || 3000;

// Middleware to parse JSON and verify Linear webhook signatures (prevents replay attacks)
app.use(express.json({
  verify: (req, res, buf) => {
    const signature = req.headers['linear-signature'];
    if (!signature) {
      throw new Error('Missing Linear signature header');
    }
    const hmac = crypto.createHmac('sha256', process.env.LINEAR_WEBHOOK_SECRET);
    hmac.update(buf);
    const digest = `sha256=${hmac.digest('hex')}`;
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))) {
      throw new Error('Invalid Linear webhook signature');
    }
    req.rawBody = buf;
  }
}));

// Health check endpoint for GitHub Actions and Slack integration validation
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'healthy', timestamp: new Date().toISOString() });
});

// Webhook handler for Linear events (issue updates, comment creation, etc.)
app.post('/linear-webhook', async (req, res) => {
  try {
    const event = req.body;
    logger.info(`Received Linear webhook event: ${event.type}`, { eventId: event.id });

    // Handle issue status change events (used later for GitHub Actions sync)
    if (event.type === 'issue.status.updated') {
      const { issue, status } = event.data;
      logger.debug(`Issue ${issue.id} status updated to ${status.name}`);
      // Placeholder for later integration logic
    }

    res.status(200).json({ received: true });
  } catch (error) {
    logger.error(`Webhook handler failed: ${error.message}`, { stack: error.stack });
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Main execution block: Verify API key, list workspaces, register webhook
async function setupLinear() {
  try {
    // Verify API key by fetching current user (Linear 2026 API returns 401 for invalid keys)
    const currentUser = await linearClient.viewer.fetch();
    logger.info(`Authenticated as Linear user: ${currentUser.email} (ID: ${currentUser.id})`);

    // List all workspaces accessible to the API key
    const workspaces = await linearClient.workspaces();
    logger.info(`Found ${workspaces.nodes.length} accessible Linear workspace(s):`);
    workspaces.nodes.forEach(ws => {
      logger.info(`- ${ws.name} (ID: ${ws.id}, slug: ${ws.slug})`);
    });

    // Register webhook for issue status updates and comment events
    const webhookUrl = `${process.env.PUBLIC_WEBHOOK_URL}/linear-webhook`;
    const existingWebhooks = await linearClient.webhooks();
    const duplicateWebhook = existingWebhooks.nodes.find(wh => wh.url === webhookUrl);

    if (duplicateWebhook) {
      logger.warn(`Webhook already registered: ${duplicateWebhook.id}, reusing`);
      return duplicateWebhook;
    }

    const newWebhook = await linearClient.createWebhook({
      url: webhookUrl,
      secret: process.env.LINEAR_WEBHOOK_SECRET,
      triggers: ['issue.status.updated', 'issue.comment.created', 'issue.created'],
      enabled: true,
      label: 'GitHub-Actions-Slack-Sentry-Integration-2026'
    });

    logger.info(`Registered new Linear webhook: ${newWebhook.id} (URL: ${webhookUrl})`);
    return newWebhook;
  } catch (error) {
    logger.error(`Linear setup failed: ${error.message}`, { 
      status: error.status, 
      linearErrorCode: error.extensions?.code 
    });
    process.exit(1);
  }
}

// Start server and run setup
app.listen(PORT, async () => {
  logger.info(`Webhook server listening on port ${PORT}`);
  await setupLinear();
});

# .github/workflows/linear-integration-2026.yml
# GitHub Actions 2026 workflow for Linear, Slack, Sentry integration
# Requires GitHub Actions 2026.0.0-beta.4 or later, repo secrets configured

name: Linear 2026 Integrated CI/CD

on:
  push:
    branches: [main, staging]
  pull_request:
    types: [opened, synchronize, reopened, closed]

env:
  NODE_VERSION: '22.9.0'
  SENTRY_ORG: 'acme-engineering-2026'
  SENTRY_PROJECT: 'web-app'
  LINEAR_WORKSPACE_ID: 'ws_2026_acme_main'

jobs:
  # Job 1: Run tests, update Linear issue status, send Slack notification
  test-and-update-linear:
    runs-on: ubuntu-2026-latest
    permissions:
      issues: write
      pull-requests: write
      id-token: write # For GitHub OIDC auth to Linear 2026
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2026.0.1
        with:
          fetch-depth: 0 # Required to get full git history for Linear issue linking

      - name: Setup Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@v2026.0.1
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci --ignore-scripts
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Run unit tests
        id: unit-tests
        run: npm run test:unit -- --coverage
        continue-on-error: false

      - name: Run integration tests
        id: integration-tests
        run: npm run test:integration
        continue-on-error: false
        env:
          DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL }}

      # Update Linear issue status to "In Progress" when PR is opened
      - name: Update Linear issue status on PR open
        if: github.event.action == 'opened'
        uses: linear-2026/github-action@v3.2.0
        with:
          linear-api-key: ${{ secrets.LINEAR_API_KEY }}
          workspace-id: ${{ env.LINEAR_WORKSPACE_ID }}
          issue-id: ${{ github.event.pull_request.head.ref }} # Assumes branch name matches Linear issue ID
          status: 'In Progress'
          comment: 'PR #${{ github.event.pull_request.number }} opened by @${{ github.actor }}: ${{ github.event.pull_request.html_url }}'

      # Send Slack notification on test failure
      - name: Notify Slack on test failure
        if: failure()
        uses: slackapi/slack-github-action@v2026.0.1
        with:
          slack-token: ${{ secrets.SLACK_BOT_TOKEN }}
          channel-id: 'C1234567890' # #ci-cd-failures channel ID
          slack-message: |
            :rotating_light: Tests failed for PR #${{ github.event.pull_request.number }}
            Author: @${{ github.actor }}
            Branch: `${{ github.head_ref }}`
            Commit: `${{ github.sha }}`
            <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>
        env:
          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

  # Job 2: Deploy to staging, update Linear, notify Slack, send Sentry release
  deploy-staging:
    needs: test-and-update-linear
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-2026-latest
    environment: staging
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2026.0.1

      - name: Setup Node.js
        uses: actions/setup-node@v2026.0.1
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build
        env:
          NODE_ENV: 'staging'
          API_URL: ${{ secrets.STAGING_API_URL }}

      - name: Deploy to staging
        id: deploy
        run: npm run deploy:staging
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: 'us-east-1'

      # Create Sentry release for staging deployment
      - name: Create Sentry release
        uses: sentry-2026/github-action@v24.0.1
        with:
          sentry-auth-token: ${{ secrets.SENTRY_AUTH_TOKEN }}
          org: ${{ env.SENTRY_ORG }}
          project: ${{ env.SENTRY_PROJECT }}
          environment: 'staging'
          version: ${{ github.sha }}
          commits: ${{ github.sha }}
          linear-issue-id: ${{ github.head_ref }} # Link Sentry release to Linear issue

      # Update Linear issue status to "In Staging" after successful deployment
      - name: Update Linear issue to In Staging
        uses: linear-2026/github-action@v3.2.0
        with:
          linear-api-key: ${{ secrets.LINEAR_API_KEY }}
          workspace-id: ${{ env.LINEAR_WORKSPACE_ID }}
          issue-id: ${{ github.head_ref }}
          status: 'In Staging'
          comment: 'Deployed to staging: ${{ steps.deploy.outputs.staging_url }}'

      # Send Slack notification for successful staging deployment
      - name: Notify Slack on staging deploy
        uses: slackapi/slack-github-action@v2026.0.1
        with:
          slack-token: ${{ secrets.SLACK_BOT_TOKEN }}
          channel-id: 'C0987654321' # #releases channel ID
          slack-message: |
            :shipit: Staging deployed successfully!
            PR: #${{ github.event.pull_request.number }}
            Author: @${{ github.actor }}
            Staging URL: ${{ steps.deploy.outputs.staging_url }}
            Sentry Release: ${{ github.sha }}
            <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Run>

# slack-sentry-linear-setup.py
# Configures Slack 2026 OAuth app, Sentry 24.0 project rules, and links Sentry to Linear 2026
# Requirements: Python 3.12+, slack-sdk-2026 v4.1.0, sentry-sdk-24 v5.0.0, python-dotenv v1.0.0

import os
import sys
import json
import logging
from dotenv import load_dotenv
from slack_sdk_2026 import WebClient
from slack_sdk_2026.oauth import OAuthStateUtils
from sentry_24 import SentryClient, SentryError
from linear_2026 import LinearClient as LinearClient2026

# Configure structured logging (JSON format for production)
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

# Load environment variables from .env file
load_dotenv()

# Validate required environment variables
REQUIRED_ENVS = [
    'SLACK_BOT_TOKEN', 'SLACK_CLIENT_ID', 'SLACK_CLIENT_SECRET',
    'SENTRY_AUTH_TOKEN', 'SENTRY_ORG', 'SENTRY_PROJECT',
    'LINEAR_API_KEY', 'LINEAR_WORKSPACE_ID'
]
for env_var in REQUIRED_ENVS:
    if not os.getenv(env_var):
        logger.error(f"Missing required environment variable: {env_var}")
        sys.exit(1)

# Initialize clients
slack_client = WebClient(token=os.getenv('SLACK_BOT_TOKEN'))
sentry_client = SentryClient(
    auth_token=os.getenv('SENTRY_AUTH_TOKEN'),
    org=os.getenv('SENTRY_ORG'),
    max_retries=3,
    retry_delay=1.0
)
linear_client = LinearClient2026(api_key=os.getenv('LINEAR_API_KEY'))

def setup_slack_oauth():
    """Configures Slack 2026 OAuth app with required scopes for Linear integration"""
    try:
        # Verify Slack token has admin scopes
        auth_test = slack_client.auth_test()
        if not auth_test['ok']:
            raise Exception(f"Slack auth test failed: {auth_test['error']}")
        logger.info(f"Authenticated to Slack as team: {auth_test['team']} (ID: {auth_test['team_id']})")

        # Required scopes for Linear integration per Slack 2026 docs
        required_scopes = [
            'channels:read', 'channels:write', 'chat:write',
            'commands', 'users:read', 'users:read.email'
        ]
        logger.info(f"Slack app configured with scopes: {required_scopes}")

        # Create #linear-updates channel if it doesn't exist
        channels = slack_client.conversations_list(types='public_channel')
        linear_channel = next((ch for ch in channels['channels'] if ch['name'] == 'linear-updates'), None)

        if not linear_channel:
            linear_channel = slack_client.conversations_create(
                name='linear-updates',
                topic='Automated Linear issue updates from GitHub Actions and Sentry'
            )['channel']
            logger.info(f"Created #linear-updates channel: {linear_channel['id']}")
        else:
            logger.info(f"Reusing existing #linear-updates channel: {linear_channel['id']}")

        return linear_channel['id']
    except Exception as e:
        logger.error(f"Slack setup failed: {str(e)}", exc_info=True)
        sys.exit(1)

def setup_sentry_linear_integration(linear_channel_id):
    """Configures Sentry 24.0 to create Linear issues for new errors, notify via Slack"""
    try:
        # Verify Sentry org access
        org = sentry_client.get_org()
        logger.info(f"Authenticated to Sentry org: {org['name']} (ID: {org['id']})")

        # Get Sentry project
        project = sentry_client.get_project(os.getenv('SENTRY_PROJECT'))
        logger.info(f"Sentry project: {project['name']} (ID: {project['id']})")

        # Create Sentry alert rule: Create Linear issue on new error, notify Slack
        rule_name = 'Linear-Slack-Error-Integration-2026'
        existing_rules = sentry_client.list_alert_rules(project['id'])
        duplicate_rule = next((r for r in existing_rules if r['name'] == rule_name), None)

        if duplicate_rule:
            logger.warn(f"Alert rule already exists: {duplicate_rule['id']}, reusing")
            return duplicate_rule

        # Rule conditions: New issue created, event frequency > 1 per hour
        new_rule = sentry_client.create_alert_rule(
            project_id=project['id'],
            name=rule_name,
            conditions=[
                {
                    'id': 'sentry.rules.conditions.first_seen_event.FirstSeenEventCondition',
                    'name': 'A new issue is created'
                },
                {
                    'id': 'sentry.rules.conditions.event_frequency.EventFrequencyCondition',
                    'value': 1,
                    'interval': '1h',
                    'name': 'An event is seen more than 1 time in 1 hour'
                }
            ],
            actions=[
                {
                    'id': 'sentry.rules.actions.linear.LinearCreateIssueAction',
                    'workspace_id': os.getenv('LINEAR_WORKSPACE_ID'),
                    'team_id': 'team_2026_acme_backend', # Linear team ID for backend errors
                    'issue_type': 'Bug',
                    'priority': 'High',
                    'assign_to_committer': True # Assign to the GitHub committer if available
                },
                {
                    'id': 'sentry.rules.actions.slack.SlackNotifyAction',
                    'channel_id': linear_channel_id,
                    'message': 'New Sentry error created: {issue_title} (Linked Linear Issue: {linear_issue_url})'
                }
            ],
            frequency=60 # Check every 60 minutes
        )

        logger.info(f"Created Sentry alert rule: {new_rule['id']} (Name: {rule_name})")
        return new_rule
    except SentryError as e:
        logger.error(f"Sentry setup failed: {str(e)} (Status: {e.status_code})", exc_info=True)
        sys.exit(1)
    except Exception as e:
        logger.error(f"Unexpected error during Sentry setup: {str(e)}", exc_info=True)
        sys.exit(1)

def verify_linear_slack_link(channel_id):
    """Verifies Linear 2026 can send notifications to Slack channel"""
    try:
        # Get Linear workspace details
        workspace = linear_client.get_workspace(os.getenv('LINEAR_WORKSPACE_ID'))
        logger.info(f"Linear workspace: {workspace['name']} (ID: {workspace['id']})")

        # Check if Slack integration is enabled for workspace
        integrations = linear_client.list_integrations(workspace['id'])
        slack_integration = next((i for i in integrations if i['type'] == 'slack'), None)

        if not slack_integration:
            logger.warn("Slack integration not enabled in Linear workspace. Enable via Linear Settings > Integrations > Slack")
        else:
            logger.info(f"Linear Slack integration active: {slack_integration['id']}")

        # Send test message to Slack channel to verify link
        slack_client.chat_postMessage(
            channel=channel_id,
            text='Linear 2026 + Slack 2026 + Sentry 24.0 integration test message. All systems operational.'
        )
        logger.info(f"Sent test message to Slack channel {channel_id}")
    except Exception as e:
        logger.error(f"Linear-Slack link verification failed: {str(e)}", exc_info=True)

if __name__ == '__main__':
    logger.info("Starting Slack + Sentry + Linear integration setup...")
    linear_channel_id = setup_slack_oauth()
    sentry_rule = setup_sentry_linear_integration(linear_channel_id)
    verify_linear_slack_link(linear_channel_id)
    logger.info("Integration setup completed successfully.")

// Handle batch Linear webhook events
app.post('/linear-webhook', async (req, res) => {
  const events = Array.isArray(req.body) ? req.body : [req.body]; // Handle both batch and single events
  for (const event of events) {
    logger.info(`Processing event: ${event.type}`, { eventId: event.id });
    // Add event-specific handling here
  }
  res.status(200).json({ received: true, eventCount: events.length });
});

# .gitmessage pre-commit hook to validate Linear issue ID
#!/bin/bash
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")
if ! echo "$commit_msg" | grep -qE '^(feat|fix|chore|docs|test)\(LINEAR-[0-9]+\):'; then
  echo "Error: Commit message must include Linear issue ID (e.g., fix(LINEAR-123): ...)"
  exit 1
fi

# Slack GitHub Action with threaded notifications by Linear issue ID
- name: Notify Slack with threading
  uses: slackapi/slack-github-action@v2026.0.1
  with:
    slack-token: ${{ secrets.SLACK_BOT_TOKEN }}
    channel-id: 'C0987654321'
    thread-ts: ${{ github.head_ref }} # Linear issue ID from branch name
    slack-message: 'Tests passed for PR #${{ github.event.pull_request.number }}'

linear-github-actions-slack-sentry-integration/
├── .github/
│   └── workflows/
│       └── linear-integration-2026.yml  # GitHub Actions workflow (Code Example 2)
├── scripts/
│   ├── linear-setup-verify.js          # Linear setup script (Code Example 1)
│   └── slack-sentry-linear-setup.py    # Slack/Sentry setup script (Code Example 3)
├── .env.example                        # Example environment variables
├── logger.js                           # Structured logger for Node.js scripts
├── .gitmessage                         # Pre-commit hook for commit validation
└── README.md                           # Tutorial setup instructions