How to Create a New Jenkins Job

Every single automated workflow in Jenkins starts the same way: creating a job. Whether it’s a simple Freestyle project, a full Pipeline, or a Multibranch setup that scans an entire organization’s repositories, the “New Item” screen is where it all begins. I want to walk you through the entire process of creating a Jenkins job, including the different job types available and when to use each one.

What Is a Jenkins Job?

A Jenkins job (also called a “project” or, in newer terminology, an “item”) is a unit of work Jenkins can execute — building code, running tests, deploying an application, or performing any scripted task. Every job has a configuration defining what to run, how to trigger it, and what to do with the results.

Jenkins Architecture Context

When you create a job, Jenkins stores its configuration as XML (for Freestyle) or references a Jenkinsfile (for Pipeline jobs) under its internal data directory. When triggered, the controller schedules the job onto an available agent matching any specified labels, then tracks its execution and results.

Step 1: Access the “New Item” Screen

From the Jenkins dashboard, click “New Item” in the left-hand menu (or navigate to http://your-jenkins-url/view/all/newJob).

Step 2: Choose a Job Type

Jenkins offers several job types, each suited to different needs:

• Freestyle project: UI-configured, simple builds. Great for beginners or simple automation.
• Pipeline: Code-defined build/test/deploy logic using a Jenkinsfile (Groovy-based). Recommended for most real-world CI/CD.
• Multibranch Pipeline: Automatically scans a repository for branches/PRs containing a Jenkinsfile and creates a sub-job for each.
• Folder: Not a job itself, but an organizational container for grouping related jobs.
• Multi-configuration project (Matrix): Runs the same job across multiple configurations (e.g., different OS/browser combinations) in parallel.
• Organization Folder: Scans an entire GitHub organization or Bitbucket project for repositories containing Jenkinsfiles.

Step 3: Name Your Job

Choose a clear, descriptive name using hyphens or underscores instead of spaces (e.g., backend-api-ci, not Backend API CI). This name becomes part of the job’s URL, so keep it consistent and readable.

Step 4A: Creating a Freestyle Job

After selecting Freestyle project and clicking OK:

1. Add a description.
2. Configure Source Code Management (typically Git).
3. Set Build Triggers (webhook, polling, or scheduled).
4. Add Build Steps (shell commands, Maven goals, etc.).
5. Add Post-build Actions (archiving artifacts, publishing test results, notifications).
6. Save.

Step 4B: Creating a Pipeline Job

After selecting Pipeline and clicking OK, scroll to the Pipeline section at the bottom of the configuration page. You have two options:

Option 1: Pipeline script (inline) — write your Groovy pipeline directly in the Jenkins UI text box. Good for quick tests, not recommended for real projects since it’s not version-controlled.

pipeline {
    agent any
    stages {
        stage('Hello') {
            steps {
                echo 'Hello from an inline pipeline!'
            }
        }
    }
}

Option 2: Pipeline script from SCM — point Jenkins to a Jenkinsfile stored in your Git repository. This is the recommended approach since your pipeline logic lives alongside your code and benefits from version history, code review, and rollback.

1. Select “Pipeline script from SCM.”
2. Choose “Git” as the SCM.
3. Enter your repository URL and credentials.
4. Set the “Script Path” (default: Jenkinsfile).
5. Save.

Step 4C: Creating a Multibranch Pipeline Job

1. Select “Multibranch Pipeline” and click OK.
2. Under “Branch Sources,” add your Git provider (GitHub, Bitbucket, etc.) and provide credentials.
3. Configure “Behaviors” to control which branches/PRs get scanned (e.g., “Discover branches,” “Discover pull requests from origin”).
4. Set a “Scan Multibranch Pipeline Triggers” interval, or rely on webhooks for instant scanning.
5. Save — Jenkins will scan the repository and automatically create sub-jobs for every branch containing a Jenkinsfile.

Step 5: Configuring Parameters (Optional)

For any job type, you can make it parameterized so users (or triggering systems) can supply input values at build time:

• String Parameter: Free text input (e.g., a version tag).
• Choice Parameter: A dropdown of predefined options (e.g., environment: staging/production).
• Boolean Parameter: A checkbox (e.g., “Run full test suite”).
• Credentials Parameter: Lets the build securely reference a credential chosen at trigger time.

In a Jenkinsfile, define parameters like this:

pipeline {
    agent any
    parameters {
        choice(name: 'ENVIRONMENT', choices: ['staging', 'production'], description: 'Deployment target')
        booleanParam(name: 'RUN_FULL_TESTS', defaultValue: false, description: 'Run the full test suite')
    }
    stages {
        stage('Deploy') {
            steps {
                echo "Deploying to ${params.ENVIRONMENT}"
            }
        }
    }
}

Step 6: Organizing Jobs with Folders

As the number of jobs grows, I strongly recommend using Folders (via the CloudBees Folders Plugin, often included by default) to group related jobs — for example, one folder per team, product, or environment. This keeps the dashboard manageable and lets you apply folder-level permissions.

Step 7: Cloning an Existing Job

If you need a job very similar to an existing one, use the “Copy from” field on the “New Item” screen. Enter the name of an existing job, and Jenkins will pre-populate the new job’s configuration, which you can then tweak as needed.

Real-World Example: Setting Up a Team’s First CI Job

Here’s a realistic sequence I’ve followed for a team adopting Jenkins for the first time:

1. Create a Folder named after the team (e.g., platform-team).
2. Inside that folder, create a Multibranch Pipeline job pointing to their main application repository.
3. Configure branch discovery for both branches and pull requests.
4. Add a Jenkinsfile to the repository defining build, test, and lint stages.
5. Set up a webhook so pushes trigger automatic scans and builds.
6. Add Slack notifications for build failures.

Using Job DSL or Configuration as Code for Bulk Job Creation

Manually clicking through “New Item” works fine for a handful of jobs, but once you’re managing dozens or hundreds, it becomes far more sustainable to define jobs as code. Two popular approaches:

Job DSL Plugin: Write Groovy scripts that programmatically define jobs:

job('backend-api-ci') {
    scm {
        git('https://github.com/yourusername/backend-api.git')
    }
    triggers {
        githubPush()
    }
    steps {
        shell('npm ci && npm test')
    }
}

Jenkins Configuration as Code (JCasC): Define entire Jenkins configurations, including jobs, in YAML files, which can be version-controlled and applied automatically on startup:

jobs:
  - script: |
      pipelineJob('backend-api-ci') {
        definition {
          cpsScm {
            scm {
              git {
                remote { url('https://github.com/yourusername/backend-api.git') }
              }
            }
          }
        }
      }

Both approaches let you treat your Jenkins job configuration the same way you treat application code — reviewed, versioned, and reproducible.

Setting Up Job-Specific Permissions

Once you have multiple teams sharing a single Jenkins instance, it’s worth configuring folder-level permissions so each team can only see and modify their own jobs. Using the Role-based Authorization Strategy Plugin, you can create roles scoped to specific folder patterns (e.g., platform-team/.*) and assign team members accordingly.

Troubleshooting Common Issues When Creating Jobs

• “It appears your reverse proxy set up is broken” warning: This usually relates to Jenkins’ root URL configuration under Manage Jenkins > System, not the job itself, but can affect webhook callbacks.
• Multibranch Pipeline shows no branches: Double-check credentials have access to the repository and that at least one branch contains a Jenkinsfile at the configured script path.
• Job configuration not saving: Check for required fields left blank, or plugin version mismatches causing UI form errors — check /var/log/jenkins/jenkins.log for details.
• Duplicate job names: Jenkins job names must be unique within their folder; use folders to logically separate similarly-named jobs across teams.

Security Best Practices

• Use Role-Based Access Control (via the Role-based Authorization Strategy Plugin) to limit who can create, edit, or delete jobs.
• Store all credentials via Jenkins’ Credentials system, scoped to the folder or job that actually needs them.
• Regularly audit and remove stale, unused jobs to reduce your attack surface and keep the system performant.
• Enable Jenkins’ CSRF protection (enabled by default in modern versions) to prevent unauthorized job triggering.

FAQs

Q: What’s the difference between a Pipeline job and a Multibranch Pipeline job? A Pipeline job builds a single branch (or whatever you configure), while a Multibranch Pipeline automatically discovers and builds every branch/PR containing a Jenkinsfile, creating sub-jobs dynamically.

Q: Can I rename a Jenkins job after creating it? Yes, use the “Rename” option in the job’s sidebar menu, though be aware this changes the job’s URL, which may break existing bookmarks or external references.

Q: How do I delete a Jenkins job? Open the job, click “Delete Project” in the sidebar, and confirm. This action is irreversible unless you have a backup of the Jenkins configuration.

Q: Can non-admin users create their own jobs? Yes, if you grant them the appropriate permissions (like “Job/Create”) via Jenkins’ security matrix or role-based strategy, typically scoped to a specific folder.

Summary

Creating a new Jenkins job is the entry point to any automation you want Jenkins to handle — whether that’s a simple Freestyle build, a fully-fledged Pipeline defined in a Jenkinsfile, or a Multibranch setup that scales automatically with your repository’s branches. Picking the right job type up front, organizing jobs into folders, and setting sensible triggers and parameters will save you a lot of maintenance headaches down the line.

References

• Jenkins Handbook — Managing Jobs
• Jenkins Pipeline Documentation
• CloudBees Folders Plugin
• Role-based Authorization Strategy Plugin