Solution by Feature

Feature-by-feature breakdown of the refactoring changes.

For layer-by-layer architecture analysis, see solution-by-layer.md. For high-level overview, see README.md.

Reference Commits

Table of Contents

• Bitbucket API Migration
• Shell Script Libraries
• Stage Modularization
• Testability
• Logger System Integration
• Reference

1. Bitbucket API Migration

Migrated from Python subprocess to Native Groovy/Java HTTP Client.

1.1 Folder Structure Comparison

Before (74fc356)                          After (ff74ac8)
─────────────────                         ─────────────────
devops-jenkins-linux/                     devops-jenkins-linux/
├── DLXJenkins/                           ├── DLXJenkins/
│   └── Jenkinsfile ←───────────┐         │   └── Jenkinsfile ←─────────────────────────┐
├── groovy/                     │         └── sharedLibraries/                          │
│   └── generalHelper.groovy ←──┤             ├── vars/                                 │
└── python/                     │             │   ├── bitbucketApiHelper.groovy ←───────┤
    └── send_bitbucket_build_   │             │   └── bitbucketApiLibrary.groovy ←──────┤
        status.py ←─────────────┘             └── src/service/general/                  │
                                                  └── HttpApiService.groovy ←───────────┘
                                                     (formerly BitbucketApiService)

1.2 Before (74fc356)

Code Path: - DLXJenkins/Jenkinsfile → groovy/generalHelper.groovy:sendBuildStatus() → python/send_bitbucket_build_status.py

Problems: - Python process spawn overhead - External dependency (requests library) - Distributed error handling

1.3 After (ff74ac8)

Note: HttpApiService was initially named BitbucketApiService, later renamed for generalization.

Code Path:

Jenkinsfile (post block)
  → bitbucketApiLibrary.createBuildStatusForCommit()  // returns Map
  → bitbucketApiHelper(Map)                           // entry point
    → HttpApiService.post()                           // HTTP execution
      → executeRequest()                              // error handling

Improvements: - HTTP processing within JVM (no process spawn) - Structured error handling (Exception hierarchy) - Reusable API Service class

1.4 Design Decisions

Problem Situation

• Time-consuming to diagnose Bitbucket API communication failures when Jenkins service URL's third-party certificate expired
• Inconsistent error handling across Python scripts
• No distinction between network error types

Solution: Centralized Error Handling

HttpApiService.executeRequest() classifies all HTTP request errors by type:

Structure

2. Shell Script Libraries

Library system abstracting shell commands using Closure pattern. Three domain-specific Libraries: Git, Shell, SSH.

2.1 File Structure

sharedLibraries/
├── vars/
│   └── shellScriptHelper.groovy      ← Closure execution + logging integration
│       ├── call(Closure, List args)
│       ├── validateShMap(Map)
│       ├── executeReturnStatus(Map)
│       ├── executeReturnStdout(Map)
│       └── executeReturnVoid(Map)
│
└── src/utils/
    ├── GitLibrary.groovy (258 lines)     ← Git command Closures (23)
    ├── ShellLibrary.groovy (210 lines)   ← General shell command Closures (15)
    └── SSHShellLibrary.groovy (99 lines) ← SSH/SCP remote command Closures (8)

2.2 Closure Pattern Structure

2.3 Before (74fc356)

Problems: - Same git commands duplicated across multiple pipelines - No error handling - No logging - Untestable

2.4 After (ff74ac8)

Improvements: - Shell command reuse through Closure pattern - Automatic logging integration - Consistent error handling - Centralized validation logic

2.5 Closure List by Library

2.6 Closure Map Schema

[
    script: String,        // (Required) Shell script to execute
    label: String,         // (Required) Description shown in Jenkins build log
    returnStdout: Boolean, // (Optional) Return stdout
    returnStatus: Boolean, // (Optional) Return exit code
    returnStderr: Boolean, // (Optional) Return stderr
    encoding: String       // (Optional) Encoding (default: UTF-8)
]

Constraint: Only one of returnStdout, returnStatus, returnStderr can be true

2.7 Design Decisions

Pattern Identification

Analysis of all sh calls across pipelines revealed three domains:

Logger System Integration

Clear return type rules enable automatic logging in shellScriptHelper:

