Jenkins Sites

Jenkins sites are configured in Jira and determine which jobs and builds are synchronized to Jira.

There are 2 different types of site that can be added:

  • A Private site, meaning the site is not accessible by the Jira app. Either because of a firewall or other network limitations.
  • A Public site, meaning the site is accessible by the Jira app for data synchronization.

To manage Jenkins sites, navigate to Settings > Apps > Jenkins Integration > Manage Sites.

Add a Site

  1. When on the Manage Sites page, click on the Add Site button. This brings up the Add Site dialog.
  2. Fill in the form and click Create to create the Site

    Private Site

    1. Selected the Type of the site.
    2. Provide a Name.
    3. Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new jobs.
      • It is advised that you enable this, since jobs will only become available in Jira after Jenkins notifies Jira of it, and this can time some time depending the build workload on Jenkins.
    4. Select Private accessibility option if your Jenkins site is behind a firewall or otherwise not accessible for job and build synchronization.
    5. Provide the Display URL for UI features.
    6. Save the site and open the Configuration options of the Jenkins site by clicking on the Configuration action of the site.
    7. Follow the instructions in the dialog box to complete the registration of the site.

    Public Site

    1. Selected the Type of the site.
    2. Provide a Name.
    3. Optionally, check the Auto enable new Jobs checkbox if you want to enable all Jobs on the site by default, including future new jobs.
    4. Select Public accessibility.
    5. Provide the Sync URL that should be used for synchronization and other background actions.
    6. Optionally, provide a Display URL in case the Sync URL is not accessible by users and a different URL should be used in the UI features.
    7. Select an Authentication Method
      • Select Sync Token Authentication to utilise JWT based authentication.
      • This option requires version 3.10.0 of the Jenkins counterpart plugin to be installed!
      • Select Basic Authentication to utilise username and token based authentication and provide them.
      • If you use and external source (like LDAP, AD or Crowd) for authentication, then provide the API Token as password for the user.
      • The API Token is a password replacing token that users can use to authenticate with against Jenkins. This is mostly useful for users that have there accounts managed outside Jenkins. To get a token for an account, follow these steps:

        1. Login on Jenkins using the username and password of the synchronization account
        2. Click on the Account Name in the top-right corner of the page after login
        3. Then click on the Configure link in the left menu
        4. The API Token can now be displayed by clicking on the Show API Token… button

Manage Sites

Edit a Site

To edit the details of a site, like name, authentication details, etc, simply click on the Edit button in the actions column. This will show the Site edit dialog and form allowing you to update the details of the Site.

In order to change the Basic Authentication token, you will need to check the Change Token box to show the Token field. If you use and external source (like LDAP, AD or Crowd) for authentication, then provide the API Token as password for the user.

The API Token is a password replacing token that users can use to authenticate with against Jenkins. This is mostly useful for users that have there accounts managed outside Jenkins. To get a token for an account, follow these steps:

  1. Login on Jenkins using the username and password of the synchronization account
  2. Click on the Account Name in the top-right corner of the page after login
  3. Then click on the Configure link in the left menu
  4. The API Token can now be displayed by clicking on the Show API Token… button

Delete a Site

To delete a Site, simply click the Delete button in the actions column and click the Delete button to delete the site.

Synchronize a Site

To synchronize a Site and all enabled jobs on it, simply click on the Synchronize button in the actions column.

Cleanup Jobs

To cleanup job and build data of a site, simply click on the Cleanup Jobs action in the actions dropdown. This will not delete data on Jenkins, but will only delete jobs and builds that are marked as deleted in Jira.

Auto Enable New Jobs

To quickly enable or disable the Auto Enable new Jobs setting for a Site, simply click on the Auto Enable new Jobs action in the actions dropdown. Alternatively this can also be done using the Site Edit action.

Registration Details

To show the site registration details of a site, simply click on the Registration Details action in the actions dropdown (If your site is behind a firewall then this button is placed top-level action). This information can be used to (re)register the Jira site with Jenkins.

Manage Jobs

The Manage Jobs site action allows you too quickly perform multiple operations, see Manage Jobs, on multiple jobs, simply click on the Manage Jobs action in the actions dropdown.

Enable/Disable a Job

Each job can be enabled or disabled in the synchronization process. Use the toggle button in front of the job name, or on top of the page, to enable or disable it.

Synchronize a Job

Jobs are automatically synchronized when they trigger a completed build using the Jira Build Notification Listener feature. But this process can be forced for a job by clicking on the Manage button in the actions column, followed by clicking on Synchronize in the actions column of a job.

Clear Build Cache

To remove all the synchronised builds of a Job, simply click on … and select Clear Build Cache

Rebuild Build Cache

To rebuild a build cache of a Job, simply click on … and select Rebuild Build Cache. This will mark all the builds of the selected Job as Deleted, reset the last synchronised build to 0, and will then trigger the synchronisation process for the selected Job.