search

jenkinsci / gitlab-branch-source-plugin

A Jenkins Plugin for GitLab Multibranch Pipeline jobs and Folder Organization
https://plugins.jenkins.io/gitlab-branch-source
MIT License
124 stars 94 forks source link
jenkins-plugins multibranch-pipeline-jobs

readme

Gitpod ready-to-code Build Status GitHub release Gitter Jenkins Plugin Installs

GitLab Branch Source Plugin

To be fully able to run a Jenkins Continuous Integration on a GitLab repository or project, you require the following plugins:

Getting Started

Getting Started with Jenkins:
Jenkins is an open source, self hosting automation server for continuous integration and continuous delivery. The source code of the core Jenkins and its plugins are written in Java. There have been developments on a modern Jenkins Server (see: [Blueocean Plugin](https://github.com/jenkinsci/blueocean-plugin)) using React and other modern front end tools to provide rich user experience. For more Jenkins related information, see [documentation](https://jenkins.io/doc/). ### Extending Jenkins Jenkins has more than a 1000 plugins so a vast set of functionality has already been implemented and this can be used to leverage new plugins. Jenkins has an extensibility feature that allows plugin to use other plugins or core features simply by extending their classes. To define or create an extension in Jenkins,we use the `@Extension` annotation type. This annotation is picked up by Jenkins, and the new extension will be added to an `ExtensionList` object, where the extension can then be found via `ExtensionFinder`. ### Running Jenkins server: Here are a few ways to setup your own Jenkins server: 1. Using a Jenkins docker: i. Download docker image from [here](https://hub.docker.com/r/jenkins/jenkins). ii. Open up a terminal/command prompt window to the download directory. iii. Run command: ```bash docker run \ -u root \ --rm \ -d \ -p 8080:8080 \ -p 50000:50000 \ -v jenkins-data:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ --name jenkins \ jenkinsci/blueocean ``` iv. Browse to `http://localhost:8080`. If you need more information about docker commands, see [here](https://jenkins.io/doc/book/installing/#on-macos-and-linux). 2. Using a Jenkins Web application Archive (WAR): i. Download [latest stable Jenkins WAR file](https://get.jenkins.io/war-stable/latest/jenkins.war). ii. Open up a terminal/command prompt window to the download directory. iii. Run command: ```bash java -jar jenkins.war ``` iv. Browse to `http://localhost:8080/jenkins`. 3. Using a Azure Jenkins solution: Refer to Azure [docs](https://docs.microsoft.com/en-us/azure/architecture/example-scenario/apps/jenkins). 4. Using a Bitnami Jenkins Stack: Refer to Bitnami [docs](https://docs.bitnami.com/general/apps/jenkins/). 5. Using [Jenkins CLI](https://github.com/jenkins-zh/jenkins-cli) run it for development: Run it via: `jcli plugin run` ### Configuring Jenkins instance: 1. Unlock your Jenkins instance: i. From the Jenkins console log output, copy the automatically-generated alphanumeric password. ii. On the Unlock Jenkins page, paste this password into the Administrator password field and click `Continue`. 2. Customizing Jenkins with plugins. Choose one option: i. `Install suggested plugins` - to install the recommended set of plugins, which are based on most common use cases. ii. `Select plugins to install` - to choose which set of plugins to initially install. When you first access the plugin selection page, the suggested plugins are selected by default. 3. Create an admin user: i. When the Create First Admin User page appears, specify the details for your administrator user in the respective fields and click Save and Finish. ii. When the Jenkins is ready page appears, click Start using Jenkins. iii. If required, log in to Jenkins with the credentials of the user you just created and you are ready to start using Jenkins!

Minimum Requirements

  1. Jenkins - 2.176.2 LTS or above
  2. GitLab - 11.0 or above

Installing plugin

You can use any one of these ways:

  1. Install from Jenkins Update Center. Go to Jenkins > Configure > Manage Plugins > Available and search for gitlab branch source plugin then select Install.

  2. Using Plugin Management Tool

    java -jar plugin-management-tool.jar
    -p gitlab-branch-source
    -d <path-to-default-jenkins-plugins-directory>
    -w <path-to-jenkins-war>

  3. From Source:

    i. Checkout out source code to your local machine:

    git clone https://github.com/jenkinsci/gitlab-branch-source-plugin.git
cd gitlab-branch-source-plugin

    ii. Install the plugin:

    mvn clean install
    or
mvn clean install -DskipTests # to skip tests

    iii. Run the Plugin:

    mvn hpi:run # runs a Jenkins instance at localhost:8080
    or
mvn hpi:run -Djetty.port={port} # to run on your desired port number

    iv. Now the *.hpi generated can be manually installed on your Jenkins instance:

    1. Select `Manage Jenkins`

2. Select `Manage Plugins`

3. Select `Advanced` tab

3. In `Upload Plugin` section, select `Choose file`

4. Select `${root_dir}/target/gitlab-branch-source.hpi`

5. Select `Upload`

6. Select `Install without restart`

  4. Download latest release from here and manually install.

Initial Setup

After installing the plugin on your Jenkins instance, you need configure your GitLab Server settings.

Setting up GitLab Server Configuration on Jenkins

  1. On jenkins, select Manage Jenkins.

  2. Select Configure System.

  3. Scroll down to find the GitLab section.

    gitlab-section

  4. Select Add GitLab Server | Select GitLab Server.

  5. Now you will now see the GitLab Server Configuration options

    gitlab-server

    There are 4 fields that needs to be configured:

    i. Name - Plugin automatically generates an unique server name for you. User may want to configure this field to suit their needs but should make sure it is sufficiently unique. We recommend to keep it as it is.

    ii. Server URL - Contains the URL to your GitLab Server. By default it is set to "https://gitlab.com". User can modify it to enter their GitLab Server URL e.g. https://gitlab.gnome.org/, http://gitlab.example.com:7990. etc.

    iii. Credentials - Contains a list of credentials entries that are of type GitLab Personal Access Token or any String Credentials. When no credential has been added it shows "-none-". User can add a credential by clicking "Add" button.

    iv. Mange Web Hook - If you want the plugin to setup web hook on your GitLab project(s) to get push/mr/tag/note events then check this box.

    iv. Mange System Hook - If you want the plugin to setup system hook on your GitLab project(s) to detect if a project is removed then check this box. Remember plugin can only setup system hook on your server if supplied access token has Admin access.

    v. Secret Token - The secret token is required to authenticate the webhook payloads received from GitLab Server. Use generate secret token from Advanced options or use your own. If you are a old plugin user and did not set a secret token previously and want secret token to applied to the hooks of your existing jobs, you can add the secret token and rescan your jobs. Existing hooks with new secret token will be applied.

    vi. Root URL for hooks - By default Root URL for hooks created by this plugin is your Jenkins instance url. You can modify the root URL in by adding your custom root URL. Leave empty if you want Jenkins URL to be your custom hook url. A path is added to your hook ROOT URL /gitlab-webhook/post for webhooks and /gitlab-systemhook/post for system hooks.

  6. Adding a Personal Access Token Credentials:

    This is a manual setup. To automatically generate Personal Access Token see next section.

    i. User is required to add a GitLab Personal Access Token or any String Credential type credentials entry to securely persist the token inside Jenkins.

    ii. Generate a Personal Access Token on your GitLab Server

    a. Select profile dropdown menu from top-right corner

b. Select `Settings`

c. Select `Access Token` from left column

d. Enter a name | Set Scope to `api` (If admin also give `sudo` which required for systemhooks and mr comment trigger)

e. Select `Create Personal Access Token`

f. Copy the token generated

    iii. Return to Jenkins | Select Add in Credentials field | Select Jenkins.

    iv. Set Kind to GitLab Personal Access Token.

    v. Enter Token.

    vi. Enter a unique id in ID.

    vii. Enter a human readable description.

    gitlab-credentials

    viii. Select Add.

  7. Testing connection:

    i. Select your desired token in the Credentials dropdown.

    ii. Select Test Connection.

    iii. It should return something like Credentials verified for user {username}.

  8. Select Apply (at the bottom).

  9. GitLab Server is now setup on Jenkins.

Creating Personal Access Token within Jenkins

Alternatively, users can generate a GitLab Personal Access Token within Jenkins itself and automatically add the GitLab Personal Access Token credentials to Jenkins server credentials.

  1. Select Advanced at the bottom of GitLab Section.

  2. Select Manage Additional GitLab Actions.

  3. Select Convert login and password to token.

  4. Set the GitLab Server URL.

  5. There are 2 options to generate token:

    i. From credentials - To select an already persisting Username Password Credentials or add an Username Password credential to persist it.

    ii. From login and password - If this is a one time thing then you can directly enter you credentials to the text boxes and the username/password credential is not persisted.

  6. After setting your username/password credential, select Create token credentials.

  7. The token creator will create a Personal Access Token in your GitLab Server for the given user with the required scope and also create a credentials for the same inside Jenkins server. You can go back to the GitLab Server Configuration to select the new credentials generated (select "-none-" first then new credentials will appear). For security reasons this token is not revealed as plain text rather returns an id. It is a 128-bit long UUID-4 string (36 characters).

    gitlab-token-creator

Manually create hooks on GitLab Server

Use the following end points for web hooks and system hooks setup on your GitLab Server. The Jenkins Url needs to be a fully qualified domain name (FQDN) so cannot be localhost.

WebHook

<jenkins_url>/gitlab-webhook/post

with push, tag, merge request and note events.

SystemHook

<jenkins_url>/gitlab-systemhook/post

with repository update event.

Configuration as Code

There is an easier way to setup GitLab Server configuration on your Jenkins server. No need for messing around in the UI. Jenkins Configuration as Code (JCasC) or simply Configuration as Code Plugin allows you to configure Jenkins via a yaml file. If you are a first time user, you can learn more about JCasC here.

Prerequisite:

Install Configuration as Code Plugin on your Jenkins instance.

Refer to Installing a new plugin in Jenkins.

Add configuration YAML:

There are multiple ways to load JCasC yaml file to configure Jenkins:

To configure your GitLab Server in Jenkins add the following to jenkins.yaml:

credentials:
  system:
    domainCredentials:
      - credentials:
          - gitlabPersonalAccessToken:
              scope: SYSTEM
              id: "i<3GitLab"
              token: "glpat-XfsqZvVtAx5YCph5bq3r" # gitlab personal access token

unclassified:
  gitLabServers:
    servers:
      - credentialsId: "i<3GitLab" # same as id specified for gitlab personal access token credentials
        manageWebHooks: true
        manageSystemHooks: true # access token should have admin access to set system hooks
        name: "gitlab-3214"
        serverUrl: "https://gitlab.com"
        hooksRootUrl: ""
        secretToken: ""

See handling secrets section in JCasC documentation for better security.

Jobs Setup

GitLab Branch Source Plugin allows you to create 2 type of jobs:

Multibranch Pipeline Jobs

The Multibranch Pipeline job type enables you to implement different Jenkinsfiles for different branches of the same project. In a Multibranch Pipeline job, Jenkins automatically discovers, manages and executes Pipelines for Branches/Merge Requests/Tags which contain a Jenkinsfile in source control. This eliminates the need for manual Pipeline creation and management.

To create a Multibranch Pipeline Job:

  1. Select New Item on Jenkins home page.

  2. Enter a name for your job, select Multibranch Pipeline | select Ok.

  3. In Branch Sources sections, select Add source | select GitLab Project.

  4. Now you need to configure your jobs.

    branch-source

    i. Select Server configured in the initial server setup.

    ii. [Optional] Add Checkout Credentials (SSHPrivateKey or Username/Password) if there is any private projects that will be built by the plugin.

    iii. Add path to the owner where the project you want to build exists. If user, enter username. If group, enter group name. If subgroup, enter subgroup path with namespace.

    iv. Based on the owner provided. All the projects are discovered in the path and added to the Projects listbox. You can now choose the project you want to build.

    v. Behaviours (a.k.a. SCM Traits) allow different configurations option to your build. More about it in the SCM Trait APIs section.

  5. Now you can go ahead and save the job.

For more info see this.

After saving, a new web hook is created in your GitLab Server if a GitLab Access Token is specified in the server configuration. Then the branch indexing starts based on what options behaviours you selected. As the indexing proceeds new jobs are started and queued for each branches with a Jenkinsfile in their root directory.

The Job results are notified to the GitLab Server as Pipeline Status for the HEAD commit of each branches built. The build for forked MR cannot be notified to GitLab Server as GitLab doesn't provide Pipeline status for Merge Requests from forks for security concerns. See this.

We have a workaround for this. Jenkins will build the MRs from forked projects if the MR author is a trusted owner i.e. has Developer/Maintainer/Owner access level. More about it in the SCM Trait APIs section.

As the web hook is now setup on your Jenkins CI by the GitLab server. Any push-events or merge-request events or tag events trigger the concerned build in Jenkins.

Folder Organization

Folders Organization enable Jenkins to monitor an entire GitLab User/Group/Subgroup and automatically create new Multibranch Pipelines for projects which contain branches/merge requests/tags containing a Jenkinsfile. In our plugin this type of job is called GitLab Group.

To create a GitLab Group Job:

  1. Select New Item on Jenkins home page.

  2. Enter a name for your job.

  3. Select Organization Folder as the job type and press the Ok button.

  4. In Configuration, under Projects, select GitLab Group as the Repository Sources.

  5. Now you need to configure your jobs.

    i. Select Server configured in the initial server setup.

    ii. [Optional] Add Checkout Credentials (SSHPrivateKey or Username/Password) only if there are any private projects required to be built.

    iii. Add path to the owner whose projects you want to build. If user, enter username. If group, enter group name. If subgroup, enter subgroup path with namespace.

    v. Behaviours (a.k.a. SCM Traits) are allow different configuration option to your build. More about it in the SCM Trait APIs section.

The indexing in this group job type only needs to discover one branch withJenkinsfile and thus it only shows the partial indexing log. You need to visit individual projects to see their full indexing.

SCM Trait APIs

The following behaviours apply to both Multibranch Pipeline Jobs and Folder Organization (unless otherwise stated).

Default Traits:

Additional Traits:

These traits can be selected by selecting Add in the Behaviours section.

Environment Variables

By default Multibranch Jobs have the following environment variables (provided by Branch API Plugin):

Branch - BRANCH_NAME

Merge Request - BRANCH_NAME, CHANGE_ID, CHANGE_TARGET, CHANGE_BRANCH, CHANGE_FORK, CHANGE_URL, CHANGE_AUTHOR, CHANGE_TITLE. CHANGE_AUTHOR_DISPLAY_NAME

Tag - BRANCH_NAME, TAG_NAME, TAG_TIMESTAMP, TAG_DATE, TAG_UNIXTIME

This plugin adds a few more environment variables to Builds (WorkflowRun type only) which is the payload received as WebHook) See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#events.

A few points to note:

If no response is recorded for any field in the Web Hook Payload, it returns an empty String. To add more variables see package io.jenkins.plugins.gitlabbranchsource.Cause.

GITLAB_OBJECT_KIND - This environment variable should be used to check the event type before accessing the environment variables. Possible values are none, push, tag_push and merge_request.

Any variables ending with # indicates the index of the list of the payload starting from 1.

Environment Variables are available from Push Event, Tag Push Event and Merge Request Event.

Push Event:

See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#push-events

Expand :snowflake:
``` GITLAB_OBJECT_KIND GITLAB_AFTER GITLAB_BEFORE GITLAB_REF GITLAB_CHECKOUT_SHA GITLAB_USER_ID GITLAB_USER_NAME GITLAB_USER_USERNAME GITLAB_USER_EMAIL GITLAB_PROJECT_ID GITLAB_PROJECT_ID_2 GITLAB_PROJECT_NAME GITLAB_PROJECT_DESCRIPTION GITLAB_PROJECT_WEB_URL GITLAB_PROJECT_AVATAR_URL GITLAB_PROJECT_GIT_SSH_URL GITLAB_PROJECT_GIT_HTTP_URL GITLAB_PROJECT_NAMESPACE GITLAB_PROJECT_VISIBILITY_LEVEL GITLAB_PROJECT_PATH_NAMESPACE GITLAB_PROJECT_CI_CONFIG_PATH GITLAB_PROJECT_DEFAULT_BRANCH GITLAB_PROJECT_HOMEPAGE GITLAB_PROJECT_URL GITLAB_PROJECT_SSH_URL GITLAB_PROJECT_HTTP_URL GITLAB_REPO_NAME GITLAB_REPO_URL GITLAB_REPO_DESCRIPTION GITLAB_REPO_HOMEPAGE GITLAB_REPO_GIT_SSH_URL GITLAB_REPO_GIT_HTTP_URL GITLAB_REPO_VISIBILITY_LEVEL GITLAB_COMMIT_COUNT GITLAB_REQUEST_URL GITLAB_REQUEST_STRING GITLAB_REQUEST_TOKEN GITLAB_REFS_HEAD ```

Tag Event:

Note:

Jenkins by default refrains from automatically building Tags on push (See reason). You need to install Branch Build Strategy Plugin to solve this.

See Guide: https://github.com/jenkinsci/basic-branch-build-strategies-plugin/blob/master/docs/user.adoc

Do remember if you are using Basic Branch Build for tag builds you also need to add strategies for branch and pull request (change request) else they would not be automatically built (See GIF below).

branch-build-strategy

See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#tag-events

Expand :sunny:
``` GITLAB_OBJECT_KIND GITLAB_AFTER GITLAB_BEFORE GITLAB_REF GITLAB_CHECKOUT_SHA GITLAB_USER_ID GITLAB_USER_NAME GITLAB_USER_USERNAME GITLAB_USER_EMAIL GITLAB_PROJECT_ID GITLAB_PROJECT_ID_2 GITLAB_PROJECT_NAME GITLAB_PROJECT_DESCRIPTION GITLAB_PROJECT_WEB_URL GITLAB_PROJECT_AVATAR_URL GITLAB_PROJECT_GIT_SSH_URL GITLAB_PROJECT_GIT_HTTP_URL GITLAB_PROJECT_NAMESPACE GITLAB_PROJECT_VISIBILITY_LEVEL GITLAB_PROJECT_PATH_NAMESPACE GITLAB_PROJECT_CI_CONFIG_PATH GITLAB_PROJECT_DEFAULT_BRANCH GITLAB_PROJECT_HOMEPAGE GITLAB_PROJECT_URL GITLAB_PROJECT_SSH_URL GITLAB_PROJECT_HTTP_URL GITLAB_REPO_NAME GITLAB_REPO_URL GITLAB_REPO_DESCRIPTION GITLAB_REPO_HOMEPAGE GITLAB_REPO_GIT_SSH_URL GITLAB_REPO_GIT_HTTP_URL GITLAB_REPO_VISIBILITY_LEVEL GITLAB_COMMIT_COUNT GITLAB_REQUEST_URL GITLAB_REQUEST_STRING GITLAB_REQUEST_TOKEN GITLAB_REFS_HEAD ```

Merge Request Event:

See https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#merge-request-events

Expand :zap:
``` GITLAB_OBJECT_KIND GITLAB_USER_NAME GITLAB_USER_USERNAME GITLAB_USER_AVATAR_URL GITLAB_PROJECT_ID GITLAB_PROJECT_NAME GITLAB_PROJECT_DESCRIPTION GITLAB_PROJECT_WEB_URL GITLAB_PROJECT_AVATAR_URL GITLAB_PROJECT_GIT_SSH_URL GITLAB_PROJECT_GIT_HTTP_URL GITLAB_PROJECT_NAMESPACE GITLAB_PROJECT_VISIBILITY_LEVEL GITLAB_PROJECT_PATH_NAMESPACE GITLAB_PROJECT_CI_CONFIG_PATH GITLAB_PROJECT_DEFAULT_BRANCH GITLAB_PROJECT_HOMEPAGE GITLAB_PROJECT_URL GITLAB_PROJECT_SSH_URL GITLAB_PROJECT_HTTP_URL GITLAB_REPO_NAME GITLAB_REPO_URL GITLAB_REPO_DESCRIPTION GITLAB_REPO_HOMEPAGE GITLAB_REPO_GIT_SSH_URL GITLAB_REPO_GIT_HTTP_URL GITLAB_REPO_VISIBILITY_LEVEL GITLAB_OA_ID GITLAB_OA_TARGET_BRANCH GITLAB_OA_SOURCE_BRANCH GITLAB_OA_SOURCE_PROJECT_ID GITLAB_OA_AUTHOR_ID GITLAB_OA_ASSIGNEE_ID GITLAB_OA_TITLE GITLAB_OA_CREATED_AT GITLAB_OA_UPDATED_AT GITLAB_OA_MILESTONE_ID GITLAB_OA_STATE GITLAB_OA_MERGE_STATUS GITLAB_OA_TARGET_PROJECT_ID GITLAB_OA_IID GITLAB_OA_DESCRIPTION GITLAB_OA_SOURCE_NAME GITLAB_OA_SOURCE_DESCRIPTION GITLAB_OA_SOURCE_WEB_URL GITLAB_OA_SOURCE_AVATAR_URL GITLAB_OA_SOURCE_GIT_SSH_URL GITLAB_OA_SOURCE_GIT_HTTP_URL GITLAB_OA_SOURCE_NAMESPACE GITLAB_OA_SOURCE_VISIBILITY_LEVEL GITLAB_OA_SOURCE_PATH_WITH_NAMESPACE GITLAB_OA_SOURCE_DEFAULT_BRANCH GITLAB_OA_SOURCE_HOMEPAGE GITLAB_OA_SOURCE_URL GITLAB_OA_SOURCE_SSH_URL GITLAB_OA_SOURCE_HTTP_URL GITLAB_OA_TARGET_NAME GITLAB_OA_TARGET_DESCRIPTION GITLAB_OA_TARGET_WEB_URL GITLAB_OA_TARGET_AVATAR_URL GITLAB_OA_TARGET_GIT_SSH_URL GITLAB_OA_TARGET_GIT_HTTP_URL GITLAB_OA_TARGET_NAMESPACE GITLAB_OA_TARGET_VISIBILITY_LEVEL GITLAB_OA_TARGET_PATH_WITH_NAMESPACE GITLAB_OA_TARGET_DEFAULT_BRANCH GITLAB_OA_TARGET_HOMEPAGE GITLAB_OA_TARGE_URL GITLAB_OA_TARGET_SSH_URL GITLAB_OA_TARGET_HTTP_URL GITLAB_OA_LAST_COMMIT_ID GITLAB_OA_LAST_COMMIT_MESSAGE GITLAB_OA_LAST_COMMIT_TIMESTAMP GITLAB_OA_LAST_COMMIT_URL GITLAB_OA_LAST_COMMIT_AUTHOR_NAME GITLAB_OA_LAST_COMMIT_AUTHOR_EMAIL GITLAB_OA_WIP GITLAB_OA_URL GITLAB_OA_ACTION GITLAB_OA_ASSIGNEE_NAME GITLAB_OA_ASSIGNEE_USERNAME GITLAB_OA_ASSIGNEE_AVATAR_URL GITLAB_LABELS_COUNT GITLAB_LABEL_ID_# GITLAB_LABEL_TITLE_# GITLAB_LABEL_COLOR_# GITLAB_LABEL_PROJECT_ID_# GITLAB_LABEL_CREATED_AT_# GITLAB_LABEL_UPDATED_AT_# GITLAB_LABEL_TEMPLATE_# GITLAB_LABEL_DESCRIPTION_# GITLAB_LABEL_TYPE_# GITLAB_LABEL_GROUP_ID_# GITLAB_CHANGES_UPDATED_BY_ID_PREV GITLAB_CHANGES_UPDATED_BY_ID_CURR GITLAB_CHANGES_UPDATED_AT_PREV GITLAB_CHANGES_UPDATED_AT_CURR ```

Job DSL seed job configuration

To create a Job DSL seed job see this tutorial.

Here is a sample seed job script for folder organization job:

organizationFolder('GitLab Organization Folder') {
    description("GitLab org folder created with Job DSL")
    displayName('My Project')
    // "Projects"
    organizations {
        gitLabSCMNavigator {
            projectOwner("baymac")
            credentialsId("i<3GitLab")
            serverName("gitlab-3214")
            // "Traits" ("Behaviours" in the GUI) that are "declarative-compatible"
            traits {
                subGroupProjectDiscoveryTrait() // discover projects inside subgroups
                gitLabBranchDiscovery {
                    strategyId(3) // discover all branches
                }
                originMergeRequestDiscoveryTrait {
                    strategyId(1) // discover MRs and merge them with target branch
                }
                gitLabTagDiscovery() // discover tags
            }
        }
    }
    // "Traits" ("Behaviours" in the GUI) that are NOT "declarative-compatible"
    // For some 'traits, we need to configure this stuff by hand until JobDSL handles it
    // https://issues.jenkins.io/browse/JENKINS-45504
    configure {
        def traits = it / navigators / 'io.jenkins.plugins.gitlabbranchsource.GitLabSCMNavigator' / traits
        traits << 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait' {
            strategyId(2)
            trust(class: 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait$TrustPermission')
        }
    }
    // "Project Recognizers"
    projectFactories {
        workflowMultiBranchProjectFactory {
            scriptPath 'Jenkinsfile'
        }
    }
    // "Orphaned Item Strategy"
    orphanedItemStrategy {
        discardOldItems {
            daysToKeep(10)
            numToKeep(5)
        }
    }
    // "Scan Organization Folder Triggers" : 1 day
    // We need to configure this stuff by hand because JobDSL only allow 'periodic(int min)' for now
    triggers {
        periodicFolderTrigger {
            interval('1d')
        }
    }
}

To see all the APIs supported by Job DSL you can visit the following link:

http://localhost:8080/jenkins/plugin/job-dsl/api-viewer/index.html#path/organizationFolder-organizations-gitLabSCMNavigator-traits

JCasC configuration to create job

You can also use JCasC to directly create job from a Job DSL seed job. Here's an example of the yaml config:

jobs:
  - script: >
      organizationFolder('GitLab Organization Folder') {
        description("GitLab org folder configured with JCasC")
        displayName('My Project')
        // "Projects"
        organizations {
          gitLabSCMNavigator {
            projectOwner("baymac")
            credentialsId("i<3GitLab")
            serverName("gitlab-3214")
            // "Traits" ("Behaviours" in the GUI) that are "declarative-compatible"
            traits {
              subGroupProjectDiscoveryTrait() // discover projects inside subgroups
              gitLabBranchDiscovery {
                strategyId(3) // discover all branches
              }
              originMergeRequestDiscoveryTrait {
                strategyId(1) // discover MRs and merge them with target branch
              }
              gitLabTagDiscovery() // discover tags
            }
          }
        }
        // "Traits" ("Behaviours" in the GUI) that are NOT "declarative-compatible"
        // For some 'traits, we need to configure this stuff by hand until JobDSL handles it
        // https://issues.jenkins.io/browse/JENKINS-45504
        configure { node ->
            def traits = node / navigators / 'io.jenkins.plugins.gitlabbranchsource.GitLabSCMNavigator' / traits
            traits << 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait' {
                strategyId('2')
                trust(class: 'io.jenkins.plugins.gitlabbranchsource.ForkMergeRequestDiscoveryTrait$TrustPermission')
            }
        }
        // "Project Recognizers"
        projectFactories {
            workflowMultiBranchProjectFactory {
                scriptPath 'Jenkinsfile'
            }
        }
        // "Orphaned Item Strategy"
        orphanedItemStrategy {
          discardOldItems {
            daysToKeep(-1)
            numToKeep(-1)
          }
        }
        // "Scan Organization Folder Triggers" : 1 day
        // We need to configure this stuff by hand because JobDSL only allow 'periodic(int min)' for now
        configure { node ->
          node / triggers / 'com.cloudbees.hudson.plugins.folder.computed.PeriodicFolderTrigger' {
            spec('H H * * *')
            interval(86400000)
          }
        }
      }

You can also use file or url to load the script, see this.

Known Issues

How to talk to us?

Acknowledgements

This plugin was created by the Google Summer of Code (GSoC) Team for Multibranch Pipeline Support for GitLab.

Current Maintainers: