Skip to content
Snippets Groups Projects
Commit 5abfc57e authored by Marcel Amirault's avatar Marcel Amirault Committed by Achilleas Pipinellis
Browse files

Fix spacing of code blocks 

Code blocks should not be spaced 4 times, as this will
prevent the code from being colored. They should
also be spaced the same as the lists they are a part
of, to make reading easier.
parent 84b49ef3
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 833 additions and 828 deletions
doc/administration/container_registry.md
+ 149
− 151
View file @ 5abfc57e
# GitLab Container Registry administration
 
> **Notes:**
>
> - [Introduced][ce-4040] in GitLab 8.8.
> - Container Registry manifest `v1` support was added in GitLab 8.9 to support
> Docker versions earlier than 1.10.
@@ -125,21 +123,21 @@ otherwise you will run into conflicts.
1. Your `/etc/gitlab/gitlab.rb` should contain the Registry URL as well as the
path to the existing TLS certificate and key used by GitLab:
 
```ruby
registry_external_url 'https://gitlab.example.com:4567'
```
```ruby
registry_external_url 'https://gitlab.example.com:4567'
```
 
Note how the `registry_external_url` is listening on HTTPS under the
existing GitLab URL, but on a different port.
Note how the `registry_external_url` is listening on HTTPS under the
existing GitLab URL, but on a different port.
 
If your TLS certificate is not in `/etc/gitlab/ssl/gitlab.example.com.crt`
and key not in `/etc/gitlab/ssl/gitlab.example.com.key` uncomment the lines
below:
If your TLS certificate is not in `/etc/gitlab/ssl/gitlab.example.com.crt`
and key not in `/etc/gitlab/ssl/gitlab.example.com.key` uncomment the lines
below:
 
```ruby
registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
```
```ruby
registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -150,12 +148,12 @@ otherwise you will run into conflicts.
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
configure it with the following settings:
 
```
registry:
enabled: true
host: gitlab.example.com
port: 4567
```
```
registry:
enabled: true
host: gitlab.example.com
port: 4567
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
@@ -188,17 +186,17 @@ Let's assume that you want the container Registry to be accessible at
`/etc/gitlab/ssl/registry.gitlab.example.com.key` and make sure they have
correct permissions:
 
```bash
chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
```
```bash
chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
```
 
1. Once the TLS certificate is in place, edit `/etc/gitlab/gitlab.rb` with:
 
```ruby
registry_external_url 'https://registry.gitlab.example.com'
```
```ruby
registry_external_url 'https://registry.gitlab.example.com'
```
 
Note how the `registry_external_url` is listening on HTTPS.
Note how the `registry_external_url` is listening on HTTPS.
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -219,11 +217,11 @@ look like:
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
configure it with the following settings:
 
```
registry:
enabled: true
host: registry.gitlab.example.com
```
```yaml
registry:
enabled: true
host: registry.gitlab.example.com
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
@@ -248,9 +246,9 @@ Registry application itself.
 
1. Open `/etc/gitlab/gitlab.rb` and set `registry['enable']` to `false`:
 
```ruby
registry['enable'] = false
```
```ruby
registry['enable'] = false
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -261,10 +259,10 @@ Registry application itself.
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
set `enabled` to `false`:
 
```
registry:
enabled: false
```
```yaml
registry:
enabled: false
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -280,9 +278,9 @@ the Container Registry by themselves, follow the steps below.
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['gitlab_default_projects_features_container_registry'] = false
```
```ruby
gitlab_rails['gitlab_default_projects_features_container_registry'] = false
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -293,16 +291,16 @@ the Container Registry by themselves, follow the steps below.
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `default_projects_features`
entry and configure it so that `container_registry` is set to `false`:
 
```
## Default project features settings
default_projects_features:
issues: true
merge_requests: true
wiki: true
snippets: false
builds: true
container_registry: false
```
```yaml
## Default project features settings
default_projects_features:
issues: true
merge_requests: true
wiki: true
snippets: false
builds: true
container_registry: false
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -332,9 +330,9 @@ The default location where images are stored in Omnibus, is
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
gitlab_rails['registry_path'] = "/path/to/registry/storage"
```
```ruby
gitlab_rails['registry_path'] = "/path/to/registry/storage"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -348,10 +346,10 @@ The default location where images are stored in source installations, is
1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
change the `path` setting:
 
```
registry:
path: shared/registry
```
```yaml
registry:
path: shared/registry
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -393,17 +391,17 @@ To configure the `s3` storage driver in Omnibus:
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
registry['storage'] = {
's3' => {
'accesskey' => 's3-access-key',
'secretkey' => 's3-secret-key-for-access-key',
'bucket' => 'your-s3-bucket',
'region' => 'your-s3-region',
'regionendpoint' => 'your-s3-regionendpoint'
}
}
```
```ruby
registry['storage'] = {
's3' => {
'accesskey' => 's3-access-key',
'secretkey' => 's3-secret-key-for-access-key',
'bucket' => 'your-s3-bucket',
'region' => 'your-s3-region',
'regionendpoint' => 'your-s3-regionendpoint'
}
}
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -442,9 +440,9 @@ In the examples below we set the Registry's port to `5001`.
 
1. Open `/etc/gitlab/gitlab.rb` and set `registry['registry_http_addr']`:
 
```ruby
registry['registry_http_addr'] = "localhost:5001"
```
```ruby
registry['registry_http_addr'] = "localhost:5001"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -455,10 +453,10 @@ In the examples below we set the Registry's port to `5001`.
1. Open the configuration file of your Registry server and edit the
[`http:addr`][registry-http-config] value:
 
```
http
addr: localhost:5001
```
```yaml
http
addr: localhost:5001
```
 
1. Save the file and restart the Registry server.
 
@@ -476,14 +474,14 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
 
1. Open `/etc/gitlab/gitlab.rb` and set necessary configurations:
 
```ruby
gitlab_rails['registry_enabled'] = true
gitlab_rails['registry_host'] = "registry.gitlab.example.com"
gitlab_rails['registry_port'] = "5005"
gitlab_rails['registry_api_url'] = "http://localhost:5000"
gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"
gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer"
```
```ruby
gitlab_rails['registry_enabled'] = true
gitlab_rails['registry_host'] = "registry.gitlab.example.com"
gitlab_rails['registry_port'] = "5005"
gitlab_rails['registry_api_url'] = "http://localhost:5000"
gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry"
gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer"
```
 
