How to Write Jenkinsfile: Syntax, Example, and Tips

A Jenkinsfile is a text file that defines a Jenkins pipeline using Groovy syntax. It contains stages and steps to automate build, test, and deploy tasks. Write it using either Declarative or Scripted pipeline syntax inside your project repository.

Syntax

A Jenkinsfile uses Groovy-based syntax to define pipelines. The two main types are Declarative and Scripted pipelines.

• Declarative Pipeline: Uses a simple, structured format with pipeline, agent, stages, and steps.
• Scripted Pipeline: Uses Groovy code with node blocks and is more flexible but complex.

Each pipeline has stages representing phases like build, test, and deploy. Steps are commands or scripts run inside stages.

groovy

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Test') {
            steps {
                echo 'Testing...'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }
}

Example

This example shows a simple Declarative Jenkinsfile that prints messages in three stages: Build, Test, and Deploy. It runs on any available agent.

groovy

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building the project...'
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests...'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying application...'
            }
        }
    }
}

Output

[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/example
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Build)
[Pipeline] echo
Building the project...
[Pipeline] }
[Pipeline] stage
[Pipeline] { (Test)
[Pipeline] echo
Running tests...
[Pipeline] }
[Pipeline] stage
[Pipeline] { (Deploy)
[Pipeline] echo
Deploying application...
[Pipeline] }
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline

Common Pitfalls

Common mistakes when writing Jenkinsfiles include:

• Forgetting to specify agent, causing the pipeline to fail to run.
• Using Scripted syntax inside Declarative pipelines without proper syntax.
• Not wrapping steps inside steps block in Declarative pipelines.
• Incorrect indentation or missing braces causing syntax errors.

Always validate your Jenkinsfile syntax in Jenkins or with a linter before committing.

groovy

/* Wrong: Missing steps block in Declarative pipeline stage */
pipeline {
    agent any
    stages {
        stage('Build') {
            // echo 'Building...' is invalid here without steps block
        }
    }
}

/* Right: Steps block included */
pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Quick Reference

Here is a quick reference for common Jenkinsfile keywords:

Keyword	Description
pipeline	Defines the entire pipeline script
agent	Specifies where the pipeline or stage runs (e.g., any, label)
stages	Groups all the stages in the pipeline
stage	Defines a single phase like Build, Test, or Deploy
steps	Contains the commands or scripts to run in a stage
echo	Prints a message to the Jenkins console output

Key Takeaways

Write Jenkinsfile using Declarative syntax with pipeline, agent, stages, and steps blocks.

Always include an agent to specify where the pipeline runs.

Wrap commands inside steps blocks in Declarative pipelines.

Validate Jenkinsfile syntax to avoid common errors.

Use stages to organize your build, test, and deploy phases clearly.