Commit 68195a29 authored by Craig Norris's avatar Craig Norris

Merge branch 'docs-aqualls-create-6' into 'master'

More word and line revisions in Create docset

See merge request gitlab-org/gitlab!52754
parents 932156cd 709aa376
...@@ -19,19 +19,20 @@ directly to the GitLab source code and contribute back upstream. This way we can ...@@ -19,19 +19,20 @@ directly to the GitLab source code and contribute back upstream. This way we can
ensure functionality is preserved across versions and covered by tests. ensure functionality is preserved across versions and covered by tests.
NOTE: NOTE:
File hooks must be configured on the filesystem of the GitLab server. Only GitLab File hooks must be configured on the file system of the GitLab server. Only GitLab
server administrators will be able to complete these tasks. Explore server administrators can complete these tasks. Explore
[system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md) as an option if you do not have filesystem access. [system hooks](../system_hooks/system_hooks.md) or [webhooks](../user/project/integrations/webhooks.md)
as an option if you do not have file system access.
A file hook will run on each event so it's up to you to filter events or projects
within a file hook code. You can have as many file hooks as you want. Each file hook will A file hook runs on each event. You can filter events or projects
be triggered by GitLab asynchronously in case of an event. For a list of events in a file hook's code, and create many file hooks as you need. Each file hook is
triggered by GitLab asynchronously in case of an event. For a list of events
see the [system hooks](../system_hooks/system_hooks.md) documentation. see the [system hooks](../system_hooks/system_hooks.md) documentation.
## Setup ## Setup
The file hooks must be placed directly into the `file_hooks` directory, subdirectories The file hooks must be placed directly into the `file_hooks` directory, subdirectories
will be ignored. There is an are ignored. There is an
[`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples) [`example` directory inside `file_hooks`](https://gitlab.com/gitlab-org/gitlab/tree/master/file_hooks/examples)
where you can find some basic examples. where you can find some basic examples.
...@@ -52,23 +53,23 @@ Follow the steps below to set up a custom hook: ...@@ -52,23 +53,23 @@ Follow the steps below to set up a custom hook:
in any language, and ensure the 'shebang' at the top properly reflects the in any language, and ensure the 'shebang' at the top properly reflects the
language type. For example, if the script is in Ruby the shebang will language type. For example, if the script is in Ruby the shebang will
probably be `#!/usr/bin/env ruby`. probably be `#!/usr/bin/env ruby`.
1. The data to the file hook will be provided as JSON on STDIN. It will be exactly 1. The data to the file hook is provided as JSON on STDIN. It is exactly the
same as for [system hooks](../system_hooks/system_hooks.md). same as for [system hooks](../system_hooks/system_hooks.md).
That's it! Assuming the file hook code is properly implemented, the hook will fire That's it! Assuming the file hook code is properly implemented, the hook fires
as appropriate. The file hooks file list is updated for each event, there is no as appropriate. The file hooks file list is updated for each event, there is no
need to restart GitLab to apply a new file hook. need to restart GitLab to apply a new file hook.
If a file hook executes with non-zero exit code or GitLab fails to execute it, a If a file hook executes with non-zero exit code or GitLab fails to execute it, a
message will be logged to: message is logged to:
- `gitlab-rails/plugin.log` in an Omnibus installation. - `gitlab-rails/plugin.log` in an Omnibus installation.
- `log/plugin.log` in a source installation. - `log/plugin.log` in a source installation.
## Creating file hooks ## Creating file hooks
Below is an example that will only response on the event `project_create` and This example responds only on the event `project_create`, and
will inform the admins from the GitLab instance that a new project has been created. the GitLab instance informs the administrators that a new project has been created.
```ruby ```ruby
#!/opt/gitlab/embedded/bin/ruby #!/opt/gitlab/embedded/bin/ruby
...@@ -97,7 +98,7 @@ end ...@@ -97,7 +98,7 @@ end
Writing your own file hook can be tricky and it's easier if you can check it Writing your own file hook can be tricky and it's easier if you can check it
without altering the system. A Rake task is provided so that you can use it without altering the system. A Rake task is provided so that you can use it
in a staging environment to test your file hook before using it in production. in a staging environment to test your file hook before using it in production.
The Rake task will use a sample data and execute each of file hook. The output The Rake task uses a sample data and execute each of file hook. The output
should be enough to determine if the system sees your file hook and if it was should be enough to determine if the system sees your file hook and if it was
executed without errors. executed without errors.
......
...@@ -38,7 +38,7 @@ very fast file copying tool. ...@@ -38,7 +38,7 @@ very fast file copying tool.
## GitLab git-annex Configuration ## GitLab git-annex Configuration
`git-annex` is disabled by default in GitLab. Below you will find the `git-annex` is disabled by default in GitLab. Below are the
configuration options required to enable it. configuration options required to enable it.
### Requirements ### Requirements
...@@ -60,7 +60,7 @@ sudo yum install epel-release && sudo yum install git-annex ...@@ -60,7 +60,7 @@ sudo yum install epel-release && sudo yum install git-annex
### Configuration for Omnibus packages ### Configuration for Omnibus packages
For Omnibus GitLab packages, only one configuration setting is needed. For Omnibus GitLab packages, only one configuration setting is needed.
The Omnibus package will internally set the correct options in all locations. The Omnibus package internally sets the correct options in all locations.
1. In `/etc/gitlab/gitlab.rb` add the following line: 1. In `/etc/gitlab/gitlab.rb` add the following line:
...@@ -148,15 +148,15 @@ To example.com:group/project.git ...@@ -148,15 +148,15 @@ To example.com:group/project.git
ok ok
``` ```
Your files can be found in the `master` branch, but you'll notice that there Your files can be found in the `master` branch, but more branches are created
are more branches created by the `annex sync` command. by the `annex sync` command.
Git Annex will also create a new directory at `.git/annex/` and will record the Git Annex creates a new directory at `.git/annex/` and records the
tracked files in the `.git/config` file. The files you assign to be tracked tracked files in the `.git/config` file. The files you assign to be tracked
with `git-annex` will not affect the existing `.git/config` records. The files with `git-annex` don't affect the existing `.git/config` records. The files
are turned into symbolic links that point to data in `.git/annex/objects/`. are turned into symbolic links that point to data in `.git/annex/objects/`.
The `debian.iso` file in the example will contain the symbolic link: The `debian.iso` file in the example contain the symbolic link:
```plaintext ```plaintext
.git/annex/objects/ZW/1k/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.png/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.iso .git/annex/objects/ZW/1k/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.png/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.iso
...@@ -167,7 +167,7 @@ repository. ...@@ -167,7 +167,7 @@ repository.
--- ---
Downloading a single large file is also very simple: You can download a single large file with these commands:
```shell ```shell
git clone git@gitlab.example.com:group/project.git git clone git@gitlab.example.com:group/project.git
...@@ -185,7 +185,7 @@ git annex sync --content # sync Git branches and download all the large files ...@@ -185,7 +185,7 @@ git annex sync --content # sync Git branches and download all the large files
``` ```
By using `git-annex` without GitLab, anyone that can access the server can also By using `git-annex` without GitLab, anyone that can access the server can also
access the files of all projects, but GitLab Annex ensures that you can only access the files of all projects. GitLab Annex ensures that you can only
access files of projects you have access to (developer, maintainer, or owner role). access files of projects you have access to (developer, maintainer, or owner role).
## How it works ## How it works
......
This diff is collapsed.
...@@ -65,7 +65,9 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker, ...@@ -65,7 +65,9 @@ Integration with services such as Campfire, Flowdock, HipChat, Pivotal Tracker,
### SSL certificate errors ### SSL certificate errors
When trying to integrate GitLab with services that are using self-signed certificates, it is very likely that SSL certificate errors occur in different parts of the application, most likely Sidekiq. When trying to integrate GitLab with services using self-signed certificates,
SSL certificate errors can occur in different parts of the application. Sidekiq
is a common culprit.
There are two approaches you can take to solve this: There are two approaches you can take to solve this:
......
...@@ -15,20 +15,24 @@ If correctly set up, emails that require an action are marked in Gmail. ...@@ -15,20 +15,24 @@ If correctly set up, emails that require an action are marked in Gmail.
To get this functioning, you need to be registered with Google. For instructions, see To get this functioning, you need to be registered with Google. For instructions, see
[Register with Google](https://developers.google.com/gmail/markup/registering-with-google). [Register with Google](https://developers.google.com/gmail/markup/registering-with-google).
*This process has a lot of steps so make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.* This process has many steps. Make sure that you fulfill all requirements set by Google to avoid your application being rejected by Google.
In particular, note: In particular, note:
<!-- vale gitlab.InclusionCultural = NO -->
- The email account used by GitLab to send notification emails must: - The email account used by GitLab to send notification emails must:
- Have a "Consistent history of sending a high volume of mail from your domain - Have a "Consistent history of sending a high volume of mail from your domain
(order of hundred emails a day minimum to Gmail) for a few weeks at least". (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. - Have a very low rate of spam complaints from users.
- Emails must be authenticated via DKIM or SPF. - Emails must be authenticated via DKIM or SPF.
- Before sending the final form ("Gmail Schema Whitelist Request"), you must - 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 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 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 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 registering. You can also go into the Rails console on the GitLab server and
trigger sending the email from there. trigger sending the email from there.
<!-- vale gitlab.InclusionCultural = YES -->
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). 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).
...@@ -50,7 +50,7 @@ Now navigate to GitLab services page and activate Jenkins ...@@ -50,7 +50,7 @@ Now navigate to GitLab services page and activate Jenkins
![screen](img/jenkins_gitlab_service.png) ![screen](img/jenkins_gitlab_service.png)
Done! Now when you push to GitLab - it creates a build for Jenkins, and you can view the merge request build status with a link to the Jenkins build. Done! When you push to GitLab, it creates a build for Jenkins. You can view the merge request build status with a link to the Jenkins build.
### Multi-project Configuration ### Multi-project Configuration
......
...@@ -62,8 +62,8 @@ self-managed GitLab) set up the integration to simplify administration. ...@@ -62,8 +62,8 @@ self-managed GitLab) set up the integration to simplify administration.
### Jira DVCS configuration ### Jira DVCS configuration
If you're using GitLab.com and Jira Cloud, we recommend you use the If you're using GitLab.com and Jira Cloud, use the
[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. [GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector.
When configuring Jira DVCS Connector: When configuring Jira DVCS Connector:
...@@ -79,13 +79,11 @@ create and use a single-purpose `jira` user in GitLab. ...@@ -79,13 +79,11 @@ create and use a single-purpose `jira` user in GitLab.
1. In GitLab, create a new application to allow Jira to connect with your GitLab account. 1. In GitLab, create a new application to allow Jira to connect with your GitLab account.
While signed in to the GitLab account that you want Jira to use to connect to GitLab, 1. Sign in to the GitLab account that you want Jira to use to connect to GitLab.
click your profile avatar at the top right, and then click **Settings > Applications**. 1. In the top right corner, click your profile avatar.
Use the form to create a new application. 1. Click **Settings > Applications** to display the form to create a new application.
1. In the **Name** field, enter a descriptive name for the integration, such as `Jira`.
In the **Name** field, enter a descriptive name for the integration, such as `Jira`. 1. In the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`,
For the **Redirect URI** field, enter `https://<gitlab.example.com>/login/oauth/callback`,
replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com,
this would be `https://gitlab.com/login/oauth/callback`. this would be `https://gitlab.com/login/oauth/callback`.
...@@ -97,15 +95,15 @@ create and use a single-purpose `jira` user in GitLab. ...@@ -97,15 +95,15 @@ create and use a single-purpose `jira` user in GitLab.
![GitLab application setup](img/jira_dev_panel_gl_setup_1.png) ![GitLab application setup](img/jira_dev_panel_gl_setup_1.png)
- Check **API** in the Scopes section and uncheck any other checkboxes. 1. Check **API** in the Scopes section, and uncheck any other checkboxes.
1. Click **Save application**. GitLab displays the generated **Application ID** 1. Click **Save application**. GitLab displays the generated **Application ID**
and **Secret** values. Copy these values, which you use in Jira. and **Secret** values. Copy these values, which you use in Jira.
#### Jira DVCS Connector setup #### Jira DVCS Connector setup
If you're using GitLab.com and Jira Cloud, we recommend you use the If you're using GitLab.com and Jira Cloud, use the
[GitLab for Jira app](#gitlab-for-jira-app), unless you have a specific need for the DVCS Connector. [GitLab for Jira app](#gitlab-for-jira-app) unless you have a specific need for the DVCS Connector.
1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs). 1. Ensure you have completed the [GitLab configuration](#gitlab-account-configuration-for-dvcs).
1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**. 1. If you're using Jira Server, go to **Settings (gear) > Applications > DVCS accounts**.
...@@ -114,37 +112,39 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the ...@@ -114,37 +112,39 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the
(We're pretending to be GitHub in this integration, until there's additional platform support in Jira.) (We're pretending to be GitHub in this integration, until there's additional platform support in Jira.)
1. Complete the form: 1. Complete the form:
Select **GitHub Enterprise** for the **Host** field. 1. Select **GitHub Enterprise** for the **Host** field.
1. In the **Team or User Account** field, enter either:
In the **Team or User Account** field, enter the relative path of a top-level GitLab group that you have access to, - The relative path of a top-level GitLab group that you have access to.
or the relative path of your personal namespace. - The relative path of your personal namespace.
![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png) ![Creation of Jira DVCS integration](img/jira_dev_panel_jira_setup_2.png)
In the **Host URL** field, enter `https://<gitlab.example.com>/`, 1. In the **Host URL** field, enter `https://<gitlab.example.com>/`,
replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com, replacing `<gitlab.example.com>` with your GitLab instance domain. For example, if you are using GitLab.com,
this would be `https://gitlab.com/`. this would be `https://gitlab.com/`.
NOTE: NOTE:
If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira` If using a GitLab version earlier than 11.3 the **Host URL** value should be `https://<gitlab.example.com>/-/jira`
For the **Client ID** field, use the **Application ID** value from the previous section. 1. For the **Client ID** field, use the **Application ID** value from the previous section.
For the **Client Secret** field, use the **Secret** value from the previous section. 1. For the **Client Secret** field, use the **Secret** value from the previous section.
Ensure that the rest of the checkboxes are checked. 1. Ensure that the rest of the checkboxes are checked.
1. Click **Add** to complete and create the integration. 1. Click **Add** to complete and create the integration.
Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches Jira takes up to a few minutes to know about (import behind the scenes) all the commits and branches
for all the projects in the GitLab group you specified in the previous step. These are refreshed for all the projects in the GitLab group you specified in the previous step. These are refreshed
every 60 minutes. every 60 minutes.
In the future, we plan on implementing real-time integration. If you need In the future, we plan on implementing real-time integration. If you need
to refresh the data manually, you can do this from the `Applications -> DVCS to refresh the data manually, you can do this from the `Applications -> DVCS
accounts` screen where you initially set up the integration: accounts` screen where you initially set up the integration:
![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png) ![Refresh GitLab information in Jira](img/jira_dev_panel_manual_refresh.png)
To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous
steps with additional Jira DVCS accounts. steps with additional Jira DVCS accounts.
...@@ -252,7 +252,7 @@ resynchronize the information. To do so: ...@@ -252,7 +252,7 @@ resynchronize the information. To do so:
You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace. You can integrate GitLab.com and Jira Cloud using the [GitLab for Jira](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud) app in the Atlassian Marketplace.
This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time, while the DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method. This method is recommended when using GitLab.com and Jira Cloud because data is synchronized in real-time. The DVCS connector updates data only once per hour. If you are not using both of these environments, use the [Jira DVCS Connector](#jira-dvcs-configuration) method.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube. For a walkthrough of the integration with GitLab for Jira, watch [Configure GitLab Jira Integration using Marketplace App](https://youtu.be/SwR-g1s1zTo) on YouTube.
...@@ -285,7 +285,7 @@ For more information, see [Usage](#usage). ...@@ -285,7 +285,7 @@ For more information, see [Usage](#usage).
#### Troubleshooting GitLab for Jira #### Troubleshooting GitLab for Jira
The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies which can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in. The GitLab for Jira App uses an iframe to add namespaces on the settings page. Some browsers block cross-site cookies. This can lead to a message saying that the user needs to log in on GitLab.com even though the user is already logged in.
> "You need to sign in or sign up before continuing." > "You need to sign in or sign up before continuing."
......
...@@ -66,7 +66,7 @@ earlier version, you must explicitly enable it. ...@@ -66,7 +66,7 @@ earlier version, you must explicitly enable it.
NOTE: NOTE:
If you set `block_auto_created_users` to `false`, make sure to only 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 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. Otherwise, set it to `false`, or any user on
the Internet can successfully sign in to your GitLab without the Internet can successfully sign in to your GitLab without
administrative approval. administrative approval.
...@@ -168,8 +168,6 @@ omniauth: ...@@ -168,8 +168,6 @@ omniauth:
## Configure OmniAuth Providers as External ## Configure OmniAuth Providers as External
> Introduced in GitLab 8.7.
You can define which OmniAuth providers you want to be `external`. Users You can define which OmniAuth providers you want to be `external`. Users
creating accounts, or logging in by using these `external` providers cannot have 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, access to internal projects. You must use the full name of the provider,
...@@ -215,7 +213,7 @@ from the OmniAuth provider's documentation. ...@@ -215,7 +213,7 @@ from the OmniAuth provider's documentation.
sudo service gitlab stop sudo service gitlab stop
``` ```
- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile): - Add the gem to your [`Gemfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Gemfile):
```shell ```shell
gem "omniauth-your-auth-provider" gem "omniauth-your-auth-provider"
...@@ -240,25 +238,28 @@ from the OmniAuth provider's documentation. ...@@ -240,25 +238,28 @@ from the OmniAuth provider's documentation.
If you have successfully set up a provider that is not shipped with GitLab itself, If you have successfully set up a provider that is not shipped with GitLab itself,
please let us know. please let us know.
Share your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
You can help others by reporting successful configurations and probably share a You can help others by reporting successful configurations and probably share a
few insights or provide warnings for common errors or pitfalls by sharing your few insights or provide warnings for common errors or pitfalls.
experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations).
While we can't officially support every possible authentication mechanism out there, While we can't officially support every possible authentication mechanism out there,
we'd like to at least help those with specific needs. we'd like to at least help those with specific needs.
## Enable or disable Sign In with an OmniAuth provider without disabling import sources ## Enable or disable Sign In with an OmniAuth provider without disabling import sources
> Introduced in GitLab 8.8. Administrators are able to enable or disable **Sign In** by using some OmniAuth providers.
Administrators are able to enable or disable Sign In by using some OmniAuth providers.
NOTE: NOTE:
By default Sign In is enabled by using 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`.
To enable/disable an OmniAuth provider:
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. 1. In the top navigation bar, go to **Admin Area**.
1. In the left sidebar, go to **Settings**.
1. Scroll to the **Sign-in Restrictions** section, and click **Expand**.
1. Next to **Enabled OAuth Sign-In sources**, select the check box for each provider you want to enable or disable.
![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png) ![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png)
## Disabling OmniAuth ## Disabling OmniAuth
...@@ -325,7 +326,7 @@ omniauth: ...@@ -325,7 +326,7 @@ omniauth:
You can add the `auto_sign_in_with_provider` setting to your GitLab You can add the `auto_sign_in_with_provider` setting to your GitLab
configuration to redirect login requests to your OmniAuth provider for configuration to redirect login requests to your OmniAuth provider for
authentication, removing the need to click a button before actually signing in. authentication. This removes the need to click a button before actually signing in.
For example, when using the Azure integration, set the following to enable auto For example, when using the Azure integration, set the following to enable auto
sign-in: sign-in:
......
...@@ -17,8 +17,7 @@ OAuth 2.0 protocol. It allows clients to: ...@@ -17,8 +17,7 @@ OAuth 2.0 protocol. It allows clients to:
- Verify the identity of the end-user based on the authentication performed by GitLab. - Verify the identity of the end-user based on the authentication performed by GitLab.
- Obtain basic profile information about the end-user in an interoperable and REST-like manner. - Obtain basic profile information about the end-user in an interoperable and REST-like manner.
OIDC performs many of the same tasks as OpenID 2.0, OIDC performs many of the same tasks as OpenID 2.0, but is API-friendly and usable by native and
but does so in a way that is API-friendly and usable by native and
mobile applications. mobile applications.
On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails
......
...@@ -10,16 +10,16 @@ type: reference, howto ...@@ -10,16 +10,16 @@ type: reference, howto
Gain additional control over what can and can't be pushed to your repository by using Gain additional control over what can and can't be pushed to your repository by using
regular expressions to reject pushes based on commit contents, branch names or file details. regular expressions to reject pushes based on commit contents, branch names or file details.
## Overview
GitLab already offers [protected branches](../user/project/protected_branches.md), but there are GitLab already offers [protected branches](../user/project/protected_branches.md), but there are
cases when you need some specific rules like preventing Git tag removal or cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or
enforcing a special format for commit messages. enforcing a special format for commit messages.
Push rules are essentially [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) that are easy to Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you
enable in a user-friendly interface. They are defined globally if you are an can enable in a user-friendly interface. They are defined either:
admin or per project so you can have different rules applied to different
projects depending on your needs. - Globally if you are an administrator.
- Per project, so you can have different rules applied to different
projects depending on your needs.
## Use cases ## Use cases
...@@ -32,24 +32,24 @@ Let's assume you have the following requirements for your workflow: ...@@ -32,24 +32,24 @@ Let's assume you have the following requirements for your workflow:
- every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.` - every commit should reference a Jira issue, for example: `Refactored css. Fixes JIRA-123.`
- users should not be able to remove Git tags with `git push` - users should not be able to remove Git tags with `git push`
All you need to do is write a simple regular expression that requires the mention Write a regular expression that requires the mention
of a Jira issue in the commit message, like `JIRA\-\d+`. of a Jira issue in the commit message, like `JIRA\-\d+`.
Now when a user tries to push a commit with a message `Bugfix`, their push will Now when a user tries to push a commit with a message `Bugfix`, their push is
be declined. Only pushing commits with messages like `Bugfix according to JIRA-123` declined. Only pushing commits with messages like `Bugfix according to JIRA-123`
will be accepted. is accepted.
### Restrict branch names ### Restrict branch names
Let's assume there's a strict policy for branch names in your company, and If your company has a strict policy for branch names, you may want the branches to start
you want the branches to start with a certain name because you have different with a certain name. This approach enables different
GitLab CI/CD jobs (`feature`, `hotfix`, `docker`, `android`, etc.) that rely on the GitLab CI/CD jobs (such as `feature`, `hotfix`, `docker`, `android`) that rely on the
branch name. branch name.
Your developers, however, don't always remember that policy, so they might push to Your developers may not remember that policy, so they might push to
various branches, and CI pipelines might not work as expected. By restricting the various branches, and CI pipelines might not work as expected. By restricting the
branch names globally in Push Rules, such mistakes are prevented. branch names globally in Push Rules, such mistakes are prevented.
Any branch name that doesn't match your push rule will get rejected. Any branch name that doesn't match your push rule is rejected.
Note that the name of your default branch is always allowed, regardless of the branch naming Note that the name of your default branch is always allowed, regardless of the branch naming
regular expression (regex) specified. GitLab is configured this way regular expression (regex) specified. GitLab is configured this way
...@@ -64,7 +64,7 @@ which already limits users from pushing directly. ...@@ -64,7 +64,7 @@ which already limits users from pushing directly.
> Introduced in GitLab 12.10. > Introduced in GitLab 12.10.
By default, GitLab restricts certain formats of branch names for security purposes. By default, GitLab restricts certain formats of branch names for security purposes.
Currently 40-character hexadecimal names, similar to Git commit hashes, are prohibited. 40-character hexadecimal names, similar to Git commit hashes, are prohibited.
### Custom Push Rules **(FREE SELF)** ### Custom Push Rules **(FREE SELF)**
...@@ -77,7 +77,7 @@ See [server hooks](../administration/server_hooks.md) for more information. ...@@ -77,7 +77,7 @@ See [server hooks](../administration/server_hooks.md) for more information.
NOTE: NOTE:
GitLab administrators can set push rules globally under GitLab administrators can set push rules globally under
**Admin Area > Push Rules** that all new projects will inherit. You can later **Admin Area > Push Rules** that all new projects inherit. You can later
override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules). override them in a project's settings. They can be also set on a [group level](../user/group/index.md#group-push-rules).
1. Navigate to your project's **Settings > Repository** and expand **Push Rules** 1. Navigate to your project's **Settings > Repository** and expand **Push Rules**
...@@ -88,11 +88,11 @@ The following options are available: ...@@ -88,11 +88,11 @@ The following options are available:
| Push rule | Description | | Push rule | Description |
|---------------------------------|-------------| |---------------------------------|-------------|
| Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags will still be able to be deleted through the web UI. | | Removal of tags with `git push` | Forbid users to remove Git tags with `git push`. Tags can be deleted through the web UI. |
| Check whether author is a GitLab user | Restrict commits by author (email) to existing GitLab users. | | Check whether author is a GitLab user | Restrict commits by author (email) to existing GitLab users. |
| Committer restriction **(PREMIUM)** | GitLab will reject any commit that was not committed by the current authenticated user. | | Committer restriction **(PREMIUM)** | GitLab rejects any commit that was not committed by the current authenticated user. |
| Check whether commit is signed through GPG **(PREMIUM)** | Reject commit when it is not signed through GPG. Read [signing commits with GPG](../user/project/repository/gpg_signed_commits/index.md). | | Check whether commit is signed through GPG **(PREMIUM)** | Reject commit when it is not signed through GPG. Read [signing commits with GPG](../user/project/repository/gpg_signed_commits/index.md). |
| Prevent committing secrets to Git | GitLab will reject any files that are likely to contain secrets. Read [what files are forbidden](#prevent-pushing-secrets-to-the-repository). | | Prevent committing secrets to Git | GitLab rejects any files that are likely to contain secrets. Read [what files are forbidden](#prevent-pushing-secrets-to-the-repository). |
| Restrict by commit message | Only commit messages that match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | | Restrict by commit message | Only commit messages that match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. |
| Restrict by commit message (negative match) | Only commit messages that do not match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. | | Restrict by commit message (negative match) | Only commit messages that do not match this regular expression are allowed to be pushed. Leave empty to allow any commit message. Uses multiline mode, which can be disabled using `(?-m)`. |
| Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. Leave empty to allow any branch name. | | Restrict by branch name | Only branch names that match this regular expression are allowed to be pushed. Leave empty to allow any branch name. |
...@@ -108,8 +108,8 @@ GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular ...@@ -108,8 +108,8 @@ GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.12. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.12.
Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control. Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control.
GitLab allows you to turn on a predefined denylist of files which won't be allowed to be GitLab enables you to turn on a predefined denylist of files which can't be
pushed to a repository, stopping those commits from reaching the remote repository. pushed to a repository. The list stops those commits from reaching the remote repository.
By selecting the checkbox *Prevent committing secrets to Git*, GitLab prevents By selecting the checkbox *Prevent committing secrets to Git*, GitLab prevents
pushes to the repository when a file matches a regular expression as read from pushes to the repository when a file matches a regular expression as read from
...@@ -117,9 +117,9 @@ pushes to the repository when a file matches a regular expression as read from ...@@ -117,9 +117,9 @@ pushes to the repository when a file matches a regular expression as read from
as your GitLab version when viewing this file). as your GitLab version when viewing this file).
NOTE: NOTE:
Files already committed won't get restricted by this push rule. Files already committed aren't restricted by this push rule.
Below is an example list of what will be rejected by these regular expressions: Below is an example list of what GitLab rejects with these regular expressions:
```shell ```shell
##################### #####################
...@@ -204,13 +204,17 @@ Example: prevent a specific configuration file in a known directory from being p ...@@ -204,13 +204,17 @@ Example: prevent a specific configuration file in a known directory from being p
^directory-name\/config\.yml$ ^directory-name\/config\.yml$
``` ```
Example: prevent the specific file named `install.exe` from being pushed to any location in the repository. Note that the parenthesized expression `(^|\/)` will match either a file following a directory separator or a file in the root directory of the repository: Example: prevent the specific file named `install.exe` from being pushed to any
location in the repository. The parenthesized expression `(^|\/)` matches either
a file following a directory separator or a file in the root directory of the repository:
```plaintext ```plaintext
(^|\/)install\.exe$ (^|\/)install\.exe$
``` ```
Example: combining all of the above in a single expression. Note that all of the preceding expressions rely on the end of string character `$`, so we can move that part of each expression to the end of the grouped collection of match conditions where it will be appended to all matches: Example: combining all of the above in a single expression. The preceding expressions rely
on the end-of-string character `$`. We can move that part of each expression to the
end of the grouped collection of match conditions where it is appended to all matches:
```plaintext ```plaintext
(\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$ (\.exe|^config\.yml|^directory-name\/config\.yml|(^|\/)install\.exe)$
......
...@@ -14,7 +14,7 @@ with Git. ...@@ -14,7 +14,7 @@ with Git.
## Broken pipe errors on `git push` ## Broken pipe errors on `git push`
'Broken pipe' errors can occur when attempting to push to a remote repository. 'Broken pipe' errors can occur when attempting to push to a remote repository.
When pushing you will usually see: When pushing you usually see:
```plaintext ```plaintext
Write failed: Broken pipe Write failed: Broken pipe
...@@ -45,14 +45,13 @@ set to 50MB. The default is 1MB. ...@@ -45,14 +45,13 @@ set to 50MB. The default is 1MB.
**If pushing over SSH**, first check your SSH configuration as 'Broken pipe' **If pushing over SSH**, first check your SSH configuration as 'Broken pipe'
errors can sometimes be caused by underlying issues with SSH (such as errors can sometimes be caused by underlying issues with SSH (such as
authentication). Make sure that SSH is correctly configured by following the authentication). Make sure that SSH is correctly configured by following the
instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) docs. instructions in the [SSH troubleshooting](../../ssh/README.md#troubleshooting) documentation.
There's another option where you can prevent session timeouts by configuring If you're a GitLab administrator and have access to the server, you can also prevent
SSH 'keep alive' either on the client or on the server (if you are a GitLab session timeouts by configuring SSH `keep alive` either on the client or on the server.
admin and have access to the server).
NOTE: NOTE:
Configuring *both* the client and the server is unnecessary. Configuring both the client and the server is unnecessary.
**To configure SSH on the client side**: **To configure SSH on the client side**:
...@@ -67,7 +66,7 @@ Configuring *both* the client and the server is unnecessary. ...@@ -67,7 +66,7 @@ Configuring *both* the client and the server is unnecessary.
- On Windows, if you are using PuTTY, go to your session properties, then - On Windows, if you are using PuTTY, go to your session properties, then
navigate to "Connection" and under "Sending of null packets to keep navigate to "Connection" and under "Sending of null packets to keep
session active", set "Seconds between keepalives (0 to turn off)" to `60`. session active", set `Seconds between keepalives (0 to turn off)` to `60`.
**To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add: **To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add:
...@@ -125,7 +124,7 @@ MaxStartups 100:30:200 ...@@ -125,7 +124,7 @@ MaxStartups 100:30:200
``` ```
`100:30:200` means up to 100 SSH sessions are allowed without restriction, `100:30:200` means up to 100 SSH sessions are allowed without restriction,
after which 30% of connections will be dropped until reaching an absolute maximum of 200. after which 30% of connections are dropped until reaching an absolute maximum of 200.
Once configured, restart the SSH daemon for the change to take effect. Once configured, restart the SSH daemon for the change to take effect.
...@@ -140,7 +139,7 @@ sudo service sshd restart ...@@ -140,7 +139,7 @@ sudo service sshd restart
## Timeout during `git push` / `git pull` ## Timeout during `git push` / `git pull`
If pulling/pushing from/to your repository ends up taking more than 50 seconds, If pulling/pushing from/to your repository ends up taking more than 50 seconds,
a timeout will be issued with a log of the number of operations performed a timeout is issued. It contains a log of the number of operations performed
and their respective timings, like the example below: and their respective timings, like the example below:
```plaintext ```plaintext
...@@ -154,7 +153,7 @@ and provide GitLab with more information on how to improve the service. ...@@ -154,7 +153,7 @@ and provide GitLab with more information on how to improve the service.
## `git clone` over HTTP fails with `transfer closed with outstanding read data remaining` error ## `git clone` over HTTP fails with `transfer closed with outstanding read data remaining` error
If the buffer size is lower than what is allowed in the request, the action will fail with an error similar to the one below: If the buffer size is lower than what is allowed in the request, the action fails with an error similar to the one below:
```plaintext ```plaintext
error: RPC failed; curl 18 transfer closed with outstanding read data remaining error: RPC failed; curl 18 transfer closed with outstanding read data remaining
...@@ -163,7 +162,7 @@ fatal: early EOF ...@@ -163,7 +162,7 @@ fatal: early EOF
fatal: index-pack failed fatal: index-pack failed
``` ```
This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, the solution will be to set `http.postBuffer` to `524288000` so that the request only starts buffering after the first 524288000 bytes. This can be fixed by increasing the existing `http.postBuffer` value to one greater than the repository size. For example, if `git clone` fails when cloning a 500M repository, you should set `http.postBuffer` to `524288000`. That setting ensures the request only starts buffering after the first 524288000 bytes.
NOTE: NOTE:
The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured. The default value of `http.postBuffer`, 1 MiB, is applied if the setting is not configured.
......
This diff is collapsed.
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