1. A certificate keypair is required for GitLab and the Container Registry to
communicate securely. By default omnibus-gitlab will generate one keypair,
@@ -492,19 +490,19 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
custom certificate key. To do that, add the following to
`/etc/gitlab/gitlab.rb`
 
```ruby
gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
# registry['internal_key'] should contain the contents of the custom key
# file. Line breaks in the key file should be marked using `\n` character
# Example:
registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
```
```ruby
gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"
# registry['internal_key'] should contain the contents of the custom key
# file. Line breaks in the key file should be marked using `\n` character
# Example:
registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
```
 
**Note:** The file specified at `registry_key_path` gets populated with the
content specified by `internal_key`, each time reconfigure is executed. If
no file is specified, omnibus-gitlab will default it to
`/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` and will populate
it.
**Note:** The file specified at `registry_key_path` gets populated with the
content specified by `internal_key`, each time reconfigure is executed. If
no file is specified, omnibus-gitlab will default it to
`/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.key` and will populate
it.
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -512,18 +510,18 @@ You can use GitLab as an auth endpoint and use a non-bundled Container Registry.
 
1. Open `/home/git/gitlab/config/gitlab.yml`, and edit the configuration settings under `registry`:
 
```
## Container Registry
```yaml
## Container Registry
 
registry:
enabled: true
host: "registry.gitlab.example.com"
port: "5005"
api_url: "http://localhost:5000"
path: /var/opt/gitlab/gitlab-rails/shared/registry
key: /var/opt/gitlab/gitlab-rails/certificate.key
issuer: omnibus-gitlab-issuer
```
registry:
enabled: true
host: "registry.gitlab.example.com"
port: "5005"
api_url: "http://localhost:5000"
path: /var/opt/gitlab/gitlab-rails/shared/registry
key: /var/opt/gitlab/gitlab-rails/certificate.key
issuer: omnibus-gitlab-issuer
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -550,20 +548,20 @@ To configure a notification endpoint in Omnibus:
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
registry['notifications'] = [
{
'name' => 'test_endpoint',
'url' => 'https://gitlab.example.com/notify',
'timeout' => '500ms',
'threshold' => 5,
'backoff' => '1s',
'headers' => {
"Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"]
}
}
]
```
```ruby
registry['notifications'] = [
{
'name' => 'test_endpoint',
'url' => 'https://gitlab.example.com/notify',
'timeout' => '500ms',
'threshold' => 5,
'backoff' => '1s',
'headers' => {
"Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"]
}
}
]
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -629,16 +627,16 @@ Start with a value between `25000000` (25MB) and `50000000` (50MB).
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
registry['storage'] = {
's3' => {
'accesskey' => 'AKIAKIAKI',
'secretkey' => 'secret123',
'bucket' => 'gitlab-registry-bucket-AKIAKIAKI',
'chunksize' => 25000000
}
}
```
```ruby
registry['storage'] = {
's3' => {
'accesskey' => 'AKIAKIAKI',
'secretkey' => 'secret123',
'bucket' => 'gitlab-registry-bucket-AKIAKIAKI',
'chunksize' => 25000000
}
}
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -648,14 +646,14 @@ Start with a value between `25000000` (25MB) and `50000000` (50MB).
 
1. Edit `config/gitlab.yml`:
 
```yaml
storage:
s3:
accesskey: 'AKIAKIAKI'
secretkey: 'secret123'
bucket: 'gitlab-registry-bucket-AKIAKIAKI'
chunksize: 25000000
```
```yaml
storage:
s3:
accesskey: 'AKIAKIAKI'
secretkey: 'secret123'
bucket: 'gitlab-registry-bucket-AKIAKIAKI'
chunksize: 25000000
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -669,9 +667,9 @@ You can add a configuration option for backwards compatibility.
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
registry['compatibility_schema1_enabled'] = true
```
```ruby
registry['compatibility_schema1_enabled'] = true
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -681,11 +679,11 @@ You can add a configuration option for backwards compatibility.
 
1. Edit the YML configuration file you created when you [deployed the registry][registry-deploy]. Add the following snippet:
 
```yaml
compatibility:
schema1:
enabled: true
```
```yaml
compatibility:
schema1:
enabled: true
```
 
1. Restart the registry for the changes to take affect.
 
@@ -694,9 +692,9 @@ You can add a configuration option for backwards compatibility.
A Docker connection error can occur when there are special characters in either the group,
project or branch name. Special characters can include:
 
* Leading underscore
* Trailing hyphen/dash
* Double hyphen/dash
- Leading underscore
- Trailing hyphen/dash
- Double hyphen/dash
 
