diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-05-20 17:34:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-05-20 17:34:42 +0300 |
commit | 9f46488805e86b1bc341ea1620b866016c2ce5ed (patch) | |
tree | f9748c7e287041e37d6da49e0a29c9511dc34768 /doc/integration | |
parent | dfc92d081ea0332d69c8aca2f0e745cb48ae5e6d (diff) |
Add latest changes from gitlab-org/gitlab@13-0-stable-ee
Diffstat (limited to 'doc/integration')
-rw-r--r-- | doc/integration/README.md | 2 | ||||
-rw-r--r-- | doc/integration/azure.md | 2 | ||||
-rw-r--r-- | doc/integration/elasticsearch.md | 89 | ||||
-rw-r--r-- | doc/integration/github.md | 7 | ||||
-rw-r--r-- | doc/integration/gitlab.md | 5 | ||||
-rw-r--r-- | doc/integration/img/gitlab_app.png | bin | 32020 -> 0 bytes | |||
-rw-r--r-- | doc/integration/img/jenkins_gitlab_service_settings.png | bin | 24094 -> 0 bytes | |||
-rw-r--r-- | doc/integration/jenkins.md | 210 | ||||
-rw-r--r-- | doc/integration/jenkins_deprecated.md | 3 | ||||
-rw-r--r-- | doc/integration/jira_development_panel.md | 9 | ||||
-rw-r--r-- | doc/integration/oauth_provider.md | 2 | ||||
-rw-r--r-- | doc/integration/omniauth.md | 2 | ||||
-rw-r--r-- | doc/integration/recaptcha.md | 2 | ||||
-rw-r--r-- | doc/integration/slash_commands.md | 6 | ||||
-rw-r--r-- | doc/integration/sourcegraph.md | 4 | ||||
-rw-r--r-- | doc/integration/vault.md | 3 |
16 files changed, 197 insertions, 149 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index bba38922b9d..f06cb5e4bb6 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -83,7 +83,7 @@ at Super User also has relevant information. **Omnibus Trusted Chain** [Install the self signed certificate or custom certificate authorities](https://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities) -in to GitLab Omnibus. +in to Omnibus GitLab. It is enough to concatenate the certificate to the main trusted certificate however it may be overwritten during upgrades: diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 75469fcbb98..809a3b703fc 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -22,7 +22,7 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap 1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`). -1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu.. +1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu. 1. Note the "CLIENT ID" and the "CLIENT SECRET". diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index fcd1c03a556..ae9d5bd8f60 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -48,12 +48,12 @@ For indexing Git repository data, GitLab uses an [indexer written in Go](https:/ The way you install the Go indexer depends on your version of GitLab: -- For GitLab Omnibus 11.8 and above, see [GitLab Omnibus](#gitlab-omnibus). -- For installations from source or older versions of GitLab Omnibus, install the indexer [From Source](#from-source). +- For Omnibus GitLab 11.8 and above, see [Omnibus GitLab](#omnibus-gitlab). +- For installations from source or older versions of Omnibus GitLab, install the indexer [From Source](#from-source). -### GitLab Omnibus +### Omnibus GitLab -Since GitLab 11.8 the Go indexer is included in GitLab Omnibus. +Since GitLab 11.8 the Go indexer is included in Omnibus GitLab. The former Ruby-based indexer was removed in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/issues/6481). ### From source @@ -152,8 +152,8 @@ The following Elasticsearch settings are available: | `AWS Access Key` | The AWS access key. | | `AWS Secret Access Key` | The AWS secret access key. | | `Maximum field length` | See [the explanation in instance limits.](../administration/instance_limits.md#maximum-field-length). | -| `Maximum bulk request size (MiB)` | Repository indexing uses the Elasticsearch bulk request API. This setting determines the maximum size of an individual bulk request during these operations. | -| `Bulk request concurrency` | Each repository indexing operation may submit bulk requests in parallel. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. | +| `Maximum bulk request size (MiB)` | The Maximum Bulk Request size is used by GitLab's Golang-based indexer processes and indicates how much data it ought to collect (and store in memory) in a given indexing process before submitting the payload to Elasticsearch’s Bulk API. This setting works in tandem with the Bulk request concurrency setting (see below) and needs to accomodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | +| `Bulk request concurrency` | The Bulk request concurrency indicates how many of GitLab's Golang-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to Elasticsearch’s Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting works in tandem with the Maximum bulk request size setting (see above) and needs to accomodate the resource constraints of both the Elasticsearch host(s) and the host(s) running GitLab's Golang-based indexer either from the `gitlab-rake` command or the Sidekiq tasks. | ### Limiting namespaces and projects @@ -174,7 +174,7 @@ If no namespaces or projects are selected, no Elasticsearch indexing will take p CAUTION: **Warning**: If you have already indexed your instance, you will have to regenerate the index in order to delete all existing data -for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:create_empty_index` and +for filtering to work correctly. To do this run the Rake tasks `gitlab:elastic:recreate_index` and `gitlab:elastic:clear_index_status`. Afterwards, removing a namespace or a project from the list will delete the data from the Elasticsearch index as expected. @@ -235,6 +235,8 @@ To index via the Admin Area: ### Indexing through Rake tasks +Indexing can be performed using Rake tasks. + #### Indexing small instances CAUTION: **Warning**: @@ -400,43 +402,32 @@ or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq For repository and snippet files, GitLab will only index up to 1 MiB of content, in order to avoid indexing timeouts. -## GitLab Elasticsearch Rake Tasks - -There are several Rake tasks available to you via the command line: - -- [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This is a wrapper task. It does the following: - - `sudo gitlab-rake gitlab:elastic:create_empty_index` - - `sudo gitlab-rake gitlab:elastic:clear_index_status` - - `sudo gitlab-rake gitlab:elastic:index_projects` - - `sudo gitlab-rake gitlab:elastic:index_snippets` -- [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This iterates over all projects and queues Sidekiq jobs to index them in the background. -- [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. -- [`sudo gitlab-rake gitlab:elastic:create_empty_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This generates an empty index on the Elasticsearch side, deleting the existing one if present. -- [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This deletes all instances of IndexStatus for all projects. -- [`sudo gitlab-rake gitlab:elastic:delete_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This removes the GitLab index on the Elasticsearch instance. -- [`sudo gitlab-rake gitlab:elastic:recreate_index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Does the same thing as `sudo gitlab-rake gitlab:elastic:create_empty_index` -- [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes the snippets data. -- [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Displays which projects are not indexed. -- [`sudo gitlab-rake gitlab:elastic:reindex_to_another_cluster[<SOURCE_CLUSTER_URL>,<DESTINATION_CLUSTER_URL>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Creates a new index in the destination cluster from the source index using - Elasticsearch "reindex from remote", where the source index is copied to the - destination. This is useful when migrating to a new cluster because it should be - quicker than reindexing via GitLab. - - NOTE: **Note:** - Your source cluster must be whitelisted in your destination cluster's Elasticsearch - settings. See [Reindex from remote](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html#reindex-from-remote). - -### Environment Variables +## GitLab Elasticsearch Rake tasks + +Rake tasks are available to: + +- [Build and install](#building-and-installing) the indexer. +- Delete indexes when [disabling Elasticsearch](#disabling-elasticsearch). +- [Add GitLab data](#adding-gitlabs-data-to-the-elasticsearch-index) to an index. + +The following are some available Rake tasks: + +| Task | Description | +|:--------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`sudo gitlab-rake gitlab:elastic:index`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:create_empty_index`, `gitlab:elastic:clear_index_status`, `gitlab:elastic:index_projects`, and `gitlab:elastic:index_snippets`. | +| [`sudo gitlab-rake gitlab:elastic:index_projects`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Iterates over all projects and queues Sidekiq jobs to index them in the background. | +| [`sudo gitlab-rake gitlab:elastic:index_projects_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. | +| [`sudo gitlab-rake gitlab:elastic:clear_index_status`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Deletes all instances of IndexStatus for all projects. | +| [`sudo gitlab-rake gitlab:elastic:create_empty_index[<INDEX_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Generates an empty index on the Elasticsearch side only if it doesn't already exist. | +| [`sudo gitlab-rake gitlab:elastic:delete_index[<INDEX_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Removes the GitLab index on the Elasticsearch instance. | +| [`sudo gitlab-rake gitlab:elastic:recreate_index[<INDEX_NAME>]`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Wrapper task for `gitlab:elastic:delete_index[<INDEX_NAME>]` and `gitlab:elastic:create_empty_index[<INDEX_NAME>]`. | +| [`sudo gitlab-rake gitlab:elastic:index_snippets`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Performs an Elasticsearch import that indexes the snippets data. | +| [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Displays which projects are not indexed. | + +NOTE: **Note:** +The `INDEX_NAME` parameter is optional and will use the default index name from the current `RAILS_ENV` if not set. + +### Environment variables In addition to the Rake tasks, there are some environment variables that can be used to modify the process: @@ -456,7 +447,7 @@ Indexing project repositories...I, [2019-03-04T21:27:03.083410 #3384] INFO -- : I, [2019-03-04T21:27:05.215266 #3384] INFO -- : Indexing GitLab User / test (ID=33) is done! ``` -## Elasticsearch Index Scopes +## Elasticsearch index scopes When performing a search, the GitLab index will use the following scopes: @@ -506,6 +497,8 @@ However, some larger installations may wish to tune the merge policy settings: ## Troubleshooting +### Common issues + Here are some common pitfalls and how to overcome them: - **How can I verify my GitLab instance is using Elasticsearch?** @@ -631,9 +624,13 @@ Here are some common pitfalls and how to overcome them: Gitlab::Elastic::Indexer::Error: time="2020-01-23T09:13:00Z" level=fatal msg="health check timeout: no Elasticsearch node available" ``` - You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticseach Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). + You probably have not used either `http://` or `https://` as part of your value in the **"URL"** field of the Elasticsearch Integration Menu. Please make sure you are using either `http://` or `https://` in this field as the [Elasticsearch client for Go](https://github.com/olivere/elastic) that we are using [needs the prefix for the URL to be accepted as valid](https://github.com/olivere/elastic/commit/a80af35aa41856dc2c986204e2b64eab81ccac3a). Once you have corrected the formatting of the URL, delete the index (via the [dedicated Rake task](#gitlab-elasticsearch-rake-tasks)) and [reindex the content of your instance](#adding-gitlabs-data-to-the-elasticsearch-index). +### Low level troubleshooting + +There is more [low level troubleshooting documentation](../administration/troubleshooting/elasticsearch.md) for when you experience other issues, including poor performance. + ### Known Issues - **[Elasticsearch `code_analyzer` doesn't account for all code cases](https://gitlab.com/gitlab-org/gitlab/issues/10693)** diff --git a/doc/integration/github.md b/doc/integration/github.md index c957fc24eb8..68971c510d5 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -138,11 +138,8 @@ You will also need to disable Git SSL verification on the server hosting GitLab. git config --global http.sslVerify false ``` -For the changes to take effect, [reconfigure GitLab] if you installed -via Omnibus, or [restart GitLab] if you installed from source. - -[reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure -[restart GitLab]: ../administration/restart_gitlab.md#installations-from-source +For the changes to take effect, [reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) if you installed +via Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) if you installed from source. ## Troubleshooting diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 4e62f6389c8..f423863ce8e 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -24,9 +24,8 @@ GitLab.com will generate an application ID and secret key for you to use. 1. Select **Save application**. -1. You should now see a **Application Id** and **Secret** near the top right of the page (see screenshot). - Keep this page open as you continue configuration. - ![GitLab app](img/gitlab_app.png) +1. You should now see an **Application ID** and **Secret**. Keep this page open as you continue + configuration. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/img/gitlab_app.png b/doc/integration/img/gitlab_app.png Binary files differdeleted file mode 100644 index 228e8a01305..00000000000 --- a/doc/integration/img/gitlab_app.png +++ /dev/null diff --git a/doc/integration/img/jenkins_gitlab_service_settings.png b/doc/integration/img/jenkins_gitlab_service_settings.png Binary files differdeleted file mode 100644 index 5a12e9cb39a..00000000000 --- a/doc/integration/img/jenkins_gitlab_service_settings.png +++ /dev/null diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 5514b756c00..485ca67c9fc 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -1,119 +1,163 @@ # 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 -integration settings. We may remove this in a future release and recommend -using the new 'Jenkins CI' integration 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/CD](../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. - -Videos are also available on [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) -and [Migrating from Jenkins to GitLab](https://www.youtube.com/watch?v=RlEVGOpYF5Y). - -## 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/CD 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. +NOTE: **Note:** +This documentation focuses only on how to **configure** a Jenkins *integration* with +GitLab. Learn how to **migrate** from Jenkins to GitLab CI/CD in our +[Migrating from Jenkins](../ci/jenkins/index.md) documentation. + +From GitLab, you can trigger a Jenkins build when you push code to a repository, or when a merge +request is created. In return, Jenkins shows the pipeline status on merge requests widgets and +on the GitLab project's home page. + +To better understand GitLab's Jenkins integration, watch the following video: + +- [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) +Use the Jenkins integration with GitLab when: + +- You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/README.md) in the future, but +need an interim solution. +- You're invested in [Jenkins Plugins](https://plugins.jenkins.io/) and choose to keep using Jenkins +to build your apps. For a real use case, read the blog post [Continuous integration: From Jenkins to GitLab using Docker](https://about.gitlab.com/blog/2017/07/27/docker-my-precious/). -NOTE: **Moving from a traditional CI plug-in to a single application for the entire software development lifecycle can decrease hours spent on maintaining toolchains by 10% or more.** -Visit the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html) to learn how our built-in CI compares to Jenkins. +Moving from a traditional CI plug-in to a single application for the entire software development +life cycle can decrease hours spent on maintaining toolchains by 10% or more. For more details, see +the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab.html). -## Requirements +## Configure GitLab integration with Jenkins -- [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 +GitLab's Jenkins integration requires installation and configuration in both GitLab and Jenkins. +In GitLab, you need to grant Jenkins access to the relevant projects. In Jenkins, you need to +install and configure several plugins. -## Configure GitLab users +### GitLab requirements -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. +- [Grant Jenkins permission to GitLab project](#grant-jenkins-access-to-gitlab-project) +- [Configure GitLab API access](#configure-gitlab-api-access) +- [Configure the GitLab project](#configure-the-gitlab-project) -Copy the private API token from **Profile Settings -> Account**. You will need this -when configuring the Jenkins server later. +### Jenkins requirements -## Configure the Jenkins server +- [Configure the Jenkins server](#configure-the-jenkins-server) +- [Configure the Jenkins project](#configure-the-jenkins-project) -Install [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin) -and [Jenkins Git Plugin](https://wiki.jenkins.io/display/JENKINS/Git+Plugin). +## Grant Jenkins access to GitLab project -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. +Grant a GitLab user access to the select GitLab projects. -For more information, see GitLab Plugin documentation about -[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication) +1. Create a new GitLab user, or choose an existing GitLab user. -![Jenkins GitLab plugin configuration](img/jenkins_gitlab_plugin_config.png) + This account will be used by Jenkins to access the GitLab projects. We recommend creating a GitLab + user for only this purpose. If you use a person's account, and their account is deactivated or + deleted, the GitLab-Jenkins integration will stop working. -## Configure a Jenkins project +1. Grant the user permission to the GitLab projects. -Follow the GitLab Plugin documentation about [Jenkins Job Configuration](https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration). + If you're integrating Jenkins with many GitLab projects, consider granting the user global + Admin permission. Otherwise, add the user to each project, and grant Developer permission. -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 GitLab API access -## Configure a GitLab project +Create a personal access token to authorize Jenkins' access to GitLab. -Create a new GitLab project or choose an existing one. Then, go to **Integrations -> -Jenkins CI**. +1. Log in to GitLab as the user to be used with Jenkins. +1. Click your avatar, then **Settings. +1. Click **Access Tokens** in the sidebar. +1. Create a personal access token with the **API** scope checkbox checked. For more details, see + [Personal access tokens](../user/profile/personal_access_tokens.md). +1. Record the personal access token's value, because it's required in [Configure the Jenkins server](#configure-the-jenkins-server). + +## Configure the Jenkins server -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. +Install and configure the Jenkins plugins. Both plugins must be installed and configured to +authorize the connection to GitLab. -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. +1. On the Jenkins server, go to **Manage Jenkins > Manage Plugins**. +1. Install the [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin). +1. Go to **Manage Jenkins > Configure System**. +1. In the **GitLab** section, check the **Enable authentication for ‘/project’ end-point** checkbox. +1. Click **Add**, then choose **Jenkins Credential Provider**. +1. Choose **GitLab API token** as the token type. +1. Enter the GitLab personal access token's value in the **API Token** field and click **Add**. +1. Enter the GitLab server's URL in the **GitLab host URL** field. +1. Click **Test Connection**, ensuring the connection is successful before proceeding. -Optionally, enter a username and password if your Jenkins server requires -authentication. +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) -![GitLab service settings](img/jenkins_gitlab_service_settings.png) +## Configure the Jenkins project + +Set up the Jenkins project you’re going to run your build on. + +1. On your Jenkins instance, go to **New Item**. +1. Enter the project's name. +1. Choose between **Freestyle** or **Pipeline** and click **OK**. + We recommend a Freestyle project, because the Jenkins plugin will update the build status on + GitLab. In a Pipeline project, you must configure a script to update the status on GitLab. +1. Choose your GitLab connection from the dropdown. +1. Check the **Build when a change is pushed to GitLab** checkbox. +1. Check the following checkboxes: + - **Accepted Merge Request Events** + - **Closed Merge Request Events** +1. Specify how build status is reported to GitLab: + - If you created a **Freestyle** project, in the **Post-build Actions** section, choose + **Publish build status to GitLab**. + - If you created a **Pipeline** project, you must use a Jenkins Pipeline script to update the status on + GitLab. + + Example Jenkins Pipeline script: + + ```groovy + pipeline { + agent any + + stages { + stage('gitlab') { + steps { + echo 'Notify GitLab' + updateGitlabCommitStatus name: 'build', state: 'pending' + updateGitlabCommitStatus name: 'build', state: 'success' + } + } + } + } + ``` + +## Configure the GitLab project + +Configure the GitLab integration with Jenkins. + +1. Create a new GitLab project or choose an existing one. +1. Go to **Settings > Integrations**, then select **Jenkins CI**. +1. Turn on the **Active** toggle. +1. Select the events you want GitLab to trigger a Jenkins build for: + - Push + - Merge request + - Tag push +1. Enter the **Jenkins URL**. +1. Enter the **Project name**. + + The project name should be URL-friendly, where spaces are replaced with underscores. To ensure + the project name is valid, copy it from your browser's address bar while viewing the Jenkins + project. +1. Enter the **Username** and **Password** if your Jenkins server requires + authentication. +1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. ## 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 +read from the repository directly. Therefore, it's 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:** +**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. @@ -133,7 +177,7 @@ 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 -1. [Configure a Jenkins project](#configure-a-jenkins-project), including the +1. [Configure the Jenkins project](#configure-the-jenkins-project), including the 'Publish build status to GitLab' post-build action. ### Merge Request event does not trigger a Jenkins Pipeline diff --git a/doc/integration/jenkins_deprecated.md b/doc/integration/jenkins_deprecated.md index af7f847f803..31bb271782a 100644 --- a/doc/integration/jenkins_deprecated.md +++ b/doc/integration/jenkins_deprecated.md @@ -6,6 +6,9 @@ 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). +NOTE: **Note:** +This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) + Integration includes: - Trigger Jenkins build after push to repo diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index 7753629c371..e9b1c9676bd 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -56,13 +56,16 @@ There are no special requirements 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`. + If using a GitLab version earlier than 11.3, the `Redirect URI` must be + `https://<your-gitlab-instance-domain>/-/jira/login/oauth/callback`. If you want Jira + to have access to all projects, GitLab recommends an administrator creates the + Application. ![GitLab Application setup](img/jira_dev_panel_gl_setup_1.png) - Check `api` in the Scopes section. -1. Click `Save application`. You will see the generated 'Application Id' and 'Secret' values. +1. 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 @@ -164,7 +167,7 @@ Click the links to see your GitLab repository data. ## Limitations -- This integration is currently not supported on GitLab instances under a [relative url](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab) (for example, `http://example.com/gitlab`). +- This integration is currently not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab) (for example, `http://example.com/gitlab`). ## Changelog diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 6c9b272f35b..fd1c21d725d 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -5,6 +5,8 @@ to sign in to other services. If you want to use: +- The [OAuth2](https://oauth.net/2/) protocol to access GitLab resources on user's behalf, + see [OAuth2 provider](../api/oauth2.md) - Other OAuth authentication service providers to sign in to GitLab, see the [OAuth2 client documentation](omniauth.md). - The related API, see [Applications API](../api/applications.md). diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 5634ad95cf7..2afdeccb764 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -51,7 +51,7 @@ that are in common for all providers that we need to consider. automatically create an account. It defaults to `false`. If `false` users must be created manually or they will not be able to sign in via OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](ldap.md) - integration enabled. It defaults to false. When enabled, users automatically + integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider will have their LDAP identity created in GitLab as well. - `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will have to be unblocked by an administrator before diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 4f3140e4cb9..bf2e6568ea6 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -27,7 +27,7 @@ configuration variable: proxy_set_header X-GitLab-Show-Login-Captcha 1; ``` -In GitLab Omnibus, this can be configured via `/etc/gitlab/gitlab.rb`: +In Omnibus GitLab, this can be configured via `/etc/gitlab/gitlab.rb`: ```ruby nginx['proxy_set_headers'] = { 'X-GitLab-Show-Login-Captcha' => 1 } diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 11abf3ca203..c73db32a42a 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -14,11 +14,11 @@ Taking the trigger term as `project-name`, the commands are: | ------- | ------ | | `/project-name help` | Shows all available slash commands | | `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>` | -| `/project-name issue show <id>` | Shows the issue with id `<id>` | -| `/project-name issue close <id>` | Closes the issue with id `<id>` | +| `/project-name issue show <id>` | Shows the issue with ID `<id>` | +| `/project-name issue close <id>` | Closes the issue with ID `<id>` | | `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | | `/project-name issue move <id> to <project>` | Moves issue ID `<id>` to `<project>` | -| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment to an issue with id `<id>` and comment body `<comment>` | +| `/project-name issue comment <id> <shift+return> <comment>` | Adds a new comment to an issue with ID `<id>` and comment body `<comment>` | | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | | `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 5da9dd1fbc9..90e9c7b9534 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -107,7 +107,7 @@ When visiting one of these views, you can now hover over a code reference to see ## Sourcegraph for GitLab.com -Sourcegraph powered code intelligence is avaialable for all public projects on GitLab.com. +Sourcegraph powered code intelligence is available for all public projects on GitLab.com. Support for private projects is currently not available for GitLab.com; follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201) @@ -117,7 +117,7 @@ for updates. ### Sourcegraph isn't working -If you enabled Sourcegraph for your project but still it doesn't looklike it's working, it might be because Sourcegraph has not indexed theproject yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. +If you enabled Sourcegraph for your project but still it doesn't look like it's working, it might be because Sourcegraph has not indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. ## Sourcegraph and Privacy diff --git a/doc/integration/vault.md b/doc/integration/vault.md index c29df9a24dc..0a6ced42925 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -1,4 +1,7 @@ --- +stage: Release +group: Release Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- |