• Success: Call stepSuccess()
• Failure: Call stepError() (pipeline abort)
• Warning: Call stepWarning() (specific status codes)

3. Stage Modularization

3.1 Folder Structure Comparison (Linting Stage Example)

Before (74fc356)                                    After (ff74ac8)
─────────────────                                   ─────────────────
devops-jenkins-linux/                               devops-jenkins-linux/
├── DLXJenkins/                                     ├── DLXJenkins/
│   ├── Jenkinsfile                                 │   ├── Jenkinsfile
│   │   stage('Linting') {Inline/Duplicated}        │   │   stage('Linting') { stageLintUnity() }
│   └── JenkinsfileDeployment                       │   └── JenkinsfileDeployment
│       stage('Linting') {Inline/Duplicated}        │       stage('Linting') { stageLintUnity() }
├── JsJenkins/                                      ├── JsJenkins/
│   ├── Jenkinsfile                                 │   ├── Jenkinsfile
│   │   stage('Linting') {Inline/Duplicated}        │   │   stage('Linting') { stageLintJs() } *
│   └── JenkinsfileDeployment                       │   └── JenkinsfileDeployment
│       stage('Linting') {Inline/Duplicated}        │       stage('Linting') { stageLintJs() } *
├── PipelineForJenkins/                             ├── PipelineForJenkins/
│   └── Jenkinsfile                                 │   └── Jenkinsfile
│       stage('Lint Groovy Code') {                 │       stage('Lint Groovy Code') {
│           Inline/Duplicated }                     │           stageLintGroovyJenkinsfile() }
│                                                   │
└── groovy/                                         └── sharedLibraries/vars/
    ├── generalHelper.groovy                            ├── stageLintUnity.groovy
    └── unityHelper.groovy                              ├── stageLintJs.groovy *
                                                        └── stageLintGroovyJenkinsfile.groovy

*stageLintJs is not yet developed

3.2 Linting Stage Example

Before (74fc356) - ~50 lines

Problems: - Same Stage logic Inline/Duplicated across 5 pipelines - Modifications require changes in all 5 places - No logging, untestable

After (ff74ac8) - 1 line

Improvements: - Stage logic separated into module files (stage*.groovy) - Pipeline calls replaced with 1-line invocation - Automatic Logger system integration - Single Source of Truth

3.3 Complete Stage Modularization Design

Before (74fc356)                                    After (ff74ac8)
─────────────────                                   ─────────────────
DLXJenkins/Jenkinsfile                              DLXJenkins/Jenkinsfile
├── stage('Prepare WORKSPACE')                      ├── stage('Jenkins Initialization') { stageInitialization() }
├── stage('Linting')                                ├── stage('Prepare Project') { stageProjectPrepare() }
├── stage('EditMode Tests')                         ├── stage('Linting') { stageLintUnity() }
├── stage('PlayMode Tests in Editor')               ├── stage('Unity Execution') { stageUnityExecution() }
├── stage('Code Coverage Send Reports')             └── stage('Send Build Results') { stageSendBuildResults() }
└── stage('Build Project')
                                                    DLXJenkins/JenkinsfileDeployment
DLXJenkins/JenkinsfileDeployment                    ├── stage('Cleanup PR Branch Artifacts') { stageCleanupPRBranchArtifacts() }
├── stage('Delete Merged Branch')                   ├── stage('Jenkins Initialization') { stageInitialization() }
├── stage('Prepare WORKSPACE')                      ├── stage('Prepare Project') { stageProjectPrepare() }
├── stage('Linting')                                ├── stage('Linting') { stageLintUnity() }
├── stage('EditMode Tests')                         ├── stage('Unity Execution') { stageUnityExecution() }
├── stage('PlayMode Tests In Editor')               ├── stage('Deploy Build') { stageDeployBuild() }
├── stage('Build Project')                          └── stage('Send Build Results') { stageSendBuildResults() }
└── stage('Deploy Build')

