Working with Input and Approvals

1. Using Input Step for Approvals

Property	Values	Description
message	`string`	Message to display to the user for approval
id	`string`	Unique identifier for the input step (optional)
ok	`string`	Text for the "OK" button (default: "OK")
submitter	`string`	Username of the user who submitted the input (optional)
parameters	`list`	List of parameters to collect from the user (optional)

Example: Basic Input Step Usage

pipeline {
    agent any
    stages {
        stage('Approve Deployment') {
            steps {
                script {
                    def userInput = input(
                        message: 'Approve deployment to production?',
                        ok: 'Deploy',
                        submitter: 'admin'
                    )
                }
            }
        }
    }
}

Example: Input Step with Parameters

pipeline {
    agent any
    stages {
        stage('Approve Deployment') {
            steps {
                script {
                    def userInput = input(
                        message: 'Approve deployment to production?',
                        parameters: [
                            [
                                name: 'environment',
                                type: 'ChoiceParameterDefinition',
                                choices: ['dev', 'staging', 'prod']
                            ]
                        ]
                    )
                }
            }
        }
    }
}

Note: The input step will pause the pipeline and wait for user interaction in the Jenkins UI.

Warning: If no user interacts with the input step within a set timeout, the pipeline will fail.

2. Configuring Input Parameters

Parameter	Type	Description	Default
name	`string`	Unique identifier for the input parameter	N/A
message	`string`	Message displayed to the user when prompting for input	`Enter value for ${name}`
defaultValue	`string`	Default value if user does not provide one	`null`
regex	`string`	Regular expression to validate input	`null`
regexMessage	`string`	Error message if input does not match regex	`Input does not match required format`

Example: Declaring Input Parameters in Pipeline Script

pipeline {
    agent any
    stages {
        stage('User Input') {
            steps {
                script {
                    def userInput = input(
                        message: 'Please enter the environment name',
                        parameters: [
                            string(name: 'ENVIRONMENT', message: 'Environment to deploy to', defaultValue: 'staging')
                        ]
                    )
                }
            }
        }
    }
}

Note: Input parameters are only available in scripted pipelines or within a script block in declarative pipelines.

3. Setting Input Timeout

Property	Values	Description
input.timeout	`300`	Timeout in seconds for input approval

Example: Setting Input Timeout

pipeline {
    agent any
    stages {
        stage('Approval') {
            steps {
                input(
                    message: 'Approve deployment to production',
                    timeout: 300
                )
            }
        }
    }
}

Note: The timeout value is specified in seconds. If not set, the default is 300 seconds (5 minutes).

4. Using Submitter Restrictions

Property	Description	Values	Notes
submitterRestriction.enabled	Enables or disables submitter restriction	`true` / `false`	Default: `false`
submitterRestriction.allowedUsers	List of users allowed to submit	Comma-separated list of Jenkins user IDs	Required if `submitterRestriction.enabled` is true
submitterRestriction.allowedGroups	List of groups allowed to submit	Comma-separated list of Jenkins group names	Optional, can be used in combination with users

Example: Configure Submitter Restrictions

pipeline {
    agent any
    stages {
        stage('Approval') {
            steps {
                input {
                    message 'Approve deployment to production'
                    submitterRestriction {
                        enabled = true
                        allowedUsers = ['admin', 'deployer']
                        allowedGroups = ['deployment-team']
                    }
                }
            }
        }
    }
}

Note: Submitter restrictions apply to the input step and are enforced at runtime. Users not in the allowed list will be blocked from submitting the input.

5. Using Checkpoint for Manual Gates

The checkpoint step in Jenkins allows you to pause a pipeline and require manual approval before continuing. This is useful for implementing manual gates in your CI/CD process.

Parameter	Description	Default	Example
name	Name of the checkpoint (used in UI)	None	`name: 'Approve deployment'`
message	Message to display to the user	None	`message: 'Please review and approve this deployment'`
unstable	Mark the build as unstable if not approved	false	`unstable: true`
timeout	Timeout in seconds for the checkpoint	None	`timeout: 3600`

Example: Basic Checkpoint Usage

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Manual Approval') {
            steps {
                checkpoint name: 'Approve deployment', message: 'Please review and approve this deployment'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }
}

Example: Checkpoint with Timeout

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Manual Approval') {
            steps {
                checkpoint name: 'Approve deployment', message: 'Please review and approve this deployment', timeout: 3600
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }
}

