diff options
Diffstat (limited to 'doc')
32 files changed, 960 insertions, 131 deletions
diff --git a/doc/README.md b/doc/README.md index be805a2ccc4..604f7244a34 100644 --- a/doc/README.md +++ b/doc/README.md @@ -211,9 +211,9 @@ straight away. ### GitLab self-hosted -With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/products/): Libre, Starter, Premium, and Ultimate. +With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/products/): Core, Starter, Premium, and Ultimate. -Every feature available in Libre is also available in Starter, Premium, and Ultimate. +Every feature available in Core is also available in Starter, Premium, and Ultimate. Starter features are also available in Premium and Ultimate, and Premium features are also available in Ultimate. @@ -227,7 +227,7 @@ GitLab.com subscriptions grants access to the same features available in GitLab self-hosted, **expect [administration](administration/index.md) tools and settings**: -- GitLab.com Free includes the same features available in GitLab Libre +- GitLab.com Free includes the same features available in Core - GitLab.com Bronze includes the same features available in GitLab Starter - GitLab.com Silver includes the same features available in GitLab Premium - GitLab.com Gold includes the same features available in GitLab Ultimate diff --git a/doc/administration/index.md b/doc/administration/index.md index 4366590578a..60a45426636 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -11,8 +11,8 @@ available through [different subscriptions](https://about.gitlab.com/products/). You can [install GitLab CE or GitLab EE](https://about.gitlab.com/installation/ce-or-ee/), but the features you'll have access to depend on the subscription you choose -(Libre, Starter, Premium, or Ultimate). GitLab Community Edition installations -only have access to Libre features. +(Core, Starter, Premium, or Ultimate). GitLab Community Edition installations +only have access to Core features. GitLab.com is administered by GitLab, Inc., therefore, only GitLab team members have access to its admin configurations. If you're a GitLab.com user, please check the diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 28e1fd4e12e..466bb1f851e 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -24,11 +24,11 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by **For Omnibus installations** 1. Open `/etc/gitlab/gitlab.rb` with your editor. -1. Change the value of `gitlab_rails['issue_closing_pattern']` to a regular +1. Change the value of `gitlab_rails['gitlab_issue_closing_pattern']` to a regular expression of your liking: ```ruby - gitlab_rails['issue_closing_pattern'] = "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" + gitlab_rails['gitlab_issue_closing_pattern'] = "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)" ``` 1. [Reconfigure] GitLab for the changes to take effect. diff --git a/doc/api/commits.md b/doc/api/commits.md index 55c673fd06a..db0a80d04d9 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -412,9 +412,10 @@ Example response: Since GitLab 8.1, this is the new commit status API. -### Get the status of a commit +### List the statuses of a commit -Get the statuses of a commit in a project. +List the statuses of a commit in a project. +The pagination parameters `page` and `per_page` can be used to restrict the list of references. ``` GET /projects/:id/repository/commits/:sha/statuses @@ -536,6 +537,74 @@ Example response: } ``` +## List Merge Requests associated with a commit + +Get a list of Merge Requests related to the specified commit. + +``` +GET /projects/:id/repository/commits/:sha/merge_requests +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `sha` | string | yes | The commit SHA + + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" +``` + +Example response: + +```json +[ + { + "id":45, + "iid":1, + "project_id":35, + "title":"Add new file", + "description":"", + "state":"opened", + "created_at":"2018-03-26T17:26:30.916Z", + "updated_at":"2018-03-26T17:26:30.916Z", + "target_branch":"master", + "source_branch":"test-branch", + "upvotes":0, + "downvotes":0, + "author" : { + "web_url" : "https://gitlab.example.com/thedude", + "name" : "Jeff Lebowski", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "username" : "thedude", + "state" : "active", + "id" : 28 + }, + "assignee":null, + "source_project_id":35, + "target_project_id":35, + "labels":[ ], + "work_in_progress":false, + "milestone":null, + "merge_when_pipeline_succeeds":false, + "merge_status":"can_be_merged", + "sha":"af5b13261899fb2c0db30abdd0af8b07cb44fdc5", + "merge_commit_sha":null, + "user_notes_count":0, + "discussion_locked":null, + "should_remove_source_branch":null, + "force_remove_source_branch":false, + "web_url":"http://https://gitlab.example.com/root/test-project/merge_requests/1", + "time_stats":{ + "time_estimate":0, + "total_time_spent":0, + "human_time_estimate":null, + "human_total_time_spent":null + } + } +] +``` + [ce-6096]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6096 "Multi-file commit" [ce-8047]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8047 [ce-15026]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15026 diff --git a/doc/api/events.md b/doc/api/events.md index 129af0afa35..f4d26c4de1c 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -42,6 +42,10 @@ Dates for the `before` and `after` parameters should be supplied in the followin YYYY-MM-DD ``` +### Event Time Period Limit + +GitLab removes events older than 1 year from the events table for performance reasons. The range of 1 year was chosen because user contribution calendars only show contributions of the past year. + ## List currently authenticated user's events >**Note:** This endpoint was introduced in GitLab 9.3. diff --git a/doc/api/issues.md b/doc/api/issues.md index a4a51101297..7479c1d2f93 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -100,6 +100,7 @@ Example response: }, "updated_at" : "2016-01-04T15:31:51.081Z", "closed_at" : null, + "closed_by" : null, "id" : 76, "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.", "created_at" : "2016-01-04T15:31:51.081Z", @@ -122,6 +123,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## List group issues Get a list of a group's issues. @@ -216,6 +219,7 @@ Example response: "updated_at" : "2016-01-04T15:31:46.176Z", "created_at" : "2016-01-04T15:31:46.176Z", "closed_at" : null, + "closed_by" : null, "user_notes_count": 1, "due_date": null, "web_url": "http://example.com/example/example/issues/1", @@ -233,6 +237,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## List project issues Get a list of a project's issues. @@ -326,6 +332,14 @@ Example response: "updated_at" : "2016-01-04T15:31:46.176Z", "created_at" : "2016-01-04T15:31:46.176Z", "closed_at" : "2016-01-05T15:31:46.176Z", + "closed_by" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, "user_notes_count": 1, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/1", @@ -343,6 +357,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Single issue Get a single project issue. @@ -409,6 +425,8 @@ Example response: "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", "created_at" : "2016-01-04T15:31:46.176Z", + "closed_at" : null, + "closed_by" : null, "subscribed": false, "user_notes_count": 1, "due_date": null, @@ -432,6 +450,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## New issue Creates a new project issue. @@ -484,6 +504,7 @@ Example response: "description" : null, "updated_at" : "2016-01-07T12:44:33.959Z", "closed_at" : null, + "closed_by" : null, "milestone" : null, "subscribed" : true, "user_notes_count": 0, @@ -508,6 +529,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Edit issue Updates an existing project issue. This call is also used to mark an issue as @@ -556,6 +579,14 @@ Example response: "description" : null, "updated_at" : "2016-01-07T12:55:16.213Z", "closed_at" : "2016-01-08T12:55:16.213Z", + "closed_by" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, "iid" : 15, "labels" : [ "bug" @@ -587,6 +618,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Delete an issue Only for admins and project owners. Soft deletes the issue in question. @@ -640,6 +673,7 @@ Example response: "created_at": "2016-04-05T21:41:45.652Z", "updated_at": "2016-04-07T12:20:17.596Z", "closed_at": null, + "closed_by": null, "labels": [], "milestone": null, "assignees": [{ @@ -687,6 +721,8 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Subscribe to an issue Subscribes the authenticated user to an issue to receive notifications. @@ -719,6 +755,7 @@ Example response: "created_at": "2016-04-05T21:41:45.652Z", "updated_at": "2016-04-07T12:20:17.596Z", "closed_at": null, + "closed_by": null, "labels": [], "milestone": null, "assignees": [{ @@ -766,6 +803,9 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Unsubscribe from an issue Unsubscribes the authenticated user from the issue to not receive notifications @@ -807,6 +847,8 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon", "web_url": "https://gitlab.example.com/keyon" }, + "closed_at": null, + "closed_by": null, "author": { "name": "Vivian Hermann", "username": "orville", @@ -927,6 +969,9 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + +**Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. + ## Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -1112,6 +1157,8 @@ Example response: "assignee": null, "source_project_id": 1, "target_project_id": 1, + "closed_at": null, + "closed_by": null, "labels": [], "work_in_progress": false, "milestone": null, @@ -1206,3 +1253,4 @@ Example response: [ce-13004]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13004 [ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016 +[ce-17042]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17042 diff --git a/doc/api/jobs.md b/doc/api/jobs.md index e7060e154f4..db4fe2f6880 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -294,9 +294,10 @@ Example of response ## Get job artifacts -> [Introduced][ce-2893] in GitLab 8.5 +> **Notes**: +- [Introduced][ce-2893] in GitLab 8.5. -Get job artifacts of a project +Get job artifacts of a project. ``` GET /projects/:id/jobs/:job_id/artifacts @@ -307,8 +308,10 @@ GET /projects/:id/jobs/:job_id/artifacts | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | +Example requests: + ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" +curl --location --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" ``` Response: @@ -322,7 +325,8 @@ Response: ## Download the artifacts archive -> [Introduced][ce-5347] in GitLab 8.10. +> **Notes**: +- [Introduced][ce-5347] in GitLab 8.10. Download the artifacts archive from the given reference name and job provided the job finished successfully. @@ -339,7 +343,7 @@ Parameters | `ref_name` | string | yes | The ref from a repository (can only be branch or tag name, not HEAD or SHA) | | `job` | string | yes | The name of the job | -Example request: +Example requests: ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index de5207fc5e4..5467187788a 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -8,6 +8,14 @@ Start a new export. +The endpoint also accepts an `upload` param. This param is a hash that contains +all the necessary information to upload the exported project to a web server or +to any S3-compatible platform. At the moment we only support binary +data file uploads to the final server. + +If the `upload` params is present, `upload[url]` param is required. + (**Note:** This feature was introduced in GitLab 10.7) + ```http POST /projects/:id/export ``` @@ -16,9 +24,12 @@ POST /projects/:id/export | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | no | Overrides the project description | +| `upload` | hash | no | Hash that contains the information to upload the exported project to a web server | +| `upload[url]` | string | yes | The URL to upload the project | +| `upload[http_method]` | string | no | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` | ```console -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "description=Foo Bar" https://gitlab.example.com/api/v4/projects/1/export +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export --data "description=FooBar&upload[http_method]=PUT&upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd" ``` ```json @@ -43,7 +54,11 @@ GET /projects/:id/export curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export ``` -Status can be one of `none`, `started`, or `finished`. +Status can be one of `none`, `started`, `after_export_action` or `finished`. The +`after_export_action` state represents that the export process has been completed successfully and +the platform is performing some actions on the resulted file. For example, sending +an email notifying the user to download the file, uploading the exported file +to a web server, etc. `_links` are only present when export has finished. diff --git a/doc/api/projects.md b/doc/api/projects.md index 271ee91dc72..f388fae42a9 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1344,3 +1344,7 @@ Read more in the [Project members](members.md) documentation. ## Project badges Read more in the [Project Badges](project_badges.md) documentation. + +## Issue and merge request description templates + +The non-default [issue and merge request description templates](../user/project/description_templates.md) are managed inside the project's repository. So you can manage them via the API through the [Repositories API](repositories.md) and the [Repository Files API](repository_files.md).
\ No newline at end of file diff --git a/doc/api/runners.md b/doc/api/runners.md index 7495c6cdedb..f384ac57bfe 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -153,7 +153,8 @@ Example response: "mysql" ], "version": null, - "access_level": "ref_protected" + "access_level": "ref_protected", + "maximum_timeout": 3600 } ``` @@ -174,6 +175,7 @@ PUT /runners/:id | `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | | `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | +| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | ``` curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" @@ -211,7 +213,8 @@ Example response: "tag2" ], "version": null, - "access_level": "ref_protected" + "access_level": "ref_protected", + "maximum_timeout": null } ``` diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 42dc6ef36ba..691370d7195 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -1,22 +1,28 @@ # Browser Performance Testing with the Sitespeed.io container -This example shows how to run the [Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on your code by using -GitLab CI/CD and [Sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. +This example shows how to run the +[Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on +your code by using GitLab CI/CD and [Sitespeed.io](https://www.sitespeed.io) +using Docker-in-Docker. -First, you need a GitLab Runner with the [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). - -Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called `performance`: +First, you need a GitLab Runner with the +[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called +`performance`: ```yaml +performance: stage: performance image: docker:git + variables: + URL: https://example.com services: - docker:dind script: - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/10-5/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js - mkdir sitespeed-results - - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results https://my.website.com + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL - mv sitespeed-results/data/performance.json performance.json artifacts: paths: @@ -24,37 +30,84 @@ Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called `performan - sitespeed-results/ ``` -This will create a `performance` job in your CI/CD pipeline and will run Sitespeed.io against the webpage you define. The GitLab plugin for Sitespeed.io is downloaded in order to export key metrics to JSON. The full HTML Sitespeed.io report will also be saved as an artifact, and if you have Pages enabled it can be viewed directly in your browser. For further customization options of Sitespeed.io, including the ability to provide a list of URLs to test, please consult their [documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/). +The above example will: + +1. Create a `performance` job in your CI/CD pipeline and will run + Sitespeed.io against the webpage you defined in `URL`. +1. The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for + Sitespeed.io is downloaded in order to export key metrics to JSON. The full + HTML Sitespeed.io report will also be saved as an artifact, and if you have + [GitLab Pages](../../user/project/pages/index.md) enabled, it can be viewed + directly in your browser. + +For further customization options of Sitespeed.io, including the ability to +provide a list of URLs to test, please consult +[their documentation](https://www.sitespeed.io/documentation/sitespeed.io/configuration/). -For [GitLab Premium](https://about.gitlab.com/products/) users, key metrics are automatically -extracted and shown right in the merge request widget. Learn more about [Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html). +TIP: **Tip:** +For [GitLab Premium](https://about.gitlab.com/pricing/) users, key metrics are automatically +extracted and shown right in the merge request widget. Learn more about +[Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html). ## Performance testing on Review Apps -The above CI YML is great for testing against static environments, and it can be extended for dynamic environments. There are a few extra steps to take to set this up: -1. The `performance` job should run after the environment has started. -1. In the `deploy` job, persist the hostname so it is available to the `performance` job. The same can be done for static environments like staging and production to unify the code path. Saving it as an artifact is as simple as `echo $CI_ENVIRONMENT_URL > environment_url.txt`. -1. In the `performance` job read the artifact into an environment variable, like `$CI_ENVIRONMENT_URL`, and use it to parameterize the test URL's. -1. Now you can run the Sitespeed.io container against the desired hostname and paths. +The above CI YML is great for testing against static environments, and it can +be extended for dynamic environments. There are a few extra steps to take to +set this up: -A simple `performance` job would look like: +1. The `performance` job should run after the dynamic environment has started. +1. In the `review` job, persist the hostname and upload it as an artifact so + it's available to the `performance` job (the same can be done for static + environments like staging and production to unify the code path). Saving it + as an artifact is as simple as `echo $CI_ENVIRONMENT_URL > environment_url.txt` + in your job's `script`. +1. In the `performance` job, read the previous artifact into an environment + variable, like `$CI_ENVIRONMENT_URL`, and use it to parameterize the test + URLs. +1. You can now run the Sitespeed.io container against the desired hostname and + paths. + +Your `.gitlab-ci.yml` file would look like: ```yaml +stages: + - deploy + - performance + +review: + stage: deploy + environment: + name: review/$CI_COMMIT_REF_SLUG + url: http://$CI_COMMIT_REF_SLUG.$APPS_DOMAIN + script: + - run_deploy_script + - echo $CI_ENVIRONMENT_URL > environment_url.txt + artifacts: + paths: + - environment_url.txt + only: + - branches + except: + - master + +performance: stage: performance image: docker:git services: - docker:dind + dependencies: + - review script: - export CI_ENVIRONMENT_URL=$(cat environment_url.txt) - mkdir gitlab-exporter - - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/10-5/index.js + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js - mkdir sitespeed-results - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results "$CI_ENVIRONMENT_URL" - mv sitespeed-results/data/performance.json performance.json artifacts: paths: - - performance.json - - sitespeed-results/ + - performance.json + - sitespeed-results/ ``` -A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml).
\ No newline at end of file +A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml). diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md index ec5e5afb8c6..64a759a9a99 100644 --- a/doc/ci/examples/code_climate.md +++ b/doc/ci/examples/code_climate.md @@ -15,13 +15,8 @@ codequality: services: - docker:dind script: - - docker pull codeclimate/codeclimate - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env SOURCE_CODE="$PWD" \ - --volume "$PWD":/code \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code + - docker run --env SOURCE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code artifacts: paths: [codeclimate.json] ``` diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index e80e246c5dd..2dcdc2d41ec 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -111,7 +111,7 @@ We also use two secure variables: ## Storing API keys Secure Variables can added by going to your project's -**Settings âž” Pipelines âž” Secret variables**. The variables that are defined +**Settings âž” CI / CD âž” Secret variables**. The variables that are defined in the project settings are sent along with the build script to the Runner. The secure variables are stored out of the repository. Never store secrets in your project's `.gitlab-ci.yml`. It is also important that the secret's value diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 856d7f264e4..301cccc80a3 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -2,6 +2,11 @@ > Introduced in GitLab 8.8. +NOTE: **Note:** +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +you may need to enable pipeline triggering in your project's +**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. + ## Pipelines A pipeline is a group of [jobs][] that get executed in [stages][](batches). @@ -121,9 +126,8 @@ The basic requirements is that there are two numbers separated with one of the following (you can even use them interchangeably): - a space -- a forward slash (`/`) +- a slash (`/`) - a colon (`:`) -- a dot (`.`) >**Note:** More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index f64e868d390..fec0ff87326 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -126,6 +126,11 @@ git push origin master Now if you go to the **Pipelines** page you will see that the pipeline is pending. +NOTE: **Note:** +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +you may need to enable pipeline triggering in your project's +**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. + You can also go to the **Commits** page and notice the little pause icon next to the commit SHA. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 7a7b50b294d..60dc2ef9ac5 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -35,7 +35,7 @@ are: A Runner that is specific only runs for the specified project(s). A shared Runner can run jobs for every project that has enabled the option **Allow shared Runners** -under **Settings âž” CI/CD**. +under **Settings > CI/CD**. Projects with high demand of CI activity can also benefit from using specific Runners. By having dedicated Runners you are guaranteed that the Runner is not @@ -76,7 +76,7 @@ Registering a specific can be done in two ways: To create a specific Runner without having admin rights to the GitLab instance, visit the project you want to make the Runner work for in GitLab: -1. Go to **Settings âž” CI/CD** to obtain the token +1. Go to **Settings > CI/CD** to obtain the token 1. [Register the Runner][register] ### Making an existing shared Runner specific @@ -85,7 +85,7 @@ If you are an admin on your GitLab instance, you can turn any shared Runner into a specific one, but not the other way around. Keep in mind that this is a one way transition. -1. Go to the Runners in the admin area **Overview âž” Runners** (`/admin/runners`) +1. Go to the Runners in the admin area **Overview > Runners** (`/admin/runners`) and find your Runner 1. Enable any projects under **Restrict projects for this Runner** to be used with the Runner @@ -101,7 +101,7 @@ can be changed afterwards under each Runner's settings. To lock/unlock a Runner: -1. Visit your project's **Settings âž” CI/CD** +1. Visit your project's **Settings > CI/CD** 1. Find the Runner you wish to lock/unlock and make sure it's enabled 1. Click the pencil button 1. Check the **Lock to current projects** option @@ -115,7 +115,7 @@ you can enable the Runner also on any other project where you have Master permis To enable/disable a Runner in your project: -1. Visit your project's **Settings âž” CI/CD** +1. Visit your project's **Settings > CI/CD** 1. Find the Runner you wish to enable/disable 1. Click **Enable for this project** or **Disable for this project** @@ -124,6 +124,13 @@ Consider that if you don't lock your specific Runner to a specific project, any user with Master role in you project can assign your runner to another arbitrary project without requiring your authorization, so use it with caution. +An admin can enable/disable a specific Runner for projects: + +1. Navigate to **Admin > Runners** +2. Find the Runner you wish to enable/disable +3. Click edit on the Runner +4. Click **Enable** or **Disable** on the project + ## Protected Runners > @@ -136,7 +143,7 @@ Whenever a Runner is protected, the Runner picks only jobs created on To protect/unprotect Runners: -1. Visit your project's **Settings âž” CI/CD** +1. Visit your project's **Settings > CI/CD** 1. Find a Runner you want to protect/unprotect and make sure it's enabled 1. Click the pencil button besides the Runner name 1. Check the **Protected** option @@ -231,6 +238,38 @@ To make a Runner pick tagged/untagged jobs: 1. Check the **Run untagged jobs** option 1. Click **Save changes** for the changes to take effect +### Setting maximum job timeout for a Runner + +For each Runner you can specify a _maximum job timeout_. Such timeout, +if smaller than [project defined timeout], will take the precedence. This +feature can be used to prevent Shared Runner from being appropriated +by a project by setting a ridiculous big timeout (e.g. one week). + +When not configured, Runner will not override project timeout. + +How this feature will work: + +**Example 1 - Runner timeout bigger than project timeout** + +1. You set the _maximum job timeout_ for a Runner to 24 hours +1. You set the _CI/CD Timeout_ for a project to **2 hours** +1. You start a job +1. The job, if running longer, will be timeouted after **2 hours** + +**Example 2 - Runner timeout not configured** + +1. You remove the _maximum job timeout_ configuration from a Runner +1. You set the _CI/CD Timeout_ for a project to **2 hours** +1. You start a job +1. The job, if running longer, will be timeouted after **2 hours** + +**Example 3 - Runner timeout smaller than project timeout** + +1. You set the _maximum job timeout_ for a Runner to **30 minutes** +1. You set the _CI/CD Timeout_ for a project to 2 hours +1. You start a job +1. The job, if running longer, will be timeouted after **30 minutes** + ### Be careful with sensitive information With some [Runner Executors](https://docs.gitlab.com/runner/executors/README.html), @@ -259,12 +298,6 @@ Mentioned briefly earlier, but the following things of Runners can be exploited. We're always looking for contributions that can mitigate these [Security Considerations](https://docs.gitlab.com/runner/security/). -[install]: http://docs.gitlab.com/runner/install/ -[fifo]: https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics) -[register]: http://docs.gitlab.com/runner/register/ -[protected branches]: ../../user/project/protected_branches.md -[protected tags]: ../../user/project/protected_tags.md - ## Determining the IP address of a Runner > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17286) in GitLab 10.6. @@ -297,3 +330,10 @@ You can find the IP address of a Runner for a specific project by: 1. On the details page you should see a row for "IP Address"  + +[install]: http://docs.gitlab.com/runner/install/ +[fifo]: https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics) +[register]: http://docs.gitlab.com/runner/register/ +[protected branches]: ../../user/project/protected_branches.md +[protected tags]: ../../user/project/protected_tags.md +[project defined timeout]: ../../user/project/pipelines/settings.html#timeout diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index bd4aeb006bd..9f268f47e6f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -449,6 +449,72 @@ export CI_REGISTRY_USER="gitlab-ci-token" export CI_REGISTRY_PASSWORD="longalfanumstring" ``` +## Variables expressions + +> Variables expressions were added in GitLab 10.7. + +It is possible to use variables expressions with only / except policies in +`.gitlab-ci.yml`. By using this approach you can limit what builds are going to +be created within a pipeline after pushing code to GitLab. + +This is particularly useful in combination with secret variables and triggered +pipeline variables. + +```yaml +deploy: + script: cap staging deploy + environment: staging + only: + variables: + - $RELEASE == "staging" + - $STAGING +``` + +Each provided variables expression is going to be evaluated before creating +a pipeline. + +If any of the conditions in `variables` evaluates to truth when using `only`, +a new job is going to be created. If any of the expressions evaluates to truth +when `except` is being used, a job is not going to be created. + +This follows usual rules for `only` / `except` policies. + +### Supported syntax + +Below you can find currently supported syntax reference: + +1. Equality matching using a string + + Example: `$VARIABLE == "some value"` + + You can use equality operator `==` to compare a variable content to a + string. We support both, double quotes and single quotes to define a string + value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'` + are supported. `"some value" == $VARIABLE` is correct too. + +1. Checking for an undefined value + + It sometimes happens that you want to check whether variable is defined or + not. To do that, you can compare variable to `null` value, like + `$VARIABLE == null`. This expression is going to evaluate to truth if + variable is not set. + +1. Checking for an empty variable + + If you want to check whether a variable is defined, but is empty, you can + simply compare it against an empty string, like `$VAR == ''`. + +1. Comparing two variables + + It is possible to compare two variables. `$VARIABLE_1 == $VARIABLE_2`. + +1. Variable presence check + + If you only want to create a job when there is some variable present, + which means that it is defined and non-empty, you can simply use + variable name as an expression, like `$STAGING`. If `$STAGING` variable + is defined, and is non empty, expression will evaluate to truth. + [ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 "Simple protection of CI secret variables" [eep]: https://about.gitlab.com/products/ "Available only in GitLab Premium" [envs]: ../environments.md diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index c2b06e53c2f..be114e7008e 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -10,6 +10,11 @@ of your repository and contains definitions of how your project should be built. If you want a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md). +NOTE: **Note:** +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +you may need to enable pipeline triggering in your project's +**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. + ## Jobs The YAML file defines a set of jobs with constraints stating when they should @@ -315,9 +320,14 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Two keys are now available: `refs` and `kubernetes`. Refs strategy equals to -simplified only/except configuration, whereas kubernetes strategy accepts only -`active` keyword. +Three keys are now available: `refs`, `kubernetes` and `variables`. +Refs strategy equals to simplified only/except configuration, whereas +kubernetes strategy accepts only `active` keyword. + +`variables` keyword is used to define variables expressions. In other words +you can use predefined variables / secret variables / project / group or +environment-scoped variables to define an expression GitLab is going to +evaluate in order to decide whether a job should be created or not. See the example below. Job is going to be created only when pipeline has been scheduled or runs for a `master` branch, and only if kubernetes service is @@ -332,6 +342,20 @@ job: kubernetes: active ``` +Example of using variables expressions: + +```yaml +deploy: + only: + refs: + - branches + variables: + - $RELEASE == "staging" + - $STAGING +``` + +Learn more about variables expressions on a separate page. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index fea92e740cb..3ba03d2d591 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -33,6 +33,26 @@ rest of the code should be as close to the CE files as possible. [single code base]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2952#note_41016454 +### EE-specific comments + +When complete separation can't be achieved with the `ee/` directory, you can wrap +code in EE specific comments to designate the difference from CE/EE and add +some context for someone resolving a conflict. + +```rb +# EE-specific start +stub_licensed_features(variable_environment_scope: true) +# EE specific end +``` + +```haml +-# EE-specific start += render 'ci/variables/environment_scope', form_field: form_field, variable: variable +-# EE-specific end +``` + +EE-specific comments should not be backported to CE. + ### Detection of EE-only files For each commit (except on `master`), the `ee-files-location-check` CI job tries @@ -350,6 +370,255 @@ class beneath the `EE` module just as you would normally. For example, if CE has LDAP classes in `lib/gitlab/ldap/` then you would place EE-specific LDAP classes in `ee/lib/ee/gitlab/ldap`. +### Code in `lib/api/` + +It can be very tricky to extend EE features by a single line of `prepend`, +and for each different [Grape](https://github.com/ruby-grape/grape) feature, +we might need different strategies to extend it. To apply different strategies +easily, we would use `extend ActiveSupport::Concern` in the EE module. + +Put the EE module files following +[EE features based on CE features](#ee-features-based-on-ce-features). + +#### EE API routes + +For EE API routes, we put them in a `prepended` block: + +``` ruby +module EE + module API + module MergeRequests + extend ActiveSupport::Concern + + prepended do + params do + requires :id, type: String, desc: 'The ID of a project' + end + resource :projects, requirements: ::API::API::PROJECT_ENDPOINT_REQUIREMENTS do + # ... + end + end + end + end +end +``` + +Note that due to namespace differences, we need to use the full qualifier for some +constants. + +#### EE params + +We can define `params` and utilize `use` in another `params` definition to +include params defined in EE. However, we need to define the "interface" first +in CE in order for EE to override it. We don't have to do this in other places +due to `prepend`, but Grape is complex internally and we couldn't easily do +that, so we'll follow regular object-oriented practices that we define the +interface first here. + +For example, suppose we have a few more optional params for EE, given this CE +API code: + +``` ruby +module API + class MergeRequests < Grape::API + # EE::API::MergeRequests would override the following helpers + helpers do + params :optional_params_ee do + end + end + + prepend EE::API::MergeRequests + + params :optional_params do + # CE specific params go here... + + use :optional_params_ee + end + end +end +``` + +And then we could override it in EE module: + +``` ruby +module EE + module API + module MergeRequests + extend ActiveSupport::Concern + + prepended do + helpers do + params :optional_params_ee do + # EE specific params go here... + end + end + end + end + end +end +``` + +This way, the only difference between CE and EE for that API file would be +`prepend EE::API::MergeRequests`. + +#### EE helpers + +To make it easy for an EE module to override the CE helpers, we need to define +those helpers we want to extend first. Try to do that immediately after the +class definition to make it easy and clear: + +``` ruby +module API + class JobArtifacts < Grape::API + # EE::API::JobArtifacts would override the following helpers + helpers do + def authorize_download_artifacts! + authorize_read_builds! + end + end + + prepend EE::API::JobArtifacts + end +end +``` + +And then we can follow regular object-oriented practices to override it: + +``` ruby +module EE + module API + module JobArtifacts + extend ActiveSupport::Concern + + prepended do + helpers do + def authorize_download_artifacts! + super + check_cross_project_pipelines_feature! + end + end + end + end + end +end +``` + +#### EE-specific behaviour + +Sometimes we need EE-specific behaviour in some of the APIs. Normally we could +use EE methods to override CE methods, however API routes are not methods and +therefore can't be simply overridden. We need to extract them into a standalone +method, or introduce some "hooks" where we could inject behavior in the CE +route. Something like this: + +``` ruby +module API + class MergeRequests < Grape::API + helpers do + # EE::API::MergeRequests would override the following helpers + def update_merge_request_ee(merge_request) + end + end + + prepend EE::API::MergeRequests + + put ':id/merge_requests/:merge_request_iid/merge' do + merge_request = find_project_merge_request(params[:merge_request_iid]) + + # ... + + update_merge_request_ee(merge_request) + + # ... + end + end +end +``` + +Note that `update_merge_request_ee` doesn't do anything in CE, but +then we could override it in EE: + +``` ruby +module EE + module API + module MergeRequests + extend ActiveSupport::Concern + + prepended do + helpers do + def update_merge_request_ee(merge_request) + # ... + end + end + end + end + end +end +``` + +#### EE `route_setting` + +It's very hard to extend this in an EE module, and this is simply storing +some meta-data for a particular route. Given that, we could simply leave the +EE `route_setting` in CE as it won't hurt and we are just not going to use +those meta-data in CE. + +We could revisit this policy when we're using `route_setting` more and whether +or not we really need to extend it from EE. For now we're not using it much. + +#### Utilizing class methods for setting up EE-specific data + +Sometimes we need to use different arguments for a particular API route, and we +can't easily extend it with an EE module because Grape has different context in +different blocks. In order to overcome this, we could use class methods from the +API class. + +For example, in one place we need to pass an extra argument to +`at_least_one_of` so that the API could consider an EE-only argument as the +least argument. This is not quite beautiful but it's working: + +``` ruby +module API + class MergeRequests < Grape::API + def self.update_params_at_least_one_of + %i[ + assignee_id + description + ] + end + + prepend EE::API::MergeRequests + + params do + at_least_one_of(*::API::MergeRequests.update_params_at_least_one_of) + end + end +end +``` + +And then we could easily extend that argument in the EE class method: + +``` ruby +module EE + module API + module MergeRequests + extend ActiveSupport::Concern + + class_methods do + def update_params_at_least_one_of + super.push(*%i[ + squash + ]) + end + end + end + end +end +``` + +It could be annoying if we need this for a lot of routes, but it might be the +simplest solution right now. + ### Code in `spec/` When you're testing EE-only features, avoid adding examples to the @@ -405,12 +674,13 @@ to avoid conflicts during CE to EE merge. } } -/* EE-specific styles */ +// EE-specific start .section-body.ee-section-body { .section-title { background: $gl-header-color-cyan; } } +// EE-specific end ``` ## gitlab-svgs diff --git a/doc/development/new_fe_guide/style/javascript.md b/doc/development/new_fe_guide/style/javascript.md index 480d50a211f..57efd9353bc 100644 --- a/doc/development/new_fe_guide/style/javascript.md +++ b/doc/development/new_fe_guide/style/javascript.md @@ -1,3 +1,195 @@ # JavaScript style guide -> TODO: Add content +We use [Airbnb's JavaScript Style Guide][airbnb-style-guide] and it's accompanying linter to manage most of our JavaScript style guidelines. + +In addition to the style guidelines set by Airbnb, we also have a few specific rules listed below. + +> **Tip:** +You can run eslint locally by running `yarn eslint` + +## Arrays + +<a name="avoid-foreach"></a><a name="1.1"></a> +- [1.1](#avoid-foreach) **Avoid ForEach when mutating data** Use `map`, `reduce` or `filter` instead of `forEach` when mutating data. This will minimize mutations in functions ([which is aligned with Airbnb's style guide][airbnb-minimize-mutations]) + +``` +// bad +users.forEach((user, index) => { + user.id = index; +}); + +// good +const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); +}); +``` + +## Functions + +<a name="limit-params"></a><a name="2.1"></a> +- [2.1](#limit-params) **Limit number of parameters** If your function or method has more than 3 parameters, use an object as a parameter instead. + +``` +// bad +function a(p1, p2, p3) { + // ... +}; + +// good +function a(p) { + // ... +}; +``` + +## Classes & constructors + +<a name="avoid-constructor-side-effects"></a><a name="3.1"></a> +- [3.1](#avoid-constructor-side-effects) **Avoid side effects in constructors** Avoid making some operations in the `constructor`, such as asynchronous calls, API requests and DOM manipulations. Prefer moving them into separate functions. This will make tests easier to write and code easier to maintain. + + ```javascript + // bad + class myClass { + constructor(config) { + this.config = config; + axios.get(this.config.endpoint) + } + } + + // good + class myClass { + constructor(config) { + this.config = config; + } + + makeRequest() { + axios.get(this.config.endpoint) + } + } + const instance = new myClass(); + instance.makeRequest(); + + ``` + +<a name="avoid-classes-to-handle-dom-events"></a><a name="3.2"></a> +- [3.2](#avoid-classes-to-handle-dom-events) **Avoid classes to handle DOM events** If the only purpose of the class is to bind a DOM event and handle the callback, prefer using a function. + +``` +// bad +class myClass { + constructor(config) { + this.config = config; + } + + init() { + document.addEventListener('click', () => {}); + } +} + +// good + +const myFunction = () => { + document.addEventListener('click', () => { + // handle callback here + }); +} +``` + +<a name="element-container"></a><a name="3.3"></a> +- [3.3](#element-container) **Pass element container to constructor** When your class manipulates the DOM, receive the element container as a parameter. +This is more maintainable and performant. + +``` +// bad +class a { + constructor() { + document.querySelector('.b'); + } +} + +// good +class a { + constructor(options) { + options.container.querySelector('.b'); + } +} +``` + +## Type Casting & Coercion + +<a name="use-parseint"></a><a name="4.1"></a> +- [4.1](#use-parseint) **Use ParseInt** Use `ParseInt` when converting a numeric string into a number. + +``` +// bad +Number('10') + + +// good +parseInt('10', 10); +``` + +## CSS Selectors + +<a name="use-js-prefix"></a><a name="5.1"></a> +- [5.1](#use-js-prefix) **Use js prefix** If a CSS class is only being used in JavaScript as a reference to the element, prefix the class name with `js-` + +``` +// bad +<button class="add-user"></button> + +// good +<button class="js-add-user"></button> +``` + +## Modules + +<a name="use-absolute-paths"></a><a name="6.1"></a> +- [6.1](#use-absolute-paths) **Use absolute paths for nearby modules** Use absolute paths if the module you are importing is less than two levels up. + +``` +// bad +import GitLabStyleGuide from '~/guides/GitLabStyleGuide'; + +// good +import GitLabStyleGuide from '../GitLabStyleGuide'; +``` + +<a name="use-relative-paths"></a><a name="6.2"></a> +- [6.2](#use-relative-paths) **Use relative paths for distant modules** If the module you are importing is two or more levels up, use a relative path instead of an absolute path. + +``` +// bad +import GitLabStyleGuide from '../../../guides/GitLabStyleGuide'; + +// good +import GitLabStyleGuide from '~/GitLabStyleGuide'; +``` + +<a name="global-namespace"></a><a name="6.3"></a> +- [6.3](#global-namespace) **Do not add to global namespace** + +<a name="domcontentloaded"></a><a name="6.4"></a> +- [6.4](#domcontentloaded) **Do not use DOMContentLoaded in non-page modules** Imported modules should act the same each time they are loaded. `DOMContentLoaded` events are only allowed on modules loaded in the `/pages/*` directory because those are loaded dynamically with webpack. + +## Security + +<a name="avoid-xss"></a><a name="7.1"></a> +- [7.1](#avoid-xss) **Avoid XSS** Do not use `innerHTML`, `append()` or `html()` to set content. It opens up too many vulnerabilities. + +## ESLint + +<a name="disable-eslint-file"></a><a name="8.1"></a> +- [8.1](#disable-eslint-file) **Disabling ESLint in new files** Do not disable ESLint when creating new files. Existing files may have existing rules disabled due to legacy compatibility reasons but they are in the process of being refactored. + +<a name="disable-eslint-rule"></a><a name="8.2"></a> +- [8.2](#disable-eslint-rule) **Disabling ESLint rule** Do not disable specific ESLint rules. Due to technical debt, you may disable the following rules only if you are invoking/instantiating existing code modules + + - [no-new][no-new] + - [class-method-use-this][class-method-use-this] + +> Note: Disable these rules on a per line basis. This makes it easier to refactor in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line` + +[airbnb-style-guide]: https://github.com/airbnb/javascript +[airbnb-minimize-mutations]: https://github.com/airbnb/javascript#testing--for-real +[no-new]: http://eslint.org/docs/rules/no-new +[class-method-use-this]: http://eslint.org/docs/rules/class-methods-use-this diff --git a/doc/install/README.md b/doc/install/README.md index 87f6969b415..9724b56910d 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -36,7 +36,7 @@ the full process of installing GitLab on Google Container Engine (GKE), pushing - [Install on AWS](https://about.gitlab.com/aws/) - _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) - Quickly test any version of GitLab on DigitalOcean using Docker Machine. -- [Getting started with GitLab and DigitalOcean](ttps://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): requirements, installation process, updates. +- [Getting started with GitLab and DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): requirements, installation process, updates. - [Demo: Cloud Native Development with GitLab](https://about.gitlab.com/2017/04/18/cloud-native-demo/): video demonstration on how to install GitLab on Kubernetes, build a project, create Review Apps, store Docker images in Container Registry, deploy to production on Kubernetes, and monitor with Prometheus. ## Database diff --git a/doc/integration/google.md b/doc/integration/google.md index 07a700f7b64..ae1d848f439 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -35,7 +35,7 @@ In Google's side: 1. You should now be able to see a Client ID and Client secret. Note them down or keep this page open as you will need them later. -1. From the **Dashboard** select **ENABLE APIS AND SERVICES > Compute > Google Container Engine API > Enable** +1. From the **Dashboard** select **ENABLE APIS AND SERVICES > Compute > Google Kubernetes Engine API > Enable** On your GitLab server: diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 8d0afa9e692..7f028565412 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -44,7 +44,7 @@ This decision is made on a case-by-case basis. ## Upgrade recommendations -We encourage everyone to run the latest stable release to ensure that you can +We encourage everyone to run the [latest stable release](https://about.gitlab.com/blog/categories/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. diff --git a/doc/update/10.5-to-10.6.md b/doc/update/10.5-to-10.6.md index f5c5c305726..2f90fb62c4a 100644 --- a/doc/update/10.5-to-10.6.md +++ b/doc/update/10.5-to-10.6.md @@ -103,7 +103,7 @@ rm go1.8.3.linux-amd64.tar.gz ```bash cd /home/git/gitlab -sudo -u git -H git fetch --all +sudo -u git -H git fetch --all --prune sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically sudo -u git -H git checkout -- locale ``` @@ -131,7 +131,7 @@ sudo -u git -H git checkout 10-6-stable-ee ```bash cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags +sudo -u git -H git fetch --all --tags --prune sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) sudo -u git -H bin/compile ``` @@ -146,7 +146,7 @@ If you are not using Linux you may have to run `gmake` instead of ```bash cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all --tags +sudo -u git -H git fetch --all --tags --prune sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) sudo -u git -H make ``` @@ -182,7 +182,7 @@ sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gital ```shell cd /home/git/gitaly -sudo -u git -H git fetch --all --tags +sudo -u git -H git fetch --all --tags --prune sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) sudo -u git -H make ``` diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 83eb7a225b2..d5f77191938 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -51,7 +51,7 @@ Below are the settings for [GitLab Pages]. | TLS certificates support| yes | no | The maximum size of your Pages site is regulated by the artifacts maximum size -which is part of [GitLab CI](#gitlab-ci). +which is part of [GitLab CI/CD](#gitlab-ci-cd). ## GitLab CI/CD @@ -61,6 +61,14 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | ----------- | ----------------- | ------------- | | Artifacts maximum size | 1G | 100M | +## Repository size limit + +The maximum size your Git repository is allowed to be including LFS. + +| Setting | GitLab.com | Default | +| ----------- | ----------------- | ------------- | +| Repository size including LFS | 10G | Unlimited | + ## Shared Runners Shared Runners on GitLab.com run in [autoscale mode] and powered by diff --git a/doc/user/project/integrations/img/jira_workflow_screenshot.png b/doc/user/project/integrations/img/jira_workflow_screenshot.png Binary files differdeleted file mode 100644 index e62fb202613..00000000000 --- a/doc/user/project/integrations/img/jira_workflow_screenshot.png +++ /dev/null diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index fc527663db0..5933bcedc8b 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -113,7 +113,20 @@ in the table below. | `JIRA API URL` | The base URL to the JIRA instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | | `Username` | The user name created in [configuring JIRA step](#configuring-jira). | | `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `Transition ID` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | +| `Transition ID` | This is the ID of a transition that moves issues to the desired state. **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | + +### Getting a transition ID + +In the most recent JIRA UI, you can no longer see transition IDs in the workflow +administration UI. You can get the ID you need in either of the following ways: + +1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` + using an issue that is in the appropriate "open" state +1. By mousing over the link for the transition you want and looking for the + "action" parameter in the URL + +Note that the transition ID may vary between workflows (e.g., bug vs. story), +even if the status you are changing to is the same. After saving the configuration, your GitLab project will be able to interact with all JIRA projects in your JIRA instance and you'll see the JIRA link on the GitLab project pages that takes you to the appropriate JIRA project. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index d403d5698a9..b4a842f33d6 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -251,7 +251,7 @@ Different issue board features are available in different [GitLab tiers](https:/ | Tier | Number of project issue boards | Board with configuration in project issue boards | Number of group issue boards | Board with configuration in group issue boards | | --- | --- | --- | --- | --- | -| Libre | 1 | No | 1 | No | +| Core | 1 | No | 1 | No | | Starter | Multiple | Yes | 1 | No | | Premium | Multiple | Yes | Multiple | Yes | | Ultimate | Multiple | Yes | Multiple | Yes | diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 43451844f2d..6cead7b9961 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -27,6 +27,13 @@ The default value is 60 minutes. Decrease the time limit if you want to impose a hard limit on your jobs' running time or increase it otherwise. In any case, if the job surpasses the threshold, it is marked as failed. +### Timeout overriding on Runner level + +> - [Introduced][ce-17221] in GitLab 10.7. + +Project defined timeout (either specific timeout set by user or the default +60 minutes timeout) may be [overridden on Runner level][timeout overriding]. + ## Custom CI config path > - [Introduced][ce-12509] in GitLab 9.4. @@ -152,5 +159,7 @@ into your `README.md`: [var]: ../../../ci/yaml/README.md#git-strategy [coverage report]: #test-coverage-parsing +[timeout overriding]: ../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner [ce-9362]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9362 [ce-12509]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12509 +[ce-17221]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17221 diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index ae131d51305..376f4e3cbe4 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -132,8 +132,9 @@ Use GPG to [sign your commits](gpg_signed_commits/index.md). ## Repository size -In GitLab.com, your repository size limit it 10GB. For other instances, -the repository size is limited by your system administrators. +On GitLab.com, your [repository size limit is 10GB](../../gitlab_com/index.md#repository-size-limit) +(including LFS). For other instances, the repository size is limited by your +system administrators. You can also [reduce a repository size using Git](reducing_the_repo_size_using_git.md). diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md index cac3cb599dd..f824756c10c 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -19,7 +19,7 @@ There are various configuration options to help GitLab server administrators: * Changing the location of LFS object storage * Setting up AWS S3 compatible object storage -### Omnibus packages +### Configuration for Omnibus installations In `/etc/gitlab/gitlab.rb`: @@ -33,7 +33,7 @@ gitlab_rails['lfs_enabled'] = false gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" ``` -### Installations from source +### Configuration for installations from source In `config/gitlab.yml`: @@ -44,20 +44,21 @@ In `config/gitlab.yml`: storage_path: /mnt/storage/lfs-objects ``` -## Setting up S3 compatible object storage +## Storing the LFS objects in an S3-compatible object storage -> **Note:** [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. -> Available in [GitLab CE][ce] 10.7 +> [Introduced][ee-2760] in [GitLab Premium][eep] 10.0. Brought to GitLab Core +in 10.7. -It is possible to store LFS objects on remote object storage instead of on a local disk. +It is possible to store LFS objects on a remote object storage which allows you +to offload storage to an external AWS S3 compatible service, freeing up disk +space locally. You can also host your own S3 compatible storage decoupled from +GitLab, with with a service such as [Minio](https://www.minio.io/). -This allows you to offload storage to an external AWS S3 compatible service, freeing up disk space locally. You can also host your own S3 compatible storage decoupled from GitLab, with with a service such as [Minio](https://www.minio.io/). +Object storage currently transfers files first to GitLab, and then on the +object storage in a second stage. This can be done either by using a rake task +to transfer existing objects, or in a background job after each file is received. -Object storage currently transfers files first to GitLab, and then on the object storage in a second stage. This can be done either by using a rake task to transfer existing objects, or in a background job after each file is received. - -### Object Storage Settings - -For source installations the following settings are nested under `lfs:` and then `object_store:`. On omnibus installs they are prefixed by `lfs_object_store_`. +The following general settings are supported. | Setting | Description | Default | |---------|-------------|---------| @@ -68,9 +69,7 @@ For source installations the following settings are nested under `lfs:` and then | `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | | `connection` | Various connection options described below | | -#### S3 compatible connection settings - -The connection settings match those provided by [Fog](https://github.com/fog), and are as follows: +The `connection` settings match those provided by [Fog](https://github.com/fog). | Setting | Description | Default | |---------|-------------|---------| @@ -82,8 +81,43 @@ The connection settings match those provided by [Fog](https://github.com/fog), a | `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | | `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | +### S3 for Omnibus installations + +On Omnibus installations, the settings are prefixed by `lfs_object_store_`: + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with + the values you want: + + ```ruby + gitlab_rails['lfs_object_store_enabled'] = true + gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects" + gitlab_rails['lfs_object_store_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N', + 'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE', + # The below options configure an S3 compatible host instead of AWS + 'host' => 'localhost', + 'endpoint' => 'http://127.0.0.1:9000', + 'path_style' => true + } + ``` + +1. Save the file and [reconfigure GitLab]s for the changes to take effect. +1. Migrate any existing local LFS objects to the object storage: + + ```bash + gitlab-rake gitlab:lfs:migrate + ``` + + This will migrate existing LFS objects to object storage. New LFS objects + will be forwarded to object storage unless + `gitlab_rails['lfs_object_store_background_upload']` is set to false. -### From source +### S3 for installations from source + +For source installations the settings are nested under `lfs:` and then +`object_store:`: 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -108,44 +142,13 @@ The connection settings match those provided by [Fog](https://github.com/fog), a 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local LFS objects to the object storage: - ```bash - sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production - ``` - - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless - `gitlab_rails['lfs_object_store_background_upload']` is set to false. - -### In Omnibus - -1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with - the values you want: - - ```ruby - gitlab_rails['lfs_object_store_enabled'] = true - gitlab_rails['lfs_object_store_remote_directory'] = "lfs-objects" - gitlab_rails['lfs_object_store_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-central-1', - 'aws_access_key_id' => '1ABCD2EFGHI34JKLM567N', - 'aws_secret_access_key' => 'abcdefhijklmnopQRSTUVwxyz0123456789ABCDE', - # The below options configure an S3 compatible host instead of AWS - 'host' => 'localhost', - 'endpoint' => 'http://127.0.0.1:9000', - 'path_style' => true - } - ``` - -1. Save the file and [reconfigure GitLab]s for the changes to take effect. -1. Migrate any existing local LFS objects to the object storage: - - ```bash - gitlab-rake gitlab:lfs:migrate - ``` + ```bash + sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production + ``` - This will migrate existing LFS objects to object storage. New LFS objects - will be forwarded to object storage unless - `gitlab_rails['lfs_object_store_background_upload']` is set to false. + This will migrate existing LFS objects to object storage. New LFS objects + will be forwarded to object storage unless `background_upload` is set to + false. ## Storage statistics diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md index 3d8d3ce8f13..e612646cfbc 100644 --- a/doc/workflow/todos.md +++ b/doc/workflow/todos.md @@ -28,11 +28,10 @@ A Todo appears in your Todos dashboard when: - an issue or merge request is assigned to you, - you are `@mentioned` in an issue or merge request, be it the description of the issue/merge request or in a comment, +- you are `@mentioned` in a comment on a commit, - a job in the CI pipeline running for your merge request failed, but this job is not allowed to fail. ->**Note:** Commenting on a commit will _not_ trigger a Todo. - ### Directly addressed Todos > [Introduced][ce-7926] in GitLab 9.0. |
