Commit ccd65e38 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs-repo-merge-3-integration' into 'master'

Docs: Merge EE doc/​integration to CE

See merge request gitlab-org/gitlab-ce!27610
parents 0ca24531 66b25804
...@@ -15,7 +15,9 @@ See the documentation below for details on how to configure these services. ...@@ -15,7 +15,9 @@ See the documentation below for details on how to configure these services.
- [CAS](cas.md) Configure GitLab to sign in using CAS - [CAS](cas.md) Configure GitLab to sign in using CAS
- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. - [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc.
- [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages
- [Jenkins](jenkins.md) Integrate with the Jenkins CI
- [JIRA](../user/project/integrations/jira.md) Integrate with the JIRA issue tracker - [JIRA](../user/project/integrations/jira.md) Integrate with the JIRA issue tracker
- [Kerberos](kerberos.md) Integrate with Kerberos
- [LDAP](ldap.md) Set up sign in via LDAP - [LDAP](ldap.md) Set up sign in via LDAP
- [OAuth2 provider](oauth_provider.md) OAuth2 application creation - [OAuth2 provider](oauth_provider.md) OAuth2 application creation
- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure and Authentiq ID - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure and Authentiq ID
......
This diff is collapsed.
# Jenkins CI service **[STARTER]**
>**Note:**
In GitLab 8.3, Jenkins integration using the
[GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
was deprecated in favor of the
[GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin).
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
using the new 'Jenkins CI' project service instead which is described in this
document.
## Overview
[Jenkins](https://jenkins.io/) is a great Continuous Integration tool, similar to our built-in
[GitLab CI](../ci/README.md).
GitLab's Jenkins integration allows you to trigger a Jenkins build when you
push code to a repository, or when a merge request is created. Additionally,
it shows the pipeline status on merge requests widgets and on the project's home page.
## Use cases
- Suppose you are new to GitLab, and want to keep using Jenkins until you prepare
your projects to build with [GitLab CI/CD](../ci/README.md). You set up the
integration between GitLab and Jenkins, then you migrate to GitLab CI later. While
you organize yourself and your team to onboard GitLab, you keep your pipelines
running with Jenkins, but view the results in your project's repository in GitLab.
- Your team uses [Jenkins Plugins](https://plugins.jenkins.io/) for other proceedings,
therefore, you opt for keep using Jenkins to build your apps. Show the results of your
pipelines directly in GitLab.
## Requirements
* [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
* [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin)
* Git clone access for Jenkins from the GitLab repository
* GitLab API access to report build status
## Configure GitLab users
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
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 pipeline 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, maintainer 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](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin)
and [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin).
Go to Manage Jenkins -> Configure System and scroll down to the 'GitLab' section.
Enter the GitLab server URL in the 'GitLab host URL' field and paste the API token
copied earlier in the 'API Token' field.
For more information, see GitLab Plugin documentation about
[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication)
![Jenkins GitLab plugin configuration](img/jenkins_gitlab_plugin_config.png)
## Configure a Jenkins project
Follow the GitLab Plugin documentation about [Jenkins Job Configuration](https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration).
NOTE: **Note:**
Be sure to include the steps about [Build status configuration](https://github.com/jenkinsci/gitlab-plugin#build-status-configuration).
The 'Publish build status to GitLab' post-build step is required to view
Jenkins build status in GitLab Merge Requests.
## Configure a GitLab project
Create a new GitLab project or choose an existing one. Then, go to **Integrations ->
Jenkins CI**.
Check the 'Active' box. Select whether you want GitLab 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, GitLab 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.
![GitLab service settings](img/jenkins_gitlab_service_settings.png)
## Plugin functional overview
GitLab does not contain a database table listing commits. Commits are always
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.
### Steps required to implement a similar integration
>**Note:**
All steps are implemented using AJAX requests on the merge request page.
1. In order to display the build status in a merge request you must create a project service in GitLab.
2. Your project service will do a (JSON) query to a URL of the CI tool with the SHA1 of the commit.
3. The project service builds this URL and payload based on project service settings and knowledge of the CI tool.
4. The response is parsed to give a response in GitLab (success/failed/pending).
## Troubleshooting
### Error in merge requests - "Could not connect to the CI server"
This integration relies on Jenkins reporting the build status back to GitLab via
the [Commit Status API](../api/commits.md#commit-status).
The error 'Could not connect to the CI server' usually means that GitLab did not
receive a build status update via the API. Either Jenkins was not properly
configured or there was an error reporting the status via the API.
1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access
2. [Configure a Jenkins project](#configure-a-jenkins-project), including the
'Publish build status to GitLab' post-build action.
# Jenkins CI (deprecated) service
>**Note:** In GitLab 8.3, Jenkins integration using the
[GitLab Hook Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Hook+Plugin)
was deprecated in favor of the
[GitLab Plugin](https://wiki.jenkins.io/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.io/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.io/display/JENKINS/GitLab+Hook+Plugin)
2. Set up jenkins project
![screen](img/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 set up a Deploy key](../ssh/README.md#deploy-keys).
### Jenkins service
Now navigate to GitLab services page and activate Jenkins
![screen](img/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.
# GitLab Jira development panel integration **[PREMIUM]**
> [Introduced][ee-2381] in [GitLab Premium][eep] 10.0.
Complementary to our [existing Jira][existing-jira] project integration, you're now able to integrate
GitLab projects with [Jira Development Panel][jira-development-panel]. Both can be used
simultaneously. This works with self-hosted GitLab or GitLab.com integrated with self-hosted Jira
or cloud Jira.
By doing this you can easily access related GitLab merge requests, branches, and commits directly from a Jira issue.
This integration connects all GitLab projects within a top-level group or a personal namespace to projects in the Jira instance.
A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group,
as well as projects of the top-level group's subgroups nesting down, are connected. Alternatively, you can specify
a GitLab personal namespace in the Jira configuration, which will then connect the projects in that personal namespace to Jira.
NOTE: **Note**:
Note this is different from the [existing Jira][existing-jira] project integration, where the mapping
is one GitLab project to the entire Jira instance.
We recommend that a GitLab group admin
or instance admin (in the case of self-hosted GitLab) set up the integration,
in order to simplify administration.
TIP: **Tip:**
Create and use a single-purpose "jira" user in GitLab, so that removing
regular users won't impact your integration.
## Requirements
### Self-hosted GitLab
If you are using self-hosted GitLab, make sure your GitLab instance is accessible by Jira.
- If you are connecting to Jira Cloud, make sure your instance is accessible via the internet.
- If you are using Jira Server, make sure your instance is accessible however your network is set up.
### GitLab.com
There are no special requirements if you are using GitLab.com.
## GitLab Configuration
1. In GitLab, create a new application in order to allow Jira to connect with your GitLab account
While logged-in, go to `Settings -> Applications`. (Click your profile avatar at
the top right, choose `Settings`, and then navigate to `Applications` from the left
navigation menu.) Use the form to create a new application.
Enter a useful name for the `Name` field.
For the `Redirect URI` field, enter `https://<your-gitlab-instance-domain>/login/oauth/callback`,
replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
this would be `https://gitlab.com/login/oauth/callback`.
NOTE: **Note**:
If using a GitLab version earlier than 11.3 the `Redirect URI` value should be `https://<your-gitlab-instance-domain>/-/jira/login/oauth/callback`.
![GitLab Application setup](img/jira_dev_panel_gl_setup_1.png)
- Check `api` in the Scopes section.
2. Click `Save application`. You will see the generated 'Application Id' and 'Secret' values.
Copy these values that you will use on the Jira configuration side.
## Jira Configuration
1. In Jira, from the gear menu at the top right, go to `Applications`. Navigate to `DVCS accounts`
from the left navigation menu. Click `Link GitHub account` to start creating a new integration.
(We are pretending to be GitHub in this integration until there is further platform support from Jira.)
![Jira DVCS from Dashboard](img/jira_dev_panel_jira_setup_1.png)
2. Complete the form
Select GitHub Enterprise for the `Host` field.
For the `Team or User Account` field, enter the relative path of a top-level GitLab group that you have access to,
or the relative path of your personal namespace.
![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
For the `Host URL` field, enter `https://<your-gitlab-instance-domain>/`,
replacing `<your-gitlab-instance-domain>` appropriately. So for example, if you are using GitLab.com,
this would be `https://gitlab.com/`.
NOTE: **Note**:
If using a GitLab version earlier than 11.3 the `Host URL` value should be `https://<your-gitlab-instance-domain>/-/jira`
For the `Client ID` field, use the `Application ID` value from the previous section.
For the `Client Secret` field, use the `Secret` value from the previous section.
Ensure that the rest of the checkboxes are checked.
3. Click `Add` to complete and create the integration.
Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches
for all the projects in the GitLab group you specified in the previous step. These are refreshed
every 60 minutes.
> **Note:**
> In the future, we plan on implementating real-time integration. If you need
> to refresh the data manually, you can do this from the `Applications -> DVCS
> accounts` screen where you initially set up the integration:
>
> ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the above
steps with additional Jira DVCS accounts.
You may now refer any Jira issue by its ID in branch names, commit messages and merge request names on GitLab's side,
and you will be able to see the linked `branches`, `commits`, and `merge requests` when entering a Jira issue
(inside the Jira issue, merge requests will be called "pull requests").
![Branch, Commit and Pull Requests links on Jira issue](img/jira_dev_panel_jira_setup_3.png)
Click the links to see your GitLab repository data.
![GitLab commits details on a Jira issue](img/jira_dev_panel_jira_setup_4.png)
![GitLab merge requests details on a Jira issue](img/jira_dev_panel_jira_setup_5.png)
## Limitations
- This integration is currently not supported on GitLab instances under a [relative url][relative-url] (e.g. `http://example.com/gitlab`).
## Changelog
### 11.10
- [Instance admins can now setup integration for all namespaces](https://gitlab.com/gitlab-org/gitlab-ee/issues/8902)
### 11.1
- [Support GitLab subgroups in Jira development panel](https://gitlab.com/gitlab-org/gitlab-ee/issues/3561)
[existing-jira]: ../user/project/integrations/jira.md
[jira-development-panel]: https://confluence.atlassian.com/adminjiraserver070/integrating-with-development-tools-776637096.html#Integratingwithdevelopmenttools-Developmentpanelonissues
[eep]: https://about.gitlab.com/pricing/
[ee-2381]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2381
[relative-url]: https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab
This diff is collapsed.
# SAML OmniAuth Provider # SAML OmniAuth Provider
> This topic is for SAML on self-managed GitLab instances. For SAML on GitLab.com, see [SAML SSO for GitLab.com Groups](https://docs.gitlab.com/ee/user/group/saml_sso/index.html).
NOTE: **Note:** NOTE: **Note:**
You need to [enable OmniAuth](omniauth.md) in order to use this. You need to [enable OmniAuth](omniauth.md) in order to use this.
...@@ -185,6 +187,78 @@ tell GitLab which groups are external via the `external_groups:` element: ...@@ -185,6 +187,78 @@ tell GitLab which groups are external via the `external_groups:` element:
} } } }
``` ```
## Required groups
>**Note:**
This setting is only available on GitLab 10.2 EE and above.
This setting works like `External Groups` setting. Just like there, your IdP has to
pass Group Information to GitLab, you have to tell GitLab where to look or the
groups SAML response, and which group membership should be requisite for logging in.
When `required_groups` is not set or it is empty, anyone with proper authentication
will be able to use the service.
Example:
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
required_groups: ['Developers', 'Managers', 'Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
} }
```
## Admin Groups
>**Note:**
This setting is only available on GitLab 8.8 EE and above.
This setting works very similarly to the `External Groups` setting. The requirements
are the same, your IdP needs to pass Group information to GitLab, you need to tell
GitLab where to look for the groups in the SAML response, and which group should be
considered `admin groups`.
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
admin_groups: ['Managers', 'Admins'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
} }
```
## Auditor Groups
>**Note:**
This setting is only available on GitLab 11.4 EE and above.
This setting also follows the requirements documented for the `External Groups` setting. GitLab uses the Group information provided by your IdP to determine if a user should be assigned the `auditor` role.
```yaml
{ name: 'saml',
label: 'Our SAML Provider',
groups_attribute: 'Groups',
auditor_groups: ['Auditors', 'Security'],
args: {
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
idp_sso_target_url: 'https://login.example.com/idp',
issuer: 'https://gitlab.example.com',
name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
} }
```
## Bypass two factor authentication ## Bypass two factor authentication
If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the If you want some SAML authentication methods to count as 2FA on a per session basis, you can register them in the
......
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