diff options
Diffstat (limited to 'doc/user')
62 files changed, 484 insertions, 580 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index b590dfa0d40..650d60f1585 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -36,12 +36,16 @@ GFM honors the markdown specification in how [paragraphs and line breaks are han A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Line-breaks, or softreturns, are rendered if you end a line with two or more spaces: - Roses are red [followed by two or more spaces] +[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) +[//]: # (They are needed for the Markdown text to render correctly.) + Roses are red [followed by two or more spaces] Violets are blue Sugar is sweet -Roses are red +[//]: # (Do *NOT* remove the two ending whitespaces in the following line.) +[//]: # (They are needed for the Markdown text to render correctly.) +Roses are red Violets are blue Sugar is sweet @@ -226,7 +230,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes. - Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup: + Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: @@ -236,7 +240,7 @@ You can use it to point out a :bug: or warn about :speak_no_evil: patches. And i If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes. -Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup: +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ### Special GitLab References @@ -750,7 +754,7 @@ This line is separated from the one above by two newlines, so it will be a *sepa This line is also a separate paragraph, but... This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. -This line is also a separate paragraph, and... +This line is also a separate paragraph, and... This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) spaces. @@ -763,7 +767,7 @@ This line is separated from the one above by two newlines, so it will be a *sepa This line is also a separate paragraph, but... This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. -This line is also a separate paragraph, and... +This line is also a separate paragraph, and... This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) spaces. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index e7596f5c577..910bd20f882 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,7 +1,7 @@ # Deleting a User Account - As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account** -- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Remove user** +- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Delete user** ## Associated Records diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 50a8e0d5ec5..4ac54f96aa2 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -5,20 +5,23 @@ Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster in a few steps. -With a cluster associated to your project, you can use Review Apps, deploy your -applications, run your pipelines, and much more, in an easy way. +## Overview + +With a Kubernetes cluster associated to your project, you can use +[Review Apps](../../../ci/review_apps/index.md), deploy your applications, run +your pipelines, and much more, in an easy way. There are two options when adding a new cluster to your project; either associate your account with Google Kubernetes Engine (GKE) so that you can [create new clusters](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab, or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster). -## Prerequisites +## Adding and creating a new GKE cluster via GitLab -In order to be able to manage your Kubernetes cluster through GitLab, the -following prerequisites must be met. +NOTE: **Note:** +You need Master [permissions] and above to access the Kubernetes page. -**For a cluster hosted on GKE:** +Before proceeding, make sure the following requirements are met: - The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab at the instance level. If that's not the case, ask your @@ -28,30 +31,16 @@ following prerequisites must be met. account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) must be set up and that you have to have permissions to access it. - You must have Master [permissions] in order to be able to access the - **Cluster** page. + **Kubernetes** page. - You must have [Cloud Billing API](https://cloud.google.com/billing/) enabled - You must have [Resource Manager API](https://cloud.google.com/resource-manager/) -**For an existing Kubernetes cluster:** - -- Since the cluster is already created, there are no prerequisites. - ---- - -If all of the above requirements are met, you can proceed to add a new Kubernetes -cluster. - -## Adding and creating a new GKE cluster via GitLab - -NOTE: **Note:** -You need Master [permissions] and above to access the Clusters page. - -Before proceeding, make sure all [prerequisites](#prerequisites) are met. -To add a new cluster hosted on GKE to your project: +If all of the above requirements are met, you can proceed to create and add a +new Kubernetes cluster that will be hosted on GKE to your project: -1. Navigate to your project's **CI/CD > Clusters** page. -1. Click on **Add cluster**. +1. Navigate to your project's **CI/CD > Kubernetes** page. +1. Click on **Add Kubernetes cluster**. 1. Click on **Create with GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. @@ -66,7 +55,7 @@ To add a new cluster hosted on GKE to your project: - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) of the Virtual Machine instance that the cluster will be based on. - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. -1. Finally, click the **Create cluster** button. +1. Finally, click the **Create Kubernetes cluster** button. After a few moments, your cluster should be created. If something goes wrong, you will be notified. @@ -77,14 +66,14 @@ enable the Cluster integration. ## Adding an existing Kubernetes cluster NOTE: **Note:** -You need Master [permissions] and above to access the Clusters page. +You need Master [permissions] and above to access the Kubernetes page. To add an existing Kubernetes cluster to your project: -1. Navigate to your project's **CI/CD > Clusters** page. -1. Click on **Add cluster**. -1. Click on **Add an existing cluster** and fill in the details: - - **Cluster name** (required) - The name you wish to give the cluster. +1. Navigate to your project's **CI/CD > Kubernetes** page. +1. Click on **Add Kuberntes cluster**. +1. Click on **Add an existing Kubernetes cluster** and fill in the details: + - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - **Environment scope** (required)- The [associated environment](#setting-the-environment-scope) to this cluster. - **API URL** (required) - @@ -112,15 +101,13 @@ To add an existing Kubernetes cluster to your project: - If you or someone created a secret specifically for the project, usually with limited permissions, the secret's namespace and project namespace may be the same. -1. Finally, click the **Create cluster** button. - -The Kubernetes service takes the following parameters: +1. Finally, click the **Create Kuberntes cluster** button. After a few moments, your cluster should be created. If something goes wrong, you will be notified. You can now proceed to install some pre-defined applications and then -enable the Cluster integration. +enable the Kubernetes cluster integration. ## Installing applications @@ -133,13 +120,14 @@ added directly to your configured cluster. Those applications are needed for | [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It will be automatically installed as a dependency when you try to install a different app. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | | [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps](../../../topics/autodevops/index.md) or deploy your own web apps. | | [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications | +| [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. | ## Getting the external IP address NOTE: **Note:** You need a load balancer installed in your cluster in order to obtain the external IP address with the following procedure. It can be deployed using the -**Ingress** application described in the previous section. +[**Ingress** application](#installing-appplications). In order to publish your web application, you first need to find the external IP address associated to your load balancer. @@ -153,7 +141,8 @@ the `gcloud` command in a local terminal or using the **Cloud Shell**. If the cluster is not on GKE, follow the specific instructions for your Kubernetes provider to configure `kubectl` with the right credentials. -If you installed the Ingress using the **Applications** section, run the following command: +If you installed the Ingress [via the **Applications**](#installing-applications), +run the following command: ```bash kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' @@ -171,9 +160,14 @@ your deployed applications. ## Setting the environment scope -When adding more than one clusters, you need to differentiate them with an -environment scope. The environment scope associates clusters and -[environments](../../../ci/environments.md) in an 1:1 relationship similar to how the +NOTE: **Note:** +This is only available for [GitLab Premium][ee] where you can add more than +one Kubernetes cluster. + +When adding more than one Kubernetes clusters to your project, you need to +differentiate them with an environment scope. The environment scope associates +clusters and [environments](../../../ci/environments.md) in an 1:1 relationship +similar to how the [environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-secret-variables) work. @@ -183,7 +177,7 @@ cluster in a project, and a validation error will occur if otherwise. --- -For example, let's say the following clusters exist in a project: +For example, let's say the following Kubernetes clusters exist in a project: | Cluster | Environment scope | | ---------- | ------------------- | @@ -231,8 +225,7 @@ With GitLab Premium, you can associate more than one Kubernetes clusters to your project. That way you can have different clusters for different environments, like dev, staging, production, etc. -To add another cluster, follow the same steps as described in [adding a -Kubernetes cluster](#adding-a-kubernetes-cluster) and make sure to +Simply add another cluster, like you did the first time, and make sure to [set an environment scope](#setting-the-environment-scope) that will differentiate the new cluster with the rest. @@ -240,45 +233,42 @@ differentiate the new cluster with the rest. The Kubernetes cluster integration exposes the following [deployment variables](../../../ci/variables/README.md#deployment-variables) in the -GitLab CI/CD build environment: - -- `KUBE_URL` - Equal to the API URL. -- `KUBE_TOKEN` - The Kubernetes token. -- `KUBE_NAMESPACE` - The Kubernetes namespace is auto-generated if not specified. - The default value is `<project_name>-<project_id>`. You can overwrite it to - use different one if needed, otherwise the `KUBE_NAMESPACE` variable will - receive the default value. -- `KUBE_CA_PEM_FILE` - Only present if a custom CA bundle was specified. Path - to a file containing PEM data. -- `KUBE_CA_PEM` (deprecated) - Only if a custom CA bundle was specified. Raw PEM data. -- `KUBECONFIG` - Path to a file containing `kubeconfig` for this deployment. - CA bundle would be embedded if specified. - -## Enabling or disabling the Cluster integration +GitLab CI/CD build environment. + +| Variable | Description | +| -------- | ----------- | +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token. | +| `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | +| `KUBE_CA_PEM_FILE` | Only present if a custom CA bundle was specified. Path to a file containing PEM data. | +| `KUBE_CA_PEM` | (**deprecated**) Only if a custom CA bundle was specified. Raw PEM data. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. | + +## Enabling or disabling the Kubernetes cluster integration After you have successfully added your cluster information, you can enable the -Cluster integration: +Kubernetes cluster integration: 1. Click the "Enabled/Disabled" switch 1. Hit **Save** for the changes to take effect You can now start using your Kubernetes cluster for your deployments. -To disable the Cluster integration, follow the same procedure. +To disable the Kubernetes cluster integration, follow the same procedure. -## Removing the Cluster integration +## Removing the Kubernetes cluster integration NOTE: **Note:** -You need Master [permissions] and above to remove a cluster integration. +You need Master [permissions] and above to remove a Kubernetes cluster integration. NOTE: **Note:** When you remove a cluster, you only remove its relation to GitLab, not the cluster itself. To remove the cluster, you can do so by visiting the GKE dashboard or using `kubectl`. -To remove the Cluster integration from your project, simply click on the +To remove the Kubernetes cluster integration from your project, simply click on the **Remove integration** button. You will then be able to follow the procedure -and [add a cluster](#adding-a-cluster) again. +and add a Kubernetes cluster again. ## What you can get with the Kubernetes integration diff --git a/doc/user/project/img/label_priority_sort_order.png b/doc/user/project/img/label_priority_sort_order.png Binary files differdeleted file mode 100644 index 21c7a76a322..00000000000 --- a/doc/user/project/img/label_priority_sort_order.png +++ /dev/null diff --git a/doc/user/project/img/labels_assign_label_sidebar.png b/doc/user/project/img/labels_assign_label_sidebar.png Binary files differdeleted file mode 100644 index d74796fdb4d..00000000000 --- a/doc/user/project/img/labels_assign_label_sidebar.png +++ /dev/null diff --git a/doc/user/project/img/labels_assign_label_sidebar_saved.png b/doc/user/project/img/labels_assign_label_sidebar_saved.png Binary files differdeleted file mode 100644 index dabffe956dc..00000000000 --- a/doc/user/project/img/labels_assign_label_sidebar_saved.png +++ /dev/null diff --git a/doc/user/project/img/labels_default.png b/doc/user/project/img/labels_default.png Binary files differindex 7934e3bfb5e..7a7fab611a4 100644 --- a/doc/user/project/img/labels_default.png +++ b/doc/user/project/img/labels_default.png diff --git a/doc/user/project/img/labels_description_tooltip.png b/doc/user/project/img/labels_description_tooltip.png Binary files differdeleted file mode 100644 index eea4f8cf0f4..00000000000 --- a/doc/user/project/img/labels_description_tooltip.png +++ /dev/null diff --git a/doc/user/project/img/labels_filter.png b/doc/user/project/img/labels_filter.png Binary files differdeleted file mode 100644 index 6a1ebfc2ecb..00000000000 --- a/doc/user/project/img/labels_filter.png +++ /dev/null diff --git a/doc/user/project/img/labels_generate.png b/doc/user/project/img/labels_generate.png Binary files differdeleted file mode 100644 index 987f4b5be71..00000000000 --- a/doc/user/project/img/labels_generate.png +++ /dev/null diff --git a/doc/user/project/img/labels_generate_default.png b/doc/user/project/img/labels_generate_default.png Binary files differnew file mode 100644 index 00000000000..fca2a06e04f --- /dev/null +++ b/doc/user/project/img/labels_generate_default.png diff --git a/doc/user/project/img/labels_group_issues.png b/doc/user/project/img/labels_group_issues.png Binary files differnew file mode 100644 index 00000000000..29dcf7ff45e --- /dev/null +++ b/doc/user/project/img/labels_group_issues.png diff --git a/doc/user/project/img/labels_list.png b/doc/user/project/img/labels_list.png Binary files differnew file mode 100644 index 00000000000..12c47ea9766 --- /dev/null +++ b/doc/user/project/img/labels_list.png diff --git a/doc/user/project/img/labels_new_label.png b/doc/user/project/img/labels_new_label.png Binary files differdeleted file mode 100644 index e26425d0188..00000000000 --- a/doc/user/project/img/labels_new_label.png +++ /dev/null diff --git a/doc/user/project/img/labels_new_label_on_the_fly.png b/doc/user/project/img/labels_new_label_on_the_fly.png Binary files differdeleted file mode 100644 index 2ac9805b1ab..00000000000 --- a/doc/user/project/img/labels_new_label_on_the_fly.png +++ /dev/null diff --git a/doc/user/project/img/labels_new_label_on_the_fly_create.png b/doc/user/project/img/labels_new_label_on_the_fly_create.png Binary files differdeleted file mode 100644 index 02ccf68553b..00000000000 --- a/doc/user/project/img/labels_new_label_on_the_fly_create.png +++ /dev/null diff --git a/doc/user/project/img/labels_prioritize.png b/doc/user/project/img/labels_prioritize.png Binary files differdeleted file mode 100644 index d602a3c90ec..00000000000 --- a/doc/user/project/img/labels_prioritize.png +++ /dev/null diff --git a/doc/user/project/img/labels_prioritized.png b/doc/user/project/img/labels_prioritized.png Binary files differnew file mode 100644 index 00000000000..57dcfe89b3d --- /dev/null +++ b/doc/user/project/img/labels_prioritized.png diff --git a/doc/user/project/img/labels_promotion.png b/doc/user/project/img/labels_promotion.png Binary files differnew file mode 100644 index 00000000000..8a5efd210a2 --- /dev/null +++ b/doc/user/project/img/labels_promotion.png diff --git a/doc/user/project/img/labels_sidebar.png b/doc/user/project/img/labels_sidebar.png Binary files differnew file mode 100644 index 00000000000..7349c6d4f0c --- /dev/null +++ b/doc/user/project/img/labels_sidebar.png diff --git a/doc/user/project/img/labels_sidebar_assign.png b/doc/user/project/img/labels_sidebar_assign.png Binary files differnew file mode 100644 index 00000000000..61e8d04fc85 --- /dev/null +++ b/doc/user/project/img/labels_sidebar_assign.png diff --git a/doc/user/project/img/labels_sidebar_inline.png b/doc/user/project/img/labels_sidebar_inline.png Binary files differnew file mode 100644 index 00000000000..31fa397761d --- /dev/null +++ b/doc/user/project/img/labels_sidebar_inline.png diff --git a/doc/user/project/img/labels_sort_label_priority.png b/doc/user/project/img/labels_sort_label_priority.png Binary files differnew file mode 100644 index 00000000000..c8b97639121 --- /dev/null +++ b/doc/user/project/img/labels_sort_label_priority.png diff --git a/doc/user/project/img/labels_sort_priority.png b/doc/user/project/img/labels_sort_priority.png Binary files differnew file mode 100644 index 00000000000..a95198e7f72 --- /dev/null +++ b/doc/user/project/img/labels_sort_priority.png diff --git a/doc/user/project/img/labels_subscribe.png b/doc/user/project/img/labels_subscribe.png Binary files differdeleted file mode 100644 index 56f24ae7bc8..00000000000 --- a/doc/user/project/img/labels_subscribe.png +++ /dev/null diff --git a/doc/user/project/img/labels_subscriptions.png b/doc/user/project/img/labels_subscriptions.png Binary files differnew file mode 100644 index 00000000000..8bcb3b57f6c --- /dev/null +++ b/doc/user/project/img/labels_subscriptions.png diff --git a/doc/user/project/img/new_label_from_sidebar.gif b/doc/user/project/img/new_label_from_sidebar.gif Binary files differnew file mode 100644 index 00000000000..572b29a86e1 --- /dev/null +++ b/doc/user/project/img/new_label_from_sidebar.gif diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index ba2adc1afda..671804035cc 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -11,11 +11,7 @@ in the table below. | `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -Once you have configured and enabled Bugzilla: - -- the **Issues** link on the GitLab project pages takes you to the appropriate - Bugzilla product page -- clicking **New issue** on the project dashboard takes you to Bugzilla for entering a new issue +Once you have configured and enabled Bugzilla you'll see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. ## Referencing issues in Bugzilla diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 757522c2ae3..731291ebe84 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -13,6 +13,8 @@ in the table below. | `issues_url` | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | | `new_issue_url` | Currently unused. Will be changed in a future release. | +Once you have configured and enabled Custom Issue Tracker Service you'll see a link on the GitLab project pages that takes you to that custom issue tracker. + ## Referencing issues diff --git a/doc/user/project/integrations/img/prometheus_dashboard.png b/doc/user/project/integrations/img/prometheus_dashboard.png Binary files differnew file mode 100644 index 00000000000..bd19f1b44cc --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard.png diff --git a/doc/user/project/integrations/img/prometheus_deploy.png b/doc/user/project/integrations/img/prometheus_deploy.png Binary files differnew file mode 100644 index 00000000000..d39081bcc7b --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_deploy.png diff --git a/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png b/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png Binary files differdeleted file mode 100644 index e30cba211e6..00000000000 --- a/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png +++ /dev/null diff --git a/doc/user/project/integrations/img/prometheus_gcp_node_name.png b/doc/user/project/integrations/img/prometheus_gcp_node_name.png Binary files differdeleted file mode 100644 index ea289431454..00000000000 --- a/doc/user/project/integrations/img/prometheus_gcp_node_name.png +++ /dev/null diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index f77569e4886..fc527663db0 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -116,7 +116,7 @@ in the table below. | `Transition ID` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | After saving the configuration, your GitLab project will be able to interact -with all JIRA projects in your JIRA instance. +with all JIRA projects in your JIRA instance and you'll see the JIRA link on the GitLab project pages that takes you to the appropriate JIRA project.  diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 5fefb3b69c4..249463fb86e 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -2,119 +2,69 @@ > [Introduced][ce-8935] in GitLab 9.0. -GitLab offers powerful integration with [Prometheus] for monitoring your apps. -Metrics are retrieved from the configured Prometheus server, and then displayed +GitLab offers powerful integration with [Prometheus] for monitoring key metrics your apps, directly within GitLab. +Metrics for each environment are retrieved from Prometheus, and then displayed within the GitLab interface. -Each project can be configured with its own specific Prometheus server, see the -[configuration](#configuration) section for more details. If you have a single -Prometheus server which monitors all of your infrastructure, you can pre-fill -the settings page with a default template. To configure the template, see the -[Services templates](services_templates.md) document. + -## Requirements +There are two ways to setup Prometheus integration, depending on where your apps are running: +* For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes) +* For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Integration with Prometheus requires the following: - -1. GitLab 9.0 or higher -1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/metrics.md) -1. Each metric must be have a label to indicate the environment -1. GitLab must have network connectivity to the Prometheus server - -## Getting started with Prometheus monitoring +## Managed Prometheus on Kubernetes +> **Note**: [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28916) in GitLab 10.5 -Depending on your deployment and where you have located your GitLab server, there are a few options to get started with Prometheus monitoring. +GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), making monitoring of your apps easy. -* If both GitLab and your applications are installed in the same Kubernetes cluster, you can leverage the [bundled Prometheus server within GitLab](#configuring-omnibus-gitlab-prometheus-to-monitor-kubernetes). -* If your applications are deployed on Kubernetes, but GitLab is not in the same cluster, then you can [configure a Prometheus server in your Kubernetes cluster](#configuring-your-own-prometheus-server-within-kubernetes). -* If your applications are not running in Kubernetes, [get started with Prometheus](#getting-started-with-prometheus-outside-of-kubernetes). - -### Getting started with Prometheus outside of Kubernetes - -Installing and configuring Prometheus to monitor applications is fairly straight forward. - -1. [Install Prometheus](https://prometheus.io/docs/introduction/install/) -1. Set up one of the [supported monitoring targets](prometheus_library/metrics.md) -1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) +### Requirements -### Configuring Omnibus GitLab Prometheus to monitor Kubernetes deployments +* A [connected Kubernetes cluster](../clusters/index.md) +* Helm Tiller [installed by GitLab](../clusters/index.md#installing-applications) -With Omnibus GitLab running inside of Kubernetes, you can leverage the bundled -version of Prometheus to collect the supported metrics. Once enabled, Prometheus will automatically begin monitoring Kubernetes Nodes and any [annotated Pods](https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config>). +### Getting started -1. Read how to configure the bundled Prometheus server in the - [Administration guide][gitlab-prometheus-k8s-monitor]. -1. Now that Prometheus is configured, proceed on - [configuring the Prometheus project service in GitLab](#configuration-in-gitlab). +Once you have a connected Kubernetes cluster with Helm installed, deploying a managed Prometheus is as easy as a single click. -### Configuring your own Prometheus server within Kubernetes +1. Go to the `CI/CD > Kubernetes` page, to view your connected clusters +1. Select the cluster you would like to deploy Prometheus to +1. Click the **Install** button to deploy Prometheus to the cluster -Setting up and configuring Prometheus within Kubernetes is quick and painless. -The Prometheus project provides an [official Docker image][prometheus-docker-image] -which we can use as a starting point. + -To get started quickly, we have provided a [sample YML file][prometheus-yml] -that can be used as a template. This file will create a `prometheus` **Namespace**, -**Service**, **Deployment**, and **ConfigMap** in Kubernetes. You can upload -this file to the Kubernetes dashboard using **+ Create** at the top right. +### About managed Prometheus deployments - +Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -Or use `kubectl`: +The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Ckubernetes_sd_config%3E) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +* `prometheus.io/scrape` to `true` to enable monitoring of the resource. +* `prometheus.io/port` to define the port of the metrics endpoint. +* `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. -```bash -kubectl apply -f path/to/prometheus.yml -``` +CPU and Memory consumption is monitored, but requires [naming conventions](prometheus_library/kubernetes.html#specifying-the-environment) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/), this is handled automatically. -Once deployed, you should see the Prometheus service, deployment, and -pod start within the `prometheus` namespace. The server will begin to collect -metrics from each Kubernetes Node in the cluster, based on the configuration -provided in the template. It will also attempt to collect metrics from any Kubernetes Pods that have been [annotated for Prometheus](https://prometheus.io/docs/operating/configuration/#pod). +The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates. -Since GitLab is not running within Kubernetes, the template provides external -network access via a `NodePort` running on `30090`. This method allows access -to be controlled using provider firewall rules, like within Google Compute Engine. +## Manual configuration of Prometheus -Since a `NodePort` does not automatically have firewall rules created for it, -one will need to be created manually to allow access. In GCP/GKE, you will want -to confirm the Node that the Prometheus pod is running on. This can be done -either by looking at the Pod in the Kubernetes dashboard, or by running: +### Requirements -```bash -kubectl describe pods -n prometheus -``` - -Next on GKE, we need to get the `tag` of the Node or VM Instance, so we can -create an accurate firewall rule. The easiest way to do this is to go into the -Google Cloud Platform Compute console and select the VM instance that matches -the name of the Node gathered from the step above. In this case, the node tag -needed is `gke-prometheus-demo-5d5ada10-node`. Also make a note of the -**External IP**, which will be the IP address the Prometheus server is reachable -on. - - - -Armed with the proper Node tag, the firewall rule can now be created -specifically for this node. To create the firewall rule, open the Google Cloud -Platform Networking console, and select **Firewall Rules**. - -Create a new rule: +Integration with Prometheus requires the following: -- Specify the source IP range to match your desired access list, which should - include your GitLab server. A sample of GitLab.com's IP address range is - available [in this issue][gitlab.com-ip-range], but note that GitLab.com's IPs - are subject to change without prior notification. -- Allowed protocol and port should be `tcp:30090`. -- The target tags should match the Node tag identified earlier in this step. +1. GitLab 9.0 or higher +1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/metrics.md) +1. Each metric must be have a label to indicate the environment +1. GitLab must have network connectivity to the Prometheus server - +### Getting started ---- +Installing and configuring Prometheus to monitor applications is fairly straight forward. -Now that Prometheus is configured, proceed to -[configure the Prometheus project service in GitLab](##configuration-in-gitlab). +1. [Install Prometheus](https://prometheus.io/docs/introduction/install/) +1. Set up one of the [supported monitoring targets](prometheus_library/metrics.md) +1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) -## Configuration in GitLab +### Configuration in GitLab The actual configuration of Prometheus integration within GitLab is very simple. All you will need is the DNS or IP address of the Prometheus server you'd like diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index a6673fa2a00..02adc562028 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -24,9 +24,10 @@ Prometheus server up and running. You have two options here: - If you have an Omnibus based GitLab installation within your Kubernetes cluster, you can leverage the bundled Prometheus server to [monitor Kubernetes](../../../../administration/monitoring/prometheus/index.md#configuring-prometheus-to-monitor-kubernetes). - To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/) or [our guide](../../../../administration/monitoring/prometheus/index.md#configuring-your-own-prometheus-server-within-kubernetes). -## Specifying the Environment label +## Specifying the Environment -In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](metrics.md#identifying-environments). +In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. + +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. If you are using [GitLab Auto-Deploy](../../../../ci/autodeploy/index.md) and one of the two [provided Kubernetes monitoring solutions](../prometheus.md#getting-started-with-prometheus-monitoring), the `environment` label will be automatically added. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index e6f13d0630b..49b34c82ae6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -2,11 +2,11 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438) in GitLab 9.5 -GitLab has support for automatically detecting and monitoring the Kubernetes NGINX ingress controller. This is provided by leveraging the built in Prometheus metrics included in [version 0.9.0](https://github.com/kubernetes/ingress/blob/master/controllers/nginx/Changelog.md#09-beta1) of the ingress. +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX ingress controller. This is provided by leveraging the built in Prometheus metrics included in [version 0.9.0](https://github.com/kubernetes/ingress/blob/master/controllers/nginx/Changelog.md#09-beta1) and above of the ingress. ## Requirements -The [Prometheus service](../prometheus/index.md) must be enabled. +[Prometheus integration](../prometheus/index.md) must be active. ## Metrics supported @@ -18,24 +18,34 @@ The [Prometheus service](../prometheus/index.md) must be enabled. ## Configuring NGINX ingress monitoring -If you have deployed with the [gitlab-omnibus](https://docs.gitlab.com/ee/install/kubernetes/gitlab_omnibus.md) Helm chart, and your application is running in the same cluster, no further action is required. The ingress metrics will be automatically enabled and annotated for Prometheus monitoring. Simply ensure Prometheus monitoring is [enabled for your project](../prometheus.md), which is on by default. +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. -For other deployments, there is some configuration required depending on your installation: -* NGINX Ingress should be version 0.9.0 or above +For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: +* NGINX Ingress should be version 0.9.0 or above, with metrics enabled * NGINX Ingress should be annotated for Prometheus monitoring * Prometheus should be configured to monitor annotated pods -### Setting up NGINX Ingress for Prometheus monitoring +### About managed NGINX Ingress deployments + +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's IP](https://docs.gitlab.com/ce/user/project/clusters/index.html#getting-the-external-ip-address). + +NGINX is configured for Prometheus monitoring, by setting: +* `enable-vts-status: "true"`, to export Prometheus metrics +* `prometheus.io/scrape: "true"`, to enable automatic discovery +* `prometheus.io/port: "10254"`, to specify the metrics port + +When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. + +### Manually setting up NGINX Ingress for Prometheus monitoring Version 0.9.0 and above of [NGINX ingress](https://github.com/kubernetes/ingress/tree/master/controllers/nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. -With metric data now available, Prometheus needs to be configured to collect it. The easiest way to do this is to leverage Prometheus' [built-in Kubernetes service discovery](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config), which automatically detects a variety of Kubernetes components and makes them available for monitoring. Since NGINX ingress metrics are exposed per pod, a scrape job for Kubernetes pods is required. A sample pod scraping configuration [is available](https://github.com/prometheus/prometheus/blob/master/documentation/examples/prometheus-kubernetes.yml#L248). This configuration will detect pods and enable collection of metrics **only if** they have been specifically annotated for monitoring. +Next, the ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: -Depending on how NGINX ingress was deployed, typically a DaemonSet or Deployment, edit the corresponding YML spec. Two new annotations need to be added: * `prometheus.io/scrape: "true"` * `prometheus.io/port: "10254"` -Prometheus should now be collecting NGINX ingress metrics. To validate view the Prometheus Targets, available under `Status > Targets` on the Prometheus dashboard. New entries for NGINX should be listed in the kubernetes pod monitoring job, `kubernetes-pods`. +Managing these settings depends on how NGINX ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible edit the NGINX ingress YML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). ## Specifying the Environment label diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index cc3218fbfd1..de2cf6d4647 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -12,6 +12,8 @@ in the table below. | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + As an example, below is a configuration for a project named gitlab-ci.  diff --git a/doc/user/project/integrations/samples/prometheus.yml b/doc/user/project/integrations/samples/prometheus.yml deleted file mode 100644 index 3a4735d282f..00000000000 --- a/doc/user/project/integrations/samples/prometheus.yml +++ /dev/null @@ -1,107 +0,0 @@ -apiVersion: v1 -kind: Namespace -metadata: - name: prometheus ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: prometheus - namespace: prometheus -data: - prometheus.yml: |- - scrape_configs: - - job_name: 'kubernetes-nodes' - scheme: https - tls_config: - ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt - insecure_skip_verify: true - bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token - kubernetes_sd_configs: - - role: node - metric_relabel_configs: - - source_labels: [pod_name] - target_label: environment - regex: (.+)-.+-.+ - replacement: $1 - - job_name: kubernetes-pods - tls_config: - ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt" - insecure_skip_verify: true - bearer_token_file: "/var/run/secrets/kubernetes.io/serviceaccount/token" - kubernetes_sd_configs: - - role: pod - api_server: https://kubernetes.default.svc:443 - tls_config: - ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt" - bearer_token_file: "/var/run/secrets/kubernetes.io/serviceaccount/token" - relabel_configs: - - source_labels: - - __meta_kubernetes_pod_annotation_prometheus_io_scrape - action: keep - regex: 'true' - - source_labels: - - __meta_kubernetes_pod_annotation_prometheus_io_path - action: replace - target_label: __metrics_path__ - regex: "(.+)" - - source_labels: - - __address__ - - __meta_kubernetes_pod_annotation_prometheus_io_port - action: replace - regex: "([^:]+)(?::[0-9]+)?;([0-9]+)" - replacement: "$1:$2" - target_label: __address__ - - action: labelmap - regex: __meta_kubernetes_pod_label_(.+) - - source_labels: - - __meta_kubernetes_namespace - action: replace - target_label: kubernetes_namespace - - source_labels: - - __meta_kubernetes_pod_name - action: replace - target_label: kubernetes_pod_name ---- -apiVersion: v1 -kind: Service -metadata: - name: prometheus - namespace: prometheus -spec: - selector: - app: prometheus - ports: - - name: prometheus - protocol: TCP - port: 9090 - nodePort: 30090 - type: NodePort ---- -apiVersion: extensions/v1beta1 -kind: Deployment -metadata: - name: prometheus - namespace: prometheus -spec: - replicas: 1 - template: - metadata: - labels: - app: prometheus - spec: - containers: - - name: prometheus - image: prom/prometheus:latest - args: - - '--config.file=/prometheus-data/prometheus.yml' - ports: - - name: prometheus - containerPort: 9090 - volumeMounts: - - name: data-volume - mountPath: /prometheus-data - volumes: - - name: data-volume - configMap: - name: prometheus diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 9af088374a1..1688edc1ee2 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -36,3 +36,25 @@ From an Issue Board, create a new issue by clicking on the plus sign (**+**) on It opens a new issue for that project labeled after its respective list.  + +## New issue via email + +*This feature needs [incoming email](../../../administration/incoming_email.md) +to be configured by a GitLab administrator to be available for CE/EE users, and +it's available on GitLab.com.* + +At the bottom of a project's issue page, click +**Email a new issue to this project**, and you will find an email address +which belongs to you. You could add this address to your contact. + +This is a private email address, generated just for you. +**Keep it to yourself** as anyone who gets ahold of it can create issues or +merge requests as if they were you. You can add this address to your contact +list for easy access. + +Sending an email to this address will create a new issue on your behalf for +this project, where the email subject becomes the issue title, and the email +body becomes the issue description. [Markdown] and [quick actions] are +supported. + + diff --git a/doc/user/project/issues/img/new_issue_from_email.png b/doc/user/project/issues/img/new_issue_from_email.png Binary files differnew file mode 100644 index 00000000000..775ea0cdffb --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_email.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 88acd8edbe2..be4436749f9 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -64,9 +64,7 @@ You can also [search and filter](../../search/index.md#issues-and-merge-requests ### Issues per group -View all the issues in a group (that is, all the issues across all projects in that -group) by navigating to **Group > Issues**. This view also has the open and closed -issue tabs. +View issues in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Issues** to view these issues. This view also has the open and closed issues tabs.  diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index 0bef83d18e8..f2ca6a6822e 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -50,8 +50,8 @@ Often multiple people likely work on the same issue together, which can especially be difficult to track in large teams where there is shared ownership of an issue. -In GitLab Enterprise Edition, you can also select multiple assignees -to an issue. +In [GitLab Starter](https://about.gitlab.com/products/), you can also +select multiple assignees to an issue. Learn more on the [Multiple Assignees documentation](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html). diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index d7eb4bca89c..dabffaec5fa 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -1,174 +1,125 @@ # Labels -Labels provide an easy way to categorize the issues or merge requests based on -descriptive titles like `bug`, `documentation` or any other text you feel like. -They can have different colors, a description, and are visible throughout -the issue tracker or inside each issue individually. +## Overview -With labels, you can navigate the issue tracker and filter any bloated -information to visualize only the issues you are interested in. Let's see how -that works. +Labels allow you to categorize issues or merge requests using descriptive titles like `bug`, `feature request`, or `docs`. Each label also has a customizable color. They allow you to quickly and dynamically filter and manage issues or merge requests you care about, and are visible throughout GitLab in most places where issues and merge requests are located. -## Create new labels +## Project labels and group labels + +In GitLab, you can create project and group labels: + +- **Project labels** can be assigned to issues or merge requests in that project only. +- **Group labels** can be assigned to any issue or merge request of any project in that group. +- In the [future](https://gitlab.com/gitlab-org/gitlab-ce/issues/40915), you will be able to assign group labels to issues and merge reqeusts of projects in [subgroups](../group/subgroups/index.md). + +## Creating labels >**Note:** -A permission level of `Developer` or higher is required in order to manage -labels. +A permission level of `Developer` or higher is required to create labels. -Head over a single project and navigate to **Issues > Labels**. +### New project label -The first time you visit this page, you'll notice that there are no labels -created yet. +To create a **project label**, navigate to **Issues > Labels** in the project. -Creating a new label from scratch is as easy as pressing the **New label** -button. From there on you can choose the name, give it an optional description, -a color and you are set. +Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label. -When you are ready press the **Create label** button to create the new label. +If a project has no labels, you can generate a default set of project labels from its empty label list page: - + ---- +GitLab will add the following default labels to the project: -## Default labels + -The very first time you visit the labels area, it's gonna be empty. In that -case, it's possible to populate the labels for your project from a set of -predefined labels. +### New group label -Click the link to 'Generate a default set of labels' and GitLab will -generate them for you. There are 8 default generated labels in total: +To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there. -- bug -- confirmed -- critical -- discussion -- documentation -- enhancement -- suggestion -- support +Group labels appear in every label list page of the group's child projects. -## Labels Overview + - +### New project label from sidebar -You can see that from the labels page you can have an overview of the number of -issues and merge requests assigned to each label. +From the sidebar of an issue or a merge request, you can create a create a new **project label** inline immediately, instead of navigating to the project label list page. -## Prioritize labels + ->**Notes:** -> -> - Introduced in GitLab 8.9. -> - Priority sorting is based on the highest priority label only. This might -> change in the future, follow the discussion in -> https://gitlab.com/gitlab-org/gitlab-ce/issues/18554. +## Editing labels -Prioritized labels are like any other label, but sorted by priority. This allows -you to sort issues and merge requests by label priority. +NOTE: **Note:** +A permission level of `Developer` or higher is required to edit labels. -To prioritize labels, navigate to your project's **Issues > Labels** and click -on the star icon next to them to put them in the priority list. Click on the -star icon again to remove them from the list. +You can update a label by navigating to **Issues > Labels** in the project or group and clicking the pencil icon. -From there, you can drag them around to set the desired priority. Priority is -set from high to low with an ascending order. Labels with no priority, count as -having their priority set to null. +You can delete a label by clicking the trash icon. - +### Promoting project labels to group labels -Now that you have labels prioritized, you can use the 'Label priority' and 'Priority' -sort orders in the issues or merge requests tracker. +If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same label among multiple projects in the same group. If you previously created a project label and now want to make it available for other projects, you can promote it to a group label. -In the following, everything applies to both issues and merge requests, but we'll -refer to just issues for brevity. +From the project label list page, you can promote a project label to a group label. This will merge all project labels across all projects in this group with the same name into a single group label. All issues and merge requests that previously were assigned one of these project labels will now be assigned the new group label. This action cannot be reversed and the changes are permanent. -The 'Label priority' sort order positions issues with higher priority labels -toward the top, and issues with lower priority labels toward the bottom. A non-prioritized -label is considered to have the lowest priority. For a given issue, we _only_ consider the -highest priority label assigned to it in the comparison. ([We are discussing](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) -including all the labels in a given issue for this comparison.) Given two issues -are equal according to this sort comparison, their relative order is equal, and -therefore it's not guaranteed that one will be always above the other. + - +## Assigning labels from the sidebar -The 'Priority' sort order comparison first considers an issue's milestone's due date, -(if the issue is assigned a milestone and the milestone's due date exists), and then -secondarily considers the label priority comparison above. Sooner due dates results -a higher sort order. If an issue doesn't have a milestone due date, it is equivalent to -being assigned to a milestone that has a due date in the infinite future. Given two issues -are equal according to this two-stage sort comparison, their relative order is equal, and -therefore it's not guaranteed that one will be always above the other. +Every issue and merge request can be assigned any number of labels. The labels are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a label to the object (i.e. label or unlabel it). You can also perform this as a [quick action](quick_actions.md) in a comment. - +| View labels in sidebar | Assign labels from sidebar | +|:---:|:---:| +|  |  | +## Filtering issues and merge requests by label -## Subscribe to labels +### Filtering in list pages -If you don’t want to miss issues or merge requests that are important to you, -simply subscribe to a label. You’ll get notified whenever the label gets added -to an issue or merge request, making sure you don’t miss a thing. +From the project issue list page and the project merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels and project labels. -Go to your project's **Issues > Labels** area, find the label(s) you want to -subscribe to and click on the eye icon. Click again to unsubscribe. +From the group issue list page and the group merge request list page, you can [filter](../search/index.md#issues-and-merge-requests) by both group labels and project labels. - + -If you work on a large or popular project, try subscribing only to the labels -that are relevant to you. You’ll notice it’ll be much easier to focus on what’s -important. +### Filtering in issue boards -## Create a new label when inside an issue +- From [project boards](issue_board.md), you can filter by both group labels and project labels in the [search and filter bar](../search/index.md#issue-boards). -There are times when you are already inside an issue searching to assign a -label, only to realize it doesn't exist. Instead of going to the **Labels** -page and being distracted from your original purpose, you can create new -labels on the fly. +## Subscribing to labels -Expand the issue sidebar and select **Create new label** from the labels dropdown -list. Provide a name, pick a color and hit **Create**. The new label will be -ready to used right away! +From the project label list page and the group label list page, you can subscribe to [notifications](../../workflow/notifications.md) of a given label, to alert you that that label has been assigned to an issue or merge request. - + -## Assigning labels to issues and merge requests +## Label priority -There are generally two ways to assign a label to an issue or merge request. +>**Notes:** +> +> - Introduced in GitLab 8.9. +> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this. -The first one is to assign a label when you first create or edit an issue or -merge request. +Labels can have relative priorities, which are used in the "Label priority" and "Priority" sort orders of the issue and merge request list pages. -The second way is by using the right sidebar when inside an issue or merge -request. Expand it and hit **Edit** in the labels area. Start typing the name -of the label you are looking for to narrow down the list, and select it. You -can add more than one labels at once. When done, click outside the sidebar area -for the changes to take effect. +From the project label list page, star a label to indicate that it has a priority. Drag starred labels up and down to change their priority. Higher means higher priority. Prioritization happens at the project level, only on the project label list page, and not on the group label list page. However, both project and group labels can be prioritized on the project label list page since both types are displayed on the project label list page. - - + ---- +On the project and group issue and merge request list pages, you can sort by `Label priority` and `Priority`, which account for objects (issues and merge requests) that have prioritized labels assigned to them. -To remove labels, expand the left sidebar and unmark them from the labels list. -Simple as that. +If you sort by `Label priority`, GitLab considers this sort comparison order: -## Use labels to filter issues +- Object with a higher priority prioritized label. +- Object without a prioritized label. -Once you start adding labels to your issues, you'll see the benefit of it. -Labels can have several uses, one of them being the quick filtering of issues -or merge requests. +Ties are broken arbitrarily. (Note that we _only_ consider the highest prioritized label in an object, and not any of the lower prioritized labels. [This discussion](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) considers changing this.) -Pick an existing label from the dropdown _Label_ menu or click on an existing -label from the issue tracker. In the latter case, you also get to see the -label description like shown below. + - +If you sort by `Priority`, GitLab considers this sort comparison order: ---- +- Object's assigned [milestone](milestones/index.md)'s due date is sooner, provided the object has a milestone and the milestone has a due date. If this isn't the case, consider the object having a due date in the infinite future. +- Object with a higher priority prioritized label. +- Object without a prioritized label. -And if you added a description to your label, you can see it by hovering your -mouse over the label in the issue tracker or wherever else the label is -rendered. +Ties are broken arbitrarily. - + diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index aa3266cb457..d3220598933 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -34,7 +34,7 @@ With **[GitLab Enterprise Edition][ee]**, you can also: - View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) (available only in GitLab Premium) - Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers (available in GitLab Starter) - [Squash and merge](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html) for a cleaner commit history (available in GitLab Starter) -- Analise the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) (available in GitLab Starter) +- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) (available in GitLab Starter) ## Use cases @@ -70,9 +70,9 @@ and you can use the tabs available to quickly filter by open and closed. You can ## Merge requests per group -View all the merge requests in a group (that is, all the merge requests across all projects in that -group) by navigating to **Group > Merge Requests**. This view also has the open, merged, and closed -merge request tabs, from which you can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group). +View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. + +You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here.  @@ -134,6 +134,10 @@ those conflicts in the GitLab UI. ## Create new merge requests by email +*This feature needs [incoming email](../../../administration/incoming_email.md) +to be configured by a GitLab administrator to be available for CE/EE users, and +it's available on GitLab.com.* + You can create a new merge request by sending an email to a user-specific email address. The address can be obtained on the merge requests page by clicking on a **Email a new merge request to this project** button. The subject will be @@ -146,6 +150,19 @@ administrator to do so.  +## Find the merge request that introduced a change + +> **Note**: this feature was [implemented in GitLab 10.5](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383). + +When viewing the commit details page, GitLab will link to the merge request (or +merge requests, if it's in more than one) containing that commit. + +This only applies to commits that are in the most recent version of a merge +request - if a commit was in a merge request, then rebased out of that merge +request, they will not be linked. + +[Read more about merge request versions](versions.md) + ## Revert changes GitLab implements Git's powerful feature to revert any commit with introducing @@ -160,7 +177,7 @@ of merge request diff is created. When you visit a merge request that contains more than one pushes, you can select and compare the versions of those merge request diffs. -[Read more about the merge requests versions.](versions.md) +[Read more about merge request versions](versions.md) ## Work In Progress merge requests diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 546c8bdc5e5..f01da06fa6e 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -7,7 +7,8 @@ have been marked a **Work In Progress**.  To mark a merge request a Work In Progress, simply start its title with `[WIP]` -or `WIP:`. +or `WIP:`. As an alternative, you're also able to do it by sending a commit +with its title starting with `wip` or `WIP` to the merge request's source branch.  diff --git a/doc/user/project/milestones/img/milestone_create.png b/doc/user/project/milestones/img/milestone_create.png Binary files differdeleted file mode 100644 index beb2caa897f..00000000000 --- a/doc/user/project/milestones/img/milestone_create.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestone_group_create.png b/doc/user/project/milestones/img/milestone_group_create.png Binary files differdeleted file mode 100644 index 7aaa7c56c15..00000000000 --- a/doc/user/project/milestones/img/milestone_group_create.png +++ /dev/null diff --git a/doc/user/project/milestones/img/milestones_new_group_milestone.png b/doc/user/project/milestones/img/milestones_new_group_milestone.png Binary files differnew file mode 100644 index 00000000000..8780394d72e --- /dev/null +++ b/doc/user/project/milestones/img/milestones_new_group_milestone.png diff --git a/doc/user/project/milestones/img/milestones_new_project_milestone.png b/doc/user/project/milestones/img/milestones_new_project_milestone.png Binary files differnew file mode 100644 index 00000000000..ba058428dfa --- /dev/null +++ b/doc/user/project/milestones/img/milestones_new_project_milestone.png diff --git a/doc/user/project/milestones/img/milestones_project_milestone_page.png b/doc/user/project/milestones/img/milestones_project_milestone_page.png Binary files differnew file mode 100644 index 00000000000..9717075b8d0 --- /dev/null +++ b/doc/user/project/milestones/img/milestones_project_milestone_page.png diff --git a/doc/user/project/milestones/img/milestones_promote_milestone.png b/doc/user/project/milestones/img/milestones_promote_milestone.png Binary files differnew file mode 100644 index 00000000000..99bee1240d4 --- /dev/null +++ b/doc/user/project/milestones/img/milestones_promote_milestone.png diff --git a/doc/user/project/milestones/img/sidebar.png b/doc/user/project/milestones/img/sidebar.png Binary files differdeleted file mode 100644 index 274962a936c..00000000000 --- a/doc/user/project/milestones/img/sidebar.png +++ /dev/null diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 27832b0fa2b..10e6321eb82 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -1,63 +1,111 @@ # Milestones -Milestones allow you to organize issues and merge requests into a cohesive group, -optionally setting a due date. A common use is keeping track of an upcoming -software version. Milestones can be created per-project or per-group. +## Overview -## Creating a project milestone +Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. + +Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. + +## Project milestones and group milestones + +- **Project milestones** can be assigned to issues or merge requests in that project only. +- **Group milestones** can be assigned to any issue or merge request of any project in that group. +- In the [future](https://gitlab.com/gitlab-org/gitlab-ce/issues/36862), you will be able to assign group milestones to issues and merge reqeusts of projects in [subgroups](../../group/subgroups/index.md). + +## Creating milestones + +>**Note:** +A permission level of `Developer` or higher is required to create milestones. + +### New project milestone + +To create a **project milestone**, navigate to **Issues > Milestones** in the project. + +Click the **New milestone** button. Enter the title, an optional description, an optional start date, and an optional due date. Click **Create milestone** to create the milestone. + + + +### New group milestone + +To create a **group milestone**, follow similar steps from above to project milestones. Navigate to **Issues > Milestones** in the group and create it from there. + + + +## Editing milestones >**Note:** -You need [Master permissions](../../permissions.md) in order to create a milestone. +A permission level of `Developer` or higher is required to edit milestones. + +You can update a milestone by navigating to **Issues > Milestones** in the project or group and clicking the **Edit** button. -You can find the milestones page under your project's **Issues ➔ Milestones**. -To create a new milestone, simply click the **New milestone** button when in the -milestones page. A milestone can have a title, a description and start/due dates. -Once you fill in all the details, hit the **Create milestone** button. +You can delete a milestone by clicking the **Delete** button. - +### Promoting project milestones to group milestones -## Creating a group milestone +If you are expanding from a few projects to a larger number of projects within the same group, you may want to share the same milestone among multiple projects in the same group. If you previously created a project milestone and now want to make it available for other milestones, you can promote it to a group milestone. + +From the project milestone list page, you can promote a project milestone to a group milestone. This will merge all project milestones across all projects in this group with the same name into a single group milestones. All issues and merge requests that previously were assigned one of these project milestones will now be assigned the new group milestones. This action cannot be reversed and the changes are permanent. >**Note:** -You need [Master permissions](../../permissions.md) in order to create a milestone. +Not all features on the project milestone view are available on the group milestone view. If you promote a project milestone to a group milestone, you will lose these features. See [Milestone view](#milestone-view) to see which features are missing from the group milestone view. + + + +## Assigning milestones from the sidebar + +Every issue and merge request can be assigned a milestone. The milestones are visible on every issue and merge request page, in the sidebar. They are also visible in the issue board. From the sidebar, you can assign or unassign a milestones to the object. You can also perform this as a [quick action](../quick_actions.md) in a comment. [As mentioned](#project-milestones-and-group-milestones), for a given issue or merge request, both project milestones and group milestones can be selected and assigned to the object. + +## Filtering issues and merge requests by milestone + +### Filtering in list pages + +From the project issue/merge request list pages and the group issue/merge request list pages, you can [filter](../../search/index.md#issues-and-merge-requests) by both group milestones and project milestones. + +### Filtering in issue boards + +From [project issue boards](../issue_board.md), you can filter by both group milestones and project milestones in the [search and filter bar](../../search/index.md#issue-boards). + +### Special milestone filters + +When filtering by milestone, in addition to choosing a specific project milestone or group milestone, you can choose a special milestone filter. -You can create a milestone for a group that will be shared across group projects. -On the group's **Issues ➔ Milestones** page, you will be able to see the state -of that milestone and the issues/merge requests count that it shares across the group projects. To create a new milestone click the **New milestone** button. The form is the same as when creating a milestone for a specific project which you can find in the previous item. +- **No Milestone**: Show issues or merge requests with no assigned milestone. +- **Upcoming**: Show issues or merge requests that have been assigned the open milestone that has the next upcoming due date (i.e. nearest due date in the future). +- **Started**: Show issues or merge requests that have an assigned milestone with a start date that is before today. -In addition to that you will be able to filter issues or merge requests by group milestones in all projects that belongs to the milestone group. +## Milestone view -## Milestone promotion +Not all features in the project milestone view are available in the group milestone view. This table summarizes the differences: -Project milestones can be promoted to group milestones if its project belongs to a group. When a milestone is promoted all other milestones across the group projects with the same title will be merged into it, which means all milestone's children like issues, merge requests and boards will be moved into the new promoted milestone. -The promote button can be found in the milestone view or milestones list. +| Feature | Project milestone view | Group milestone view | +|---|:---:|:---:| +| Title an description | ✓ | ✓ | +| Issues assigned to milestone | ✓ | | +| Merge requests assigned to milestone | ✓ | | +| Participants and labels used | ✓ | | +| Percentage complete | ✓ | ✓ | +| Start date and due date | ✓ | ✓ | +| Total issue time spent | ✓ | ✓ | +| Total issue weight | ✓ | | -## Special milestone filters +The milestone view shows the title and description. -In addition to the milestones that exist in the project or group, there are some -special options available when filtering by milestone: +### Project milestone features -* **No Milestone** - only show issues or merge requests without a milestone. -* **Upcoming** - show issues or merge request that belong to the next open - milestone with a due date, by project. (For example: if project A has - milestone v1 due in three days, and project B has milestone v2 due in a week, - then this will show issues or merge requests from milestone v1 in project A - and milestone v2 in project B.) -* **Started** - show issues or merge requests from any milestone with a start - date less than today. Note that this can return results from several - milestones in the same project. +These features are only available for project milestones and not group milestones. -## Milestone sidebar +- Issues assigned to the milestone are displayed in three columns: Unstarted issues, ongoing issues, and completed issues. +- Merge requests assigned to the milestone are displayed in four columns: Work in progress merge requests, waiting for merge, rejected, and closed. +- Participants and labels that are used in issues and merge requests that have the milestone assigned are displayed. -The milestone sidebar shows percentage complete, start date and due date, -issues, total issue weight, total issue time spent, and merge requests. +### Milestone sidebar -The percentage complete is calculated as: Closed and merged merge requests plus all closed issues divided by -total merge requests and issues. +The milestone sidebar on the milestone view shows the following: - +- Percentage complete, which is calculated as number of closed issues plus number of closed/merged merge requests divided by total number issues and merge requests. +- The start date and due date. +- The total time spent on all issues that have the milestone assigned. -## Quick actions +For project milestones only, the milestone sidebar shows the total issue weight of all issues that have the milestone assigned. -[Quick actions](../quick_actions.md) are available for assigning and removing -project and group milestones. + diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index bd0cb437924..e4ee2f7cdfa 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,16 +1,13 @@ -# GitLab Pages from A to Z: Part 4 +--- +last_updated: 2018-02-16 +author: Marcia Ramos +author_gitlab: marcia +level: intermediate +article_type: user guide +date: 2017-02-22 +--- -> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || -> **Level**: intermediate || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || -> **Publication date:** 2017/02/22 - -- [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) -- [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) -- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) -- **Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages** - -## Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages +# Creating and Tweaking GitLab CI/CD for GitLab Pages [GitLab CI](https://about.gitlab.com/gitlab-ci/) serves numerous purposes, to build, test, and deploy your app @@ -19,10 +16,13 @@ from GitLab through methods. You will need it to build your website with GitLab Pages, and deploy it to the Pages server. +To implement GitLab CI/CD, the first thing we need is a configuration +file called `.gitlab-ci.yml` placed at your website's root directory. + What this file actually does is telling the [GitLab Runner](https://docs.gitlab.com/runner/) to run scripts as you would do from the command line. The Runner acts as your -terminal. GitLab CI tells the Runner which commands to run. +terminal. GitLab CI/CD tells the Runner which commands to run. Both are built-in in GitLab, and you don't need to set up anything for them to work. @@ -34,7 +34,7 @@ need to understand just a few things to be able to write our own with its own syntax. You can always check your CI syntax with the [GitLab CI Lint Tool](https://gitlab.com/ci/lint). -**Practical Example:** +## Practical example Let's consider you have a [Jekyll](https://jekyllrb.com/) site. To build it locally, you would open your terminal, and run `jekyll build`. @@ -384,7 +384,3 @@ in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the [pulling specific directories from different projects](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) to deploy this website you're looking at, docs.gitlab.com. - On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). - -||| -|:--|--:| -|[**← Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**](getting_started_part_three.md)|| diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 1e19f422d94..290dfa5af84 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,31 +1,28 @@ -# GitLab Pages from A to Z: Part 1 - -> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || -> **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || -> **Publication date:** 2017/02/22 - -- **Part 1: Static sites and GitLab Pages domains** -- [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) -- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) -- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md) - -## GitLab Pages from A to Z - -This is a comprehensive guide, made for those who want to +--- +last_updated: 2018-02-16 +author: Marcia Ramos +author_gitlab: marcia +level: beginner +article_type: user guide +date: 2017-02-22 +--- + +# Static sites and GitLab Pages domains + +This document is the beginning of a comprehensive guide, made for those who want to publish a website with GitLab Pages but aren't familiar with the entire process involved. -This [first part](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of +This [first document](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of static sites, and go over how the default Pages domains work. -The [second part](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy +The [second document](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy a website from a forked project or create a new one from scratch. -The [third part](getting_started_part_three.md) will show you how to set up a custom domain or subdomain +The [third document](getting_started_part_three.md) will show you how to set up a custom domain or subdomain to your site already deployed. -The [fourth part](getting_started_part_four.md) will show you how to create and tweak GitLab CI for +The [fourth document](getting_started_part_four.md) will show you how to create and tweak GitLab CI for GitLab Pages. To **enable** GitLab Pages for GitLab CE (Community Edition) @@ -113,6 +110,4 @@ You can only create the highest level group website. - On your GitLab instance, replace `gitlab.io` above with your Pages server domain. Ask your sysadmin for this information. -||| -|:--|--:| -||[**Part 2: Quick start guide - Setting up GitLab Pages →**](getting_started_part_two.md)| +_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 0096f8507d2..430fe3af1f8 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,27 +1,19 @@ --- -last_updated: 2017-09-28 +last_updated: 2018-02-16 +author: Marcia Ramos +author_gitlab: marcia +level: beginner +article_type: user guide +date: 2017-02-22 --- -# GitLab Pages from A to Z: Part 3 +# GitLab Pages custom domains and SSL/TLS Certificates -> **[Article Type](../../../development/writing_documentation.md#types-of-technical-articles)**: user guide || -> **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || -> **Publication date:** 2017-02-22 || -> **Last updated**: 2017-09-28 - -- [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) -- [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) -- **Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates** -- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md) - -## Setting Up Custom Domains - DNS Records and SSL/TLS Certificates - -As described in the previous part of this series, setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. +Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. These steps assume you've already [set your site up](getting_started_part_two.md) and and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`. -### Adding your custom domain to GitLab Pages +## Adding your custom domain to GitLab Pages To use one or more custom domain with your Pages site, there are two things you should consider first, which we'll cover in this guide: @@ -36,7 +28,7 @@ Let's start from the beginning with [DNS records](#dns-records). If you already know how they work and want to skip the introduction to DNS, you may be interested in skipping it until the [TL;DR](#tl-dr) section below. -### DNS Records +## DNS Records A Domain Name System (DNS) web service routes visitors to websites by translating domain names (such as `www.example.com`) into the @@ -70,9 +62,9 @@ for the most popular hosting services: - [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx) If your hosting service is not listed above, you can just try to -search the web for "how to add dns record on <my hosting service>". +search the web for `how to add dns record on <my hosting service>`. -#### DNS A record +### DNS A record In case you want to point a root domain (`example.com`) to your GitLab Pages site, deployed to `namespace.gitlab.io`, you need to @@ -87,7 +79,7 @@ running on your instance).  -#### DNS CNAME record +### DNS CNAME record In case you want to point a subdomain (`hello-world.example.com`) to your GitLab Pages site initially deployed to `namespace.gitlab.io`, @@ -103,12 +95,32 @@ without any `/project-name`.  +#### DNS TXT record + +Unless your GitLab administrator has [disabled custom domain verification](../../../administration/pages/index.md#custom-domain-verification), +you'll have to prove that you own the domain by creating a `TXT` record +containing a verification code. The code will be displayed after you +[add your custom domain to GitLab Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). + +If using a [DNS A record](#dns-a-record), you can place the TXT record directly +under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't +co-exist, so you need to place the TXT record in a special subdomain of its own. + #### TL;DR +If the domain has multiple uses (e.g., you host email on it as well): + | From | DNS Record | To | | ---- | ---------- | -- | | domain.com | A | 52.167.214.135 | -| subdomain.domain.com | CNAME | namespace.gitlab.io | +| domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +If the domain is dedicated to GitLab Pages use and no other services run on it: + +| From | DNS Record | To | +| ---- | ---------- | -- | +| subdomain.domain.com | CNAME | gitlab.io | +| _gitlab-pages-verification-code.subdomain.domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | > **Notes**: > @@ -119,7 +131,7 @@ domain. E.g., **do not** point your `subdomain.domain.com` to `namespace.gitlab.io.` or `namespace.gitlab.io/`. > - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) from `104.208.235.32` to `52.167.214.135`. -### Add your custom domain to GitLab Pages settings +## Add your custom domain to GitLab Pages settings Once you've set the DNS record, you'll need navigate to your project's **Setting > Pages** and click **+ New domain** to add your custom domain to @@ -129,6 +141,17 @@ your site will be accessible only via HTTP:  +Once you have added a new domain, you will need to **verify your ownership** +(unless the GitLab administrator has disabled this feature). A verification code +will be shown to you; add it as a [DNS TXT record](#dns-txt-record), then press +the "Verify ownership" button to activate your new domain: + + + +Once your domain has been verified, leave the verification record in place - +your domain will be periodically reverified, and may be disabled if the record +is removed. + 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. @@ -136,13 +159,13 @@ All the aliases you've set to your site will be listed on **Setting > Pages**. From that page, you can view, add, and remove them. Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), -although it's usually a matter of minutes to complete. Until it does, visit attempts -to your domain will respond with a 404. +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. Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more about adding custom domains to GitLab Pages sites. -### SSL/TLS Certificates +## SSL/TLS Certificates Every GitLab Pages project on GitLab.com will be available under HTTPS for the default Pages domain (`*.gitlab.io`). Once you set @@ -155,16 +178,41 @@ Certificates are NOT required to add to your custom (sub)domain on your GitLab Pages project, though they are highly recommendable. -The importance of having any website securely served under HTTPS -is explained on the introductory section of the blog post -[Secure GitLab Pages with StartSSL](https://about.gitlab.com/2016/06/24/secure-gitlab-pages-with-startssl/#https-a-quick-overview). +Let's start with an introduction to the importance of HTTPS. +Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-your-project). + +### Why should I care about HTTPS? + +This might be your first question. If our sites are hosted by GitLab Pages, +they are static, hence we are not dealing with server-side scripts +nor credit card transactions, then why do we need secure connections? -The reason why certificates are so important is that they encrypt +Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +security measure, necessary just for big companies, like banks and shoppings sites +with financial transactions. +Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): + +> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](http://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ + +Therefore, the reason why certificates are so important is that they encrypt the connection between the **client** (you, me, your visitors) and the **server** (where you site lives), through a keychain of authentications and validations. -### Issuing Certificates +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 +[supports the cause](https://w3ctag.github.io/web-https/) and explains very well +the reasons for that. Richard Barnes, a writer for Mozilla Security Blog, +suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/), +and would no longer accept unsecured connections. Recently, Mozilla published a +[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/) +reiterating the importance of HTTPS. + +## Issuing Certificates GitLab Pages accepts [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) certificates issued by [Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority) @@ -193,7 +241,7 @@ Their certs are valid up to 15 years. Read through the tutorial on Regardless the CA you choose, the steps to add your certificate to your Pages project are the same. -#### What do you need +### What do you need 1. A PEM certificate 1. An intermediate certificate @@ -203,7 +251,7 @@ your Pages project are the same. These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**. -#### What's what? +### What's what? - A PEM certificate is the certificate generated by the CA, which needs to be added to the field **Certificate (PEM)**. @@ -216,7 +264,7 @@ are one of these cases. - A public key is an encrypted key which validates your PEM against your domain. -#### Now what? +### Now what? Now that you hopefully understand why you need all of this, it's simple: @@ -233,6 +281,4 @@ just jumping a line between them. regular text editors. Always use code editors (such as Sublime Text, Atom, Dreamweaver, Brackets, etc). -||| -|:--|--:| -|[**← Part 2: Quick start guide - Setting up GitLab Pages**](getting_started_part_two.md)|[**Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages →**](getting_started_part_four.md)| +_Read on about [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md)_ diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 4a724dd5c1b..2274cac8ace 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,27 +1,23 @@ -# GitLab Pages from A to Z: Part 2 +--- +last_updated: 2018-02-16 +author: Marcia Ramos +author_gitlab: marcia +level: beginner +article_type: user guide +date: 2017-02-22 +--- -> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || -> **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || -> **Publication date:** 2017/02/22 - -- [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) -- **Part 2: Quick start guide - Setting up GitLab Pages** -- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) -- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md) - -## Setting up GitLab Pages - -For a complete step-by-step tutorial, please read the -blog post [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). The following sections will explain -what do you need and why do you need them. +# Projects for GitLab Pages and URL structure ## What you need to get started +To get started with GitLab Pages, you need: + 1. A project 1. A configuration file (`.gitlab-ci.yml`) to deploy your site 1. A specific `job` called `pages` in the configuration file that will make GitLab aware that you are deploying a GitLab Pages website +1. A `public` directory with the content of the website Optional Features: @@ -51,35 +47,26 @@ containing the most popular SSGs templates. Watch the [video tutorial](https://youtu.be/TWqh9MtT4Bg) we've created for the steps below. -1. Choose your SSG template -1. Fork a project from the [Pages group](https://gitlab.com/pages) -1. Remove the fork relationship by navigating to your **Project**'s **Settings** > **Edit Project** +1. [Fork a sample project](../../../gitlab-basics/fork-project.md) from the [Pages group](https://gitlab.com/pages) +1. Trigger a build (push a change to any file) +1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your project's **Settings** > **Pages** +1. Optionally, remove the fork relationship by navigating to your project's **Settings** > expanding **Advanced settings** and scrolling down to **Remove fork relashionship**:  -1. Enable Shared Runners for your fork: navigate to your **Project**'s **Settings** > **Pipelines** -1. Trigger a build (push a change to any file) -1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your **Project**'s **Settings** > **Pages** - To turn a **project website** forked from the Pages group into a **user/group** website, you'll need to: -- Rename it to `namespace.gitlab.io`: navigate to **Project**'s **Settings** > **Edit Project** > **Rename repository** +- Rename it to `namespace.gitlab.io`: navigate to project's **Settings** > expand **Advanced settings** > and scroll down to **Rename repository** - Adjust your SSG's [base URL](#urls-and-baseurls) to from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likelly, it will be in the SSG's config file. > **Notes:** > ->1. Why do I need to remove the fork relationship? +> Why do I need to remove the fork relationship? > -> Unless you want to contribute to the original project, +> Unless you want to contribute to the original project, you won't need it connected to the upstream. A [fork](https://about.gitlab.com/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/#fork) is useful for submitting merge requests to the upstream. -> -> 2. Why do I need to enable Shared Runners? -> -> Shared Runners will run the script set by your GitLab CI/CD -configuration file. They're enabled by default to new projects, -but not to forks. ### Create a project from scratch @@ -108,7 +95,7 @@ where you'll find its default URL. > - GitLab Pages [supports any SSG](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but, if you don't find yours among the templates, you'll need to configure your own `.gitlab-ci.yml`. Do do that, please -read through the article [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among +read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among the [example projects](https://gitlab.com/pages). If you set up a new one, please [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md) @@ -121,7 +108,7 @@ you can run `git init` in your local website directory, add the remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, then add, commit, and push. -### URLs and Baseurls +## URLs and Baseurls Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not @@ -149,11 +136,7 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to: baseurl: "" ``` -### Custom Domains +## Custom Domains -GitLab Pages supports custom domains and subdomains, served under HTTPS or HTTPS. +GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. Please check the [next part](getting_started_part_three.md) of this series for an overview. - -||| -|:--|--:| -|[**← Part 1: Static sites, domains, DNS records, and SSL/TLS certificates**](getting_started_part_one.md)|[**Setting Up Custom Domains - DNS Records and SSL/TLS Certificates →**](getting_started_part_three.md)| diff --git a/doc/user/project/pages/img/verify_your_domain.png b/doc/user/project/pages/img/verify_your_domain.png Binary files differnew file mode 100644 index 00000000000..89c69cac9a5 --- /dev/null +++ b/doc/user/project/pages/img/verify_your_domain.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 8404d789de6..a65aa758198 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -37,10 +37,10 @@ to secure them. Read the following tutorials to know more about: -- [Static websites and GitLab Pages domains](getting_started_part_one.md) -- [Forking projects and creating new ones from scratch, URLs and baseurls](getting_started_part_two.md) -- [Custom domains and subdomains, DNS records, SSL/TLS certificates](getting_started_part_three.md) -- [How to create your own `.gitlab-ci.yml` for your site](getting_started_part_four.md) +- [Static websites and GitLab Pages domains](getting_started_part_one.md): Understand what is a static website, and how GitLab Pages default domains work +- [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls +- [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records, and SSL/TLS certificates +- [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site - [Technical aspects, custom 404 pages, limitations](introduction.md) - [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) (outdated) @@ -54,7 +54,6 @@ _Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_ - [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) - [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (outdated) -- [StartSSL](https://about.gitlab.com/2016/06/24/secure-gitlab-pages-with-startssl/) (deprecated) ## Advanced use diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index ce081cedd71..e6aede7f46e 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -18,7 +18,7 @@ documentation. > **Important:** For security reasons, when using the command line, we strongly recommend -you to [connect with GitLab via SSH](../../../ssh/README.md). +that you [connect with GitLab via SSH](../../../ssh/README.md). ## Files @@ -66,8 +66,7 @@ your implementation with your team. You can live preview changes submitted to a new branch with [Review Apps](../../../ci/review_apps/index.md). -With [GitLab Enterprise Edition](https://about.gitlab.com/products/) -subscriptions, you can also request +With [GitLab Starter](https://about.gitlab.com/products/), you can also request [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers. To create, delete, and [branches](branches/index.md) via GitLab's UI: diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index b8f865679a2..dedf102fc37 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -22,6 +22,7 @@ > in the import side is required to map the users, based on email or username. > Otherwise, a supplementary comment is left to mention the original author and > the MRs, notes or issues will be owned by the importer. +> - Control project Import/Export with the [API](../../../api/project_import_export.md). Existing projects running on any GitLab instance or GitLab.com can be exported with all their related data and be moved into a new GitLab instance. |
