diff options
Diffstat (limited to 'doc')
64 files changed, 1388 insertions, 431 deletions
diff --git a/doc/README.md b/doc/README.md index a2e152ce383..c929ba7a59e 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,6 @@ --- comments: false +description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- # GitLab Documentation diff --git a/doc/administration/external_database.md b/doc/administration/external_database.md new file mode 100644 index 00000000000..31199f2cdc7 --- /dev/null +++ b/doc/administration/external_database.md @@ -0,0 +1,17 @@ +# Configure GitLab using an external PostgreSQL service + +If you're hosting GitLab on a cloud provider, you can optionally use a +managed service for PostgreSQL. For example, AWS offers a managed Relational +Database Service (RDS) that runs PostgreSQL. + +Alternatively, you may opt to manage your own PostgreSQL instance or cluster +separate from the GitLab Omnibus package. + +If you use a cloud-managed service, or provide your own PostgreSQL instance: + +1. Setup PostgreSQL according to the + [database requirements document](../install/requirements.md#database). +1. Set up a `gitlab` username with a password of your choice. The `gitlab` user + needs privileges to create the `gitlabhq_production` database. +1. Configure the GitLab application servers with the appropriate details. + This step is covered in [Configuring GitLab for HA](high_availability/gitlab.md). diff --git a/doc/administration/index.md b/doc/administration/index.md index b472ca5b4d8..df935095e61 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -1,3 +1,7 @@ +--- +description: 'Learn how to install, configure, update, and maintain your GitLab instance.' +--- + # Administrator documentation **[CORE ONLY]** Learn how to administer your GitLab instance (Community Edition and @@ -40,6 +44,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. [source installations](../install/installation.md#installation-from-source). - [Environment variables](environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab. - [Plugins](plugins.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. +- [Enforcing Terms of Service](../user/admin_area/settings/terms.md) #### Customizing GitLab's appearance diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index 84a1ffeec98..f0b2054a7f3 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -40,3 +40,98 @@ To change the location where the job logs will be stored, follow the steps below [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" + +## New live trace architecture + +> [Introduced][ce-18169] in GitLab 10.4. + +> **Notes**: +- This feature is still Beta, which could impact GitLab.com/on-premises instances, and in the worst case scenario, traces will be lost. +- This feature is still being discussed in [an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46097) for the performance improvements. +- This feature is off by default. Please check below how to enable/disable this featrue. + +**What is "live trace"?** + +Job trace that is sent by runner while jobs are running. You can see live trace in job pages UI. +The live traces are archived once job finishes. + +**What is new architecture?** + +So far, when GitLab Runner sends a job trace to GitLab-Rails, traces have been saved to file storage as text files. +This was a problem for [Cloud Native-compatible GitLab application](https://gitlab.com/gitlab-com/migration/issues/23) where GitLab had to rely on File Storage. + +This new live trace architecture stores chunks of traces in Redis and database instead of file storage. +Redis is used as first-class storage, and it stores up-to 128kB. Once the full chunk is sent it will be flushed to database. Afterwhile, the data in Redis and database will be archived to ObjectStorage. + +Here is the detailed data flow. + +1. GitLab Runner picks a job from GitLab-Rails +1. GitLab Runner sends a piece of trace to GitLab-Rails +1. GitLab-Rails appends the data to Redis +1. If the data in Redis is fulfilled 128kB, the data is flushed to Database. +1. 2.~4. is continued until the job is finished +1. Once the job is finished, GitLab-Rails schedules a sidekiq worker to archive the trace +1. The sidekiq worker archives the trace to Object Storage, and cleanup the trace in Redis and Database + +**How to check if it's on or off?** + +```ruby +Feature.enabled?('ci_enable_live_trace') +``` + +**How to enable?** + +```ruby +Feature.enable('ci_enable_live_trace') +``` + +>**Note:** +The transition period will be handled gracefully. Upcoming traces will be generated with the new architecture, and on-going live traces will stay with the legacy architecture (i.e. on-going live traces won't be re-generated forcibly with the new architecture). + +**How to disable?** + +```ruby +Feature.disable('ci_enable_live_trace') +``` + +>**Note:** +The transition period will be handled gracefully. Upcoming traces will be generated with the legacy architecture, and on-going live traces will stay with the new architecture (i.e. on-going live traces won't be re-generated forcibly with the legacy architecture). + +**Redis namespace:** + +`Gitlab::Redis::SharedState` + +**Potential impact:** + +- This feature could incur data loss: + - Case 1: When all data in Redis are accidentally flushed. + - On-going live traces could be recovered by re-sending traces (This is supported by all versions of GitLab Runner) + - Finished jobs which has not archived live traces will lose the last part (~128kB) of trace data. + - Case 2: When sidekiq workers failed to archive (e.g. There was a bug that prevents archiving process, Sidekiq inconsistancy, etc): + - Currently all trace data in Redis will be deleted after one week. If the sidekiq workers can't finish by the expiry date, the part of trace data will be lost. +- This feature could consume all memory on Redis instance. If the number of jobs is 1000, 128MB (128kB * 1000) is consumed. +- This feature could pressure Database replication lag. `INSERT` are generated to indicate that we have trace chunk. `UPDATE` with 128kB of data is issued once we receive multiple chunks. +- and so on + +**How to test?** + +We're currently evaluating this feature on dev.gitalb.org or staging.gitlab.com to verify this features. Here is the list of tests/measurements. + +- Features: + - Live traces should be visible on job pages + - Archived traces should be visible on job pages + - Live traces should be archived to Object storage + - Live traces should be cleaned up after archived + - etc +- Performance: + - Schedule 1000~10000 jobs and let GitLab-runners process concurrently. Measure memoery presssure, IO load, etc. + - etc +- Failover: + - Simulate Redis outage + - etc + +**How to verify the correctnesss?** + +- TBD + +[ce-44935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18169 diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9b3b1e48efd..c0221533f13 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -1,3 +1,7 @@ +--- +description: 'Learn how to administer GitLab Pages.' +--- + # GitLab Pages administration > **Notes:** @@ -8,8 +12,6 @@ GitLab from source, follow the [Pages source installation document](source.md). - To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. ---- - This document describes how to set up the _latest_ GitLab Pages feature. Make sure to read the [changelog](#changelog) if you are upgrading to a new GitLab version as it may include new features and changes needed to be made in your @@ -24,8 +26,6 @@ SNI and exposes pages using HTTP2 by default. You are encouraged to read its [README][pages-readme] to fully understand how it works. ---- - In the case of [custom domains](#custom-domains) (but not [wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on ports `80` and/or `443`. For that reason, there is some flexibility in the way diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 39b1883375e..ecc4ac6b29b 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -1,4 +1,4 @@ -# Project import/export +# Project import/export administration **[CORE ONLY]** >**Note:** > diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index ee37ea49874..efeec9db517 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -13,12 +13,12 @@ checks failed you can see their output on the admin log page under ## Periodic checks -When enabled, GitLab periodically runs a repository check on all project -repositories and wiki repositories in order to detect data corruption problems. +When enabled, GitLab periodically runs a repository check on all project +repositories and wiki repositories in order to detect data corruption. A project will be checked no more than once per month. If any projects fail their repository checks all GitLab administrators will receive an email -notification of the situation. This notification is sent out once a week on -Sunday, by default. +notification of the situation. This notification is sent out once a week, +by default, midnight at the start of Sunday. ## Disabling periodic checks @@ -28,16 +28,18 @@ panel. ## What to do if a check failed If the repository check fails for some repository you should look up the error -in repocheck.log (in the admin panel or on disk; see -`/var/log/gitlab/gitlab-rails` for Omnibus installations or -`/home/git/gitlab/log` for installations from source). Once you have -resolved the issue use the admin panel to trigger a new repository check on -the project. This will clear the 'check failed' state. +in `repocheck.log`: + +- in the [admin panel](logs.md#repocheck.log) +- or on disk, see: + - `/var/log/gitlab/gitlab-rails` for Omnibus installations + - `/home/git/gitlab/log` for installations from source If for some reason the periodic repository check caused a lot of false -alarms you can choose to clear ALL repository check states from the -'Settings' page of the admin panel. +alarms you can choose to clear *all* repository check states by +clicking "Clear all repository checks" on the **Settings** page of the +admin panel (`/admin/application_settings`). --- [ce-3232]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3232 "Auto git fsck" -[git-fsck]: https://www.kernel.org/pub/software/scm/git/docs/git-fsck.html "git fsck documentation" +[git-fsck]: https://git-scm.com/docs/git-fsck "git fsck documentation" diff --git a/doc/api/runners.md b/doc/api/runners.md index f384ac57bfe..3ca07ce9795 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -411,3 +411,86 @@ DELETE /projects/:id/runners/:runner_id ``` curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9" ``` + +## Register a new Runner + +Register a new Runner for the instance. + +``` +POST /runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Registration token ([Read how to obtain a token](../ci/runners/README.md)) | +| `description`| string | no | Runner's description| +| `info` | hash | no | Runner's metadata | +| `active` | boolean| no | Whether the Runner is active | +| `locked` | boolean| no | Whether the Runner should be locked for current project | +| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs | +| `tag_list` | Array[String] | no | List of Runner's tags | +| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | + +``` +curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 201 | Runner was created | + +Example response: + +```json +{ + "id": "12345", + "token": "6337ff461c94fd3fa32ba3b1ff4125" +} +``` + +## Delete a registered Runner + +Deletes a registed Runner. + +``` +DELETE /runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Runner's authentication token | + +``` +curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 204 | Runner was deleted | + +## Verify authentication for a registered Runner + +Validates authentication credentials for a registered Runner. + +``` +POST /runners/verify +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Runner's authentication token | + +``` +curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 200 | Credentials are valid | +| 403 | Credentials are invalid | diff --git a/doc/api/services.md b/doc/api/services.md index 92f12acbc73..ec632125325 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -968,7 +968,7 @@ Group Chat Software Set Microsoft Teams service for a project. ``` -PUT /projects/:id/services/microsoft_teams +PUT /projects/:id/services/microsoft-teams ``` Parameters: @@ -982,7 +982,7 @@ Parameters: Delete Microsoft Teams service for a project. ``` -DELETE /projects/:id/services/microsoft_teams +DELETE /projects/:id/services/microsoft-teams ``` ### Get Microsoft Teams service settings @@ -990,7 +990,7 @@ DELETE /projects/:id/services/microsoft_teams Get Microsoft Teams service settings for a project. ``` -GET /projects/:id/services/microsoft_teams +GET /projects/:id/services/microsoft-teams ``` ## Mattermost notifications diff --git a/doc/api/settings.md b/doc/api/settings.md index 0b5b1f0c134..e06b1bfb6df 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -53,6 +53,8 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "enforce_terms": true, + "terms": "Hello world!", } ``` @@ -153,6 +155,8 @@ PUT /application/settings | `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. | +| `enforce_terms` | boolean | no | Enforce application ToS to all users | +| `terms` | text | yes (if `enforce_terms` is true) | Markdown content for the ToS | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal @@ -195,5 +199,7 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "enforce_terms": true, + "terms": "Hello world!", } ``` diff --git a/doc/articles/openshift_and_gitlab/index.md b/doc/articles/openshift_and_gitlab/index.md index b7594cfef7f..76fdb2eb00a 100644 --- a/doc/articles/openshift_and_gitlab/index.md +++ b/doc/articles/openshift_and_gitlab/index.md @@ -1 +1,4 @@ -This document was moved to [another location](../../install/openshift_and_gitlab/index.html). +--- +redirect_to: '../../install/openshift_and_gitlab/index.html' +--- + diff --git a/doc/ci/README.md b/doc/ci/README.md index 6aa0e5885db..8d1d72c2a2b 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,5 +1,6 @@ --- comments: false +description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Integration, Continuous Deployment, and Continuous Delivery toolset to build, test, and deploy your application." --- # GitLab Continuous Integration (GitLab CI/CD) diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index eb76521cc02..a9501f6c577 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -23,7 +23,7 @@ sast:container: - docker:stable-dind script: - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair arminc/clair-local-scan:v2.0.1 + - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.1 - apk add -U wget ca-certificates - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 821413900fd..703a7f030ed 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -11,7 +11,7 @@ Ideally, the GitLab Runner should not be installed on the same machine as GitLab Read the [requirements documentation](../../install/requirements.md#gitlab-runner) for more information. -## Shared vs specific Runners +## Shared, specific and group Runners After [installing the Runner][install], you can either register it as shared or specific. You can only register a shared Runner if you have admin access to @@ -32,6 +32,9 @@ are: Runners. For example, if you want to deploy a certain project, you can setup a specific Runner to have the right credentials for this. The [usage of tags](#using-tags) may be useful in this case. Specific Runners process jobs using a [FIFO] queue. +- **Group Runners** are useful when you have multiple projects under one group + and would like all projects to have access to a set of Runners. Group Runners + process jobs using a [FIFO] queue. 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** @@ -66,7 +69,7 @@ Runners to disabled. ## Registering a specific Runner -Registering a specific can be done in two ways: +Registering a specific Runner can be done in two ways: 1. Creating a Runner with the project registration token 1. Converting a shared Runner into a specific Runner (one-way, admin only) @@ -79,6 +82,14 @@ visit the project you want to make the Runner work for in GitLab: 1. Go to **Settings > CI/CD** to obtain the token 1. [Register the Runner][register] +## Registering a group Runner + +Creating a group Runner requires Master permissions for the group. To create a +group Runner visit the group you want to make the Runner work for in GitLab: + +1. Go to **Settings > CI/CD** to obtain the token +1. [Register the Runner][register] + ### Making an existing shared Runner specific If you are an admin on your GitLab instance, you can turn any shared Runner into @@ -121,7 +132,7 @@ To enable/disable a Runner in your project: > **Note**: 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 +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: diff --git a/doc/ci/services/docker-services.md b/doc/ci/services/docker-services.md index 787c5e462e4..e5fc7a3c85f 100644 --- a/doc/ci/services/docker-services.md +++ b/doc/ci/services/docker-services.md @@ -1,9 +1,3 @@ --- -comments: false +redirect_to: 'README.md' --- - -# GitLab CI Services - -- [Using MySQL](mysql.md) -- [Using PostgreSQL](postgres.md) -- [Using Redis](redis.md) diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 38a988f4507..42367bf13f7 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -41,6 +41,9 @@ future GitLab releases.** | **CI_COMMIT_REF_SLUG** | 9.0 | all | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | | **CI_COMMIT_SHA** | 9.0 | all | The commit revision for which project is built | | **CI_COMMIT_TAG** | 9.0 | 0.5 | The commit tag name. Present only when building tags. | +| **CI_COMMIT_MESSAGE** | 10.8 | all | The full commit message. | +| **CI_COMMIT_TITLE** | 10.8 | all | The title of the commit - the full first line of the message | +| **CI_COMMIT_DESCRIPTION** | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | | **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 | Marks that the 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. | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fb6d9826d08..2a17a51d7f8 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -738,10 +738,15 @@ cache: rspec: script: test cache: + key: rspec paths: - binaries/ ``` +Note that since cache is shared between jobs, if you're using different +paths for different jobs, you should also set a different **cache:key** +otherwise cache content can be overwritten. + ### `cache:key` > Introduced in GitLab Runner v1.0.0. @@ -756,10 +761,9 @@ or any other way that fits your workflow. This way, you can fine tune caching, allowing you to cache data between different jobs or even different branches. The `cache:key` variable can use any of the -[predefined variables](../variables/README.md), and the default key, if not set, -is `$CI_JOB_NAME-$CI_COMMIT_REF_NAME` which translates as "per-job and -per-branch". It is the default across the project, therefore everything is -shared between pipelines and jobs running on the same branch by default. +[predefined variables](../variables/README.md), and the default key, if not +set, is just literal `default` which means everything is shared between each +pipelines and jobs by default, starting from GitLab 9.0. NOTE: **Note:** The `cache:key` variable cannot contain the `/` character, or the equivalent @@ -779,7 +783,7 @@ If you use **Windows Batch** to run your shell scripts you need to replace ```yaml cache: - key: "%CI_JOB_STAGE%-%CI_COMMIT_REF_SLUG%" + key: "%CI_COMMIT_REF_SLUG%" paths: - binaries/ ``` @@ -789,7 +793,7 @@ If you use **Windows PowerShell** to run your shell scripts you need to replace ```yaml cache: - key: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_SLUG" + key: "$env:CI_COMMIT_REF_SLUG" paths: - binaries/ ``` @@ -1572,7 +1576,7 @@ capitalization, the commit will be created but the pipeline will be skipped. ## Validate the .gitlab-ci.yml Each instance of GitLab CI has an embedded debug tool called Lint, which validates the -content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your +content of your `.gitlab-ci.yml` files. You can find the Lint under the page `ci/lint` of your project namespace (e.g, `http://gitlab-example.com/gitlab-org/project-123/-/ci/lint`) ## Using reserved keywords diff --git a/doc/container_registry/README.md b/doc/container_registry/README.md index fe3e4681ba7..5d2f5edcb18 100644 --- a/doc/container_registry/README.md +++ b/doc/container_registry/README.md @@ -1 +1 @@ -This document was moved in [user/project/container_registry](../user/project/container_registry.md). +This document was moved to [another location](../user/project/container_registry.md). diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index d14ba6ad522..680c51e7524 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -1,8 +1,3 @@ --- -comments: false +redirect_to: '../user/project/issues/automatic_issue_closing.md' --- - -This document was split into: - -- [administration/issue_closing_pattern.md](../administration/issue_closing_pattern.md). -- [user/project/issues/automatic_issue_closing](../user/project/issues/automatic_issue_closing.md). diff --git a/doc/development/README.md b/doc/development/README.md index 3c77e99b8cf..898c60e96c0 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -1,5 +1,6 @@ --- comments: false +description: 'Learn how to contribute to GitLab.' --- # GitLab development guides @@ -18,6 +19,7 @@ comments: false - [Code review guidelines](code_review.md) for reviewing code and having code reviewed. - [Automatic CE->EE merge](automatic_ce_ee_merge.md) - [Guidelines for implementing Enterprise Edition features](ee_features.md) +- [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) ## UX and frontend guides diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 5da015ca557..5d595c33915 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -1,3 +1,7 @@ +--- +description: 'Writing styles, markup, formatting, and reusing regular expressions throughout the GitLab Documentation.' +--- + # Documentation style guidelines The documentation style guide defines the markup structure used in @@ -21,23 +25,39 @@ Check the GitLab handbook for the [writing styles guidelines](https://about.gitl - Use [single spaces][] instead of double spaces - Jump a line between different markups (e.g., after every paragraph, header, list, etc) - Capitalize "G" and "L" in GitLab -- Capitalize feature, products, and methods names. E.g.: GitLab Runner, Geo, -Issue Boards, Git, Prometheus, Continuous Integration. +- Use sentence case for titles, headings, labels, menu items, and buttons. +- Use title case when referring to [features](https://about.gitlab.com/features/) or [products](https://about.gitlab.com/pricing/), and methods. Note that some features are also objects (e.g. "Merge Requests" and "merge requests"). E.g.: GitLab Runner, Geo, Issue Boards, Git, Prometheus, Continuous Integration. ## Formatting +- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`) +- Use undescore (`_`) for text in italics (`_italic_`) +- Jump a line between different markups, for example: + + ```md + ## Header + + Paragraph. + + - List item + - List item + ``` + +### Punctuation + +For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). + +### Ordered and unordered lists + - Use dashes (`-`) for unordered lists instead of asterisks (`*`) - Use the number one (`1`) for ordered lists -- Use underscores (`_`) to mark a word or text in italics -- Use double asterisks (`**`) to mark a word or text in bold -- When using lists, prefer not to end each item with a period. You can use - them if there are multiple sentences, just keep the last sentence without - a period +- For punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/) ## Headings -- Add only one H1 title in each document, by adding `#` at the beginning of - it (when using markdown). For subheadings, use `##`, `###` and so on +- Add **only one H1** in each document, by adding `#` at the beginning of + it (when using markdown). The `h1` will be the document `<title>`. +- For subheadings, use `##`, `###` and so on - Avoid putting numbers in headings. Numbers shift, hence documentation anchor links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with @@ -106,21 +126,75 @@ Inside the document: - If a heading is placed right after an image, always add three dashes (`---`) between the image and the heading -## Notes +## Alert boxes -- Notes should be quoted with the word `Note:` being bold. Use this form: +Whenever you want to call the attention to a particular sentence, +use the following markup for highlighting. - ```md - >**Note:** - This is something to note. - ``` +_Note that the alert boxes only work for one paragraph only. Multiple paragraphs, +lists, headers, etc will not render correctly._ + +### Note + +```md +NOTE: **Note:** +This is something to note. +``` + +How it renders in docs.gitlab.com: + +NOTE: **Note:** +This is something to note. + +### Tip + +```md +TIP: **Tip:** +This is a tip. +``` + +How it renders in docs.gitlab.com: + +TIP: **Tip:** +This is a tip. + +### Caution + +```md +CAUTION: **Caution:** +This is something to be cautious about. +``` + +How it renders in docs.gitlab.com: + +CAUTION: **Caution:** +This is something to be cautious about. + +### Danger - which renders to: +```md +DANGER: **Danger:** +This is a breaking change, a bug, or something very important to note. +``` + +How it renders in docs.gitlab.com: - >**Note:** - This is something to note. +DANGER: **Danger:** +This is a breaking change, a bug, or something very important to note. - If the note spans across multiple lines it's OK to split the line. +## Blockquotes + +For highlighting a text within a blue blockquote, use this format: + +```md +> This is a blockquote. +``` + +which renders in docs.gitlab.com to: + +> This is a blockquote. + +If the text spans across multiple lines it's OK to split the line. ## Specific sections and terms @@ -137,7 +211,7 @@ below. > Introduced in GitLab 8.3. ``` -- If possible every feature should have a link to the MR, issue, or epic that introduced it. +- Whenever possible, every feature should have a link to the MR, issue, or epic that introduced it. The above note would be then transformed to: ```md @@ -152,11 +226,9 @@ below. the feature is available in: ```md - > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/products/) 8.3. + > [Introduced][ee-1234] in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. ``` - Otherwise, leave this mention out. - ### Product badges When a feature is available in EE-only tiers, add the corresponding tier according to the diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 3b4dfd50761..6d3796e7560 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,5 +1,8 @@ # Frontend Development Guidelines +> **Notice:** +We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md) + This document describes various guidelines to ensure consistency and quality across GitLab's frontend team. @@ -45,6 +48,9 @@ Common JavaScript design patterns in GitLab's codebase. ## [Vue.js Best Practices](vue.md) Vue specific design patterns and practices. +## [Vuex](vuex.md) +Vuex specific design patterns and practices. + ## [Axios](axios.md) Axios specific practices and gotchas. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 677168937c7..04dfe418dbe 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -310,7 +310,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. })); ``` -1. Don not use a singleton for the service or the store +1. Do not use a singleton for the service or the store ```javascript // bad class Store { @@ -328,9 +328,11 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. } } ``` +1. Use `.vue` for Vue templates. Do not use `%template` in HAML. #### Naming -1. **Extensions**: Use `.vue` extension for Vue components. + +1. **Extensions**: Use `.vue` extension for Vue components. Do not use `.js` as file extension ([#34371]). 1. **Reference Naming**: Use PascalCase for their instances: ```javascript // bad @@ -364,6 +366,8 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. <component my-prop="prop" /> ``` +[#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 + #### Alignment 1. Follow these alignment styles for the template method: 1. With more than one attribute, all attributes should be on a new line: diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 9c4b0e86351..f971d8b7388 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -1,29 +1,7 @@ # Vue -For more complex frontend features, we recommend using Vue.js. It shares -some ideas with React.js as well as Angular. - To get started with Vue, read through [their documentation][vue-docs]. -## When to use Vue.js - -We recommend using Vue for more complex features. Here are some guidelines for when to use Vue.js: - -- If you are starting a new feature or refactoring an old one that highly interacts with the DOM; -- For real time data updates; -- If you are creating a component that will be reused elsewhere; - -## When not to use Vue.js - -We don't want to refactor all GitLab frontend code into Vue.js, here are some guidelines for -when not to use Vue.js: - -- Adding or changing static information; -- Features that highly depend on jQuery will be hard to work with Vue.js; -- Features without reactive data; - -As always, the Frontend Architectural Experts are available to help with any Vue or JavaScript questions. - ## Vue architecture All new features built with Vue.js must follow a [Flux architecture][flux]. @@ -57,15 +35,15 @@ new_feature │ └── ... ├── stores │ └── new_feature_store.js -├── services +├── services # only when not using vuex │ └── new_feature_service.js -├── new_feature_bundle.js +├── index.js ``` _For consistency purposes, we recommend you to follow the same structure._ Let's look into each of them: -### A `*_bundle.js` file +### A `index.js` file This is the index file of your new feature. This is where the root Vue instance of the new feature should be. @@ -144,30 +122,30 @@ in one table would not be a good use of this pattern. You can read more about components in Vue.js site, [Component System][component-system] #### Components Gotchas -1. Using SVGs in components: To use an SVG in a template we need to make it a property we can access through the component. -A `prop` and a property returned by the `data` functions require `vue` to set a `getter` and a `setter` for each of them. -The SVG should be a computed property in order to improve performance, note that computed properties are cached based on their dependencies. - -```javascript -// bad -import svg from 'svg.svg'; -data() { - return { - myIcon: svg, - }; -}; - -// good -import svg from 'svg.svg'; -computed: { - myIcon() { - return svg; - } -} -``` +1. Using SVGs icons in components: To use an SVG icon in a template use the `icon.vue` +1. Using SVGs illustrations in components: To use an SVG illustrations in a template provide the path as a prop and display it through a standard img tag. + ```javascript + <script> + export default { + props: { + svgIllustrationPath: { + type: String, + required: true, + }, + }, + }; + <script> + <template> + <img :src="svgIllustrationPath" /> + </template> + ``` ### A folder for the Store +#### Vuex +Check this [page](vuex.md) for more details. + +#### Flux like state management The Store is a class that allows us to manage the state in a single source of truth. It is not aware of the service or the components. @@ -176,6 +154,8 @@ itself, please read this guide: [State Management][state-management] ### A folder for the Service +**If you are using Vuex you won't need this step** + The Service is a class used only to communicate with the server. It does not store or manipulate any data. It is not aware of the store or the components. We use [axios][axios] to communicate with the server. @@ -273,6 +253,9 @@ import Store from 'store'; import Service from 'service'; import TodoComponent from 'todoComponent'; export default { + components: { + todo: TodoComponent, + }, /** * Although most data belongs in the store, each component it's own state. * We want to show a loading spinner while we are fetching the todos, this state belong @@ -291,10 +274,6 @@ export default { }; }, - components: { - todo: TodoComponent, - }, - created() { this.service = new Service('todos'); @@ -476,201 +455,6 @@ need to test the rendered output. [Vue][vue-test] guide's to unit test show us e Refer to [mock axios](axios.md#mock-axios-response-on-tests) -## Vuex -To manage the state of an application you may use [Vuex][vuex-docs]. - -_Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs]. - -### Separation of concerns -Vuex is composed of State, Getters, Mutations, Actions and Modules. - -When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. -_Note:_ The action itself will not update the state, only a mutation should update the state. - -#### File structure -When using Vuex at GitLab, separate this concerns into different files to improve readability. If you can, separate the Mutation Types as well: - -``` -└── store - ├── index.js # where we assemble modules and export the store - ├── actions.js # actions - ├── mutations.js # mutations - ├── getters.js # getters - └── mutation_types.js # mutation types -``` -The following examples show an application that lists and adds users to the state. - -##### `index.js` -This is the entry point for our store. You can use the following as a guide: - -```javascript -import Vue from 'vue'; -import Vuex from 'vuex'; -import * as actions from './actions'; -import * as getters from './getters'; -import mutations from './mutations'; - -Vue.use(Vuex); - -export default new Vuex.Store({ - actions, - getters, - mutations, - state: { - users: [], - }, -}); -``` -_Note:_ If the state of the application is too complex, an individual file for the state may be better. - -##### `actions.js` -An action commits a mutation. In this file, we will write the actions that will commit the respective mutation: - -```javascript - import * as types from './mutation_types'; - - export const addUser = ({ commit }, user) => { - commit(types.ADD_USER, user); - }; -``` - -To dispatch an action from a component, use the `mapActions` helper: -```javascript -import { mapActions } from 'vuex'; - -{ - methods: { - ...mapActions([ - 'addUser', - ]), - onClickUser(user) { - this.addUser(user); - }, - }, -}; -``` - -##### `getters.js` -Sometimes we may need to get derived state based on store state, like filtering for a specific prop. This can be done through the `getters`: - -```javascript -// get all the users with pets -export getUsersWithPets = (state, getters) => { - return state.users.filter(user => user.pet !== undefined); -}; -``` - -To access a getter from a component, use the `mapGetters` helper: -```javascript -import { mapGetters } from 'vuex'; - -{ - computed: { - ...mapGetters([ - 'getUsersWithPets', - ]), - }, -}; -``` - -##### `mutations.js` -The only way to actually change state in a Vuex store is by committing a mutation. - -```javascript - import * as types from './mutation_types'; - - export default { - [types.ADD_USER](state, user) { - state.users.push(user); - }, - }; -``` - -##### `mutations_types.js` -From [vuex mutations docs][vuex-mutations]: -> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application. - -```javascript -export const ADD_USER = 'ADD_USER'; -``` - -### How to include the store in your application -The store should be included in the main component of your application: -```javascript - // app.vue - import store from 'store'; // it will include the index.js file - - export default { - name: 'application', - store, - ... - }; -``` - -### Vuex Gotchas -1. Avoid calling a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency through out the application. From Vuex docs: - - > why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action. - - ```javascript - // component.vue - - // bad - created() { - this.$store.commit('mutation'); - } - - // good - created() { - this.$store.dispatch('action'); - } - ``` -1. When possible, use mutation types instead of hardcoding strings. It will be less error prone. -1. The State will be accessible in all components descending from the use where the store is instantiated. - -### Testing Vuex -#### Testing Vuex concerns -Refer to [vuex docs][vuex-testing] regarding testing Actions, Getters and Mutations. - -#### Testing components that need a store -Smaller components might use `store` properties to access the data. -In order to write unit tests for those components, we need to include the store and provide the correct state: - -```javascript -//component_spec.js -import Vue from 'vue'; -import store from './store'; -import component from './component.vue' - -describe('component', () => { - let vm; - let Component; - - beforeEach(() => { - Component = Vue.extend(issueActions); - }); - - afterEach(() => { - vm.$destroy(); - }); - - it('should show a user', () => { - const user = { - name: 'Foo', - age: '30', - }; - - // populate the store - store.dispatch('addUser', user); - - vm = new Component({ - store, - propsData: props, - }).$mount(); - }); -}); -``` - [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments @@ -681,9 +465,5 @@ describe('component', () => { [vue-test]: https://vuejs.org/v2/guide/unit-testing.html [issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6 [flux]: https://facebook.github.io/flux -[vuex-docs]: https://vuex.vuejs.org -[vuex-structure]: https://vuex.vuejs.org/en/structure.html -[vuex-mutations]: https://vuex.vuejs.org/en/mutations.html -[vuex-testing]: https://vuex.vuejs.org/en/testing.html [axios]: https://github.com/axios/axios [axios-interceptors]: https://github.com/axios/axios#interceptors diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md new file mode 100644 index 00000000000..6a89bfc7721 --- /dev/null +++ b/doc/development/fe_guide/vuex.md @@ -0,0 +1,358 @@ +# Vuex +To manage the state of an application you should use [Vuex][vuex-docs]. + +_Note:_ All of the below is explained in more detail in the official [Vuex documentation][vuex-docs]. + +## Separation of concerns +Vuex is composed of State, Getters, Mutations, Actions and Modules. + +When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. +_Note:_ The action itself will not update the state, only a mutation should update the state. + +## File structure +When using Vuex at GitLab, separate this concerns into different files to improve readability: + +``` +└── store + ├── index.js # where we assemble modules and export the store + ├── actions.js # actions + ├── mutations.js # mutations + ├── getters.js # getters + ├── state.js # state + └── mutation_types.js # mutation types +``` +The following example shows an application that lists and adds users to the state. +(For a more complex example implementation take a look at the security applications store in [here](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store)) + +### `index.js` +This is the entry point for our store. You can use the following as a guide: + +```javascript +import Vue from 'vue'; +import Vuex from 'vuex'; +import * as actions from './actions'; +import * as getters from './getters'; +import mutations from './mutations'; +import state from './state'; + +Vue.use(Vuex); + +export default new Vuex.Store({ + actions, + getters, + mutations, + state, +}); +``` + +### `state.js` +The first thing you should do before writing any code is to design the state. + +Often we need to provide data from haml to our Vue application. Let's store it in the state for better access. + +```javascript + export default { + endpoint: null, + + isLoading: false, + error: null, + + isAddingUser: false, + errorAddingUser: false, + + users: [], + }; +``` + +#### Access `state` properties +You can use `mapState` to access state properties in the components. + +### `actions.js` +An action is a playload of information to send data from our application to our store. + +An action is usually composed by a `type` and a `payload` and they describe what happened. +Enforcing that every change is described as an action lets us have a clear understanting of what is going on in the app. + +In this file, we will write the actions that will call the respective mutations: + +```javascript + import * as types from './mutation_types'; + import axios from '~/lib/utils/axios-utils'; + import createFlash from '~/flash'; + + export const requestUsers = ({ commit }) => commit(types.REQUEST_USERS); + export const receiveUsersSuccess = ({ commit }, data) => commit(types.RECEIVE_USERS_SUCCESS, data); + export const receiveUsersError = ({ commit }, error) => commit(types.REQUEST_USERS_ERROR, error); + + export const fetchUsers = ({ state, dispatch }) => { + dispatch('requestUsers'); + + axios.get(state.endoint) + .then(({ data }) => dispatch('receiveUsersSuccess', data)) + .catch((error) => { + dispatch('receiveUsersError', error) + createFlash('There was an error') + }); + } + + export const requestAddUser = ({ commit }) => commit(types.REQUEST_ADD_USER); + export const receiveAddUserSuccess = ({ commit }, data) => commit(types.RECEIVE_ADD_USER_SUCCESS, data); + export const receiveAddUserError = ({ commit }, error) => commit(types.REQUEST_ADD_USER_ERROR, error); + + export const addUser = ({ state, dispatch }, user) => { + dispatch('requestAddUser'); + + axios.post(state.endoint, user) + .then(({ data }) => dispatch('receiveAddUserSuccess', data)) + .catch((error) => dispatch('receiveAddUserError', error)); + } +``` + +#### Actions Pattern: `request` and `receive` namespaces +When a request is made we often want to show a loading state to the user. + +Instead of creating an action to toggle the loading state and dispatch it in the component, +create: +1. An action `requestSomething`, to toggle the loading state +1. An action `receiveSomethingSuccess`, to handle the success callback +1. An action `receiveSomethingError`, to handle the error callback +1. An action `fetchSomething` to make the request. + 1. In case your application does more than a `GET` request you can use these as examples: + 1. `PUT`: `createSomething` + 2. `POST`: `updateSomething` + 3. `DELETE`: `deleteSomething` + +The component MUST only dispatch the `fetchNamespace` action. Actions namespaced with `request` or `receive` should not be called from the component +The `fetch` action will be responsible to dispatch `requestNamespace`, `receiveNamespaceSuccess` and `receiveNamespaceError` + +By following this pattern we guarantee: +1. All aplications follow the same pattern, making it easier for anyone to maintain the code +1. All data in the application follows the same lifecycle pattern +1. Actions are contained and human friendly +1. Unit tests are easier +1. Actions are simple and straightforward + +#### Dispatching actions +To dispatch an action from a component, use the `mapActions` helper: +```javascript +import { mapActions } from 'vuex'; + +{ + methods: { + ...mapActions([ + 'addUser', + ]), + onClickUser(user) { + this.addUser(user); + }, + }, +}; +``` + +#### `mutations.js` +The mutations specify how the application state changes in response to actions sent to the store. +The only way to change state in a Vuex store should be by committing a mutation. + +**It's a good idea to think of the state before writing any code.** + +Remember that actions only describe that something happened, they don't describe how the application state changes. + +**Never commit a mutation directly from a component** + +```javascript + import * as types from './mutation_types'; + + export default { + [types.REQUEST_USERS](state) { + state.isLoading = true; + }, + [types.RECEIVE_USERS_SUCCESS](state, data) { + // Do any needed data transformation to the received payload here + state.users = data; + state.isLoading = false; + }, + [types.REQUEST_USERS_ERROR](state, error) { + state.isLoading = false; + }, + [types.REQUEST_ADD_USER](state, user) { + state.isAddingUser = true; + }, + [types.RECEIVE_ADD_USER_SUCCESS](state, user) { + state.isAddingUser = false; + state.users.push(user); + }, + [types.REQUEST_ADD_USER_ERROR](state, error) { + state.isAddingUser = true; + state.errorAddingUser = error∂; + }, + }; +``` + +#### `getters.js` +Sometimes we may need to get derived state based on store state, like filtering for a specific prop. +Using a getter will also cache the result based on dependencies due to [how computed props work](https://vuejs.org/v2/guide/computed.html#Computed-Caching-vs-Methods) +This can be done through the `getters`: + +```javascript +// get all the users with pets +export const getUsersWithPets = (state, getters) => { + return state.users.filter(user => user.pet !== undefined); +}; +``` + +To access a getter from a component, use the `mapGetters` helper: +```javascript +import { mapGetters } from 'vuex'; + +{ + computed: { + ...mapGetters([ + 'getUsersWithPets', + ]), + }, +}; +``` + +#### `mutations_types.js` +From [vuex mutations docs][vuex-mutations]: +> It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application. + +```javascript +export const ADD_USER = 'ADD_USER'; +``` + +### How to include the store in your application +The store should be included in the main component of your application: +```javascript + // app.vue + import store from 'store'; // it will include the index.js file + + export default { + name: 'application', + store, + ... + }; +``` + +### Communicating with the Store +```javascript +<script> +import { mapActions, mapState, mapGetters } from 'vuex'; +import store from './store'; + +export default { + store, + computed: { + ...mapGetters([ + 'getUsersWithPets' + ]), + ...mapState([ + 'isLoading', + 'users', + 'error', + ]), + }, + methods: { + ...mapActions([ + 'fetchUsers', + 'addUser', + ]), + + onClickAddUser(data) { + this.addUser(data); + } + }, + + created() { + this.fetchUsers() + } +} +</script> +<template> + <ul> + <li v-if="isLoading"> + Loading... + </li> + <li v-else-if="error"> + {{ error }} + </li> + <template v-else> + <li + v-for="user in users" + :key="user.id" + > + {{ user }} + </li> + </template> + </ul> +</template> +``` + +### Vuex Gotchas +1. Do not call a mutation directly. Always use an action to commit a mutation. Doing so will keep consistency through out the application. From Vuex docs: + + > why don't we just call store.commit('action') directly? Well, remember that mutations must be synchronous? Actions aren't. We can perform asynchronous operations inside an action. + + ```javascript + // component.vue + + // bad + created() { + this.$store.commit('mutation'); + } + + // good + created() { + this.$store.dispatch('action'); + } + ``` +1. Use mutation types instead of hardcoding strings. It will be less error prone. +1. The State will be accessible in all components descending from the use where the store is instantiated. + +### Testing Vuex +#### Testing Vuex concerns +Refer to [vuex docs][vuex-testing] regarding testing Actions, Getters and Mutations. + +#### Testing components that need a store +Smaller components might use `store` properties to access the data. +In order to write unit tests for those components, we need to include the store and provide the correct state: + +```javascript +//component_spec.js +import Vue from 'vue'; +import store from './store'; +import component from './component.vue' + +describe('component', () => { + let vm; + let Component; + + beforeEach(() => { + Component = Vue.extend(issueActions); + }); + + afterEach(() => { + vm.$destroy(); + }); + + it('should show a user', () => { + const user = { + name: 'Foo', + age: '30', + }; + + // populate the store + store.dipatch('addUser', user); + + vm = new Component({ + store, + propsData: props, + }).$mount(); + }); +}); +``` + +[vuex-docs]: https://vuex.vuejs.org +[vuex-structure]: https://vuex.vuejs.org/en/structure.html +[vuex-mutations]: https://vuex.vuejs.org/en/mutations.html +[vuex-testing]: https://vuex.vuejs.org/en/testing.html diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 7b32e0a47e1..61fa5459b91 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -230,6 +230,11 @@ describe "#==" do end ``` +### Prometheus tests + +Prometheus metrics may be preserved from one test run to another. To ensure that metrics are +reset before each example, add the `:prometheus` tag to the Rspec test. + ### Matchers Custom matchers should be created to clarify the intent and/or hide the diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md index 9bca4637830..1c41fc7611f 100644 --- a/doc/development/writing_documentation.md +++ b/doc/development/writing_documentation.md @@ -1,3 +1,7 @@ +--- +description: Learn how to contribute to GitLab Documentation. +--- + # GitLab Documentation guidelines - **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. @@ -201,6 +205,19 @@ Things to note: built-in help page, that's why we omit it in `git grep`. - Use the checklist on the documentation MR description template. +#### Alternative redirection method + +Alternatively to the method described above, you can simply replace the content +of the old file with a frontmatter containing a redirect link: + +```yaml +--- +redirect_to: '../path/to/file/README.md' +--- +``` + +It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`. + ### Redirections for pages with Disqus comments If the documentation page being relocated already has any Disqus comments, diff --git a/doc/install/README.md b/doc/install/README.md index 5dadf57ea9a..27df03c6ac6 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -1,5 +1,6 @@ --- comments: false +description: Read through the GitLab installation methods. --- # Installation diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index b0c3ad960bb..21694b02d18 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -1,3 +1,8 @@ +--- +description: 'Learn how to spin up a +pre-configured GitLab VM on Microsoft Azure and have your very own private GitLab instance up and running in around 30 minutes.' +--- + # Install GitLab on Microsoft Azure > _This article was originally written by Dave Wentzel and [published on the GitLab Blog][Original-Blog-Post]._ diff --git a/doc/install/docker.md b/doc/install/docker.md index 933756072ff..c7dc9db70c5 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -1,4 +1,4 @@ -# GitLab Docker images +# Install GitLab with Docker [Docker](https://www.docker.com) and container technology have been revolutionizing the software world for the past few years. They combine the performance and efficiency of native execution with the abstraction, security, and immutability of virtualization. diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 2691495e0d4..ab5f7507f24 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -1,3 +1,7 @@ +--- +description: 'Learn how to install a GitLab instance on Google Cloud Platform.' +--- + # Installing GitLab on Google Cloud Platform  diff --git a/doc/install/installation.md b/doc/install/installation.md index fa5bcfa6f07..a0ae9017f71 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -301,9 +301,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 10-7-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 10-8-stable gitlab -**Note:** You can change `10-6-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `10-8-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index 9c5258c2cdf..98af87455ec 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -129,8 +129,8 @@ You may see a temporary error message `SchedulerPredicates failed due to Persist Add the GitLab Helm repository and initialize Helm: ```bash -helm repo add gitlab https://charts.gitlab.io helm init +helm repo add gitlab https://charts.gitlab.io ``` Once you have reviewed the [configuration settings](#configuring-and-installing-gitlab) you can install the chart. We recommending saving your configuration options in a `values.yaml` file for easier upgrades in the future. diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md index 7d8b8fc1597..aeaa739edab 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -1,4 +1,9 @@ +--- +description: 'Read through the different methods to deploy GitLab on Kubernetes.' +--- + # Installing GitLab on Kubernetes + > **Note**: These charts have been tested on Google Kubernetes Engine and Azure Container Service. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/charts.gitlab.io/issues). The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is @@ -16,6 +21,7 @@ should be deployed, upgraded, and configured. * [Community Contributed Charts](#community-contributed-charts): Community contributed charts, deprecated by the official GitLab chart. ## GitLab-Omnibus Chart (Recommended) + > **Note**: This chart is in beta while [additional features](https://gitlab.com/charts/charts.gitlab.io/issues/68) are being added. This chart is the best available way to operate GitLab on Kubernetes. It deploys and configures nearly all features of GitLab, including: a [Runner](https://docs.gitlab.com/runner/), [Container Registry](../../user/project/container_registry.html#gitlab-container-registry), [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/), [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego), and a [load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). It is based on our [GitLab Omnibus Docker Images](https://docs.gitlab.com/omnibus/docker/README.html). diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index e6ccfccd33f..1ced1fb513d 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -6,7 +6,7 @@ article_type: tutorial date: 2016-06-28 --- -# Getting started with OpenShift Origin 3 and GitLab +# How to install GitLab on OpenShift Origin 3 ## Introduction diff --git a/doc/legal/README.md b/doc/legal/README.md index 6413f1d645f..d991429a652 100644 --- a/doc/legal/README.md +++ b/doc/legal/README.md @@ -4,5 +4,4 @@ comments: false # Legal -- [Corporate contributor license agreement](corporate_contributor_license_agreement.md) -- [Individual contributor license agreement](individual_contributor_license_agreement.md) +Please read through the [GitLab License Agreement](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md). diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md index ebb24ba0a7f..e5fc7a3c85f 100644 --- a/doc/legal/corporate_contributor_license_agreement.md +++ b/doc/legal/corporate_contributor_license_agreement.md @@ -1,2 +1,3 @@ -This document has been replaced by a Developer Certificate of Origin and License, -as described in [Contributing.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md).
\ No newline at end of file +--- +redirect_to: 'README.md' +--- diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index ebb24ba0a7f..e5fc7a3c85f 100644 --- a/doc/legal/individual_contributor_license_agreement.md +++ b/doc/legal/individual_contributor_license_agreement.md @@ -1,2 +1,3 @@ -This document has been replaced by a Developer Certificate of Origin and License, -as described in [Contributing.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md).
\ No newline at end of file +--- +redirect_to: 'README.md' +--- diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md index fee49cc27cc..57c16f110e4 100644 --- a/doc/raketasks/features.md +++ b/doc/raketasks/features.md @@ -1,4 +1,4 @@ -# Features +# Namespaces ## Enable usernames and namespaces for user projects diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 2ebf7c48f4e..5f3143f76cd 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,4 +1,4 @@ -# Webhooks +# Webhooks administration **[CORE ONLY]** ## Add a webhook for **ALL** projects: diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 7c0cd2c40d2..5254e6e3d9a 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -389,7 +389,7 @@ If you have installed GitLab using a different method, you need to: 1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and - [enable Prometheus metrics](https://github.com/kubernetes/ingress/blob/master/examples/customization/custom-vts-metrics/nginx/nginx-vts-metrics-conf.yaml). + [enable Prometheus metrics](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml). 1. Finally, [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) the NGINX Ingress deployment to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`. @@ -495,6 +495,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `POSTGRES_PASSWORD` | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password. | | `POSTGRES_DB` | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name. | | `BUILDPACK_URL` | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` | +| `STAGING_ENABLED` | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | TIP: **Tip:** Set up the replica variables using a @@ -561,6 +562,22 @@ service: internalPort: 5000 ``` +#### Deploy policy for staging and production environments + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/merge_requests/160) +in GitLab 10.8. + +The normal behavior of Auto DevOps is to use Continuous Deployment, pushing +automatically to the `production` environment every time a new pipeline is run +on the default branch. However, there are cases where you might want to use a +staging environment and deploy to production manually. For this scenario, the +`STAGING_ENABLED` environment variable was introduced. + +If `STAGING_ENABLED` is defined in your project (e.g., set `STAGING_ENABLED` to +`1` as a secret variable), then the application will be automatically deployed +to a `staging` environment, and a `production_manual` job will be created for +you when you're ready to manually deploy to production. + ## Currently supported languages NOTE: **Note:** diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 6c909a1ba86..58d86f7d387 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -4,6 +4,7 @@ author_gitlab: SeanPackham level: beginner article_type: user guide date: 2017-05-15 +description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' --- # Installing Git diff --git a/doc/university/training/gitlab_flow.md b/doc/university/training/gitlab_flow.md index 02a6ad48a38..d7bc7bda43f 100644 --- a/doc/university/training/gitlab_flow.md +++ b/doc/university/training/gitlab_flow.md @@ -2,39 +2,31 @@ comments: false --- -# GitLab Flow +# What is the GitLab Flow - A simplified branching strategy - All features and fixes first go to master - Allows for 'production' or 'stable' branches - Bug fixes/hot fix patches are cherry-picked from master ---- - -# Feature branches +## Feature branches - Create a feature/bugfix branch to do all work - Use merge requests to merge to master  ---- - -# Production branch +## Production branch - One, long-running production release branch as opposed to individual stable branches - Consider creating a tag for each version that gets deployed ---- - -# Production branch +## Production branch  ---- - -# Release branch +## Release branch - Useful if you release software to customers - When preparing a new release, create stable branch @@ -43,15 +35,11 @@ comments: false - Cherry-pick critical bug fixes to stable branch for patch release - Never commit bug fixes directly to stable branch ---- - -# Release branch +## Release branch  ---- - -# More details +## More details -Blog post on 'GitLab Flow' at -[http://doc.gitlab.com/ee/workflow/gitlab_flow.html](http://doc.gitlab.com/ee/workflow/gitlab_flow.html) +For more information read through the [GitLab Flow](../../workflow/gitlab_flow.md) +documentation. diff --git a/doc/university/training/topics/gitlab_flow.md b/doc/university/training/topics/gitlab_flow.md index b8049b5c80e..f6006ce0a60 100644 --- a/doc/university/training/topics/gitlab_flow.md +++ b/doc/university/training/topics/gitlab_flow.md @@ -1,57 +1,3 @@ --- -comments: false +redirect_to: '../gitlab_flow.md' --- - -# GitLab Flow - ----------- - -- A simplified branching strategy -- All features and fixes first go to master -- Allows for 'production' or 'stable' branches -- Bug fixes/hot fix patches are cherry-picked from master - ----------- - -### Feature branches - -- Create a feature/bugfix branch to do all work -- Use merge requests to merge to master - - - ----------- - -## Production branch - -- One, long-running production release branch - as opposed to individual stable branches -- Consider creating a tag for each version that gets deployed - ----------- - -## Production branch - - - ----------- - -## Release branch - -- Useful if you release software to customers -- When preparing a new release, create stable branch - from master -- Consider creating a tag for each version -- Cherry-pick critical bug fixes to stable branch for patch release -- Never commit bug fixes directly to stable branch - ----------- - - - ----------- - -## More details - -Blog post on 'GitLab Flow' at -[http://doc.gitlab.com/ee/workflow/gitlab_flow.html](http://doc.gitlab.com/ee/workflow/gitlab_flow.html) diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md index 4e8c9de85a1..d7b771cd87b 100644 --- a/doc/university/training/topics/merge_requests.md +++ b/doc/university/training/topics/merge_requests.md @@ -2,7 +2,7 @@ comments: false --- -# Merge requests +# Code review and collaboration with Merge Requests ---------- diff --git a/doc/update/10.7-to-10.8.md b/doc/update/10.7-to-10.8.md new file mode 100644 index 00000000000..13101a987f4 --- /dev/null +++ b/doc/update/10.7-to-10.8.md @@ -0,0 +1,362 @@ +--- +comments: false +--- + +# From 10.7 to 10.8 + +Make sure you view this update guide from the tag (version) of GitLab you would +like to install. In most cases this should be the highest numbered production +tag (without rc in it). You can select the tag in the version dropdown at the +top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + + ```bash + mkdir /tmp/ruby && cd /tmp/ruby + curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.7.tar.gz + echo '540996fec64984ab6099e34d2f5820b14904f15a ruby-2.3.7.tar.gz' | shasum -c - && tar xzf ruby-2.3.7.tar.gz + cd ruby-2.3.7 + + ./configure --disable-install-rdoc + make + sudo make install + ``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v6.0.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v6.0.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go +1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz +echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.8.3.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +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 +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 10-8-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 10-8-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +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 +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +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 +``` + +### 9. Update Gitaly + +#### New Gitaly configuration options required + +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. + +```shell +echo ' +[gitaly-ruby] +dir = "/home/git/gitaly/ruby" + +[gitlab-shell] +dir = "/home/git/gitlab-shell" +' | sudo -u git tee -a /home/git/gitaly/config.toml +``` + +#### Check Gitaly configuration + +Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly +configuration file may contain syntax errors. The block name +`[[storages]]`, which may occur more than once in your `config.toml` +file, should be `[[storage]]` instead. + +```shell +sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml +``` + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +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 +``` + +### 10. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 11. Update configuration files + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/10-7-stable:config/gitlab.yml.example origin/10-8-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/10-7-stable:lib/support/nginx/gitlab-ssl origin/10-8-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/10-7-stable:lib/support/nginx/gitlab origin/10-8-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/10-7-stable:lib/support/init.d/gitlab.default.example origin/10-8-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 12. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 13. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 14. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (10.7) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 10.6 to 10.7](10.6-to-10.7.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index 9e2a89ebdf6..e383142c33e 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -1,4 +1,4 @@ -# Labels +# Labels administration **[CORE ONLY]** ## Default Labels diff --git a/doc/user/admin_area/settings/img/enforce_terms.png b/doc/user/admin_area/settings/img/enforce_terms.png Binary files differnew file mode 100755 index 00000000000..e5f0a2683b5 --- /dev/null +++ b/doc/user/admin_area/settings/img/enforce_terms.png diff --git a/doc/user/admin_area/settings/img/respond_to_terms.png b/doc/user/admin_area/settings/img/respond_to_terms.png Binary files differnew file mode 100755 index 00000000000..d0d086c3498 --- /dev/null +++ b/doc/user/admin_area/settings/img/respond_to_terms.png diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md new file mode 100644 index 00000000000..8e1fb982aba --- /dev/null +++ b/doc/user/admin_area/settings/terms.md @@ -0,0 +1,38 @@ +# Enforce accepting Terms of Service + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18570) +> in [GitLab Core](https://about.gitlab.com/pricing/) 10.8 + +## Configuration + +When it is required for all users of the GitLab instance to accept the +Terms of Service, this can be configured by an admin on the settings +page: + +. + +The terms itself can be entered using Markdown. For each update to the +terms, a new version is stored. When a user accepts or declines the +terms, GitLab will keep track of which version they accepted or +declined. + +When an admin enables this feature, they will automattically be +directed to the page to accept the terms themselves. After they +accept, they will be directed back to the settings page. + +## Accepting terms + +When this feature was enabled, the users that have not accepted the +terms of service will be presented with a screen where they can either +accept or decline the terms. + + + +When the user accepts the terms, they will be directed to where they +were going. After a sign-in or sign-up this will most likely be the +dashboard. + +When the user was already logged in when the feature was turned on, +they will be asked to accept the terms on their next interaction. + +When a user declines the terms, they will be signed out. diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 88f4bb2ee04..30761a66563 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -40,20 +40,20 @@ In GitLab, a namespace is a unique name to be used as a user name, a group name, - `http://gitlab.example.com/groupname` - `http://gitlab.example.com/groupname/subgroup_name` -For example, consider a user called John: +For example, consider a user named Alex: -1. John creates his account on GitLab.com with the username `john`; -his profile will be accessed under `https://gitlab.example.com/john` -1. John creates a group for his team with the groupname `john-team`; -his group and its projects will be accessed under `https://gitlab.example.com/john-team` -1. John creates a subgroup of `john-team` with the subgroup name `marketing`; -his subgroup and its projects will be accessed under `https://gitlab.example.com/john-team/marketing` +1. Alex creates an account on GitLab.com with the username `alex`; +their profile will be accessed under `https://gitlab.example.com/alex` +1. Alex creates a group for their team with the groupname `alex-team`; +the group and its projects will be accessed under `https://gitlab.example.com/alex-team` +1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`; +this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing` By doing so: -- Any team member mentions John with `@john` -- John mentions everyone from his team with `@john-team` -- John mentions only his marketing team with `@john-team/marketing` +- Any team member mentions Alex with `@alex` +- Alex mentions everyone from their team with `@alex-team` +- Alex mentions only the marketing team with `@alex-team/marketing` ## Issues and merge requests within a group diff --git a/doc/user/index.md b/doc/user/index.md index 2494df46f1c..a50e5e8fbf8 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -1,3 +1,7 @@ +--- +description: 'Read through the GitLab User documentation to learn how to use, configure, and customize GitLab and GitLab.com to your own needs.' +--- + # User documentation Welcome to GitLab! We're glad to have you here! diff --git a/doc/user/permissions.md b/doc/user/permissions.md index a9ba2a51242..0808e3949be 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,3 +1,7 @@ +--- +description: 'Understand and explore the user permission levels in GitLab, and what features each of them grants you access to.' +--- + # Permissions Users have different abilities depending on the access level they have in a diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index fea3231006b..557487e1a75 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -10,17 +10,19 @@ The [Prometheus service](../prometheus.md) must be enabled. ## Metrics supported +NGINX server metrics are detected, which tracks the pages and content directly served by NGINX. + | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_responses_total{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (status_code) | -| Latency (ms) | avg(nginx_upstream_response_msecs_avg{%{environment_filter}}) | -| HTTP Error Rate (HTTP Errors / sec) | rate(nginx_responses_total{status_code="5xx", %{environment_filter}}[2m])) | +| Throughput (req/sec) | sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code) | +| Latency (ms) | avg(nginx_server_requestMsec{%{environment_filter}}) | +| HTTP Error Rate (HTTP Errors / sec) | sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m])) | ## Configuring Prometheus to monitor for NGINX metrics To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts)) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes ingress, there is [upcoming direct support](https://github.com/kubernetes/ingress/pull/423) for enabling Prometheus monitoring in the 0.9.0 release. +If you are using NGINX as your Kubernetes ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## Specifying the Environment label diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index a97ce84b861..4b5c2539c4b 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,3 +1,7 @@ +--- +description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' +--- + # GitLab Pages With GitLab Pages it's easy to publish your project website. GitLab Pages is a hosting service for static websites, at no additional cost. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 0b5076b8c5d..fe4d15adfa1 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,4 +1,4 @@ -# GitLab Pages +# Exploring GitLab Pages > **Notes:** > - This feature was [introduced][ee-80] in GitLab EE 8.3. @@ -14,9 +14,7 @@ deploy static pages for your individual projects, your user or your group. Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlab-com) for specific information, if you are using GitLab.com to host your website. -Read through [All you Need to Know About GitLab Pages][pages-index-guide] for a list of all learning materials we have prepared for GitLab Pages (webpages, articles, guides, blog posts, video tutorials). - -## Getting started with GitLab Pages +## Getting started with GitLab Pages domains > **Note:** > In the rest of this document we will assume that the general domain name that diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 2c90f4b4413..b8bac01959e 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -5,6 +5,7 @@ > - [Introduced][ce-3050] in GitLab 8.9. > - Importing will not be possible if the import instance version differs from > that of the exporter. +> - For GitLab admins, please read through [Project import/export administration](../../../administration/raketasks/project_import_export.md). > - For existing installations, the project import option has to be enabled in > application settings (`/admin/application_settings`) under 'Import sources'. > Ask your administrator if you don't see the **GitLab export** button when diff --git a/doc/workflow/protected_branches.md b/doc/workflow/protected_branches.md index aa48b8f750e..ced7d391ace 100644 --- a/doc/workflow/protected_branches.md +++ b/doc/workflow/protected_branches.md @@ -1 +1 @@ -This document is moved to [user/project/protected_branches.md](../user/project/protected_branches.md) +This document was moved to [another location](../user/project/protected_branches.md). diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md new file mode 100644 index 00000000000..dbe63144e38 --- /dev/null +++ b/doc/workflow/repository_mirroring.md @@ -0,0 +1,111 @@ +# Repository mirroring + +Repository Mirroring is a way to mirror repositories from external sources. +It can be used to mirror all branches, tags, and commits that you have +in your repository. + +Your mirror at GitLab will be updated automatically. You can +also manually trigger an update at most once every 5 minutes. + +## Overview + +Repository mirroring is very useful when, for some reason, you must use a +project from another source. + +There are two kinds of repository mirroring features supported by GitLab: +**push** and **pull**, the latter being only available in GitLab Enterprise Edition. +The **push** method mirrors the repository in GitLab to another location. + +Once the mirror repository is updated, all new branches, +tags, and commits will be visible in the project's activity feed. +Users with at least [developer access][perms] to the project can also force an +immediate update with the click of a button. This button will not be available if +the mirror is already being updated or 5 minutes still haven't passed since its last update. + +A few things/limitations to consider: + +- The repository must be accessible over `http://`, `https://`, `ssh://` or `git://`. +- If your HTTP repository is not publicly accessible, add authentication + information to the URL, like: `https://username@gitlab.company.com/group/project.git`. + In some cases, you might need to use a personal access token instead of a + password, e.g., you want to mirror to GitHub and have 2FA enabled. +- The import will time out after 15 minutes. For repositories that take longer + use a clone/push combination. +- The Git LFS objects will not be synced. You'll need to push/pull them + manually. + +## Use-case + +- You have old projects in another source that you don't use actively anymore, + but don't want to remove for archiving purposes. In that case, you can create + a push mirror so that your active GitLab repository can push its changes to the + old location. + +## Pushing to a remote repository **[STARTER]** + +>[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in +GitLab Enterprise Edition 8.7. [Moved to GitLab Community Edition][ce-18715] in 10.8. + +For an existing project, you can set up push mirror from your project's +**Settings ➔ Repository** and searching for the "Push to a remote repository" +section. Check the "Remote mirror repository" box and fill in the Git URL of +the repository to push to. Click **Save changes** for the changes to take +effect. + + + +When push mirroring is enabled, you are advised not to push commits directly +to the mirrored repository to prevent the mirror diverging. +All changes will end up in the mirrored repository whenever commits +are pushed to GitLab, or when a [forced update](#forcing-an-update) is +initiated. + +Pushes into GitLab are automatically pushed to the remote mirror at least once +every 5 minutes after they are received or once every minute if **push only +protected branches** is enabled. + +In case of a diverged branch, you will see an error indicated at the **Mirror +repository** settings. + + + +### Push only protected branches + +>[Introduced][ee-3350] in GitLab Enterprise Edition 10.3. [Moved to GitLab Community Edition][ce-18715] in 10.8. + +You can choose to only push your protected branches from GitLab to your remote repository. + +To use this option go to your project's repository settings page under push mirror. + +## Setting up a push mirror from GitLab to GitHub + +To set up a mirror from GitLab to GitHub, you need to follow these steps: + +1. Create a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the "public_repo" box checked: + +  + +1. Fill in the "Git repository URL" with the personal access token replacing the password `https://GitHubUsername:GitHubPersonalAccessToken@github.com/group/project.git`: + +  + +1. Save +1. And either wait or trigger the "Update Now" button: + +  + +## Forcing an update + +While mirrors are scheduled to update automatically, you can always force an update +by using the **Update now** button which is exposed in various places: + +- in the commits page +- in the branches page +- in the tags page +- in the **Mirror repository** settings page + +[ee-3350]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350 +[ce-18715]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715 +[perms]: ../user/permissions.md + diff --git a/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png b/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png Binary files differnew file mode 100644 index 00000000000..038b05cb31d --- /dev/null +++ b/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png diff --git a/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png b/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png Binary files differnew file mode 100644 index 00000000000..139de42d8db --- /dev/null +++ b/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png diff --git a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png Binary files differnew file mode 100644 index 00000000000..ccbc1d92329 --- /dev/null +++ b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png diff --git a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png Binary files differnew file mode 100644 index 00000000000..b16b3d2828e --- /dev/null +++ b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png diff --git a/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png b/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png Binary files differnew file mode 100644 index 00000000000..f8199aa7c0f --- /dev/null +++ b/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png |
