spicy-automation/docs/JENKINS_UTILITIES.md

Jenkins Utilities Reference

All available utility functions in the spicy-automation Jenkins shared library.

Table of Contents

• cdkUtils - CDK command execution
• dockerUtils - Docker/Nexus operations
• gitUtils - Git information
• giteaUtils - Gitea commit status
• awsUtils - AWS CLI operations
• spicyUtils - Pipeline utilities
• accounts - Account configurations
• manualApproval - Approval gates

---

cdkUtils

Execute AWS CDK commands from Jenkins pipelines.

cdkUtils.deploy(Map args)

Deploy a CDK stack.

cdkUtils.deploy(
    account: [
        region: "ca-central-1",
        jenkinsAwsCredentialsId: "aws-credentials",
        accountId: "123456789012"  // optional
    ],
    stackName: "my-stack",
    stackType: "vpc",              // vpc, ecs-cluster, ecs-service
    context: [                     // Additional CDK context
        ownerTag: "MyTeam",
        productTag: "myapp"
    ],
    workDir: "."                   // optional, defaults to current dir
)

cdkUtils.diff(Map args)

Show changes between deployed and local stack.

cdkUtils.diff(
    account: account,
    stackName: "my-stack",
    stackType: "vpc",
    context: context
)

cdkUtils.synth(Map args)

Synthesize CloudFormation template.

cdkUtils.synth(
    account: account,
    stackName: "my-stack",
    stackType: "vpc",
    context: context
)

cdkUtils.destroy(Map args)

Destroy a CDK stack.

cdkUtils.destroy(
    account: account,
    stackName: "my-stack",
    stackType: "vpc",
    context: context
)

cdkUtils.install(Map args)

Install CDK dependencies.

cdkUtils.install(workDir: ".")

cdkUtils.build(Map args)

Build CDK TypeScript (optional - ts-node runs directly).

cdkUtils.build(workDir: ".")

cdkUtils.test(Map args)

Run CDK tests.

cdkUtils.test(workDir: ".")

---

dockerUtils

Docker operations with Nexus registry support.

Default Configuration:

• Registry: nexus.kodeniks.com
• Repository: docker-hosted
• Credentials: kodeniks-nexus-repository

dockerUtils.buildAndPush(Map args)

Build and push a Docker image to Nexus.

def imageRef = dockerUtils.buildAndPush(
    imageName: "my-service",           // required
    dockerfile: "Dockerfile",          // default: Dockerfile
    context: ".",                       // default: .
    buildArgs: [                        // optional
        NODE_ENV: "production",
        VERSION: "1.0.0"
    ],
    tagLatest: true,                   // default: true on main branch
    compareWithLatest: true,           // default: true, skip if unchanged
    registry: "nexus.kodeniks.com",    // optional override
    repository: "docker-hosted",       // optional override
    credentialsId: "kodeniks-nexus-repository"  // optional override
)

echo "Pushed: ${imageRef}"
// Output: nexus.kodeniks.com/docker-hosted/my-service:abc1234

dockerUtils.buildImage(Map args)

Build a Docker image without pushing.

def containerName = dockerUtils.buildImage(
    imageName: "my-service",
    dockerfile: "Dockerfile",
    context: ".",
    buildArgs: [NODE_ENV: "production"]
)

dockerUtils.tagImage(Map args)

Tag an image for Nexus registry.

dockerUtils.tagImage(
    imageName: "my-service",
    tagLatest: true  // also tag as 'latest'
)

dockerUtils.pushImage(Map args)

Push image to Nexus with smart comparison.

def pushed = dockerUtils.pushImage(
    imageName: "my-service",
    tagLatest: true,
    compareWithLatest: true  // skip if identical to remote latest
)

if (pushed) {
    echo "Image was pushed"
} else {
    echo "Image unchanged, push skipped"
}

dockerUtils.pullImage(Map args)

Pull an image from Nexus.

def imageRef = dockerUtils.pullImage(
    imageName: "my-service",
    tag: "latest"  // default: latest
)

dockerUtils.login(Map args)

Login to Nexus registry.

dockerUtils.login()
// Or with custom registry:
dockerUtils.login(registry: "other-nexus.example.com")

dockerUtils.prune()

Clean up dangling Docker images.

dockerUtils.prune()

dockerUtils.copyFromImage(Map args)

Copy files from a Docker image.

dockerUtils.copyFromImage(
    imageID: "my-image:latest",
    dockerPath: "/app/dist",
    jenkinsPath: "./dist"
)

dockerUtils.getImageRefSHA(Map args)

Get full image reference with SHA tag.

def ref = dockerUtils.getImageRefSHA(imageName: "my-service")
// Returns: nexus.kodeniks.com/docker-hosted/my-service:abc1234

