# Jenkins

Jenkins provides flexible Docker integration through plugins and pipeline scripts, making it suitable for self-hosted KushoAI testing workflows.

# Prerequisites

Docker Support: Jenkins server with Docker installed
Docker Plugin: Install the Docker plugin for Jenkins (recommended)
Credentials Management: Jenkins credential store for secure API key management

# Docker Image

All execution uses the Kusho test runner Docker image:

public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

# Setup Instructions

# 1. Configure Jenkins Credentials

Navigate to Jenkins → Manage Jenkins → Manage Credentials → System → Global credentials:

Add Secret Text for your Kusho API key:
- Kind: Secret text
- Secret: Your Kusho API key
- ID: KUSHO_API_KEY
- Description: Kusho API Key

# 2. Create Pipeline Job

Create a new Pipeline job or modify an existing one with the following configuration:

# 3. Basic Pipeline Configuration

pipeline {
    agent any
    
    environment {
        KUSHO_API_KEY = credentials('KUSHO_API_KEY')
        BASE_URL = 'https://be.kusho.ai'
        ENVIRONMENT_ID = '2'
        TEST_SUITE_UUID = 'uuid1,uuid2,uuid3'
    }
    
    stages {
        stage('Run Kusho Tests') {
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e BASE_URL="${BASE_URL}" \\
                            -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                            -e API_KEY="${KUSHO_API_KEY}" \\
                            -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                            -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                            -e TEST_SUITE_UUID="${TEST_SUITE_UUID}" \\
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
    }
}

# Execution Methods

# 1. Execute by Test Suite UUID

stage('Test by UUID') {
    steps {
        script {
            sh """
                docker run --rm \\
                    -e BASE_URL="${BASE_URL}" \\
                    -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                    -e API_KEY="${KUSHO_API_KEY}" \\
                    -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                    -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                    -e TEST_SUITE_UUID="${params.TEST_SUITE_UUID}" \\
                    public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
            """
        }
    }
}

# 2. Execute by Group ID

stage('Test by Group') {
    steps {
        script {
            sh """
                docker run --rm \\
                    -e BASE_URL="${BASE_URL}" \\
                    -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                    -e API_KEY="${KUSHO_API_KEY}" \\
                    -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                    -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                    -e GROUP_ID="${params.GROUP_ID}" \\
                    public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
            """
        }
    }
}

# 3. Execute by Tags

stage('Test by Tags') {
    steps {
        script {
            sh """
                docker run --rm \\
                    -e BASE_URL="${BASE_URL}" \\
                    -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                    -e API_KEY="${KUSHO_API_KEY}" \\
                    -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                    -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                    -e TAGS="${params.TEST_TAGS}" \\
                    public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
            """
        }
    }
}

# 4. Execute E2E Workflows

stage('E2E Tests') {
    steps {
        script {
            sh """
                docker run --rm \\
                    -e BASE_URL="${BASE_URL}" \\
                    -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                    -e API_KEY="${KUSHO_API_KEY}" \\
                    -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                    -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                    -e E2E_TEST_SUITE_UUID="${params.E2E_TEST_SUITE_UUID}" \\
                    -e EXECUTION_PROFILE_UUID="${params.EXECUTION_PROFILE_UUID}" \\
                    public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
            """
        }
    }
}

# Complete Pipeline Examples

# Multi-Stage Testing Pipeline

pipeline {
    agent any
    
    parameters {
        choice(
            name: 'ENVIRONMENT',
            choices: ['staging', 'production'],
            description: 'Target environment'
        )
        string(
            name: 'TEST_SUITE_UUID',
            defaultValue: '',
            description: 'Comma-separated test suite UUIDs'
        )
        string(
            name: 'TEST_TAGS',
            defaultValue: 'smoke',
            description: 'Comma-separated test tags'
        )
    }
    
    environment {
        KUSHO_API_KEY = credentials('KUSHO_API_KEY')
        BASE_URL = 'https://be.kusho.ai'
    }
    
    stages {
        stage('Setup Environment') {
            steps {
                script {
                    if (params.ENVIRONMENT == 'production') {
                        env.ENVIRONMENT_ID = '1'
                    } else {
                        env.ENVIRONMENT_ID = '2'
                    }
                }
            }
        }
        
        stage('Smoke Tests') {
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e BASE_URL="${BASE_URL}" \\
                            -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                            -e API_KEY="${KUSHO_API_KEY}" \\
                            -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                            -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                            -e TAGS="smoke" \\
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
        
        stage('Integration Tests') {
            when {
                anyOf {
                    branch 'main'
                    branch 'develop'
                }
            }
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e BASE_URL="${BASE_URL}" \\
                            -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                            -e API_KEY="${KUSHO_API_KEY}" \\
                            -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                            -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                            -e TAGS="integration" \\
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
        
        stage('Custom Test Suite') {
            when {
                not { equals expected: '', actual: params.TEST_SUITE_UUID }
            }
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e BASE_URL="${BASE_URL}" \\
                            -e ENVIRONMENT_ID="${ENVIRONMENT_ID}" \\
                            -e API_KEY="${KUSHO_API_KEY}" \\
                            -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                            -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}" \\
                            -e TEST_SUITE_UUID="${params.TEST_SUITE_UUID}" \\
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
    }
    
    post {
        success {
            echo 'All tests passed successfully!'
        }
        failure {
            echo 'Tests failed. Check the logs for details.'
            // Add notification logic here
        }
        always {
            // Clean up Docker containers if needed
            sh 'docker system prune -f || true'
        }
    }
}

# Parameterized Build Pipeline

pipeline {
    agent any
    
    parameters {
        choice(
            name: 'EXECUTION_MODE',
            choices: ['UUID', 'GROUP', 'TAGS', 'E2E'],
            description: 'Test execution mode'
        )
        string(
            name: 'TEST_SUITE_UUID',
            defaultValue: '',
            description: 'Test Suite UUIDs (for UUID mode)'
        )
        string(
            name: 'GROUP_ID',
            defaultValue: '',
            description: 'Group ID (for GROUP mode)'
        )
        string(
            name: 'TAGS',
            defaultValue: '',
            description: 'Test tags (for TAGS mode)'
        )
        string(
            name: 'E2E_TEST_SUITE_UUID',
            defaultValue: '',
            description: 'E2E Test Suite UUID (for E2E mode)'
        )
        string(
            name: 'EXECUTION_PROFILE_UUID',
            defaultValue: '',
            description: 'Execution Profile UUID (for E2E mode)'
        )
        string(
            name: 'ENVIRONMENT_ID',
            defaultValue: '2',
            description: 'Target Environment ID'
        )
    }
    
    environment {
        KUSHO_API_KEY = credentials('KUSHO_API_KEY')
        BASE_URL = 'https://be.kusho.ai'
    }
    
    stages {
        stage('Run Tests') {
            steps {
                script {
                    def dockerCmd = """
                        docker run --rm \\
                            -e BASE_URL="${BASE_URL}" \\
                            -e ENVIRONMENT_ID="${params.ENVIRONMENT_ID}" \\
                            -e API_KEY="${KUSHO_API_KEY}" \\
                            -e CI_COMMIT_SHA="${env.GIT_COMMIT}" \\
                            -e CI_COMMIT_MESSAGE="${env.GIT_COMMIT_MSG}"
                    """
                    
                    switch(params.EXECUTION_MODE) {
                        case 'UUID':
                            dockerCmd += " -e TEST_SUITE_UUID=\"${params.TEST_SUITE_UUID}\""
                            break
                        case 'GROUP':
                            dockerCmd += " -e GROUP_ID=\"${params.GROUP_ID}\""
                            break
                        case 'TAGS':
                            dockerCmd += " -e TAGS=\"${params.TAGS}\""
                            break
                        case 'E2E':
                            dockerCmd += " -e E2E_TEST_SUITE_UUID=\"${params.E2E_TEST_SUITE_UUID}\""
                            dockerCmd += " -e EXECUTION_PROFILE_UUID=\"${params.EXECUTION_PROFILE_UUID}\""
                            break
                    }
                    
                    dockerCmd += " public.ecr.aws/y5g4u6y7/kusho-test-runner:latest"
                    
                    sh dockerCmd
                }
            }
        }
    }
}

# Jenkins Features and Best Practices

# Environment Variables

Jenkins provides several built-in environment variables:

${env.GIT_COMMIT} - Git commit SHA
${env.GIT_BRANCH} - Git branch name
${env.BUILD_NUMBER} - Jenkins build number
${env.JOB_NAME} - Jenkins job name

# Conditional Execution

when {
    anyOf {
        branch 'main'
        branch 'develop'
    }
}

when {
    not { equals expected: '', actual: params.TEST_SUITE_UUID }
}

when {
    environment name: 'DEPLOY_ENV', value: 'production'
}

# Parallel Execution

stage('Parallel Tests') {
    parallel {
        stage('Smoke Tests') {
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e TAGS="smoke" \\
                            # ... other variables
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
        stage('Integration Tests') {
            steps {
                script {
                    sh """
                        docker run --rm \\
                            -e TAGS="integration" \\
                            # ... other variables
                            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                    """
                }
            }
        }
    }
}

# Notifications

post {
    success {
        slackSend(
            channel: '#testing',
            color: 'good',
            message: "✅ Kusho tests passed for ${env.JOB_NAME} - ${env.BUILD_NUMBER}"
        )
    }
    failure {
        slackSend(
            channel: '#testing',
            color: 'danger',
            message: "❌ Kusho tests failed for ${env.JOB_NAME} - ${env.BUILD_NUMBER}"
        )
        emailext(
            subject: "Test Failure: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
            body: "Tests failed. Check the build logs for details.",
            to: "${env.CHANGE_AUTHOR_EMAIL}"
        )
    }
}

# Security Best Practices

# Credential Management

Use Jenkins credential store for API keys
Never hardcode sensitive information in pipeline scripts
Implement proper access controls

# Pipeline Security

pipeline {
    options {
        skipDefaultCheckout()
        timeout(time: 1, unit: 'HOURS')
    }
    // ... rest of pipeline
}

# Docker Security

// Clean up after execution
post {
    always {
        sh 'docker system prune -f || true'
    }
}

# Troubleshooting

# Common Issues

Docker Permission Issues
- Ensure Jenkins user has Docker permissions
- Add Jenkins user to docker group: sudo usermod -aG docker jenkins
Network Connectivity
- Verify Jenkins server can access ECR registry
- Check firewall and proxy settings
Git Commit Message Issues
- Set up proper Git integration
- Use Git plugin for automatic variable population

# Manual Commit Message Setup

If Git environment variables are not available:

stage('Get Commit Info') {
    steps {
        script {
            env.GIT_COMMIT_MSG = sh(
                script: 'git log -1 --pretty=%B',
                returnStdout: true
            ).trim()
        }
    }
}

# Debug Information

stage('Debug Info') {
    steps {
        sh 'docker --version'
        sh 'docker info'
        sh 'env | grep -E "(GIT_|BUILD_|JOB_)"'
    }
}

# Integration Examples

# Blue Ocean Plugin

The pipeline is compatible with Blue Ocean for enhanced visualization.

# Pipeline as Code

Store your Jenkinsfile in version control for better maintainability:

// Jenkinsfile
@Library('your-shared-library') _

kushoTestPipeline {
    environment = 'staging'
    testTags = 'smoke,regression'
    apiKeyCredential = 'KUSHO_API_KEY'
}

# Matrix Builds

stage('Matrix Tests') {
    matrix {
        axes {
            axis {
                name 'ENVIRONMENT'
                values 'staging', 'production'
            }
            axis {
                name 'TAG_SET'
                values 'smoke', 'integration'
            }
        }
        stages {
            stage('Test') {
                steps {
                    script {
                        sh """
                            docker run --rm \\
                                -e ENVIRONMENT_ID="\${ENVIRONMENT == 'production' ? '1' : '2'}" \\
                                -e TAGS="\${TAG_SET}" \\
                                # ... other variables
                                public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
                        """
                    }
                }
            }
        }
    }
}