diff options
Diffstat (limited to 'doc')
23 files changed, 292 insertions, 113 deletions
diff --git a/doc/administration/img/circuitbreaker_config.png b/doc/administration/img/circuitbreaker_config.png Binary files differnew file mode 100644 index 00000000000..9250d38297c --- /dev/null +++ b/doc/administration/img/circuitbreaker_config.png diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 76e071dc673..c9ed2d84ccb 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -18,8 +18,7 @@ other than production, the corresponding logfile is shown here.) It contains a structured log for Rails controller requests received from GitLab, thanks to [Lograge](https://github.com/roidrage/lograge/). Note that -requests from the API [are not yet logged to this -file](https://gitlab.com/gitlab-org/gitlab-ce/issues/36189). +requests from the API are logged to a separate file in `api_json.log`. Each line contains a JSON line that can be ingested by Elasticsearch, Splunk, etc. For example: @@ -73,6 +72,27 @@ In this example we can see that server processed an HTTP request with URL 19:34:53 +0200. Also we can see that request was processed by `Projects::TreeController`. +## `api_json.log` + +Introduced in GitLab 10.0, this file lives in +`/var/log/gitlab/gitlab-rails/api_json.log` for Omnibus GitLab packages or in +`/home/git/gitlab/log/api_json.log` for installations from source. + +It helps you see requests made directly to the API. For example: + +```json +{"time":"2017-10-10T12:30:11.579Z","severity":"INFO","duration":16.84,"db":1.57,"view":15.27,"status":200,"method":"POST","path":"/api/v4/internal/allowed","params":{"action":"git-upload-pack","changes":"_any","gl_repository":null,"project":"root/foobar.git","protocol":"ssh","env":"{}","key_id":"[FILTERED]","secret_token":"[FILTERED]"},"host":"127.0.0.1","ip":"127.0.0.1","ua":"Ruby"} +``` + +This entry above shows an access to an internal endpoint to check whether an +associated SSH key can download the project in question via a `git fetch` or +`git clone`. In this example, we see: + +1. `method`: The HTTP method used to make the request +1. `path`: The relative path of the query +1. `params`: Key-value pairs passed in a query string or HTTP body. Sensitive parameters (e.g. passwords, tokens, etc.) are filtered out. +1. `ua`: The User-Agent of the requester + ## `application.log` This file lives in `/var/log/gitlab/gitlab-rails/application.log` for diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 04c70c3644e..6b8ad1b039b 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -7,6 +7,7 @@ > projects. You can get it from: https://github.com/settings/tokens > - You also need to pass an username as the second argument to the rake task > which will become the owner of the project. +> - You can also resume an import with the same command. To import a project from the list of your GitHub projects available: diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 624a908b3a3..efcabd69822 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -105,61 +105,26 @@ When GitLab detects access to the repositories storage fails repeatedly, it can gracefully prevent attempts to access the storage. This might be useful when the repositories are stored somewhere on the network. -The configuration could look as follows: +This can be configured from the admin interface: -**For Omnibus installations** - -1. Edit `/etc/gitlab/gitlab.rb`: - - ```ruby - git_data_dirs({ - "default" => { - "path" => "/mnt/nfs-01/git-data", - "failure_count_threshold" => 10, - "failure_wait_time" => 30, - "failure_reset_time" => 1800, - "storage_timeout" => 5 - } - }) - ``` - -1. Save the file and [reconfigure GitLab][reconfigure-gitlab] for the changes to take effect. - ---- - -**For installations from source** - -1. Edit `config/gitlab.yml`: - - ```yaml - repositories: - storages: # You must have at least a `default` storage path. - default: - path: /home/git/repositories/ - failure_count_threshold: 10 # number of failures before stopping attempts - failure_wait_time: 30 # Seconds after last access failure before trying again - failure_reset_time: 1800 # Time in seconds to expire failures - storage_timeout: 5 # Time in seconds to wait before aborting a storage access attempt - ``` - -1. Save the file and [restart GitLab][restart-gitlab] for the changes to take effect. + -**`failure_count_threshold`:** The number of failures of after which GitLab will +**Maximum git storage failures:** The number of failures of after which GitLab will completely prevent access to the storage. The number of failures can be reset in the admin interface: `https://gitlab.example.com/admin/health_check` or using the [api](../api/repository_storage_health.md) to allow access to the storage again. -**`failure_wait_time`:** When access to a storage fails. GitLab will prevent -access to the storage for the time specified here. This allows the filesystem to -recover without. +**Seconds to wait after a storage failure:** When access to a storage fails. GitLab +will prevent access to the storage for the time specified here. This allows the +filesystem to recover. -**`failure_reset_time`:** The time in seconds GitLab will keep failure -information. When no failures occur during this time, information about the +**Seconds before reseting failure information:** The time in seconds GitLab will +keep failure information. When no failures occur during this time, information about the mount is reset. -**`storage_timeout`:** The time in seconds GitLab will try to access storage. -After this time a timeout error will be raised. +**Seconds to wait for a storage access attempt:** The time in seconds GitLab will +try to access storage. After this time a timeout error will be raised. When storage failures occur, this will be visible in the admin interface like this: diff --git a/doc/api/README.md b/doc/api/README.md index 3fd4c97e536..de0fe79b3d6 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -63,7 +63,21 @@ following locations: ## Road to GraphQL -We have changed our plans to move to GraphQL. After reviewing the GraphQL license, anything related to the Facebook BSD plus patent license will not be allowed at GitLab. +Going forward, we will start on moving to +[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of +controller-specific endpoints. GraphQL has a number of benefits: + +1. We avoid having to maintain two different APIs. +2. Callers of the API can request only what they need. +3. It is versioned by default. + +It will co-exist with the current v4 REST API. If we have a v5 API, this should +be a compatibility layer on top of GraphQL. + +Although there were some patenting and licensing concerns with GraphQL, these +have been resolved to our satisfaction by the relicensing of the reference +implementations under MIT, and the use of the OWF license for the GraphQL +specification. ## Basic usage @@ -441,6 +455,23 @@ Content-Type: application/json } ``` +## Encoding `+` in ISO 8601 dates + +If you need to include a `+` in a query parameter, you may need to use `%2B` instead due +a [W3 recommendation]((http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) that +causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, you may want to pass +a time in Mountain Standard Time, such as: + +``` +2017-10-17T23:11:13.000+05:30 +``` + +The correct encoding for the query parameter would be: + +``` +2017-10-17T23:11:13.000%2B05:30 +``` + ## Clients There are many unofficial GitLab API Clients for most of the popular diff --git a/doc/api/repositories.md b/doc/api/repositories.md index bccef924375..594babc74be 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -85,7 +85,7 @@ GET /projects/:id/repository/blobs/:sha Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `sha` (required) - The commit or branch name +- `sha` (required) - The blob SHA ## Raw blob content diff --git a/doc/api/settings.md b/doc/api/settings.md index b78f1252108..664f3ef7b77 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -64,38 +64,93 @@ PUT /application/settings | Attribute | Type | Required | Description | | --------- | ---- | :------: | ----------- | -| `default_projects_limit` | integer | no | Project limit per user. Default is `100000` | -| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | -| `password_authentication_enabled` | boolean | no | Enable authentication via a GitLab account password. Default is `true`. | -| `gravatar_enabled` | boolean | no | Enable Gravatar | -| `sign_in_text` | string | no | Text on login page | -| `home_page_url` | string | no | Redirect to this URL when not logged in | -| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `2`. | -| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is null which means there is no restriction. | -| `max_attachment_size` | integer | no | Limit attachment size in MB | -| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | -| `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`.| -| `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`.| -| `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`.| -| `domain_whitelist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. | -| `domain_blacklist_enabled` | boolean | no | Enable/disable the `domain_blacklist` | -| `domain_blacklist` | array of strings | yes (if `domain_blacklist_enabled` is `true`) | People trying to sign-up with emails from this domain will not be allowed to do so. | -| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider | -| `after_sign_out_path` | string | no | Where to redirect users after logout | -| `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes | -| `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | -| `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | -| `koding_enabled` | boolean | no | Enable Koding integration. Default is `false`. | -| `koding_url` | string | yes (if `koding_enabled` is `true`) | The Koding instance URL for integration. | -| `disabled_oauth_sign_in_sources` | Array of strings | no | Disabled OAuth sign-in sources | -| `plantuml_enabled` | boolean | no | Enable PlantUML integration. Default is `false`. | -| `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | -| `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | -| `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | -| `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. -| `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. -| `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. -| `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. +| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the admin area. | +| `after_sign_out_path` | string | no | Where to redirect users after logout | +| `after_sign_up_text` | string | no | Text shown to the user after signing up | +| `akismet_api_key` | string | no | API key for akismet spam protection | +| `akismet_enabled` | boolean | no | Enable or disable akismet spam protection | +| `circuitbreaker_failure_count_threshold` | integer | no | The number of failures of after which GitLab will completely prevent access to the storage. | +| `circuitbreaker_failure_reset_time` | integer | no | Time in seconds GitLab will keep storage failure information. When no failures occur during this time, the failure information is reset. | +| `circuitbreaker_failure_wait_time` | integer | no | Time in seconds GitLab will block access to a failing storage to allow it to recover. | +| `circuitbreaker_storage_timeout` | integer | no | Seconds to wait for a storage access attempt | +| `clientside_sentry_dsn` | string | no | Required if `clientside_sentry_dsn` is enabled | +| `clientside_sentry_enabled` | boolean | no | Enable Sentry error reporting for the client side | +| `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes | +| `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts | +| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `2`. | +| `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `default_project_visibility` | string | no | What visibility level new projects receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `default_projects_limit` | integer | no | Project limit per user. Default is `100000` | +| `default_snippet_visibility` | string | no | What visibility level new snippets receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | +| `disabled_oauth_sign_in_sources` | Array of strings | no | Disabled OAuth sign-in sources | +| `domain_blacklist_enabled` | boolean | no | Enable/disable the `domain_blacklist` | +| `domain_blacklist` | array of strings | yes (if `domain_blacklist_enabled` is `true`) | People trying to sign-up with emails from this domain will not be allowed to do so. | +| `domain_whitelist` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. | +| `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | +| `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | +| `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | +| `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | +| `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | +| `gravatar_enabled` | boolean | no | Enable Gravatar | +| `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help | +| `help_page_support_url` | string | no | Alternate support URL for help page | +| `home_page_url` | string | no | Redirect to this URL when not logged in | +| `housekeeping_bitmaps_enabled` | boolean | no | Enable Git pack file bitmap creation | +| `housekeeping_enabled` | boolean | no | Enable or disable git housekeeping | +| `housekeeping_full_repack_period` | integer | no | Number of Git pushes after which an incremental 'git repack' is run. | +| `housekeeping_gc_period` | integer | no | Number of Git pushes after which 'git gc' is run. | +| `housekeeping_incremental_repack_period` | integer | no | Number of Git pushes after which an incremental 'git repack' is run. | +| `html_emails_enabled` | boolean | no | Enable HTML emails | +| `import_sources` | Array of strings | no | Sources to allow project import from, possible values: "github bitbucket gitlab google_code fogbugz git gitlab_project | +| `koding_enabled` | boolean | no | Enable Koding integration. Default is `false`. | +| `koding_url` | string | yes (if `koding_enabled` is `true`) | The Koding instance URL for integration. | +| `max_artifacts_size` | integer | no | Maximum artifacts size in MB | +| `max_attachment_size` | integer | no | Limit attachment size in MB | +| `max_pages_size` | integer | no | Maximum size of pages repositories in MB | +| `metrics_enabled` | boolean | no | Enable influxDB metrics | +| `metrics_host` | string | yes (if `metrics_enabled` is `true`) | InfluxDB host | +| `metrics_method_call_threshold` | integer | yes (if `metrics_enabled` is `true`) | A method call is only tracked when it takes longer than the given amount of milliseconds | +| `metrics_packet_size` | integer | yes (if `metrics_enabled` is `true`) | The amount of datapoints to send in a single UDP packet. | +| `metrics_pool_size` | integer | yes (if `metrics_enabled` is `true`) | The amount of InfluxDB connections to keep open | +| `metrics_port` | integer | no | The UDP port to use for connecting to InfluxDB | +| `metrics_sample_interval` | integer | yes (if `metrics_enabled` is `true`) | The sampling interval in seconds. | +| `metrics_timeout` | integer | yes (if `metrics_enabled` is `true`) | The amount of seconds after which InfluxDB will time out. | +| `password_authentication_enabled` | boolean | no | Enable authentication via a GitLab account password. Default is `true`. | +| `performance_bar_allowed_group_id` | string | no | The group that is allowed to enable the performance bar | +| `performance_bar_enabled` | boolean | no | Allow enabling the performance bar | +| `plantuml_enabled` | boolean | no | Enable PlantUML integration. Default is `false`. | +| `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | +| `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | +| `project_export_enabled` | boolean | no | Enable project export | +| `prometheus_metrics_enabled` | boolean | no | Enable prometheus metrics | +| `recaptcha_enabled` | boolean | no | Enable recaptcha | +| `recaptcha_private_key` | string | yes (if `recaptcha_enabled` is true) | Private key for recaptcha | +| `recaptcha_site_key` | string | yes (if `recaptcha_enabled` is true) | Site key for recaptcha | +| `repository_checks_enabled` | boolean | no | GitLab will periodically run 'git fsck' in all project and wiki repositories to look for silent disk corruption issues. | +| `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | +| `require_two_factor_authentication` | boolean | no | Require all users to setup Two-factor authentication | +| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is null which means there is no restriction. | +| `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | +| `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up | +| `sentry_dsn` | string | yes (if `sentry_enabled` is true) | Sentry Data Source Name | +| `sentry_enabled` | boolean | no | Sentry is an error reporting and logging tool which is currently not shipped with GitLab, get it here: https://getsentry.com | +| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | +| `shared_runners_enabled` | true | no | Enable shared runners for new projects | +| `shared_runners_text` | string | no | Shared runners text | +| `sidekiq_throttling_enabled` | boolean | no | Enable Sidekiq Job Throttling | +| `sidekiq_throttling_factor` | decimal | yes (if `sidekiq_throttling_enabled` is true) | The factor by which the queues should be throttled. A value between 0.0 and 1.0, exclusive. | +| `sidekiq_throttling_queues` | array of strings | yes (if `sidekiq_throttling_enabled` is true) | Choose which queues you wish to throttle | +| `sign_in_text` | string | no | Text on login page | +| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | +| `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | +| `two_factor_grace_period` | integer | no | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication | +| `unique_ips_limit_enabled` | boolean | no | Limit sign in from multiple ips | +| `unique_ips_limit_per_user` | integer | yes (if `unique_ips_limit_enabled` is true) | Maximum number of ips per user | +| `unique_ips_limit_time_window` | integer | yes (if `unique_ips_limit_enabled` is true) | How many seconds an IP will be counted towards the limit | +| `usage_ping_enabled` | boolean | no | Every week GitLab will report license usage back to GitLab, Inc. | +| `user_default_external` | boolean | no | Newly registered users will by default be external | +| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider | +| `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal diff --git a/doc/ci/README.md b/doc/ci/README.md index 5cfd82de381..ec0ddfbea75 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -42,7 +42,7 @@ digging into specific reference guides. - **The permissions model** - Learn about the access levels a user can have for performing certain CI actions - [User permissions](../user/permissions.md#gitlab-ci) - - [Jobs permissions](../user/permissions.md#jobs-permissions) + - [Job permissions](../user/permissions.md#job-permissions) ## Auto DevOps diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 17839cbaef1..73568757aaa 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -43,6 +43,7 @@ future GitLab releases.** | **CI_COMMIT_TAG** | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | **CI_CONFIG_PATH** | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | | **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | +| **CI_DISPOSABLE_ENVIRONMENT** | all | 10.1 | Mark that job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | | **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job | | **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. | | **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job | @@ -73,6 +74,7 @@ future GitLab releases.** | **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate jobs | | **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule jobs | | **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule jobs | +| **CI_SHARED_ENVIRONMENT** | all | 10.1 | Mark that job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. | | **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job | | **GET_SOURCES_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to fetch sources running a job | | **GITLAB_CI** | all | all | Mark that job is executed in GitLab CI environment | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 38bd0450a09..6ad70707594 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -95,6 +95,12 @@ be an array or a multi-line string. `after_script` is used to define the command that will be run after for all jobs. This has to be an array or a multi-line string. +> **Note:** +The `before_script` and the main `script` are concatenated and run in a single context/container. +The `after_script` is run separately, so depending on the executor, changes done +outside of the working tree might not be visible, e.g. software installed in the +`before_script`. + ### stages `stages` is used to define stages that can be used by jobs. diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index e41d258bec6..ca2048c7019 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -52,8 +52,8 @@ rm -rf tmp/tests/gitaly ## `TooManyInvocationsError` errors -During development and testing, you may experience `Gitlab::GitalyClient::TooManyInvocationsError` failures. -The `GitalyClient` will attempt to block against potential n+1 issues by raising this error +During development and testing, you may experience `Gitlab::GitalyClient::TooManyInvocationsError` failures. +The `GitalyClient` will attempt to block against potential n+1 issues by raising this error when Gitaly is called more than 30 times in a single Rails request or Sidekiq execution. As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This will disable the n+1 detection @@ -64,7 +64,7 @@ Please raise an issue in the GitLab CE or EE repositories to report the issue. I `TooManyInvocationsError`. Also include any known failing tests if possible. Isolate the source of the n+1 problem. This will normally be a loop that results in Gitaly being called for each -element in an array. If you are unable to isolate the problem, please contact a member +element in an array. If you are unable to isolate the problem, please contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. Once the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: @@ -79,6 +79,24 @@ end Once the code is wrapped in this block, this code-path will be excluded from n+1 detection. +## Request counts + +Commits and other git data, is now fetched through Gitaly. These fetches can, +much like with a database, be batched. This improves performance for the client +and for Gitaly itself and therefore for the users too. To keep performance stable +and guard performance regressions, Gitaly calls can be counted and the call count +can be tested against. This requires the `:request_store` flag to be set. + +```ruby +describe 'Gitaly Request count tests' do + context 'when the request store is activated', :request_store do + it 'correctly counts the gitaly requests made' do + expect { subject }.to change { Gitlab::GitalyClient.get_request_count }.by(10) + end + end +end +``` + --- [Return to Development documentation](README.md) diff --git a/doc/development/licensing.md b/doc/development/licensing.md index a75cdf22f40..902b1c74a42 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -56,6 +56,7 @@ Libraries with the following licenses are acceptable for use: - [ISC License][ISC] (also known as the OpenBSD License): A permissive (non-copyleft) license as defined by the Open Source Initiative. - [Creative Commons Zero (CC0)][CC0]: A public domain dedication, recommended as a way to disclaim copyright on your work to the maximum extent possible. - [Unlicense][UNLICENSE]: Another public domain dedication. +- [OWFa 1.0][OWFa1]: An open-source license and patent grant designed for specifications. ## Unacceptable Licenses @@ -105,6 +106,7 @@ Gems which are included only in the "development" or "test" groups by Bundler ar [OSL-GNU]: https://www.gnu.org/licenses/license-list.en.html#OSL [Org-Repo]: https://gitlab.com/gitlab-com/organization [UNLICENSE]: https://unlicense.org +[OWFa1]: http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0 [Facebook]: https://code.facebook.com/pages/850928938376556 [x-list]: https://www.apache.org/legal/resolved.html#category-x [Acceptable-Licenses]: #acceptable-licenses diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 933033a09e0..af79353b721 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -27,3 +27,13 @@ Bullet will log query problems to both the Rails log as well as the Chrome console. As a follow up to finding `N+1` queries with Bullet, consider writing a [QueryRecoder test](query_recorder.md) to prevent a regression. + +## GitLab Profiler + + +[Gitlab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) was built to +help developers understand why specific URLs of their application may be slow +and to provide hard data that can help reduce load times. + +For GitLab.com, you can find the latest results here: +<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics> diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 613423dbd9a..7ddd02e6c73 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -35,6 +35,8 @@ Here are some things to keep in mind regarding test performance: [Gotchas](../gotchas.md#dont-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Don't supply the `:each` argument to hooks since it's the default. - On `before` and `after` hooks, prefer it scoped to `:context` over `:all` +- When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element, + use a Capyabara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists. [four-phase-test]: https://robots.thoughtbot.com/four-phase-test diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 67ef189fee9..e18711f3392 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -17,7 +17,7 @@ [Project Templates](https://gitlab.com/gitlab-org/project-templates): this will kickstart your repository code and CI automatically. Otherwise, if you have a project in a different repository, you can [import it] by - clicking an **Import project from** button provided this is enabled in + clicking on the **Import project** tab, provided this is enabled in your GitLab instance. Ask your administrator if not. 1. Provide the following information: diff --git a/doc/gitlab-basics/img/create_new_project_info.png b/doc/gitlab-basics/img/create_new_project_info.png Binary files differindex ef8753e224b..ce4f7d1204b 100644 --- a/doc/gitlab-basics/img/create_new_project_info.png +++ b/doc/gitlab-basics/img/create_new_project_info.png diff --git a/doc/install/installation.md b/doc/install/installation.md index 2c93297ca2f..2a004152d5e 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -80,7 +80,7 @@ Make sure you have the right version of Git installed # Install Git sudo apt-get install -y git-core - # Make sure Git is version 2.13.0 or higher + # Make sure Git is version 2.13.6 or higher git --version Is the system packaged Git too old? Remove it and compile from source. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 17fe80fa93d..3d7becd18fc 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -121,8 +121,8 @@ Existing users using GitLab with MySQL/MariaDB are advised to ### PostgreSQL Requirements -As of GitLab 9.3, PostgreSQL 9.2 or newer is required, and earlier versions are -not supported. We highly recommend users to use at least PostgreSQL 9.6 as this +As of GitLab 10.0, PostgreSQL 9.6 or newer is required, and earlier versions are +not supported. We highly recommend users to use PostgreSQL 9.6 as this is the PostgreSQL version used for development and testing. Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every diff --git a/doc/integration/google.md b/doc/integration/google.md index 0611cbb59dc..727ca13ebcf 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -105,24 +105,5 @@ form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. -## Further Configuration - -This further configuration is not required for Google authentication to function -but it is strongly recommended. Taking these steps will increase usability for -users by providing a little more recognition and branding. - -At this point, when users first try to authenticate to your GitLab installation -with Google they will see a generic application name on the prompt screen. The -prompt informs the user that "Project Default Service Account" would like to -access their account. "Project Default Service Account" isn't very recognizable -and may confuse or cause users to be concerned. This is easily changeable: - -1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for - instructions on how to get here if you closed your window). -1. Scroll down until you find "Product Name". Change the product name to - something more descriptive. -1. Add any additional information as you wish - homepage, logo, privacy policy, - etc. None of this is required, but it may help your users. - [reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md new file mode 100644 index 00000000000..7ab56c89014 --- /dev/null +++ b/doc/policy/maintenance.md @@ -0,0 +1,81 @@ +# GitLab Maintenance Policy + +## Versioning + +GitLab follows the [Semantic Versioning](http://semver.org/) for its releases: +`(Major).(Minor).(Patch)` in a [pragmatic way]. + +- **Major version**: Whenever there is something significant or any backwards + incompatible changes are introduced to the public API. +- **Minor version**: When new, backwards compatible functionality is introduced + to the public API or a minor feature is introduced, or when a set of smaller + features is rolled out. +- **Patch number**: When backwards compatible bug fixes are introduced that fix + incorrect behavior. + +For example, for GitLab version 10.5.7: + +* `10` represents major version +* `5` represents minor version +* `7` represents patch number + +## Security releases + +The current stable release will receive security patches and bug fixes +(eg. `8.9.0` -> `8.9.1`). + +Feature releases will mark the next supported stable +release where the minor version is increased numerically by increments of one +(eg. `8.9 -> 8.10`). + +Our current policy is to support one stable release at any given time. +For medium-level security issues, we may consider backporting to the previous two +monthly releases. + +For very serious security issues, there is [precedent](https://about.gitlab.com/2016/05/02/cve-2016-4340-patches/) +to backport security fixes to even more monthly releases of GitLab. This decision +is made on a case-by-case basis. + +## Version support + +We encourage everyone to run the latest stable release to ensure that you can +easily upgrade to the most secure and feature-rich GitLab experience. In order +to make sure you can easily run the most recent stable release, we are working +hard to keep the update process simple and reliable. + +If you are unable to follow our monthly release cycle, there are a couple of +cases you need to consider. + +It is considered safe to jump between patch versions and minor versions within +one major version. For example, it is safe to: + +* Upgrade the patch version: + * `8.9.0` -> `8.9.7` + * `8.9.0` -> `8.9.1` + * `8.9.2` -> `8.9.6` +* Upgrade the minor version: + * `8.9.4` -> `8.12.3` + * `9.2.3` -> `9.5.5` + +Upgrading the major version requires more attention. +We cannot guarantee that upgrading between major versions will be seamless. As previously mentioned, major versions are reserved for backwards incompatible changes. + +We recommend that you first upgrade to the latest available minor version within +your major version. By doing this, you can address any deprecation messages +that could possibly change behaviour in the next major release. + +Please see the table below for some examples: + +| Latest stable version | Your version | Recommended upgrade path | Note | +| -------------- | ------------ | ------------------------ | ---------------- | +| 9.4.5 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.4.5` | `8.17.7` is the last version in version `8` | +| 10.1.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.8` -> `10.1.4` | `8.17.7` is the last version in version `8`, `9.5.8` is the last version in version `9` | +| + +More information about the release procedures can be found in our +[release-tools documentation][rel]. You may also want to read our +[Responsible Disclosure Policy][disclosure]. + +[rel]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/ +[disclosure]: https://about.gitlab.com/disclosure/ +[pragmatic way]: https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 0399ebec86a..a45a4eb9e49 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -2,6 +2,8 @@ Your GitLab instance can perform HTTP POST requests on the following events: `project_create`, `project_destroy`, `project_rename`, `project_transfer`, `project_update`, `user_add_to_team`, `user_remove_from_team`, `user_create`, `user_destroy`, `key_create`, `key_destroy`, `group_create`, `group_destroy`, `user_add_to_group` and `user_remove_from_group`. +The triggers for most of these are self-explanatory, but `project_update` and `project_rename` deserve some clarification: `project_update` is fired any time an attribute of a project is changed (name, description, tags, etc.) *unless* the `path` attribute is also changed. In that case, a `project_rename` is triggered instead (so that, for instance, if all you care about is the repo URL, you can just listen for `project_rename`). + System hooks can be used, e.g. for logging or changing information in a LDAP server. > **Note:** diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index d6f3a7d5555..402a2a3c727 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -1,8 +1,10 @@ # Automatic issue closing ->**Note:** -This is the user docs. In order to change the default issue closing pattern, -follow the steps in the [administration docs]. +>**Notes:** +> - This is the user docs. In order to change the default issue closing pattern, +> follow the steps in the [administration docs]. +> - For performance reasons, automatic issue closing is disabled for the very +> first push from an existing repository. When a commit or merge request resolves one or more issues, it is possible to automatically have these issues closed when the commit or merge request lands @@ -19,7 +21,7 @@ When not specified, the default issue closing pattern as shown below will be used: ```bash -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing))(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) +((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) ``` Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's @@ -34,6 +36,7 @@ This translates to the following keywords: - Close, Closes, Closed, Closing, close, closes, closed, closing - Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing - Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving +- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing --- diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 6a5d2d40927..e81e935e37d 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -32,7 +32,7 @@ do. | `/wip` | Toggle the Work In Progress status | | <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | | `/remove_estimate` | Remove estimated time | -| <code>/spend <1h 30m | -1h 5m></code> | Add or subtract spent time | +| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | | `/remove_time_spent` | Remove time spent | | `/target_branch <Branch Name>` | Set target branch for current merge request | | `/award :emoji:` | Toggle award for :emoji: | |