groovy/                                             sharedLibraries/vars/
├── generalHelper.groovy                            ├── stageInitialization.groovy
├── jsHelper.groovy                                 ├── stageProjectPrepare.groovy
└── unityHelper.groovy                              ├── stageLintUnity.groovy
                                                    ├── stageLintGroovyJenkinsfile.groovy
                                                    ├── stageStaticAnalysis.groovy
                                                    ├── stageUnityExecution.groovy
                                                    ├── stageDeployBuild.groovy
                                                    ├── stageCleanupPRBranchArtifacts.groovy
                                                    └── stageSendBuildResults.groovy

4. Testability

One of the core goals of refactoring was to transition to a structure that enables unit testing.

4.1 Before: Helper + Python Script Structure

2 untestable patterns existed:

Pattern 1: Direct sh() calls in Helper

// groovy/generalHelper.groovy (Before - commit 74fc356)
void checkoutBranch(String prBranch) {
    sh(script: "git checkout ${prBranch}", returnStdout: true)  // Direct Jenkins DSL call
    echo "Checked out branch: ${prBranch}"                       // Direct Jenkins DSL call
}

Pattern 2: API calls via Python scripts

# python/send_bitbucket_build_status.py (Before)
import requests
import os

access_token = os.getenv('BITBUCKET_ACCESS_TOKEN')
url = f'{pr_repo}/commit/{args["pr-commit"]}/statuses/build'
response = requests.post(url, data=build_status, headers=headers)

Reasons for Being Untestable:

4.2 After: Library + Service Separation

Core Change: "Definition" and "Execution" separation + Dependency Injection

┌─────────────────────────────────────────────────────────────────────┐
│ Library (src/utils/)                                                │
│ → Shell command "definition" (returns Map)                          │
│ → No Jenkins dependency                                             │
│ → ✅ 100% unit testable                                             │
├─────────────────────────────────────────────────────────────────────┤
│ Service (src/service/)                                              │
│ → Business logic + API calls                                        │
│ → Mock-friendly constructor (receives context, uses only logger)    │
│ → ✅ Testable with mocks                                            │
├─────────────────────────────────────────────────────────────────────┤
│ Helper (vars/)                                                      │
│ → Command "execution" (sh calls)                                    │
│ → Jenkins DSL orchestration                                         │
│ → ⚠️ Integration test                                               │
└─────────────────────────────────────────────────────────────────────┘

Library: Shell Command Definition (Map Return)

// src/utils/GitLibrary.groovy
class GitLibrary {
    static final Closure CheckoutBranch = { String branchName ->
        [
            script: "git checkout ${branchName}",
            label: "Checkout branch '${branchName}'",
            returnStdout: true
        ]
    }
}

Service: API Call Logic (Mock-friendly Constructor)

// src/service/general/HttpApiService.groovy
class HttpApiService {
    def jenkinsfile
    def logger  // Only dependency actually used

    HttpApiService(def jenkinsfile) {
        this.jenkinsfile = jenkinsfile
        this.logger = jenkinsfile.logger
    }

    def post(String apiUrlString, String requestBodyJson, String bearerToken) {
        HttpPost httpPost = new HttpPost(apiUrlString)
        return executeRequest(httpPost, bearerToken)
    }
}

Why "Mock-friendly": The constructor receives pipeline context, but internally only uses logger. For testing, simply pass a mock object:

def mockJenkinsfile = [logger: mockLogger]
def service = new HttpApiService(mockJenkinsfile)
// Now service is fully testable without Jenkins environment

4.3 Test Code Examples

Library Test - Pure unit test without Jenkins:

// GitLibrarySpec.groovy
class GitLibrarySpec extends Specification {
    def "CheckoutBranch - branch name correctly inserted into script"() {
        when:
        def result = GitLibrary.CheckoutBranch('feature/JIRA-123')

        then:
        result.script == "git checkout feature/JIRA-123"
        result.label == "Checkout branch 'feature/JIRA-123'"
        result.returnStdout == true
    }
}

4.4 Before vs After: API Testability Comparison

5. Logger System Integration

For detailed design documentation including problem analysis, solution discovery, and architecture integration, see logger-system-design-integration.md.

Summary

Before/After

6. Reference

Repository

• GitHub: https://github.com/JindoKimKor/devops-jenkins-linux

Related Documents

• solution-by-layer.md - Layer-by-layer architecture analysis
• logger-system-design-integration.md - Logger System design details
• domain-driven-analysis.md - DDD pattern analysis