@@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Integrate your GitLab instance with GitHub
You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to
enable users to import projects from GitHub or sign in to your GitLab instance
with your GitHub account.
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.
## Enabling GitHub OAuth
...
...
@@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover
See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next.
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.
| Setting from GitHub | Substitute in the GitLab configuration file | Description |
(order of hundred emails a day minimum to Gmail) for a few weeks at least".
- Have a very low rate of spam complaints from users.
- Emails must be authenticated via DKIM or SPF.
- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there.
- Before sending the final form ("Gmail Schema Whitelist Request"), you must
send a real email from your production server. This means that you must find
a way to send this email from the email address you are registering. You can
do this by forwarding the real email from the email address you are
registering. You can also go into the Rails console on the GitLab server and
trigger sending the email from there.
You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517).
@@ -64,7 +64,7 @@ Grant a GitLab user access to the select GitLab projects.
1. Grant the user permission to the GitLab projects.
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.
Administrator permission. Otherwise, add the user to each project, and grant Developer permission.
## Configure GitLab API access
...
...
@@ -166,7 +166,7 @@ to integrate GitLab and Jenkins.
1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**.
1. Click the **Generate** button under the **Secret Token** field.
1. Copy the resulting token, and save the job configuration.
1. In GitLab, create a webhook for your project, enter the trigger URL (e.g.`https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field.
1. In GitLab, create a webhook for your project, enter the trigger URL (such as`https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field.
1. After you add the webhook, click the **Test** button, and it should succeed.
## Troubleshooting
...
...
@@ -205,8 +205,8 @@ which is set to 10 seconds by default.
To fix this the `gitlab_rails['webhook_timeout']` value must be increased
in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md).
If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this
could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered):
If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`),
[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered):
@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4.
The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying
The Jira Development Panel integration allows you to reference Jira issues in GitLab, displaying
activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/)
in the issue.
...
...
@@ -35,7 +35,7 @@ See the [Configuration](#configuration) section for details.
With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage).
This integration connects all GitLab projects to projects in the Jira instance within either:
This integration connects all GitLab projects to projects in the Jira instance in either:
- A top-level group. 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
...
...
@@ -211,7 +211,7 @@ The requested scope is invalid, unknown, or malformed.
Potential resolutions:
- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api`within the query string.
- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string.
- If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes.
##### Jira error adding account and no repositories listed
...
...
@@ -314,6 +314,6 @@ For more information on using Jira Smart Commits to track time against an issue,
## Limitations
This integration is currently not supported on GitLab instances under a
This integration is not supported on GitLab instances under a
The GitLab OAuth applications support scopes, which allow various actions that any given
application can perform. The available scopes are depicted in the following table.
application can perform. The available scopes are depicted in the following table.
| Scope | Description |
| ------------------ | ----------- |
...
...
@@ -88,9 +87,9 @@ application can perform. The available scopes are depicted in the following tabl
| `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). |
| `read_registry` | Grants read-only access to container registry images on private projects. |
| `write_registry` | Grants read-only access to container registry images on private projects. |
| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an admin user. |
| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. |
| `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. |
| `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). |
| `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). |
At any time you can revoke any access by just clicking **Revoke**.
At any time you can revoke any access by clicking **Revoke**.
@@ -55,7 +55,7 @@ earlier version, you must explicitly enable it.
-`allow_single_sign_on` allows you to specify the providers you want to allow to
automatically create an account. It defaults to `false`. If `false` users must
be created manually or they can't sign in via OmniAuth.
be created manually or they can't sign in by using OmniAuth.
-`auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md)
integration enabled. It defaults to `false`. When enabled, users automatically
created through an OmniAuth provider have their LDAP identity created in GitLab as well.
...
...
@@ -66,7 +66,7 @@ earlier version, you must explicitly enable it.
NOTE:
If you set `block_auto_created_users` to `false`, make sure to only
define providers under `allow_single_sign_on` that you are able to control, like
SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on
SAML, Shibboleth, Crowd, or Google, or set it to `false` otherwise any user on
the Internet can successfully sign in to your GitLab without
administrative approval.
...
...
@@ -170,8 +170,8 @@ omniauth:
> Introduced in GitLab 8.7.
You can define which OmniAuth providers you want to be `external` so that all users
**creating accounts, or logging in via these providers** can't have
You can define which OmniAuth providers you want to be `external`. Users
creating accounts, or logging in by using these `external` providers cannot have
access to internal projects. You must use the full name of the provider,
like `google_oauth2` for Google. Refer to the examples for the full names of the
supported providers.
...
...
@@ -200,9 +200,9 @@ NOTE:
The following information only applies for installations from source.
GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships
with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that
is not enough and you need to integrate with other authentication solutions. For
these cases you can use the OmniAuth provider.
with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also
need to integrate with other authentication solutions. For
these cases, you can use the OmniAuth provider.
### Steps
...
...
@@ -251,10 +251,10 @@ we'd like to at least help those with specific needs.
> Introduced in GitLab 8.8.
Administrators are able to enable or disable Sign In via some OmniAuth providers.
Administrators are able to enable or disable Sign In by using some OmniAuth providers.
NOTE:
By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`.
By default Sign In is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`.
In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable.
...
...
@@ -345,7 +345,7 @@ omniauth:
Keep in mind that every sign-in attempt is redirected to the OmniAuth
provider; you can't sign in using local credentials. Ensure at least
one of the OmniAuth users has admin permissions.
one of the OmniAuth users has administrator permissions.
You may also bypass the auto sign in feature by browsing to
@@ -86,4 +86,6 @@ Click the icon to begin the authentication process. Salesforce asks the user to
If everything goes well, the user is returned to GitLab and is signed in.
NOTE:
GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email.
GitLab requires the email address of each new user. After the user is signed in
using Salesforce, GitLab redirects the user to the profile page where they must
The preferred approach for integrating a Shibboleth authentication system
with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older.
In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider.
To enable Shibboleth support in GitLab we need to use Apache instead of NGINX. (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package.) Apache uses `mod_shib2` module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider.
To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module.
The installation and configuration of the module itself is out of the scope of this document.
Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information.
Check [the Shibboleth documentation](https://wiki.shibboleth.net/confluence/display/SP3/Apache) for more information.
You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache).
The following changes are needed to enable Shibboleth:
1. Protect OmniAuth Shibboleth callback URL:
1. Protect the OmniAuth Shibboleth callback URL:
```apache
<Location /users/auth/shibboleth/callback>
...
...
@@ -53,7 +53,7 @@ The following changes are needed to enable Shibboleth:
```
NOTE:
Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
In GitLab versions 11.4 and later, OmniAuth is enabled by default. If you're using an
earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`.
1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider.
...
...
@@ -100,7 +100,7 @@ The following changes are needed to enable Shibboleth:
1.[Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you
installed GitLab via Omnibus or from source respectively.
On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in.
On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in.
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it.
Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it.
Commands are scoped to a project, with a trigger term that is specified during configuration.
...
...
@@ -28,8 +28,8 @@ Taking the trigger term as `project-name`, the commands are:
| `/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` |
Note that if you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for
your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage).
If you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for
your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage).
If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running.
If you are using an HTTPS connection to GitLab, you will need to[configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance.
If you are using an HTTPS connection to GitLab, you must[configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance.
### Connect your Sourcegraph instance to your GitLab instance
...
...
@@ -79,9 +79,9 @@ You can skip this step if you already have your GitLab repositories searchable i
1. In GitLab, go to **Admin Area > Settings > General**.
1. Expand the **Sourcegraph** configuration section.
1. Check **Enable Sourcegraph**.
1. Set the Sourcegraph URL to your Sourcegraph instance, e.g.,`https://sourcegraph.example.com`.
1. Set the Sourcegraph URL to your Sourcegraph instance, such as`https://sourcegraph.example.com`.
@@ -95,7 +95,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i
## Using Sourcegraph code intelligence
Once enabled, participating projects will have a code intelligence popover available in
Once enabled, participating projects display a code intelligence popover available in
the following code views:
- Merge request diffs
...
...
@@ -114,7 +114,7 @@ When visiting one of these views, you can now hover over a code reference to see
Sourcegraph powered code intelligence is available for all public projects on GitLab.com.
Support for private projects is currently not available for GitLab.com;
Support for private projects is not yet available for GitLab.com;
follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201)
for updates.
...
...
@@ -122,7 +122,7 @@ for updates.
### Sourcegraph isn't working
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.
If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have 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
...
...
@@ -130,5 +130,5 @@ From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integr
engine behind the native GitLab integration:
> Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com.
> They will only connect to Sourcegraph.com as required to provide code intelligence or other functionality on public code.
> They connect only to Sourcegraph.com as required to provide code intelligence or other functionality on public code.
> As a result, no private code, private repository names, usernames, or any other specific data is sent to Sourcegraph.com.
