How to Create a New Build Job in Jenkins Freestyle Project

By : Thomas Hamilton Thomas Hamilton
Hours Updated

⚡ Smart Summary

Jenkins Freestyle Project is a repeatable build job that bundles source-code checkout, build steps and post-build actions into one configurable task, created entirely through the Jenkins web interface without writing pipeline code.

  • 🔘 Definition: A freestyle job is Jenkins’ general-purpose project type, configured through forms rather than a Jenkinsfile.
  • ☑️ Prerequisites: A running Jenkins controller, a JDK on the build agent, the Git plugin and a reachable repository are required first.
  • ✅ Ten steps: Log in, create a New Item, name it, set the repository, add a build step, save, build and read the console output.
  • 🧪 Worked example: A HelloWorld project pulled from GitHub compiles with javac and runs with java inside a Windows batch build step.
  • 🛠️ Configuration map: Six form sections — General, Source Code Management, Build Triggers, Build Environment, Build Steps and Post-build Actions — cover every option.
  • ⚙️ Scope limit: Freestyle jobs suit single-task automation; multi-stage delivery work belongs in a version-controlled Pipeline job instead.
Read More

How to Create a New Build Job in Jenkins Freestyle Project

What is a Jenkins Freestyle Project?

Jenkins Freestyle Project is a repeatable build job, script, or pipeline that contains steps and post-build actions. It is an improved job or task that can span multiple operations. It allows you to configure build triggers and offers project-based security for your Jenkins project. It also offers plugins to help you build steps and post-build actions.

The types of actions you can perform in a Jenkins build step or post-build action are quite limited. There are many standard plugins available within a Jenkins Freestyle Project to help you overcome this problem.

The diagram below places the freestyle job inside the wider continuous integration loop, from source checkout through to the post-build actions that report the result.

Steps to create a job in Jenkins Freestyle Project
How to Create a Job in Jenkins

Prerequisites for Creating a Jenkins Freestyle Job

Before the ten steps below will work end to end, four things have to be in place. Missing any one of them is the usual reason a first freestyle build fails with a red ball rather than a blue one.

  • A running Jenkins controller. Jenkins listens on port 8080 by default. If Jenkins is not running yet, follow the installation walkthrough first.
  • A JDK on the machine that runs the build. The worked example compiles Java, so javac must be on the PATH of the controller or agent that executes the job. Confirm this with a one-line java -version build step before adding anything else.
  • The Git plugin. The Git option only appears under Source Code Management once the plugin is installed, through Manage Jenkins > Plugins.
  • A reachable repository. A public HTTPS URL needs no credentials. A private repository needs a credential stored in Jenkins first, otherwise the checkout fails during the very first build.

An account with the Job/Create permission is also needed — on a fresh single-user Jenkins the admin account already has it.

How to Create a New Build Job in Jenkins

The freestyle build job is a highly flexible and easy-to-use option. You can use it for any type of project; it is easy to set up, and many of its options appear in other build jobs. Below is a step by step process to create job in Jenkins.

Step 1) Login to Jenkins

To create a Jenkins freestyle job, log on to your Jenkins dashboard by visiting your Jenkins installation path. Usually, it will be hosted on localhost at http://localhost:8080 If you have installed Jenkins in another path, use the appropriate URL to access your dashboard as shown in the below Jenkins job creation example.

Jenkins dashboard reached at the Jenkins installation path after logging in

Step 2) Create New Item

Click on “New Item” at the top left-hand side of your dashboard. The screenshot below shows where that link sits.

New Item link at the top left-hand side of the Jenkins dashboard

Step 3) Enter Item details

In the next screen,

  1. Enter the name of the item you want to create. We shall use the “Hello world” for this demo.
  2. Select Freestyle project
  3. Click Okay

Item name box with Freestyle project selected before clicking Okay

Step 4) Enter Project details

Enter the details of the project you want to test. The configuration page that opens is shown below.

Project details entered on the Jenkins freestyle job configuration page

Step 5) Enter repository URL

Under Source Code Management, Enter your repository URL. We have a test repository located at https://github.com/kriru/firstJava.git

Source Code Management section with the Git test repository URL entered

It is also possible for you to use a local repository.

If your GitHub repository is private, Jenkins will first validate your login credentials with GitHub and only then pull the source code from your GitHub repository.

RELATED ARTICLES

Step 6) Tweak the settings

Now that you have provided all the details, it is time to build the code. Tweak the settings under the build section to build the code at the time you want. You can even schedule the build to happen periodically, at set times.

Under build,

  1. Click on “Add build step”
  2. Click on “Execute Windows batch command” and add the commands you want to execute during the build process.

The drop-down that lists the available build steps looks like this.

