GitSwarm-EE 2017.1-1 Documentation
Jenkins CI integration
In GitSwarm 2016.1, Jenkins integration using the GitLab Hook Plugin was deprecated in favor of the GitLab Plugin. The deprecated integration has been renamed to 'Jenkins CI (Deprecated)' in the project service settings. We may remove this in a future release and recommend using the new 'Jenkins CI' project service instead. See documentation for 'Jenkins CI (Deprecated)' below.
Jenkins CI Service
Integration includes:
- Trigger a Jenkins build after push to a repository and/or when a merge request is created
- Show build status on Merge Request page, on each commit and on the project home page
Requirements:
- Jenkins GitLab Plugin
- Jenkins Git Plugin
- Git clone access for Jenkins from the GitSwarm repository
- GitSwarm API access to report build status
Configure GitSwarm users
Create a user or choose an existing user that Jenkins will use to interact through the GitSwarm API. This user will need to be a global Admin or added as a member to each Group/Project. Developer permission is required for reporting build status. This is because a successful build status can trigger a merge when 'Merge when build succeeds' feature is used. Some features of the GitLab Plugin may require additional privileges. For example, there is an option to accept a merge request if the build is successful. Using this feature would require developer, master or owner-level permission.
Copy the private API token from Profile Settings -> Account. You will need this when configuring the Jenkins server later.
Configure the Jenkins server
Install Jenkins GitLab Plugin and Jenkins Git Plugin.
Go to Manage Jenkins -> Configure System and scroll down to the 'GitSwarm' section. Enter the GitSwarm server URL in the 'GitSwarm host URL' field and paste the API token copied earlier in the 'API Token' field.
Configure a Jenkins project
Follow the GitLab Plugin documentation under the Using it With a Job heading. You do not need to complete instructions under the 'GitSwarm Configuration (>= 8.0)'. Be sure to check the 'Use GitLab CI features' checkbox as described under the 'GitSwarm Configuration (>= 8.1)'.
Configure a GitLab project
Create a new GitLab project or choose an existing one. Then, go to Services -> Jenkins CI.
Check the 'Active' box. Select whether you want GitSwarm to trigger a build on push, Merge Request creation, tag push, or any combination of these. We recommend unchecking 'Merge Request events' unless you have a specific use-case that requires re-building a commit when a merge request is created. With 'Push events' selected, GitSwarm will build the latest commit on each push and the build status will be displayed in the merge request.
Enter the Jenkins URL and Project name. The project name should be URL-friendly where spaces are replaced with underscores. To be safe, copy the project name from the URL bar of your browser while viewing the Jenkins project.
Optionally, enter a username and password if your Jenkins server requires authentication.
Jenkins CI (Deprecated) Service
This service is deprecated and may be removed in a future version of GitSwarm. Please see documentation for the new Jenkins CI service above.
Integration includes:
- Trigger Jenkins build after push to repo
- Show build status on Merge Request page
Requirements:
- Jenkins GitLab Hook plugin
- git clone access for Jenkins from GitSwarm repo (via ssh key)
Jenkins
- Install GitLab Hook plugin
- Setup jenkins project
GitSwarm
Read access to repository
Jenkins needs read access to the GitSwarm repository. We already specified a private key to use in Jenkins, now we need to add a public one to the GitLab project. For that case we will need a Deploy key. Read the documentation on how to setup a Deploy key.
Jenkins service
Now navigate to GitSwarm services page and activate Jenkins
Done! Now when you push to GitSwarm - it will create a build for Jenkins. And also you will be able to see merge request build status with a link to the Jenkins build.
Multi-project Configuration
The GitLab Hook plugin in Jenkins supports the automatic creation of a project for each feature branch. After configuration GitSwarm will trigger feature branch builds and a corresponding project will be created in Jenkins.
Configure the GitLab Hook plugin in Jenkins. Go to 'Manage Jenkins' and then 'Configure System'. Find the 'GitSwarm Web Hook' section and configure as shown below.
In the Jenkins service in GitSwarm, check the 'Multi-project setup enabled?'.
Mark unstable build as passing
When using some plugins in Jenkins, an unstable build status will result when tests are not passing. In these cases the unstable status in Jenkins should register as a failure in GitSwarm on the merge request page. In other cases you may not want an unstable status to display as a build failure in GitSwarm. Control this behavior using the 'Should unstable builds be treated as passing?' setting in the Jenkins service in GitSwarm.
When checked, unstable builds will display as green or passing in GitSwarm. By default unstable builds display in GitSwarm as red or failed.
Development
An explanation of how this works in case anyone want to improve it or develop this service for another CI tool. In GitSwarm there is no database table that lists the commits, these are always read from the repository. Therefore it is not possible to mark the build status of a commit in GitSwarm. Actually we believe this information should be stored in a single place, the CI tool itself. To show this information in a merge request you make a project service in GitSwarm. This project service does a (JSON) query to a url of the CI tool with the SHA1 of the commit. The project service builds this url and payload based on project service settings and knowlegde of the CI tool. The response is parsed to give a response in GitSwarm (success/failed/pending). All this happens with AJAX requests on the merge request page. The Jenkins project service code is only available in GitSwarm EE. The GitLab CI project service code is available in the GitSwarm CE codebase.