Skip next build

4 minute read

The Skip Next Build plugin allows you to skip building a job for a short period of time. While you could skip building a job by disabling it from the job configure page, you would need to remember to enable the job.

Use this plugin:

  • If you are going to take some external resources that the build requires offline for maintenance and you don’t want to see any build failure notices.

  • If you are merging a major feature branch and you want to prevent builds until after the merge is completed.

The plugin adds a image Skip Builds action to all jobs. When a skip is applied to the job, a message with an orange background appears across the main job page as shown in the image below.

Figure 1. The main job screen when a skip has been applied
Figure 1. The main job screen when a skip has been applied

To apply a skip to a folder or job:

  1. Select a job or folder from your controller dashboard.

  2. Select image Skip builds on the left navigation menu. The Skip builds page displays.

    Figure 2. Applying a skip to a folder/job
    Figure 2. Applying a skip to a folder/job
  3. Under Skip build for, select how long to apply the skip. You can select a value from 1 to 8 hours or enter a value up to 100 in the hours field.

  4. Select Apply skip. A message displays across the main job page that builds are skipped until the specified time.

When a skip is applied to a folder, all jobs within the folder will be skipped.

To remove a skip from a folder or job:

  1. Select image Skip builds on the left navigation menu.

    Figure 3. Removing a skip from a job
    Figure 3. Removing a skip from a job
  2. Select Remove skip to remove the skip. If the skip was not applied directly to the folder/job but instead is either inherited from a parent folder or originating from a skip group, the screen will look similar to the image below.

    Figure 4. Trying to remove a skip from a job where the skip is inherited from a parent folder.
    Figure 4. Trying to remove a skip from a job where the skip is inherited from a parent folder.

    The link(s) in the table of active skips can be used to navigate to the corresponding skip.

Skip groups

Depending on how the jobs in your Jenkins instance are organized and the reasons for skipping builds, it may be necessary to select a disjoint set of jobs from across the instance for skipping. Skip groups can be used to combine jobs from different folders so that they can be skipped as a single group. The Jenkins administrator configures skip groups in the global configuration.

To create a skip group:

  1. From the controller dashboard, select Manage Jenkins on the left navigation menu.

  2. On the Manage Jenkins page, select System.

  3. On the System page, select Skip groups from the breadcrumb bar context menu.

    skip groups global config navigate
    Figure 5. Navigating to the Jenkins  Manage Jenkins  System  Skip groups section using the breadcrumb bar’s context menu.
  4. Select Add.

  5. Configure the skip group.

    skip groups global config adding
    Figure 6. Adding a skip group to the Jenkins global configuration
    1. Enter a skip group title in the Name field.

    2. Enter information in the Description field that explains to users why the skip has been applied to their jobs.

    3. Use ANT Path expressions in the Include: and Exclude: fields to identify jobs to be included or excluded from the skip group.

      1. Include: An expression to match elements to be added in the skip group, coming from the Jenkins instance.

      2. Exclude: An expression to match elements from the Skip Group that will be excluded from the Skip Group.

        To configure the ANT Path expressions for the Include: and Exclude: fields use the following example.

        myproject (a folder for your development project):

        • build jobs for branches and features:

          • myproject/build-core

          • myproject/build-api

          • myproject/build-ui

          • myproject/build-data

        • release jobs for the application:

          • myproject/release-test

          • myproject/release-qa

          • myproject/release-prod

        If you are planning on releasing your project and would like to skip all of the build projects, but not the release jobs, you can create a skip group by entering the following in the Include: field:

        • Include: myproject/build-**

        If your project has additional jobs:

        • testing jobs for the application:

          • myproject/test-commons

          • myproject/test-ui

          • myproject/test-regression

        You can create a skip group by entering the following in the Exclude: field:

        • Include: myproject/**

        • Exlude: myproject/release-**

        When you use the Include: field for ANT Path expressions, you do not have to use the Exclude: field. However, you cannot use the Exclude: field without the Include: field.

  6. Select Add again if you want to create more skip groups.

Adding folders or jobs to a skip group

Once skip groups are defined, you can configure the jobs and/or folder membership from the job/folder configuration page.

skip groups folder membership
Figure 7. Configuring a folder’s skip group membership
1 Select Skip group membership.
2 Select a skip group.

When there is at least one skip group defined in a Jenkins instance, the Jenkins  Skip groups page is enabled. The Skip groups page contains a table that lists the available skip groups.

skip groups index
Figure 8. The Jenkins  Skip groups page

To manage the skip state of a skip group, select the skip group name in the table to navigate to that skip group’s details page.

skip groups details
Figure 9. The details page for a specific skip group

The details page displays the current status of the skip group and lists all of the items that are a direct member of this skip group.

Where folders are a member of a skip group, the skip group membership will be inherited by all items in the folder.

Controlling skips with Jenkins CLI

The Skip Next Build plugin adds a number of Jenkins CLI commands for controlling skips.

apply-skip: Enables the skip setting on a job.

Command apply-skip
Figure 10. Command apply-skip

This command takes two parameters:

  1. The full name of the job.

  2. The number of hours the skip should be active.

apply-folder-skip: Enables the skip setting on a folder.

Command apply-folder-skip
Figure 11. Command apply-folder-skip

This command takes two parameters:

  1. The full name of the folder.

  2. The number of hours the skip should be active.

skip-group-on: Enables the skip setting on a skip group.

Command skip-group-on
Figure 12. Command skip-group-on

This command takes two parameters:

  1. The name of the skip group.

  2. The number of hours the skip should be active.

remove-skip: Removes the currently active skip setting from a job.

Command remove-skip
Figure 13. Command remove-skip

This command takes only one parameter: the full name of the job.

remove-folder-skip: Removes the currently active skip setting from a folder.

Command remove-folder-skip
Figure 14. Command remove-folder-skip

This command takes only one parameter: the full name of the folder.

skip-group-off: Removes the currently active skip setting from a skip group.

Command skip-group-off
Figure 15. Command skip-group-off

This command takes only one parameter: the name of the skip group.