Merge branch 'master' into release-1.2

This commit is contained in:
Robin Müller 2016-04-25 21:06:32 +02:00
commit b9916396a5
5 changed files with 199 additions and 43 deletions

7
.gitignore vendored
View File

@ -1,13 +1,6 @@
.idea/
*.iml
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.next
release.properties
work
.classpath
.project
.settings
/bin/
/bin

View File

@ -1,6 +1,42 @@
ChangeLog
=====================
1.1.32
=====================
* #218 license within pom.xml and LICENSE is different
* #226 Add description to parameters actions
* #216 Fix NPE when author email is not available
* #235 mention required permissions for commit status API
* #225 Enhance README section Contribution
* #236 Fix the usage of CommitStatus
* #215 Fix error "failed to communicate with gitlab server ..." when try to rebuild open MRs
1.1.30 + 1.1.31
=====================
* issues with the release plugin
1.1.29
=====================
* #127 Added support for the GitLab 8.1 commit API
* #128 Add two variables gitlabUserName and gitlabUserEmail
* #129 Assorted minor fixes for merge requests
* #139 Fix for issue #125: use reponame for branch caching
* #140 Added missing documentation 8.1 CI features
* #141 Refactoring data objects to own package
* #146 Fixed Documentation after #128
* #149 New feature: Add support for regex based filtering and more
* #151 Update readme to reflect support for the commit status API
* #154 8.1 is now a supported version
* #163 Bugfix for issue #160: allow merge requests to different branches from one commit
* #164 Not reporting build status 8.1+
* #180 Parameter gitlabMergeRequestTitle is always blank
* #182 Status to canceled instead of failed if Jenkins build is aborted
* #195 Fix NPE if there is no assignee of the MR
* #197 Reorganize README to be more clear about config for different versions of GitLab
* #205 closes #183 Plugin not working with multiple SCM configuration
* #206 Fix Jenkins Workflow support in build trigger code
* #209 Don't ignore push builds when responding to status query
1.1.28
=====================
* (#119 - @mfriedenhagen) Add buildUrl in the description of the merge (shown in GitLab)

123
README.md
View File

@ -1,22 +1,39 @@
Overview
======
# Table of Contents
- [Introduction](#introduction)
- [User support](#user-support)
- [Supported GitLab versions](#supported-gitLab-versions)
- [Supported GitLabCI Functions](#supported-gitlabci-functions)
- [Configuring access to GitLab](#configuring-access-to-gitlab)
- [Jenkins Job Configuration](#jenkins-job-configuration)
- [Gitlab Configuration (7.14.x)](#gitlab-configuration-714x)
- [Gitlab Configuration (>= 8.1)](#gitlab-configuration--81)
- [Forked repositories](#forked-repositories)
- [Branch filtering](#branch-filtering)
- [Build Tags](#build-tags)
- [Parameterized builds](#parameterized-builds)
- [Help Needed](#help-needed)
- [Quick test environment setup using Docker](#quick-test-environment-setup-using-docker)
- [Access GitLab](#access-gitlab)
- [Access Jenkins](#access-jenkins)
- [Release Workflow](#release-workflow)
# Introduction
This plugin allows GitLab to trigger builds in Jenkins after code is pushed and/or after a merge request is created.
User support
======
# User support
If you have a problem or question about using the plugin, please create an issue in the GitHub project. You can also try chatting with us in #gitlab-plugin on the Freenode IRC network.
Supported GitLab versions
======
* 7.14.x where it emulates Jenkins as a GitlabCI Web Service
# Supported GitLab versions
* 7.14.x where it emulates Jenkins as a GitLabCI Web Service
* 8.1.x and newer via the new commit status API that supports with external CI services like Jenkins
Unsupported GitLab versions
======
* 8.0.x - in this version, GitLab folded the GitLabCI functionality into core GitLab, and in doing so broke the ability for the plugin to give build status to GitLab. **Jenkins build status will never work with GitLab 8.0.x!**
**Note:** GitLab version **8.0.x** is **not** supported! In this version, GitLab folded the GitLabCI functionality into core GitLab, and in doing so broke the ability for the plugin to give build status to GitLab. Jenkins build status will never work with GitLab 8.0.x!
# Supported GitLabCI Functions
Current Supported GitLabCI Functions
=====================
* `/project/PROJECT_NAME/builds/COMMIT_SHA1/status.json` (used for Merge Request pages) returns build result for Merge Request build with `COMMIT_SHA1` as last commit
* `/project/PROJECT_NAME/builds/status.png?ref=BRANCH_NAME` returns build status icon for latest build for `BRANCH_NAME`
* `/project/PROJECT_NAME/builds/status.png?sha1=COMMIT_SHA1` returns build status icon for latest build for `COMMIT_SHA1` as last commit
@ -25,21 +42,20 @@ Current Supported GitLabCI Functions
* `/project/PROJECT_NAME?ref=BRANCH_NAME` redirects to build page of the last build for `BRANCH_NAME`
* `/project/PROJECT_NAME` triggers a build, type (Merge Request or Push) depending on payload
Configuring access to Gitlab
=======================================
# Configuring access to GitLab
Optionally, the plugin communicates with the Gitlab server in order to fetch additional information. At this moment, this information is limited to fetching the source project of a Merge Request, in order to support merging from forked repositories.
Optionally, the plugin communicates with the GitLab server in order to fetch additional information. At this moment, this information is limited to fetching the source project of a Merge Request, in order to support merging from forked repositories.
To enable this functionality, a user should be set up on Gitlab, with adequate permissions to access the repository. On the global configuration screen, supply the gitlab host url ``http://your.gitlab.server`` and the API token of the user of choice.
To enable this functionality, a user should be set up on GitLab, with GitLab 'Developer' permissions, to access the repository. On the global configuration screen, supply the gitlab host url ``http://your.gitlab.server`` and the API token of the user of choice.
### Jenkins Job Configuration
## Jenkins Job Configuration
* Create a new job by going to *New Job*
* Set the _Project Name_ to whatever you like
* In the *Source Code Management* section:
* Click *Git*
* Enter your *Repository URL* (e.g.: ``git@your.gitlab.server:group/repo_name.git``)
* In the Advanced settings, set its *Name* to ``origin``
* To be able to merge from forked repositories: <br/>**Note:** this requires [configuring communication to the Gitlab server](#configuring-access-to-gitlab)
* To be able to merge from forked repositories: <br/>**Note:** this requires [configuring communication to the GitLab server](#configuring-access-to-gitlab)
* Add a second repository with:
* *URL*: ``${gitlabSourceRepoURL}``
* *Name* (in Advanced): ``${gitlabSourceRepoName}``
@ -58,7 +74,7 @@ To enable this functionality, a user should be set up on Gitlab, with adequate p
* Configure any other pre build, build or post build actions as necessary
* Click *Save* to preserve your changes in Jenkins.
### GitLab Configuration (7.x)
## Gitlab Configuration (7.14.x)
* In GitLab go to your repository's project *Settings*
* Click on *Services*
* Click on *GitLab CI*
@ -70,7 +86,7 @@ To enable this functionality, a user should be set up on Gitlab, with adequate p
* Add a Web Hook for *Merge Request Events* to ``http://JENKINS_URL/project/PROJECT_NAME`` <br/>
**Note:** GitLab for some reason does not send a merge request event with the GitLab Service.
### GitLab Configuration (8.0.x)
## Gitlab Configuration (>= 8.1)
* In GitLab go to you primary repository's project *Settings*
* Click on *Web Hooks*
* Add a Web Hook for *Merge Request Events* and *Push Events* to ``http://JENKINS_URL/project/PROJECT_NAME`` <br/>
@ -82,12 +98,10 @@ If you plan to use forked repositories, you will need to enable the GitLab CI in
* Add a Web Hook for *Merge Request Events* and *Push Events* to ``http://JENKINS_URL/project/PROJECT_NAME`` <br/>
**Note:** You do not need to select any "Trigger Events" as the Web Hook for Merge Request Events will alert Jenkins.
### GitLab Configuration (>= 8.1)
GitLab 8.1 uses the same configuration as GitLab 8.0
* GitLab 8.1 has implemented a commit status api. To enable this check the ``Use GitLab CI features`` under the project settings.
* Configure access to GitLab as described above in "Configure access to GitLab" (the account needs at least developer permissions to post commit statuses)
### Forked repositories
## Forked repositories
If you plan to use forked repositories, you will need to enable the GitLab CI integration on **each fork**.
* Go to the Settings page in each developer's fork
* Click on *Services*
@ -98,15 +112,18 @@ If you plan to use forked repositories, you will need to enable the GitLab CI in
* Click *Save* <br />
**Note:** You do not need to select any "Trigger Events" as the Web Hook for Merge Request Events will alert Jenkins.
Branch filtering
================
In addition, you will need to make sure that the Git plugin has an appropriate setting for user.name and user.email in the global Jenkins configuration. This is good practice generally, but is required for forked repos to work.
1. Click on Manage Jenkins, then Configure System
2. Under the Git Plugin section, set something for 'Global Config user.name Value' and 'Global Config user.email Value'
# Branch filtering
Triggers from push events may be filtered based on the branch name, i.e. the build will only be allowed for selected branches. On the project configuration page, a list of all branches on the remote repository is displayed under ``Build when a change is pushed to GitLab.``. It is possible to select multiple branches by holding Ctrl and clicking.
This functionality requires accessing the Gitlab server (see [above](#configuring-access-to-gitlab)) and for the time being also a git repository url already saved in the project configuration. In other words, when creating a new project, the configuration needs to be saved *once* before being able to select the allowed branches. For Workflow jobs, the configuration must be saved *and* the job must be run once before the list is populated. For existing projects, all branches are allowed to push by default.
This functionality requires accessing the GitLab server (see [above](#configuring-access-to-gitlab)) and for the time being also a git repository url already saved in the project configuration. In other words, when creating a new project, the configuration needs to be saved *once* before being able to select the allowed branches. For Workflow jobs, the configuration must be saved *and* the job must be run once before the list is populated. For existing projects, all branches are allowed to push by default.
Build Tags
================
# Build Tags
In order to build when a new tag is pushed:
* In the ``GitLab server`` add ``Tag push events`` to the ``Web Hook``
@ -114,8 +131,7 @@ In order to build when a new tag is pushed:
* select ``Advance...`` and add ``+refs/tags/*:refs/remotes/origin/tags/*`` as ``Refspec``
* you can also use ``Branch Specifier`` to specify which tag need to be built (exampple ``refs/tags/${TAGNAME}``)
Parameterized builds
====================
# Parameterized builds
You can trigger a job a manually by clicking ``This build is parameterized`` and adding the relevant build parameters.
These include:
@ -132,14 +148,13 @@ These include:
* gitlabUserName
* gitlabUserEmail
Help Needed
=====================
# Help Needed
* `/projects/` - seems to be already used by Jenkins, A way to use this path would be awesome
* `?token=XYZ` - Can not find a way to include a token parameter on an AbstractProject to security check without an extra plugin configuration
* `/PROJECT_NAME/` should really be /PROJECT_ID_NUMBER/ - Can not find a project id number on an AbstractProject to use here instead.
Contributing to the Plugin
==========================
# Contributing to the Plugin
Plugin source code is hosted on [Github](https://github.com/jenkinsci/gitlab-plugin).
New feature proposals and bug fix proposals should be submitted as
@ -151,6 +166,7 @@ If you are adding new features please make sure that they support the Jenkins Wo
See [here](https://github.com/jenkinsci/workflow-plugin/blob/master/COMPATIBILITY.md) for some information.
Before submitting your change make sure that:
* your changes work with the oldest and latest supported GitLab version
* new features are provided with tests
* refactored code is provided with regression tests
* the code formatting follows the plugin standard
@ -158,3 +174,42 @@ Before submitting your change make sure that:
* you updated the help docs
* you updated the README
* you have used findbugs to see if you haven't introduced any new warnings.
# Quick test environment setup using Docker
In order to test the plugin on different versions of `GitLab` and `Jenkins` you may want to use `Docker` containers.
A example docker-compose file is available at `gitlab-plugin/src/docker` which allows to set up instances of the latest `GitLab` and `Jenkins` versions.
To start the containers, run below command from the `docker` folder:
```bash
docker-compose up -d
```
## Access GitLab
To access `GitLab`, point your browser to `http://localhost:10080` and login using the default username and password:
* username: **root**
* password: **5iveL!fe**
For more information on the supported `GitLab` versions and how to configure the containers, visit Sameer Naik's github page at https://github.com/sameersbn/docker-gitlab.
## Access Jenkins
To see `Jenkins`, point your browser to `http://localhost:8080`.
For more information on the supported `Jenkins` tags and how to configure the containers, visit https://hub.docker.com/r/library/jenkins.
# Release Workflow
GitLab-Plugin admins should adhere to the following rules when releasing a new plugin version:
* Ensure codestyle conformity
* Run unit tests
* Run manual tests on both, oldest and latest GitLab versions
* Update documentation
* Create change log
* Create release tag
* Create release notes (on github)

View File

@ -22,8 +22,8 @@
<licenses>
<license>
<name>MIT License</name>
<url>http://opensource.org/licenses/MIT</url>
<name>GPL v2.0 License</name>
<url>http://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html</url>
</license>
</licenses>

View File

@ -0,0 +1,72 @@
postgresql:
restart: always
image: sameersbn/postgresql:9.4-17
environment:
- DB_USER=gitlab
- DB_PASS=password
- DB_NAME=gitlabhq_production
- DB_EXTENSION=pg_trgm
volumes:
- /srv/docker/gitlab/postgresql:/var/lib/postgresql
gitlab:
restart: always
image: sameersbn/gitlab:8.5.8-1
links:
- redis:redisio
- postgresql:postgresql
ports:
- "10080:80"
- "10022:22"
environment:
- DEBUG=false
- TZ=Asia/Kolkata
- GITLAB_TIMEZONE=Kolkata
- GITLAB_SECRETS_DB_KEY_BASE=long-and-random-alphanumeric-string
- GITLAB_HOST=localhost
- GITLAB_PORT=10080
- GITLAB_SSH_PORT=10022
- GITLAB_RELATIVE_URL_ROOT=
- GITLAB_NOTIFY_ON_BROKEN_BUILDS=true
- GITLAB_NOTIFY_PUSHER=false
- GITLAB_EMAIL=notifications@example.com
- GITLAB_EMAIL_REPLY_TO=noreply@example.com
- GITLAB_INCOMING_EMAIL_ADDRESS=reply@example.com
- GITLAB_BACKUP_SCHEDULE=daily
- GITLAB_BACKUP_TIME=01:00
- SMTP_ENABLED=false
- SMTP_DOMAIN=www.example.com
- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=587
- SMTP_USER=mailer@example.com
- SMTP_PASS=password
- SMTP_STARTTLS=true
- SMTP_AUTHENTICATION=login
- IMAP_ENABLED=false
- IMAP_HOST=imap.gmail.com
- IMAP_PORT=993
- IMAP_USER=mailer@example.com
- IMAP_PASS=password
- IMAP_SSL=true
- IMAP_STARTTLS=false
volumes:
- /srv/docker/gitlab/gitlab:/home/git/data
redis:
restart: always
image: sameersbn/redis:latest
volumes:
- /srv/docker/gitlab/redis:/var/lib/redis
jenkins:
restart: always
image: jenkins:1.642.2
ports:
- "8080:8080"
- "50000:50000"
volumes:
- /srv/docker/jenkins:/var/jenkins