Job configuration sections in Jenkins - Commands & Configuration

Introduction

Jenkins jobs need configuration files to tell them what to do. These files have sections that organize settings like source code location, build steps, and notifications. This helps Jenkins run tasks automatically and correctly.

When you want Jenkins to pull code from a Git repository before building.

When you need to run a script or command as part of your build process.

When you want Jenkins to send an email after a build finishes.

When you want to set environment variables for your build steps.

When you want to schedule your job to run at specific times automatically.

Config File - config.xml

config.xml

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <actions/>
  <description>Example Jenkins job configuration</description>
  <keepDependencies>false</keepDependencies>
  <properties/>
  <scm class="hudson.plugins.git.GitSCM" plugin="git@4.10.0">
    <configVersion>2</configVersion>
    <userRemoteConfigs>
      <hudson.plugins.git.UserRemoteConfig>
        <url>https://github.com/example/my-app.git</url>
      </hudson.plugins.git.UserRemoteConfig>
    </userRemoteConfigs>
    <branches>
      <hudson.plugins.git.BranchSpec>
        <name>*/main</name>
      </hudson.plugins.git.BranchSpec>
    </branches>
    <doGenerateSubmoduleConfigurations>false</doGenerateSubmoduleConfigurations>
    <submoduleCfg class="list"/>
    <extensions/>
  </scm>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers>
    <hudson.triggers.TimerTrigger>
      <spec>H 2 * * *</spec>
    </hudson.triggers.TimerTrigger>
  </triggers>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>echo "Building the project..."
./build.sh</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers>
    <hudson.tasks.Mailer>
      <recipients>[e-mail]</recipients>
      <dontNotifyEveryUnstableBuild>false</dontNotifyEveryUnstableBuild>
      <sendToIndividuals>true</sendToIndividuals>
    </hudson.tasks.Mailer>
  </publishers>
  <buildWrappers/>
</project>

<scm> tells Jenkins where to get the source code (Git repo URL and branch).

<triggers> schedules the job to run automatically (here, daily at 2 AM).

<builders> defines the commands Jenkins runs to build the project.

<publishers> sets notifications, like sending emails after builds.

Commands

This command creates a new Jenkins job named 'example-job' using the configuration file 'config.xml'. It tells Jenkins what the job should do.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 create-job example-job < config.xml

Expected Output

Created job: example-job

→

-s - Specifies the Jenkins server URL

This command starts a build of the 'example-job' immediately to test if the configuration works.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 build example-job

Expected Output

Started build #1 for job example-job

→

-s - Specifies the Jenkins server URL

This command retrieves and shows the current configuration of the 'example-job' to verify it was set correctly.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 get-job example-job

Expected Output

<?xml version="1.0" encoding="UTF-8"?>

<project>

  <actions/>

  <description>Example Jenkins job configuration</description>

  <keepDependencies>false</keepDependencies>

  <properties/>

  <scm class="hudson.plugins.git.GitSCM" plugin="git@4.10.0">

    <configVersion>2</configVersion>

    <userRemoteConfigs>

      <hudson.plugins.git.UserRemoteConfig>

        <url>https://github.com/example/my-app.git</url>

      </hudson.plugins.git.UserRemoteConfig>

    </userRemoteConfigs>

    <branches>

      <hudson.plugins.git.BranchSpec>

        <name>*/main</name>

      </hudson.plugins.git.BranchSpec>

    </branches>

    <doGenerateSubmoduleConfigurations>false</doGenerateSubmoduleConfigurations>

    <submoduleCfg class="list"/>

    <extensions/>

  </scm>

  <canRoam>true</canRoam>

  <disabled>false</disabled>

  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>

  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>

  <triggers>

    <hudson.triggers.TimerTrigger>

      <spec>H 2 * * *</spec>

    </hudson.triggers.TimerTrigger>

  </triggers>

  <concurrentBuild>false</concurrentBuild>

  <builders>

    <hudson.tasks.Shell>

      <command>echo "Building the project..."

./build.sh</command>

    </hudson.tasks.Shell>

  </builders>

  <publishers>

    <hudson.tasks.Mailer>

      <recipients>[e-mail]</recipients>

      <dontNotifyEveryUnstableBuild>false</dontNotifyEveryUnstableBuild>

      <sendToIndividuals>true</sendToIndividuals>

    </hudson.tasks.Mailer>

  </publishers>

  <buildWrappers/>

</project>

→

-s - Specifies the Jenkins server URL

Key Concept

If you remember nothing else from this pattern, remember: Jenkins job configuration sections organize how the job gets code, builds it, runs, and reports results.

Common Mistakes

Forgetting to include the <scm> section or giving a wrong Git URL.

Jenkins won't know where to get the source code, so the build will fail.

Always include a valid <scm> section with the correct repository URL and branch.

Not defining any build steps inside <builders>.

Jenkins will run the job but do nothing, so no build happens.

Add at least one build step like a shell command or script inside <builders>.

Setting an invalid schedule in <triggers>.

The job won't run automatically as expected.

Use valid cron syntax for the <spec> field to schedule builds properly.

Summary

The config.xml file defines sections like <scm>, <builders>, <triggers>, and <publishers> to control job behavior.

Use Jenkins CLI commands to create, build, and check jobs using this configuration file.

Correct configuration ensures Jenkins can get code, build it, schedule runs, and send notifications.