Note: The checkpoint step requires the Checkpoint Plugin to be installed.

Warning: If a checkpoint times out, the build will fail unless unstable: true is specified.

Key Features of Checkpoint

Pauses pipeline execution until manual approval
Supports timeout configuration
Can mark build as unstable on timeout
Provides a user-friendly UI for approval

6. Implementing Multi-Stage Approvals

Example: Pipeline with Multi-Stage Approval

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Approve Deployment') {
            input {
                message 'Deploy to Production?'
                parameters {
                    choice(
                        name: 'ENVIRONMENT',
                        choices: ['staging', 'production'],
                        description: 'Select environment for deployment'
                    )
                }
            }
            steps {
                echo "Deploying to ${params.ENVIRONMENT}"
            }
        }
        stage('Post-Deployment') {
            steps {
                echo 'Post-deployment tasks'
            }
        }
    }
}

Property	Description	Values	Notes
input	Defines input step for user approval	`input { ... }`	Must be placed inside a stage
message	Message displayed to user	`'Deploy to Production?'`	Can include dynamic values
parameters	Optional parameters for input	`parameters { choice(...) }`	Supports multiple parameter types

Key Concepts

Input steps pause pipeline execution until user provides approval
Approvals can include parameters for additional context
Approvals can be conditional based on environment or stage
Approvals support multi-stage workflows for complex deployments

Multi-Stage Approval Workflow

First stage completes successfully
User is prompted for approval with custom message
Optional parameters can be collected (e.g., environment selection)
Pipeline continues only after approval
Subsequent stages can also require approvals

7. Using Input with Credentials

Property	Description	Example
credentials	Credentials to be used in the input step	`credentials('my-credential')`
description	Description of the input step	`description('Enter your credentials')`

Example: Using Input with Credentials

pipeline {
    agent any
    stages {
        stage('Input with Credentials') {
            steps {
                script {
                    def input = input(
                        message: 'Please enter your credentials',
                        parameters: [
                            string(name: 'username', defaultValue: '', description: 'Enter your username'),
                            password(name: 'password', defaultValue: '', description: 'Enter your password')
                        ]
                    )
                    withCredentials([usernamePassword(credentialsId: 'my-credential', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
                        echo "Username: ${USER}"
                        echo "Password length: ${PASS.length()}"
                    }
                }
            }
        }
    }
}

8. Aborting on Timeout

Property	Values	Description
timeout.duration	`30`	Timeout duration in minutes
timeout.unit	`MINUTES`	Time unit for timeout (MINUTES, SECONDS, HOURS)
timeout.abort	`true`	Whether to abort the build on timeout

Example: Configuring Timeout in Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                timeout(time: 30, unit: 'MINUTES') {
                    sh 'echo "Building..."'
                }
            }
        }
    }
}

Note: If timeout.abort is set to false, the build will continue running even after timeout.

9. Using Milestone for Concurrency

Milestones in Jenkins are used to manage concurrency and ensure that only one build of a particular type can run at a time. They are particularly useful in scenarios where multiple builds might interfere with each other or when you want to enforce a specific order of execution.

Property	Description	Example
milestoneName	Name of the milestone to be used for concurrency control.	`build-concurrent`
proceed	Indicates whether to proceed with the build after acquiring the milestone.	`true`
timeout	Timeout in seconds to wait for the milestone to be acquired.	`30`

Example: Using Milestone in a Pipeline

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                milestone(1)
                echo 'Starting build'
                sh 'echo "Building..."'
            }
        }
    }
}

Note: Milestones are particularly useful in environments where multiple builds might run simultaneously and could interfere with each other, such as when deploying to the same environment or modifying shared resources.

Warning: If a milestone is not properly released, subsequent builds may hang indefinitely waiting for the milestone to be acquired.

10. Logging Input Decisions

Property	Description	Example
input.log	Logs input decisions to the build console	`input log: 'Build approved by user'`
input.timestamp	Includes timestamp in the log entry	`input timestamp: true`

Example: Logging Input Decision

pipeline {
    agent any
    stages {
        stage('Approval') {
            steps {
                script {
                    def decision = input(
                        id: 'approval',
                        message: 'Approve build?',
                        parameters: [
                            string(name: 'user', defaultValue: 'jenkins', description: 'User approving build')
                        ]
                    )
                    echo "Build approved by ${decision.user}"
                }
            }
        }
    }
}

Note: The input step logs the decision to the build console by default. You can customize the log message using the log parameter.