Add build step drop-down opened on the freestyle job configuration page

⚠️ Version note: recent Jenkins releases label this area Build Steps rather than Build, and on Linux or macOS agents the equivalent option is Execute shell. The button is still called Add build step.

Here, I have added the java commands to compile the java code.

I have added the following windows commands:

javac HelloWorld.java
java HelloWorld

The command box with those two lines entered is shown below.

Execute Windows batch command box holding the javac and java commands

Step 7) Save the project

When you have entered all the data,

  1. Click Apply
  2. Save the project.

Step 8) Build Source code

Now, in the main screen, Click the Build Now button on the left-hand side to build the source code.

Build Now button on the left-hand side of the freestyle project screen

Step 9) Check the status

After clicking on Build now, you can see the status of the build you run under Build History.

Build History panel showing the status of the freestyle build that was run

Step 10) See the console output

Click on the build number and then Click on console output to see the status of the build you run. It should show you a success message, provided you have followed the setup properly as shown in the below Jenkins create new job example.

Console output screen showing the success message for the finished build

In sum, we have executed a HelloWorld program hosted on GitHub. Jenkins pulls the code from the remote repository and builds continuously at a frequency you define.

Jenkins Freestyle Project Configuration Sections Explained

The walkthrough above touches only the fields the HelloWorld example needs. The configuration page itself is divided into six form sections, and knowing what each one owns makes the remaining options far easier to find.

Section What it controls Typical setting
General Job description, discarding old builds, parameters, and whether the job runs on a specific agent Description plus a build-retention limit
Source Code Management Which repository to check out and with which credential and branch Git, an HTTPS URL, branch */master or */main
Build Triggers What starts the build automatically Poll SCM, build periodically, or a webhook from GitHub
Build Environment Wrappers applied around the whole build Delete workspace before the build starts; add timestamps to the console log
Build Steps The commands that do the work, run top to bottom Execute Windows batch command, or Execute shell
Post-build Actions What happens after the steps finish, whatever the result Archive the artifacts, publish a test report, send an email

Two habits save a lot of debugging later. Add build steps in the order they must run, because Jenkins processes them top to bottom and stops at the first failure. Then archive whatever the build produces as a post-build action, because the workspace is reused by the next build while archived artifacts are kept per build number.

Freestyle Project vs Pipeline: Which Should You Use?

Freestyle is not the only project type on the New Item screen, and it is not always the right one. The table below sets it against a Pipeline job on the points that decide most real choices.

Point of comparison Freestyle project Pipeline
How it is defined Web forms stored in the job’s config.xml on the controller A Jenkinsfile committed with the application code
Change history Held by Jenkins, outside your repository Reviewed and versioned like any other source file
Stages and parallel work A single flat list of build steps Named stages, parallel branches, and a stage view
Learning curve No scripting needed Requires the declarative pipeline syntax
Best fit One compile, one script, one scheduled task, or learning Jenkins Multi-stage build, test and deploy flows across environments

A practical rule: reach for freestyle while the job is a single task and you are still learning the tool, and move the work into a CI/CD pipeline as soon as it grows a second stage or needs to be reviewed alongside the code. Teams that pair Jenkins with build tools often reach that point quickly — a Maven and Selenium setup is a common trigger for the switch, and the same reasoning applies to any automation testing suite that runs in several phases.

FAQs

The console output names the cause. The three common ones are javac missing from the agent PATH, a private repository with no stored credential, and a wrong branch name. Fix the reported line, then run Build Now again.

Open Build Triggers and tick Build periodically, then enter cron syntax such as H 2 * * * for a nightly run. The H spreads load across the hour. Poll SCM uses the same syntax but only builds when the repository changed.

Choose Execute shell from the Add build step menu rather than Execute Windows batch command. The option shown depends on the operating system of the controller or agent the job is tied to, not on your own machine.

Store the token or SSH key once under Manage Jenkins > Credentials, then pick it from the Credentials drop-down in the Source Code Management section. Jenkins validates it before the checkout, so a bad credential fails the build at once.

Machine learning tools read console logs and cluster repeated failures, separating a genuine compile error from a flaky agent or a timeout. That triage points you at the one line that matters instead of scrolling a long log by hand.

GitHub Copilot drafts the batch or shell script inside a build step, and its CLI can summarise a failed console log. It cannot click through the configuration form, so review every generated command before saving.

Add Archive the artifacts as a post-build action and give it a pattern such as **/*.class. Archived files are stored per build number, so they survive the workspace being reused or cleaned by the next run.

Each job lives in JENKINS_HOME/jobs/<job-name>, with the form settings in config.xml and each run under builds/. Backing up that folder is enough to move or restore the job.

Summarize this post with: