Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 40 ยท Meet Jenkins

Your First Job: Freestyle Projects

Create your first Jenkins freestyle job: add a shell build step, run it, read the console output, understand build numbers and workspaces, and see its limits.

The simplest thing you can build in Jenkins is a freestyle project: a job configured through web forms. You give it a name, tell it where the code is, add one or more build steps, press Build Now, and Jenkins runs the steps and records what happened. It is the quickest way to see Jenkins do something real, and it teaches the vocabulary (build number, workspace, console output) that carries over to pipelines.

You will also learn why teams outgrow freestyle jobs, which is the reason the next chapter exists. The real job creation happens in a Jenkins server, so the steps below are described in words and read-only snippets, and a stand-in written in JavaScript shows what a runner does with your build steps.

Create a freestyle job

New Item Pick a name and "Freestyle project".
Add a step Build Steps, then Execute shell.
Build Now Jenkins queues and runs it.
Read the log Open the build, then Console Output.

The whole loop takes about two minutes.

1 / 2

Creating the job

In the Jenkins dashboard:

  1. Click New Item.
  2. Enter a name such as hello-jenkins. Use letters, digits and dashes; avoid spaces, because the name becomes part of URLs and folder names.
  3. Choose Freestyle project and click OK.

You arrive on the configuration page, organised into tabs or sections. The ones you will use most:

  • General: description, discard old builds, parameters (extra inputs to the build).
  • Source Code Management: where the code is (Git URL, branch, credentials). Leave it as None for your first job.
  • Build Triggers: what starts the job (a schedule, a webhook, another job). Leave it empty and start builds by hand.
  • Build Environment: options such as timeouts and secret masking.
  • Build Steps: the actual work.
  • Post-build Actions: things that happen after the steps, such as archiving files, publishing test results and sending email.

Adding a shell build step

Under Build Steps, click Add build step and choose Execute shell (on Windows agents, Execute Windows batch command). A text box appears. Type a few commands:

Terminal
echo "Hello from build $BUILD_NUMBER of $JOB_NAME"
date
pwd
ls -la
echo "Tests passed" > result.txt

Click Save. BUILD_NUMBER and JOB_NAME are environment variables that Jenkins sets for every build. You will meet more of them in Environment Variables and Parameters.

A detail that matters: Jenkins runs a shell step with the -xe options. The -x flag makes the shell print each command before running it (that is why the log shows lines starting with +), and -e stops the step at the first command that fails. So a step succeeds only if every command in it returns exit code 0. This is exactly how Jenkins decides whether a step passed: exit code 0 means success, anything else means failure.

Running it and reading the log

Click Build Now. A new entry, #1, appears in Build History, first with a flashing ball and then a solid one. Click the number and then Console Output. You will see something like this (read-only):

TEXT
Started by user ana
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/hello-jenkins
[hello-jenkins] $ /bin/sh -xe /tmp/jenkins8123.sh
+ echo 'Hello from build 1 of hello-jenkins'
Hello from build 1 of hello-jenkins
+ date
Tue Mar  3 09:15:02 UTC 2026
+ pwd
/var/jenkins_home/workspace/hello-jenkins
+ ls -la
total 12
-rw-r--r-- 1 jenkins jenkins 13 Mar  3 09:15 result.txt
+ echo 'Tests passed'
Finished: SUCCESS

Click Build Now again and you get #2, with BUILD_NUMBER equal to 2. Build numbers only grow; they are never reused, even if you delete builds. They give every run a permanent, short name you can quote in chat ("fixed in #57").

The workspace

The line Building in workspace ... names a folder on the agent, the workspace. It is where Jenkins checks out your code and where your commands run; the files from the last build usually stay there. Open the job page and click Workspace to browse it. Two consequences:

  • Files from build #1 can still be there in build #2. A script that only works because of leftovers is a flaky script. Either start each build with a cleanup or use the Delete workspace before build starts option.
  • Workspaces use disk space on the agent. Plan for it.

Jenkins also creates a separate folder for each build's record (log and metadata) under JENKINS_HOME/jobs/<job>/builds/<number>. The workspace is scratch space; the record is history. See Jenkins Architecture: Controller, Agents and Executors.

Making a build fail on purpose

Change the shell step to include a failing command:

Terminal
echo "Starting"
test -f missing-file.txt
echo "This line never runs"

Because of -e, the step stops at test -f missing-file.txt (which returns 1), the build is marked FAILURE, and the dashboard ball turns red. Seeing a deliberate failure early teaches you how errors surface.

A stand-in step runner

Jenkins hands your script to a real shell, which we cannot do in a browser. The stand-in below models what the runner does around it: it numbers the build, runs a list of steps in order, prints each command with a + prefix like sh -x, stops at the first failing step, and records a result. Each "command" is a small JavaScript function that returns an exit code.

JS A stand-in freestyle build runner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Build #1 runs every step and finishes with SUCCESS. Build #2 stops at the failing test -f and never reaches the last echo. The build numbers keep counting up. Everything here is a model of the behaviour you read about above, not Jenkins itself.

Parameters, triggers and post-build actions in one minute

You can extend a freestyle job without leaving the forms:

  • This project is parameterized adds inputs (text, choice, boolean) that your shell step reads as variables.
  • Build Triggers can poll Git on a schedule or react to a webhook; see Triggers: Webhooks, Polling and Schedules.
  • Post-build Actions such as Archive the artifacts keep chosen files (like result.txt) after the workspace is cleaned. We return to this in Artifacts, Stash and Fingerprints.

Why freestyle does not scale

Freestyle jobs are fine for a first experiment and a few simple tasks. As soon as a team depends on them, the weaknesses show:

  • The job lives in the server, not with the code. A change to the build means clicking in a form, and the code and its build instructions drift apart.
  • No review, no history. Nobody can see who changed a step or roll it back, unless you add extra tooling.
  • Copy and paste. Ten similar projects mean ten forms to keep in sync.
  • Limited flow. Parallel work, conditions and stages that survive a restart are awkward or impossible.
  • Plugin-driven options. Much of the form comes from plugins, so the job's behaviour is harder to read than a single text file.

The answer is Pipeline as code: a Jenkinsfile stored in your repository. It is the subject of the next chapter, beginning with Pipeline Basics and the Jenkinsfile.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does Jenkins decide whether a shell build step succeeded?

    Jenkins treats exit code 0 as success. With -e, the shell also stops at the first failing command, so the step fails.
  2. 2. What happens to a build number when you delete build #5?

    Build numbers are permanent identifiers that only grow, which is why they are safe to quote.
  3. 3. What is the workspace?

    The workspace is the working directory for the build. Files may persist between builds unless you clean it.
  4. 4. Which is a real weakness of freestyle jobs for a team?

    Pipeline as code solves this by keeping the build definition in version control with the project.

Summary

  • A freestyle project is a web-form job with source, triggers, build steps and post-build actions.
  • A shell step succeeds only when every command exits with 0; Jenkins shows the commands with a + prefix in the log.
  • Build numbers only increase; the workspace is scratch space that may keep files between builds.
  • Freestyle jobs are quick to start but hard to review, copy and evolve; teams move to pipelines.

Continue with Pipeline Basics and the Jenkinsfile.