diff options
Diffstat (limited to 'doc/integration')
| -rw-r--r-- | doc/integration/README.md | 9 | ||||
| -rw-r--r-- | doc/integration/external-issue-tracker.md | 2 | ||||
| -rw-r--r-- | doc/integration/github.md | 46 | ||||
| -rw-r--r-- | doc/integration/google.md | 59 | ||||
| -rw-r--r-- | doc/integration/ldap.md | 5 | ||||
| -rw-r--r-- | doc/integration/omniauth.md | 53 | ||||
| -rw-r--r-- | doc/integration/slack.md | 42 | ||||
| -rw-r--r-- | doc/integration/twitter.md | 69 |
8 files changed, 166 insertions, 119 deletions
diff --git a/doc/integration/README.md b/doc/integration/README.md index 4773dd8fffb..00c73afd872 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,11 +1,12 @@ # GitLab Integration GitLab integrates with multiple third-party services to allow external issue trackers and external authentication. + See the documentation below for details on how to configure these services. -+ [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. -+ [LDAP](ldap.md) Set up sign in via LDAP -+ [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, and Google via OAuth. -+ [Slack](slack.md) Integrate with the Slack chat service +- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. +- [LDAP](ldap.md) Set up sign in via LDAP +- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, and Google via OAuth. +- [Slack](slack.md) Integrate with the Slack chat service Jenkins support is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jenkins.html). diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 1b531aeeda7..6245836bef1 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,3 +1,5 @@ +# External issue tracker + GitLab has a great issue tracker but you can also use an external issue tracker such as JIRA or Redmine. This is something that you can turn on per GitLab project. If for example you configure JIRA it provides the following functionality: - the 'Issues' link on the GitLab project pages takes you to the appropriate JIRA issue index; diff --git a/doc/integration/github.md b/doc/integration/github.md index 672536b4daf..b53a7c12857 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -2,18 +2,24 @@ To enable the GitHub OmniAuth provider you must register your application with GitHub. GitHub will generate a client ID and secret key for you to use. -1. Sign in to GitHub. -2. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. -3. Select "Applications" in the left menu. -4. Select "Register new application". -5. Provide the required details. - * Application name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - * Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' - * Application description: Fill this in if you wish. - * Authorization callback URL: 'https://gitlab.company.com/users/auth/github/callback' -6. Select "Register application". -7. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). Keep this page open as you continue configuration.  -8. On your GitLab server, open the configuration file. +1. Sign in to GitHub. + +1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. + +1. Select "Applications" in the left menu. + +1. Select "Register new application". + +1. Provide the required details. + - Application name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. + - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' + - Application description: Fill this in if you wish. + - Authorization callback URL: 'https://gitlab.company.com/users/auth/github/callback' +1. Select "Register application". + +1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). Keep this page open as you continue configuration.  + +1. On your GitLab server, open the configuration file. ```sh cd /home/git/gitlab @@ -21,8 +27,9 @@ To enable the GitHub OmniAuth provider you must register your application with G sudo -u git -H editor config/gitlab.yml ``` -9. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details. -10. Under `providers:` uncomment (or add) lines that look like the following: +1. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details. + +1. Under `providers:` uncomment (or add) lines that look like the following: ``` - { name: 'github', app_id: 'YOUR APP ID', @@ -30,9 +37,12 @@ To enable the GitHub OmniAuth provider you must register your application with G args: { scope: 'user:email' } } ``` -11. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. -12. Change 'YOUR APP SECRET' to the client secret from the GitHub application page from step 7. -13. Save the configuration file. -14. Restart GitLab for the changes to take effect. +1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. + +1. Change 'YOUR APP SECRET' to the client secret from the GitHub application page from step 7. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. On the sign in page there should now be a GitHub icon below the regular sign in form. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/google.md b/doc/integration/google.md index 50f63502e79..3cf546bd77e 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -2,28 +2,38 @@ To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use. -1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. -2. Select "Create Project". -3. Provide the project information - * Project name: 'GitLab' works just fine here. - * Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. -4. Refresh the page. You should now see your new project in the list. Click on the project. -5. Select "APIs & auth" in the left menu. -6. Select "Credentials" in the submenu. -7. Select "Create New Client ID". -8. Fill in the required information - * Application type: "Web Application" - * Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. - * Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' -9. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration.  -10. On your GitLab server, open the configuration file. +1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. + +1. Select "Create Project". + +1. Provide the project information + - Project name: 'GitLab' works just fine here. + - Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. +1. Refresh the page. You should now see your new project in the list. Click on the project. + +1. Select "APIs & auth" in the left menu. + +1. Select "Credentials" in the submenu. + +1. Select "Create New Client ID". + +1. Fill in the required information + - Application type: "Web Application" + - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. + - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' +1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration.  + +1. On your GitLab server, open the configuration file. + ```sh cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml ``` -11. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details. -12. Under `providers:` uncomment (or add) lines that look like the following: + +1. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details. + +1. Under `providers:` uncomment (or add) lines that look like the following: ``` - { name: 'google_oauth2', app_id: 'YOUR APP ID', @@ -31,10 +41,13 @@ To enable the Google OAuth2 OmniAuth provider you must register your application args: { access_type: 'offline', approval_prompt: '' } } ``` -13. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. -14. Change 'YOUR APP SECRET' to the client secret from the GitHub application page from step 7. -15. Save the configuration file. -16. Restart GitLab for the changes to take effect. +1. Change 'YOUR APP ID' to the client ID from the GitHub application page from step 7. + +1. Change 'YOUR APP SECRET' to the client secret from the GitHub application page from step 7. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. @@ -45,5 +58,5 @@ This further configuration is not required for Google authentication to function At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable. 1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window). -2. Scroll down until you find "Product Name". Change the product name to something more descriptive. -3. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. +1. Scroll down until you find "Product Name". Change the product name to something more descriptive. +1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md index b52c4a4b5e4..62bb957d951 100644 --- a/doc/integration/ldap.md +++ b/doc/integration/ldap.md @@ -1,14 +1,19 @@ # GitLab LDAP integration GitLab can be configured to allow your users to sign with their LDAP credentials to integrate with e.g. Active Directory. + The first time a user signs in with LDAP credentials, GitLab will create a new GitLab user associated with the LDAP Distinguished Name (DN) of the LDAP user. + GitLab user attributes such as nickname and email will be copied from the LDAP user entry. ## Enabling LDAP sign-in for existing GitLab users When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then the LDAP DN will be associated with the existing user. + If the LDAP email attribute is not found in GitLab's database, a new user is created. In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their LDAP email address, and then sign into GitLab via their LDAP credentials. + GitLab recognizes the following LDAP attributes as email addresses: `mail`, `email` and `userPrincipalName`. + If multiple LDAP email attributes are present, e.g. `mail: foo@bar.com` and `email: foo@example.com`, then the first attribute found wins -- in this case `foo@bar.com`. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 84a5a8e8c28..1b0bf9c5f64 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,18 +1,18 @@ # OmniAuth GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. Configuring -OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can -choose to sign in using any of the configured mechanisms. -+ [Initial OmniAuth Configuration](#initial-omniauth-configuration) -+ [Supported Providers](#supported-providers) -+ [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) +OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms. -### Initial OmniAuth Configuration +- [Initial OmniAuth Configuration](#initial-omniauth-configuration) +- [Supported Providers](#supported-providers) +- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) + +## Initial OmniAuth Configuration Before configuring individual OmniAuth providers there are a few global settings that need to be verified. -1. Open the configuration file<br /> +1. Open the configuration file. ```sh cd /home/git/gitlab @@ -20,7 +20,7 @@ Before configuring individual OmniAuth providers there are a few global settings sudo -u git -H editor config/gitlab.yml ``` -2. Find the section dealing with OmniAuth. The section will look similar to the following.<br /> +1. Find the section dealing with OmniAuth. The section will look similar to the following. ``` ## OmniAuth settings @@ -52,32 +52,33 @@ Before configuring individual OmniAuth providers there are a few global settings # args: { scope: 'user:email' } } ``` -3. Change `enabled` to `true`. -4. Consider the next two configuration options: `allow_single_sign_on` and `block_auto_created_users`. - * `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to +1. Change `enabled` to `true`. + +1. Consider the next two configuration options: `allow_single_sign_on` and `block_auto_created_users`. + + - `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to sign in via OmniAuth. - * `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will + - `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 they are able to sign in. - * **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware + - **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware that any user on the Internet will be able to successfully sign in to your GitLab without administrative approval. -5. Choose one or more of the Supported Providers below to continue configuration. -### Supported Providers +1. Choose one or more of the Supported Providers below to continue configuration. + +## Supported Providers -+ [GitHub](github.md) -+ [Google](google.md) -+ [Twitter](twitter.md) +- [GitHub](github.md) +- [Google](google.md) +- [Twitter](twitter.md) -### Enable OmniAuth for an Existing User +## Enable OmniAuth for an Existing User -Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user -originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an -OmniAuth provider for an existing user. +Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -2. Go to profile settings (the silhouette icon in the top right corner). -3. Select the "Account" tab. -4. Under "Social Accounts" select the desired OmniAuth provider, such as Twitter. -5. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. +1. Go to profile settings (the silhouette icon in the top right corner). +1. Select the "Account" tab. +1. Under "Social Accounts" select the desired OmniAuth provider, such as Twitter. +1. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 057871a4b8e..95cb0c6fae2 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -1,34 +1,36 @@ -# Slack integration +# Slack integration -### On Slack +## On Slack To enable Slack integration you must create an Incoming WebHooks integration on Slack; - -1. Sign in to [Slack](https://slack.com) (https://YOURSUBDOMAIN.slack.com/services) -2. Click on the Integrations menu at the top of the page. -3. Add a new Integration. -4. Pick Incoming WebHooks -5. Choose the channel name you want to send notifications to, in the Settings section -6. Add Integrations. - * Optional step; You can change bot's name and avatar by clicking "change the name of your bot", and "change the icon" after that you have to click "Save settings". +1. Sign in to [Slack](https://slack.com) (https://YOURSUBDOMAIN.slack.com/services) +1. Click on the Integrations menu at the top of the page. +1. Add a new Integration. +1. Pick Incoming WebHooks +1. Choose the channel name you want to send notifications to, in the Settings section +1. Add Integrations. + - Optional step; You can change bot's name and avatar by clicking "change the name of your bot", and "change the icon" after that you have to click "Save settings". Now, Slack is ready to get external hooks. Before you leave this page don't forget to get the Token that you'll need on GitLab. You can find it by clicking Expand button, located in the "Instructions for creating Incoming WebHooks" section. It's a random alpha-numeric text 24 characters long. -### On GitLab +## On GitLab After Slack is ready we need to setup GitLab. Here are the steps to achieve this. +1. Sign in to GitLab + +1. Pick the repository you want. + +1. Navigate to Settings -> Services -> Slack + +1. Fill in your Slack details -1. Sign in to GitLab -2. Pick the repository you want. -3. Navigate to Settings -> Services -> Slack -4. Fill in your Slack details - * Mark as active it - * Type your subdomain's prefix (If your subdomain is https://somedomain.slack.com you only have to type the somedomain) - * Type in the token you got from Slack - * Type in the channel name you want to use (eg. #announcements) + - Mark as active it + - Type your subdomain's prefix (If your subdomain is https://somedomain.slack.com you only have to type the somedomain) + - Type in the token you got from Slack + - Type in the channel name you want to use (eg. #announcements) Have fun :) -_P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them._ +*P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them.* diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 0440e2f21f3..d1b52927d30 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -1,27 +1,37 @@ # Twitter OAuth2 OmniAuth Provider -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client -ID and secret key for you to use. - -1. Sign in to [Twitter Developers](https://dev.twitter.com/) area. -2. Hover over the avatar in the top right corner and select "My applications." -3. Select "Create new app" -4. Fill in the application details. - * Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or +To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. + +1. Sign in to [Twitter Developers](https://dev.twitter.com/) area. + +1. Hover over the avatar in the top right corner and select "My applications." + +1. Select "Create new app" + +1. Fill in the application details. + - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - * Description: Create a description. - * Website: The URL to your GitLab installation. 'https://gitlab.example.com' - * Callback URL: 'https://gitlab.example.com/users/auth/github/callback' - * Agree to the "Rules of the Road." + - Description: Create a description. + - Website: The URL to your GitLab installation. 'https://gitlab.example.com' + - Callback URL: 'https://gitlab.example.com/users/auth/github/callback' + - Agree to the "Rules of the Road." +  -6. Select "Create your Twitter application." -7. Select the "Settings" tab. -8. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in the Twitter." -9. Select "Update settings" at the bottom to save changes. -10. Select the "API Keys" tab. -11. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. - -12. On your GitLab server, open the configuration file. +1. Select "Create your Twitter application." + +1. Select the "Settings" tab. + +1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in the Twitter." + +1. Select "Update settings" at the bottom to save changes. + +1. Select the "API Keys" tab. + +1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. + +  + +1. On your GitLab server, open the configuration file. ```sh cd /home/git/gitlab @@ -29,19 +39,22 @@ ID and secret key for you to use. sudo -u git -H editor config/gitlab.yml ``` -13. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) +1. Find the section dealing with OmniAuth. See [Initial OmniAuth Configuration](README.md#initial-omniauth-configuration) for more details. -14. Under `providers:` uncomment (or add) lines that look like the following: + +1. Under `providers:` uncomment (or add) lines that look like the following: ``` - { name: 'twitter', app_id: 'YOUR APP ID', app_secret: 'YOUR APP SECRET' } ``` -15. Change 'YOUR APP ID' to the API key from Twitter page in step 11. -16. Change 'YOUR APP SECRET' to the API secret from the Twitter page in step 11. -17. Save the configuration file. -18. Restart GitLab for the changes to take effect. +1. Change 'YOUR APP ID' to the API key from Twitter page in step 11. + +1. Change 'YOUR APP SECRET' to the API secret from the Twitter page in step 11. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the -authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. |