Jenkins Pipeline Tutorial: How to Create and Run a Pipeline
Create a Jenkins Pipeline with a Jenkinsfile, connect it to a job, run your first build, and troubleshoot common setup errors.
A Jenkins Pipeline is a workflow defined as code and run by Jenkins. The recommended starting point is a Declarative Jenkinsfile committed at the root of your project repository. Create a Pipeline job that loads that file from source control, then start a build and inspect its stage results and console output. Jenkins also lets you enter a Pipeline directly in the classic UI. Jenkins recommends keeping the Jenkinsfile in source control, where it can be reviewed and versioned with the project.
1. Check prerequisites and choose where to define the Pipeline
You need Jenkins 2.x or later and the Pipeline plugin. The plugin is included among the suggested plugins in Jenkins’ post-installation setup. You do not need to know Groovy to begin with Declarative syntax; start with the structured example below.
| Approach | Good fit | Where the definition lives |
|---|---|---|
| Jenkinsfile in source control | Projects whose pipeline should be reviewed and versioned alongside application code | A file named Jenkinsfile, usually at the repository root |
| Classic UI Pipeline script | A quick first exercise or a simple Pipeline managed in Jenkins | Jenkins stores the script in its home directory |
The syntax is the same either way. Source control is usually the more repeatable choice for a project. Jenkins’ getting-started guide documents both routes.
2. Write a minimal Jenkinsfile
Create a plain text file named exactly Jenkinsfile (no extension) at the root of your repository and add:
pipeline {
agent any
stages {
stage('Hello') {
steps {
echo 'Hello from Jenkins Pipeline'
}
}
}
}This first version uses echo, so it does not depend on a build tool being installed on the agent.
pipelineencloses a Declarative Pipeline.agent anyasks Jenkins to allocate an available agent and workspace. An agent is the machine or execution environment where the steps run.stagesgroups the main units of work.stage('Hello')names one unit of work for people reading the run.stepscontains the operations Jenkins executes.echowrites a message to the build’s console output.
The required Declarative structure includes a top-level pipeline, an agent, stages, and steps inside stages. See the official Pipeline syntax reference for the full grammar and directives.
3. Create a Pipeline job and run it
Recommended: load the Jenkinsfile from source control
- Commit the
Jenkinsfileto your project’s repository. - In Jenkins, create a new item and choose a Pipeline job. Configure its definition to load from source control, then provide the repository and branch details requested by your Jenkins installation.
- Set the script path to
Jenkinsfileif the file is at the repository root. If you put it elsewhere, use its repository-relative path. - Save the job, open it, and start a build using the available build action (often labeled Build Now).
- Open the run and inspect the stage view and console output. The Hello stage should print the message.
For repository and branch discovery across a project, Jenkins documents the repository-root Jenkinsfile pattern in its Pipeline as Code guide. Exact labels can vary with Jenkins version and installed plugins.
Alternative: enter the script in the classic UI
- From the Jenkins Dashboard, choose New Item, enter a job name, and select a Pipeline project.
- In the Pipeline section of the job configuration, enter the same Declarative script in the script editor.
- Save the job, then start a build and inspect its console output.
A UI-defined script is stored by Jenkins itself. For a project that will evolve, source control gives the team a reviewable history of pipeline changes.
4. Add project commands and useful stages
Once the Hello run works, replace or extend it with commands your project actually supports. The following is a structural example, not a claim that every agent has make or that every repository produces a JAR:
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'make'
}
}
stage('Test') {
steps {
sh 'make test'
}
}
}
}sh runs a Unix/Linux shell command. On a Windows agent, use the bat step with a Windows command instead. A command returning a nonzero exit code fails the Pipeline by default, so a failed build or test prevents later stages from proceeding normally.
A common continuous-delivery example has Build, Test, and Deploy stages, but deployment is not required for every project. Add only stages that correspond to real steps in your delivery process. Jenkins demonstrates that sequence in its deployment tutorial.
For example, if the build really creates matching JAR files and you want basic Jenkins-side retention, you can archive them:
stage('Build') {
steps {
sh 'make'
archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true
}
}Adjust the command and artifact pattern to the project. Jenkins notes that artifact archiving is basic retention and is not a replacement for an external artifact repository.
5. Choose Declarative syntax, agents, and configuration
Declarative or Scripted
Declarative Pipeline is structured and opinionated, making it a practical first choice. Scripted Pipeline uses a limited form of Groovy and gives more direct flow control, including constructs such as conditionals, loops, and exception handling. Use Scripted when a concrete workflow needs that flexibility; the official Pipeline overview and syntax reference describe both.
One agent or per-stage agents
agent any requests any available configured agent for the whole Pipeline. You can target a configured agent label instead. A top-level agent none avoids allocating one agent for the whole run, but then each stage that runs work must define its own agent. This can be useful when stages need different environments, at the cost of explicitly configuring each stage’s execution environment.
Common Declarative directives
The syntax reference covers more than the starter example. Add these only when the job needs them:
| Directive or section | Purpose |
|---|---|
environment |
Define environment values for a Pipeline or stage. |
options |
Set Pipeline behaviors and options supported by installed plugins. |
parameters |
Declare inputs for a run. |
triggers |
Configure supported ways to start runs automatically. |
tools |
Select configured tools such as Maven, JDK, or Gradle. |
when |
Control whether a stage runs based on a condition. |
post |
Define actions associated with Pipeline completion conditions. |
input |
Pause for human input or approval when the workflow requires it. |
Available steps and directives depend on the Jenkins and plugin configuration. Jenkins’ in-product Snippet Generator and Directive Generator can help produce syntax for the installed setup.
Credentials and untrusted input
Use Jenkins credentials facilities for secrets; do not print secrets to logs. Keep user-controlled input out of interpolated shell command strings: interpolation can turn input into executable shell content. For less common credential types, Jenkins recommends its Snippet Generator to create appropriate Pipeline syntax. See Using a Jenkinsfile for credential handling guidance.
6. Troubleshoot common first-run failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Jenkins rejects the Pipeline before a stage starts | Required Declarative structure is missing, braces do not match, or a directive is in the wrong section. | Compare the file with the minimal example; ensure pipeline, agent, stages, stage, and steps are nested correctly. |
| Job cannot find the Jenkinsfile | The file name or configured script path does not match its repository location. | Name it Jenkinsfile and set the job’s script path relative to the repository; check that the file was committed to the branch the job reads. |
| Pipeline has no agent or cannot allocate an executor | No usable agent matches the configuration, or a stage using top-level agent none lacks its own agent. |
Check that an appropriate agent is configured and available; specify a matching label or add an agent to each stage that runs work. |
sh is unavailable or command syntax fails on Windows |
The example uses a Unix/Linux shell step on a Windows agent. | Use bat with the appropriate Windows command, or run the stage on a compatible Unix/Linux agent. |
| Build stops at a shell step | The command is missing, not executable, or returned a nonzero exit code. | Read the console output, verify the command exists in the agent environment and workspace, and fix the underlying command failure. Do not assume tools installed on the controller are present on the agent. |
| Artifact archive is empty | The build did not create files matching the include pattern or created them at another path. | Check the workspace and adjust the pattern to the project’s actual output location. |
| Credential value appears in command output or behavior is unsafe | A secret may have been printed, or untrusted input was interpolated into a shell command. | Remove secret logging, use Jenkins credential binding patterns, and avoid interpolating untrusted values into shell command text. |
7. Reliability, performance, and cost considerations
- Execution capacity: Pipeline steps need an available agent and workspace. Agent labels and stage-level agents let the job target the environment that has the required operating system and tools.
- Failure behavior: A nonzero shell exit fails the run by default. Make build and test commands report failure accurately so later work does not treat a broken result as success.
- Repeatability: A versioned Jenkinsfile makes pipeline changes reviewable and keeps the definition with the project. Keep commands and required tools explicit for the agents that execute them.
- Artifacts: Jenkins archiving is useful for basic build output retention and reporting. Use an external artifact repository when that is required by the project.
- Controller load: Run build work on configured agents and keep Pipeline code focused on orchestration. The amount of work, agent capacity, plugins, and job configuration determine actual run time; this tutorial does not imply a benchmark.
- Cost: Jenkins Pipeline itself is a plugin feature. Infrastructure, agent capacity, storage, and operational maintenance still have costs that depend on how Jenkins is hosted and used.
Or skip the browser setup
If a build or release workflow also needs website screenshots, ScreenshotNeo provides a one-request screenshot API. This is separate from creating the Jenkins Pipeline, and can be called from a stage or another service:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. See ScreenshotNeo for product details. Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
Does a Jenkinsfile have to be written in Groovy?
Pipeline syntax is Groovy-like. Declarative syntax provides a structured DSL, so a beginner can use the basic form without first learning general-purpose Groovy.
Can I start a Pipeline without connecting source control?
Yes. Enter a Pipeline script in a classic UI Pipeline job. A Jenkinsfile in source control is the more reviewable approach for an ongoing project.
Can a Pipeline run on more than one operating system?
Yes, if Jenkins has appropriate configured agents and stages are assigned to them. Match each stage’s commands to its agent operating system.
Where do I find syntax for an installed plugin step?
Use Jenkins’ Pipeline Snippet Generator in the classic UI, and consult the installed step’s documentation. Jenkins’ Pipeline Steps reference also catalogs built-in and plugin-provided steps.
