Skip to content

G
gitlab-ce
Commit 68195a29 authored by Craig Norris's avatar Craig Norris
Browse files
Options

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
Show whitespace changes
Inline Side-by-side
Showing with 202 additions and 190 deletions
doc/administration/file_hooks.md
View file @ 68195a29
...@@ -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.
......
doc/administration/git_annex.md
View file @ 68195a29
...@@ -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
......
doc/administration/lfs/index.md
View file @ 68195a29
...@@ -12,11 +12,11 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.h ...@@ -12,11 +12,11 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.h
> - Support for object storage, such as AWS S3, was introduced in 10.0. > - Support for object storage, such as AWS S3, was introduced in 10.0.
> - LFS is enabled in GitLab self-managed instances by default. > - LFS is enabled in GitLab self-managed instances by default.
Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). Documentation about how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md).
## Requirements ## Requirements
- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. - Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 or later.
## Configuration ## Configuration
...@@ -25,9 +25,9 @@ GitLab is installed on. ...@@ -25,9 +25,9 @@ GitLab is installed on.
There are various configuration options to help GitLab server administrators: There are various configuration options to help GitLab server administrators:
- Enabling/disabling Git LFS support - Enabling/disabling Git LFS support.
- Changing the location of LFS object storage - Changing the location of LFS object storage.
- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html) - Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html).
### Configuration for Omnibus installations ### Configuration for Omnibus installations
...@@ -43,7 +43,7 @@ gitlab_rails['lfs_enabled'] = false ...@@ -43,7 +43,7 @@ gitlab_rails['lfs_enabled'] = false
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
``` ```
After you update settings in `/etc/gitlab/gitlab.rb`, make sure to run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). After you update settings in `/etc/gitlab/gitlab.rb`, run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure).
### Configuration for installations from source ### Configuration for installations from source
...@@ -58,14 +58,12 @@ In `config/gitlab.yml`: ...@@ -58,14 +58,12 @@ In `config/gitlab.yml`:
## Storing LFS objects in remote object storage ## Storing LFS objects in remote object storage
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2760) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. Brought to GitLab Core in 10.7. You can store LFS objects in remote object storage. This allows you
to offload reads and writes to the local disk, and free up disk space significantly.
It is possible to store LFS objects in remote object storage which allows you
to offload local hard disk R/W operations, and free up disk space significantly.
GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html) GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html)
to check which storage services can be integrated with GitLab. to check which storage services can be integrated with GitLab.
You can also use external object storage in a private local network. For example, You can also use external object storage in a private local network. For example,
[MinIO](https://min.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances. [MinIO](https://min.io/) is a standalone object storage service that works with GitLab instances.
GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload". GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload".
...@@ -78,26 +76,26 @@ This section describes the earlier configuration format. ...@@ -78,26 +76,26 @@ This section describes the earlier configuration format.
**Option 1. Direct upload** **Option 1. Direct upload**
1. User pushes an `lfs` file to the GitLab instance 1. User pushes an `lfs` file to the GitLab instance.
1. GitLab-workhorse uploads the file directly to the external object storage 1. GitLab-workhorse uploads the file directly to the external object storage.
1. GitLab-workhorse notifies GitLab-rails that the upload process is complete 1. GitLab-workhorse notifies GitLab-rails that the upload process is complete.
**Option 2. Background upload** **Option 2. Background upload**
1. User pushes an `lfs` file to the GitLab instance 1. User pushes an `lfs` file to the GitLab instance.
1. GitLab-rails stores the file in the local file storage 1. GitLab-rails stores the file in the local file storage.
1. GitLab-rails then uploads the file to the external object storage asynchronously 1. GitLab-rails then uploads the file to the external object storage asynchronously.
The following general settings are supported. The following general settings are supported.
| Setting | Description | Default | | Setting | Description | Default |
|---------|-------------|---------| |---------------------|-------------|---------|
| `enabled` | Enable/disable object storage | `false` | | `enabled` | Enable/disable object storage. | `false` |
| `remote_directory` | The bucket name where LFS objects will be stored| | | `remote_directory` | The bucket name where LFS objects are stored. | |
| `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | | `direct_upload` | Set to true to enable direct upload of LFS without the need of local shared storage. Option may be removed after we decide to support only single storage for all files. | `false` |
| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | | `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3. | `true` |
| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data. | `false` |
| `connection` | Various connection options described below | | | `connection` | Various connection options described below. | |
See [the available connection settings for different providers](../object_storage.md#connection-settings). See [the available connection settings for different providers](../object_storage.md#connection-settings).
...@@ -131,10 +129,9 @@ end ...@@ -131,10 +129,9 @@ end
### S3 for Omnibus installations ### S3 for Omnibus installations
On Omnibus installations, the settings are prefixed by `lfs_object_store_`: On Omnibus GitLab installations, the settings are prefixed by `lfs_object_store_`:
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines, replacing values based on your needs:
the values you want:
```ruby ```ruby
gitlab_rails['lfs_object_store_enabled'] = true gitlab_rails['lfs_object_store_enabled'] = true
...@@ -151,17 +148,17 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`: ...@@ -151,17 +148,17 @@ On Omnibus installations, the settings are prefixed by `lfs_object_store_`:
} }
``` ```
1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
1. Migrate any existing local LFS objects to the object storage: 1. Migrate any existing local LFS objects to the object storage:
```shell ```shell
gitlab-rake gitlab:lfs:migrate gitlab-rake gitlab:lfs:migrate
``` ```
This will migrate existing LFS objects to object storage. New LFS objects This migrates existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless are forwarded to object storage unless
`gitlab_rails['lfs_object_store_background_upload']` and `gitlab_rails['lfs_object_store_direct_upload']` is set to `false`. `gitlab_rails['lfs_object_store_background_upload']` and `gitlab_rails['lfs_object_store_direct_upload']` is set to `false`.
1. Optional: Verify all files migrated properly. 1. (Optional) Verify all files migrated properly.
From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database) From [PostgreSQL console](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database)
(`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: (`sudo gitlab-psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts:
...@@ -204,17 +201,17 @@ For source installations the settings are nested under `lfs:` and then ...@@ -204,17 +201,17 @@ For source installations the settings are nested under `lfs:` and then
path_style: true path_style: true
``` ```
1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect. 1. Save the file, and then [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
1. Migrate any existing local LFS objects to the object storage: 1. Migrate any existing local LFS objects to the object storage:
```shell ```shell
sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
``` ```
This will migrate existing LFS objects to object storage. New LFS objects This migrates existing LFS objects to object storage. New LFS objects
will be forwarded to object storage unless `background_upload` and `direct_upload` is set to are forwarded to object storage unless `background_upload` and `direct_upload` is set to
`false`. `false`.
1. Optional: Verify all files migrated properly. 1. (Optional) Verify all files migrated properly.
From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts: From PostgreSQL console (`sudo -u git -H psql -d gitlabhq_production`) verify `objectstg` below (where `file_store=2`) has count of all artifacts:
```shell ```shell
...@@ -233,7 +230,7 @@ For source installations the settings are nested under `lfs:` and then ...@@ -233,7 +230,7 @@ For source installations the settings are nested under `lfs:` and then
### Migrating back to local storage ### Migrating back to local storage
In order to migrate back to local storage: To migrate back to local storage:
1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab. 1. Set both `direct_upload` and `background_upload` to `false` under the LFS object storage settings. Don't forget to restart GitLab.
1. Run `rake gitlab:lfs:migrate_to_local` on your console. 1. Run `rake gitlab:lfs:migrate_to_local` on your console.
...@@ -241,17 +238,18 @@ In order to migrate back to local storage: ...@@ -241,17 +238,18 @@ In order to migrate back to local storage:
## Storage statistics ## Storage statistics
You can see the total storage used for LFS objects on groups and projects You can see the total storage used for LFS objects on groups and projects:
in the administration area, as well as through the [groups](../../api/groups.md)
and [projects APIs](../../api/projects.md). - In the administration area.
- In the [groups](../../api/groups.md) and [projects APIs](../../api/projects.md).
## Troubleshooting: `Google::Apis::TransmissionError: execution expired` ## Troubleshooting: `Google::Apis::TransmissionError: execution expired`
If LFS integration is configured with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`), If LFS integration is configured with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`),
Sidekiq workers may encounter this error. This is because the uploading timed out with very large files. Sidekiq workers may encounter this error. This is because the uploading timed out with very large files.
LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround. LFS files up to 6 GB can be uploaded without any extra steps, otherwise you need to use the following workaround.
Log into Rails console: Sign in to Rails console:
```shell ```shell
sudo gitlab-rails console sudo gitlab-rails console
...@@ -282,6 +280,6 @@ See more information in [!19581](https://gitlab.com/gitlab-org/gitlab-foss/-/mer ...@@ -282,6 +280,6 @@ See more information in [!19581](https://gitlab.com/gitlab-org/gitlab-foss/-/mer
- Support for removing unreferenced LFS objects was added in 8.14 onward. - Support for removing unreferenced LFS objects was added in 8.14 onward.
- LFS authentications via SSH was added with GitLab 8.12. - LFS authentications via SSH was added with GitLab 8.12.
- Only compatible with the Git LFS client versions 1.1.0 and up, or 1.0.2. - Only compatible with the Git LFS client versions 1.1.0 and later, or 1.0.2.
- The storage statistics currently count each LFS object multiple times for - The storage statistics count each LFS object multiple times for
every project linking to it. every project linking to it.
doc/integration/README.md
View file @ 68195a29
...@@ -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:
......
doc/integration/gmail_action_buttons_for_gitlab.md
View file @ 68195a29
...@@ -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).
doc/integration/jenkins_deprecated.md
View file @ 68195a29
...@@ -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
......
doc/integration/jira_development_panel.md
View file @ 68195a29
...@@ -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,25 +112,27 @@ If you're using GitLab.com and Jira Cloud, we recommend you use the ...@@ -114,25 +112,27 @@ 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.
...@@ -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."
......
doc/integration/omniauth.md
View file @ 68195a29
...@@ -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:
......
doc/integration/openid_connect_provider.md
View file @ 68195a29
...@@ -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
......
doc/push_rules/push_rules.md
View file @ 68195a29
...@@ -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)$
......
doc/topics/git/troubleshooting_git.md
View file @ 68195a29
...@@ -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.
......
doc/topics/gitlab_flow.md
View file @ 68195a29
...@@ -16,7 +16,7 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d ...@@ -16,7 +16,7 @@ It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-d
Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow.
This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. This article describes GitLab flow, which integrates the Git workflow with an issue tracking system.
It offers a simple, transparent, and effective way to work with Git. It offers a transparent and effective way to work with Git.
![Four stages (working copy, index, local repository, remote repository) and three steps between them](img/gitlab_flow_four_stages.png) ![Four stages (working copy, index, local repository, remote repository) and three steps between them](img/gitlab_flow_four_stages.png)
...@@ -28,7 +28,7 @@ After getting used to these three steps, the next challenge is the branching mod ...@@ -28,7 +28,7 @@ After getting used to these three steps, the next challenge is the branching mod
![Multiple long-running branches and merging in all directions](img/gitlab_flow_messy_flow.png) ![Multiple long-running branches and merging in all directions](img/gitlab_flow_messy_flow.png)
Since many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. Because many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy.
The biggest problem is that many long-running branches emerge that all contain part of the changes. The biggest problem is that many long-running branches emerge that all contain part of the changes.
People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. People have a hard time figuring out which branch has the latest code, or which branch to deploy to production.
Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html).
...@@ -51,7 +51,7 @@ The development happens on the `develop` branch, moves to a release branch, and ...@@ -51,7 +51,7 @@ The development happens on the `develop` branch, moves to a release branch, and
Git flow is a well-defined standard, but its complexity introduces two problems. Git flow is a well-defined standard, but its complexity introduces two problems.
The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production.
It is a convention to call your default branch `master` and to mostly branch from and merge to this. It is a convention to call your default branch `master` and to mostly branch from and merge to this.
Since most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. Because most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch.
The second problem of Git flow is the complexity introduced by the hotfix and release branches. The second problem of Git flow is the complexity introduced by the hotfix and release branches.
These branches can be a good idea for some organizations but are overkill for the vast majority of them. These branches can be a good idea for some organizations but are overkill for the vast majority of them.
...@@ -65,28 +65,32 @@ For example, many projects do releases but don't need to do hotfixes. ...@@ -65,28 +65,32 @@ For example, many projects do releases but don't need to do hotfixes.
## GitHub flow as a simpler alternative ## GitHub flow as a simpler alternative
![Master branch with feature branches merged in](img/gitlab_flow_github_flow.png) ![Branch with feature branches merged in](img/gitlab_flow_github_flow.png)
In reaction to Git flow, GitHub created a simpler alternative. In reaction to Git flow, GitHub created a simpler alternative.
[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch. [GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch.
This flow is clean and straightforward, and many organizations have adopted it with great success. This flow is clean and straightforward, and many organizations have adopted it with great success.
Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches. Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/git/simple-git-workflow-is-simple), although they rebase feature branches.
Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code, which is in line with lean and continuous delivery best practices. Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code. This approach is in line with lean and continuous delivery best practices.
However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues.
With GitLab flow, we offer additional guidance for these questions. With GitLab flow, we offer additional guidance for these questions.
## Production branch with GitLab flow ## Production branch with GitLab flow
![Master branch and production branch with an arrow that indicates a deployment](img/gitlab_flow_production_branch.png) ![Branches with an arrow that indicates a deployment](img/gitlab_flow_production_branch.png)
GitHub flow assumes you can deploy to production every time you merge a feature branch. GitHub flow assumes you can deploy to production every time you merge a feature branch.
While this is possible in some cases, such as SaaS applications, there are many cases where this is not possible. While this is possible in some cases, such as SaaS applications, there are some cases where this is not possible, such as:
One case is where you don't control the timing of a release, for example, an iOS application that is released when it passes App Store validation.
Another case is when you have deployment windows &mdash; for example, workdays from 10&nbsp;AM to 4&nbsp;PM when the operations team is at full capacity &mdash; but you also merge code at other times. - You don't control the timing of a release. For example, an iOS application that
is released when it passes App Store validation.
- You have deployment windows - for example, workdays from 10 AM to 4 PM when the
operations team is at full capacity - but you also merge code at other times.
In these cases, you can make a production branch that reflects the deployed code. In these cases, you can make a production branch that reflects the deployed code.
You can deploy a new version by merging `master` into the production branch. You can deploy a new version by merging `master` into the production branch.
If you need to know what code is in production, you can just checkout the production branch to see. If you need to know what code is in production, you can check out the production branch to see.
The approximate time of deployment is easily visible as the merge commit in the version control system. The approximate time of deployment is visible as the merge commit in the version control system.
This time is pretty accurate if you automatically deploy your production branch. This time is pretty accurate if you automatically deploy your production branch.
If you need a more exact time, you can have your deployment script create a tag on each deployment. If you need a more exact time, you can have your deployment script create a tag on each deployment.
This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow. This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow.
...@@ -109,10 +113,10 @@ If this is not possible because more manual testing is required, you can send me ...@@ -109,10 +113,10 @@ If this is not possible because more manual testing is required, you can send me
## Release branches with GitLab flow ## Release branches with GitLab flow
![Master and multiple release branches that vary in length with cherry-picks from master](img/gitlab_flow_release_branches.png) ![Multiple release branches that vary in length with cherry-picks](img/gitlab_flow_release_branches.png)
You only need to work with release branches if you need to release software to the outside world. You only need to work with release branches if you need to release software to the outside world.
In this case, each branch contains a minor version, for example, 2-3-stable, 2-4-stable, etc. In this case, each branch contains a minor version, such as `2-3-stable` or `2-4-stable`.
Create stable branches using `master` as a starting point, and branch as late as possible. Create stable branches using `master` as a starting point, and branch as late as possible.
By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches.
After announcing a release branch, only add serious bug fixes to the branch. After announcing a release branch, only add serious bug fixes to the branch.
...@@ -128,11 +132,11 @@ In this flow, it is not common to have a production branch (or Git flow `master` ...@@ -128,11 +132,11 @@ In this flow, it is not common to have a production branch (or Git flow `master`
![Merge request with inline comments](img/gitlab_flow_mr_inline_comments.png) ![Merge request with inline comments](img/gitlab_flow_mr_inline_comments.png)
Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches. Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches.
Tools such as GitHub and Bitbucket choose the name "pull request" since the first manual action is to pull the feature branch. Tools such as GitHub and Bitbucket choose the name "pull request", because the first manual action is to pull the feature branch.
Tools such as GitLab and others choose the name "merge request" since the final action is to merge the feature branch. Tools such as GitLab and others choose the name "merge request", because the final action is to merge the feature branch.
In this article, we'll refer to them as merge requests. This article refers to them as merge requests.
If you work on a feature branch for more than a few hours, it is good to share the intermediate result with the rest of the team. If you work on a feature branch for more than a few hours, share the intermediate result with the rest of your team.
To do this, create a merge request without assigning it to anyone. To do this, create a merge request without assigning it to anyone.
Instead, mention people in the description or a comment, for example, "/cc @mark @susan." Instead, mention people in the description or a comment, for example, "/cc @mark @susan."
This indicates that the merge request is not ready to be merged yet, but feedback is welcome. This indicates that the merge request is not ready to be merged yet, but feedback is welcome.
...@@ -147,7 +151,7 @@ Also, mention any other people from whom you would like feedback. ...@@ -147,7 +151,7 @@ Also, mention any other people from whom you would like feedback.
After the assigned person feels comfortable with the result, they can merge the branch. After the assigned person feels comfortable with the result, they can merge the branch.
If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging.
In GitLab, it is common to protect the long-lived branches, e.g., the `master` branch, so that [most developers can't modify them](../user/permissions.md). In GitLab, it is common to protect the long-lived branches, such as the `master` branch, so [most developers can't modify them](../user/permissions.md).
So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions.
After you merge a feature branch, you should remove it from the source control software. After you merge a feature branch, you should remove it from the source control software.
...@@ -169,10 +173,10 @@ GitLab flow is a way to make the relation between the code and the issue tracker ...@@ -169,10 +173,10 @@ GitLab flow is a way to make the relation between the code and the issue tracker
Any significant change to the code should start with an issue that describes the goal. Any significant change to the code should start with an issue that describes the goal.
Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small. Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small.
In GitLab, each change to the codebase starts with an issue in the issue tracking system. In GitLab, each change to the codebase starts with an issue in the issue tracking system.
If there is no issue yet, create the issue, as long as the change will take a significant amount of work, i.e., more than 1 hour. If there is no issue yet, create the issue if the change requires more than an hour's work.
In many organizations, raising an issue is part of the development process because they are used in sprint planning. In many organizations, raising an issue is part of the development process because they are used in sprint planning.
The issue title should describe the desired state of the system. The issue title should describe the desired state of the system.
For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Admin can't remove users." For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Administrators can't remove users."
When you are ready to code, create a branch for the issue from the `master` branch. When you are ready to code, create a branch for the issue from the `master` branch.
This branch is the place for any work related to this change. This branch is the place for any work related to this change.
...@@ -189,20 +193,20 @@ Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to pr ...@@ -189,20 +193,20 @@ Start the title of the merge request with `[Draft]`, `Draft:` or `(Draft)` to pr
When you think the code is ready, assign the merge request to a reviewer. When you think the code is ready, assign the merge request to a reviewer.
The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch.
When they press the merge button, GitLab merges the code and creates a merge commit that makes this event easily visible later on. When they press the merge button, GitLab merges the code and creates a merge commit that makes this event visible later on.
Merge requests always create a merge commit, even when the branch could be merged without one. Merge requests always create a merge commit, even when the branch could be merged without one.
This merge strategy is called "no fast-forward" in Git. This merge strategy is called "no fast-forward" in Git.
After the merge, delete the feature branch since it is no longer needed. After the merge, delete the feature branch, because it is no longer needed.
In GitLab, this deletion is an option when merging. In GitLab, this deletion is an option when merging.
Suppose that a branch is merged but a problem occurs and the issue is reopened. Suppose that a branch is merged but a problem occurs and the issue is reopened.
In this case, it is no problem to reuse the same branch name since the first branch was deleted when it was merged. In this case, it is no problem to reuse the same branch name, because the first branch was deleted when it was merged.
At any time, there is at most one branch for every issue. At any time, there is at most one branch for every issue.
It is possible that one feature branch solves more than one issue. It is possible that one feature branch solves more than one issue.
## Linking and closing issues from merge requests ## Linking and closing issues from merge requests
![Merge request showing the linked issues that will be closed](img/gitlab_flow_close_issue_mr.png) ![Merge request showing the linked issues to close](img/gitlab_flow_close_issue_mr.png)
Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12."
GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request.
...@@ -216,12 +220,12 @@ If you have an issue that spans across multiple repositories, create an issue fo ...@@ -216,12 +220,12 @@ If you have an issue that spans across multiple repositories, create an issue fo
![Vim screen showing the rebase view](img/gitlab_flow_rebase.png) ![Vim screen showing the rebase view](img/gitlab_flow_rebase.png)
With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them.
This functionality is useful if you want to replace a couple of small commits with a single commit, or if you want to make the order more logical. This feature helps you replace a couple of small commits with a single commit, or if you want to make the order more logical.
However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch.
Since rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers.
It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors. It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors.
Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed since the last review. Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed after the last review.
You should never rebase commits authored by other people unless you've agreed otherwise. You should never rebase commits authored by other people unless you've agreed otherwise.
Not only does this rewrite history, but it also loses authorship information. Not only does this rewrite history, but it also loses authorship information.
...@@ -229,7 +233,7 @@ Rebasing prevents the other authors from being attributed and sharing part of th ...@@ -229,7 +233,7 @@ Rebasing prevents the other authors from being attributed and sharing part of th
If a merge involves many commits, it may seem more difficult to undo. If a merge involves many commits, it may seem more difficult to undo.
You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature. You might consider solving this by squashing all the changes into one commit just before merging by using the GitLab [Squash-and-Merge](../user/project/merge_requests/squash_and_merge.md) feature.
Fortunately, there is an easy way to undo a merge with all its commits. Fortunately, you can undo a merge with all its commits.
The way to do this is by reverting the merge commit. The way to do this is by reverting the merge commit.
Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually.
...@@ -247,8 +251,8 @@ Often, people avoid merge commits by just using rebase to reorder their commits ...@@ -247,8 +251,8 @@ Often, people avoid merge commits by just using rebase to reorder their commits
Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history.
However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others. However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should avoid rebasing commits in a feature branch that you're sharing with others.
Rebasing could create more work, since every time you rebase, you may need to resolve the same conflicts. Rebasing could create more work, as every time you rebase, you may need to resolve the same conflicts.
Sometimes you can reuse recorded resolutions (`rerere`), but merging is better since you only have to resolve conflicts once. Sometimes you can reuse recorded resolutions (`rerere`), but merging is better, because you only have to resolve conflicts once.
Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase).
A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch.
...@@ -274,8 +278,8 @@ You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggl ...@@ -274,8 +278,8 @@ You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggl
NOTE: NOTE:
Don't confuse automatic branch testing with continuous integration. Don't confuse automatic branch testing with continuous integration.
Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): Martin Fowler makes this distinction in [an article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html):
"I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. "\[People\] say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit.
That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI." That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI."
In conclusion, you should try to prevent merge commits, but not eliminate them. In conclusion, you should try to prevent merge commits, but not eliminate them.
...@@ -289,19 +293,19 @@ If you rebase code, the history is incorrect, and there is no way for tools to r ...@@ -289,19 +293,19 @@ If you rebase code, the history is incorrect, and there is no way for tools to r
Another way to make your development work easier is to commit often. Another way to make your development work easier is to commit often.
Every time you have a working set of tests and code, you should make a commit. Every time you have a working set of tests and code, you should make a commit.
Splitting up work into individual commits provides context for developers looking at your code later. Splitting up work into individual commits provides context for developers looking at your code later.
Smaller commits make it clear how a feature was developed, and they make it easy to roll back to a specific good point in time or to revert one code change without reverting several unrelated changes. Smaller commits make it clear how a feature was developed. They help you roll back to a specific good point in time, or to revert one code change without reverting several unrelated changes.
Committing often also makes it easy to share your work, which is important so that everyone is aware of what you are working on. Committing often also helps you share your work, which is important so that everyone is aware of what you are working on.
You should push your feature branch frequently, even when it is not yet ready for review. You should push your feature branch frequently, even when it is not yet ready for review.
By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work. By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work.
Sharing your work before it's complete also allows for discussion and feedback about the changes, which can help improve the code before it gets to review. Sharing your work before it's complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review.
## How to write a good commit message ## How to write a good commit message
![Good and bad commit message](img/gitlab_flow_good_commit.png) ![Good and bad commit message](img/gitlab_flow_good_commit.png)
A commit message should reflect your intention, not just the contents of the commit. A commit message should reflect your intention, not just the contents of the commit.
It is easy to see the changes in a commit, so the commit message should explain why you made those changes. You can see the changes in a commit, so the commit message should explain why you made those changes.
An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." An example of a good commit message is: "Combine templates to reduce duplicate code in the user views."
The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. The words "change," "improve," "fix," and "refactor" don't add much information to a commit message.
For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation."
...@@ -315,12 +319,12 @@ In old workflows, the continuous integration (CI) server commonly ran tests on t ...@@ -315,12 +319,12 @@ In old workflows, the continuous integration (CI) server commonly ran tests on t
Developers had to ensure their code did not break the `master` branch. Developers had to ensure their code did not break the `master` branch.
When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks.
Therefore, each merge request must be tested before it is accepted. Therefore, each merge request must be tested before it is accepted.
CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to make this easy. CI software like Travis CI and GitLab CI/CD show the build results right in the merge request itself to simplify the process.
There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result.
Ideally, the server could also test the `master` branch after each change. Ideally, the server could also test the `master` branch after each change.
However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results.
Since feature branches should be short-lived, testing just the branch is an acceptable risk. Because feature branches should be short-lived, testing just the branch is an acceptable risk.
If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests.
As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller.
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7