The Jenkinsfile
A Jenkinsfile is a text file, checked into your repository, that contains your pipeline definition.
A Jenkinsfile is a plain-text file named exactly Jenkinsfile that holds your pipeline definition. It normally lives in the root of your Git repository, right next to your source code.
Pipeline as code
Keeping the pipeline in your repo brings big benefits:
- Every change to the build process is tracked in version control.
- Different branches can have different pipelines.
- Code review applies to your CI/CD process too.
- You can roll back a broken pipeline like any other bad commit.
How Jenkins finds it
When you create a Pipeline job (or a Multibranch pipeline), you tell Jenkins to read the pipeline definition from SCM. Jenkins then checks out your repo and runs the Jenkinsfile it finds there.
Example
# A typical repository layout:
#
# my-app/
# |-- Jenkinsfile <-- pipeline definition
# |-- src/
# |-- package.json
# +-- README.md
#
# Jenkins checks out the repo and runs the Jenkinsfile.When to use it
- A team stores the Jenkinsfile in the root of their Git repo so Jenkins automatically picks it up without any UI configuration.
- A code reviewer can see the CI/CD pipeline change in the same pull request as the feature code that requires it.
- An engineer runs a linting check on the Jenkinsfile in CI to catch syntax errors before they break the build.
More examples
Jenkinsfile at repo root
A standard Jenkinsfile committed at the repository root; Jenkins finds it automatically via multibranch or SCM pipeline config.
// File: Jenkinsfile (at repository root)
pipeline {
agent any
stages {
stage('Checkout') { steps { checkout scm } }
stage('Build') { steps { sh 'npm install && npm run build' } }
stage('Test') { steps { sh 'npm test' } }
}
}Validate Jenkinsfile via REST
Sends the Jenkinsfile to Jenkins' pipeline validator endpoint to check for syntax errors.
# Lint a Jenkinsfile before committing
curl -X POST \
http://localhost:8080/pipeline-model-converter/validate \
--user admin:$TOKEN \
-F "jenkinsfile=<Jenkinsfile"Jenkinsfile with shared library import
Imports a versioned shared library at the top of the Jenkinsfile to reuse custom pipeline steps.
// File: Jenkinsfile
@Library('my-shared-lib@main') _
pipeline {
agent any
stages {
stage('Build') {
steps { myBuildStep() } // from shared library
}
}
}
Discussion