dockerUtils.getImageRefLatest(Map args)

Get full image reference with latest tag.

def ref = dockerUtils.getImageRefLatest(imageName: "my-service")
// Returns: nexus.kodeniks.com/docker-hosted/my-service:latest

---

gitUtils

Git repository information.

gitUtils.getSHA()

Get full commit SHA.

def sha = gitUtils.getSHA()
// Returns: abc123def456...

gitUtils.getShortSHA()

Get short commit SHA (7 characters).

def shortSha = gitUtils.getShortSHA()
// Returns: abc123d

gitUtils.getBranch()

Get current branch name.

def branch = gitUtils.getBranch()
// Returns: main, feature/xyz, etc.

gitUtils.isMain()

Check if on main branch.

if (gitUtils.isMain()) {
    echo "On main branch - deploying!"
}

gitUtils.getRemoteURL()

Get Git remote URL.

def url = gitUtils.getRemoteURL()
// Returns: git@git.kodeniks.com:CORP/my-repo.git

---

giteaUtils

Update Gitea commit status.

Default Configuration:

• Gitea URL: https://git.kodeniks.com
• Credentials: kodeniks-gitea-token

giteaUtils.setSuccess(context)

Set commit status to success.

giteaUtils.setSuccess("build")
giteaUtils.setSuccess("deploy")

giteaUtils.setPending(context)

Set commit status to pending.

giteaUtils.setPending("build")

giteaUtils.setFailed(context)

Set commit status to failed.

giteaUtils.setFailed("build")

giteaUtils.setError(context)

Set commit status to error.

giteaUtils.setError("build")

giteaUtils.updateStatus(Map args)

Update commit status with full control.

giteaUtils.updateStatus(
    context: "build",
    state: "success",      // success, pending, failure, error
    message: "Build passed",
    giteaUrl: "https://git.kodeniks.com",  // optional override
    credentialsId: "kodeniks-gitea-token"       // optional override
)

---

awsUtils

AWS CLI operations.

awsUtils.assumeRole(Map args)

Assume an IAM role.

awsUtils.assumeRole(
    roleArn: "arn:aws:iam::123456789012:role/MyRole",
    sessionName: "jenkins-deploy"
)

awsUtils.getCallerIdentity(Map args)

Get current AWS identity.

def identity = awsUtils.getCallerIdentity(
    jenkinsAwsCredentialsId: "aws-credentials",
    region: "ca-central-1"
)

awsUtils.describeStacks(Map args)

Describe CloudFormation stacks.

def stacks = awsUtils.describeStacks(
    jenkinsAwsCredentialsId: "aws-credentials",
    region: "ca-central-1",
    stackName: "my-stack"
)

---

spicyUtils

Pipeline utility functions.

spicyUtils.stageWithFailure(name, closure)

Run a stage that sets Gitea status on failure.

spicyUtils.stageWithFailure("Build") {
    sh "npm run build"
}

spicyUtils.withRetry(Map args, closure)

Retry a block with exponential backoff.

spicyUtils.withRetry(maxAttempts: 3, delay: 5) {
    sh "flaky-command"
}

---

accounts

Multi-account configuration management.

accounts.get()

Get all account configurations.

def allAccounts = accounts.get()

def prodAccount = allAccounts.SPICY_CA_CENRAL_1_PROD
def devAccount = allAccounts.SPICY_CA_CENRAL_1_DEV

Account Object Properties

Property	Description
accountId	AWS Account ID
region	AWS Region
jenkinsAwsCredentialsId	Jenkins credential ID
vpcStackName	Default VPC stack name
ecsClusterStackName	Default ECS cluster stack name

Available Accounts

Key	Description
SPICY_CA_CENRAL_1	Base account
SPICY_CA_CENRAL_1_DEV	Development environment
SPICY_CA_CENRAL_1_SANDBOX	Sandbox environment
SPICY_CA_CENRAL_1_QA	QA environment
SPICY_CA_CENRAL_1_STAGING	Staging environment
SPICY_CA_CENRAL_1_PROD	Production environment

---

manualApproval

Manual approval gates for pipelines.

manualApproval(Map args)

Request manual approval before proceeding.

manualApproval(
    message: "Deploy to production?",
    submitter: "admin,deployers",     // optional: allowed approvers
    timeout: 24,                       // optional: hours to wait
    timeoutUnit: "HOURS"              // optional: HOURS, MINUTES, DAYS
)

---

spicyDefaults

Apply default pipeline configuration.

spicyDefaults(Map args)

Merge defaults into pipeline arguments.

def call(Map args) {
    args = spicyDefaults(args)
    // args now has default pipelineProperties, etc.
}

Default properties applied:

• Build discarder (keep 10 builds)
• Disable concurrent builds
• GitHub project URL (if applicable)