Skip to content

G
gitlab-ce
Commit fbd6831d authored by Sean Packham's avatar Sean Packham
Browse files
Options

Merge branch 'docs/jenkins-split-ee' into 'master' 

Split Jenkins docs

See merge request !2045
parents bc0882c3 9bd593d7
Hide whitespace changes
Inline Side-by-side
Showing with 77 additions and 93 deletions
doc/integration/jenkins.md
View file @ fbd6831d
# Jenkins CI integration # Jenkins CI service
>**Note:**
In GitLab 8.3, Jenkins integration using the In GitLab 8.3, Jenkins integration using the
[GitLab Hook Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin) [GitLab Hook Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
was deprecated in favor of the was deprecated in favor of the
[GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin). [GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin).
The deprecated integration has been renamed to 'Jenkins CI (Deprecated)' in the The deprecated integration has been renamed to [Jenkins CI (Deprecated)](jenkins_deprecated.md) in the
project service settings. We may remove this in a future release and recommend project service settings. We may remove this in a future release and recommend
using the new 'Jenkins CI' project service instead. See using the new 'Jenkins CI' project service instead which is described in this
[documentation for 'Jenkins CI (Deprecated)'](#jenkins-ci-deprecated-service) document.
below.
## Jenkins CI Service The Jenkins integration includes:
Integration includes:
* Trigger a Jenkins build after push to a repository and/or when a merge request * Trigger a Jenkins build after push to a repository and/or when a merge request
is created is created
* Show build status on Merge Request page, on each commit and on the project * Show build status on Merge Request page, on each commit and on the project
home page home page
### Requirements: ## Requirements
* [Jenkins GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin) * [Jenkins GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin)
* [Jenkins Git Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin) * [Jenkins Git Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin)
* Git clone access for Jenkins from the GitLab repository * Git clone access for Jenkins from the GitLab repository
* GitLab API access to report build status * GitLab API access to report build status
### Configure GitLab users ## Configure GitLab users
Create a user or choose an existing user that Jenkins will use to interact Create a user or choose an existing user that Jenkins will use to interact
through the GitLab API. This user will need to be a global Admin or added through the GitLab API. This user will need to be a global Admin or added
...@@ -40,7 +38,7 @@ require developer, master or owner-level permission. ...@@ -40,7 +38,7 @@ require developer, master or owner-level permission.
Copy the private API token from **Profile Settings -> Account**. You will need this Copy the private API token from **Profile Settings -> Account**. You will need this
when configuring the Jenkins server later. when configuring the Jenkins server later.
### Configure the Jenkins server ## Configure the Jenkins server
Install [Jenkins GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin) Install [Jenkins GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin)
and [Jenkins Git Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin). and [Jenkins Git Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin).
...@@ -51,7 +49,7 @@ copied earlier in the 'API Token' field. ...@@ -51,7 +49,7 @@ copied earlier in the 'API Token' field.
![Jenkins GitLab plugin configuration](jenkins_gitlab_plugin_config.png) ![Jenkins GitLab plugin configuration](jenkins_gitlab_plugin_config.png)
### Configure a Jenkins project ## Configure a Jenkins project
Follow the GitLab Plugin documentation under the Follow the GitLab Plugin documentation under the
[Using it With a Job](https://github.com/jenkinsci/gitlab-plugin#using-it-with-a-job) [Using it With a Job](https://github.com/jenkinsci/gitlab-plugin#using-it-with-a-job)
...@@ -59,7 +57,7 @@ heading. You *do not* need to complete instructions under the 'GitLab ...@@ -59,7 +57,7 @@ heading. You *do not* need to complete instructions under the 'GitLab
Configuration (>= 8.0)'. Be sure to check the 'Use GitLab CI features' checkbox Configuration (>= 8.0)'. Be sure to check the 'Use GitLab CI features' checkbox
as described under the 'GitLab Configuration (>= 8.1)'. as described under the 'GitLab Configuration (>= 8.1)'.
### Configure a GitLab project ## Configure a GitLab project
Create a new GitLab project or choose an existing one. Then, go to **Integrations -> Create a new GitLab project or choose an existing one. Then, go to **Integrations ->
Jenkins CI**. Jenkins CI**.
...@@ -80,87 +78,20 @@ authentication. ...@@ -80,87 +78,20 @@ authentication.
![GitLab service settings](jenkins_gitlab_service_settings.png) ![GitLab service settings](jenkins_gitlab_service_settings.png)
# Jenkins CI (Deprecated) Service ## Plugin functional overview
This service is deprecated and may be removed in a future version of GitLab.
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](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
* git clone access for Jenkins from GitLab repo (via ssh key)
## Jenkins
1. Install [GitLab Hook plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
2. Setup jenkins project
![screen](jenkins_project.png)
## GitLab
### Read access to repository
Jenkins needs read access to the GitLab 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](../ssh/README.md#deploy-keys).
### Jenkins service
Now navigate to GitLab services page and activate Jenkins
![screen](jenkins_gitlab_service.png)
Done! Now when you push to GitLab - 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 GitLab 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 'GitLab Web Hook' section and configure as shown below.
![Jenkins Multi-project Configuration](jenkins_multiproject_configuration.png)
In the Jenkins service in GitLab, check the 'Multi-project setup enabled?'.
![Jenkins Multi-project Enabled](jenkins_multiproject_enabled.png)
### 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 GitLab on the merge request page. In other cases you
may not want an unstable status to display as a build failure in GitLab. Control
this behavior using the 'Should unstable builds be treated as passing?' setting
in the Jenkins service in GitLab.
When checked, unstable builds will display as green or passing in GitLab. By GitLab does not contain a database table listing commits. Commits are always
default unstable builds display in GitLab as red or failed. read from the repository directly. Therefore, it is not possible to retain the
build status of a commit in GitLab. This is overcome by requesting build
information from the integrated CI tool. The CI tool is responsible for creating
and storing build status for Commits and Merge Requests.
![Jenkins Unstable Passing](jenkins_unstable_passing.png) ### Steps required to implement a similar integration
## Development >**Note:**
All steps are implemented using AJAX requests on the merge request page.
An explanation of how this works in case anyone want to improve it or develop this service for another CI tool. 1. In order to display the build status in a merge request you must create a project service in GitLab.
In GitLab there is no database table that lists the commits, these are always read from the repository. 2. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
Therefore it is not possible to mark the build status of a commit in GitLab. 3. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
Actually we believe this information should be stored in a single place, the CI tool itself. 4. The response is parsed to give a response in GitLab (success/failed/pending).
To show this information in a merge request you make a project service in GitLab.
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 GitLab (success/failed/pending).
All this happens with AJAX requests on the merge request page.
The Jenkins project service code is only available in GitLab EE.
The GitLab CI project service code is available in the GitLab CE codebase.
doc/integration/jenkins_deprecated.md 0 → 100644
View file @ fbd6831d
# Jenkins CI (deprecated) service
>**Note:** In GitLab 8.3, Jenkins integration using the
[GitLab Hook Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
was deprecated in favor of the
[GitLab Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Plugin).
Please use documentation for the new [Jenkins CI service](jenkins.md).
Integration includes:
* Trigger Jenkins build after push to repo
* Show build status on Merge Request page
Requirements:
* [Jenkins GitLab Hook plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
* git clone access for Jenkins from GitLab repo (via ssh key)
## Jenkins
1. Install [GitLab Hook plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+Hook+Plugin)
2. Setup jenkins project
![screen](jenkins_project.png)
## GitLab
In GitLab, perform the following steps.
### Read access to repository
Jenkins needs read access to the GitLab 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](../ssh/README.md#deploy-keys).
### Jenkins service
Now navigate to GitLab services page and activate Jenkins
![screen](jenkins_gitlab_service.png)
Done! Now when you push to GitLab - 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 GitLab 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 'GitLab Web Hook' section and configure as shown below.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7