diff options
Diffstat (limited to 'doc/integration/github.md')
| -rw-r--r-- | doc/integration/github.md | 298 |
1 files changed, 159 insertions, 139 deletions
diff --git a/doc/integration/github.md b/doc/integration/github.md index d8877e069b8..a265d5c67ed 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -4,198 +4,218 @@ group: Integrations 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/#assignments --- -# Integrate your GitLab instance with GitHub **(FREE SELF)** +# Use GitHub as an authentication provider **(FREE SELF)** -You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration -enables users to import projects from GitHub, or sign in to your GitLab instance -with their GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. +You can import projects from GitHub, or sign in to GitLab +with your GitHub credentials. -## Security check +## Create an OAuth app in GitHub -Some integrations risk compromising GitLab accounts. To help mitigate this -[OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) -vulnerability, append `/users/auth` to the end of the authorization callback URL. +To enable the GitHub OmniAuth provider, you need an OAuth 2.0 client ID and client +secret from GitHub: + +1. Sign in to GitHub. +1. [Create an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) + and provide the following information: + - The URL of your GitLab instance, such as `https://gitlab.example.com`. + - The authorization callback URL, such as, `https://gitlab.example.com/users/auth`. + Include the port number if your GitLab instance uses a non-default port. + +### Check for security vulnerabilities + +For some integrations, the [OAuth 2 covert redirect](https://oauth.net/advisories/2014-1-covert-redirect/) +vulnerability can compromise GitLab accounts. +To mitigate this vulnerability, append `/users/auth` to the authorization +callback URL. However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`. -This means that a subdomain takeover, an XSS, or an open redirect on any subdomain of +Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of your website could enable the covert redirect attack. -## Enabling GitHub OAuth +## Enable GitHub OAuth in GitLab -To enable the GitHub OmniAuth provider, you need an OAuth 2 Client ID and Client Secret from GitHub. To get these credentials, sign into GitHub and follow their procedure for [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). +1. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab. -When you create an OAuth 2 app in GitHub, you need the following information: +1. Edit the GitLab configuration file using the following information: -- The URL of your GitLab instance, such as `https://gitlab.example.com`. -- The authorization callback URL; in this case, `https://gitlab.example.com/users/auth`. Include the port number if your GitLab instance uses a non-default port. + | GitHub setting | Value in the GitLab configuration file | Description | + |----------------|----------------------------------------|-------------------------| + | Client ID | `YOUR_APP_ID` | OAuth 2.0 client ID | + | Client secret | `YOUR_APP_SECRET` | OAuth 2.0 client secret | + | URL | `https://github.example.com/` | GitHub deployment URL | -See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings. + - **For Omnibus installations** -After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps. + 1. Open the `/etc/gitlab/gitlab.rb` file. -| Setting from GitHub | Substitute in the GitLab configuration file | Description | -|:---------------------|:---------------------------------------------|:------------| -| Client ID | `YOUR_APP_ID` | OAuth 2 Client ID | -| Client Secret | `YOUR_APP_SECRET` | OAuth 2 Client Secret | -| URL | `https://github.example.com/` | GitHub Deployment URL | + For GitHub.com, update the following section: -Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server: + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + args: { scope: "user:email" } + } + ] + ``` -**For Omnibus installations** + For GitHub Enterprise, update the following section and replace + `https://github.example.com/` with your GitHub URL: -1. Edit `/etc/gitlab/gitlab.rb`: + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + args: { scope: "user:email" } + } + ] + ``` - For GitHub.com: + 1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab. - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - args: { scope: "user:email" } - } - ] - ``` + - **For installations from source** - For GitHub Enterprise: + 1. Open the `config/gitlab.yml` file. - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - url: "https://github.example.com/", - args: { scope: "user:email" } - } - ] - ``` + For GitHub.com, update the following section: - **Replace `https://github.example.com/` with your GitHub URL.** + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + args: { scope: 'user:email' } } + ``` -1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect. + For GitHub Enterprise, update the following section and replace + `https://github.example.com/` with your GitHub URL: ---- - -**For installations from source** + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + args: { scope: 'user:email' } } + ``` -1. Navigate to your repository and edit `config/gitlab.yml`: + 1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) + GitLab. - For GitHub.com: +1. Refresh the GitLab sign-in page. A GitHub icon should display below the + sign-in form. - ```yaml - - { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'user:email' } } - ``` +1. Select the icon. Sign in to GitHub and authorize the GitLab application. - For GitHub Enterprise: +## Troubleshooting - ```yaml - - { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - url: "https://github.example.com/", - args: { scope: 'user:email' } } - ``` +### Imports from GitHub Enterprise with a self-signed certificate fail - **Replace `https://github.example.com/` with your GitHub URL.** +When you import projects from GitHub Enterprise using a self-signed +certificate, the imports fail. -1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. +To fix this issue, you must disable SSL verification: ---- +1. Set `verify_ssl` to `false` in the configuration file. -1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form. + - **For Omnibus installations** -1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application. + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: "github", + # label: "Provider name", # optional label for login button, defaults to "GitHub" + app_id: "YOUR_APP_ID", + app_secret: "YOUR_APP_SECRET", + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: "user:email" } + } + ] + ``` -## GitHub Enterprise with self-signed Certificate + - **For installations from source** -If you are attempting to import projects from GitHub Enterprise with a self-signed -certificate and the imports are failing, you must disable SSL verification. -It should be disabled by adding `verify_ssl` to `false` in the provider configuration -and changing the global Git `sslVerify` option to `false` in the GitLab server. + ```yaml + - { name: 'github', + # label: 'Provider name', # optional label for login button, defaults to "GitHub" + app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: 'user:email' } } + ``` -For Omnibus package: +1. Change the global Git `sslVerify` option to `false` on the GitLab server. -```ruby -gitlab_rails['omniauth_providers'] = [ - { - name: "github", - # label: "Provider name", # optional label for login button, defaults to "GitHub" - app_id: "YOUR_APP_ID", - app_secret: "YOUR_APP_SECRET", - url: "https://github.example.com/", - verify_ssl: false, - args: { scope: "user:email" } - } -] -``` + - **For Omnibus installations** -You must also disable Git SSL verification on the server hosting GitLab. + ```ruby + omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } + ``` -```ruby -omnibus_gitconfig['system'] = { "http" => ["sslVerify = false"] } -``` + - **For installations from source** -For installation from source: + ```shell + git config --global http.sslVerify false + ``` -```yaml -- { name: 'github', - # label: 'Provider name', # optional label for login button, defaults to "GitHub" - app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - url: "https://github.example.com/", - verify_ssl: false, - args: { scope: 'user:email' } } -``` +1. [Reconfigure GitLab](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + if you installed using Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installations-from-source) + if you installed from source. -You must also disable Git SSL verification on the server hosting GitLab. +### Signing in using GitHub Enterprise returns a 500 error -```shell -git config --global http.sslVerify false -``` +This error can occur because of a network connectivity issue between your +GitLab instance and GitHub Enterprise. -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. +To check for a connectivity issue: -## Troubleshooting +1. Go to the [`production.log`](../administration/logs.md#productionlog) + on your GitLab server and look for the following error: -### Error 500 when trying to sign in to GitLab via GitHub Enterprise + ``` plaintext + Faraday::ConnectionFailed (execution expired) + ``` -Check the [`production.log`](../administration/logs.md#productionlog) -on your GitLab server to obtain further details. If you are getting the error like -`Faraday::ConnectionFailed (execution expired)` in the log, there may be a connectivity issue -between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) -and run the commands below replacing `<github_url>` with the URL of your GitHub Enterprise instance: +1. [Start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session) + and run the following commands. Replace `<github_url>` with the URL of your + GitHub Enterprise instance: -```ruby -uri = URI.parse("https://<github_url>") # replace `GitHub-URL` with the real one here -http = Net::HTTP.new(uri.host, uri.port) -http.use_ssl = true -http.verify_mode = 1 -response = http.request(Net::HTTP::Get.new(uri.request_uri)) -``` + ```ruby + uri = URI.parse("https://<github_url>") # replace `GitHub-URL` with the real one here + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = true + http.verify_mode = 1 + response = http.request(Net::HTTP::Get.new(uri.request_uri)) + ``` -If you are getting a similar `execution expired` error, it confirms the theory about the -network connectivity. In that case, make sure that the GitLab server is able to reach your -GitHub enterprise instance. +1. If a similar `execution expired` error is returned, this confirms the error is + caused by a connectivity issue. Make sure the GitLab server can reach + your GitHub Enterprise instance. ### Signing in using your GitHub account without a pre-existing GitLab account is not allowed -If you're getting the message `Signing in using your GitHub account without a pre-existing -GitLab account is not allowed. Create a GitLab account first, and then connect it to your -GitHub account` when signing in, in GitLab: +When you sign in to GitLab, you get the following error: + +```plaintext +Signing in using your GitHub account without a pre-existing +GitLab account is not allowed. Create a GitLab account first, +and then connect it to your GitHub account +``` + +To fix this issue, you must activate GitHub sign-in in GitLab: -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Account**. 1. In the **Social sign-in** section, select **Connect to GitHub**. - -After that, you should be able to sign in via GitHub successfully. |