To get around this, you can [change the group path](../user/group/index.md#changing-a-groups-path),
[change the project path](../user/project/settings/index.md#renaming-a-repository) or change the
doc/administration/database_load_balancing.md
+ 13
− 13
View file @ 5abfc57e
@@ -74,9 +74,9 @@ the following. This will balance the load between `host1.example.com` and
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['db_load_balancing'] = { 'hosts' => ['host1.example.com', 'host2.example.com'] }
```
```ruby
gitlab_rails['db_load_balancing'] = { 'hosts' => ['host1.example.com', 'host2.example.com'] }
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -86,16 +86,16 @@ the following. This will balance the load between `host1.example.com` and
 
1. Edit `/home/git/gitlab/config/database.yml` and add or amend the following lines:
 
```yaml
production:
username: gitlab
database: gitlab
encoding: unicode
load_balancing:
hosts:
- host1.example.com
- host2.example.com
```
```yaml
production:
username: gitlab
database: gitlab
encoding: unicode
load_balancing:
hosts:
- host1.example.com
- host2.example.com
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
doc/administration/incoming_email.md
+ 20
− 20
View file @ 5abfc57e
@@ -102,16 +102,16 @@ for a real-world example of this exploit.
 
1. Reconfigure GitLab for the changes to take effect:
 
```sh
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
```
```sh
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart
```
 
1. Verify that everything is configured correctly:
 
```sh
sudo gitlab-rake gitlab:incoming_email:check
```
```sh
sudo gitlab-rake gitlab:incoming_email:check
```
 
Reply by email should now be working.
 
@@ -119,31 +119,31 @@ Reply by email should now be working.
 
1. Go to the GitLab installation directory:
 
```sh
cd /home/git/gitlab
```
```sh
cd /home/git/gitlab
```
 
1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature
and fill in the details for your specific IMAP server and email account (see [examples](#config-examples) below).
 
1. Enable `mail_room` in the init script at `/etc/default/gitlab`:
 
```sh
sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
```
```sh
sudo mkdir -p /etc/default
echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab
```
 
1. Restart GitLab:
 
```sh
sudo service gitlab restart
```
```sh
sudo service gitlab restart
```
 
1. Verify that everything is configured correctly:
 
```sh
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
```
```sh
sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production
```
 
Reply by email should now be working.
 
doc/administration/issue_closing_pattern.md
+ 7
− 6
View file @ 5abfc57e
@@ -27,9 +27,10 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
1. Change the value of `gitlab_rails['gitlab_issue_closing_pattern']` to a regular
expression of your liking:
 
```ruby
gitlab_rails['gitlab_issue_closing_pattern'] = "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
```ruby
gitlab_rails['gitlab_issue_closing_pattern'] = "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
1. [Reconfigure] GitLab for the changes to take effect.
 
**For installations from source**
@@ -37,9 +38,9 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
1. Open `gitlab.yml` with your editor.
1. Change the value of `issue_closing_pattern`:
 
```yaml
issue_closing_pattern: "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
```yaml
issue_closing_pattern: "\b((?:[Cc]los(?:e[sd]|ing)|\b[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
 
1. [Restart] GitLab for the changes to take effect.
 
doc/administration/job_artifacts.md
+ 75
− 79
View file @ 5abfc57e
# Jobs artifacts administration
 
> **Notes:**
>
> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0.
> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`.
> - Starting with GitLab 8.17, builds are renamed to jobs.
@@ -21,9 +19,9 @@ To disable artifacts site-wide, follow the steps below.
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['artifacts_enabled'] = false
```
```ruby
gitlab_rails['artifacts_enabled'] = false
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -33,10 +31,10 @@ To disable artifacts site-wide, follow the steps below.
 
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
```yaml
artifacts:
enabled: false
```
```yaml
artifacts:
enabled: false
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -61,9 +59,9 @@ _The artifacts are stored by default in
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
```ruby
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -77,18 +75,16 @@ _The artifacts are stored by default in
1. To change the storage path for example to `/mnt/storage/artifacts`, edit
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
```yaml
artifacts:
enabled: true
path: /mnt/storage/artifacts
```
```yaml
artifacts:
enabled: true
path: /mnt/storage/artifacts
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
### Using object storage
 
> **Notes:**
>
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1762) in
> [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
> - Since version 9.5, artifacts are [browsable](../user/project/pipelines/job_artifacts.md#browsing-artifacts),
@@ -141,35 +137,35 @@ _The artifacts are stored by default in
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
the values you want:
 
```ruby
gitlab_rails['artifacts_enabled'] = true
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_remote_directory'] = "artifacts"
gitlab_rails['artifacts_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
NOTE: For GitLab 9.4+, if you are using AWS IAM profiles, be sure to omit the
AWS access key and secret access key/value pairs. For example:
```ruby
gitlab_rails['artifacts_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
```ruby
gitlab_rails['artifacts_enabled'] = true
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_remote_directory'] = "artifacts"
gitlab_rails['artifacts_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
NOTE: For GitLab 9.4+, if you are using AWS IAM profiles, be sure to omit the
AWS access key and secret access key/value pairs. For example:
```ruby
gitlab_rails['artifacts_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
1. Migrate any existing local artifacts to the object storage:
 
```bash
gitlab-rake gitlab:artifacts:migrate
```
```bash
gitlab-rake gitlab:artifacts:migrate
```
 
---
 
@@ -181,25 +177,25 @@ _The artifacts are stored by default in
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
artifacts:
enabled: true
object_store:
enabled: true
remote_directory: "artifacts" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
```yaml
artifacts:
enabled: true
object_store:
enabled: true
remote_directory: "artifacts" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
1. Migrate any existing local artifacts to the object storage:
 
```bash
sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production
```
```bash
sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production
```
 
## Expiring artifacts
 
@@ -217,9 +213,9 @@ steps below.
 
1. Edit `/etc/gitlab/gitlab.rb` and comment out or add the following line
 
```ruby
gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *"
```
```ruby
gitlab_rails['expire_build_artifacts_worker_cron'] = "50 * * * *"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -230,10 +226,10 @@ steps below.
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
expire_build_artifacts_worker:
cron: "50 * * * *"
```
```yaml
expire_build_artifacts_worker:
cron: "50 * * * *"
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -250,15 +246,15 @@ you can flip the feature flag from a Rails console.
 
1. Enter the Rails console:
 
```sh
sudo gitlab-rails console
```
```sh
sudo gitlab-rails console
```
 
1. Flip the switch and disable it:
 
```ruby
Feature.enable('ci_disable_validates_dependencies')
```
```ruby
Feature.enable('ci_disable_validates_dependencies')
```
 
---
 
@@ -266,16 +262,16 @@ you can flip the feature flag from a Rails console.
 
1. Enter the Rails console:
 
```sh
cd /home/git/gitlab
RAILS_ENV=production sudo -u git -H bundle exec rails console
```
```sh
cd /home/git/gitlab
RAILS_ENV=production sudo -u git -H bundle exec rails console
```
 
1. Flip the switch and disable it:
 
```ruby
Feature.enable('ci_disable_validates_dependencies')
```
```ruby
Feature.enable('ci_disable_validates_dependencies')
```
 
## Set the maximum file size of the artifacts
 
doc/administration/job_traces.md
+ 24
− 24
View file @ 5abfc57e
@@ -25,11 +25,11 @@ To change the location where the job logs will be stored, follow the steps below
 
**In Omnibus installations:**
 
1. Edit `/etc/gitlab/gitlab.rb` and add or amend the following line:
1. Edit `/etc/gitlab/gitlab.rb` and add or amend the following line:
 
```
gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds'
```
```ruby
gitlab_ci['builds_directory'] = '/mnt/to/gitlab-ci/builds'
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -39,12 +39,12 @@ To change the location where the job logs will be stored, follow the steps below
 
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
```yaml
gitlab_ci:
# The location where build traces are stored (default: builds/).
# Relative paths are relative to Rails.root.
builds_path: path/to/builds/
```
```yaml
gitlab_ci:
# The location where build traces are stored (default: builds/).
# Relative paths are relative to Rails.root.
builds_path: path/to/builds/
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -67,24 +67,24 @@ To archive those legacy job traces, please follow the instruction below.
 
1. Execute the following command
 
```bash
gitlab-rake gitlab:traces:archive
```
```bash
gitlab-rake gitlab:traces:archive
```
 
After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes)
for migrating job trace files from local storage to object storage.
It could take time to complete the all migration jobs. You can check the progress by the following command
After you executed this task, GitLab instance queues up Sidekiq jobs (asynchronous processes)
for migrating job trace files from local storage to object storage.
It could take time to complete the all migration jobs. You can check the progress by the following command
 
```bash
sudo gitlab-rails console
```
```bash
sudo gitlab-rails console
```
 
```bash
[1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace']
=> 100
```
```bash
[1] pry(main)> Sidekiq::Stats.new.queues['pipeline_background:archive_trace']
=> 100
```
 
If the count becomes zero, the archiving processes are done
If the count becomes zero, the archiving processes are done
 
## How to migrate archived job traces to object storage
 
doc/administration/merge_request_diffs.md
+ 58
− 58
View file @ 5abfc57e
@@ -21,18 +21,18 @@ To enable external storage of merge request diffs, follow the instructions below
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['external_diffs_enabled'] = true
```
```ruby
gitlab_rails['external_diffs_enabled'] = true
```
 
1. _The external diffs will be stored in in
`/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path,
for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb`
and add the following line:
 
```ruby
gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
```
```ruby
gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
```
 
1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -41,21 +41,21 @@ To enable external storage of merge request diffs, follow the instructions below
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
external_diffs:
enabled: true
```
```yaml
external_diffs:
enabled: true
```
 
1. _The external diffs will be stored in
`/home/git/gitlab/shared/external-diffs`._ To change the path, for example,
to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml`
and add or amend the following lines:
 
```yaml
external_diffs:
enabled: true
storage_path: /mnt/storage/external-diffs
```
```yaml
external_diffs:
enabled: true
storage_path: /mnt/storage/external-diffs
```
 
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -101,28 +101,28 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
the values you want:
 
```ruby
gitlab_rails['external_diffs_enabled'] = true
gitlab_rails['external_diffs_object_store_enabled'] = true
gitlab_rails['external_diffs_object_store_remote_directory'] = "external-diffs"
gitlab_rails['external_diffs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
Note that, if you are using AWS IAM profiles, be sure to omit the
AWS access key and secret access key/value pairs. For example:
```ruby
gitlab_rails['external_diffs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
```ruby
gitlab_rails['external_diffs_enabled'] = true
gitlab_rails['external_diffs_object_store_enabled'] = true
gitlab_rails['external_diffs_object_store_remote_directory'] = "external-diffs"
gitlab_rails['external_diffs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
Note that, if you are using AWS IAM profiles, be sure to omit the
AWS access key and secret access key/value pairs. For example:
```ruby
gitlab_rails['external_diffs_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
 
1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -131,18 +131,18 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
external_diffs:
enabled: true
object_store:
enabled: true
remote_directory: "external-diffs" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
```yaml
external_diffs:
enabled: true
object_store:
enabled: true
remote_directory: "external-diffs" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
 
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -157,11 +157,11 @@ To enable this feature, perform the following steps:
 
**In Omnibus installations:**
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['external_diffs_when'] = 'outdated'
```
```ruby
gitlab_rails['external_diffs_when'] = 'outdated'
```
 
1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -170,11 +170,11 @@ To enable this feature, perform the following steps:
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
external_diffs:
enabled: true
when: outdated
```
```yaml
external_diffs:
enabled: true
when: outdated
```
 
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
doc/administration/packages.md
+ 71
− 69
View file @ 5abfc57e
@@ -28,9 +28,9 @@ To enable the Packages feature:
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['packages_enabled'] = true
```
```ruby
gitlab_rails['packages_enabled'] = true
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -39,10 +39,11 @@ To enable the Packages feature:
1. After the installation is complete, you will have to configure the `packages`
section in `config/gitlab.yml`. Set to `true` to enable it:
 
```yaml
packages:
enabled: true
```
```yaml
packages:
enabled: true
```
1. [Restart GitLab] for the changes to take effect.
 
## Changing the storage path
@@ -61,9 +62,9 @@ To change the local storage path:
 
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['packages_storage_path'] = "/mnt/packages"
```
```ruby
gitlab_rails['packages_storage_path'] = "/mnt/packages"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -71,11 +72,12 @@ To change the local storage path:
 
1. Edit the `packages` section in `config/gitlab.yml`:
 
```yaml
packages:
enabled: true
storage_path: shared/packages
```
```yaml
packages:
enabled: true
storage_path: shared/packages
```
1. [Restart GitLab] for the changes to take effect.
 
### Using object storage
@@ -88,31 +90,31 @@ upload packages:
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
necessary):
 
```ruby
gitlab_rails['packages_enabled'] = true
gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
gitlab_rails['packages_object_store_enabled'] = true
gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
gitlab_rails['packages_object_store_direct_upload'] = false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
gitlab_rails['packages_object_store_background_upload'] = true # Temporary option to limit automatic upload (Default: true).
gitlab_rails['packages_object_store_proxy_download'] = false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['packages_object_store_connection'] = {
##
## If the provider is AWS S3, uncomment the following
##
#'provider' => 'AWS',
#'region' => 'eu-west-1',
#'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
#'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#'host' => 's3.amazonaws.com',
#'aws_signature_version' => 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#'path_style' => false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}
```
```ruby
gitlab_rails['packages_enabled'] = true
gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
gitlab_rails['packages_object_store_enabled'] = true
gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
gitlab_rails['packages_object_store_direct_upload'] = false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
gitlab_rails['packages_object_store_background_upload'] = true # Temporary option to limit automatic upload (Default: true).
gitlab_rails['packages_object_store_proxy_download'] = false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['packages_object_store_connection'] = {
##
## If the provider is AWS S3, uncomment the following
##
#'provider' => 'AWS',
#'region' => 'eu-west-1',
#'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
#'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#'host' => 's3.amazonaws.com',
#'aws_signature_version' => 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#'path_style' => false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -120,35 +122,35 @@ upload packages:
 
1. Edit the `packages` section in `config/gitlab.yml` (uncomment where necessary):
 
```yaml
packages:
enabled: true
##
## The location where build packages are stored (default: shared/packages).
##
#storage_path: shared/packages
object_store:
enabled: false
remote_directory: packages # The bucket name.
#direct_upload: false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
#background_upload: true # Temporary option to limit automatic upload (Default: true).
#proxy_download: false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
connection:
##
## If the provider is AWS S3, uncomment the following
##
#provider: AWS
#region: us-east-1
#aws_access_key_id: AWS_ACCESS_KEY_ID
#aws_secret_access_key: AWS_SECRET_ACCESS_KEY
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#host: 's3.amazonaws.com' # default: s3.amazonaws.com.
#aws_signature_version: 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#path_style: false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
```
```yaml
packages:
enabled: true
##
## The location where build packages are stored (default: shared/packages).
##
#storage_path: shared/packages
object_store:
enabled: false
remote_directory: packages # The bucket name.
#direct_upload: false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
#background_upload: true # Temporary option to limit automatic upload (Default: true).
#proxy_download: false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
connection:
##
## If the provider is AWS S3, uncomment the following
##
#provider: AWS
#region: us-east-1
#aws_access_key_id: AWS_ACCESS_KEY_ID
#aws_secret_access_key: AWS_SECRET_ACCESS_KEY
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#host: 's3.amazonaws.com' # default: s3.amazonaws.com.
#aws_signature_version: 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#path_style: false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
```
 
1. [Restart GitLab] for the changes to take effect.
 
doc/administration/pseudonymizer.md
+ 32
− 32
View file @ 5abfc57e
@@ -31,27 +31,27 @@ To configure the pseudonymizer, you need to:
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
the values you want:
 
```ruby
gitlab_rails['pseudonymizer_manifest'] = 'config/pseudonymizer.yml'
gitlab_rails['pseudonymizer_upload_remote_directory'] = 'gitlab-elt' # bucket name
gitlab_rails['pseudonymizer_upload_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
NOTE: **Note:**
If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
```ruby
gitlab_rails['pseudonymizer_upload_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
```ruby
gitlab_rails['pseudonymizer_manifest'] = 'config/pseudonymizer.yml'
gitlab_rails['pseudonymizer_upload_remote_directory'] = 'gitlab-elt' # bucket name
gitlab_rails['pseudonymizer_upload_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
NOTE: **Note:**
If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
```ruby
gitlab_rails['pseudonymizer_upload_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
 
1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure)
for the changes to take effect.
@@ -63,17 +63,17 @@ To configure the pseudonymizer, you need to:
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
pseudonymizer:
manifest: config/pseudonymizer.yml
upload:
remote_directory: 'gitlab-elt' # bucket name
connection:
provider: AWS
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
```yaml
pseudonymizer:
manifest: config/pseudonymizer.yml
upload:
remote_directory: 'gitlab-elt' # bucket name
connection:
provider: AWS
aws_access_key_id: AWS_ACCESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
 
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source)
for the changes to take effect.
doc/administration/reply_by_email_postfix_setup.md
+ 194
− 190
View file @ 5abfc57e
@@ -14,109 +14,109 @@ The instructions make the assumption that you will be using the email address `i
 
1. Install the `postfix` package if it is not installed already:
 
```sh
sudo apt-get install postfix
```
```sh
sudo apt-get install postfix
```
 
When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`.
When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches gitlab.example.com`.
 
1. Install the `mailutils` package.
 
```sh
sudo apt-get install mailutils
```
```sh
sudo apt-get install mailutils
```
 
## Create user
 
1. Create a user for incoming email.
 
```sh
sudo useradd -m -s /bin/bash incoming
```
```sh
sudo useradd -m -s /bin/bash incoming
```
 
1. Set a password for this user.
 
```sh
sudo passwd incoming
```
```sh
sudo passwd incoming
```
 
Be sure not to forget this, you'll need it later.
Be sure not to forget this, you'll need it later.
 
## Test the out-of-the-box setup
 
1. Connect to the local SMTP server:
 
```sh
telnet localhost 25
```
```sh
telnet localhost 25
```
 
You should see a prompt like this:
You should see a prompt like this:
 
```sh
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
```sh
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
 
If you get a `Connection refused` error instead, verify that `postfix` is running:
If you get a `Connection refused` error instead, verify that `postfix` is running:
 
```sh
sudo postfix status
```
```sh
sudo postfix status
```
 
If it is not, start it:
If it is not, start it:
 
```sh
sudo postfix start
```
```sh
sudo postfix start
```
 
1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
 
```
ehlo localhost
mail from: root@localhost
rcpt to: incoming@localhost
data
Subject: Re: Some issue
```
ehlo localhost
mail from: root@localhost
rcpt to: incoming@localhost
data
Subject: Re: Some issue
 
Sounds good!
.
quit
```
Sounds good!
.
quit
```
 
_**Note:** The `.` is a literal period on its own line._
_**Note:** The `.` is a literal period on its own line._
 
_**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
then your Postfix `my_network` configuration is not correct. The error will
say 'Temporary lookup failure'. See
[Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
_**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
then your Postfix `my_network` configuration is not correct. The error will
say 'Temporary lookup failure'. See
[Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
 
1. Check if the `incoming` user received the email:
 
```sh
su - incoming
mail
```
```sh
su - incoming
mail
```
 
You should see output like this:
You should see output like this:
 
```
"/var/mail/incoming": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
```
"/var/mail/incoming": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
 
Quit the mail app:
Quit the mail app:
 
```sh
q
```
```sh
q
```
 
1. Log out of the `incoming` account and go back to being `root`:
 
```sh
logout
```
```sh
logout
```
 
## Configure Postfix to use Maildir-style mailboxes
 
@@ -124,208 +124,212 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
 
1. Configure Postfix to use Maildir-style mailboxes:
 
```sh
sudo postconf -e "home_mailbox = Maildir/"
```
```sh
sudo postconf -e "home_mailbox = Maildir/"
```
 
1. Restart Postfix:
 
```sh
sudo /etc/init.d/postfix restart
```
```sh
sudo /etc/init.d/postfix restart
```
 
1. Test the new setup:
 
1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
1. Check if the `incoming` user received the email:
1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_.
1. Check if the `incoming` user received the email:
 
```sh
su - incoming
MAIL=/home/incoming/Maildir
mail
```
```sh
su - incoming
MAIL=/home/incoming/Maildir
mail
```
 
You should see output like this:
You should see output like this:
 
```
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
```
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
 
Quit the mail app:
Quit the mail app:
 
```sh
q
```
```sh
q
```
 
_**Note:** If `mail` returns an error `Maildir: Is a directory` then your
version of `mail` doesn't support Maildir style mailboxes. Install
`heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
try the above steps again, substituting `heirloom-mailx` for the `mail`
command._
_**Note:** If `mail` returns an error `Maildir: Is a directory` then your
version of `mail` doesn't support Maildir style mailboxes. Install
`heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
try the above steps again, substituting `heirloom-mailx` for the `mail`
command._
 
1. Log out of the `incoming` account and go back to being `root`:
 
```sh
logout
```
```sh
logout
```
 
## Install the Courier IMAP server
 
1. Install the `courier-imap` package:
 
```sh
sudo apt-get install courier-imap
```
```sh
sudo apt-get install courier-imap
```
 
And start `imapd`:
```sh
imapd start
```
And start `imapd`:
```sh
imapd start
```
 
1. The courier-authdaemon isn't started after installation. Without it, imap authentication will fail:
```sh
sudo service courier-authdaemon start
```
You can also configure courier-authdaemon to start on boot:
```sh
sudo systemctl enable courier-authdaemon
```
```sh
sudo service courier-authdaemon start
```
You can also configure courier-authdaemon to start on boot:
```sh
sudo systemctl enable courier-authdaemon
```
 
## Configure Postfix to receive email from the internet
 
1. Let Postfix know about the domains that it should consider local:
 
```sh
sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
```
```sh
sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
```
 
1. Let Postfix know about the IPs that it should consider part of the LAN:
 
We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
 
```sh
sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
```
```sh
sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
```
 
1. Configure Postfix to receive mail on all interfaces, which includes the internet:
 
```sh
sudo postconf -e "inet_interfaces = all"
```
```sh
sudo postconf -e "inet_interfaces = all"
```
 
1. Configure Postfix to use the `+` delimiter for sub-addressing:
 
```sh
sudo postconf -e "recipient_delimiter = +"
```
```sh
sudo postconf -e "recipient_delimiter = +"
```
 
1. Restart Postfix:
 
```sh
sudo service postfix restart
```
```sh
sudo service postfix restart
```
 
## Test the final setup
 
1. Test SMTP under the new setup:
 
1. Connect to the SMTP server:
1. Connect to the SMTP server:
 
```sh
telnet gitlab.example.com 25
```
```sh
telnet gitlab.example.com 25
```
 
You should see a prompt like this:
You should see a prompt like this:
 
```sh
Trying 123.123.123.123...
Connected to gitlab.example.com.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
```sh
Trying 123.123.123.123...
Connected to gitlab.example.com.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
 
If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25.
If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25.
 
1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt:
 
```
ehlo gitlab.example.com
mail from: root@gitlab.example.com
rcpt to: incoming@gitlab.example.com
data
Subject: Re: Some issue
```
ehlo gitlab.example.com
mail from: root@gitlab.example.com
rcpt to: incoming@gitlab.example.com
data
Subject: Re: Some issue
 
Sounds good!
.
quit
```
Sounds good!
.
quit
```
 
(Note: The `.` is a literal period on its own line)
(Note: The `.` is a literal period on its own line)
 
1. Check if the `incoming` user received the email:
1. Check if the `incoming` user received the email:
 
```sh
su - incoming
MAIL=/home/incoming/Maildir
mail
```
```sh
su - incoming
MAIL=/home/incoming/Maildir
mail
```
 
You should see output like this:
You should see output like this:
 
```
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@gitlab.example.com 59/2842 Re: Some issue
```
```
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@gitlab.example.com 59/2842 Re: Some issue
```
 
Quit the mail app:
Quit the mail app:
 
```sh
q
```
```sh
q
```
 
1. Log out of the `incoming` account and go back to being `root`:
1. Log out of the `incoming` account and go back to being `root`:
 
```sh
logout
```
```sh
logout
```
 
1. Test IMAP under the new setup:
 
1. Connect to the IMAP server:
1. Connect to the IMAP server:
 
```sh
telnet gitlab.example.com 143
```
```sh
telnet gitlab.example.com 143
```
 
You should see a prompt like this:
You should see a prompt like this:
 
```sh
Trying 123.123.123.123...
Connected to mail.example.gitlab.com.
Escape character is '^]'.
- OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information.
```
```sh
Trying 123.123.123.123...
Connected to mail.example.gitlab.com.
Escape character is '^]'.
- OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information.
```
 
1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
 
```
a login incoming PASSWORD
```
```
a login incoming PASSWORD
```
 
Replace PASSWORD with the password you set on the `incoming` user earlier.
Replace PASSWORD with the password you set on the `incoming` user earlier.
 
You should see output like this:
You should see output like this:
 
```
a OK LOGIN Ok.
```
```
a OK LOGIN Ok.
```
 
1. Disconnect from the IMAP server:
1. Disconnect from the IMAP server:
 
```sh
a logout
```
```sh
a logout
```
 
## Done!
 
doc/administration/repository_storage_paths.md
+ 21
− 21
View file @ 5abfc57e
@@ -68,18 +68,18 @@ NOTE: **Note:** This example uses NFS and CephFS. We do not recommend using EFS
 
1. Edit `gitlab.yml` and add the storage paths:
 
```yaml
repositories:
# Paths where repositories can be stored. Give the canonicalized absolute pathname.
# NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
storages: # You must have at least a 'default' storage path.
default:
path: /home/git/repositories
nfs:
path: /mnt/nfs/repositories
cephfs:
path: /mnt/cephfs/repositories
```
```yaml
repositories:
# Paths where repositories can be stored. Give the canonicalized absolute pathname.
# NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
storages: # You must have at least a 'default' storage path.
default:
path: /home/git/repositories
nfs:
path: /mnt/nfs/repositories
cephfs:
path: /mnt/cephfs/repositories
```
 
1. [Restart GitLab][restart-gitlab] for the changes to take effect.
 
@@ -97,16 +97,16 @@ working, you can remove the `repos_path` line.
1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the
default one:
 
```ruby
git_data_dirs({
"default" => { "path" => "/var/opt/gitlab/git-data" },
"nfs" => { "path" => "/mnt/nfs/git-data" },
"cephfs" => { "path" => "/mnt/cephfs/git-data" }
})
```
```ruby
git_data_dirs({
"default" => { "path" => "/var/opt/gitlab/git-data" },
"nfs" => { "path" => "/mnt/nfs/git-data" },
"cephfs" => { "path" => "/mnt/cephfs/git-data" }
})
```
 
Note that Omnibus stores the repositories in a `repositories` subdirectory
of the `git-data` directory.
Note that Omnibus stores the repositories in a `repositories` subdirectory
of the `git-data` directory.
 
## Choose where new project repositories will be stored
 
doc/administration/uploads.md
+ 41
− 41
View file @ 5abfc57e
@@ -23,10 +23,10 @@ _The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._
1. To change the storage path for example to `/mnt/storage/uploads`, edit
`/etc/gitlab/gitlab.rb` and add the following line:
 
```ruby
gitlab_rails['uploads_storage_path'] = "/mnt/storage/"
gitlab_rails['uploads_base_dir'] = "uploads"
```
```ruby
gitlab_rails['uploads_storage_path'] = "/mnt/storage/"
gitlab_rails['uploads_base_dir'] = "uploads"
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -40,11 +40,11 @@ _The uploads are stored by default in
1. To change the storage path for example to `/mnt/storage/uploads`, edit
`/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
 
```yaml
uploads:
storage_path: /mnt/storage
base_dir: uploads
```
```yaml
uploads:
storage_path: /mnt/storage
base_dir: uploads
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
 
@@ -97,27 +97,27 @@ _The uploads are stored by default in
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
the values you want:
 
```ruby
gitlab_rails['uploads_object_store_enabled'] = true
gitlab_rails['uploads_object_store_remote_directory'] = "uploads"
gitlab_rails['uploads_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
>**Note:**
If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
```ruby
gitlab_rails['uploads_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
```ruby
gitlab_rails['uploads_object_store_enabled'] = true
gitlab_rails['uploads_object_store_remote_directory'] = "uploads"
gitlab_rails['uploads_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
}
```
>**Note:**
>If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
```ruby
gitlab_rails['uploads_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'eu-central-1',
'use_iam_profile' => true
}
```
 
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
@@ -132,17 +132,17 @@ _The uploads are stored by default in
1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
lines:
 
```yaml
uploads:
object_store:
enabled: true
remote_directory: "uploads" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
```yaml
uploads:
object_store:
enabled: true
remote_directory: "uploads" # The bucket name
connection:
provider: AWS # Only AWS supported at the moment
aws_access_key_id: AWS_ACESS_KEY_ID
aws_secret_access_key: AWS_SECRET_ACCESS_KEY
region: eu-central-1
```
 
1. Save the file and [restart GitLab][] for the changes to take effect.
1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md).
doc/api/README.md
+ 7
− 7
View file @ 5abfc57e
@@ -311,9 +311,9 @@ By default, impersonation is enabled. To disable impersonation:
 
1. Edit `/etc/gitlab/gitlab.rb`:
 
```ruby
gitlab_rails['impersonation_enabled'] = false
```
```ruby
gitlab_rails['impersonation_enabled'] = false
```
 
1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
GitLab for the changes to take effect.
@@ -326,10 +326,10 @@ To re-enable impersonation, remove this configuration and reconfigure GitLab.
 
1. Edit `config/gitlab.yml`:
 
```yaml
gitlab:
impersonation_enabled: false
```
```yaml
gitlab:
impersonation_enabled: false
```
 
1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
doc/api/lint.md
+ 19
− 19
View file @ 5abfc57e
@@ -22,30 +22,30 @@ Example responses:
 
- Valid content:
 
```json
{
"status": "valid",
"errors": []
}
```
```json
{
"status": "valid",
"errors": []
}
```
 
- Invalid content:
 
```json
{
"status": "invalid",
"errors": [
"variables config should be a hash of key value pairs"
]
}
```
```json
{
"status": "invalid",
"errors": [
"variables config should be a hash of key value pairs"
]
}
```
 
- Without the content attribute:
 
```json
{
"error": "content is missing"
}
```
```json
{
"error": "content is missing"
}
```
 
[ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953
doc/api/repositories.md
+ 3
− 3
View file @ 5abfc57e
@@ -121,9 +121,9 @@ Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
- `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example:
 
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>
```
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>
```
 
## Compare branches, tags or commits
 
doc/api/runners.md
+ 4
− 4
View file @ 5abfc57e
@@ -20,10 +20,10 @@ Here's an example of how the two tokens are used in Runner registration:
1. You use that authentication token and add it to the
[Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file):
 
```toml
[[runners]]
token = "<authentication_token>"
```
```toml
[[runners]]
token = "<authentication_token>"
```
 
GitLab and Runner are then connected.
 
doc/ci/git_submodules.md
+ 8
− 8
View file @ 5abfc57e
@@ -79,14 +79,14 @@ correctly with your CI jobs:
1. If you are using an older version of `gitlab-runner`, then use
`git submodule sync/update` in `before_script`:
 
```yaml
before_script:
- git submodule sync --recursive
- git submodule update --init --recursive
```
`--recursive` should be used in either both or none (`sync/update`) depending on
whether you have recursive submodules.
```yaml
before_script:
- git submodule sync --recursive
- git submodule update --init --recursive
```
`--recursive` should be used in either both or none (`sync/update`) depending on
whether you have recursive submodules.
 
The rationale to set the `sync` and `update` in `before_script` is because of
the way Git submodules work. On a fresh Runner workspace, Git will set the
doc/development/architecture.md
+ 5
− 1
View file @ 5abfc57e
@@ -484,9 +484,11 @@ When making a request to an HTTP Endpoint (think `/users/sign_in`) the request w
Below we describe the different pathing that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences.
 
### Web Request (80/443)
TODO
 
### SSH Request (22)
TODO
 
## System Layout
@@ -505,7 +507,9 @@ To summarize here's the [directory structure of the `git` user home directory](.
 
### Processes
 
ps aux | grep '^git'
```sh
ps aux | grep '^git'
```
 
GitLab has several components to operate. As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database. It also uses Apache httpd or Nginx to proxypass Unicorn. As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default). Under the GitLab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process).
 
doc/development/ee_features.md
+ 35
− 35
View file @ 5abfc57e
@@ -182,52 +182,52 @@ There are a few gotchas with it:
pattern](https://en.wikipedia.org/wiki/Template_method_pattern).
For example, given this base:
 
```ruby
class Base
def execute
return unless enabled?
```ruby
class Base
def execute
return unless enabled?
 
# ...
# ...
end
# ...
# ...
end
```
end
```
 
Instead of just overriding `Base#execute`, we should update it and extract
the behaviour into another method:
Instead of just overriding `Base#execute`, we should update it and extract
the behaviour into another method:
 
```ruby
class Base
def execute
return unless enabled?
```ruby
class Base
def execute
return unless enabled?
 
do_something
end
do_something
end
 
private
private
 
def do_something
# ...
# ...
end
def do_something
# ...
# ...
end
```
end
```
 
Then we're free to override that `do_something` without worrying about the
guards:
Then we're free to override that `do_something` without worrying about the
guards:
 
```ruby
module EE::Base
extend ::Gitlab::Utils::Override
```ruby
module EE::Base
extend ::Gitlab::Utils::Override
 
override :do_something
def do_something
# Follow the above pattern to call super and extend it
end
override :do_something
def do_something
# Follow the above pattern to call super and extend it
end
```
end
```
 
This would require updating CE first, or make sure this is back ported to CE.
This would require updating CE first, or make sure this is back ported to CE.
 
When prepending, place them in the `ee/` specific sub-directory, and
wrap class or module in `module EE` to avoid naming conflicts.
@@ -1038,8 +1038,8 @@ to avoid conflicts during CE to EE merge.
Until the work completed to merge the ce and ee codebases, which is tracked on [epic &802](https://gitlab.com/groups/gitlab-org/-/epics/802), there exists times in which some changes for EE require specific changes to the CE
code base. Examples of backports include the following:
 
* Features intended or originally built for EE that are later decided to move to CE
* Sometimes some code in CE may impact the EE feature
- Features intended or originally built for EE that are later decided to move to CE
- Sometimes some code in CE may impact the EE feature
 
Here is a workflow to make sure those changes end up backported safely into CE too.
 
doc/development/emails.md
+ 47
− 47
View file @ 5abfc57e
@@ -26,51 +26,51 @@ See the [Rails guides] for more info.
feature and fill in the details for your specific IMAP server and email
account:
 
Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com
```yaml
incoming_email:
enabled: true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
address: "gitlab-incoming+%{key}@gmail.com"
# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
user: "gitlab-incoming@gmail.com"
# Email account password
password: "[REDACTED]"
# IMAP server host
host: "imap.gmail.com"
# IMAP server port
port: 993
# Whether the IMAP server uses SSL
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox".
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
Configuration for Gmail / Google Apps, assumes mailbox `gitlab-incoming@gmail.com`:
```yaml
incoming_email:
enabled: true
# The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to.
# The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`).
address: "gitlab-incoming+%{key}@gmail.com"
# Email account username
# With third party providers, this is usually the full email address.
# With self-hosted email servers, this is usually the user part of the email address.
user: "gitlab-incoming@gmail.com"
# Email account password
password: "[REDACTED]"
# IMAP server host
host: "imap.gmail.com"
# IMAP server port
port: 993
# Whether the IMAP server uses SSL
ssl: true
# Whether the IMAP server uses StartTLS
start_tls: false
# The mailbox where incoming mail will end up. Usually "inbox".
mailbox: "inbox"
# The IDLE command timeout.
idle_timeout: 60
```
As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`.
 
1. Run this command in the GitLab root directory to launch `mail_room`:
 
```sh
bundle exec mail_room -q -c config/mail_room.yml
```
```sh
bundle exec mail_room -q -c config/mail_room.yml
```
 
1. Verify that everything is configured correctly:
 
```sh
bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
```
```sh
bundle exec rake gitlab:incoming_email:check RAILS_ENV=development
```
 
1. Reply by email should now be working.
 
@@ -91,10 +91,10 @@ for the format of the email key:
 
Examples of valid email keys:
 
- `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue)
- `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request)
- `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation)
- `1234567890abcdef1234567890abcdef` (reply to a conversation)
- `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue)
- `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request)
- `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation)
- `1234567890abcdef1234567890abcdef` (reply to a conversation)
 
Please note that the action `-issue-` is used in GitLab Premium as the handler for the Service Desk feature.
 
@@ -103,10 +103,10 @@ Please note that the action `-issue-` is used in GitLab Premium as the handler f
Although we continue to support the older legacy format, no new features should use a legacy format.
These are the only valid legacy formats for an email handler:
 
- `path/to/project+namespace`
- `path/to/project+namespace+action`
- `namespace`
- `namespace+action`
- `path/to/project+namespace`
- `path/to/project+namespace+action`
- `namespace`
- `namespace+action`
 
Please note that `path/to/project` is used in GitLab Premium as handler for the Service Desk feature.
 
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