diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-28 03:09:33 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-28 03:09:33 +0300 |
commit | 31aa5407f8ebffd4cf8f4c31e1133e310dc0a30f (patch) | |
tree | 0413bc08412d4bc93ee07da5781b9c9e2bd4b559 /doc | |
parent | 10eb15fe07b89755e82dbe2798651795aebd6614 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
42 files changed, 461 insertions, 416 deletions
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 040bf027443..6448fd13979 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -411,6 +411,7 @@ reauthenticate reauthenticated reauthenticates reauthenticating +rebalancing rebar rebase rebased @@ -482,6 +483,7 @@ serializer serializers serializing serverless +sharded sharding shfmt Shibboleth diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index ca4fa0549d0..e034314f6ce 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -29,11 +29,11 @@ server to accept the `GIT_PROTOCOL` environment. In installations using [GitLab Helm Charts](https://docs.gitlab.com/charts/) and [All-in-one Docker image](https://docs.gitlab.com/omnibus/docker/), the SSH -service is already configured to accept the `GIT_PROTOCOL` environment and users +service is already configured to accept the `GIT_PROTOCOL` environment. Users need not do anything more. -For Omnibus GitLab and installations from source, you have to manually update -the SSH configuration of your server by adding the line below to the `/etc/ssh/sshd_config` file: +For Omnibus GitLab and installations from source, update +the SSH configuration of your server manually by adding this line to the `/etc/ssh/sshd_config` file: ```plaintext AcceptEnv GIT_PROTOCOL diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 9577fb40abe..7491807c501 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -40,7 +40,7 @@ The following is a high-level architecture overview of how Gitaly is used. ## Configure Gitaly -The Gitaly service itself is configured via a [TOML configuration file](reference.md). +The Gitaly service itself is configured by using a [TOML configuration file](reference.md). To change Gitaly settings: @@ -121,7 +121,7 @@ The following list depicts the network architecture of Gitaly: - GitLab Shell. - Elasticsearch indexer. - Gitaly itself. -- A Gitaly server must be able to make RPC calls **to itself** via its own +- A Gitaly server must be able to make RPC calls **to itself** by uing its own `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`. - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails nodes. @@ -502,8 +502,8 @@ If it's excluded, default Git storage directory is used for that storage shard. ### Disable Gitaly where not required (optional) -If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server), you may want to -disable the local Gitaly service that runs on your GitLab server by default and have it only running +If you run Gitaly [as a remote service](#run-gitaly-on-its-own-server), consider +disabling the local Gitaly service that runs on your GitLab server by default, and only run it where required. Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where @@ -538,7 +538,7 @@ To disable Gitaly on a GitLab server: > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured. Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure -connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding +connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. Gitaly provides the same server certificates as client certificates in TLS @@ -935,12 +935,13 @@ Note that `enforced="true"` means that authentication is being enforced. ## Direct Git access bypassing Gitaly -While it is possible to access Gitaly repositories stored on disk directly with a Git client, -it is not advisable because Gitaly is being continuously improved and changed. Theses improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss. +GitLab doesn't advise directly accessing Gitaly repositories stored on disk with +a Git client, because Gitaly is being continuously improved and changed. These +improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss. Gitaly has optimizations, such as the [`info/refs` advertisement cache](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/design_diskcache.md), -that rely on Gitaly controlling and monitoring access to repositories via the +that rely on Gitaly controlling and monitoring access to repositories by using the official gRPC interface. Likewise, Praefect has optimizations, such as fault tolerance and distributed reads, that depend on the gRPC interface and database to determine repository state. @@ -979,11 +980,11 @@ lookup. Even when Gitaly is able to re-use an already-running `git` process (for a commit), you still have: - The cost of a network roundtrip to Gitaly. -- Within Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. +- Inside Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process. Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git -file severs, rather than via NFS mounts. This gave us a speed boost that counteracted the negative +file severs, rather than by using NFS mounts. This gave us a speed boost that counteracted the negative effect of not using Rugged anymore. Unfortunately, other deployments of GitLab could not remove NFS like we did on GitLab.com, and they @@ -1018,7 +1019,7 @@ The result of these checks is cached. To see if GitLab can access the repository file system directly, we use the following heuristic: - Gitaly ensures that the file system has a metadata file in its root with a UUID in it. -- Gitaly reports this UUID to GitLab via the `ServerInfo` RPC. +- Gitaly reports this UUID to GitLab by using the `ServerInfo` RPC. - GitLab Rails tries to read the metadata file directly. If it exists, and if the UUID's match, assume we have direct access. @@ -1085,7 +1086,7 @@ app nodes). ### Client side gRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC -client has its own log file which may contain useful information when +client has its own log file which may contain debugging information when you are seeing Gitaly errors. You can control the log level of the gRPC client with the `GRPC_LOG_LEVEL` environment variable. The default level is `WARN`. @@ -1100,7 +1101,7 @@ sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check Sometimes you need to find out which Gitaly RPC created a particular Git process. -One method for doing this is via `DEBUG` logging. However, this needs to be enabled +One method for doing this is by using `DEBUG` logging. However, this needs to be enabled ahead of time and the logs produced are quite verbose. A lightweight method for doing this correlation is by inspecting the environment @@ -1137,16 +1138,19 @@ sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0 ### Repository changes fail with a `401 Unauthorized` error -If you're running Gitaly on its own server and notice that users can -successfully clone and fetch repositories (via both SSH and HTTPS), but can't -push to them or make changes to the repository in the web UI without getting a -`401 Unauthorized` message, then it's possible Gitaly is failing to authenticate -with the Gitaly client due to having the [wrong secrets file](#configure-gitaly-servers). +If you run Gitaly on its own server and notice these conditions: + +- Users can successfully clone and fetch repositories by using both SSH and HTTPS. +- Users can't push to repositories, or receive a `401 Unauthorized` message when attempting to + make changes to them in the web UI. + +Gitaly may be failing to authenticate with the Gitaly client because it has the +[wrong secrets file](#configure-gitaly-servers). Confirm the following are all true: - When any user performs a `git push` to any repository on this Gitaly server, it - fails with the following error (note the `401 Unauthorized`): + fails with a `401 Unauthorized` error: ```shell remote: GitLab: 401 Unauthorized @@ -1158,7 +1162,7 @@ Confirm the following are all true: - When any user adds or modifies a file from the repository using the GitLab UI, it immediately fails with a red `401 Unauthorized` banner. - Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects) - successfully creates the project but doesn't create the README. + successfully creates the project, but doesn't create the README. - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server) on a Gitaly client and reproducing the error, you get `401` errors when reaching the `/api/v4/internal/allowed` endpoint: @@ -1229,11 +1233,11 @@ update the secrets file on the Gitaly server to match the Gitaly client, then ### Command line tools cannot connect to Gitaly -If you are having trouble connecting to a Gitaly server with command line (CLI) tools, +If you can't connect to a Gitaly server with command line (CLI) tools, and certain actions result in a `14: Connect Failed` error message, -it means that gRPC cannot reach your Gitaly server. +gRPC cannot reach your Gitaly server. -Verify that you can reach Gitaly via TCP: +Verify you can reach Gitaly by using TCP: ```shell sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT] diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 0281516d6a2..41b840b1e1a 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -105,7 +105,7 @@ sharding is: replicas. - Simpler management, because all Gitaly nodes are identical. -Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes and it +Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes. It can be uneconomical to have one to one replication factor. A hybrid approach can be used in these instances, where each shard is configured as a smaller @@ -168,7 +168,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov The communication between components is secured with different secrets, which are described below. Before you begin, generate a unique secret for each, and -make note of it. This makes it easy to replace these placeholder tokens +make note of it. This enables you to replace these placeholder tokens with secure tokens as you complete the setup process. 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP @@ -260,13 +260,12 @@ this, set the corresponding IP or host address of the PgBouncer instance in - `praefect['database_port']`, for the port. Because PgBouncer manages resources more efficiently, Praefect still requires a -direct connection to the PostgreSQL database because it uses +direct connection to the PostgreSQL database. It uses the [LISTEN](https://www.postgresql.org/docs/11/sql-listen.html) -functionality that is [not supported](https://www.pgbouncer.org/features.html) by +feature that is [not supported](https://www.pgbouncer.org/features.html) by PgBouncer with `pool_mode = transaction`. - -Therefore, `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` -should be set to a direct connection and not a PgBouncer connection. +Set `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` +to a direct connection, and not a PgBouncer connection. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure). @@ -960,14 +959,14 @@ To get started quickly: gitlab-ctl reconfigure ``` -1. Set the Grafana admin password. This command prompts you to enter a new +1. Set the Grafana administrator password. This command prompts you to enter a new password: ```shell gitlab-ctl set-grafana-password ``` -1. In your web browser, open `/-/grafana` (e.g. +1. In your web browser, open `/-/grafana` (such as `https://gitlab.example.com/-/grafana`) on your GitLab server. Login using the password you set, and the username `admin`. @@ -1085,7 +1084,7 @@ specific storage nodes to host a repository. support configuring a default replication factor for a virtual storage. The default replication factor is applied to every newly-created repository. -Prafect does not store the actual replication factor, but assigns enough storages to host the repository +Praefect does not store the actual replication factor, but assigns enough storages to host the repository so the desired replication factor is met. If a storage node is later removed from the virtual storage, the replication factor of repositories assigned to the storage is decreased accordingly. @@ -1164,8 +1163,8 @@ To enable writes again, an administrator can: ### Check for data loss -The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This is -useful for identifying potential data loss after a failover. The following parameters are +The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This can help +identify potential data loss after a failover. The following parameters are available: - `-virtual-storage` that specifies which virtual storage to check. The default behavior is to @@ -1189,7 +1188,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t ``` Repositories which have assigned storage nodes that contain an outdated copy of the repository are listed -in the output. A number of useful information is printed for each repository: +in the output. This information is printed for each repository: - A repository's relative path to the storage directory identifies each repository and groups the related information. @@ -1206,7 +1205,7 @@ in the output. A number of useful information is printed for each repository: Whether a replica is assigned to host the repository is listed with each replica's status. `assigned host` is printed next to replicas which are assigned to store the repository. The text is omitted if the replica contains a copy of -the repository but is not assigned to store the repository. Such replicas won't be kept in-sync by Praefect but may +the repository but is not assigned to store the repository. Such replicas aren't kept in-sync by Praefect, but may act as replication sources to bring assigned replicas up to date. Example output: @@ -1275,7 +1274,7 @@ To check a project's repository checksums across on all Gitaly nodes, run the ### Enable writes or accept data loss -Praefect provides the following subcommands to re-enable writes: +Praefect provides the following sub-commands to re-enable writes: - In GitLab 13.2 and earlier, `enable-writes` to re-enable virtual storage for writes after data recovery attempts. @@ -1317,7 +1316,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a Praefect automatically reconciles repositories that are not up to date. By default, this is done every five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a -random, fully up to date replica of the repository on another healthy Gitaly node to replicate from. A +random, fully up-to-date replica of the repository on another healthy Gitaly node to replicate from. A replication job is scheduled only if there are no other replication jobs pending for the target repository. @@ -1376,7 +1375,7 @@ To move repositories to Gitaly Cluster: - The moves are in progress. Re-query the repository move until it completes successfully. - The moves have failed. Most failures are temporary and are solved by rescheduling the move. -1. Once the moves are complete, [query projects](../../api/projects.md#list-all-projects) +1. After the moves are complete, [query projects](../../api/projects.md#list-all-projects) using the API to confirm that all projects have moved. No projects should be returned with `repository_storage` field set to the old storage. diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 5a004d97220..5105b9ed0d4 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -95,13 +95,13 @@ key_path = '/home/git/key.pem' ### Storage -GitLab repositories are grouped into directories known as "storages" -(e.g., `/home/git/repositories`) containing bare repositories managed -by GitLab with names (e.g., `default`). +GitLab repositories are grouped into directories known as storages, such as +`/home/git/repositories`. They contain bare repositories managed +by GitLab with names, such as `default`. These names and paths are also defined in the `gitlab.yml` configuration file of -GitLab. When you run Gitaly on the same machine as GitLab, which is the default -and recommended configuration, storage paths defined in Gitaly's `config.toml` +GitLab. When you run Gitaly on the same machine as GitLab (the default +and recommended configuration) storage paths defined in Gitaly's `config.toml` must match those in `gitlab.yml`. | Name | Type | Required | Description | @@ -232,9 +232,9 @@ The following values configure logging in Gitaly under the `[logging]` section. | ---- | ---- | -------- | ----------- | | `format` | string | no | Log format: `text` or `json`. Default: `text`. | | `level` | string | no | Log level: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. Default: `info`. | -| `sentry_dsn` | string | no | Sentry DSN for exception monitoring. | +| `sentry_dsn` | string | no | Sentry DSN (Data Source Name) for exception monitoring. | | `sentry_environment` | string | no | [Sentry Environment](https://docs.sentry.io/product/sentry-basics/environments/) for exception monitoring. | -| `ruby_sentry_dsn` | string | no | Sentry DSN for `gitaly-ruby` exception monitoring. | +| `ruby_sentry_dsn` | string | no | Sentry DSN (Data Source Name) for `gitaly-ruby` exception monitoring. | While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index cd61dc9a2bf..5f6222f1169 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -10,13 +10,13 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16. When [PlantUML](https://plantuml.com) integration is enabled and configured in -GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents +GitLab you can create diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. ## PlantUML Server -Before you can enable PlantUML in GitLab; you need to set up your own PlantUML -server that will generate the diagrams. +Before you can enable PlantUML in GitLab; set up your own PlantUML +server to generate the diagrams. ### Docker @@ -26,12 +26,11 @@ With Docker, you can just run a container like this: docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat ``` -The **PlantUML URL** will be the hostname of the server running the container. +The **PlantUML URL** is the hostname of the server running the container. -When running GitLab in Docker, it will need to have access to the PlantUML container. -The easiest way to achieve that is by using [Docker Compose](https://docs.docker.com/compose/). - -A simple `docker-compose.yml` file would be: +When running GitLab in Docker, it must have access to the PlantUML container. +You can achieve that by using [Docker Compose](https://docs.docker.com/compose/). +A basic `docker-compose.yml` file could contain: ```yaml version: "3" @@ -47,13 +46,12 @@ services: container_name: plantuml ``` -In this scenario, PlantUML will be accessible for GitLab at the URL +In this scenario, PlantUML is accessible to GitLab at the URL `http://plantuml:8080/`. ### Debian/Ubuntu -Installing and configuring your -own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat. +You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat. First you need to create a `plantuml.war` file from the source code: @@ -64,8 +62,7 @@ cd plantuml-server mvn package ``` -The above sequence of commands will generate a WAR file that can be deployed -using Tomcat: +The above sequence of commands generates a `.war` file you can deploy with Tomcat: ```shell sudo apt-get install tomcat8 @@ -74,17 +71,18 @@ sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war sudo service tomcat8 restart ``` -Once the Tomcat service restarts the PlantUML service will be ready and +After the Tomcat service restarts, the PlantUML service is ready and listening for requests on port 8080: ```plaintext http://localhost:8080/plantuml ``` -you can change these defaults by editing the `/etc/tomcat8/server.xml` file. +To change these defaults, edit the `/etc/tomcat8/server.xml` file. -Note that the default URL is different than when using the Docker-based image, -where the service is available at the root of URL with no relative path. Adjust +NOTE: +The default URL is different when using this approach. The Docker-based image +makes the service available at the root URL, with no relative path. Adjust the configuration below accordingly. ### Making local PlantUML accessible using custom GitLab setup @@ -112,7 +110,7 @@ To activate the changes, run the following command: sudo gitlab-ctl reconfigure ``` -Note that the redirection through GitLab **must** be configured +Note that the redirection through GitLab must be configured when running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html) due to PlantUML's use of the insecure HTTP protocol. Newer browsers such as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408) @@ -120,7 +118,7 @@ do not load insecure HTTP resources on a page served over HTTPS. ### Security -PlantUML has features that allows fetching network resources. +PlantUML has features that allow fetching network resources. ```plaintext @startuml @@ -136,18 +134,18 @@ stop; ## GitLab You need to enable PlantUML integration from Settings under Admin Area. To do -that, login with an Admin account and do following: +that, sign in with an Administrator account, and then do following: -- In GitLab, go to **Admin Area > Settings > General**. -- Expand the **PlantUML** section. -- Check **Enable PlantUML** checkbox. -- Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. +1. In GitLab, go to **Admin Area > Settings > General**. +1. Expand the **PlantUML** section. +1. Select the **Enable PlantUML** check box. +1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. NOTE: If you are using a PlantUML server running v1.2020.9 and above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING` -environment variable to enable the `deflate` compression. On Omnibus, -this can be done set in `/etc/gitlab.rb`: +environment variable to enable the `deflate` compression. On Omnibus GitLab, +this can be set in `/etc/gitlab.rb`: ```ruby gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' } @@ -191,9 +189,11 @@ our AsciiDoc snippets, wikis, and repositories using delimited blocks: Alice -> Bob: hi ``` - You can also use the `uml::` directive for compatibility with [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), but please note that we currently only support the `caption` option. + You can also use the `uml::` directive for compatibility with + [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), + but GitLab only supports the `caption` option. -The above blocks will be converted to an HTML image tag with source pointing to the +The above blocks are converted to an HTML image tag with source pointing to the PlantUML instance. If the PlantUML server is correctly configured, this should render a nice diagram instead of the block: @@ -202,12 +202,18 @@ Bob -> Alice : hello Alice -> Bob : hi ``` -Inside the block you can add any of the supported diagrams by PlantUML such as -[Sequence](https://plantuml.com/sequence-diagram), [Use Case](https://plantuml.com/use-case-diagram), -[Class](https://plantuml.com/class-diagram), [Activity](https://plantuml.com/activity-diagram-legacy), -[Component](https://plantuml.com/component-diagram), [State](https://plantuml.com/state-diagram), -and [Object](https://plantuml.com/object-diagram) diagrams. You do not need to use the PlantUML -diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `plantuml` block. +Inside the block you can add any of the diagrams PlantUML supports, such as: + +- [Sequence](https://plantuml.com/sequence-diagram) +- [Use Case](https://plantuml.com/use-case-diagram) +- [Class](https://plantuml.com/class-diagram) +- [Activity](https://plantuml.com/activity-diagram-legacy) +- [Component](https://plantuml.com/component-diagram) +- [State](https://plantuml.com/state-diagram), +- [Object](https://plantuml.com/object-diagram) + +You do not need to use the PlantUML +diagram delimiters `@startuml`/`@enduml`, as these are replaced by the AsciiDoc `plantuml` block. Some parameters can be added to the AsciiDoc block definition: @@ -217,4 +223,4 @@ Some parameters can be added to the AsciiDoc block definition: - `width`: Width attribute added to the image tag. - `height`: Height attribute added to the image tag. -Markdown does not support any parameters and will always use PNG format. +Markdown does not support any parameters and always uses PNG format. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index f4c242b6e72..0f26eb83d17 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -8,14 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. -NOTE: -Only project maintainers and owners can access web terminals. - With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), -GitLab gained the ability to store and use credentials for a Kubernetes cluster. -One of the things it uses these credentials for is providing access to +GitLab can store and use credentials for a Kubernetes cluster. +GitLab uses these credentials to provide access to [web terminals](../../ci/environments/index.md#web-terminals) for environments. +NOTE: +Only project maintainers and owners can access web terminals. + ## How it works A detailed overview of the architecture of web terminals and how they work @@ -53,15 +53,13 @@ detail below. NOTE: AWS Elastic Load Balancers (ELBs) do not support web sockets. -AWS Application Load Balancers (ALBs) must be used if you want web terminals -to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) +If you want web terminals to work, use AWS Application Load Balancers (ALBs). +Read [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) for more information. As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of -Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers -through to the next one in the chain. If you installed GitLab using Omnibus, or -from source, starting with GitLab 8.15, this should be done by the default -configuration, so there's no need for you to do anything. +Workhorse must be configured to pass the `Connection` and `Upgrade` headers +to the next one in the chain. GitLab is configured by default to do so. However, if you run a [load balancer](../load_balancer.md) in front of GitLab, you may need to make some changes to your configuration. These @@ -73,17 +71,17 @@ guides document the necessary steps for a selection of popular reverse proxies: - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so -it's safe to enable support for these headers globally. If you'd rather had a -narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` -(although this may still have a few false positives). +it's safe to enable support for these headers globally. If you prefer a +narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`. +This approach may still result in a few false positives. If you installed from source, or have made any configuration changes to your Omnibus installation before upgrading to 8.15, you may need to make some changes -to your configuration. See the [Upgrading Community Edition and Enterprise -Edition from source](../../update/upgrading_from_source.md#nginx-configuration) -document for more details. +to your configuration. Read +[Upgrading Community Edition and Enterprise Edition from source](../../update/upgrading_from_source.md#nginx-configuration) +for more details. -If you'd like to disable web terminal support in GitLab, just stop passing +To disable web terminal support in GitLab, stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse proxy in the chain. For most users, this is the NGINX server bundled with Omnibus GitLab, in which case, you need to: @@ -104,4 +102,6 @@ they receive a `Connection failed` message. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8413) in GitLab 8.17. Terminal sessions, by default, do not expire. -You can limit terminal session lifetime in your GitLab instance. To do so, navigate to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), and set a `max session time`. +You can limit terminal session lifetime in your GitLab instance. To do so, +go to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), +and set a `max session time`. diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md index 75bee6e0c9a..266e9d44ff7 100644 --- a/doc/administration/invalidate_markdown_cache.md +++ b/doc/administration/invalidate_markdown_cache.md @@ -8,10 +8,10 @@ type: reference # Invalidate Markdown Cache For performance reasons, GitLab caches the HTML version of Markdown text -(e.g. issue and merge request descriptions, comments). It's possible -that these cached versions become outdated, for example -when the `external_url` configuration option is changed - causing links -in the cached text to refer to the old URL. +in fields like comments, issue descriptions, and merge request descriptions. These +cached versions can become outdated, such as +when the `external_url` configuration option is changed. Links +in the cached text would still refer to the old URL. To avoid this problem, the administrator can invalidate the existing cache by increasing the `local_markdown_version` setting in application settings. This can diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 92fdba6216c..72be4932a8e 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -31,8 +31,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d gitlab_rails['external_diffs_enabled'] = true ``` -1. _The external diffs will be stored in - `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path, +1. The external diffs are stored in + `/var/opt/gitlab/gitlab-rails/shared/external-diffs`. To change the path, for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb` and add the following line: @@ -52,8 +52,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d enabled: true ``` -1. _The external diffs will be stored in - `/home/git/gitlab/shared/external-diffs`._ To change the path, for example, +1. The external diffs are stored in + `/home/git/gitlab/shared/external-diffs`. To change the path, for example, to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -68,7 +68,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d ## Using object storage WARNING: -Currently migrating to object storage is **non-reversible** +Migrating to object storage is not reversible. Instead of storing the external diffs on disk, we recommended the use of an object store like AWS S3 instead. This configuration relies on valid AWS credentials to @@ -114,7 +114,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by | Setting | Description | Default | |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | -| `remote_directory` | The bucket name where external diffs will be stored| | +| `remote_directory` | The bucket name where external diffs are stored| | | `direct_upload` | Set to `true` to enable direct upload of external diffs without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | | `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | | `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | @@ -141,7 +141,7 @@ See [the available connection settings for different providers](object_storage.m } ``` - Note that, if you are using AWS IAM profiles, be sure to omit the + If you are using AWS IAM profiles, omit the AWS access key and secret access key/value pairs. For example: ```ruby @@ -206,8 +206,8 @@ To enable this feature, perform the following steps: 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. -With this feature enabled, diffs will initially stored in the database, rather -than externally. They will be moved to external storage once any of these +With this feature enabled, diffs are initially stored in the database, rather +than externally. They are moved to external storage after any of these conditions become true: - A newer version of the merge request diff exists @@ -225,15 +225,15 @@ of some merge request diffs when [external diffs in object storage](#object-stor were enabled. This mainly affected imported merge requests, and was resolved with [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31005). -If you are using object storage, have never used on-disk storage for external -diffs, the "changes" tab for some merge requests fails to load with a 500 error, +If you are using object storage, or have never used on-disk storage for external +diffs, the **Changes** tab for some merge requests fails to load with a 500 error, and the exception for that error is of this form: ```plain Errno::ENOENT (No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-rails/shared/external-diffs/merge_request_diffs/mr-6167082/diff-8199789) ``` -Then you are affected by this issue. Since it's not possible to safely determine +Then you are affected by this issue. Because it's not possible to safely determine all these conditions automatically, we've provided a Rake task in GitLab v13.2.0 that you can run manually to correct the data: diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 029f3bb01ed..9dbc743033f 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -20,8 +20,8 @@ The GitLab API is the recommended way to move Git repositories: For more information, see: -- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). Within this - example, additional storage called `storage1` and `storage2` is configured. +- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). This + example configures additional storage called `storage1` and `storage2`. - [The API documentation](../../api/project_repository_storage_moves.md) details the endpoints for querying and scheduling project repository moves. - [The API documentation](../../api/snippet_repository_storage_moves.md) details the endpoints for @@ -38,7 +38,7 @@ Read more in the [API documentation for projects](../../api/project_repository_s GitLab environment, for example: - From a single-node GitLab to a scaled-out architecture. -- From a GitLab instance in your private datacenter to a cloud provider. +- From a GitLab instance in your private data center to a cloud provider. The rest of the document looks at some of the ways you can copy all your repositories from @@ -103,8 +103,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption. If the target directory already contains a partial / outdated copy of the repositories it may be wasteful to copy all the data again with `tar`. In this scenario it is better to use `rsync`. This utility -is either already installed on your system or easily installable -via `apt`, `yum`, and so on. +is either already installed on your system, or installable +by using `apt` or `yum`. ```shell sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ @@ -112,7 +112,7 @@ sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ ``` The `/.` in the command above is very important, without it you can -easily get the wrong directory structure in the target directory. +get the wrong directory structure in the target directory. If you want to see progress, replace `-a` with `-av`. #### Single `rsync` to another server @@ -135,20 +135,23 @@ WARNING: Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). -Every time you start an `rsync` job it has to inspect all files in -the source directory, all files in the target directory, and then -decide what files to copy or not. If the source or target directory -has many contents this startup phase of `rsync` can become a burden -for your GitLab server. In cases like this you can make `rsync`'s -life easier by dividing its work in smaller pieces, and sync one -repository at a time. +Every time you start an `rsync` job it must: + +- Inspect all files in the source directory. +- Inspect all files in the target directory. +- Decide whether or not to copy files. + +If the source or target directory +has many contents, this startup phase of `rsync` can become a burden +for your GitLab server. You can reduce the workload of `rsync` by dividing its +work in smaller pieces, and sync one repository at a time. In addition to `rsync` we use [GNU Parallel](http://www.gnu.org/software/parallel/). -This utility is not included in GitLab so you need to install it yourself with `apt` -or `yum`. Also note that the GitLab scripts we used below were added in GitLab 8.1. +This utility is not included in GitLab, so you must install it yourself with `apt` +or `yum`. -**This process does not clean up repositories at the target location that no -longer exist at the source.** +This process does not clean up repositories at the target location that no +longer exist at the source. #### Parallel `rsync` for all repositories known to GitLab @@ -218,8 +221,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. -Then you might only want to sync repositories that were changed via GitLab -_after_ that time. You can use the `SINCE` variable to tell `rake +Then you might only want to sync repositories that were changed by using GitLab +after that time. You can use the `SINCE` variable to tell `rake gitlab:list_repos` to only print repositories with recent activity. ```shell diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 6f7a72a0ef2..6c7069a5ac6 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -14,25 +14,24 @@ integrity of all data committed to a repository. GitLab administrators can trigger such a check for a project via the project page under the admin panel. The checks run asynchronously so it may take a few minutes before the check result is visible on the project admin page. If the -checks failed you can see their output on in the [`repocheck.log` -file.](logs.md#repochecklog) +checks failed you can see their output on in the +[`repocheck.log` file.](logs.md#repochecklog) -NOTE: -It is OFF by default because it still causes too many false alarms. +This setting is off by default, because it can cause many false alarms. ## Periodic checks 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 +A project is checked no more than once per month. If any projects +fail their repository checks all GitLab administrators receive an email notification of the situation. This notification is sent out once a week, by default, midnight at the start of Sunday. Repositories with known check failures can be found at `/admin/projects?last_repository_check_failed=1`. ## Disabling periodic checks -You can disable the periodic checks on the 'Settings' page of the admin +You can disable the periodic checks on the **Settings** page of the admin panel. ## What to do if a check failed @@ -40,9 +39,9 @@ panel. If the repository check fails for some repository you should look up the error in the [`repocheck.log` file](logs.md#repochecklog) on disk: -- `/var/log/gitlab/gitlab-rails` for Omnibus installations +- `/var/log/gitlab/gitlab-rails` for Omnibus GitLab installations - `/home/git/gitlab/log` for installations from source If the periodic repository check causes false alarms, you can clear all repository check states by -navigating to **Admin Area > Settings > Repository** +going to **Admin Area > Settings > Repository** (`/admin/application_settings/repository`) and clicking **Clear all repository checks**. diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index c71d1a5714c..1c6218b22be 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -40,9 +40,9 @@ storage2: ## Configure GitLab -In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a -mount point and the GitLab user should have correct permissions for the parent -directory of the path. In Omnibus GitLab this is taken care of automatically, +For [backups](../raketasks/backup_restore.md) to work correctly, the storage path cannot be a +mount point, and the GitLab user must have correct permissions for the parent +directory of the path. Omnibus GitLab takes care of these issues for you, but for source installations you should be extra careful. The thing is that for compatibility reasons `gitlab.yml` has a different @@ -52,22 +52,26 @@ indicate `git_data_dirs`, which for the example above would be `/home/git`. Then, Omnibus creates a `repositories` directory under that path to use with `gitlab.yml`. -This little detail matters because while restoring a backup, the current -contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`, -so if `/home/git/repositories` is the mount point, then `mv` would be moving +WARNING: +This detail matters because while restoring a backup, the current +contents of `/home/git/repositories` +[are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) +`/home/git/repositories.old`. +If `/home/git/repositories` is the mount point, then `mv` would be moving things between mount points, and bad things could happen. Ideally, -`/home/git` would be the mount point, so then things would be moving within the -same mount point. This is guaranteed with Omnibus installations (because they -don't specify the full repository path but the parent path), but not for source -installations. +`/home/git` would be the mount point, so things would remain inside the +same mount point. Omnibus installations guarantee this, because they +don't specify the full repository path but instead the parent path, but source +installations do not. -Now that you've read that big fat warning above, let's edit the configuration -files and add the full paths of the alternative repository storage paths. In +Next, edit the configuration +files, and add the full paths of the alternative repository storage paths. In the example below, we add two more mount points that are named `nfs_1` and `nfs_2` respectively. NOTE: -This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. +This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. Read +the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. **For installations from source** @@ -112,7 +116,7 @@ working, you can remove the `repos_path` line. ## Choose where new repositories are stored -Once you set the multiple storage paths, you can choose where new repositories +After you set the multiple storage paths, you can choose where new repositories are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**. Each storage can be assigned a weight from 0-100. When a new project is created, these diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 6ec43a8ce06..5773c2d2142 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -38,13 +38,13 @@ been disabled. Hashed storage is the storage behavior we rolled out with 10.0. Instead of coupling project URL and the folder structure where the repository is -stored on disk, we are coupling a hash, based on the project's ID. This makes +stored on disk, we couple a hash based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to synchronize state from URLs to disk structure. This means that renaming a group, user, or project costs only the database transaction, and takes effect immediately. -The hash also helps to spread the repositories more evenly on the disk, so the +The hash also helps spread the repositories more evenly on the disk. The top-level directory contains fewer folders than the total number of top-level namespaces. @@ -136,8 +136,8 @@ when housekeeping is run on the source project. ### Hashed storage coverage migration Files stored in an S3-compatible endpoint do not have the downsides -mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`, -which is true for CI Cache and LFS Objects. +mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`. +This is true for CI Cache and LFS Objects. In the table below, you can find the coverage of the migration to the hashed storage. @@ -194,10 +194,10 @@ reasons, GitLab replicated the same mapping structure from the projects URLs: - Project's repository: `#{namespace}/#{project_name}.git` - Project's wiki: `#{namespace}/#{project_name}.wiki.git` -This structure made it simple to migrate from existing solutions to GitLab and -easy for Administrators to find where the repository is stored. +This structure enables you to migrate from existing solutions to GitLab, and +for Administrators to find where the repository is stored. -On the other hand this has some drawbacks: +This approach also has some drawbacks: Storage location concentrates a huge number of top-level namespaces. The impact can be reduced by the introduction of @@ -211,4 +211,4 @@ is at that same URL today. Any change in the URL needs to be reflected on disk (when groups / users or projects are renamed). This can add a lot of load in big installations, -especially if using any type of network based filesystem. +especially if using any type of network based file system. diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 0bf0eb3b1ed..88cf8e14e4f 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -18,7 +18,7 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB). ### How does it work? -The content size limit will be applied when a snippet is created or updated. +The content size limit is applied when a snippet is created or updated. This limit doesn't affect existing snippets until they're updated and their content changes. @@ -60,8 +60,8 @@ To retrieve the current value, start the Rails console and run: #### Through the API -The process to set the snippets size limit through the Application Settings API is -exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). +To set the snippets size limit through the Application Settings API (similar to +[updating any other setting](../../api/settings.md#change-application-settings)), use this command: ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800" diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index b10af12de67..947e2d43fe9 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -9,8 +9,8 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31025) in GitLab 12.3. -GitLab can be configured to serve repository static objects (for example, archives or raw blobs) from an external -storage, such as a Content Delivery Network (CDN). +You can configure GitLab to serve repository static objects, like archives or raw blobs, +from an external storage, such as a Content Delivery Network (CDN). ## Configuring @@ -19,19 +19,22 @@ To configure external storage for static objects: 1. Navigate to **Admin Area > Settings > Repository**. 1. Expand the **Repository static objects** section. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), -you'll use a script that uses these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. + use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. The token is required to distinguish requests coming from the external storage, so users don't -circumvent the external storage and go for the application directly. The token is expected to be -set in the `X-Gitlab-External-Storage-Token` header in requests originating from the external -storage. +circumvent the external storage and access the application directly. GitLab expects +this token to be set in the `X-Gitlab-External-Storage-Token` header in requests +originating from the external storage. ## Serving private static objects -GitLab will append a user-specific token for static object URLs that belong to private projects, -so an external storage can be authenticated on behalf of the user. When processing requests originating -from the external storage, GitLab will look for the token in the `token` query parameter or in -the `X-Gitlab-Static-Object-Token` header to check the user's ability to access the requested object. +GitLab appends a user-specific token for static object URLs belonging to private projects, +so an external storage can be authenticated on the user's behalf. When processing requests originating +from the external storage, GitLab checks the following places to confirm the user may +access the requested object: + +- The `token` query parameter. +- The `X-Gitlab-Static-Object-Token` header. ## Requests flow example @@ -66,8 +69,8 @@ other CDNs or Function as a Service (FaaS) systems should work using the same pr 1. In the following script, set the following values for the first two constants: - `ORIGIN_HOSTNAME`: the hostname of your GitLab installation. - - `STORAGE_TOKEN`: any arbitrary secure token (e.g. you can get one by running - `pwgen -cn1 64` on a UNIX machine). Save this token for the admin panel, as + - `STORAGE_TOKEN`: any arbitrary secure token. You can get a token by running + `pwgen -cn1 64` on a UNIX machine. Save this token for the admin panel, as described in the [configuring](#configuring) section. ```javascript diff --git a/doc/administration/wikis/index.md b/doc/administration/wikis/index.md index 026f9b6f471..02790a33a40 100644 --- a/doc/administration/wikis/index.md +++ b/doc/administration/wikis/index.md @@ -18,24 +18,24 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB). ### How does it work? -The content size limit will be applied when a wiki page is created or updated -through the GitLab UI or API. Local changes pushed via Git will not be validated. +The content size limit is applied when a wiki page is created or updated +through the GitLab UI or API. Local changes pushed via Git are not validated. -In order not to break any existing wiki pages, the limit doesn't have any -effect on them until a wiki page is edited again and the content changes. +To break any existing wiki pages, the limit doesn't take effect until a wiki page +is edited again and the content changes. ### Wiki page content size limit configuration This setting is not available through the [Admin Area settings](../../user/admin_area/settings/index.md). -In order to configure this setting, use either the Rails console +To configure this setting, use either the Rails console or the [Application settings API](../../api/settings.md). NOTE: -The value of the limit **must** be in bytes. The minimum value is 1024 bytes. +The value of the limit must be in bytes. The minimum value is 1024 bytes. #### Through the Rails console -The steps to configure this setting through the Rails console are: +To configure this setting through the Rails console: 1. Start the Rails console: @@ -61,14 +61,14 @@ To retrieve the current value, start the Rails console and run: #### Through the API -The process to set the wiki page size limit through the Application Settings API is -exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings). +To set the wiki page size limit through the Application Settings API, use a command, +as you would to [update any other setting](../../api/settings.md#change-application-settings): ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?wiki_page_max_content_bytes=52428800" ``` -You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings). +You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings): ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings" diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index d264e68e96a..c5adf361fb6 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -225,8 +225,8 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet -- `ref` (required) - The name of a branch, tag or commit e.g. master -- `file_path` (required) - The URL-encoded path to the file, e.g. snippet%2Erb +- `ref` (required) - The name of a branch, tag or commit, such as `master` +- `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb` Example request: @@ -239,7 +239,7 @@ curl "https://gitlab.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/ > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29508) in GitLab 9.4. -Available only for admins. +Available only for users with Administrator [permissions](../user/permissions.md). ```plaintext GET /projects/:id/snippets/:snippet_id/user_agent_detail diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md index b27aef788b1..f783a97fbd3 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.md @@ -14,7 +14,7 @@ Editor Lite is a thin wrapper around [the Monaco editor](https://microsoft.githu ## How to use Editor Lite -Editor Lite is framework-agnostic and can be used in any application, whether it's Rails or Vue. For the convenience of integration, we have [the dedicated `<editor-lite>` Vue component](#vue-component), but in general, the integration of Editor Lite is pretty straightforward: +Editor Lite is framework-agnostic and can be used in any application, whether it's Rails or Vue. For the convenience of integration, we have the dedicated `<editor-lite>` Vue component, but in general, the integration of Editor Lite is pretty straightforward: 1. Import Editor Lite: @@ -225,7 +225,3 @@ Just pass the array of extensions to your `use` method: ```javascript editor.use([FileTemplateExtension, MyFancyExtension]); ``` - -## <a id="vue-component"></a>`<editor-lite>` Vue component - -TBD diff --git a/doc/integration/README.md b/doc/integration/README.md index 227e2eec53c..1070655cc6c 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -25,7 +25,7 @@ GitLab can be configured to authenticate access requests with the following auth - Enable sign in via [LDAP](../administration/auth/ldap/index.md). - Enable [OAuth2 provider](oauth_provider.md) application creation. - Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure or Authentiq ID. + Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID. - Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider. - Authenticate to [Vault](vault.md) through GitLab OpenID Connect. - Configure GitLab as a [SAML](saml.md) 2.0 Service Provider. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index 4bc9d39ae3f..8999f4da9a2 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -10,8 +10,8 @@ NOTE: Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it. -You can set up Bitbucket.org as an OAuth2 provider so that you can use your -Bitbucket.org account credentials to sign into GitLab or import your projects from +You can set up Bitbucket.org as an OAuth2 provider to use your +Bitbucket.org account credentials to sign in to GitLab, or import your projects from Bitbucket.org. - To use Bitbucket.org as an OmniAuth provider, follow the diff --git a/doc/integration/github.md b/doc/integration/github.md index 858614a0571..8c2a48225dd 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Integrate your GitLab instance with GitHub -You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to -enable users to import projects from GitHub or sign in to your GitLab instance -with your GitHub account. +You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration +enables users to import projects from GitHub, or sign in to your GitLab instance +with their GitHub account. ## Enabling GitHub OAuth @@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. -After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next. +After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps. | Setting from GitHub | Substitute in the GitLab configuration file | Description | |:---------------------|:---------------------------------------------|:------------| diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 3bd3099e390..94a26ee792b 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -11,7 +11,7 @@ Import projects from GitLab.com and login to your GitLab instance with your GitL To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. GitLab.com generates an application ID and secret key for you to use. -1. Sign in to GitLab.com +1. Sign in to GitLab.com. 1. On the upper right corner, click on your avatar and go to your **Settings**. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 6cb42ad99c7..93e8820300f 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -24,6 +24,11 @@ In particular, note: (order of hundred emails a day minimum to Gmail) for a few weeks at least". - Have a very low rate of spam complaints from users. - Emails must be authenticated via DKIM or SPF. -- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Before sending the final form ("Gmail Schema Whitelist Request"), you must + send a real email from your production server. This means that you must find + a way to send this email from the email address you are registering. You can + do this by forwarding the real email from the email address you are + registering. You can also go into the Rails console on the GitLab server and + trigger sending the email from there. You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517). diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 7be2a6efd71..a07c23275e0 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -64,7 +64,7 @@ Grant a GitLab user access to the select GitLab projects. 1. Grant the user permission to the GitLab projects. If you're integrating Jenkins with many GitLab projects, consider granting the user global - Admin permission. Otherwise, add the user to each project, and grant Developer permission. + Administrator permission. Otherwise, add the user to each project, and grant Developer permission. ## Configure GitLab API access @@ -166,7 +166,7 @@ to integrate GitLab and Jenkins. 1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**. 1. Click the **Generate** button under the **Secret Token** field. 1. Copy the resulting token, and save the job configuration. -1. In GitLab, create a webhook for your project, enter the trigger URL (e.g. `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. +1. In GitLab, create a webhook for your project, enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field. 1. After you add the webhook, click the **Test** button, and it should succeed. ## Troubleshooting @@ -205,8 +205,8 @@ which is set to 10 seconds by default. To fix this the `gitlab_rails['webhook_timeout']` value must be increased in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md). -If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this -could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): +If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), +[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index c693485949f..550efa6691b 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. -The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying +The Jira Development Panel integration allows you to reference Jira issues in GitLab, displaying activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/) in the issue. @@ -35,7 +35,7 @@ See the [Configuration](#configuration) section for details. With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage). -This integration connects all GitLab projects to projects in the Jira instance within either: +This integration connects all GitLab projects to projects in the Jira instance in either: - A top-level group. A top-level GitLab group is one that does not have any parent group itself. All the projects of that top-level group, as well as projects of the top-level group's subgroups nesting @@ -211,7 +211,7 @@ The requested scope is invalid, unknown, or malformed. Potential resolutions: -- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` within the query string. +- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string. - If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes. ##### Jira error adding account and no repositories listed @@ -314,6 +314,6 @@ For more information on using Jira Smart Commits to track time against an issue, ## Limitations -This integration is currently not supported on GitLab instances under a +This integration is not supported on GitLab instances under a [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab). For example, `http://example.com/gitlab`. diff --git a/doc/integration/oauth2_generic.md b/doc/integration/oauth2_generic.md index 88e9e3ef05c..41656bd2216 100644 --- a/doc/integration/oauth2_generic.md +++ b/doc/integration/oauth2_generic.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Sign into GitLab with (almost) any OAuth2 provider -The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider +The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider (or any OAuth2 provider compatible with this gem) This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below: diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 4e4a0ea3a40..2302ab2d853 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -20,15 +20,14 @@ If you want to use: ## Introduction to OAuth [OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server -resources on behalf of a resource owner. In fact, OAuth allows an authorization +resources on behalf of a resource owner. OAuth allows an authorization server to issue access tokens to third-party clients with the approval of the resource owner, or the end-user. OAuth is mostly used as a Single Sign-On service (SSO), but you can find a lot of different uses for this functionality. For example, you can allow users -to sign in to your application with their GitLab.com account, or GitLab.com -can be used for authentication to your GitLab instance -(see [GitLab OmniAuth](gitlab.md)). +to sign in to your application with their GitLab.com account. You can also use GitLab.com +for authentication to your GitLab instance (see [GitLab OmniAuth](gitlab.md)). The 'GitLab Importer' feature is also using the OAuth protocol to give access to repositories without sharing user credentials to your GitLab.com account. @@ -37,7 +36,7 @@ GitLab supports two ways of adding a new OAuth2 application to an instance. You can either add an application as a regular user or add it in the Admin Area. What this means is that GitLab can actually have instance-wide and a user-wide applications. There is no difference between them except for the different -permission levels they are set (user/admin). The default callback URL is +permission levels they are set (user or administrator). The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback` ## Adding an application through the profile @@ -64,7 +63,7 @@ connects to GitLab. To create an application that does not belong to a certain user, you can create it from the Admin Area. -![OAuth admin_applications](img/oauth_provider_admin_application.png) +![OAuth administrator applications](img/oauth_provider_admin_application.png) You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that, the user authorization step is automatically skipped for this application. @@ -77,7 +76,7 @@ in the **Authorized applications** section under **Profile Settings > Applicatio ![Authorized_applications](img/oauth_provider_authorized_application.png) The GitLab OAuth applications support scopes, which allow various actions that any given -application can perform. The available scopes are depicted in the following table. +application can perform. The available scopes are depicted in the following table. | Scope | Description | | ------------------ | ----------- | @@ -88,9 +87,9 @@ application can perform. The available scopes are depicted in the following tabl | `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). | | `read_registry` | Grants read-only access to container registry images on private projects. | | `write_registry` | Grants read-only access to container registry images on private projects. | -| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an admin user. | +| `sudo` | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. | | `openid` | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. | | `profile` | Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). | | `email` | Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). | -At any time you can revoke any access by just clicking **Revoke**. +At any time you can revoke any access by clicking **Revoke**. diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 53c19ddfdb1..cd582c2edc3 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -55,7 +55,7 @@ earlier version, you must explicitly enable it. - `allow_single_sign_on` allows you to specify the providers you want to allow to automatically create an account. It defaults to `false`. If `false` users must - be created manually or they can't sign in via OmniAuth. + be created manually or they can't sign in by using OmniAuth. - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md) integration enabled. It defaults to `false`. When enabled, users automatically created through an OmniAuth provider have their LDAP identity created in GitLab as well. @@ -66,7 +66,7 @@ earlier version, you must explicitly enable it. NOTE: If you set `block_auto_created_users` to `false`, make sure to only define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +SAML, Shibboleth, Crowd, or Google, or set it to `false` otherwise any user on the Internet can successfully sign in to your GitLab without administrative approval. @@ -170,8 +170,8 @@ omniauth: > Introduced in GitLab 8.7. -You can define which OmniAuth providers you want to be `external` so that all users -**creating accounts, or logging in via these providers** can't have +You can define which OmniAuth providers you want to be `external`. Users +creating accounts, or logging in by using these `external` providers cannot have access to internal projects. You must use the full name of the provider, like `google_oauth2` for Google. Refer to the examples for the full names of the supported providers. @@ -200,9 +200,9 @@ NOTE: The following information only applies for installations from source. GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships -with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that -is not enough and you need to integrate with other authentication solutions. For -these cases you can use the OmniAuth provider. +with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also +need to integrate with other authentication solutions. For +these cases, you can use the OmniAuth provider. ### Steps @@ -251,10 +251,10 @@ we'd like to at least help those with specific needs. > Introduced in GitLab 8.8. -Administrators are able to enable or disable Sign In via some OmniAuth providers. +Administrators are able to enable or disable Sign In by using some OmniAuth providers. NOTE: -By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. +By default Sign In is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`. In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. @@ -345,7 +345,7 @@ omniauth: Keep in mind that every sign-in attempt is redirected to the OmniAuth provider; you can't sign in using local credentials. Ensure at least -one of the OmniAuth users has admin permissions. +one of the OmniAuth users has administrator permissions. You may also bypass the auto sign in feature by browsing to `https://gitlab.example.com/users/sign_in?auto_sign_in=false`. diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 5bf079df800..6161f463b99 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -12,11 +12,13 @@ to sign in to other services. ## Introduction to OpenID Connect [OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the -OAuth 2.0 protocol. It allows clients to verify the identity of the end-user -based on the authentication performed by GitLab, as well as to obtain -basic profile information about the end-user in an interoperable and -REST-like manner. OIDC performs many of the same tasks as OpenID 2.0, -but does so in a way that is API-friendly, and usable by native and +OAuth 2.0 protocol. It allows clients to: + +- Verify the identity of the end-user based on the authentication performed by GitLab. +- Obtain basic profile information about the end-user in an interoperable and REST-like manner. + +OIDC performs many of the same tasks as OpenID 2.0, +but does so in a way that is API-friendly and usable by native and mobile applications. On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails @@ -34,7 +36,7 @@ is select the `openid` scope in the application settings. ## Shared information -Currently the following user information is shared with clients: +The following user information is shared with clients: | Claim | Type | Description | |:-----------------|:----------|:------------| diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index bb5425187c1..8f090dfc588 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -14,7 +14,7 @@ to confirm that a real user, not a bot, is attempting to create an account. To use reCAPTCHA, first you must create a site and private key. -1. Go to the URL: <https://www.google.com/recaptcha/admin>. +1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin). 1. Fill out the form necessary to obtain reCAPTCHA v2 keys. 1. Log in to your GitLab server, with administrator credentials. 1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`). @@ -26,7 +26,7 @@ To use reCAPTCHA, first you must create a site and private key. return `recaptcha_html`. NOTE: -Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public. +Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public. ## Enabling reCAPTCHA for user logins via passwords diff --git a/doc/integration/salesforce.md b/doc/integration/salesforce.md index 1aca3b04eee..156109518a6 100644 --- a/doc/integration/salesforce.md +++ b/doc/integration/salesforce.md @@ -86,4 +86,6 @@ Click the icon to begin the authentication process. Salesforce asks the user to If everything goes well, the user is returned to GitLab and is signed in. NOTE: -GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email. +GitLab requires the email address of each new user. After the user is signed in +using Salesforce, GitLab redirects the user to the profile page where they must +provide the email and verify the email. diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index e811cac4f0b..3b92f2858ac 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -10,17 +10,17 @@ NOTE: The preferred approach for integrating a Shibboleth authentication system with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older. -In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. +To enable Shibboleth support in GitLab we need to use Apache instead of NGINX. (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package.) Apache uses `mod_shib2` module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider. To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module. The installation and configuration of the module itself is out of the scope of this document. -Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information. +Check [the Shibboleth documentation](https://wiki.shibboleth.net/confluence/display/SP3/Apache) for more information. You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). The following changes are needed to enable Shibboleth: -1. Protect OmniAuth Shibboleth callback URL: +1. Protect the OmniAuth Shibboleth callback URL: ```apache <Location /users/auth/shibboleth/callback> @@ -53,7 +53,7 @@ The following changes are needed to enable Shibboleth: ``` NOTE: - Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an + In GitLab versions 11.4 and later, OmniAuth is enabled by default. If you're using an earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`. 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider. @@ -100,7 +100,7 @@ The following changes are needed to enable Shibboleth: 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. +On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in. ## Apache 2.4 / GitLab 8.6 update diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 6820ff8a0aa..e466b0edb6f 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. -Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it. +Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it. Commands are scoped to a project, with a trigger term that is specified during configuration. @@ -28,8 +28,8 @@ Taking the trigger term as `project-name`, the commands are: | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment | | `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` | -Note that if you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for -your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). +If you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for +your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage). ## Issue commands diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 8e1a6cdcfd1..5a2d07d661b 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -25,7 +25,7 @@ you can choose to enable Sourcegraph [through your user preferences](#enable-sou ## Set up for self-managed GitLab instances **(CORE ONLY)** -Before you can enable Sourcegraph code intelligence in GitLab you will need to: +Before you can enable Sourcegraph code intelligence in GitLab you must: - Enable the `sourcegraph` feature flag for your GitLab instance. - Configure a Sourcegraph instance with your GitLab instance as an external service. @@ -33,7 +33,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to: ### Enable the Sourcegraph feature flag NOTE: -If you are running a self-managed instance, the Sourcegraph integration will not be available +If you are running a self-managed instance, the Sourcegraph integration is unavailable unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console by instance administrators. @@ -64,7 +64,7 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running. -If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. +If you are using an HTTPS connection to GitLab, you must [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance. ### Connect your Sourcegraph instance to your GitLab instance @@ -79,9 +79,9 @@ You can skip this step if you already have your GitLab repositories searchable i 1. In GitLab, go to **Admin Area > Settings > General**. 1. Expand the **Sourcegraph** configuration section. 1. Check **Enable Sourcegraph**. -1. Set the Sourcegraph URL to your Sourcegraph instance, e.g., `https://sourcegraph.example.com`. +1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`. -![Sourcegraph admin settings](img/sourcegraph_admin_v12_5.png) +![Sourcegraph administration settings](img/sourcegraph_admin_v12_5.png) ## Enable Sourcegraph in user preferences @@ -95,7 +95,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i ## Using Sourcegraph code intelligence -Once enabled, participating projects will have a code intelligence popover available in +Once enabled, participating projects display a code intelligence popover available in the following code views: - Merge request diffs @@ -114,7 +114,7 @@ When visiting one of these views, you can now hover over a code reference to see Sourcegraph powered code intelligence is available for all public projects on GitLab.com. -Support for private projects is currently not available for GitLab.com; +Support for private projects is not yet available for GitLab.com; follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201) for updates. @@ -122,7 +122,7 @@ for updates. ### Sourcegraph isn't working -If you enabled Sourcegraph for your project but still it doesn't look like it's working, it might be because Sourcegraph has not indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. +If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project. ## Sourcegraph and Privacy @@ -130,5 +130,5 @@ From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integr engine behind the native GitLab integration: > Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com. -> They will only connect to Sourcegraph.com as required to provide code intelligence or other functionality on public code. +> They connect only to Sourcegraph.com as required to provide code intelligence or other functionality on public code. > As a result, no private code, private repository names, usernames, or any other specific data is sent to Sourcegraph.com. diff --git a/doc/raketasks/migrate_snippets.md b/doc/raketasks/migrate_snippets.md index 244ff4f2b56..52eb8954289 100644 --- a/doc/raketasks/migrate_snippets.md +++ b/doc/raketasks/migrate_snippets.md @@ -4,25 +4,24 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migration to Versioned Snippets **(CORE ONLY)** +# Migration to versioned snippets **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215861) in GitLab 13.0. In GitLab 13.0, [GitLab Snippets are backed by Git repositories](../user/snippets.md#versioned-snippets). -This means that the snippet content will be stored in the repository -and users can update it directly through Git. +Snippet content is stored in the repository, and users can update it directly through Git. -Nevertheless, existing GitLab Snippets have to be migrated to this new functionality. -For each snippet, a new repository is created and the snippet content is committed -to the repository inside a file whose name is the filename used in the snippet -as well. +Nevertheless, existing GitLab Snippets must be migrated to this new feature. +For each snippet: -GitLab performs this migration through a [Background Migration](../development/background_migrations.md) -automatically when the GitLab instance is upgrade to 13.0 or a higher version. -However, if the migration fails for any of the snippets, they still need -to be migrated individually. +- A new repository is created. +- A file is created in the repository, using the snippet filename. +- The snippet is committed to the repository. -The following Rake tasks will help with that process. +GitLab performs this migration through a [Background Migration](../development/background_migrations.md) +when the GitLab instance is upgraded to 13.0 or a higher version. +However, if the migration fails for any of the snippets, they must be migrated individually. +The following Rake tasks help with that process. ## Migrate specific snippets to Git diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index e80f672d05d..74dcce70cae 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -58,5 +58,6 @@ At the end, fill in your Mattermost details: | **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | +| **Branches to be notified** | Select which types of branches to send notifications for. | ![Mattermost configuration](img/mattermost_configuration.png) diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 4f996df5fef..df3e24fbf30 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -17,8 +17,8 @@ project. ![Find file button](img/file_finder_find_button_v12_10.png) -For those who prefer to keep their fingers on the keyboard, there is a -[shortcut button](../../shortcuts.md) as well, which you can invoke from _anywhere_ +If you prefer to keep their fingers on the keyboard, use the +[shortcut button](../../shortcuts.md), which you can invoke from anywhere in a project. Press `t` to launch the File search function when in **Issues**, diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index b9477da3937..a9e249bb8c3 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -21,8 +21,8 @@ Choose **New file** from the dropdown. Enter a filename in the **Filename** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field -will default to the branch you were viewing in the file browser. If you enter -a new branch name, a checkbox will appear, allowing you to start a new merge +defaults to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox displays, allowing you to start a new merge request after you commit the changes. When you are satisfied with your new file, click **Commit Changes** at the bottom. @@ -31,46 +31,45 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ### Shortcuts -You can use handy shortcuts when editing a file through the Web Editor, which are the same as -the Web IDE's. For details, see the documentation for [Command Palette](../web_ide/index.md#command-palette). +You can use shortcuts when editing a file through the Web Editor. It uses the same shortcuts +as the Web IDE. For details, read the documentation for [Command Palette](../web_ide/index.md#command-palette). ### Template dropdowns When starting a new project, there are some common files that the new project -might need too. Therefore a message will be displayed by GitLab to make this -easy for you. +might need. GitLab displays a message to help you: ![First file for your project](img/web_editor_template_dropdown_first_file.png) -When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown will be displayed -to provide you with a template that might be suitable for your project. +When clicking on either `LICENSE` or `.gitignore` and so on, a dropdown displays +to provide you a template that may be suitable for your project: ![MIT license selected](img/web_editor_template_dropdown_mit_license.png) -The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also -be added through a button on the project page. In the example below, the license +The license, changelog, contribution guide, or `.gitlab-ci.yml` file can also +be added through a button on the project page. In this example, the license has already been created, which creates a link to the license itself. ![New file button](img/web_editor_template_dropdown_buttons.png) NOTE: -The **Set up CI/CD** button will not appear on an empty repository. You have to at -least add a file in order for the button to show up. +The **Set up CI/CD** button does not appear on an empty repository. For the button +to display, add a file to your repository. ## Upload a file The ability to create a file is great when the content is text. However, this -doesn't work well for binary data such as images, PDFs, or other file types. In +doesn't work well for binary data such as images, PDFs, or other binary file types. In this case, you need to upload a file. From a project's files page, click the '+' button to the right of the branch -selector. Choose **Upload file** from the dropdown. +selector. Choose **Upload file** from the dropdown: ![Upload file dropdown menu](img/web_editor_upload_file_dropdown.png) -Once the upload dialog pops up, there are two ways to upload your file. Either -drag and drop a file on the popup or use the **click to upload** link. A file -preview will appear once you have selected a file to upload. +After the upload dialog pops up, there are two ways to upload your file. Either +drag and drop a file on the popup or use the **click to upload** link. After you +select a file to upload, a file preview displays. Enter a commit message, choose a branch, and click **Upload file** when you are ready. @@ -100,19 +99,22 @@ There are multiple ways to create a branch from the GitLab web interface. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. -If your development workflow dictates to have an issue for every merge -request, you can quickly create a branch directly from the issue to speed the process up. -The new branch, and later its merge request, will be marked as related to this issue. -Once merged, the MR will automatically close the issue. +If your development workflow requires an issue for every merge +request, you can create a branch directly from the issue to speed the process up. +The new branch, and later its merge request, are marked as related to this issue. +Once merged, the merge request closes the issue. You can see a **Create merge request** dropdown below the issue description. -NOTE: -You won't see the **Create merge request** button if there is already a branch with the same -name or a referenced merge request or your project has an active -fork relationship. -If you would like to make this button appear, a possible workaround is to [remove your project's -fork relationship](../settings/index.md#removing-a-fork-relationship). Once removed, the fork -relationship cannot be restored. This project will no longer be able to receive or send merge requests to the source project or other forks. +The **Create merge request** button doesn't display if: + +- A branch with the same name already exists. +- The branch already has a referenced merge request. +- Your project has an active fork relationship. + +To make this button appear, one possible workaround is to +[remove your project's fork relationship](../settings/index.md#removing-a-fork-relationship). +After removal, the fork relationship cannot be restored. This project can no longer +be able to receive or send merge requests to the source project, or other forks. ![Create Button](img/web_editor_new_branch_from_issue_create_button_v12_6.png) @@ -120,46 +122,47 @@ This dropdown contains the options **Create merge request and branch** and **Cre ![New Branch Button](img/web_editor_new_branch_from_issue_v_12_6.png) -Once you choose one of these options, a new branch or branch and merge request -will be created based on the default -branch of your project (by default, `master`). The branch name will be based on -the title of the issue, and as a prefix, it will have its internal ID. Thus, the example -screenshot above will create a branch named +After selecting one of these options, a new branch or branch and merge request +is created based on your project's default branch. By default, this branch is `master`. +The branch name is based on an internal ID, and the issue title. The example +screenshot above creates a branch named `2-make-static-site-auto-deploy-and-serve`. When you click the **Create branch** button in an empty -repository project, GitLab automatically creates a `master` branch, commits -a blank `README.md` file to it, and creates and redirects you to a new branch -based on the issue title. -If your [project is already configured with a deployment service](../integrations/overview.md), -such as Kubernetes, GitLab takes one step further and prompts you to set up -[auto deploy](../../../topics/autodevops/stages.md#auto-deploy) -by helping you create a `.gitlab-ci.yml` file. +repository project, GitLab performs these actions: + +- Creates a `master` branch. +- Commits a blank `README.md` file to it. +- Creates and redirects you to a new branch based on the issue title. +- _If your project is [configured with a deployment service](../integrations/overview.md) like Kubernetes,_ + GitLab prompts you to set up [auto deploy](../../../topics/autodevops/stages.md#auto-deploy) + by helping you create a `.gitlab-ci.yml` file. After the branch is created, you can edit files in the repository to fix -the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) -`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +the issue. When a merge request is created based on the newly-created branch, +the description field displays the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) +`Closes #ID`, where `ID` is the ID of the issue. This closes the issue when the merge request is merged. ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge -request, you can create a new branch upfront. From a project's files page, -choose **New branch** from the dropdown. +request, you can create a new branch upfront. -![New branch dropdown](img/web_editor_new_branch_dropdown.png) +1. From a project's files page, choose **New branch** from the dropdown. -Enter a new **Branch name**. Optionally, change the **Create from** field -to choose which branch, tag, or commit SHA this new branch will originate from. -This field will autocomplete if you start typing an existing branch or tag. -Click **Create branch** and you will be returned to the file browser on this new -branch. + ![New branch dropdown](img/web_editor_new_branch_dropdown.png) -![New branch page](img/web_editor_new_branch_page.png) +1. Enter a new **Branch name**. +1. (Optional) Change the **Create from** field to choose which branch, tag, or + commit SHA this new branch originates from. This field autocompletes if you + start typing an existing branch or tag. +1. Click **Create branch** to return to the file browser on this new branch. + + ![New branch page](img/web_editor_new_branch_page.png) You can now make changes to any files, as needed. When you're ready to merge -the changes back to master, you can use the widget at the top of the screen. +the changes back to `master`, you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or modify files. @@ -167,31 +170,35 @@ modify files. ## Create a new tag -Tags are useful for marking major milestones such as production releases, -release candidates, and more. You can create a tag from a branch or a commit -SHA. From a project's files page, choose **New tag** from the dropdown. +Tags help you mark major milestones such as production releases and +release candidates. You can create a tag from a branch or a commit +SHA: + +1. From a project's files page, choose **New tag** from the dropdown. -![New tag dropdown](img/web_editor_new_tag_dropdown.png) + ![New tag dropdown](img/web_editor_new_tag_dropdown.png) -Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you -would like to create this new tag. You can optionally add a message and -release notes. The release notes section supports Markdown format and you can -also upload an attachment. Click **Create tag**, and you will be taken to the tag -list page. +1. Give the tag a name such as `v1.0.0`. +1. Choose the branch or SHA from which you want to create this new tag. +1. (Optional) Add a message and release notes. The release notes section supports + Markdown format. +1. (Optional) Upload an attachment. +1. Click **Create tag**, and GitLab redirects you to the tag list page. -![New tag page](img/web_editor_new_tag_page.png) + ![New tag page](img/web_editor_new_tag_page.png) ## Tips When creating or uploading a new file or creating a new directory, you can -trigger a new merge request rather than committing directly to `master`. Enter -a new branch name in the **Target branch** field. You will notice a checkbox -appear that is labeled **Start a new merge request with these changes**. After -you commit the changes you will be taken to a new merge request form. +trigger a new merge request rather than committing directly to `master`: + +1. Enter a new branch name in the **Target branch** field. +1. GitLab displays the **Start a new merge request with these changes** check box. +1. Commit your changes, and GitLab redirects you to a new merge request form. -![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) + ![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) -If you'd prefer _not_ to use your primary email address for commits created +If you'd prefer to not use your primary email address for commits created through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md index c0501de3546..1e5e0f74fd6 100644 --- a/doc/user/project/static_site_editor/index.md +++ b/doc/user/project/static_site_editor/index.md @@ -23,8 +23,8 @@ and submit the changes for review. The Static Site Editor allows collaborators to submit changes to static site files seamlessly. For example: -- Non-technical collaborators can easily edit a page directly from the browser; - they don't need to know Git and the details of your project to be able to contribute. +- Non-technical collaborators can edit a page directly from the browser. + They don't need to know Git and the details of your project to contribute. - Recently hired team members can quickly edit content. - Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to. @@ -68,7 +68,7 @@ The editor can then navigate to the merge request to assign it to a colleague fo ## Set up your project First, set up the project. Once done, you can use the Static Site Editor to -easily [edit your content](#edit-content). +[edit your content](#edit-content). 1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork) @@ -101,7 +101,7 @@ To edit a file: wish to edit the raw Markdown instead, you can toggle the **Markdown** mode in the bottom-right corner. 1. When you're done, click **Submit changes...**. -1. (Optional) Adjust the default title and description of the merge request that will be submitted +1. (Optional) Adjust the default title and description of the merge request, to submit with your changes. Alternatively, select a [merge request template](../../../user/project/description_templates.md#creating-merge-request-templates) from the dropdown menu and edit it accordingly. 1. Click **Submit changes**. @@ -154,9 +154,9 @@ so you can verify the correct image is included and there aren't any references You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**). The following URL/ID formats are supported: -- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`) -- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`) -- YouTube video ID (e.g. `0t1DgySidms`) +- **YouTube watch URLs**: `https://www.youtube.com/watch?v=0t1DgySidms` +- **YouTube embed URLs**: `https://www.youtube.com/embed/0t1DgySidms` +- **YouTube video IDs**: `0t1DgySidms` ### Front matter @@ -164,13 +164,13 @@ The following URL/ID formats are supported: > - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5. Front matter is a flexible and convenient way to define page-specific variables in data files -intended to be parsed by a static site generator. It is commonly used for setting a page's -title, layout template, or author, but can be used to pass any kind of metadata to the +intended to be parsed by a static site generator. Use it to set a page's +title, layout template, or author. You can also pass any kind of metadata to the generator as the page renders out to HTML. Included at the very top of each data file, the -front matter is often formatted as YAML or JSON and requires consistent and accurate syntax. +front matter is often formatted as YAML or JSON, and requires consistent and accurate syntax. To edit the front matter from the Static Site Editor you can use the GitLab regular file editor, -the Web IDE, or easily update the data directly from the WYSIWYG editor: +the Web IDE, or update the data directly from the WYSIWYG editor: 1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you have on the page's front matter. The form is populated with the current data: @@ -181,10 +181,16 @@ the Web IDE, or easily update the data directly from the WYSIWYG editor: 1. When you're done, click **Submit changes...**. 1. Describe your changes (add a commit message). 1. Click **Submit changes**. -1. Click **View merge request** and GitLab will take you there. +1. Click **View merge request** to view it. -Note that support for adding new attributes to the page's front matter from the form is not supported -yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields. +Adding new attributes to the page's front matter from the form is not supported. +To add new attributes: + +- Edit the file locally +- Edit the file with the GitLab regular file editor. +- Edit the file with the Web IDE. + +After adding an attribute, the form loads the new fields. ## Configuration files @@ -206,8 +212,8 @@ use to customize behavior of the Static Site Editor (SSE). If the file does not default values which support a default Middleman project configuration are used. The [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman) project template generates a file pre-populated with these defaults. -To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries -(described in the table below) according to what works best for your project (respecting YAML syntax). +To customize the behavior of the SSE, edit `.gitlab/static-site-editor.yml`'s entries, +according to your project's needs. Make sure to respect YAML syntax. After the table, see an [example of the SSE configuration file](#gitlabstatic-site-editoryml-example). @@ -224,8 +230,9 @@ image_upload_path: 'source/images' # Relative path to the project's root. Don't ### Static Site Generator configuration The Static Site Editor uses Middleman's configuration file, `data/config.yml` -to customize the behavior of the project itself and to control the **Edit this -page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). +to customize the behavior of the project itself. This file also controls the +**Edit this page** button, rendered through the file +[`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb). To [configure the project template to your own project](#set-up-your-project), you must replace the `<username>` and `<project-name>` in the `data/config.yml` @@ -236,7 +243,7 @@ the Static Site Editor may use different configuration files or approaches. ## Using Other Static Site Generators -Although Middleman is the only Static Site Generator currently officially supported +Although Middleman is the only Static Site Generator officially supported by the Static Site Editor, you can configure your project's build and deployment to use a different Static Site Generator. In this case, use the Middleman layout as an example, and follow a similar approach to properly render an **Edit this page** diff --git a/doc/user/search/img/search_history.gif b/doc/user/search/img/search_history.gif Binary files differdeleted file mode 100644 index 4cfa48ee0ab..00000000000 --- a/doc/user/search/img/search_history.gif +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index d229c27b608..8b0934903eb 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -9,16 +9,14 @@ type: index, reference, howto ## Issues and merge requests -To search through issues and merge requests in multiple projects, you can use the **Issues** or **Merge Requests** links -in the top-right part of your screen. +To search through issues and merge requests in multiple projects, use the **Issues** or **Merge Requests** links +in the top-right part of your screen. These instructions are valid for both. -Both of them work in the same way, therefore, the following notes are valid for both. - -The number displayed on their right represents the number of issues and merge requests assigned to you. +The number displayed on their right represents the number of issues and merge requests assigned to you: ![issues and MRs dashboard links](img/dashboard_links.png) -When you click **Issues**, the opened issues assigned to you are shown straight away: +When you click **Issues**, GitLab shows the opened issues assigned to you: ![Issues assigned to you](img/issues_assigned_to_you.png) @@ -30,7 +28,7 @@ You can also filter the results using the search and filter field, as described ### Issues and MRs assigned to you or created by you GitLab shows shortcuts to issues and merge requests created by you or assigned to you -on the search field on the top-right of your screen: +in the search field in the upper right corner: ![shortcut to your issues and merge requests](img/issues_mrs_shortcut.png) @@ -156,15 +154,16 @@ using the filter functionality, you can start typing characters to bring up relevant users or other attributes. For performance optimization, there is a requirement of a minimum of three -characters to begin your search. For example, if you want to search for -issues that have the assignee "Simone Presley", you must type at -least "Sim" before autocomplete gives any relevant results. +characters to begin your search. To search for issues with the assignee `Simone Presley`, +you must type at least `Sim` before autocomplete displays results. ## Search history -You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser. +Search history is available for issues and merge requests, and is stored locally +in your browser. To run a search from history: -![search history](img/search_history.gif) +1. In the top menu, click **Issues** or **Merge requests**. +1. To the left of the search bar, click **Recent searches**, and select a search from the list. ## Removing search filters @@ -174,7 +173,7 @@ To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</ ## Filtering with multiple filters of the same type -Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. +Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the `AND` logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned. ![multiple assignees filtering](img/multiple_assignees.png) @@ -192,8 +191,8 @@ You can search through your projects from the left menu, by clicking the menu ba On the field **Filter by name**, type the project or group name you want to find, and GitLab filters them for you as you type. -You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all -public and internal projects available in GitLab.com, from which you can filter by visibility, +You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**). +You can **Explore** all public and internal projects available in GitLab.com, from which you can filter by visibility, through **Trending**, best rated with **Most stars**, or **All** of them. You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, @@ -217,7 +216,7 @@ and sort them by **Last created**, **Oldest created**, **Last updated**, or **Ol From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. -When you want to search for issues to add to lists present in your Issue Board, click +To search for issues to add to lists present in your Issue Board, click the button **Add issues** on the top-right of your screen, opening a modal window from which you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, and **Labels**, select multiple issues to add to a list of your choice: @@ -226,10 +225,14 @@ and **Labels**, select multiple issues to add to a list of your choice: ## Shortcut -GitLab shows a shortcut on the search field on the top-right of the project's dashboard to -quickly access issues and merge requests created or assigned to you in that project: +To view issues and merge requests created or assigned to you in a project: + +1. Go to your project. +1. In the top navigation bar, click the search box to display a list of issues and + merge requests. +1. Select your desired issue or merge request: -![search per project - shortcut](img/project_search.png) + ![search per project - shortcut](img/project_search.png) ### Autocomplete suggestions @@ -246,7 +249,7 @@ You can also type in this search bar to see autocomplete suggestions for: ## Basic search -The Basic search in GitLab is a global search service that allows you to search +The Basic search in GitLab enables you to search across the entire GitLab instance, in a group, or in a single project. Basic search is backed by the database and allows searching in: diff --git a/doc/user/snippets.md b/doc/user/snippets.md index af499221da6..e919e73f404 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -65,8 +65,8 @@ have version control enabled by default. This means that all snippets get their own underlying repository initialized with a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a -new commit to the master branch is recorded. Commit messages are automatically -generated. The snippet's repository has only one branch (master) by default, deleting +new commit to the `master` branch is recorded. Commit messages are automatically +generated. The snippet's repository has only one branch (`master`) by default, deleting it or creating other branches is not supported. Existing snippets are automatically migrated in 13.0. Their current @@ -75,14 +75,14 @@ content is saved as the initial commit to the snippets' repository. ### Filenames Snippets support syntax highlighting based on the filename and -extension provided for them. While it is possible to submit a snippet +extension provided for them. While you can submit a snippet without specifying a filename and extension, it needs a valid name so the content can be created as a file in the snippet's repository. -In case the user does not attribute a filename and extension to a snippet, -GitLab automatically adds a filename in the format `snippetfile<x>.txt` +If you don't attribute a filename and extension to a snippet, +GitLab adds a filename in the format `snippetfile<x>.txt` where `<x>` represents a number added to the file, starting with 1. This -number increases incrementally when more snippets without an attributed +number increments when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets @@ -96,14 +96,15 @@ direct or embedded links to the snippet. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5. -GitLab Snippets support multiple files in one single snippet. It can be very handy +GitLab Snippets support multiple files in one single snippet. This is helpful when your code snippet is composed of multiple parts or when they relate to a certain context. For example: - A snippet that includes a script and its output. - A snippet that includes HTML, CSS, and JS code. - A snippet with a `docker-compose.yml` file and its associated `.env` file. -- A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. +- A `gulpfile.js` file coupled with a `package.json` file, which together can be + used to bootstrap a project and manage its dependencies. Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. @@ -135,7 +136,7 @@ button above the snippet content to copy the URL of your choice. This allows you to have a local copy of the snippet's repository and make changes as needed. You can commit those changes and push them to the remote -master branch. +`master` branch. ### Reduce snippets repository size @@ -148,15 +149,15 @@ see the documentation on [reducing repository size](../user/project/repository/r ### Limitations - Binary files are not supported. -- Creating or deleting branches is not supported. Only a default *master* branch is used. +- Creating or deleting branches is not supported. Only a default `master` branch is used. - Git tags are not supported in snippet repositories. - Snippets' repositories are limited to 10 files. Attempting to push more -than 10 files results in an error. -- Revisions are not *yet* visible to the user on the GitLab UI, but -it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) -for updates. + than 10 files results in an error. +- Revisions are not visible to the user on the GitLab UI, but this feature is planned + in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271) + for updates. - The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit) -is 50 MB, by default. + is 50 MB, by default. - Git LFS is not supported. ## Discover snippets @@ -168,10 +169,10 @@ dashboard of your GitLab instance via the top navigation. For GitLab.com you can navigate to an [overview]((https://gitlab.com/dashboard/snippets)) that shows snippets you created and allows you to explore all snippets. -If you want to discover snippets that belong to a specific project, you can navigate +To discover snippets that belong to a specific project, navigate to the Snippets page via the left side navigation on the project page. -Project snippets are enabled and available by default, but they can -be disabled by navigating to your project's **Settings**, expanding +Project snippets are enabled and available by default. You can +disable them by navigating to your project's **Settings**, expanding **Visibility, project features, permissions** and scrolling down to **Snippets**. From there, you can toggle to disable them or select a different visibility level from the dropdown menu. @@ -181,7 +182,7 @@ different visibility level from the dropdown menu. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2. With GitLab Snippets you engage in a conversation about that piece of code, -facilitating the collaboration among users. +encouraging user collaboration. ## Downloading snippets @@ -207,20 +208,23 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -After the above conditions are met, the "Embed" section appears in your -snippet where you can simply click on the "Copy" button. This copies a one-line -script that you can add to any website or blog post. - -Here's how an example code looks like: +After the above conditions are met, the **Embed** section appears in your +snippet. Click the **Copy** button to copy a one-line +script that you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> ``` -Here's how an embedded snippet looks like: +Here's what an embedded snippet looks like: <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script> -Embedded snippets are displayed with a header that shows the filename if it's defined, -the snippet size, a link to GitLab, and the actual snippet content. Actions in -the header allow users to see the snippet in raw format and download it. +Embedded snippets are displayed with a header that shows: + +- The filename, if defined. +- The snippet size. +- A link to GitLab. +- The actual snippet content. + +Actions in the header enable users to see the snippet in raw format, and download it. |