diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 21:09:57 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-17 21:09:57 +0000 |
| commit | 43678813e8265b8a00b3039fce155f4c20947a7a (patch) | |
| tree | 0bd6d4f8ecfebf00e5cde7770d73aec62973d800 /doc/user | |
| parent | f3b791d5d5b0b058d2b717da1a54a63f3bba5adc (diff) | |
| download | gitlab-ce-43678813e8265b8a00b3039fce155f4c20947a7a.tar.gz | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user')
19 files changed, 167 insertions, 173 deletions
diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 7546556a7c0..3d4ec83c587 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -54,8 +54,8 @@ specific environment, there are a lot of use cases. To name a few: - You want to promote what's running in staging, to production. You go to the environments list, verify that what's running in staging is what you think is running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production. -- You trigger a deploy, and you've got lots of containers to upgrade so you know - it'll take a while (you've also throttled your deploy to only take down X +- You trigger a deploy, and you have many containers to upgrade so you know + this takes a while (you've also throttled your deploy to only take down X containers at a time). But you need to tell someone when it's deployed, so you go to the environments list, look at the production environment to see what the progress is in real-time as each pod is rolled. @@ -76,8 +76,8 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. Have a Kubernetes cluster up and running. NOTE: - If you are using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards won't render + If you're using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`. Otherwise, the Deploy Boards don't render correctly. For more information, read the [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584). @@ -85,7 +85,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ 1. [Configure GitLab Runner](../../ci/runners/README.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the - cluster. The Kubernetes namespace is of particular note as you will need it + cluster. The Kubernetes namespace is of particular note as you need it for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the @@ -95,7 +95,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ than one. These resources should be contained in the namespace defined in the Kubernetes service setting. You can use an [Autodeploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml` template which has predefined stages and commands to use, and automatically - applies the annotations. Each project will need to have a unique namespace in + applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes. @@ -106,7 +106,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary. - If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: + If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**:  @@ -142,7 +142,7 @@ spec: app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG} ``` -The annotations will be applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. +The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like `kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}`, you can follow the instances' pods from the board. NOTE: The YAML file is static. If you apply it using `kubectl apply`, you must diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 39b790544c1..93ed1030e1f 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -92,7 +92,7 @@ There are three lists of Project Deploy Keys:  -After you add a key, it will be enabled for this project by default, and it'll appear +After you add a key, it's enabled for this project by default and it appears in the **Enabled deploy keys** tab. In the **Privately accessible deploy keys** tab, you can enable a private key which @@ -111,7 +111,7 @@ and `read-write` access. NOTE: If you have enabled a privately or publicly accessible or deploy key for your project, and if you then update the access level for this key from `read-only` to -`read-write`, the change will be only for the **current project**. +`read-write`, the change is only for the **current project**. ### Public deploy keys @@ -131,7 +131,7 @@ Instance administrators can add public deploy keys:  -After adding a key, it will be available to any shared systems. Project maintainers +After adding a key, it's available to any shared systems. Project maintainers or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project. NOTE: @@ -155,8 +155,8 @@ until a project maintainer chooses to make use of it. ### Deploy Key cannot push to a protected branch -If the owner of this deploy key does not have access to a [protected -branch](../protected_branches.md), then this deploy key won't have access to +If the owner of this deploy key doesn't have access to a [protected +branch](../protected_branches.md), then this deploy key doesn't have access to the branch either. In addition to this, choosing the **No one** value in [the "Allowed to push" section](../protected_branches.md#configuring-protected-branches) means that no users **and** no services using deploy keys can push to that selected branch. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ac19c44c58a..5a62730d989 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -36,7 +36,7 @@ project. Alternatively, you can also create [group-scoped deploy tokens](#group- 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Select **Create deploy token**. 1. Save the deploy token somewhere safe. After you leave or refresh - the page, **you won't be able to access it again**. + the page, **you can't access it again**.  @@ -89,7 +89,7 @@ Replace `<username>` and `<deploy_token>` with the proper values. ### Read Container Registry images -To read the container registry images, you'll need to: +To read the container registry images, you must: 1. Create a Deploy Token with `read_registry` as a scope. 1. Take note of your `username` and `token`. @@ -106,7 +106,7 @@ pull images from your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -To push the container registry images, you'll need to: +To push the container registry images, you must: 1. Create a Deploy Token with `write_registry` as a scope. 1. Take note of your `username` and `token`. @@ -123,7 +123,7 @@ push images to your Container Registry. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To pull packages in the GitLab package registry, you'll need to: +To pull packages in the GitLab package registry, you must: 1. Create a Deploy Token with `read_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -134,7 +134,7 @@ To pull packages in the GitLab package registry, you'll need to: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. -To upload packages in the GitLab package registry, you'll need to: +To upload packages in the GitLab package registry, you must: 1. Create a Deploy Token with `write_package_registry` as a scope. 1. Take note of your `username` and `token`. @@ -160,7 +160,7 @@ To use a group deploy token: 1. Use it the same way you use a project deploy token when [cloning a repository](#git-clone-a-repository). -The scopes applied to a group deploy token (such as `read_repository`) will +The scopes applied to a group deploy token (such as `read_repository`) apply consistently when cloning the repository of related projects. ### GitLab Deploy Token @@ -168,7 +168,7 @@ apply consistently when cloning the repository of related projects. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18414) in GitLab 10.8. There's a special case when it comes to Deploy Tokens. If a user creates one -named `gitlab-deploy-token`, the username and token of the Deploy Token will be +named `gitlab-deploy-token`, the username and token of the Deploy Token is automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and `CI_DEPLOY_PASSWORD`, respectively. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 02cb0313a74..3b3d594ddda 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -29,8 +29,8 @@ confidential checkbox and hit **Save changes**. There are two ways to change an issue's confidentiality. -The first way is to edit the issue and mark/unmark the confidential checkbox. -Once you save the issue, it will change the confidentiality of the issue. +The first way is to edit the issue and toggle the confidentiality checkbox. +After you save the issue, the confidentiality of the issue is updated. The second way is to locate the Confidentiality section in the sidebar and click **Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. @@ -46,20 +46,19 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), -you won't be able to see the confidential issues at all. - There are a few things that visually separate a confidential issue from a regular one. In the issues index page view, you can see the eye-slash icon next to the issues that are marked as confidential.  +If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +you cannot see confidential issues at all. + --- Likewise, while inside the issue, you can see the eye-slash icon right next to -the issue number, but there is also an indicator in the comment area that the +the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential.  @@ -83,7 +82,7 @@ project's search results respectively. | Maintainer access | Guest access | | :-----------: | :----------: | -|  |  | +|  |  | ## Merge Requests for Confidential Issues @@ -93,24 +92,24 @@ To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be resolved by creating a merge request from a private fork. -The merge request created will target the default branch of the private fork, +The created merge request targets the default branch of the private fork, not the default branch of the public upstream project. This prevents the merge request, branch, and commits entering the public repository, and revealing -confidential information prematurely. When the confidential commits are ready -to be made public, this can be done by opening a merge request from the private -fork to the public upstream project. +confidential information prematurely. To make a confidential commit public, +open a merge request from the private fork to the public upstream project. -NOTE: -If you create a long-lived private fork in the same group or in a sub-group of -the original upstream, all the users with Developer membership to the public -project will also have the same permissions in the private project. This way, -all the Developers, who have access to view confidential issues, will have a -streamlined workflow for fixing them. +Permissions are inherited from parent groups. Developers have the same permissions +for private forks created in the same group or in a sub-group of the original +Permissions are inherited from parent groups. When private forks are created +in the same group or sub-group as the original upstream repository, users +receive the same permissions in both projects. This inheritance ensures +Developer users have the needed permissions to both view confidential issues and +resolve them. ### How it works On a confidential issue, a **Create confidential merge request** button is -available. Clicking on it will open a dropdown where you can choose to +available. Clicking on it opens a dropdown where you can choose to **Create confidential merge request and branch** or **Create branch**: | Create confidential merge request | Create branch | @@ -121,12 +120,12 @@ The **Project** dropdown includes the list of private forks the user is a member of as at least a Developer and merge requests are enabled. Whenever the **Branch name** and **Source (branch or tag)** fields change, the -availability of the target or source branch will be checked. Both branches should -be available in the private fork selected. +availability of the target and source branch are checked. Both branches should +be available in the selected private fork. -By clicking the **Create confidential merge request** button, GitLab will create +By clicking the **Create confidential merge request** button, GitLab creates the branch and merge request in the private fork. When you choose -**Create branch**, GitLab will only create the branch. +**Create branch**, GitLab creates only the branch. -Once the branch is created in the private fork, developers can now push code to +After the branch is created in the private fork, developers can push code to that branch to fix the confidential issue. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 03060ca720c..ef860df054e 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,16 +19,16 @@ Key actions for issues include: ## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. +[Quick actions](../quick_actions.md) feature to input values. While creating an issue, you can associate it to an existing epic from current group by selecting it using **Epic** dropdown. ### Accessing the New Issue form -There are many ways to get to the New Issue form from within a project: +There are many ways to get to the New Issue form from a project's page: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -75,9 +75,8 @@ using the dropdown button at the top-right of the page.  -We'll keep track of the project you selected most recently, and use it as the default -for your next visit. This should save you a lot of time and clicks, if you mostly -create issues for the same project. +The project you selected most recently becomes the default for your next visit. +This should save you a lot of time and clicks, if you mostly create issues for the same project.  @@ -90,22 +89,22 @@ the appropriate project and followed up from there. ### New issue via email A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured. +**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured and there is at least one issue in the issue list.  When you click this link, an email address is generated and displayed, which should be used by **you only**, to create issues in this project. You can save this address as a -contact in your email client for easy access. +contact in your email client for quick access. WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. +were you. If the address is compromised, or you want to regenerate it, +click **Email a new issue to this project**, followed by **reset it**. -Sending an email to this address will create a new issue in your name for +Sending an email to this address creates a new issue associated with your account for this project, where: - The email subject becomes the issue title. @@ -118,15 +117,15 @@ older format is still supported, allowing existing aliases or contacts to contin ### New issue via URL with prefilled fields -You can link directly to the new issue page for a given project, with prefilled -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. +To link directly to the new issue page with prefilled fields, use query +string parameters in a URL. You can embed a URL in an external +HTML page, or create issues with certain +fields prefilled. The title, description, description template, and confidential fields can be prefilled using this method. You cannot pre-fill both the description and description template -fields in the same URL (since a description template also populates the description -field). +fields in the same URL because a description template also populates the description +field. | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| @@ -147,9 +146,9 @@ Follow these examples to form your new issue URL with prefilled fields. ## Moving Issues -Moving an issue will copy it to a new location (project), and close it in the old project, -but it will not be deleted. There will also be a system note added to both issues -indicating where it came from and went to. +Moving an issue copies it to the target project, and closes it in the originating project. +The original issue is not deleted. A system note, which indicates +where it came from and went to, is added to both issues. The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. @@ -157,7 +156,9 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i ### Moving Issues in Bulk -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. +If you have advanced technical skills you can also bulk move all the issues from +one project to another in the rails console. The below script moves all issues +that are not in status **closed** from one project to another. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. @@ -193,23 +194,18 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: -For performance reasons, automatic issue closing is disabled for the very first -push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to have -these issues closed automatically when the commit or merge request reaches the project's -default branch. +When a commit or merge request resolves issues, the issues +can be closed automatically when the commit reaches the project's default branch. If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text will be closed. This happens when the commit +all issues referenced in the matched text are closed. This happens when the commit is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), or when a commit or merge request is merged into it. For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. Using `Related to` flags `#5` as a [related issue](related_issues.md), -but it will not close automatically. +but is not closed automatically.  @@ -219,9 +215,12 @@ If the issue is in a different repository than the MR, add the full URL for the Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> ``` +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + #### Default closing pattern -When not specified, the default issue closing pattern as shown below will be used: +When not specified, this default issue closing pattern is used: ```shell \b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) @@ -251,8 +250,8 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, -as well as `#22` and `#23` in `group/otherproject`. `#17` won't be closed as it does +closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does not match the pattern. It works with multi-line commit messages as well as one-liners when used from the command line with `git commit -m`. @@ -261,14 +260,14 @@ when used from the command line with `git commit -m`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. The automatic issue closing feature can be disabled on a per-project basis -within the [project's repository settings](../settings/index.md). Referenced -issues will still be displayed as such but won't be closed automatically. +in the [project's repository settings](../settings/index.md). Referenced +issues are still displayed, but are not closed automatically.  This only applies to issues affected by new merge requests or commits. Already closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *within* the project and won't prevent other projects from closing it +requests *in* the project and does not prevent other projects from closing it via cross-project issues. #### Customizing the issue closing pattern **(CORE ONLY)** diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 4aa89ec6f8d..f02697a3cd5 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -24,7 +24,7 @@ GitLab Pages site. Note that **how to** add DNS records depends on which server your domain is hosted on. Every control panel has its own place to do it. If you are not an administrator of your domain, and don't have access to your registrar, -you'll need to ask for the technical support of your hosting service +you must ask the technical support of your hosting service to do it for you. To help you out, we've gathered some instructions on how to do that @@ -67,7 +67,7 @@ Example: - `www` => `CNAME` => `example.com` -This way, visitors visiting `www.example.com` will be redirected to +This way, visitors visiting `www.example.com` are redirected to `example.com`. ## MX record diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index f8173b4c004..8ed0ef82893 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -47,7 +47,8 @@ Click **Create New Domain**. #### 2. Get the verification code -Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step. +After you add a new domain to Pages, the verification code prompts you. Copy the values from GitLab +and paste them in your domain's control panel as a TXT record on the next step.  @@ -91,7 +92,7 @@ add a DNS apex `CNAME` record instead of an `A` record. The main advantage of doing so is that when GitLab Pages IP on GitLab.com changes for whatever reason, you don't need to update your `A` record. There may be a few exceptions, but **this method is not recommended** -as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. +as it most likely doesn't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. ##### For subdomains @@ -154,12 +155,11 @@ Once you have added all the DNS records:  -As soon as your domain becomes active, your website will be available -through your domain name. +As soon as your domain becomes active, your website is available through your domain name. WARNING: Considering GitLab instances with domain verification enabled, -if the domain cannot be verified for 7 days, it will be removed +if the domain can't be verified for 7 days, it's removed from the GitLab project. > **Notes:** @@ -169,9 +169,9 @@ from the GitLab project. to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). > - [DNS propagation may take some time (up to 24h)](https://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/complete-guide-to-dns-records/), although it's usually a matter of minutes to complete. Until it does, verification - will fail and attempts to visit your domain will respond with a 404. + fails, and attempts to visit your domain result in a 404. > - Once your domain has been verified, leave the verification record - in place: your domain will be periodically reverified, and may be + in place. Your domain is periodically reverified, and may be disabled if the record is removed. ##### Troubleshooting Pages domain verification @@ -211,7 +211,7 @@ For a subdomain: You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room. -All the aliases you've set to your site will be listed on **Setting > Pages**. +All the aliases you've set to your site are listed on **Setting > Pages**. From that page, you can view, add, and remove them. ### Redirecting `www.domain.com` to `domain.com` with Cloudflare @@ -294,7 +294,7 @@ Sublime Text, Atom, Dreamweaver, Brackets, etc). To make your website's visitors even more secure, you can choose to force HTTPS for GitLab Pages. By doing so, all attempts to visit your -website via HTTP will be automatically redirected to HTTPS via 301. +website through HTTP are automatically redirected to HTTPS through 301. It works with both the GitLab default domain and with your custom domain (as long as you've set a valid certificate for it). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md index 3dea35153e4..aa06a15a8c0 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -50,15 +50,15 @@ Once you've met the requirements, enable Let's Encrypt integration: 1. Click **Save changes**. -Once enabled, GitLab will obtain a LE certificate and add it to the -associated Pages domain. It also will be renewed automatically by GitLab. +Once enabled, GitLab obtains a LE certificate and add it to the +associated Pages domain. GitLab also renews it automatically. > **Notes:** > > - Issuing the certificate and updating Pages configuration > **can take up to an hour**. -> - If you already have SSL certificate in domain settings it -> will continue to work until it will be replaced by Let's Encrypt's certificate. +> - If you already have an SSL certificate in domain settings it +> continues to work until replaced by the Let's Encrypt's certificate. ## Troubleshooting diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md index dc73a664324..e8c6305dbab 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w _Read this document for a brief overview of SSL/TLS certificates in the scope of GitLab Pages, for beginners in web development._ -Every GitLab Pages project on GitLab.com will be available under +Every GitLab Pages project on GitLab.com is available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set up your Pages project with your custom (sub)domain, if you want -it secured by HTTPS, you will have to issue a certificate for that +it secured by HTTPS, you must issue a certificate for that (sub)domain and install it on your project. NOTE: @@ -41,9 +41,6 @@ the connection between the **client** (you, me, your visitors) and the **server** (where you site lives), through a keychain of authentications and validations. -How about taking Josh's advice and protecting our sites too? We will be -well supported, and we'll contribute to a safer internet. - ## Organizations supporting HTTPS There is a huge movement in favor of securing all the web. W3C fully @@ -62,8 +59,8 @@ GitLab Pages accepts certificates provided in the [PEM](https://knowledge.digice for public websites for security reasons and to ensure that browsers trust your site's certificate. There are various kinds of certificates, each one -with a certain security level. A static personal website will -not require the same security level as an online banking web app, +with a certain security level. A static personal website doesn't +require the same security level as an online banking web app, for instance. There are some certificate authorities that diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index 6dd431e02b0..e0d5e8be535 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -41,7 +41,7 @@ configuration for the Pages site to generate properly. If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by going to **CI / CD > Pipelines**. +You can watch the pipeline run by navigating to **CI / CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 525bbde4671..b6ab650ca13 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -17,7 +17,7 @@ configured to generate a Pages site. To fork a sample project and create a Pages website: -1. View the sample projects by going to the [GitLab Pages examples](https://gitlab.com/pages) group. +1. View the sample projects by navigating to the [GitLab Pages examples](https://gitlab.com/pages) group. 1. Click the name of the project you want to [fork](../../../../gitlab-basics/fork-project.md). 1. In the top right, click the **Fork** button, and then choose a namespace to fork to. 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**. diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index 230e88f35f5..3f2df634e3a 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a GitLab Pages website from scratch -This tutorial shows you how to create a Pages site from scratch. You will start with +This tutorial shows you how to create a Pages site from scratch. You start with a blank project and create your own CI file, which gives instruction to a [runner](https://docs.gitlab.com/runner/). When your CI/CD [pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created. @@ -218,7 +218,7 @@ There are three default stages for GitLab CI/CD: build, test, and deploy. If you want to test your script and check the built site before deploying -to production, you can run the test exactly as it will run when you +to production, you can run the test exactly as it runs when you push to `master`. To specify a stage for your job to run in, @@ -376,7 +376,7 @@ test: In this case, you need to exclude the `/vendor` directory from the list of folders Jekyll builds. Otherwise, Jekyll -will try to build the directory contents along with the site. +tries to build the directory contents along with the site. In the root directory, create a file called `_config.yml` and add this content: diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index f549c4e6e7d..801fe0c7ef0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -16,7 +16,7 @@ wildcard domain with your sysadmin. This guide is valid for any GitLab instance, replace the Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. If you set up a GitLab Pages project on GitLab, -it will automatically be accessible under a +it's automatically accessible under a subdomain of `namespace.example.io`. The [`namespace`](../../group/index.md#namespaces) is defined by your username on GitLab.com, @@ -45,35 +45,35 @@ To understand Pages domains clearly, read the examples below. - You created a project called `blog` under your username `john`, therefore your project URL is `https://gitlab.com/john/blog/`. Once you enable GitLab Pages for this project, and build your site, - it will be available under `https://john.gitlab.io/blog/`. + you can access it at `https://john.gitlab.io/blog/`. - You created a group for all your websites called `websites`, and a project within this group is called `blog`. Your project URL is `https://gitlab.com/websites/blog/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://websites.gitlab.io/blog/`. - You created a group for your engineering department called `engineering`, a subgroup for all your documentation websites called `docs`, and a project within this subgroup is called `workflows`. Your project URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable - GitLab Pages for this project, the site will live under + GitLab Pages for this project, the site is available at `https://engineering.gitlab.io/docs/workflows`. ### User and Group website examples - Under your username, `john`, you created a project called - `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. + `john.gitlab.io`. Your project URL is `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website - will be published under `https://john.gitlab.io`. + is published under `https://john.gitlab.io`. - Under your group `websites`, you created a project called - `websites.gitlab.io`. your project's URL will be `https://gitlab.com/websites/websites.gitlab.io`. + `websites.gitlab.io`. Your project's URL is `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, - your website will be published under `https://websites.gitlab.io`. + your website is published under `https://websites.gitlab.io`. **General example:** -- On GitLab.com, a project site will always be available under +- On GitLab.com, a project site is always available under `https://namespace.gitlab.io/project-name` -- On GitLab.com, a user or group website will be available under +- On GitLab.com, a user or group website is available under `https://namespace.gitlab.io/` - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. @@ -87,7 +87,7 @@ Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, whenever you publish a project website (`namespace.gitlab.io/project-name`), -you'll have to look for this configuration (base URL) on your SSG's +you must look for this configuration (base URL) on your SSG's documentation and set it up to reflect this pattern. For example, for a Jekyll site, the `baseurl` is defined in the Jekyll @@ -99,11 +99,11 @@ baseurl: "/blog" ``` On the contrary, if you deploy your website after forking one of -our [default examples](https://gitlab.com/pages), the `baseurl` will -already be configured this way, as all examples there are project -websites. If you decide to make yours a user or group website, you'll -have to remove this configuration from your project. For the Jekyll -example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: +our [default examples](https://gitlab.com/pages), the `baseurl` is +already configured this way, as all examples there are project +websites. If you decide to make yours a user or group website, you +must remove this configuration from your project. For the Jekyll +example we just mentioned, you must change Jekyll's `_config.yml` to: ```yaml baseurl: "" diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 846d30e898c..c9e28bf15c2 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -81,10 +81,12 @@ becomes available automatically. To deploy your site, GitLab uses its built-in tool called [GitLab CI/CD](../../../ci/README.md) to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named -`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md) at will. A specific `job` called `pages` in the configuration file will make GitLab aware that you are deploying a GitLab Pages website. +`.gitlab-ci.yml`, which you can [create and modify](getting_started/pages_from_scratch.md). +A specific `job` called `pages` in the configuration file makes GitLab aware that you're deploying a +GitLab Pages website. You can either use the GitLab [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-default-domain-names), -`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll +`*.gitlab.io`, or your own domain (`example.com`). In that case, you need administrator access to your domain's registrar (or control panel) to set it up with Pages. The following diagrams show the workflows you might follow to get started with Pages. @@ -94,15 +96,15 @@ The following diagrams show the workflows you might follow to get started with P ## Access to your Pages site If you're using GitLab Pages default domain (`.gitlab.io`), -your website will be automatically secure and available under +your website is automatically secure and available under HTTPS. If you're using your own custom domain, you can optionally secure it with SSL/TLS certificates. -If you're using GitLab.com, your website will be publicly available to the internet. +If you're using GitLab.com, your website is publicly available to the internet. To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md). If you're using a self-managed instance (Core, Starter, Premium, or Ultimate), -your websites will be published on your own server, according to the +your websites are published on your own server, according to the [Pages settings](../../../administration/pages/index.md) chosen by your sysadmin, who can make them public or internal. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 5a284bf57c3..8380f367212 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -44,19 +44,19 @@ Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete l You can provide your own 403 and 404 error pages by creating the `403.html` and `404.html` files respectively in the root directory of the `public/` directory -that will be included in the artifacts. Usually this is the root directory of +that are included in the artifacts. Usually this is the root directory of your project, but that may differ depending on your static generator configuration. If the case of `404.html`, there are different scenarios. For example: - If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages will try to serve first + `/projectname/non/existing_file`, GitLab Pages tries to serve first `/projectname/404.html`, and then `/404.html`. - If you use user/group Pages (served under `/`) and try to access - `/non/existing_file` GitLab Pages will try to serve `/404.html`. + `/non/existing_file` GitLab Pages tries to serve `/404.html`. - If you use a custom domain and try to access `/non/existing_file`, GitLab - Pages will try to serve only `/404.html`. + Pages tries to serve only `/404.html`. ## Redirects in GitLab Pages @@ -71,8 +71,8 @@ To restrict access to your website, enable [GitLab Pages Access Control](pages_a If you ever feel the need to purge your Pages content, you can do so by going to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Hit the **Remove pages** button and your Pages website -will be deleted. +navigating to **Pages**. Click the **Remove pages** button to delete your Pages +website.  @@ -81,9 +81,9 @@ will be deleted. When using Pages under the general domain of a GitLab instance (`*.example.io`), you _cannot_ use HTTPS with sub-subdomains. That means that if your username or group name contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). HTTP pages will continue to work provided you -don't redirect HTTP to HTTPS. +`https://foo.bar.example.io` does _not_ work. This is a limitation of the +[HTTP Over TLS protocol](https://tools.ietf.org/html/rfc2818#section-3.1). +HTTP pages continue to work provided you don't redirect HTTP to HTTPS. GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). You can only create the highest-level group website. @@ -130,11 +130,11 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch. Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), -whenever a new commit is pushed to a branch that will be used specifically for -your pages. +whenever a new commit is pushed to a branch used specifically for your +pages. That way, you can have your project's code in the `master` branch and use an -orphan branch (let's name it `pages`) that will host your static generator site. +orphan branch (let's name it `pages`) to host your static generator site. You can create a new empty branch like this: @@ -142,9 +142,9 @@ You can create a new empty branch like this: git checkout --orphan pages ``` -The first commit made on this new branch will have no parents and it will be -the root of a new history totally disconnected from all the other branches and -commits. Push the source files of your static generator in the `pages` branch. +The first commit made on this new branch has no parents and is the root of a +new history totally disconnected from all the other branches and commits. +Push the source files of your static generator in the `pages` branch. Below is a copy of `.gitlab-ci.yml` where the most significant line is the last one, specifying to execute everything in the `pages` branch: @@ -172,9 +172,9 @@ also includes `.gitlab-ci.yml`. Most modern browsers support downloading files in a compressed format. This speeds up downloads by reducing the size of files. -Before serving an uncompressed file, Pages will check whether the same file -exists with a `.br` or `.gz` extension. If it does, and the browser supports receiving -compressed files, it will serve that version instead of the uncompressed one. +Before serving an uncompressed file, Pages checks if the same file exists with +a `.br` or `.gz` extension. If it does, and the browser supports receiving +compressed files, it serves that version instead of the uncompressed one. To take advantage of this feature, the artifact you upload to the Pages should have this structure: @@ -236,10 +236,10 @@ public/ ``` Pages supports reaching each of these files through several different URLs. In -particular, it will always look for an `index.html` file if the URL only +particular, it always looks for an `index.html` file if the URL only specifies the directory. If the URL references a file that doesn't exist, but -adding `.html` to the URL leads to a file that *does* exist, it will be served -instead. Here are some examples of what will happen given the above Pages site: +adding `.html` to the URL leads to a file that *does* exist, it's served +instead. Here are some examples of what happens given the above Pages site: | URL path | HTTP response | File served | | -------------------- | ------------- | ----------- | @@ -275,7 +275,7 @@ to private, internal or public. ### Do I need to create a user/group website before creating a project website? -No, you don't. You can create your project first and it will be accessed under +No, you don't. You can create your project first and access it under `http(s)://namespace.example.io/projectname`. ## Known issues diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index f2b75354bf8..86ea19ba512 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -61,7 +61,7 @@ might be slightly different. Follow the ``` Alternatively, you can register without adding an e-mail account, - but you won't be notified about the certificate expiration's date: + but you aren't notified about the certificate expiration's date: ```shell sudo certbot certonly -a manual -d example.com --register-unsafely-without-email @@ -71,10 +71,10 @@ might be slightly different. Follow the Read through CertBot's documentation on their [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). -1. You'll be prompted with a message to agree with their terms. +1. You're prompted with a message to agree with their terms. Press `A` to agree and `Y` to let they log your IP. - CertBot will then prompt you with the following message: + CertBot then prompts you with the following message: ```shell Create a file containing just this data: @@ -88,7 +88,7 @@ might be slightly different. Follow the Press Enter to Continue ``` -1. **Do not press Enter yet.** Let's Encrypt will need to verify your +1. **Do not press Enter yet.** Let's Encrypt needs to verify your domain ownership before issuing the certificate. To do so, create 3 consecutive directories under your website's root: `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` @@ -107,7 +107,7 @@ might be slightly different. Follow the 1. Add, commit, and push the file into your repository in GitLab. Once the pipeline passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot will then prompt you with the following message: + certificate. CertBot then prompts you with the following message: ```shell Waiting for verification... @@ -157,7 +157,7 @@ valid certificates)**. ## Renewal -Let's Encrypt certificates expire every 90 days and you'll have to +Let's Encrypt certificates expire every 90 days and you must renew them periodically. To renew all your certificates at once, run: ```shell diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 9d17277fe9e..a2a17a4f2ca 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -28,20 +28,20 @@ For a demonstration, see [Pages access controls](https://www.youtube.com/watch?v with GitLab Pages, depending on your project's visibility: - If your project is private: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is internal: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone with access**: Everyone logged into GitLab is able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. - If your project is public: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - **Only project members**: Only project members are able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, is able to browse the website, no matter their project membership. 1. Click **Save changes**. The next time someone tries to access your website and the access control is -enabled, they will be presented with a page to sign into GitLab and verify they +enabled, they're presented with a page to sign into GitLab and verify they can access the website. ## Terminating a Pages session diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 7b412270938..06b614f877a 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -274,14 +274,11 @@ Release note descriptions are unrelated. Description supports [Markdown](../../m ### Release assets -You can currently add the following types of assets to each release: +You can add the following types of assets to each release: - [Source code](#source-code) - [Links](#links) -GitLab will support more asset types in the future, including objects such -as pre-built packages, compliance/security evidence, or container images. - #### Permanent links to release assets > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27300) in GitLab 12.9. @@ -336,8 +333,8 @@ The four types of links are "Runbook," "Package," "Image," and "Other." > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. Each time a release is created, GitLab takes a snapshot of data that's related to it. -This data is saved in a JSON file and called *release evidence*. The feature currently -includes test artifacts and linked milestones (and will include issues) to facilitate +This data is saved in a JSON file and called *release evidence*. The feature +includes test artifacts and linked milestones to facilitate internal processes, like external audits. To access the release evidence, on the Releases page, click the link to the JSON file that's listed diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 494f0b725e3..2b37fdb2b91 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -72,7 +72,7 @@ the following table. | Scope | Description | | ------------------ | ----------- | -| `api` | Grants complete read/write access to the scoped project API, including the Package Registry](../../packages/package_registry/index.md). | +| `api` | Grants complete read/write access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_api` | Grants read access to the scoped project API, including the [Package Registry](../../packages/package_registry/index.md). | | `read_registry` | Allows read-access (pull) to [container registry](../../packages/container_registry/index.md) images if a project is private and authorization is required. | | `write_registry` | Allows write-access (push) to [container registry](../../packages/container_registry/index.md). | |