Before I ever wrote a Jenkinsfile, I started with Freestyle projects — Jenkins’ original, GUI-driven way of defining a job. Even though Pipelines have become the modern standard, Freestyle projects are still incredibly useful for simple tasks, quick automation, and for anyone just getting started with Jenkins. In this guide, I’ll walk through exactly how to create one, configure it properly, and use it effectively.
What Is a Freestyle Project?
A Freestyle project is Jenkins’ simplest job type. Instead of writing pipeline code, you configure everything — source code checkout, build steps, post-build actions — through a web form in the Jenkins UI. It’s straightforward, visual, and doesn’t require learning Groovy syntax, which makes it a great entry point for beginners.
Jenkins Architecture Recap
Regardless of job type, Jenkins always follows the same controller-agent model. When you create a Freestyle project, you’re essentially defining a job configuration that the controller stores, and when triggered, dispatches to an agent (or itself, if no agents are configured) for execution.
Step 1: Access the Jenkins Dashboard
Log into your Jenkins instance and, from the main dashboard, click “New Item” in the left sidebar.
Step 2: Name Your Project and Select Freestyle
Enter a name for your job (avoid spaces — use hyphens or underscores instead, e.g., my-first-freestyle-job). Select “Freestyle project” from the list of job types, then click OK.
Step 3: General Configuration
At the top of the configuration page, you can:
- Add a Description so teammates understand the job’s purpose.
- Check “Discard old builds” and set a retention policy (e.g., keep the last 20 builds) to avoid disk space bloat over time.
- Check “This project is parameterized” if you want the job to accept input values at build time (e.g., a string parameter for environment name, or a choice parameter for branch selection).
Example of adding a parameter:
- Click “Add Parameter” > “String Parameter”
- Name:
ENVIRONMENT - Default Value:
staging
Step 4: Source Code Management
Under this section, choose Git (assuming your code lives in a Git repository) and provide:
- Repository URL:
https://github.com/yourusername/your-repo.git - Credentials: Select or add credentials if the repo is private.
- Branch Specifier:
*/main(or whatever branch you want to build)
If your project doesn’t use version control at all, you can leave this as “None,” though I’d strongly recommend using Git for virtually any real project.
Step 5: Build Triggers
This section defines what causes the job to run:
- Build periodically: Cron-based scheduling (e.g.,
H 2 * * *for a nightly build). - Poll SCM: Periodically checks for repository changes.
- GitHub hook trigger for GITScm polling: Instant trigger via webhook (requires GitHub Plugin).
- Trigger builds remotely: Allows triggering via a specific authentication token and URL, useful for external system integration.
For a simple learning project, “Build periodically” or manual triggering (leaving this section empty and clicking “Build Now”) both work fine.
Step 6: Build Environment
Here you can configure options like:
- Delete workspace before build starts: Ensures a clean slate every run.
- Add timestamps to the console output: Useful for debugging timing issues.
- Use secret text(s) or file(s): Inject credentials as environment variables for this specific build.
Step 7: Build Steps
This is where the actual work happens. Click “Add build step” and choose from options like:
- Execute shell (Linux/macOS agents)
- Execute Windows batch command (Windows agents)
- Invoke Ant
- Invoke top-level Maven targets
Example shell build step:
echo "Starting build for environment: $ENVIRONMENT"
npm install
npm run build
npm test
You can chain multiple build steps, and Jenkins executes them sequentially, stopping if any step returns a non-zero exit code (unless configured otherwise).
Step 8: Post-build Actions
After the build steps run, you can configure:
- Archive the artifacts: Save specific files (e.g.,
dist/**) so they’re downloadable from the build page. - Publish JUnit test result report: Point to your test output XML files for visual pass/fail reporting.
- Email notifications: Alert specific recipients on build failure or status change.
- Trigger parameterized build on other projects: Chain this job into another one after completion.
Example artifact archiving pattern: build/**/*.jar or dist/**.
Step 9: Save and Run
Click Save, then click “Build Now” from the job’s page to trigger your first build manually. You’ll see the build appear in the Build History panel; click it to view the Console Output and watch your build steps execute in real time.
Freestyle vs Pipeline: When to Use Which
I generally recommend Freestyle projects for:
- Quick, one-off automation tasks
- Simple builds that don’t need complex branching logic
- Teams or individuals just learning Jenkins for the first time
And Pipeline (Jenkinsfile-based) projects for:
- Anything involving multiple sequential or parallel stages
- Projects where you want your build configuration version-controlled alongside your code
- Complex conditional logic, approval gates, or integration with many external systems
That said, Freestyle projects remain fully supported and are still widely used for simpler automation needs.
Real-World Example: A Simple Notification Job
Here’s a practical Freestyle project I’ve set up before — a job that checks a website’s uptime and sends a Slack alert if it’s down:
Build Trigger: Build periodically — H/10 * * * * (every 10 minutes)
Build Step (Execute shell):
STATUS=$(curl -o /dev/null -s -w "%{http_code}\n" https://yourapp.com)
if [ "$STATUS" -ne 200 ]; then
echo "Site down! Status: $STATUS"
exit 1
fi
echo "Site is up. Status: $STATUS"
Post-build Action: Slack Notifications plugin configured to alert on failure.
Using the “Execute Windows Batch Command” Build Step
If your Freestyle project runs on a Windows agent, you’ll use “Execute Windows batch command” instead of “Execute shell.” The syntax follows standard Windows batch/CMD conventions:
echo Starting build for environment: %ENVIRONMENT%
dotnet restore
dotnet build --configuration Release
Parameters defined earlier (like ENVIRONMENT) are automatically exposed as environment variables, accessible with %PARAM_NAME% syntax on Windows or $PARAM_NAME on Linux/macOS.
Combining Multiple SCM Sources
Occasionally a Freestyle job needs to pull code from more than one repository — for example, your application code plus a shared configuration repository. Jenkins supports this through the “Multiple SCMs” option (via the Multiple SCMs Plugin), letting you check out several repositories into different subdirectories of the same workspace before running your build steps.
Adding Conditional Build Steps
For more advanced Freestyle configurations, the “Conditional BuildStep” plugin lets you run certain steps only if specific conditions are met — for instance, only running a deployment step if a particular parameter equals production, all through the UI without writing any Groovy.
Troubleshooting Common Freestyle Project Issues
- Build fails immediately with “No such file or directory”: Double-check your working directory assumptions; Jenkins runs build steps from the job’s workspace root by default.
- Git checkout fails: Verify credentials and repository URL; test SSH/HTTPS access from the agent machine directly if needed.
- Parameters not appearing: Confirm “This project is parameterized” is checked and parameters are saved before triggering a build.
- Artifacts not archiving: Make sure the file path pattern in “Archive the artifacts” actually matches generated files relative to the workspace.
Archiving Build History for Auditing
For teams in regulated industries, keeping a longer build history for audit purposes is often required. Rather than the default “Discard old builds” policy, you can configure a longer retention window or export build logs to external long-term storage using a post-build step that copies console output and artifacts to an archive location outside Jenkins itself.
Security Best Practices
- Avoid embedding secrets directly in shell build steps; use the Credentials Binding plugin instead.
- Restrict who can edit job configurations using Jenkins’ role-based access control.
- Regularly review and remove old, unused Freestyle jobs to reduce your attack surface and keep the dashboard manageable.
FAQs
Q: Can a Freestyle project use a Jenkinsfile? No — Freestyle projects are configured entirely through the UI. If you want your build logic in a Jenkinsfile, you need to create a Pipeline job instead.
Q: Can I convert a Freestyle project to a Pipeline later? There’s no automatic converter, but it’s usually straightforward to manually translate your build steps and post-build actions into an equivalent Jenkinsfile.
Q: Are Freestyle projects deprecated? No, they’re still fully supported and commonly used, especially for simpler automation tasks, though Pipelines are generally recommended for anything nontrivial.
Q: Can Freestyle projects run on specific agents only? Yes — check “Restrict where this project can be run” and specify a label matching the desired agent(s).
Summary
Freestyle projects are Jenkins’ original, form-based way of defining automation jobs, and they’re still a great option for simple builds, scheduled tasks, and anyone new to Jenkins. By walking through source code management, build triggers, build steps, and post-build actions, you can have a working automated job in just a few minutes — no scripting required.
