Commit f4053e39 authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'kpaizee-github-ctrt-edits' into 'master'

CTRT edits for GitHub page - part 1

See merge request gitlab-org/gitlab!80073
parents 74f805e6 1c3977eb
......@@ -62,7 +62,7 @@ You may need to import projects from external sources like GitHub, Bitbucket, or
### Popular project imports
- [GitHub Enterprise to self-managed GitLab](../integration/github.md#enabling-github-oauth): Enabling OAuth makes it easier for developers to find and import their projects.
- [GitHub Enterprise to self-managed GitLab](../integration/github.md): Enabling OAuth makes it easier for developers to find and import their projects.
- [Bitbucket Server](../user/project/import/bitbucket_server.md#limitations): There are certain data limitations.
For assistance with these data types, contact your GitLab account manager or GitLab Support about our professional migration services.
......
......@@ -16,7 +16,7 @@ Watch a video on [Using GitLab CI/CD pipelines with GitHub repositories](https:/
NOTE:
Because of [GitHub limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/9147),
[GitHub OAuth](../../integration/github.md#enabling-github-oauth)
[GitHub OAuth](../../integration/github.md#enable-github-oauth-in-gitlab)
cannot be used to authenticate with GitHub as an external CI/CD repository.
## Connect with Personal Access Token
......
......@@ -4,48 +4,52 @@ 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:
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
your website could enable the covert redirect attack.
## Enabling GitHub OAuth
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.
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).
### Check for security vulnerabilities
When you create an OAuth 2 app in GitHub, you need the following information:
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.
- 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.
However, as far as we know, GitHub does not validate the subdomain part of the `redirect_uri`.
Therefore, a subdomain takeover, an XSS, or an open redirect on any subdomain of
your website could enable the covert redirect attack.
See [Configure initial settings](omniauth.md#configure-initial-settings) for initial settings.
## Enable GitHub OAuth in GitLab
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. [Configure the initial settings](omniauth.md#configure-initial-settings) in GitLab.
| 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 |
1. Edit the GitLab configuration file using the following information:
Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
| 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 |
**For Omnibus installations**
- **For Omnibus installations**
1. Edit `/etc/gitlab/gitlab.rb`:
1. Open the `/etc/gitlab/gitlab.rb` file.
For GitHub.com:
For GitHub.com, update the following section:
```ruby
gitlab_rails['omniauth_providers'] = [
......@@ -59,7 +63,8 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
]
```
For GitHub Enterprise:
For GitHub Enterprise, update the following section and replace
`https://github.example.com/` with your GitHub URL:
```ruby
gitlab_rails['omniauth_providers'] = [
......@@ -74,17 +79,14 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
]
```
**Replace `https://github.example.com/` with your GitHub URL.**
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
GitLab.
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
- **For installations from source**
---
1. Open the `config/gitlab.yml` file.
**For installations from source**
1. Navigate to your repository and edit `config/gitlab.yml`:
For GitHub.com:
For GitHub.com, update the following section:
```yaml
- { name: 'github',
......@@ -94,7 +96,8 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
args: { scope: 'user:email' } }
```
For GitHub Enterprise:
For GitHub Enterprise, update the following section and replace
`https://github.example.com/` with your GitHub URL:
```yaml
- { name: 'github',
......@@ -105,15 +108,13 @@ Follow these steps to incorporate the GitHub OAuth 2 app in your GitLab server:
args: { scope: 'user:email' } }
```
**Replace `https://github.example.com/` with your GitHub URL.**
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect.
---
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
GitLab.
1. Refresh the GitLab sign in page. You should now see a GitHub icon below the regular sign in form.
1. Refresh the GitLab sign-in page. A GitHub icon should display below the
sign-in form.
1. Click the icon to begin the authentication process. GitHub asks the user to sign in and authorize the GitLab application.
1. Select the icon. Sign in to GitHub and authorize the GitLab application.
## GitHub Enterprise with self-signed Certificate
......
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