diff options
| author | Rémy Coutable <remy@rymai.me> | 2018-12-04 16:39:35 +0300 |
|---|---|---|
| committer | Rémy Coutable <remy@rymai.me> | 2018-12-04 16:39:35 +0300 |
| commit | 4bcec7439b6228af84a902d4a7d1a3ad9d3b24c5 (patch) | |
| tree | e56f967952045b119de78cc30d04c7d4528a9af0 /doc | |
| parent | 8c94d245db71105f299622b31ff4192400fe8ffa (diff) | |
| parent | 77f215b3f4feaab49f9d10975554b8c866e865f9 (diff) | |
Merge branch 'master' into 'patch-28'
# Conflicts:
# doc/development/i18n/proofreader.md
Diffstat (limited to 'doc')
467 files changed, 11445 insertions, 6784 deletions
diff --git a/doc/README.md b/doc/README.md index 4248f62c08c..b15c3a63d92 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,137 +3,227 @@ comments: false description: 'Learn how to use and administer GitLab, the most scalable Git-based fully integrated platform for software development.' --- +<div class="display-none"> + <em>Visit <a href="https://docs.gitlab.com/ce/">docs.gitlab.com</a> for optimized + navigation, discoverability, and readability.</em> +</div> +<!-- the div above will not display on the docs site but will display on /help --> + # GitLab Documentation -Welcome to [GitLab](https://about.gitlab.com/), a Git-based fully featured -platform for software development! +Welcome to [GitLab](https://about.gitlab.com/) Documentation. + +Here you can access the complete documentation for GitLab, the single application for the +[entire DevOps lifecycle](#the-entire-devops-lifecycle). + +## Overview + +No matter how you use GitLab, we have documentation for you. + +| Essential Documentation | Essential Documentation | +|:-------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| +| [**User Documentation**](user/index.md)<br/>Discover features and concepts for GitLab users. | [**Administrator documentation**](administration/index.md)<br/>Everything GitLab self-managed administrators need to know. | +| [**Contributing to GitLab**](#contributing-to-gitlab)<br/>At GitLab, everyone can contribute! | [**New to Git and GitLab?**](#new-to-git-and-gitlab)<br/>We have resources to get you started. | +| [**Building an integration with GitLab?**](#building-an-integration-with-gitlab)<br/>Consult our automation and integration documentation. | [**Coming to GitLab from another platform?**](#coming-to-gitlab-from-another-platform)<br/>Consult our handy guides. | +| [**Install GitLab**](https://about.gitlab.com/install/)<br/>Installation options for different platforms. | [**Subscribe to GitLab**](#subscribe-to-gitlab)<br/>Get access to more features. | +| [**Update GitLab**](update/README.md)<br/>Update your GitLab self-managed instance to the latest version. | [**GitLab Releases**](https://about.gitlab.com/releases/)<br/>What's new in GitLab. | -GitLab offers the most scalable Git-based fully integrated platform for -software development, with flexible products and subscriptions. -To understand what features you have access to, check the [GitLab subscriptions](#gitlab-subscriptions) below. +## Popular Documentation -**Shortcuts to GitLab's most visited docs:** +Have a look at some of our most popular documentation resources: -| General documentation | GitLab CI/CD docs | -| :----- | :----- | -| [User documentation](user/index.md) | [GitLab CI/CD quick start guide](ci/quick_start/README.md) | -| [Administrator documentation](administration/index.md) | [GitLab CI/CD examples](ci/examples/README.md) | -| [Contributor documentation](#contributor-documentation) | [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | -| [Getting started with GitLab](#getting-started-with-gitlab) | [Using Docker images](ci/docker/using_docker_images.md) | -| [API](api/README.md) | [Auto DevOps](topics/autodevops/index.md) | -| [SSH authentication](ssh/README.md) | [Kubernetes integration](user/project/clusters/index.md)| -| [GitLab Pages](user/project/pages/index.md) | [GitLab Container Registry](user/project/container_registry.md) | +| Popular Topic | Description | +|:----------------------------------------------------------------|:-----------------------------------------------------------------| +| [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | Complete syntax documentation for configuring your CI pipelines. | +| [GitLab CI/CD examples](ci/examples/README.md) | Get up to speed quickly with common CI/CD scenarios. | +| [GitLab Container Registry](user/project/container_registry.md) | Host containers within GitLab. | +| [GitLab Pages](user/project/pages/index.md) | Host static websites for your projects with GitLab. | +| [Kubernetes integration](user/project/clusters/index.md) | Use GitLab with Kubernetes. | +| [SSH authentication](ssh/README.md) | Secure your network communications. | +| [Using Docker images](ci/docker/using_docker_images.md) | Build and test your applications with Docker. | -## Complete DevOps with GitLab +## The entire DevOps Lifecycle GitLab is the first single application for software development, security, -and operations that enables Concurrent DevOps, making the software lifecycle -three times faster and radically improving the speed of business. GitLab -provides solutions for all the stages of the DevOps lifecycle: -[plan](#plan), [create](#create), [verify](#verify), [package](#package), -[release](#release), [configure](#configure), [monitor](#monitor). +and operations that enables [Concurrent DevOps](https://about.gitlab.com/concurrent-devops/), +making the software lifecycle faster and radically improving the speed of business. - +GitLab provides solutions for [all the stages of the DevOps lifecycle](https://about.gitlab.com/stages-devops-lifecycle/): -### Plan + -Whether you use Waterfall, Agile, or Conversational Development, -GitLab streamlines your collaborative workflows. Visualize, prioritize, -coordinate, and track your progress your way with GitLab’s flexible project -management tools. +The following sections provide links to documentation for each DevOps stage: + +| DevOps Stage | Documentation for | +|:------------------------|:------------------------------------------------------------| +| [Manage](#manage) | Statistics and analytics features. | +| [Plan](#plan) | Project planning and management features. | +| [Create](#create) | Source code and data creation and management features. | +| [Verify](#verify) | Testing, code quality, and continuous integration features. | +| [Package](#package) | Docker container registry. | +| [Release](#release) | Application release and delivery features. | +| [Configure](#configure) | Application and infrastructure configuration tools. | +| [Monitor](#monitor) | Application monitoring and metrics features. | +| [Secure](#secure) | Security capability features. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> -- Chat operations - - [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) - - [Slack slash commands](user/project/integrations/slack_slash_commands.md) -- [Discussions](user/discussions/index.md): Threads, comments, and resolvable discussions in issues, commits, and merge requests. -- [Issues](user/project/issues/index.md) -- [Project Issue Board](user/project/issue_board.md) -- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests. -- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles. -- [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date. -- [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard. -- [GitLab Quick Actions](user/project/quick_actions.md): Textual shortcuts for common actions on issues or merge requests that are usually done by clicking buttons or dropdowns in GitLab's UI. +### Manage -#### Migrate and import your projects from other platforms +GitLab provides statistics and insight into ways you can maximize the value of GitLab in your organization. -- [Importing to GitLab](user/project/import/index.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. -- [Migrating from SVN](workflow/importing/migrating_from_svn.md): Convert a SVN repository to Git and GitLab. +The following documentation relates to the DevOps **Manage** stage: + +| Manage Topics | Description | +|:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Authentication and<br/>Authorization](administration/auth/README.md) **[CORE ONLY]** | Supported authentication and authorization providers. | +| [GitLab Cycle Analytics](user/project/cycle_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | +| [Instance Statistics](user/instance_statistics/index.md) | Discover statistics on how many GitLab features you use and user activity. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +### Plan + +Whether you use Waterfall, Agile, or Conversational Development, GitLab streamlines your collaborative workflows. + +Visualize, prioritize, coordinate, and track your progress your way with GitLab’s flexible project +management tools. + +The following documentation relates to the DevOps **Plan** stage: + +| Plan Topics | Description | +|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------| +| [Discussions](user/discussions/index.md) | Threads, comments, and resolvable discussions in issues, commits, and merge requests. | +| [Due Dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. | +| [Quick Actions](user/project/quick_actions.md) | Shortcuts for common actions on issues or merge requests, replacing the need to click buttons or use dropdowns in GitLab's UI. | +| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/moving_issues.md) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. | +| [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. | +| [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. | +| [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. | +| [Time Tracking](workflow/time_tracking.md) | Track time spent on issues and merge requests. | +| [Todos](workflow/todos.md) | Keep track of work requiring attention with a chronological list displayed on a simple dashboard. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Create -Consolidate source code into a single [DVCS](https://en.wikipedia.org/wiki/Distributed_version_control) +Consolidate source code into a single [distributed version control system](https://en.wikipedia.org/wiki/Distributed_version_control) that’s easily managed and controlled without disrupting your workflow. -GitLab’s git repositories come complete with branching tools and access + +GitLab’s Git repositories come complete with branching tools and access controls, providing a scalable, single source of truth for collaborating on projects and code. -#### Projects and groups - -- [Projects](user/project/index.md): - - [Project settings](user/project/settings/index.md) - - [Create a project](gitlab-basics/create-project.md) - - [Fork a project](gitlab-basics/fork-project.md) - - [Importing and exporting projects between instances](user/project/settings/import_export.md). - - [Project access](public_access/public_access.md): Setting up your project's visibility to public, internal, or private. - - [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages. -- [Groups](user/group/index.md): Organize your projects in groups. - - [Subgroups](user/group/subgroups/index.md) -- [Search through GitLab](user/search/index.md): Search for issues, merge requests, projects, groups, todos, and issues in Issue Boards. -- [Snippets](user/snippets.md): Snippets allow you to create little bits of code. -- [Wikis](user/project/wiki/index.md): Enhance your repository documentation with built-in wikis. -- [Web IDE](user/project/web_ide/index.md) +The following documentation relates to the DevOps **Create** stage: -#### Repositories - -Manage your [repositories](user/project/repository/index.md) from the UI (user interface): - -- [Files](user/project/repository/index.md#files) - - [Create a file](user/project/repository/web_editor.md#create-a-file) - - [Upload a file](user/project/repository/web_editor.md#upload-a-file) - - [File templates](user/project/repository/web_editor.md#template-dropdowns) - - [Jupyter Notebook files](user/project/repository/index.md#jupyter-notebook-files) - - [Create a directory](user/project/repository/web_editor.md#create-a-directory) - - [Start a merge request](user/project/repository/web_editor.md#tips) (when committing via UI) -- [Branches](user/project/repository/branches/index.md) - - [Default branch](user/project/repository/branches/index.md#default-branch) - - [Create a branch](user/project/repository/web_editor.md#create-a-new-branch) - - [Protected branches](user/project/protected_branches.md#protected-branches) - - [Delete merged branches](user/project/repository/branches/index.md#delete-merged-branches) -- [Commits](user/project/repository/index.md#commits) - - [Signing commits](user/project/repository/gpg_signed_commits/index.md): use GPG to sign your commits. +#### Projects and Groups -#### Merge Requests +| Create Topics - Projects and Groups | Description | +|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------| +| [Create](gitlab-basics/create-project.md) and [fork](gitlab-basics/fork-project.md) projects, and<br/>[import and export<br/>projects between instances](user/project/settings/import_export.md) | Create, duplicate, and move projects. | +| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy your static website with GitLab Pages. | +| [Groups](user/group/index.md) and [Subgroups](user/group/subgroups/index.md) | Organize your projects in groups. | +| [Projects](user/project/index.md), including [project access](public_access/public_access.md)<br/>and [settings](user/project/settings/index.md) | Host source code, and control your project's visibility and set configuration. | +| [Search through GitLab](user/search/index.md) | Search for issues, merge requests, projects, groups, and todos. | +| [Snippets](user/snippets.md) | Snippets allow you to create little bits of code. | +| [Web IDE](user/project/web_ide/index.md) | Edit files within GitLab's user interface. | +| [Wikis](user/project/wiki/index.md) | Enhance your repository documentation with built-in wikis. | -- [Merge Requests](user/project/merge_requests/index.md) - - [Work In Progress "WIP" Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md) - - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved. - - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) - - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md) +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> -#### Integrations +#### Repositories -- [Project Services](user/project/integrations/project_services.md): Integrate a project with external services, such as CI and chat. -- [GitLab Integration](integration/README.md): Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. -- [Trello Power-Up](integration/trello_power_up.md): Integrate with GitLab's Trello Power-Up +| Create Topics - Repositories | Description | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------| +| [Branches](user/project/repository/branches/index.md) and the [default branch](user/project/repository/branches/index.md#default-branch) | How to use branches in GitLab. | +| [Commits](user/project/repository/index.md#commits) and [signing commits](user/project/repository/gpg_signed_commits/index.md) | Work with commits, and use GPG to sign your commits. | +| [Create branches](user/project/repository/web_editor.md#create-a-new-branch), [create](user/project/repository/web_editor.md#create-a-file)<br/>and [upload](user/project/repository/web_editor.md#upload-a-file) files, and [create directories](user/project/repository/web_editor.md#create-a-directory) | Create branches, create and upload files, and create directories within GitLab. | +| [Delete merged branches](user/project/repository/branches/index.md#delete-merged-branches) | Bulk delete branches after their changes are merged. | +| [File templates](user/project/repository/web_editor.md#template-dropdowns) | File templates for common files. | +| [Files](user/project/repository/index.md#files) | Files management. | +| [Jupyter Notebook files](user/project/repository/index.md#jupyter-notebook-files) | GitLab's support for `.ipynb` files. | +| [Protected branches](user/project/protected_branches.md) | Use protected branches. | +| [Repositories](user/project/repository/index.md) | Manage source code repositories in GitLab's user interface. | +| [Start a merge request](user/project/repository/web_editor.md#tips) | Start merge request when committing via GitLab's user interface. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> -#### Automation +#### Merge Requests -- [API](api/README.md): Automate GitLab via a simple and powerful API. -- [GitLab Webhooks](user/project/integrations/webhooks.md): Let GitLab notify you when new code has been pushed to your project. +| Create Topics - Merge Requests | Description | +|:------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------| +| [Checking out merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) | Tips for working with merge requests locally. | +| [Cherry-picking](user/project/merge_requests/cherry_pick_changes.md) | Use GitLab for cherry-picking changes. | +| [Merge request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue) | Resolve discussions, move discussions in a merge request to an issue, and only allow merge requests to be merged if all discussions are resolved. | +| [Merge requests](user/project/merge_requests/index.md) | Merge request management. | +| [Work In Progress "WIP" merge requests](user/project/merge_requests/work_in_progress_merge_requests.md) | Prevent merges of work-in-progress merge requests. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +#### Integration and Automation + +| Create Topics - Integration and Automation | Description | +|:------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| +| [GitLab API](api/README.md) | Integrate GitLab via a simple and powerful API. | +| [GitLab Integration](integration/README.md) | Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. | +| [GitLab Webhooks](user/project/integrations/webhooks.md) | Let GitLab notify you when new code has been pushed to your project. | +| [Project Services](user/project/integrations/project_services.md) | Integrate a project with external services, such as CI and chat. | +| [Trello Power-Up](integration/trello_power_up.md) | Integrate with GitLab's Trello Power-Up. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Verify Spot errors sooner, improve security and shorten feedback cycles with built-in -static code analysis, code testing, code quality, dependency checking and review -apps. Customize your approval workflow controls, automatically test the quality -of your code, and spin up a staging environment for every code change. GitLab -Continuous Integration is the most popular next generation testing system that +static code analysis, code testing, code quality, dependency checking, and Review +Apps. Customize your approval workflow controls, automatically test the quality +of your code, and spin up a staging environment for every code change. + +GitLab Continuous Integration is the most popular next generation testing system that scales to run your tests faster. -- [GitLab CI/CD](ci/README.md): Explore the features and capabilities of Continuous Integration, Continuous Delivery, and Continuous Deployment with GitLab. -- [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request. -- [Pipeline Graphs](ci/pipelines.md#pipeline-graphs) -- [JUnit test reports](ci/junit_test_reports.md) +The following documentation relates to the DevOps **Verify** stage: + +| Verify Topics | Description | +|:---------------------------------------------------|:-----------------------------------------------------------------------------| +| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. | +| [JUnit test reports](ci/junit_test_reports.md) | Display JUnit test reports on merge requests. | +| [Pipeline Graphs](ci/pipelines.md#pipeline-graphs) | Visualize builds. | +| [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Package @@ -141,7 +231,17 @@ GitLab Container Registry gives you the enhanced security and access controls of custom Docker images without 3rd party add-ons. Easily upload and download images from GitLab CI/CD with full Git repository management integration. -- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry. +The following documentation relates to the DevOps **Package** stage: + +| Package Topics | Description | +|:----------------------------------------------------------------|:-------------------------------------------------------| +| [GitLab Container Registry](user/project/container_registry.md) | Learn how to use GitLab's built-in Container Registry. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Release @@ -149,111 +249,257 @@ Spend less time configuring your tools, and more time creating. Whether you’re deploying to one server or thousands, build, test, and release your code confidently and securely with GitLab’s built-in Continuous Delivery and Deployment. -- [Auto Deploy](topics/autodevops/index.md#auto-deploy): Configure GitLab CI for the deployment of your application. -- [Environments and deployments](ci/environments.md): With environments, you can control the continuous deployment of your software within GitLab. -- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy a static site directly from GitLab. -- [Scheduled Pipelines](user/project/pipelines/schedules.md) -- [Protected Runners](ci/runners/README.md#protected-runners) +The following documentation relates to the DevOps **Release** stage: + +| Release Topics | Description | +|:------------------------------------------------------------|:---------------------------------------------------------------------------------------------| +| [Auto Deploy](topics/autodevops/index.md#auto-deploy) | Configure GitLab for the deployment of your application. | +| [Environments and deployments](ci/environments.md) | With environments, you can control the continuous deployment of your software within GitLab. | +| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab. | +| [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy a static site directly from GitLab. | +| [Protected Runners](ci/runners/README.md#protected-runners) | Select Runners to only pick jobs for protected branches and tags. | +| [Scheduled Pipelines](user/project/pipelines/schedules.md) | Execute pipelines on a schedule. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Configure Automate your entire workflow from build to deploy and monitoring with GitLab -Auto Devops. Best practice templates get you started with minimal to zero +Auto DevOps. Best practice templates get you started with minimal to zero configuration. Then customize everything from buildpacks to CI/CD. -- [Auto DevOps](topics/autodevops/index.md) -- [Deployment of Helm, Ingress, and Prometheus on Kubernetes](user/project/clusters/index.md#installing-applications) -- [Protected variables](ci/variables/README.md#protected-variables) -- [Easy creation of Kubernetes clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +The following documentation relates to the DevOps **Configure** stage: + +| Configure Topics | Description | +|:-----------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------| +| [Auto DevOps](topics/autodevops/index.md) | Automatically employ a complete DevOps lifecycle. | +| [Easy creation of Kubernetes<br/>clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) | Use Google Kubernetes Engine and GitLab. | +| [Executable Runbooks](user/project/clusters/runbooks/index.md) | Documented procedures that explain how to carry out particular processes. | +| [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. | +| [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | +| [Protected variables](ci/variables/README.md#protected-variables) | Restrict variables to protected branches and tags. | +| [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### Monitor -Measure how long it takes to go from planning to monitoring and ensure your -applications are always responsive and available. GitLab collects and displays -performance metrics for deployed apps using Prometheus so you can know in an +Ensure your applications are always responsive and available. + +GitLab collects and displays performance metrics for deployed applications so you can know in an instant how code changes impact your production environment. -- [GitLab Prometheus](administration/monitoring/prometheus/index.md): Configure the bundled Prometheus to collect various metrics from your GitLab instance. -- [Prometheus project integration](user/project/integrations/prometheus.md): Configure the Prometheus integration per project and monitor your CI/CD environments. -- [Prometheus metrics](user/project/integrations/prometheus_library/metrics.md): Let Prometheus collect metrics from various services, like Kubernetes, NGINX, NGINX ingress controller, HAProxy, and Amazon Cloud Watch. -- [GitLab Performance Monitoring](administration/monitoring/performance/index.md): Use InfluxDB and Grafana to monitor the performance of your GitLab instance (will be eventually replaced by Prometheus). -- [Health check](user/admin_area/monitoring/health_check.md): GitLab provides liveness and readiness probes to indicate service health and reachability to required services. -- [GitLab Cycle Analytics](user/project/cycle_analytics.md): Cycle Analytics measures the time it takes to go from an - [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. +The following documentation relates to the DevOps **Monitor** stage: -## Getting started with GitLab +| Monitor Topics | Description | +|:------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------| +| [GitLab Performance Monitoring](administration/monitoring/performance/index.md) **[CORE ONLY]** | Use InfluxDB and Grafana to monitor the performance of your GitLab instance (will be eventually replaced by Prometheus). | +| [GitLab Prometheus](administration/monitoring/prometheus/index.md) **[CORE ONLY]** | Configure the bundled Prometheus to collect various metrics from your GitLab instance. | +| [Health check](user/admin_area/monitoring/health_check.md) | GitLab provides liveness and readiness probes to indicate service health and reachability to required services. | +| [Prometheus project integration](user/project/integrations/prometheus.md) | Configure the Prometheus integration per project and monitor your CI/CD environments. | +| [Prometheus metrics](user/project/integrations/prometheus_library/index.md) | Let Prometheus collect metrics from various services, like Kubernetes, NGINX, NGINX ingress controller, HAProxy, and Amazon Cloud Watch. | -- [GitLab Basics](gitlab-basics/README.md): Start working on your command line and on GitLab. -- [GitLab Workflow](workflow/README.md): Enhance your workflow with the best of GitLab Workflow. - - See also [GitLab Workflow - an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). -- [GitLab Markdown](user/markdown.md): GitLab's advanced formatting system (GitLab Flavored Markdown). +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> -### User account +### Secure -- [User account](user/profile/index.md): Manage your account - - [Authentication](topics/authentication/index.md): Account security with two-factor authentication, setup your ssh keys and deploy keys for secure access to your projects. - - [Profile settings](user/profile/index.md#profile-settings): Manage your profile settings, two factor authentication and more. -- [User permissions](user/permissions.md): Learn what each role in a project (external/guest/reporter/developer/maintainer/owner) can do. +GitLab can help you secure your applications from within your development lifecycle. -### Git and GitLab +The following documentation relates to the DevOps **Secure** stage: -- [Git](topics/git/index.md): Getting started with Git, branching strategies, Git LFS, advanced use. -- [Git cheatsheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf): Download a PDF describing the most used Git operations. -- [GitLab Flow](workflow/gitlab_flow.md): explore the best of Git with the GitLab Flow strategy. +| Monitor Topics | Description | +|:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------| +| [Container Scanning example](ci/examples/container_scanning.md) | `.gitlab-ci.yml` example of using Clair and clair-scanner to scan docker images for known vulnerabilities. | -## Administrator documentation +NOTE: **Note:** +Viewing [Container Scanning reports](https://docs.gitlab.com/ee/user/project/merge_requests/container_scanning.html) within merge requests requires [GitLab Ultimate](https://about.gitlab.com/pricing/). -[Administration documentation](administration/index.md) applies to admin users of GitLab -self-hosted instances. +## Subscribe to GitLab -Learn how to install, configure, update, upgrade, integrate, and maintain your own instance. -Regular users don't have access to GitLab administration tools and settings. +There are two ways to use GitLab: -## Contributor documentation +- [GitLab self-managed](#gitlab-self-managed): Install, administer, and maintain your own GitLab instance. +- [GitLab.com](#gitlab-com): GitLab's SaaS offering. You don't need to install anything to use GitLab.com, + you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab straight away. -GitLab Community Edition is [open source](https://gitlab.com/gitlab-org/gitlab-ce/) -and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitlab-ee/). -Learn how to contribute to GitLab: +The following sections outline tiers and features within GitLab self-managed and GitLab.com. -- [Development](development/README.md): All styleguides and explanations how to contribute. -- [Legal](legal/README.md): Contributor license agreements. -- [Writing documentation](development/documentation/index.md): Contributing to GitLab Docs. +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> -## GitLab subscriptions +### GitLab self-managed -You have two options to use GitLab: +With GitLab self-managed, you deploy your own GitLab instance on-premises or on a cloud of your choice. +GitLab self-managed is available for [free and with paid subscriptions](https://about.gitlab.com/pricing/#self-managed) in the following tiers: -- GitLab self-hosted: Install, administer, and maintain your own GitLab instance. -- GitLab.com: GitLab's SaaS offering. You don't need to install anything to use GitLab.com, -you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab -straight away. +| Tier | Includes | +|:---------|:-----------------------------------------------| +| Core | Core features. | +| Starter | Core and Starter features. | +| Premium | Core, Starter, and Premium features. | +| Ultimate | Core, Starter, Premium, and Ultimate features. | -### GitLab self-hosted +The following resources are available for more information on GitLab self-managed: -With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/pricing/): Core, Starter, Premium, and Ultimate. +- [Feature comparison](https://about.gitlab.com/pricing/self-managed/feature-comparison/), for information on what features are available at each tier. +- [GitLab pricing page](https://about.gitlab.com/pricing/#self-managed), for subscription information and a free trial. +- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including: + - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers). + - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions). -Every feature available in Core is also available in Starter, Premium, and Ultimate. -Starter features are also available in Premium and Ultimate, and Premium features are also -available in Ultimate. +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> ### GitLab.com GitLab.com is hosted, managed, and administered by GitLab, Inc., with -[free and paid subscriptions](https://about.gitlab.com/gitlab-com/) for individuals -and teams: Free, Bronze, Silver, and Gold. +[free and paid subscriptions](https://about.gitlab.com/pricing/) for individuals +and teams in the following tiers: + +| Tier | Includes same features available in | +|:-------|:----------------------------------------------------| +| Free | [Core](#gitlab-self-managed) self-managed tier. | +| Bronze | [Starter](#gitlab-self-managed) self-managed tier. | +| Silver | [Premium](#gitlab-self-managed) self-managed tier. | +| Gold | [Ultimate](#gitlab-self-managed) self-managed tier. | + +GitLab.com subscriptions grant access +to the same features available in GitLab self-managed, **except +[administration](administration/index.md) tools and settings**. + +TIP: **Tip:** +To support the open source community and encourage the development of open source projects, GitLab grants access to **Gold** features for all GitLab.com **public** projects, regardless of the subscription. + +The following resources are available for more information on GitLab.com: + +- [Feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/), for information on what features are available at each tier. +- [GitLab pricing page](https://about.gitlab.com/pricing/), for subscription information and a free trial. +- Our [product marketing page](https://about.gitlab.com/handbook/marketing/product-marketing/), for additional information including: + - How [different tiers are licensed](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers). + - The different [GitLab distributions](https://about.gitlab.com/handbook/marketing/product-marketing/#distributions). + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +## New to Git and GitLab? + +Working with new systems can be daunting. + +We have the following documentation to rapidly uplift your GitLab knowledge: + +| Topic | Description | +|:-----------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------| +| [GitLab Basics](gitlab-basics/README.md) | Start working on the command line and with GitLab. | +| [GitLab Workflow](workflow/README.md) and [overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/) | Enhance your workflow with the best of GitLab Workflow. | +| [Get started with GitLab CI/CD](ci/quick_start/README.md) | Quickly implement GitLab CI/CD. | +| [Auto DevOps](topics/autodevops/index.md) | Learn more about GitLab's Auto DevOps. | +| [GitLab Markdown](user/markdown.md) | GitLab's advanced formatting system (GitLab Flavored Markdown) | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +### User account + +Learn more about GitLab account management: + +| Topic | Description | +|:-----------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------| +| [User account](user/profile/index.md) | Manage your account. | +| [Authentication](topics/authentication/index.md) | Account security with two-factor authentication, set up your ssh keys, and deploy keys for secure access to your projects. | +| [Profile settings](user/profile/index.md#profile-settings) | Manage your profile settings, two factor authentication, and more. | +| [User permissions](user/permissions.md) | Learn what each role in a project can do. | -GitLab.com subscriptions grants access -to the same features available in GitLab self-hosted, **except -[administration](administration/index.md) tools and settings**: +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +### Git and GitLab + +Learn more about using Git, and using Git with GitLab: + +| Topic | Description | +|:----------------------------------------------------------------------------|:---------------------------------------------------------------------------| +| [Git](topics/git/index.md) | Getting started with Git, branching strategies, Git LFS, and advanced use. | +| [Git cheatsheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF describing the most used Git operations. | +| [GitLab Flow](workflow/gitlab_flow.md) | Explore the best of Git with the GitLab Flow strategy. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +## Coming to GitLab from another platform + +If you are coming to GitLab from another platform, you'll find the following information useful: + +| Topic | Description | +|:---------------------------------------------------------------|:---------------------------------------------------------------------------------------| +| [Importing to GitLab](user/project/import/index.md) | Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz, and SVN into GitLab. | +| [Migrating from SVN](workflow/importing/migrating_from_svn.md) | Convert a SVN repository to Git and GitLab. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +## Building an integration with GitLab + +There are many ways to integrate with GitLab, including: + +| Topic | Description | +|:-----------------------------------------------------------|:------------------------------------------------| +| [GitLab API](api/README.md) | Integrate GitLab via a simple and powerful API. | +| [Integrations and automation](#integration-and-automation) | All GitLab integration and automation options. | + +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> + +## Contributing to GitLab + +GitLab Community Edition is [open source](https://gitlab.com/gitlab-org/gitlab-ce/) +and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitlab-ee/). -- GitLab.com Free includes the same features available in Core -- GitLab.com Bronze includes the same features available in GitLab Starter -- GitLab.com Silver includes the same features available in GitLab Premium -- GitLab.com Gold includes the same features available in GitLab Ultimate +Learn how to contribute to GitLab with the following resources: -For supporting the open source community and encouraging the development of -open source projects, GitLab grants access to **Gold** features -for all GitLab.com **public** projects, regardless of the subscription. +| Topic | Description | +|:------------------------------------------------------------|:-----------------------------------------| +| [Development](development/README.md) | How to contribute to GitLab development. | +| [Legal](legal/README.md) | Contributor license agreements. | +| [Writing documentation](development/documentation/index.md) | How to contribute to GitLab Docs. | -To know more about GitLab subscriptions and licensing, please refer to the -[GitLab Product Marketing Handbook](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers). +<div align="right"> + <a type="button" class="btn btn-default" href="#overview"> + Back to Overview <i class="fa fa-angle-double-up" aria-hidden="true"></i> + </a> +</div> diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 252ff1f4b15..772e55cef07 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -6,7 +6,7 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t 1. Get your Client credentials (Client ID and Client Secret) at [Authentiq](https://www.authentiq.com/developers). -2. On your GitLab server, open the configuration file: +1. On your GitLab server, open the configuration file: For omnibus installation ```sh @@ -18,11 +18,11 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t ```sh sudo -u git -H editor /home/git/gitlab/config/gitlab.yml ``` - -3. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider. -4. Add the provider configuration for Authentiq: - +1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider. + +1. Add the provider configuration for Authentiq: + For Omnibus packages: ```ruby @@ -31,15 +31,15 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t "name" => "authentiq", "app_id" => "YOUR_CLIENT_ID", "app_secret" => "YOUR_CLIENT_SECRET", - "args" => { + "args" => { "scope": 'aq:name email~rs address aq:push' } } ] ``` - + For installations from source: - + ```yaml - { name: 'authentiq', app_id: 'YOUR_CLIENT_ID', @@ -49,20 +49,20 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t } } ``` - - -5. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. + + +1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. -6. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in step 1. +1. Change `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` to the Client credentials you received in step 1. -7. Save the configuration file. +1. Save the configuration file. -8. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. +1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be an Authentiq icon below the regular sign in form. Click the icon to begin the authentication process. +On the sign in page there should now be an Authentiq icon below the regular sign in form. Click the icon to begin the authentication process. -- If the user has the Authentiq ID app installed in their iOS or Android device, they can scan the QR code, decide what personal details to share and sign in to your GitLab installation. -- If not they will be prompted to download the app and then follow the procedure above. +- If the user has the Authentiq ID app installed in their iOS or Android device, they can scan the QR code, decide what personal details to share and sign in to your GitLab installation. +- If not they will be prompted to download the app and then follow the procedure above. -If everything goes right, the user will be returned to GitLab and will be signed in.
\ No newline at end of file +If everything goes right, the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 5c7392b99d0..54ded25291a 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -111,7 +111,7 @@ main: uid: 'sAMAccountName' # This should be the attribute, not the value that maps to uid. ## - ## Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com' + ## Examples: 'america\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com' ## bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' password: '_the_password_of_the_bind_user' @@ -132,7 +132,7 @@ main: ## Enables SSL certificate verification if encryption method is ## "start_tls" or "simple_tls". Defaults to true since GitLab 10.0 for ## security. This may break installations upon upgrade to 10.0, that did - ## not know their LDAP SSL certificates were not setup properly. + ## not know their LDAP SSL certificates were not set up properly. ## verify_certificates: true diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 664657650d4..ae38094391b 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -11,7 +11,7 @@ The following documentation enables Okta as a SAML provider. 1. When the app screen comes up you see another button to **Create an App** and choose SAML 2.0 on the next screen. 1. Now, very important, add a logo - (you can choose it from https://about.gitlab.com/press/). You'll have to + (you can choose it from <https://about.gitlab.com/press/>). You'll have to crop and resize it. 1. Next, you'll need the to fill in the SAML general config. Here's an example image. diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 890b780fe80..cfe7b0e05e3 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -71,7 +71,7 @@ A Registry init file is not shipped with GitLab if you install it from source. Hence, [restarting GitLab][restart gitlab] will not restart the Registry should you modify its settings. Read the upstream documentation on how to achieve that. -At the absolute minimum, make sure your [Registry configuration][registry-auth] +At the **absolute** minimum, make sure your [Registry configuration][registry-auth] has `container_registry` as the service and `https://gitlab.example.com/jwt/auth` as the realm: @@ -84,6 +84,9 @@ auth: rootcertbundle: /root/certs/certbundle ``` +CAUTION: **Caution:** +If `auth` is not set up, users will be able to pull docker images without authentication. + ## Container Registry domain configuration There are two ways you can configure the Registry's external domain. diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 9b0fabb9259..60ad4bf4e8f 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -50,6 +50,9 @@ Hooks can be also placed in `hooks/<hook_name>.d` (global) or `custom_hooks/<hook_name>.d` (per project) directories supporting chained execution of the hooks. +NOTE: **Note:** `<hook_name>.d` would need to be either `pre-receive.d`, +`post-receive.d`, or `update.d` to work properly. Any other names will be ignored. + To look in a different directory for the global custom hooks (those in `hooks/<hook_name.d>`), set `custom_hooks_dir` in gitlab-shell config. For Omnibus installations, this can be set in `gitlab.rb`; and in source @@ -57,7 +60,7 @@ installations, this can be set in `gitlab-shell/config.yml`. The hooks are searched and executed in this order: -1. `<project>.git/hooks/` - symlink to `gitlab-shell/hooks` global dir +1. `gitlab-shell/hooks` directory as known to Gitaly 1. `<project>.git/hooks/<hook_name>` - executed by `git` itself, this is `gitlab-shell/hooks/<hook_name>` 1. `<project>.git/custom_hooks/<hook_name>` - per project hook (this is already existing behavior) 1. `<project>.git/custom_hooks/<hook_name>.d/*` - per project hooks diff --git a/doc/administration/external_database.md b/doc/administration/external_database.md index 31199f2cdc7..ec2d30c82d1 100644 --- a/doc/administration/external_database.md +++ b/doc/administration/external_database.md @@ -9,7 +9,7 @@ separate from the GitLab Omnibus package. If you use a cloud-managed service, or provide your own PostgreSQL instance: -1. Setup PostgreSQL according to the +1. Set up PostgreSQL according to the [database requirements document](../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md new file mode 100644 index 00000000000..341a00009e5 --- /dev/null +++ b/doc/administration/git_protocol.md @@ -0,0 +1,103 @@ +--- +description: "Set and configure Git protocol v2" +--- + +# Configuring Git Protocol v2 + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46555) in GitLab 11.4. + +Git protocol v2 improves the v1 wire protocol in several ways and is +enabled by default in GitLab for HTTP requests. In order to enable SSH, +further configuration is needed by the administrator. + +More details about the new features and improvements are available in +the [Google Open Source Blog](https://opensource.googleblog.com/2018/05/introducing-git-protocol-version-2.html) +and the [protocol documentation](https://github.com/git/git/blob/master/Documentation/technical/protocol-v2.txt). + +## Requirements + +From the client side, `git` `v2.18.0` or newer must be installed. + +From the server side, if we want to configure SSH we need to set the `sshd` +server to accept the `GIT_PROTOCOL` environment. + +In installations using [GitLab Helm Charts](../install/kubernetes/gitlab_chart.md) +and [All-in-one docker image](https://docs.gitlab.com/omnibus/docker/), the SSH +service is already configured to accept the `GIT_PROTOCOL` environment and users +need not do anything more. + +For Omnibus GitLab and installations from source, you have to manually update +the SSH configuration of your server: + +``` +# /etc/ssh/sshd_config +AcceptEnv GIT_PROTOCOL +``` + +Once configured, restart the SSH daemon. In Ubuntu, run: + +```sh +sudo service ssh restart +``` + +## Instructions + +In order to use the new protocol, clients need to either pass the configuration +`-c protocol.version=2` to the git command, or set it globally: + +```sh +git config --global protocol.version 2 +``` + +### HTTP connections + +Verify Git v2 is used by the client: + +```sh +GIT_TRACE_CURL=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | grep Git-Protocol +``` + +You should see that the `Git-Protocol` header is sent: + +``` +16:29:44.577888 http.c:657 => Send header: Git-Protocol: version=2 +``` + +Verify Git v2 is used by the server: + +```sh +GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | head +``` + +Example response using Git protocol v2: + +```sh +$ GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-instance.com/group/repo.git 2>&1 | head +10:42:50.574485 pkt-line.c:80 packet: git< # service=git-upload-pack +10:42:50.574653 pkt-line.c:80 packet: git< 0000 +10:42:50.574673 pkt-line.c:80 packet: git< version 2 +10:42:50.574679 pkt-line.c:80 packet: git< agent=git/2.18.1 +10:42:50.574684 pkt-line.c:80 packet: git< ls-refs +10:42:50.574688 pkt-line.c:80 packet: git< fetch=shallow +10:42:50.574693 pkt-line.c:80 packet: git< server-option +10:42:50.574697 pkt-line.c:80 packet: git< 0000 +10:42:50.574817 pkt-line.c:80 packet: git< version 2 +10:42:50.575308 pkt-line.c:80 packet: git< agent=git/2.18.1 +``` + +### SSH Connections + +Verify Git v2 is used by the client: + +```sh +GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://your-gitlab-instance.com:group/repo.git 2>&1 |grep GIT_PROTOCOL +``` + +You should see that the `GIT_PROTOCOL` environment variable is sent: + +``` +debug1: Sending env GIT_PROTOCOL = version=2 +``` + +For the server side, you can use the [same examples from HTTP](#http-connections), changing the +URL to use SSH. diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 49c6902bc42..dc6a71e2ebd 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,10 +1,8 @@ # Gitaly -[Gitaly](https://gitlab.com/gitlab-org/gitaly) (introduced in GitLab -9.0) is a service that provides high-level RPC access to Git -repositories. Gitaly was optional when it was first introduced in -GitLab, but since GitLab 9.4 it is a mandatory component of the -application. +[Gitaly](https://gitlab.com/gitlab-org/gitaly) is the service that +provides high-level RPC access to Git repositories. Without it, no other +components can read or write Git data. GitLab components that access Git repositories (gitlab-rails, gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do @@ -25,15 +23,13 @@ gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` To change a Gitaly setting in installations from source you can edit -`/home/git/gitaly/config.toml`. +`/home/git/gitaly/config.toml`. Changes will be applied when you run +`service gitlab restart`. ```toml prometheus_listen_addr = "localhost:9236" ``` -Changes to `/home/git/gitaly/config.toml` are applied when you run `service -gitlab restart`. - ## Client-side GRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC @@ -49,15 +45,9 @@ installations that are larger than a single machine. Most installations will be better served with the default configuration used by Omnibus and the GitLab source installation guide. -Starting with GitLab 9.4 it is possible to run Gitaly on a different -server from the rest of the application. This can improve performance -when running GitLab with its repositories stored on an NFS server. - -At the moment (GitLab 9.4) Gitaly is not yet a replacement for NFS -because some parts of GitLab still bypass Gitaly when accessing Git -repositories. If you choose to deploy Gitaly on your NFS server you -must still also mount your Git shares on your GitLab application -servers. +Starting with GitLab 11.4, Gitaly is a replacement for NFS except +when the [Elastic Search indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer) +is used. Gitaly network traffic is unencrypted so you should use a firewall to restrict access to your Gitaly server. @@ -219,7 +209,7 @@ repository from your GitLab server over HTTP. If you are running Gitaly [as a remote service](#running-gitaly-on-its-own-server) you may want to disable -the local Gitaly service that runs on your Gitlab server by default. +the local Gitaly service that runs on your GitLab server by default. > 'Disabling Gitaly' only makes sense when you run GitLab in a custom cluster configuration, where different services run on different @@ -247,3 +237,14 @@ gitaly_enabled=false When you run `service gitlab restart` Gitaly will be disabled on this particular machine. + +## Troubleshooting Gitaly in production + +Since GitLab 11.6, Gitaly comes with a command-line tool called +`gitaly-debug` that can be run on a Gitaly server to aid in +troubleshooting. In GitLab 11.6 its only sub-command is +`simulate-http-clone` which allows you to measure the maximum possible +Git clone speed for a specific repository on the server. + +For an up to date list of sub-commands see [the gitaly-debug +README](https://gitlab.com/gitlab-org/gitaly/blob/master/cmd/gitaly-debug/README.md). diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index b5124b1d540..c1eeb40b98f 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -13,7 +13,7 @@ Database Service (RDS) that runs PostgreSQL. If you use a cloud-managed service, or provide your own PostgreSQL: -1. Setup PostgreSQL according to the +1. Set up PostgreSQL according to the [database requirements document](../../install/requirements.md#database). 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index f16ae835ced..2ca860bd763 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -118,7 +118,7 @@ need some extra configuration. gitlab_rails['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964' ``` -1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations +1. Run `touch /etc/gitlab/skip-auto-reconfigure` to prevent database migrations from running on upgrade. Only the primary GitLab application server should handle migrations. diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 95e2caf0cad..74b0e2c8184 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -3,6 +3,11 @@ You can view information and options set for each of the mounted NFS file systems by running `nfsstat -m` and `cat /etc/fstab`. +NOTE: **Note:** Filesystem performance has a big impact on overall GitLab +performance, especially for actions that read or write to Git repositories. See +[Filesystem Performance Benchmarking](../operations/filesystem_benchmarking.md) +for steps to test filesystem performance. + ## NFS Server features ### Required features @@ -32,7 +37,31 @@ options: circumstances it could lead to data loss if a failure occurs before data has synced. -## AWS Elastic File System +### Known issues + +On some customer systems, we have seen NFS clients slow precipitously due to +[excessive network traffic from numerous `TEST_STATEID` NFS +messages](https://gitlab.com/gitlab-org/gitlab-ce/issues/52017). This is +likely due to a [Linux kernel +bug](https://bugzilla.redhat.com/show_bug.cgi?id=1552203) that may be fixed in +[more recent kernels with this +commit](https://github.com/torvalds/linux/commit/95da1b3a5aded124dd1bda1e3cdb876184813140). + +Users encountering a similar issue may be advised to disable the NFS server +delegation feature, which is an optimization to reduce the number of network +round-trips needed to read or write files. To disable NFS server delegations +on an Linux NFS server, do the following: + +1. On the NFS server, run: + + ```sh + echo 0 > /proc/sys/fs/leases-enable + sysctl -w fs.leases-enable=0 + ``` + +1. Restart the NFS server process. For example, on CentOS run `service nfs restart`. + +## Avoid using AWS's Elastic File System (EFS) GitLab strongly recommends against using AWS Elastic File System (EFS). Our support team will not be able to assist on performance issues related to @@ -49,6 +78,23 @@ stored on a local volume. For more details on another person's experience with EFS, see [Amazon's Elastic File System: Burst Credits](https://rawkode.com/2017/04/16/amazons-elastic-file-system-burst-credits/) +## Avoid using PostgreSQL with NFS + +GitLab strongly recommends against running your PostgreSQL database +across NFS. The GitLab support team will not be able to assist on performance issues related to +this configuration. + +Additionally, this configuration is specifically warned against in the +[Postgres Documentation](https://www.postgresql.org/docs/current/static/creating-cluster.html#CREATING-CLUSTER-NFS): + +>PostgreSQL does nothing special for NFS file systems, meaning it assumes NFS behaves exactly like +>locally-connected drives. If the client or server NFS implementation does not provide standard file +>system semantics, this can cause reliability problems. Specifically, delayed (asynchronous) writes +>to the NFS server can cause data corruption problems. + +For supported database architecture, please see our documentation on +[Configuring a Database for GitLab HA](https://docs.gitlab.com/ee/administration/high_availability/database.html). + ## NFS Client mount options Below is an example of an NFS mount point defined in `/etc/fstab` we use on @@ -58,10 +104,11 @@ GitLab.com: 10.1.1.1:/var/opt/gitlab/git-data /var/opt/gitlab/git-data nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 ``` -Notice several options that you should consider using: +Note there are several options that you should consider using: | Setting | Description | | ------- | ----------- | +| `vers=4.1` |NFS v4.1 should be used instead of v4.0 because there is a Linux [NFS client bug in v4.0](https://gitlab.com/gitlab-org/gitaly/issues/1339) that can cause significant problems due to stale data. | `nofail` | Don't halt boot process waiting for this mount to become available | `lookupcache=positive` | Tells the NFS client to honor `positive` cache results but invalidates any `negative` cache results. Negative cache results cause problems with Git. Specifically, a `git push` can fail to register uniformly across all NFS clients. The negative cache causes the clients to 'remember' that the files did not exist previously. @@ -87,7 +134,7 @@ Mount `/gitlab-nfs` then use the following Omnibus configuration to move each data location to a subdirectory: ```ruby -git_data_dirs({"default" => "/gitlab-nfs/gitlab-data/git-data"}) +git_data_dirs({"default" => { "path" => "/gitlab-nfs/gitlab-data/git-data"} }) user['home'] = '/gitlab-nfs/gitlab-data/home' gitlab_rails['uploads_directory'] = '/gitlab-nfs/gitlab-data/uploads' gitlab_rails['shared_path'] = '/gitlab-nfs/gitlab-data/shared' @@ -133,7 +180,7 @@ following are the 5 locations need to be shared: | Location | Description | Default configuration | | -------- | ----------- | --------------------- | -| `/var/opt/gitlab/git-data` | Git repository data. This will account for a large portion of your data | `git_data_dirs({"default" => "/var/opt/gitlab/git-data"})` +| `/var/opt/gitlab/git-data` | Git repository data. This will account for a large portion of your data | `git_data_dirs({"default" => { "path" => "/var/opt/gitlab/git-data"} })` | `/var/opt/gitlab/.ssh` | SSH `authorized_keys` file and keys used to import repositories from some other Git services | `user['home'] = '/var/opt/gitlab/'` | `/var/opt/gitlab/gitlab-rails/uploads` | User uploaded attachments | `gitlab_rails['uploads_directory'] = '/var/opt/gitlab/gitlab-rails/uploads'` | `/var/opt/gitlab/gitlab-rails/shared` | Build artifacts, GitLab Pages, LFS objects, temp files, etc. If you're using LFS this may also account for a large portion of your data | `gitlab_rails['shared_path'] = '/var/opt/gitlab/gitlab-rails/shared'` diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index e05bebbef18..833c1f367dd 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -15,7 +15,7 @@ Omnibus GitLab packages. > **Notes:** > - Redis requires authentication for High Availability. See -> [Redis Security](http://redis.io/topics/security) documentation for more +> [Redis Security](https://redis.io/topics/security) documentation for more > information. We recommend using a combination of a Redis password and tight > firewall rules to secure your Redis service. > - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation @@ -81,8 +81,8 @@ When a **Master** fails to respond, it's the application's responsibility (in our case GitLab) to handle timeout and reconnect (querying a **Sentinel** for a new **Master**). -To get a better understanding on how to correctly setup Sentinel, please read -the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as +To get a better understanding on how to correctly set up Sentinel, please read +the [Redis Sentinel documentation](https://redis.io/topics/sentinel) first, as failing to configure it correctly can lead to data loss or can bring your whole cluster down, invalidating the failover effort. @@ -217,7 +217,7 @@ Pick the one that suits your needs. and configure Sentinel, jump directly to the Sentinel section in the [Redis HA installation from source](redis_source.md#step-3-configuring-the-redis-sentinel-instances) documentation. - [Omnibus GitLab **Enterprise Edition** (EE) package][ee]: Both Redis and Sentinel - are bundled in the package, so you can use the EE package to setup the whole + are bundled in the package, so you can use the EE package to set up the whole Redis HA infrastructure (master, slave and Sentinel) which is described in this document. - If you have installed GitLab using the Omnibus GitLab packages (CE or EE), @@ -228,7 +228,7 @@ Pick the one that suits your needs. ## Configuring Redis HA -This is the section where we install and setup the new Redis instances. +This is the section where we install and set up the new Redis instances. > **Notes:** > - We assume that you have installed GitLab and all HA components from scratch. If you @@ -336,7 +336,7 @@ The prerequisites for a HA Redis setup are the following: 1. To prevent database migrations from running on upgrade, run: ``` - sudo touch /etc/gitlab/skip-auto-migrations + sudo touch /etc/gitlab/skip-auto-reconfigure ``` Only the primary GitLab application server should handle migrations. @@ -370,7 +370,7 @@ You must have at least `3` Redis Sentinel servers, and they need to be each in an independent machine. You can configure them in the same machines where you've configured the other Redis servers. -With GitLab Enterprise Edition, you can use the Omnibus package to setup +With GitLab Enterprise Edition, you can use the Omnibus package to set up multiple machines with the Sentinel daemon. --- @@ -458,7 +458,7 @@ multiple machines with the Sentinel daemon. 1. To prevent database migrations from running on upgrade, run: ``` - sudo touch /etc/gitlab/skip-auto-migrations + sudo touch /etc/gitlab/skip-auto-reconfigure ``` Only the primary GitLab application server should handle migrations. @@ -535,7 +535,7 @@ In this example we consider that all servers have an internal network interface with IPs in the `10.0.0.x` range, and that they can connect to each other using these IPs. -In a real world usage, you would also setup firewall rules to prevent +In a real world usage, you would also set up firewall rules to prevent unauthorized access from other machines and block traffic from the outside (Internet). @@ -665,7 +665,7 @@ cache, queues, and shared_state. To make this work with Sentinel: **Note**: Redis URLs should be in the format: `redis://:PASSWORD@SENTINEL_MASTER_NAME` 1. PASSWORD is the plaintext password for the Redis instance - 2. SENTINEL_MASTER_NAME is the Sentinel master name (e.g. `gitlab-redis-cache`) + 1. SENTINEL_MASTER_NAME is the Sentinel master name (e.g. `gitlab-redis-cache`) 1. Include an array of hashes with host/port combinations, such as the following: ```ruby @@ -684,7 +684,7 @@ cache, queues, and shared_state. To make this work with Sentinel: ``` 1. Note that for each persistence class, GitLab will default to using the configuration specified in `gitlab_rails['redis_sentinels']` unless - overriden by the settings above. + overridden by the settings above. 1. Be sure to include BOTH configuration options for each persistent classes. For example, if you choose to configure a cache instance, you must specify both `gitlab_rails['redis_cache_instance']` and `gitlab_rails['redis_cache_sentinels']` for GitLab to generate the proper configuration files. @@ -885,8 +885,8 @@ Read more on High Availability: [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [gh-531]: https://github.com/redis/redis-rb/issues/531 [gh-534]: https://github.com/redis/redis-rb/issues/534 -[redis]: http://redis.io/ -[sentinel]: http://redis.io/topics/sentinel +[redis]: https://redis.io/ +[sentinel]: https://redis.io/topics/sentinel [omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb [source]: ../../install/installation.md [ce]: https://about.gitlab.com/downloads diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md index 8b7a515a076..2101d36d2b6 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -24,7 +24,7 @@ the Omnibus Redis HA documentation. ## Configuring your own Redis server -This is the section where we install and setup the new Redis instances. +This is the section where we install and set up the new Redis instances. ### Prerequisites @@ -107,7 +107,7 @@ starting with `sentinel` prefix. Assuming that the Redis Sentinel is installed on the same instance as Redis master with IP `10.0.0.1` (some settings might overlap with the master): -1. [Install Redis Sentinel](http://redis.io/topics/sentinel) +1. [Install Redis Sentinel](https://redis.io/topics/sentinel) 1. Edit `/etc/redis/sentinel.conf`: ```conf @@ -204,7 +204,7 @@ In this example we consider that all servers have an internal network interface with IPs in the `10.0.0.x` range, and that they can connect to each other using these IPs. -In a real world usage, you would also setup firewall rules to prevent +In a real world usage, you would also set up firewall rules to prevent unauthorized access from other machines, and block traffic from the outside ([Internet][it]). @@ -363,7 +363,7 @@ production: port: 26379 # point to sentinel, not to redis port ``` -When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel). +When in doubt, please read [Redis Sentinel documentation](https://redis.io/topics/sentinel). [gh-531]: https://github.com/redis/redis-rb/issues/531 [downloads]: https://about.gitlab.com/downloads diff --git a/doc/administration/img/circuitbreaker_config.png b/doc/administration/img/circuitbreaker_config.png Binary files differdeleted file mode 100644 index 20233276055..00000000000 --- a/doc/administration/img/circuitbreaker_config.png +++ /dev/null diff --git a/doc/administration/img/failing_storage.png b/doc/administration/img/failing_storage.png Binary files differdeleted file mode 100644 index 652d7dcb5d7..00000000000 --- a/doc/administration/img/failing_storage.png +++ /dev/null diff --git a/doc/administration/index.md b/doc/administration/index.md index 8b6a42b0ca5..6083806af6c 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -47,6 +47,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Enforcing Terms of Service](../user/admin_area/settings/terms.md) - [Third party offers](../user/admin_area/settings/third_party_offers.md) - [Compliance](compliance.md): A collection of features from across the application that you may configure to help ensure that your GitLab instance and DevOps workflow meet compliance standards. +- [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages. #### Customizing GitLab's appearance @@ -60,7 +61,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Raketasks](../raketasks/README.md): Perform various tasks for maintenance, backups, automatic webhooks setup, etc. - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance. -- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq Job throttling, Sidekiq MemoryKiller, Unicorn). +- [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Unicorn). - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components. #### Updating GitLab @@ -117,10 +118,9 @@ created in snippets, wikis, and repos. ## Continuous Integration settings - [Enable/disable GitLab CI/CD](../ci/enable_or_disable_ci.md#site-wide-admin-setting): Enable or disable GitLab CI/CD for your instance. -- [GitLab CI/CD admin settings](../user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration time. +- [GitLab CI/CD admin settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job traces](job_traces.md): Information about the job traces (logs). -- [Artifacts size and expiration](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size): Define maximum artifacts limits and expiration date. - [Register Shared and specific Runners](../ci/runners/README.md#registering-a-shared-runner): Learn how to register and configure Shared and specific Runners to your own instance. - [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for Shared Runners. - [Enable/disable Auto DevOps](../topics/autodevops/index.md#enabling-auto-devops): Enable or disable Auto DevOps for your instance. @@ -130,6 +130,7 @@ created in snippets, wikis, and repos. - [Custom Git hooks](custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough. - [Git LFS configuration](../workflow/lfs/lfs_administration.md): Learn how to configure LFS for GitLab. - [Housekeeping](housekeeping.md): Keep your Git repositories tidy and fast. +- [Configuring Git Protocol v2](git_protocol.md): Git protocol version 2 support. ## Monitoring GitLab diff --git a/doc/administration/integration/koding.md b/doc/administration/integration/koding.md deleted file mode 100644 index def0add0061..00000000000 --- a/doc/administration/integration/koding.md +++ /dev/null @@ -1,246 +0,0 @@ -# Koding & GitLab - -> **Notes:** -> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed -> in a future version. The option to configure it is removed from GitLab's admin -> area.** -> - [Introduced][ce-5909] in GitLab 8.11. - -This document will guide you through installing and configuring Koding with -GitLab. - -First of all, to be able to use Koding and GitLab together you will need public -access to your server. This allows you to use single sign-on from GitLab to -Koding and using vms from cloud providers like AWS. Koding has a registry for -VMs, called Kontrol and it runs on the same server as Koding itself, VMs from -cloud providers register themselves to Kontrol via the agent that we put into -provisioned VMs. This agent is called Klient and it provides Koding to access -and manage the target machine. - -Kontrol and Klient are based on another technology called -[Kite](https://github.com/koding/kite), that we have written at Koding. Which is a -microservice framework that allows you to develop microservices easily. - -## Requirements - -### Hardware - -Minimum requirements are; - - - 2 cores CPU - - 3G RAM - - 10G Storage - -If you plan to use AWS to install Koding it is recommended that you use at -least a `c3.xlarge` instance. - -### Software - - - [Git](https://git-scm.com) - - [Docker](https://www.docker.com) - - [docker-compose](https://www.docker.com/products/docker-compose) - -Koding can run on most of the UNIX based operating systems, since it's shipped -as containerized with Docker support, it can work on any operating system that -supports Docker. - -Required services are: - -- **PostgreSQL** - Kontrol and Service DB provider -- **MongoDB** - Main DB provider the application -- **Redis** - In memory DB used by both application and services -- **RabbitMQ** - Message Queue for both application and services - -which are also provided as a Docker container by Koding. - - -## Getting Started with Development Versions - - -### Koding - -You can run `docker-compose` environment for developing koding by -executing commands in the following snippet. - -```bash -git clone https://github.com/koding/koding.git -cd koding -docker-compose -f docker-compose-init.yml run init -docker-compose up -``` - -This should start koding on `localhost:8090`. - -By default there is no team exists in Koding DB. You'll need to create a team -called `gitlab` which is the default team name for GitLab integration in the -configuration. To make things in order it's recommended to create the `gitlab` -team first thing after setting up Koding. - - -### GitLab - -To install GitLab to your environment for development purposes it's recommended -to use GitLab Development Kit which you can get it from -[here](https://gitlab.com/gitlab-org/gitlab-development-kit). - -After all those steps, gitlab should be running on `localhost:3000` - - -## Integration - -Integration includes following components; - - - Single Sign On with OAuth from GitLab to Koding - - System Hook integration for handling GitLab events on Koding - (`project_created`, `user_joined` etc.) - - Service endpoints for importing/executing stacks from GitLab to Koding - (`Run/Try on IDE (Koding)` buttons on GitLab Projects, Issues, MRs) - -As it's pointed out before, you will need public access to this machine that -you've installed Koding and GitLab on. Better to use a domain but a static IP -is also fine. - -For IP based installation you can use [nip.io](https://nip.io) service which is -free and provides DNS resolution to IP based requests like following; - - - 127.0.0.1.nip.io -> resolves to 127.0.0.1 - - foo.bar.baz.127.0.0.1.nip.io -> resolves to 127.0.0.1 - - and so on... - -As Koding needs subdomains for team names; `foo.127.0.0.1.nip.io` requests for -a running koding instance on `127.0.0.1` server will be handled as `foo` team -requests. - - -### GitLab Side - -You need to enable Koding integration from Settings under Admin Area. To do -that login with an Admin account and do followings; - -- open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) -- scroll to bottom of the page until Koding section -- check `Enable Koding` checkbox -- provide GitLab team page for running Koding instance as `Koding URL`* - * For `Koding URL` you need to provide the gitlab integration enabled team on -your Koding installation. Team called `gitlab` has integration on Koding out -of the box, so if you didn't change anything your team on Koding should be -`gitlab`. - -So, if your Koding is running on `http://1.2.3.4.nip.io:8090` your URL needs -to be `http://gitlab.1.2.3.4.nip.io:8090`. You need to provide the same host -with your Koding installation here. - - -#### Registering Koding for OAuth integration - -We need `Application ID` and `Secret` to enable login to Koding via GitLab -feature and to do that you need to register running Koding as a new application -to your running GitLab application. Follow -[these](http://docs.gitlab.com/ce/integration/oauth_provider.html) steps to -enable this integration. - -Redirect URI should be `http://gitlab.127.0.0.1:8090/-/oauth/gitlab/callback` -which again you need to _replace `127.0.0.1` with your instance public IP._ - -Take a copy of `Application ID` and `Secret` that is generated by the GitLab -application, we will need those on _Koding Part_ of this guide. - - -#### Registering system hooks to Koding (optional) - -Koding can take actions based on the events generated by GitLab application. -This feature is still in progress and only following events are processed by -Koding at the moment; - - - user_create - - user_destroy - -All system events are handled but not implemented on Koding side. - -To enable this feature you need to provide a `URL` and a `Secret Token` to your -GitLab application. Open your admin area on your GitLab app from -[http://127.0.0.1:3000/admin/hooks](http://127.0.0.1:3000/admin/hooks) -and provide `URL` as `http://gitlab.127.0.0.1:8090/-/api/gitlab` which is the -endpoint to handle GitLab events on Koding side. Provide a `Secret Token` and -keep a copy of it, we will need it on _Koding Part_ of this guide. - -_(replace `127.0.0.1` with your instance public IP)_ - - -### Koding Part - -If you followed the steps in GitLab part we should have followings to enable -Koding part integrations; - - - `Application ID` and `Secret` for OAuth integration - - `Secret Token` for system hook integration - - Public address of running GitLab instance - - -#### Start Koding with GitLab URL - -Now we need to configure Koding with all this information to get things ready. -If it's already running please stop koding first. - -##### From command-line - -Replace followings with the ones you got from GitLab part of this guide; - -```bash -cd koding -docker-compose run \ - --service-ports backend \ - /opt/koding/scripts/bootstrap-container build \ - --host=**YOUR_IP**.nip.io \ - --gitlabHost=**GITLAB_IP** \ - --gitlabPort=**GITLAB_PORT** \ - --gitlabToken=**SECRET_TOKEN** \ - --gitlabAppId=**APPLICATION_ID** \ - --gitlabAppSecret=**SECRET** -``` - -##### By updating configuration - -Alternatively you can update `gitlab` section on -`config/credentials.default.coffee` like following; - -``` -gitlab = - host: '**GITLAB_IP**' - port: '**GITLAB_PORT**' - applicationId: '**APPLICATION_ID**' - applicationSecret: '**SECRET**' - team: 'gitlab' - redirectUri: '' - systemHookToken: '**SECRET_TOKEN**' - hooksEnabled: yes -``` - -and start by only providing the `host`; - -```bash -cd koding -docker-compose run \ - --service-ports backend \ - /opt/koding/scripts/bootstrap-container build \ - --host=**YOUR_IP**.nip.io \ -``` - -#### Enable Single Sign On - -Once you restarted your Koding and logged in with your username and password -you need to activate oauth authentication for your user. To do that - - - Navigate to Dashboard on Koding from; - `http://gitlab.**YOUR_IP**.nip.io:8090/Home/my-account` - - Scroll down to Integrations section - - Click on toggle to turn On integration in GitLab integration section - -This will redirect you to your GitLab instance and will ask your permission ( -if you are not logged in to GitLab at this point you will be redirected after -login) once you accept you will be redirected to your Koding instance. - -From now on you can login by using `SIGN IN WITH GITLAB` button on your Login -screen in your Koding instance. - -[ce-5909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5909 diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 293036f2f4b..b61c5409a56 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -80,10 +80,10 @@ our AsciiDoc snippets, wikis and repos using delimited blocks: ``` [plantuml, format="png", id="myDiagram", width="200px"] - -- + ---- Bob->Alice : hello Alice -> Bob : Go Away - -- + ---- ``` - **reStructuredText** diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 757865ea2c5..a1ea78b64bd 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -1,12 +1,10 @@ # Jobs artifacts administration ->**Notes:** ->- Introduced in GitLab 8.2 and GitLab Runner 0.7.0. ->- Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format - changed to `ZIP`. ->- Starting with GitLab 8.17, builds are renamed to jobs. ->- This is the administration documentation. For the user guide see - [pipelines/job_artifacts](../user/project/pipelines/job_artifacts.md). +> **Notes:** +> - Introduced in GitLab 8.2 and GitLab Runner 0.7.0. +> - Starting with GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format changed to `ZIP`. +> - Starting with GitLab 8.17, builds are renamed to jobs. +> - This is the administration documentation. For the user guide see [pipelines/job_artifacts](../user/project/pipelines/job_artifacts.md). Artifacts is a list of files and directories which are attached to a job after it completes successfully. This feature is enabled by default in all @@ -98,7 +96,7 @@ _The artifacts are stored by default in If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. This configuration relies on valid AWS credentials to be configured already. -Use an [Object storage option][os] like AWS S3 to store job artifacts. +Use an object storage option like AWS S3 to store job artifacts. ### Object Storage Settings @@ -315,4 +313,3 @@ memory and disk I/O. [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository" -[os]: https://docs.gitlab.com/administration/job_artifacts.html#using-object-storage diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 98134075b94..698f4caab3a 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -13,7 +13,7 @@ This guide talks about how to read and use these system log files. This file lives in `/var/log/gitlab/gitlab-rails/production_json.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/production_json.log` for -installations from source. (When Gitlab is running in an environment +installations from source. (When GitLab is running in an environment other than production, the corresponding logfile is shown here.) It contains a structured log for Rails controller requests received from @@ -29,9 +29,9 @@ Each line contains a JSON line that can be ingested by Elasticsearch, Splunk, et In this example, you can see this was a GET request for a specific issue. Notice each line also contains performance data: 1. `duration`: the total time taken to retrieve the request -2. `view`: total time taken inside the Rails views -3. `db`: total time to retrieve data from the database -4. `gitaly_calls`: total number of calls made to Gitaly +1. `view`: total time taken inside the Rails views +1. `db`: total time to retrieve data from the database +1. `gitaly_calls`: total number of calls made to Gitaly User clone/fetch activity using http transport appears in this log as `action: git_upload_pack`. @@ -42,7 +42,7 @@ In addition, the log contains the IP address from which the request originated This file lives in `/var/log/gitlab/gitlab-rails/production.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/production.log` for -installations from source. (When Gitlab is running in an environment +installations from source. (When GitLab is running in an environment other than production, the corresponding logfile is shown here.) It contains information about all performed requests. You can see the @@ -84,7 +84,7 @@ Introduced in GitLab 10.0, this file lives in It helps you see requests made directly to the API. For example: ```json -{"time":"2017-10-10T12:30:11.579Z","severity":"INFO","duration":16.84,"db":1.57,"view":15.27,"status":200,"method":"POST","path":"/api/v4/internal/allowed","params":{"action":"git-upload-pack","changes":"_any","gl_repository":null,"project":"root/foobar.git","protocol":"ssh","env":"{}","key_id":"[FILTERED]","secret_token":"[FILTERED]"},"host":"127.0.0.1","ip":"127.0.0.1","ua":"Ruby"} +{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30} ``` This entry above shows an access to an internal endpoint to check whether an @@ -119,13 +119,32 @@ This file lives in `/var/log/gitlab/gitlab-rails/integrations_json.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/integrations_json.log` for installations from source. -It contains information about [integrations](../user/project/integrations/project_services.md) activities such as JIRA, Asana and Irker services. It uses JSON format like the example below: +It contains information about [integrations](../user/project/integrations/project_services.md) activities such as JIRA, Asana and Irker services. It uses JSON format like the example below: ``` json {"severity":"ERROR","time":"2018-09-06T14:56:20.439Z","service_class":"JiraService","project_id":8,"project_path":"h5bp/html5-boilerplate","message":"Error sending message","client_url":"http://jira.gitlap.com:8080","error":"execution expired"} {"severity":"INFO","time":"2018-09-06T17:15:16.365Z","service_class":"JiraService","project_id":3,"project_path":"namespace2/project2","message":"Successfully posted","client_url":"http://jira.example.net"} ``` +## `kubernetes.log` + +Introduced in GitLab 11.6. This file lives in +`/var/log/gitlab/gitlab-rails/kubernetes.log` for Omnibus GitLab +packages or in `/home/git/gitlab/log/kubernetes.log` for +installations from source. + +It logs information related to the Kubernetes Integration including errors +during installing cluster applications on your GitLab managed Kubernetes +clusters. + +Each line contains a JSON line that can be ingested by Elasticsearch, Splunk, +etc. For example: + +```json +{"severity":"ERROR","time":"2018-11-23T15:14:54.652Z","exception":"Kubeclient::HttpError","error_code":401,"service":"Clusters::Applications::CheckInstallationProgressService","app_id":14,"project_ids":[1],"group_ids":[],"message":"Unauthorized"} +{"severity":"ERROR","time":"2018-11-23T15:42:11.647Z","exception":"Kubeclient::HttpError","error_code":null,"service":"Clusters::Applications::InstallService","app_id":2,"project_ids":[19],"group_ids":[],"message":"SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)"} +``` + ## `githost.log` This file lives in `/var/log/gitlab/gitlab-rails/githost.log` for @@ -144,6 +163,20 @@ December 03, 2014 13:20 -> ERROR -> Command failed [1]: /usr/bin/git --git-dir=/ error: failed to push some refs to '/Users/vsizov/gitlab-development-kit/repositories/gitlabhq/gitlab_git.git' ``` +## `audit_json.log` + +This file lives in `/var/log/gitlab/gitlab-rails/audit_json.log` for +Omnibus GitLab packages or in `/home/git/gitlab/log/audit_json.log` for +installations from source. + +Changes to group or project settings are logged to this file. For example: + +```json +{"severity":"INFO","time":"2018-10-17T17:38:22.523Z","author_id":3,"entity_id":2,"entity_type":"Project","change":"visibility","from":"Private","to":"Public","author_name":"John Doe4","target_id":2,"target_type":"Project","target_details":"namespace2/project2"} +{"severity":"INFO","time":"2018-10-17T17:38:22.830Z","author_id":5,"entity_id":3,"entity_type":"Project","change":"name","from":"John Doe7 / project3","to":"John Doe7 / new name","author_name":"John Doe6","target_id":3,"target_type":"Project","target_details":"namespace3/project3"} +{"severity":"INFO","time":"2018-10-17T17:38:23.175Z","author_id":7,"entity_id":4,"entity_type":"Project","change":"path","from":"","to":"namespace4/newpath","author_name":"John Doe8","target_id":4,"target_type":"Project","target_details":"namespace4/newpath"} +``` + ## `sidekiq.log` This file lives in `/var/log/gitlab/gitlab-rails/sidekiq.log` for @@ -187,7 +220,7 @@ This file lives in `/var/log/gitlab/gitlab-shell/gitlab-shell.log` for Omnibus GitLab packages or in `/home/git/gitlab-shell/gitlab-shell.log` for installations from source. -GitLab shell is used by Gitlab for executing Git commands and provide +GitLab shell is used by GitLab for executing Git commands and provide SSH access to Git repositories. For example: ``` @@ -243,8 +276,8 @@ importer. Future importers may use this file. ## Reconfigure Logs -Reconfigure log files live in `/var/log/gitlab/reconfigure` for Omnibus GitLab -packages. Installations from source don't have reconfigure logs. A reconfigure log +Reconfigure log files live in `/var/log/gitlab/reconfigure` for Omnibus GitLab +packages. Installations from source don't have reconfigure logs. A reconfigure log is populated whenever `gitlab-ctl reconfigure` is run manually or as part of an upgrade. Reconfigure logs files are named according to the UNIX timestamp of when the reconfigure diff --git a/doc/administration/monitoring/performance/img/request_profiling_token.png b/doc/administration/monitoring/performance/img/request_profiling_token.png Binary files differindex 8c4109c17f0..a9160b62acb 100644 --- a/doc/administration/monitoring/performance/img/request_profiling_token.png +++ b/doc/administration/monitoring/performance/img/request_profiling_token.png diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md index c30cd2950d8..fa281f47ed8 100644 --- a/doc/administration/monitoring/performance/influxdb_configuration.md +++ b/doc/administration/monitoring/performance/influxdb_configuration.md @@ -95,10 +95,10 @@ UDP can be done using the following settings: This does the following: 1. Enable UDP and bind it to port 8089 for all addresses. -2. Store any data received in the "gitlab" database. -3. Define a batch of points to be 1000 points in size and allow a maximum of +1. Store any data received in the "gitlab" database. +1. Define a batch of points to be 1000 points in size and allow a maximum of 5 batches _or_ flush them automatically after 1 second. -4. Define a UDP read buffer size of 200 MB. +1. Define a UDP read buffer size of 200 MB. One of the most important settings here is the UDP read buffer size as if this value is set too low, packets will be dropped. You must also make sure the OS diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index dc4f685d843..6a55dbe1eb4 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -26,8 +26,8 @@ page was open. Only the first two requests per unique URL are captured. ## Enable the Performance Bar via the Admin panel GitLab Performance Bar is disabled by default. To enable it for a given group, -navigate to the Admin area in **Settings > Profiling - Performance Bar** -(`/admin/application_settings`). +navigate to the Admin area in **Settings > Metrics and Profiling > Profiling - Performance bar** +(`admin/application_settings/metrics_and_profiling`). The only required setting you need to set is the full path of the group that will be allowed to display the Performance Bar. diff --git a/doc/administration/monitoring/performance/request_profiling.md b/doc/administration/monitoring/performance/request_profiling.md index c358dfbead2..dfd9be3d04c 100644 --- a/doc/administration/monitoring/performance/request_profiling.md +++ b/doc/administration/monitoring/performance/request_profiling.md @@ -1,16 +1,17 @@ # Request Profiling ## Procedure + 1. Grab the profiling token from `Monitoring > Requests Profiles` admin page -(highlighted in a blue in the image below). - -1. Pass the header `X-Profile-Token: <token>` to the request you want to profile. You can use any of these tools - * [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj) Chrome extension - * [Modify Headers](https://addons.mozilla.org/en-US/firefox/addon/modify-headers/) Firefox extension - * `curl --header 'X-Profile-Token: <token>' https://gitlab.example.com/group/project` + (highlighted in a blue in the image below). +  +1. Pass the header `X-Profile-Token: <token>` to the request you want to profile. You can use: + - Browser extensions. For example, [ModHeader](https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj) Chrome extension. + - `curl`. For example, `curl --header 'X-Profile-Token: <token>' https://gitlab.example.com/group/project`. 1. Once request is finished (which will take a little longer than usual), you can -view the profiling output from `Monitoring > Requests Profiles` admin page. - + view the profiling output from `Monitoring > Requests Profiles` admin page. +  ## Cleaning up + Profiling output will be cleared out every day via a Sidekiq worker. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 7bc92ae77ee..c9a2778b3a4 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -45,9 +45,7 @@ The following metrics are available: | redis_ping_success | Gauge | 9.4 | Whether or not the last redis ping succeeded | | redis_ping_latency_seconds | Gauge | 9.4 | Round trip time of the redis ping | | user_session_logins_total | Counter | 9.4 | Counter of how many users have logged in | -| filesystem_circuitbreaker_latency_seconds | Gauge | 9.5 | Time spent validating if a storage is accessible | -| filesystem_circuitbreaker | Gauge | 9.5 | Whether or not the circuit for a certain shard is broken or not | -| circuitbreaker_storage_check_duration_seconds | Histogram | 10.3 | Time a single storage probe took | +| upload_file_does_not_exist | Counter | 10.7 in EE, 11.5 in CE | Number of times an upload record could not find its file | | failed_login_captcha_total | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | successful_login_captcha_total | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index b1b670c3b42..8f65cd6418c 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,4 +1,4 @@ -# GitLab Prometheus +# Monitoring GitLab with Prometheus > **Notes:** > - Prometheus and the various exporters listed in this page are bundled in the @@ -24,10 +24,10 @@ dashboard tool like [Grafana]. ## Configuring Prometheus ->**Note:** +NOTE: **Note:** For installations from source you'll have to install and configure it yourself. -Prometheus and it's exporters are on by default, starting with GitLab 9.0. +Prometheus and its exporters are on by default, starting with GitLab 9.0. Prometheus will run as the `gitlab-prometheus` user and listen on `http://localhost:9090`. By default Prometheus is only accessible from the GitLab server itself. Each exporter will be automatically set up as a @@ -43,17 +43,17 @@ To disable Prometheus and all of its exporters, as well as any added in the futu ``` 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to - take effect + take effect. -## Changing the port and address Prometheus listens on +### Changing the port and address Prometheus listens on ->**Note:** +NOTE: **Note:** The following change was added in [GitLab Omnibus 8.17][1261]. Although possible, it's not recommended to change the port Prometheus listens on as this might affect or conflict with other services running on the GitLab server. Proceed at your own risk. -In order to access Prometheus from outside the GitLab server you will need to +In order to access Prometheus from outside the GitLab server you will need to set a FQDN or IP in `prometheus['listen_address']`. To change the address/port that Prometheus listens on: @@ -77,6 +77,60 @@ To change the address/port that Prometheus listens on: 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to take effect +### Using an external Prometheus server + +NOTE: **Note:** +Prometheus and most exporters do not support authentication. We do not recommend exposing them outside the local network. + +A few configuration changes are required to allow GitLab to be monitored by an external Prometheus server. External servers are recommended for highly available deployments of GitLab with multiple nodes. + +To use an external Prometheus server: + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Disable the bundled Prometheus: + + ```ruby + prometheus['enable'] = false + ``` + +1. Set each bundled service's [exporter](#bundled-software-metrics) to listen on a network address, for example: + + ```ruby + gitlab_monitor['listen_address'] = '0.0.0.0' + gitlab_monitor['listen_port'] = '9168' + gitaly['prometheus_listen_addr'] = "0.0.0.0:9236" + node_exporter['listen_address'] = '0.0.0.0:9100' + redis_exporter['listen_address'] = '0.0.0.0:9121' + postgres_exporter['listen_address'] = '0.0.0.0:9187' + ``` + +1. Install and set up a dedicated Prometheus instance, if necessary, using the [official installation instructions](https://prometheus.io/docs/prometheus/latest/installation/). +1. Add the Prometheus server IP address to the [monitoring IP whitelist](../ip_whitelist.html). For example: + + ```ruby + gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1'] + ``` + +1. [Reconfigure GitLab][reconfigure] to apply the changes +1. Edit the Prometheus server's configuration file. +1. Add each node's exporters to the Prometheus server's + [scrape target configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Cscrape_config%3E). + For example, a sample snippet using `static_configs`: + + ```yaml + scrape_configs: + - job_name: 'gitlab_exporters' + static_configs: + - targets: ['1.1.1.1:9168', '1.1.1.1:9236', '1.1.1.1:9236', '1.1.1.1:9100', '1.1.1.1:9121', '1.1.1.1:9187'] + + - job_name: 'gitlab_metrics' + metrics_path: /-/metrics + static_configs: + - targets: ['1.1.1.1:443'] + ``` + +1. Restart the Prometheus server. + ## Viewing performance metrics You can visit `http://localhost:9090` for the dashboard that Prometheus offers by default. @@ -86,7 +140,7 @@ If SSL has been enabled on your GitLab instance, you may not be able to access Prometheus on the same browser as GitLab if using the same FQDN due to [HSTS][hsts]. We plan to [provide access via GitLab][multi-user-prometheus], but in the interim there are some workarounds: using a separate FQDN, using server IP, using a separate browser for Prometheus, resetting HSTS, or -having [Nginx proxy it][nginx-custom-config]. +having [NGINX proxy it][nginx-custom-config]. The performance data collected by Prometheus can be viewed directly in the Prometheus console or through a compatible dashboard tool. @@ -102,26 +156,21 @@ Sample Prometheus queries: - **Data transmitted:** `rate(node_network_transmit_bytes_total{device!="lo"}[5m])` - **Data received:** `rate(node_network_receive_bytes_total{device!="lo"}[5m])` -## Configuring Prometheus to monitor Kubernetes +## Prometheus as a Grafana data source -> Introduced in GitLab 9.0. -> Pod monitoring introduced in GitLab 9.4. +Grafana allows you to import Prometheus performance metrics as a data source +and render the metrics as graphs and dashboards which is helpful with visualisation. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. +To add a Prometheus dashboard for a single server GitLab setup: -To disable the monitoring of Kubernetes: +1. Create a new data source in Grafana. +1. Name your data source i.e GitLab. +1. Select `Prometheus` in the type drop down. +1. Add your Prometheus listen address as the URL and set access to `Browser`. +1. Set the HTTP method to `GET`. +1. Save & Test your configuration to verify that it works. -1. Edit `/etc/gitlab/gitlab.rb` -1. Add or find and uncomment the following line and set it to `false`: - - ```ruby - prometheus['monitor_kubernetes'] = false - ``` - -1. Save the file and [reconfigure GitLab][reconfigure] for the changes to - take effect - -## GitLab Prometheus metrics +## GitLab metrics > Introduced in GitLab 9.3. @@ -129,17 +178,10 @@ GitLab monitors its own internal service metrics, and makes them available at th [➔ Read more about the GitLab Metrics.](gitlab_metrics.md) -## Prometheus exporters - -There are a number of libraries and servers which help in exporting existing -metrics from third-party systems as Prometheus metrics. This is useful for cases -where it is not feasible to instrument a given system with Prometheus metrics -directly (for example, HAProxy or Linux system stats). You can read more in the -[Prometheus exporters and integrations upstream documentation][prom-exporters]. +## Bundled software metrics -While you can use any exporter you like with your GitLab installation, the -following ones documented here are bundled in the Omnibus GitLab packages -making it easy to configure and use. +Many of the GitLab dependencies bundled in Omnibus GitLab are preconfigured to +export Prometheus metrics. ### Node exporter @@ -166,6 +208,25 @@ The GitLab monitor exporter allows you to measure various GitLab metrics, pulled [➔ Read more about the GitLab monitor exporter.](gitlab_monitor_exporter.md) +## Configuring Prometheus to monitor Kubernetes + +> Introduced in GitLab 9.0. +> Pod monitoring introduced in GitLab 9.4. + +If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/operating/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][prometheus integration] to monitor them. + +To disable the monitoring of Kubernetes: + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Add or find and uncomment the following line and set it to `false`: + + ```ruby + prometheus['monitor_kubernetes'] = false + ``` + +1. Save the file and [reconfigure GitLab][reconfigure] for the changes to + take effect. + [grafana]: https://grafana.net [hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security [multi-user-prometheus]: https://gitlab.com/gitlab-org/multi-user-prometheus diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index eada7b19dcd..c293df3fc57 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -5,7 +5,7 @@ NOTE: **Note:** This document describes a drop-in replacement for the using [ssh certificates](ssh_certificates.md), they are even faster, but are not a drop-in replacement. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1631) in +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1631) in > [GitLab Starter](https://about.gitlab.com/gitlab-ee) 9.3. > > [Available in](https://gitlab.com/gitlab-org/gitlab-ee/issues/3953) GitLab @@ -109,7 +109,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: yum install rpm-build gcc make wget openssl-devel krb5-devel pam-devel libX11-devel xmkmf libXt-devel ``` -3. Prepare the build by copying files to the right place: +1. Prepare the build by copying files to the right place: ``` mkdir -p /root/rpmbuild/{SOURCES,SPECS} @@ -118,7 +118,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: cd /root/rpmbuild/SPECS ``` -3. Next, set the spec settings properly: +1. Next, set the spec settings properly: ``` sed -i -e "s/%define no_gnome_askpass 0/%define no_gnome_askpass 1/g" openssh.spec @@ -126,13 +126,13 @@ the database. The following instructions can be used to build OpenSSH 7.5: sed -i -e "s/BuildPreReq/BuildRequires/g" openssh.spec ``` -3. Build the RPMs: +1. Build the RPMs: ``` rpmbuild -bb openssh.spec ``` -4. Ensure the RPMs were built: +1. Ensure the RPMs were built: ``` ls -al /root/rpmbuild/RPMS/x86_64/ @@ -150,7 +150,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: -rw-r--r--. 1 root root 367516 Jun 20 19:37 openssh-server-7.5p1-1.x86_64.rpm ``` -5. Install the packages. OpenSSH packages will replace `/etc/pam.d/sshd` +1. Install the packages. OpenSSH packages will replace `/etc/pam.d/sshd` with its own version, which may prevent users from logging in, so be sure that the file is backed up and restored after installation: @@ -161,7 +161,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: yes | cp pam-ssh-conf-$timestamp /etc/pam.d/sshd ``` -6. Verify the installed version. In another window, attempt to login to the server: +1. Verify the installed version. In another window, attempt to login to the server: ``` ssh -v <your-centos-machine> @@ -171,7 +171,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: If not, you may need to restart sshd (e.g. `systemctl restart sshd.service`). -7. *IMPORTANT!* Open a new SSH session to your server before exiting to make +1. *IMPORTANT!* Open a new SSH session to your server before exiting to make sure everything is working! If you need to downgrade, simple install the older package: diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md new file mode 100644 index 00000000000..44018e966e0 --- /dev/null +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -0,0 +1,55 @@ +# Filesystem Performance Benchmarking + +Filesystem performance has a big impact on overall GitLab performance, +especially for actions that read or write to Git repositories. This information +will help benchmark filesystem performance against known good and bad real-world +systems. + +Normally when talking about filesystem performance the biggest concern is +with Network Filesystems (NFS). However, even some local disks can have slow +IO. The information on this page can be used for either scenario. + +## Write Performance + +The following one-line command is a quick benchmark for filesystem write +performance. This will write 1,000 small files to the directory in which it is +executed. + +1. Change into the root of the appropriate + [repository storage path](../repository_storage_paths.md). +1. Create a temporary directory for the test so it's easy to remove the files later: + + ```sh + mkdir test; cd test + ``` +1. Run the command: + + ```sh + time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + ``` +1. Remove the test files: + + ```sh + cd ../; rm -rf test + ``` + +The output of the `time for ...` command will look similar to the following. The +important metric is the `real` time. + +```sh +$ time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + +real 0m0.116s +user 0m0.025s +sys 0m0.091s +``` + +From experience with multiple customers, the following are ranges that indicate +whether your filesystem performance is satisfactory or less than ideal: + +| Rating | Benchmark result | +|:----------|:------------------------| +| Best | Less than 10 seconds | +| OK | 10-18 seconds | +| Poor | 18-25 seconds | +| Very poor | Greater than 25 seconds | diff --git a/doc/administration/operations/img/sidekiq_job_throttling.png b/doc/administration/operations/img/sidekiq_job_throttling.png Binary files differdeleted file mode 100644 index abd09f3b115..00000000000 --- a/doc/administration/operations/img/sidekiq_job_throttling.png +++ /dev/null diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index e9cad99c4b0..a16fc7ae74f 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -9,8 +9,6 @@ GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis database after you upgrade to GitLab 7.3. - [Moving repositories](moving_repositories.md): Moving all repositories managed by GitLab to another file system or another server. -- [Sidekiq job throttling](sidekiq_job_throttling.md): Throttle Sidekiq queues -that to prioritize important jobs. - [Sidekiq MemoryKiller](sidekiq_memory_killer.md): Configure Sidekiq MemoryKiller to restart Sidekiq. - [Unicorn](unicorn.md): Understand Unicorn and unicorn-worker-killer. @@ -18,3 +16,7 @@ to restart Sidekiq. indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). +- [Filesystem Performance Benchmarking](filesystem_benchmarking.md): Filesystem +performance can have a big impact on GitLab performance, especially for actions +that read or write Git repositories. This information will help benchmark +filesystem performance against known good and bad real-world systems. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 54adb99386a..ec11a92db1b 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -22,9 +22,8 @@ However, it is not possible to resume an interrupted tar pipe: if that happens then all data must be copied again. ``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - tar -C /mnt/gitlab/repositories -xf - +sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + tar -C /mnt/gitlab/repositories -xf -' ``` If you want to see progress, replace `-xf` with `-xvf`. @@ -36,9 +35,8 @@ You can also use a tar pipe to copy data to another server. If your can pipe the data through SSH. ``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - ssh git@newserver tar -C /mnt/gitlab/repositories -xf - +sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + ssh git@newserver tar -C /mnt/gitlab/repositories -xf -' ``` If you want to compress the data before it goes over the network @@ -53,9 +51,8 @@ is either already installed on your system or easily installable via apt, yum etc. ``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - /mnt/gitlab/repositories +sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + /mnt/gitlab/repositories' ``` The `/.` in the command above is very important, without it you can @@ -68,9 +65,8 @@ If the 'git' user on your source system has SSH access to the target server you can send the repositories over the network with rsync. ``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - git@newserver:/mnt/gitlab/repositories +sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + git@newserver:/mnt/gitlab/repositories' ``` ## Thousands of Git repositories: use one rsync per repository @@ -125,7 +121,7 @@ sudo -u git -H sh -c 'bundle exec rake gitlab:list_repos > /home/git/transfer-lo Now we can start the transfer. The command below is idempotent, and the number of jobs done by GNU Parallel should converge to zero. If it -does not some repositories listed in all-repos-1234.txt may have been +does not, some repositories listed in `all-repos-1234.txt` may have been deleted/renamed before they could be copied. ``` @@ -155,8 +151,8 @@ cat /home/git/transfer-logs/* | sort | uniq -u |\ Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. Then you might only want to sync repositories that were changed via GitLab -_after_ that time. You can use the 'SINCE' variable to tell 'rake -gitlab:list_repos' to only print repositories with recent activity. +_after_ that time. You can use the `SINCE` variable to tell `rake +gitlab:list_repos` to only print repositories with recent activity. ``` # Omnibus diff --git a/doc/administration/operations/sidekiq_job_throttling.md b/doc/administration/operations/sidekiq_job_throttling.md deleted file mode 100644 index ddeaa22e288..00000000000 --- a/doc/administration/operations/sidekiq_job_throttling.md +++ /dev/null @@ -1,33 +0,0 @@ -# Sidekiq Job throttling - -> Note: Introduced with GitLab 8.14 - -When your GitLab installation needs to handle tens of thousands of background -jobs, it can be convenient to throttle queues that do not need to be executed -immediately, e.g. long running jobs like Pipelines, thus allowing jobs that do -need to be executed immediately to have access to more resources. - -In order to accomplish this, you can limit the amount of workers that certain -slow running queues can have available. This is what we call Sidekiq Job -Throttling. Depending on your infrastructure, you might have different slow -running queues, which is why you can choose which queues you want to throttle -and by how much you want to throttle them. - -These settings are available in the Application Settings of your GitLab -installation. - - - -The throttle factor determines the maximum number of workers a queue can run on. -This value gets multiplied by `:concurrency` value set in the Sidekiq settings -and rounded up to the closest full integer. - -So, for example, you set the `:concurrency` to 25 and the `Throttling factor` to -0.1, the maximum workers assigned to the selected queues would be 3. - -```ruby -queue_limit = (factor * Sidekiq.options[:concurrency]).ceil -``` - -After enabling the job throttling, you will need to restart your GitLab -instance, in order for the changes to take effect.
\ No newline at end of file diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 9edccd25ced..b00301fec1c 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -31,7 +31,7 @@ uploading user SSH keys to GitLab entirely. ## Setting up SSH certificate lookup via GitLab Shell -How to fully setup SSH certificates is outside the scope of this +How to fully set up SSH certificates is outside the scope of this document. See [OpenSSH's PROTOCOL.certkeys](https://cvsweb.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/PROTOCOL.certkeys?annotate=HEAD) for how it works, and e.g. [RedHat's documentation about @@ -132,7 +132,7 @@ message about this being an invalid user. ## Interaction with the `authorized_keys` file SSH certificates can be used in conjunction with the `authorized_keys` -file, and if setup as configured above the `authorized_keys` file will +file, and if set up as configured above the `authorized_keys` file will still serve as a fallback. This is because if the `AuthorizedPrincipalsCommand` can't diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 3af0a5759a7..cbd3032bd4e 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -92,9 +92,8 @@ where `example.io` is the domain under which GitLab Pages will be served and `192.0.2.1` is the IPv4 address of your GitLab instance and `2001::1` is the IPv6 address. If you don't have IPv6, you can omit the AAAA record. -> **Note:** -You should not use the GitLab domain to serve user pages. For more information -see the [security section](#security). +NOTE: **Note:** +You should not use the GitLab domain to serve user pages. For more information see the [security section](#security). [wiki-wildcard-dns]: https://en.wikipedia.org/wiki/Wildcard_DNS_record @@ -107,12 +106,13 @@ since that is needed in all configurations. ### Wildcard domains -> **Requirements:** -> - [Wildcard DNS setup](#dns-configuration) -> -> --- -> -> URL scheme: `http://page.example.io` +**Requirements:** + +- [Wildcard DNS setup](#dns-configuration) + +--- + +URL scheme: `http://page.example.io` This is the minimum setup that you can use Pages with. It is the base for all other setups as described below. Nginx will proxy all requests to the daemon. @@ -126,18 +126,18 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab][reconfigure] - Watch the [video tutorial][video-admin] for this configuration. ### Wildcard domains with TLS support -> **Requirements:** -> - [Wildcard DNS setup](#dns-configuration) -> - Wildcard TLS certificate -> -> --- -> -> URL scheme: `https://page.example.io` +**Requirements:** + +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate + +--- + +URL scheme: `https://page.example.io` Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the outside world. @@ -168,13 +168,14 @@ you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains -> **Requirements:** -> - [Wildcard DNS setup](#dns-configuration) -> - Secondary IP -> -> --- -> -> URL scheme: `http://page.example.io` and `http://domain.com` +**Requirements:** + +- [Wildcard DNS setup](#dns-configuration) +- Secondary IP + +--- + +URL scheme: `http://page.example.io` and `http://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -197,14 +198,15 @@ world. Custom domains are supported, but no TLS. ### Custom domains with TLS support -> **Requirements:** -> - [Wildcard DNS setup](#dns-configuration) -> - Wildcard TLS certificate -> - Secondary IP -> -> --- -> -> URL scheme: `https://page.example.io` and `https://domain.com` +**Requirements:** + +- [Wildcard DNS setup](#dns-configuration) +- Wildcard TLS certificate +- Secondary IP + +--- + +URL scheme: `https://page.example.io` and `https://domain.com` In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside @@ -240,6 +242,35 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck **Require users to prove ownership of custom domains** in the Pages section. This setting is enabled by default. +### Access control + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. + +GitLab Pages access control can be configured per-project, and allows access to a Pages +site to be controlled based on a user's membership to that project. + +Access control works by registering the Pages daemon as an OAuth application +with GitLab. Whenever a request to access a private Pages site is made by an +unauthenticated user, the Pages daemon redirects the user to GitLab. If +authentication is successful, the user is redirected back to Pages with a token, +which is persisted in a cookie. The cookies are signed with a secret key, so +tampering can be detected. + +Each request to view a resource in a private site is authenticated by Pages +using that token. For each request it receives, it makes a request to the GitLab +API to check that the user is authorized to read that site. + +Pages access control is disabled by default. To enable it: + +1. Enable it in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['access_control'] = true + ``` + +1. [Reconfigure GitLab][reconfigure]. +1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control-core-only). + ## Activate verbose logging for daemon Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/2533) in @@ -320,12 +351,12 @@ latest previous version. --- -**GitLab 8.17 ([documentation][8-17-docs])** +**GitLab 8.17 ([documentation](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/doc/administration/pages/index.md))** - GitLab Pages were ported to Community Edition in GitLab 8.17. - Documentation was refactored to be more modular and easy to follow. -**GitLab 8.5 ([documentation][8-5-docs])** +**GitLab 8.5 ([documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md))** - In GitLab 8.5 we introduced the [gitlab-pages][] daemon which is now the recommended way to set up GitLab Pages. @@ -334,13 +365,10 @@ latest previous version. - Custom CNAME and TLS certificates support. - Documentation was moved to one place. -**GitLab 8.3 ([documentation][8-3-docs])** +**GitLab 8.3 ([documentation](https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md))** - GitLab Pages feature was introduced. -[8-3-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-3-stable-ee/doc/pages/administration.md -[8-5-docs]: https://gitlab.com/gitlab-org/gitlab-ee/blob/8-5-stable-ee/doc/pages/administration.md -[8-17-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable-ce/doc/administration/pages/index.md [backup]: ../../raketasks/backup_restore.md [ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605 [ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 295905a7625..9f2b4d9075a 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -391,6 +391,49 @@ the first one with a backslash (\). For example `pages.example.io` would be: server_name ~^.*\.pages\.example\.io$; ``` +## Access control + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. + +GitLab Pages access control can be configured per-project, and allows access to a Pages +site to be controlled based on a user's membership to that project. + +Access control works by registering the Pages daemon as an OAuth application +with GitLab. Whenever a request to access a private Pages site is made by an +unauthenticated user, the Pages daemon redirects the user to GitLab. If +authentication is successful, the user is redirected back to Pages with a token, +which is persisted in a cookie. The cookies are signed with a secret key, so +tampering can be detected. + +Each request to view a resource in a private site is authenticated by Pages +using that token. For each request it receives, it makes a request to the GitLab +API to check that the user is authorized to read that site. + +Pages access control is disabled by default. To enable it: + +1. Modify your `config/gitlab.yml` file: + + ```yaml + pages: + access_control: true + ``` + +1. [Restart GitLab][restart]. +1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile). + This should be called `GitLab Pages` and have a `Redirect URL` of + `https://projects.example.io/auth`. It does not need to be a "trusted" + application, but it does need the "api" scope. +1. Start the Pages daemon with the following additional arguments: + + ```shell + -auth-client-secret <OAuth code generated by GitLab> \ + -auth-redirect-uri http://projects.example.io/auth \ + -auth-secret <40 random hex characters> \ + -auth-server <URL of the GitLab instance> + ``` + +1. Users can now configure it in their [projects' settings](../../user/project/pages/introduction.md#gitlab-pages-access-control-core-only). + ## Change storage path Follow the steps below to change the default path where GitLab Pages' contents diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 6b8ad1b039b..ccd9c0afb1d 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -1,37 +1,41 @@ # GitHub import ->**Note:** -> -> - [Introduced][ce-10308] in GitLab 9.1. -> - You need a personal access token in order to retrieve and import GitHub -> projects. You can get it from: https://github.com/settings/tokens -> - You also need to pass an username as the second argument to the rake task -> which will become the owner of the project. -> - You can also resume an import with the same command. +> [Introduced]( https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308) in GitLab 9.1. + +In order to retrieve and import GitHub repositories, you will need a +[GitHub personal access token](https://github.com/settings/tokens). +A username should be passed as the second argument to the rake task +which will become the owner of the project. You can resume an import +with the same command. + +Bear in mind that the syntax is very specific. Remove any spaces within the argument block and +before/after the brackets. Also, Some shells (e.g., zsh) can interpret the open/close brackets +(`[]`) separately. You may need to either escape the brackets or use double quotes. + +## Importing multiple projects To import a project from the list of your GitHub projects available: ```bash # Omnibus installations -sudo gitlab-rake import:github[access_token,root,foo/bar] +sudo gitlab-rake "import:github[access_token,root,foo/bar]" # Installations from source -bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production +bundle exec rake "import:github[access_token,root,foo/bar]" RAILS_ENV=production ``` In this case, `access_token` is your GitHub personal access token, `root` is your GitLab username, and `foo/bar` is the new GitLab namespace/project that will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. +## Importing a single project To import a specific GitHub project (named `foo/github_repo` here): ```bash # Omnibus installations -sudo gitlab-rake import:github[access_token,root,foo/bar,foo/github_repo] +sudo gitlab-rake "import:github[access_token,root,foo/bar,foo/github_repo]" # Installations from source -bundle exec rake import:github[access_token,root,foo/bar,foo/github_repo] RAILS_ENV=production +bundle exec rake "import:github[access_token,root,foo/bar,foo/github_repo]" RAILS_ENV=production ``` - -[ce-10308]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308 diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 2b4252a7b1d..0d863594fc7 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -53,14 +53,15 @@ Git: /usr/bin/git Runs the following rake tasks: - `gitlab:gitlab_shell:check` +- `gitlab:gitaly:check` - `gitlab:sidekiq:check` - `gitlab:app:check` -It will check that each component was setup according to the installation guide and suggest fixes for issues found. +It will check that each component was set up according to the installation guide and suggest fixes for issues found. -You may also have a look at our Trouble Shooting Guides: -- [Trouble Shooting Guide (GitLab)](http://docs.gitlab.com/ee/README.html#troubleshooting) -- [Trouble Shooting Guide (Omnibus Gitlab)](http://docs.gitlab.com/omnibus/README.html#troubleshooting) +You may also have a look at our Troubleshooting Guides: +- [Troubleshooting Guide (GitLab)](http://docs.gitlab.com/ee/README.html#troubleshooting) +- [Troubleshooting Guide (Omnibus Gitlab)](http://docs.gitlab.com/omnibus/README.html#troubleshooting) **Omnibus Installation** @@ -252,7 +253,7 @@ clear it. To clear all exclusive leases: -DANGER: **DANGER**: +DANGER: **DANGER**: Don't run it while GitLab or Sidekiq is running ```bash diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 426245c7aca..6d7069dd461 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -5,7 +5,7 @@ replying to notification emails. ## Requirement -Make sure [incoming email](incoming_email.md) is setup. +Make sure [incoming email](incoming_email.md) is set up. ## How it works? diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index 3e8b78e56d5..4c42cb7756a 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -8,7 +8,7 @@ The instructions make the assumption that you will be using the email address `i ## Configure your server firewall 1. Open up port 25 on your server so that people can send email into the server over SMTP. -2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP. +1. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP. ## Install packages @@ -245,7 +245,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo 220 gitlab.example.com ESMTP Postfix (Ubuntu) ``` - If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25. + If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25. 1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index efeec9db517..8b725e50f58 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -18,7 +18,8 @@ repositories and wiki repositories in order to detect data corruption. A project will be checked no more than once per month. If any projects fail their repository checks all GitLab administrators will receive an email notification of the situation. This notification is sent out once a week, -by default, midnight at the start of Sunday. +by default, midnight at the start of Sunday. Repositories with known check +failures can be found at `/admin/projects?last_repository_check_failed=1`. ## Disabling periodic checks @@ -30,7 +31,7 @@ panel. If the repository check fails for some repository you should look up the error in `repocheck.log`: -- in the [admin panel](logs.md#repocheck.log) +- in the [admin panel](logs.md#repocheck-log) - or on disk, see: - `/var/log/gitlab/gitlab-rails` for Omnibus installations - `/home/git/gitlab/log` for installations from source diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 7ea7ed48850..c03f23a8931 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -97,55 +97,6 @@ be stored via the **Application Settings** in the Admin area. Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be randomly placed on one of the selected paths. -## Handling failing repository storage - -> [Introduced][ce-11449] in GitLab 9.5. - -When GitLab detects access to the repositories storage fails repeatedly, it can -gracefully prevent attempts to access the storage. This might be useful when -the repositories are stored somewhere on the network. - -This can be configured from the admin interface: - - - -**Number of access attempts**: The number of attempts GitLab will make to access a -storage when probing a shard. - -**Number of failures before backing off**: The number of failures after which -GitLab will start temporarily disabling access to a storage shard on a host. - -**Maximum git storage failures:** The number of failures of after which GitLab will -completely prevent access to the storage. The number of failures can be reset in -the admin interface: `https://gitlab.example.com/admin/health_check` or using the -[api](../api/repository_storage_health.md) to allow access to the storage again. - -**Seconds to wait after a storage failure:** When access to a storage fails. GitLab -will prevent access to the storage for the time specified here. This allows the -filesystem to recover. - -**Seconds before reseting failure information:** The time in seconds GitLab will -keep failure information. When no failures occur during this time, information about the -mount is reset. - -**Seconds to wait for a storage access attempt:** The time in seconds GitLab will -try to access storage. After this time a timeout error will be raised. - -To enable the circuitbreaker for repository storage you can flip the feature flag from a rails console: - -``` -Feature.enable('git_storage_circuit_breaker') -``` - -Alternatively it can be enabled by setting `true` in the `GIT_STORAGE_CIRCUIT_BREAKER` environment variable. -This approach would be used when enabling the circuit breaker on a single host. - -When storage failures occur, this will be visible in the admin interface like this: - - - -To allow access to all storages, click the `Reset git storage health information` button. - [ce-4578]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4578 [restart-gitlab]: restart_gitlab.md#installations-from-source [reconfigure-gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index bd758c49eba..9379944b250 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -41,11 +41,8 @@ Registry, etc. ## Hashed Storage -> **Warning:** Hashed storage is in **Beta**. For the latest updates, check the -> associated [issue](https://gitlab.com/gitlab-com/infrastructure/issues/3542) -> and please report any problems you encounter. -Hashed Storage is the new storage behavior we are rolling out with 10.0. Instead +Hashed Storage is the new storage behavior we rolled out with 10.0. Instead of coupling project URL and the folder structure where the repository will be stored on disk, we are coupling a hash, based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index 2902af8c782..643c5b9fe80 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -20,7 +20,7 @@ an SMTP server, but you're not seeing mail delivered. Here's how to check the se bundle exec rails console production ``` -2. Look at the ActionMailer `delivery_method` to make sure it matches what you +1. Look at the ActionMailer `delivery_method` to make sure it matches what you intended. If you configured SMTP, it should say `:smtp`. If you're using Sendmail, it should say `:sendmail`: @@ -29,7 +29,7 @@ an SMTP server, but you're not seeing mail delivered. Here's how to check the se => :smtp ``` -3. If you're using SMTP, check the mail settings: +1. If you're using SMTP, check the mail settings: ```ruby irb(main):002:0> ActionMailer::Base.smtp_settings @@ -39,7 +39,7 @@ an SMTP server, but you're not seeing mail delivered. Here's how to check the se In the example above, the SMTP server is configured for the local machine. If this is intended, you may need to check your local mail logs (e.g. `/var/log/mail.log`) for more details. -4. Send a test message via the console. +1. Send a test message via the console. ```ruby irb(main):003:0> Notify.test_email('youremail@email.com', 'Hello World', 'This is a test message').deliver_now diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index ce83da16067..f85a1f791f9 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -18,7 +18,7 @@ below. >**Notes:** For historical reasons, uploads are stored into a base directory, which by default is `uploads/-/system`. It is strongly discouraged to change this configuration option on an existing GitLab installation. -_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/public/uploads/-/system`._ +_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads/-/system`._ 1. To change the storage path for example to `/mnt/storage/uploads`, edit `/etc/gitlab/gitlab.rb` and add the following line: @@ -48,11 +48,12 @@ _The uploads are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. -### Using object storage +### Using object storage **[CORE ONLY]** > **Notes:** > -> - [Introduced][ee-3867] in [GitLab Enterprise Edition Premium][eep] 10.5. +> - [Introduced][ee-3867] in [GitLab Premium][eep] 10.5. +> - [Introduced][ce17358] in [GitLab Core][ce] 10.7. > - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the @@ -197,4 +198,6 @@ _The uploads are stored by default in [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [eep]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition Premium" +[ce]: https://about.gitlab.com/gitlab-ce/ "GitLab Community Edition" [ee-3867]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3867 +[ce-17358]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17358 diff --git a/doc/api/README.md b/doc/api/README.md index a3589377e9d..b49c3a198f1 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -20,10 +20,11 @@ following locations: - [Custom Attributes](custom_attributes.md) - [Deployments](deployments.md) - [Deploy Keys](deploy_keys.md) +- [Dockerfile templates](templates/dockerfiles.md) - [Environments](environments.md) - [Events](events.md) - [Feature flags](features.md) -- [Gitignores templates](templates/gitignores.md) +- [Gitignore templates](templates/gitignores.md) - [GitLab CI Config templates](templates/gitlab_ci_ymls.md) - [Groups](groups.md) - [Group Access Requests](access_requests.md) @@ -55,10 +56,12 @@ following locations: - [Project import/export](project_import_export.md) - [Project Members](members.md) - [Project Snippets](project_snippets.md) +- [Project Templates](project_templates.md) - [Protected Branches](protected_branches.md) - [Protected Tags](protected_tags.md) - [Repositories](repositories.md) - [Repository Files](repository_files.md) +- [Repository Submodules](repository_submodules.md) - [Runners](runners.md) - [Search](search.md) - [Services](services.md) @@ -67,6 +70,7 @@ following locations: - [System Hooks](system_hooks.md) - [Tags](tags.md) - [Todos](todos.md) +- [Triggering Pipelines](../ci/triggers/README.md) - [Users](users.md) - [Validate CI configuration](lint.md) - [V3 to V4](v3_to_v4.md) @@ -101,7 +105,7 @@ not explicit. This allows for a stable API endpoint, but also means new features can be added to the API in the same version number. New features and bug fixes are released in tandem with a new GitLab, and apart -from incidental patch and security releases, are released on the 22nd each +from incidental patch and security releases, are released on the 22nd of each month. Backward incompatible changes (e.g. endpoints removal, parameters removal etc.), as well as removal of entire API versions are done in tandem with a major point release of GitLab itself. All deprecations and changes @@ -221,6 +225,42 @@ For more information, refer to the Impersonation tokens are used exactly like regular personal access tokens, and can be passed in either the `private_token` parameter or the `Private-Token` header. +#### Disable impersonation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/40385) in GitLab +11.6. + +By default, impersonation is enabled. To disable impersonation: + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['impersonation_enabled'] = false + ``` + +1. Save the file and [reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration and reconfigure GitLab. + +--- + +**For installations from source** + +1. Edit `config/gitlab.yml`: + + ```yaml + gitlab: + impersonation_enabled: false + ``` + +1. Save the file and [restart](../administration/restart_gitlab.md#installations-from-source) + GitLab for the changes to take effect. + +To re-enable impersonation, remove this configuration and restart GitLab. + ### Sudo NOTE: **Note:** @@ -233,6 +273,9 @@ You need to pass the `sudo` parameter either via query string or a header with a the user you want to perform the operation as. If passed as a header, the header name must be `Sudo`. +NOTE: **Note:** +Usernames are case insensitive. + If a non administrative access token is provided, an error message will be returned with status code `403`: diff --git a/doc/api/applications.md b/doc/api/applications.md index 6d244594b71..d74a3cdf5c1 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -4,12 +4,12 @@ [ce-8160]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8160 +Only admin user can use the Applications API. + ## Create a application Create a application by posting a JSON payload. -User must be admin to do that. - Returns `200` if the request succeeds. ``` @@ -30,8 +30,55 @@ Example response: ```json { + "id":1, "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737", + "application_name": "MyApplication", "secret": "ee1dd64b6adc89cf7e2c23099301ccc2c61b441064e9324d963c46902a85ec34", "callback_url": "http://redirect.uri" } ``` + +## List all applications + +List all registered applications. + +``` +GET /applications +``` + +```bash +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/applications +``` + +Example response: + +```json +[ + { + "id":1, + "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737", + "application_name": "MyApplication", + "callback_url": "http://redirect.uri" + } +] +``` + +> Note: the `secret` value will not be exposed by this API. + +## Delete an application + +Delete a specific application. + +Returns `204` if the request succeeds. + +``` +DELETE /applications/:id +``` + +Parameters: + +- `id` (required) - The id of the application (not the application_id) + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/applications/:id +``` diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 7faed893066..aa6f7c185ae 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -4,7 +4,7 @@ ## Get a single avatar URL -Get a single avatar URL for a given email addres. If user with matching public +Get a single avatar URL for a given email address. If user with matching public email address is not found, results from external avatar services are returned. This endpoint can be accessed without authentication. In case public visibility is restricted, response will be `403 Forbidden` when unauthenticated. diff --git a/doc/api/commits.md b/doc/api/commits.md index 624ed529009..6c16216429d 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -79,16 +79,18 @@ POST /projects/:id/repository/commits | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | | `author_email` | string | no | Specify the commit author's email address | | `author_name` | string | no | Specify the commit author's name | +| `stats` | boolean | no | Include commit stats. Default is true | | `actions[]` Attribute | Type | Required | Description | | --------------------- | ---- | -------- | ----------- | -| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update` | +| `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update`, `chmod`| | `file_path` | string | yes | Full path to the file. Ex. `lib/class.rb` | -| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb` | -| `content` | string | no | File content, required for all except `delete`. Optional for `move` | +| `previous_path` | string | no | Original full path to the file being moved. Ex. `lib/class1.rb`. Only considered for `move` action. | +| `content` | string | no | File content, required for all except `delete`, `chmod`, and `move`. Move actions that do not specify `content` will preserve the existing file content, and any other value of `content` will overwrite the file content. | | `encoding` | string | no | `text` or `base64`. `text` is default. | | `last_commit_id` | string | no | Last known file commit id. Will be only considered in update, move and delete actions. | +| `execute_filemode` | boolean | no | When `true/false` enables/disables the execute flag on the file. Only considered for `chmod` action. | ```bash PAYLOAD=$(cat << 'JSON' @@ -115,6 +117,11 @@ PAYLOAD=$(cat << 'JSON' "action": "update", "file_path": "foo/bar5", "content": "new content" + }, + { + "action": "chmod", + "file_path": "foo/bar5", + "execute_filemode": true } ] } @@ -281,6 +288,47 @@ Example response: } ``` +## Revert a commit + +> [Introduced][ce-22919] in GitLab 11.5. + +Reverts a commit in a given branch. + +``` +POST /projects/:id/repository/commits/:sha/revert +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `sha` | string | yes | Commit SHA to revert | +| `branch` | string | yes | Target branch name | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert" +``` + +Example response: + +```json +{ + "id":"8b090c1b79a14f2bd9e8a738f717824ff53aebad", + "short_id": "8b090c1b", + "title":"Revert \"Feature added\"", + "created_at":"2018-11-08T15:55:26.000Z", + "parent_ids":["a738f717824ff53aebad8b090c1b79a14f2bd9e8"], + "message":"Revert \"Feature added\"\n\nThis reverts commit a738f717824ff53aebad8b090c1b79a14f2bd9e8", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2018-11-08T15:55:26.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2018-11-08T15:55:26.000Z" +} +``` + ## Get the diff of a commit Get the diff of a commit in a project. @@ -612,3 +660,4 @@ Example response: [ce-8047]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8047 [ce-15026]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15026 [ce-18004]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18004 +[ce-22919]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22919 diff --git a/doc/api/deployments.md b/doc/api/deployments.md index fd11894ea8f..1963b0a21de 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -46,19 +46,21 @@ Example of response "status": "success", "tag": false, "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, - "created_at": "2016-08-11T07:09:20.351Z", - "id": 1, - "linkedin": "", "location": null, - "name": "Administrator", + "public_email": "", "skype": "", - "state": "active", + "linkedin": "", "twitter": "", - "username": "root", - "web_url": "http://localhost:3000/root", - "website_url": "" + "website_url": "", + "organization": "" } }, "environment": { @@ -103,19 +105,21 @@ Example of response "status": "success", "tag": false, "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, - "created_at": "2016-08-11T07:09:20.351Z", - "id": 1, - "linkedin": "", "location": null, - "name": "Administrator", + "public_email": "", "skype": "", - "state": "active", + "linkedin": "", "twitter": "", - "username": "root", - "web_url": "http://localhost:3000/root", - "website_url": "" + "website_url": "", + "organization": "" } }, "environment": { @@ -188,19 +192,20 @@ Example of response "started_at": null, "finished_at": "2016-08-11T11:32:35.145Z", "user": { + "id": 1, "name": "Administrator", "username": "root", - "id": 1, "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "http://localhost:3000/root", - "created_at": "2016-08-11T07:09:20.351Z", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", "bio": null, "location": null, "skype": "", "linkedin": "", "twitter": "", - "website_url": "" + "website_url": "", + "organization": "" }, "commit": { "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", diff --git a/doc/api/discussions.md b/doc/api/discussions.md index a1e1ff1419d..3538a577c8e 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -123,7 +123,7 @@ curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab ### Create new issue discussion Creates a new discussion to a single project issue. This is similar to creating -a note but but another comments (replies) can be added to it later. +a note but other comments (replies) can be added to it later. ``` POST /projects/:id/issues/:issue_iid/discussions @@ -329,7 +329,7 @@ curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitla ### Create new snippet discussion Creates a new discussion to a single project snippet. This is similar to creating -a note but but another comments (replies) can be added to it later. +a note but other comments (replies) can be added to it later. ``` POST /projects/:id/snippets/:snippet_id/discussions @@ -588,7 +588,7 @@ curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab ### Create new merge request discussion Creates a new discussion to a single project merge request. This is similar to creating -a note but but another comments (replies) can be added to it later. +a note but other comments (replies) can be added to it later. ``` POST /projects/:id/merge_requests/:merge_request_iid/discussions @@ -881,7 +881,7 @@ curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab ### Create new commit discussion Creates a new discussion to a single project commit. This is similar to creating -a note but but another comments (replies) can be added to it later. +a note but other comments (replies) can be added to it later. ``` POST /projects/:id/commits/:commit_id/discussions diff --git a/doc/api/events.md b/doc/api/events.md index fb5ebb71a86..e1c6b801a77 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -44,7 +44,7 @@ YYYY-MM-DD ### Event Time Period Limit -GitLab removes events older than 1 year from the events table for performance reasons. The range of 1 year was chosen because user contribution calendars only show contributions of the past year. +GitLab removes events older than 2 years from the events table for performance reasons. ## List currently authenticated user's events @@ -71,7 +71,7 @@ Parameters: Example request: ``` -curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` Example response: @@ -276,7 +276,7 @@ Parameters: Example request: ``` -curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:project_id/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:project_id/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` Example response: diff --git a/doc/api/groups.md b/doc/api/groups.md index be75c363a40..59444a98086 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -37,6 +37,7 @@ GET /groups "request_access_enabled": false, "full_name": "Foobar Group", "full_path": "foo-bar", + "file_template_project_id": 1, "parent_id": null } ] @@ -62,6 +63,7 @@ GET /groups?statistics=true "request_access_enabled": false, "full_name": "Foobar Group", "full_path": "foo-bar", + "file_template_project_id": 1, "parent_id": null, "statistics": { "storage_size" : 212, @@ -122,6 +124,7 @@ GET /groups/:id/subgroups "request_access_enabled": false, "full_name": "Foobar Group", "full_path": "foo-bar", + "file_template_project_id": 1, "parent_id": 123 } ] @@ -149,8 +152,10 @@ Parameters: | `simple` | boolean | no | Return only the ID, URL, name, and path of each project | | `owned` | boolean | no | Limit by projects owned by the current user | | `starred` | boolean | no | Limit by projects starred by the current user | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | -| `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | +| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | +| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | +| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | +| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | Example response: @@ -232,6 +237,7 @@ Example response: "request_access_enabled": false, "full_name": "Twitter", "full_path": "twitter", + "file_template_project_id": 1, "parent_id": null, "projects": [ { @@ -386,6 +392,7 @@ Example response: "request_access_enabled": false, "full_name": "Twitter", "full_path": "twitter", + "file_template_project_id": 1, "parent_id": null } ``` @@ -442,6 +449,7 @@ PUT /groups/:id | `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | | `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group | | `request_access_enabled` | boolean | no | Allow users to request member access. | +| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" @@ -462,6 +470,7 @@ Example response: "request_access_enabled": false, "full_name": "Foobar Group", "full_path": "foo-bar", + "file_template_project_id": 1, "parent_id": null, "projects": [ { diff --git a/doc/api/issues.md b/doc/api/issues.md index f4c0f4ea65b..6a99c52234d 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -36,12 +36,12 @@ GET /issues?my_reaction_emoji=star | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -149,13 +149,13 @@ GET /groups/:id/issues?my_reaction_emoji=star | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -264,12 +264,12 @@ GET /projects/:id/issues?my_reaction_emoji=star | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | Array[integer] | no | Return only the milestone having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -658,7 +658,7 @@ POST /projects/:id/issues/:issue_iid/move | `to_project_id` | integer | yes | The ID of the new project | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data '{"to_project_id": 5}' https://gitlab.example.com/api/v4/projects/4/issues/85/move +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form to_project_id=5 https://gitlab.example.com/api/v4/projects/4/issues/85/move ``` Example response: @@ -1113,6 +1113,93 @@ Example response: } ``` +## List merge requests related to issue + +Get all the merge requests that are related to the issue. + +``` +GET /projects/:id/issues/:issue_id/related_merge_requests +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```sh +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests +``` + +Example response: + +```json +[ + { + "id": 29, + "iid": 11, + "project_id": 1, + "title": "Provident eius eos blanditiis consequatur neque odit.", + "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8", + "state": "opened", + "created_at": "2018-09-18T14:36:15.510Z", + "updated_at": "2018-09-19T07:45:13.089Z", + "target_branch": "v2.x", + "source_branch": "so_long_jquery", + "upvotes": 0, + "downvotes": 0, + "author": { + "id": 14, + "name": "Verna Hills", + "username": "lawanda_reinger", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon", + "web_url": "https://gitlab.example.com/lawanda_reinger" + }, + "assignee": { + "id": 19, + "name": "Jody Baumbach", + "username": "felipa.kuvalis", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", + "web_url": "https://gitlab.example.com/felipa.kuvalis" + }, + "source_project_id": 1, + "target_project_id": 1, + "labels": [], + "work_in_progress": false, + "milestone": { + "id": 27, + "iid": 2, + "project_id": 1, + "title": "v1.0", + "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.", + "state": "active", + "created_at": "2018-09-18T14:35:44.353Z", + "updated_at": "2018-09-18T14:35:44.353Z", + "due_date": null, + "start_date": null, + "web_url": "https://gitlab.example.com/twitter/flight/milestones/2" + }, + "merge_when_pipeline_succeeds": false, + "merge_status": "cannot_be_merged", + "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12", + "merge_commit_sha": null, + "user_notes_count": 9, + "discussion_locked": null, + "should_remove_source_branch": null, + "force_remove_source_branch": false, + "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false + } +] +``` + ## List merge requests that will close issue on merge Get all the merge requests that will close issue when merged. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index cf292adf150..aa290ff4cf8 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -53,18 +53,21 @@ Example of response "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } }, { @@ -109,18 +112,21 @@ Example of response "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ] @@ -180,18 +186,21 @@ Example of response "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/6", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } }, { @@ -236,18 +245,21 @@ Example of response "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/7", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ] @@ -305,18 +317,21 @@ Example of response "tag": false, "web_url": "https://example.com/foo/bar/-/jobs/8", "user": { - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "bio": null, - "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "linkedin": "", "name": "Administrator", - "skype": "", - "state": "active", - "twitter": "", "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://gitlab.dev/root", - "website_url": "" + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "" } } ``` diff --git a/doc/api/keys.md b/doc/api/keys.md index ddcf7830621..06b31a67d6a 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -27,10 +27,16 @@ Parameters: "web_url": "http://localhost:3000/john_smith", "created_at": "2015-09-03T07:24:01.670Z", "bio": null, + "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", "website_url": "", + "organization": null, + "last_sign_in_at": "2015-09-03T07:24:01.670Z", + "confirmed_at": "2015-09-03T07:24:01.670Z", + "last_activity_on": "2015-09-03", "email": "john@example.com", "theme_id": 2, "color_scheme_id": 1, @@ -40,6 +46,8 @@ Parameters: "can_create_group": true, "can_create_project": true, "two_factor_enabled": false + "external": false, + "private_profile": null } } ``` diff --git a/doc/api/members.md b/doc/api/members.md index 7b228b92594..bb4fae35f52 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -15,6 +15,7 @@ The access levels are defined in the `Gitlab::Access` module. Currently, these l ## List all members of a group or project Gets a list of group or project members viewable by the authenticated user. +Returns only direct members and not inherited members through ancestors groups. ``` GET /groups/:id/members @@ -61,6 +62,7 @@ Example response: ## List all members of a group or project including inherited members Gets a list of group or project members viewable by the authenticated user, including inherited members through ancestor groups. +Returns multiple times the same user (with different member attributes) when the user is a member of the project/group and of one or more ancestor group. ``` GET /groups/:id/members/all diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 9e6676d62fe..fc03cf6cc39 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -30,58 +30,73 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels | +| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `created_after` | datetime | no | Return merge requests created on or after the given time | | `created_before` | datetime | no | Return merge requests created on or before the given time | | `updated_after` | datetime | no | Return merge requests updated on or after the given time | | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "opened", + "description": "fixed login page css paddings", + "state": "merged", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -92,23 +107,28 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -145,22 +165,22 @@ Parameters: | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a project | | `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels | +| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `created_after` | datetime | no | Return merge requests created on or after the given time | | `created_before` | datetime | no | Return merge requests created on or before the given time | | `updated_after` | datetime | no | Return merge requests updated on or after the given time | | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -168,35 +188,49 @@ Parameters: { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "opened", + "description": "fixed login page css paddings", + "state": "merged", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -207,24 +241,28 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -250,23 +288,23 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels | +| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | | `created_after` | datetime | no | Return merge requests created on or after the given time | | `created_before` | datetime | no | Return merge requests created on or before the given time | | `updated_after` | datetime | no | Return merge requests updated on or after the given time | | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -274,35 +312,49 @@ Parameters: { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "opened", + "description": "fixed login page css paddings", + "state": "merged", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -313,23 +365,26 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-10-22", + "start_date": "2018-09-08", + "web_url": "gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false } ] ``` @@ -353,40 +408,44 @@ Parameters: - `merge_request_iid` (required) - The internal ID of the merge request - `render_html` (optional) - If `true` response includes rendered HTML for title and description - `include_diverged_commits_count` (optional) - If `true` response includes the commits behind the target branch +- `include_rebase_in_progress` (optional) - If `true` response includes whether a rebase operation is in progress ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" + "id": 1, + "name": "Administrator", + "username": "admin", + "state": "active", + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" + "id": 1, + "name": "Administrator", + "username": "admin", + "state": "active", + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "source_project_id": 2, "target_project_id": 3, - "labels": [ ], - "description": "fixed login page css paddings", + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, @@ -397,47 +456,59 @@ Parameters: "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, + "merge_error": null, "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": "9999999999999999999999999999999999999999", + "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null }, - "closed_at": "2018-01-19T14:36:11.086Z", - "latest_build_started_at": null, - "latest_build_finished_at": null, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", "first_deployed_to_production_at": null, "pipeline": { - "id": 8, - "ref": "master", - "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0", - "status": "created" + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" }, - "merged_by": null, - "merged_at": null, - "closed_by": { - "state" : "active", - "web_url" : "https://gitlab.example.com/root", - "avatar_url" : null, - "username" : "root", - "id" : 1, - "name" : "Administrator" + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "rebase_in_progress": false } ``` @@ -657,65 +728,100 @@ POST /projects/:id/merge_requests { "id": 1, "iid": 1, + "project_id": 3, + "title": "test1", + "description": "fixed login page css paddings", + "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", "source_branch": "test1", - "project_id": 4, - "title": "test1", - "state": "opened", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 3, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, - "user_notes_count": 0, - "changes_count": "1", + "user_notes_count": 1, + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, "allow_collaboration": false, "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -750,64 +856,100 @@ Must include at least one non-required attribute from above. { "id": 1, "iid": 1, - "target_branch": "master", - "project_id": 4, + "project_id": 3, "title": "test1", - "state": "opened", + "description": "fixed login page css paddings", + "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 3, - "target_project_id": 4, - "labels": [ ], - "description": "description1", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, "allow_collaboration": false, "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -851,70 +993,107 @@ Parameters: - `merge_request_iid` (required) - Internal ID of MR - `merge_commit_message` (optional) - Custom merge commit message - `should_remove_source_branch` (optional) - if `true` removes the source branch -- `merge_when_pipeline_succeeds` (optional) - if `true` the MR is merged when the pipeline succeeds +- `merge_when_pipeline_succeeds` (optional) - if `true` the MR is merged when the pipeline succeeds - `sha` (optional) - if present, then this SHA must match the HEAD of the source branch, otherwise the merge will fail ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", + "description": "fixed login page css paddings", "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 4, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", - "subscribed" : true, + "merge_error": null, "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": "9999999999999999999999999999999999999999", + "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -931,69 +1110,162 @@ PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_s Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `merge_request_iid` (required) - Internal ID of MR +- `merge_request_iid` (required) - Internal ID of MR ```json { "id": 1, "iid": 1, - "target_branch": "master", - "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "opened", + "description": "fixed login page css paddings", + "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, "assignee": { "id": 1, - "username": "admin", "name": "Administrator", + "username": "admin", "state": "active", "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 4, - "target_project_id": 4, - "labels": [ ], - "description": "fixed login page css paddings", + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { "id": 5, "iid": 1, - "project_id": 4, + "project_id": 3, "title": "v2.0", "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", "created_at": "2015-02-02T19:49:26.013Z", "updated_at": "2015-02-02T19:49:26.013Z", - "due_date": null + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": true, + "merge_when_pipeline_succeeds": false, "merge_status": "can_be_merged", - "subscribed" : true, + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, - "changes_count": "1", + "discussion_locked": null, "should_remove_source_branch": true, "force_remove_source_branch": false, - "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", - "discussion_locked": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", "time_stats": { "time_estimate": 0, "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 +} +``` + +## Rebase a merge request + +Automatically rebase the `source_branch` of the merge request against its +`target_branch`. + +If you don't have permissions to push to the merge request's source branch - +you'll get a `403 Forbidden` response. + +``` +PUT /projects/:id/merge_requests/:merge_request_iid/rebase +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `merge_request_iid` | integer | yes | The internal ID of the merge request | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase +``` + +This is an asynchronous request. The API will return an empty `202 Accepted` +response if the request is enqueued successfully. + +You can poll the [Get single MR](#get-single-mr) endpoint with the +`include_rebase_in_progress` parameter to check the status of the +asynchronous request. + +If the rebase operation is ongoing, the response will include the following: + +```json +{ + "rebase_in_progress": true + "merge_error": null +} +``` + +Once the rebase operation has completed successfully, the response will include +the following: + +```json +{ + "rebase_in_progress": false, + "merge_error": null, +} +``` + +If the rebase operation fails, the response will include the following: + +```json +{ + "rebase_in_progress": false, + "merge_error": "Rebase failed. Please rebase locally", } ``` @@ -1061,7 +1333,7 @@ Example response when the GitLab issue tracker is used: "labels" : [], "user_notes_count": 1, "changes_count": "1" - }, + } ] ``` @@ -1098,54 +1370,101 @@ Example response: ```json { - "id": 17, + "id": 1, "iid": 1, - "project_id": 5, - "title": "Et et sequi est impedit nulla ut rem et voluptatem.", - "description": "Consequatur velit eos rerum optio autem. Quia id officia quaerat dolorum optio. Illo laudantium aut ipsum dolorem.", - "state": "opened", - "created_at": "2016-04-05T21:42:23.233Z", - "updated_at": "2016-04-05T22:11:52.900Z", - "target_branch": "ui-dev-kit", - "source_branch": "version-1-9", + "project_id": 3, + "title": "test1", + "description": "fixed login page css paddings", + "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "name": "Eileen Skiles", - "username": "leila", - "id": 19, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/39ce4a2822cc896933ffbd68c1470e55?s=80&d=identicon", - "web_url": "https://gitlab.example.com/leila" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "name": "Celine Wehner", - "username": "carli", - "id": 16, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/f4cd5605b769dd2ce405a27c6e6f2684?s=80&d=identicon", - "web_url": "https://gitlab.example.com/carli" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 5, - "target_project_id": 5, - "labels": [], + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { - "id": 7, + "id": 5, "iid": 1, - "project_id": 5, + "project_id": 3, "title": "v2.0", - "description": "Corrupti eveniet et velit occaecati dolorem est rerum aut.", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", - "created_at": "2016-04-05T21:41:40.905Z", - "updated_at": "2016-04-05T21:41:40.905Z", - "due_date": null + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": false, - "merge_status": "cannot_be_merged", - "subscribed": true, + "merge_when_pipeline_succeeds": true, + "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": null + "merge_commit_sha": null, + "user_notes_count": 1, + "discussion_locked": null, + "should_remove_source_branch": true, + "force_remove_source_branch": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -1172,54 +1491,101 @@ Example response: ```json { - "id": 17, + "id": 1, "iid": 1, - "project_id": 5, - "title": "Et et sequi est impedit nulla ut rem et voluptatem.", - "description": "Consequatur velit eos rerum optio autem. Quia id officia quaerat dolorum optio. Illo laudantium aut ipsum dolorem.", - "state": "opened", - "created_at": "2016-04-05T21:42:23.233Z", - "updated_at": "2016-04-05T22:11:52.900Z", - "target_branch": "ui-dev-kit", - "source_branch": "version-1-9", + "project_id": 3, + "title": "test1", + "description": "fixed login page css paddings", + "state": "merged", + "created_at": "2017-04-29T08:46:00Z", + "updated_at": "2017-04-29T08:46:00Z", + "target_branch": "master", + "source_branch": "test1", "upvotes": 0, "downvotes": 0, "author": { - "name": "Eileen Skiles", - "username": "leila", - "id": 19, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/39ce4a2822cc896933ffbd68c1470e55?s=80&d=identicon", - "web_url": "https://gitlab.example.com/leila" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, "assignee": { - "name": "Celine Wehner", - "username": "carli", - "id": 16, + "id": 1, + "name": "Administrator", + "username": "admin", "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/f4cd5605b769dd2ce405a27c6e6f2684?s=80&d=identicon", - "web_url": "https://gitlab.example.com/carli" + "avatar_url": null, + "web_url" : "https://gitlab.example.com/admin" }, - "source_project_id": 5, - "target_project_id": 5, - "labels": [], + "source_project_id": 2, + "target_project_id": 3, + "labels": [ + "Community contribution", + "Manage" + ], "work_in_progress": false, "milestone": { - "id": 7, + "id": 5, "iid": 1, - "project_id": 5, + "project_id": 3, "title": "v2.0", - "description": "Corrupti eveniet et velit occaecati dolorem est rerum aut.", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", "state": "closed", - "created_at": "2016-04-05T21:41:40.905Z", - "updated_at": "2016-04-05T21:41:40.905Z", - "due_date": null + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": "2018-09-22", + "start_date": "2018-08-08", + "web_url": "https://gitlab.example.com/my-group/my-project/milestones/1" }, - "merge_when_pipeline_succeeds": false, - "merge_status": "cannot_be_merged", - "subscribed": false, + "merge_when_pipeline_succeeds": true, + "merge_status": "can_be_merged", "sha": "8888888888888888888888888888888888888888", - "merge_commit_sha": null + "merge_commit_sha": null, + "user_notes_count": 1, + "discussion_locked": null, + "should_remove_source_branch": true, + "force_remove_source_branch": false, + "allow_collaboration": false, + "allow_maintainer_to_push": false, + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false, + "subscribed": false, + "changes_count": "1", + "merged_by": { + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merged_at": "2018-09-07T11:16:17.520Z", + "closed_by": null, + "closed_at": null, + "latest_build_started_at": "2018-09-07T07:27:38.472Z", + "latest_build_finished_at": "2018-09-07T08:07:06.012Z", + "first_deployed_to_production_at": null, + "pipeline": { + "id": 29626725, + "sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "ref": "patch-28", + "status": "success", + "web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725" + }, + "diff_refs": { + "base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00", + "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", + "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" + }, + "diverged_commits_count": 2 } ``` @@ -1270,7 +1636,7 @@ Example response: "project_id": 3, "title": "Et voluptas laudantium minus nihil recusandae ut accusamus earum aut non.", "description": "Veniam sunt nihil modi earum cumque illum delectus. Nihil ad quis distinctio quia. Autem eligendi at quibusdam repellendus.", - "state": "opened", + "state": "merged", "created_at": "2016-06-17T07:48:04.330Z", "updated_at": "2016-07-01T11:14:15.537Z", "target_branch": "allow_regex_for_project_skip_ref", diff --git a/doc/api/notes.md b/doc/api/notes.md index 44940bdd9e5..9f6740ad86a 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -98,7 +98,7 @@ POST /projects/:id/issues/:issue_iid/notes Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) -- `issue_id` (required) - The IID of an issue +- `issue_iid` (required) - The IID of an issue - `body` (required) - The content of a note - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 77bb7a55d8c..8a1e6b52092 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,6 +1,6 @@ # GitLab as an OAuth2 provider -This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access Gitlab resources on user's behalf. +This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services access GitLab resources on user's behalf. If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [OAuth2 provider](../integration/oauth_provider.md) documentation. @@ -9,7 +9,7 @@ This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-ge ## Supported OAuth2 Flows -Gitlab currently supports following authorization flows: +GitLab currently supports following authorization flows: * *Web Application Flow* - Most secure and common type of flow, designed for the applications with secure server-side. * *Implicit Flow* - This flow is designed for user-agent only apps (e.g. single page web application running on GitLab Pages). @@ -76,7 +76,7 @@ Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.2) for a detailed Unlike the web flow, the client receives an `access token` immediately as a result of the authorization request. The flow does not use client secret or authorization code because all of the application code and storage is easily accessible, therefore __secrets__ can leak easily. ->**Important:** Avoid using this flow for applications that store data outside of the Gitlab instance. If you do, make sure to verify `application id` +>**Important:** Avoid using this flow for applications that store data outside of the GitLab instance. If you do, make sure to verify `application id` associated with access token before granting access to the data (see [/oauth/token/info](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo)). @@ -146,7 +146,7 @@ access_token = client.password.get_token('user@example.com', 'secret') puts access_token.token ``` -## Access Gitlab API with `access token` +## Access GitLab API with `access token` The `access token` allows you to make requests to the API on a behalf of a user. You can pass the token either as GET parameter ``` diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 574be52801c..7b4c9a8fbb3 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -235,5 +235,22 @@ Response: } ``` +## Delete a pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22988) in GitLab 11.6. + +``` +DELETE /projects/:id/pipelines/:pipeline_id +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_id` | integer | yes | The ID of a pipeline | + +``` +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --request "DELETE" "https://gitlab.example.com/api/v4/projects/1/pipelines/46" +``` + [ce-5837]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5837 [ce-7209]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7209 diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md new file mode 100644 index 00000000000..ef98205cd68 --- /dev/null +++ b/doc/api/project_templates.md @@ -0,0 +1,139 @@ +# Project templates API + +This API is a project-specific version of these endpoints: + +- [Dockerfile templates](templates/dockerfiles.md) +- [Gitignore templates](templates/gitignores.md) +- [GitLab CI Config templates](templates/gitlab_ci_ymls.md) +- [Open source license templates](templates/licenses.md) + +It deprecates these endpoints, which will be removed for API version 5. + +In addition to templates common to the entire instance, project-specific +templates are also available from this API endpoint. + +Support will be added for [Issue and Merge Request templates](../user/project/description_templates.md) +in a future release. + +Support for [Group-level file templates](../user/group/index.md#group-level-file-templates-premium) +**[PREMIUM]** was [added](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) +in GitLab 11.5 + +## Get all templates of a particular type + +``` +GET /projects/:id/templates/:type +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | + +Example response (licenses): + +```json +[ + { + "key": "epl-1.0", + "name": "Eclipse Public License 1.0" + }, + { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0" + }, + { + "key": "unlicense", + "name": "The Unlicense" + }, + { + "key": "agpl-3.0", + "name": "GNU Affero General Public License v3.0" + }, + { + "key": "gpl-3.0", + "name": "GNU General Public License v3.0" + }, + { + "key": "bsd-3-clause", + "name": "BSD 3-clause \"New\" or \"Revised\" License" + }, + { + "key": "lgpl-2.1", + "name": "GNU Lesser General Public License v2.1" + }, + { + "key": "mit", + "name": "MIT License" + }, + { + "key": "apache-2.0", + "name": "Apache License 2.0" + }, + { + "key": "bsd-2-clause", + "name": "BSD 2-clause \"Simplified\" License" + }, + { + "key": "mpl-2.0", + "name": "Mozilla Public License 2.0" + }, + { + "key": "gpl-2.0", + "name": "GNU General Public License v2.0" + } +] +``` + +## Get one template of a particular type + +``` +GET /projects/:id/templates/:type/:key +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `id ` | integer / string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `type` | string | yes| The type `(dockerfiles|gitignores|gitlab_ci_ymls|licenses)` of the template | +| `key` | string | yes | The key of the template, as obtained from the collection endpoint | +| `project` | string | no | The project name to use when expanding placeholders in the template. Only affects licenses | +| `fullname` | string | no | The full name of the copyright holder to use when expanding placeholders in the template. Only affects licenses | + +Example response (Dockerfile): + + +```json +{ + "name": "Binary", + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" +} + +``` + +Example response (license): + +```json +{ + "key": "mit", + "name": "MIT License", + "nickname": null, + "popular": true, + "html_url": "http://choosealicense.com/licenses/mit/", + "source_url": "https://opensource.org/licenses/MIT", + "description": "A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.", + "conditions": [ + "include-copyright" + ], + "permissions": [ + "commercial-use", + "modifications", + "distribution", + "private-use" + ], + "limitations": [ + "liability", + "warranty" + ], + "content": "MIT License\n\nCopyright (c) 2018 [fullname]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" +} +``` diff --git a/doc/api/projects.md b/doc/api/projects.md index 947e7db9c52..ef51ea20e7f 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -451,6 +451,7 @@ GET /projects/:id | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `statistics` | boolean | no | Include project statistics | +| `license` | boolean | no | Include project license data | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | ```json @@ -508,6 +509,14 @@ GET /projects/:id }, "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -572,6 +581,14 @@ If the project is a fork, and you provide a valid token to authenticate, the "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-ce.git", "web_url":"https://gitlab.com/gitlab-org/gitlab-ce", "avatar_url":"https://assets.gitlab-static.net/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png", + "license_url": "https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE", + "license": { + "key": "mit", + "name": "MIT License", + "nickname": null, + "html_url": "http://choosealicense.com/licenses/mit/", + "source_url": "https://opensource.org/licenses/MIT", + }, "star_count":3812, "forks_count":3561, "last_activity_at":"2018-01-02T11:40:26.570Z", @@ -651,7 +668,7 @@ POST /projects | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the merge method used | @@ -689,7 +706,7 @@ POST /projects/user/:user_id | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the merge method used | @@ -725,7 +742,7 @@ PUT /projects/:id | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | -| `public_jobs` | boolean | no | If `true`, jobs can be viewed by non-project-members | +| `public_builds` | boolean | no | If `true`, jobs can be viewed by non-project-members | | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the merge method used | @@ -905,6 +922,14 @@ Example response: "import_status": "none", "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 1, @@ -983,6 +1008,14 @@ Example response: "import_status": "none", "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -1101,6 +1134,14 @@ Example response: }, "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -1197,6 +1238,14 @@ Example response: }, "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, diff --git a/doc/api/repositories.md b/doc/api/repositories.md index a4fdeca162e..55f5a4cc3b2 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -14,9 +14,10 @@ GET /projects/:id/repository/tree Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `path` (optional) - The path inside repository. Used to get contend of subdirectories +- `path` (optional) - The path inside repository. Used to get content of subdirectories - `ref` (optional) - The name of a repository branch or tag or if not given the default branch - `recursive` (optional) - Boolean value used to get a recursive tree (false by default) +- `per_page` (optional) - Number of results to show per page. If not specified, defaults to `20` ```json [ @@ -107,14 +108,18 @@ Get an archive of the repository. This endpoint can be accessed without authentication if the repository is publicly accessible. ``` -GET /projects/:id/repository/archive +GET /projects/:id/repository/archive[.format] ``` +`format` is an optional suffix for the archive format. Default is +`tar.gz`. Options are `tar.gz`, `tar.bz2`, `tbz`, 'tbz2`, `tb2`, +`bz2`, `tar`, and `zip`. For example, specifying `archive.zip` +would send an archive in ZIP format. + Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `sha` (optional) - The commit SHA to download. A tag, branch reference or sha can be used. This defaults to the tip of the default branch if not specified -- `format` (optional) - The archive format. Default is `tar.gz`. Options are `tar.gz`, `tar.bz2`, `tbz`, `tbz2`, `tb2`, `bz2`, `tar`, `zip` ## Compare branches, tags or commits @@ -216,7 +221,7 @@ GET /projects/:id/repository/merge_base | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `refs` | array | yes | The refs to find the common ancestor of, for now only 2 refs are supported | +| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257dcb821665ab5110318fc58a007bd104ed&refs[]=0031876facac3f2b2702a0e53a26e89939a42209" diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 49fb9bc141d..c3624f1a535 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -90,12 +90,17 @@ Like [Get file from repository](repository_files.md#get-file-from-repository) yo ## Create new file in repository +This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` POST /projects/:id/repository/files/:file_path ``` ```bash -curl --request POST --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fprojectrb%2E?branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&content=some%20content&commit_message=create%20a%20new%20file' +curl --request POST --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "content": "some content", "commit_message": "create a new file"}' \ + 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb' ``` Example response: @@ -120,12 +125,17 @@ Parameters: ## Update existing file in repository +This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` PUT /projects/:id/repository/files/:file_path ``` ```bash -curl --request PUT --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb?branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&content=some%20other%20content&commit_message=update%20file' +curl --request PUT --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "content": "some content", "commit_message": "update file"}' \ + 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb' ``` Example response: @@ -160,12 +170,17 @@ Currently gitlab-shell has a boolean return code, preventing GitLab from specify ## Delete existing file in repository +This allows you to delete a single file. For deleting multiple files with a singleh request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions). + ``` DELETE /projects/:id/repository/files/:file_path ``` ```bash -curl --request DELETE --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb?branch=master&author_email=author%40example.com&author_name=Firstname%20Lastname&commit_message=delete%20file' +curl --request DELETE --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ + --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname", \ + "commit_message": "delete file"}' \ + 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb' ``` Parameters: diff --git a/doc/api/repository_storage_health.md b/doc/api/repository_storage_health.md index e0c0315c2d7..edf4b04acea 100644 --- a/doc/api/repository_storage_health.md +++ b/doc/api/repository_storage_health.md @@ -1,74 +1,5 @@ # Circuitbreaker API -> [Introduced][ce-11449] in GitLab 9.5. - -The Circuitbreaker API is only accessible to administrators. All requests by -guests will respond with `401 Unauthorized`, and all requests by normal users -will respond with `403 Forbidden`. - -## Repository Storages - -### Get all storage information - -Returns of all currently configured storages and their health information. - -``` -GET /circuit_breakers/repository_storage -``` - -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/circuit_breakers/repository_storage -``` - -```json -[ - { - "storage_name": "default", - "failing_on_hosts": [], - "total_failures": 0 - }, - { - "storage_name": "broken", - "failing_on_hosts": [ - "web01", "worker01" - ], - "total_failures": 1 - } -] -``` - -### Get failing storages - -This returns a list of all currently failing storages. - -``` -GET /circuit_breakers/repository_storage/failing -``` - -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/circuit_breakers/repository_storage/failing -``` - -```json -[ - { - "storage_name":"broken", - "failing_on_hosts":["web01", "worker01"], - "total_failures":2 - } -] -``` - -## Reset failing storage information - -Use this remove all failing storage information and allow access to the storage again. - -``` -DELETE /circuit_breakers/repository_storage -``` - -```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/circuit_breakers/repository_storage -``` - -[ce-11449]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11449 +NOTE: **Deprecated:** +Support of the circuit breaker is removed, as Gitaly can be configured to +to work without NFS and [communicate solely over HTTP](../administration/gitaly/index.md). diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md new file mode 100644 index 00000000000..2e6797f18f4 --- /dev/null +++ b/doc/api/repository_submodules.md @@ -0,0 +1,49 @@ +# Repository submodules API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41213) in GitLab 11.5 + +## Update existing submodule reference in repository + +In some workflows, especially automated ones, it can be useful to update a +submodule's reference to keep up to date other projects that use it. +This endpoint allows you to update a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) reference in a +specific branch. + +``` +PUT /projects/:id/repository/submodules/:submodule +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `submodule` | string | yes | URL encoded full path to the submodule. For example, `lib%2Fclass%2Erb` | +| `branch` | string | yes | Name of the branch to commit into | +| `commit_sha` | string | yes | Full commit SHA to update the submodule to | +| `commit_message` | string | no | Commit message. If no message is provided, a default one will be set | + +```sh +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repositories/submodules/lib%2Fmodules%2Fexample" +--data "branch=master&commit_sha=3ddec28ea23acc5caa5d8331a6ecb2a65fc03e88&commit_message=Update submodule reference" +``` + +Example response: + +```json +{ + "id": "ed899a2f4b50b4370feeea94676502b42383c746", + "short_id": "ed899a2f4b5", + "title": "Updated submodule example_submodule with oid 3ddec28ea23acc5caa5d8331a6ecb2a65fc03e88", + "author_name": "Dmitriy Zaporozhets", + "author_email": "dzaporozhets@sphereconsultinginc.com", + "committer_name": "Dmitriy Zaporozhets", + "committer_email": "dzaporozhets@sphereconsultinginc.com", + "created_at": "2018-09-20T09:26:24.000-07:00", + "message": "Updated submodule example_submodule with oid 3ddec28ea23acc5caa5d8331a6ecb2a65fc03e88", + "parent_ids": [ + "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" + ], + "committed_date": "2018-09-20T09:26:24.000-07:00", + "authored_date": "2018-09-20T09:26:24.000-07:00", + "status": null +} +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 66476e7db64..071c13f41cb 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -11,11 +11,15 @@ Get a list of specific runners available to the user. ``` GET /runners GET /runners?scope=active +GET /runners?type=project_type +GET /runners?status=active ``` | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `scope` | string | no | The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners" @@ -56,11 +60,15 @@ is restricted to users with `admin` privileges. ``` GET /runners/all GET /runners/all?scope=online +GET /runners/all?type=project_type +GET /runners/all?status=active ``` | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `scope` | string | no | The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/all" @@ -286,6 +294,7 @@ Example response: "created_at": "2017-11-16T18:38:46.000Z", "bio": null, "location": null, + "public_email": "", "skype": "", "linkedin": "", "twitter": "", @@ -331,16 +340,21 @@ Example response: ## List project's runners List all runners (specific and shared) available in the project. Shared runners -are listed if at least one shared runner is defined **and** shared runners -usage is enabled in the project's settings. +are listed if at least one shared runner is defined. ``` GET /projects/:id/runners +GET /projects/:id/runners?scope=active +GET /projects/:id/runners?type=project_type +GET /projects/:id/runners?status=active ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| +| Attribute | Type | Required | Description | +|-----------|----------------|----------|---------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" diff --git a/doc/api/services.md b/doc/api/services.md index 741ea83070f..f122bac6f1f 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -10,7 +10,7 @@ Asana - Teamwork without email Set Asana service for a project. -> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your Api Keys here: https://asana.com/developers/documentation/getting-started/auth#api-key +> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found will get the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your Api Keys here: <https://asana.com/developers/documentation/getting-started/auth#api-key>. ``` PUT /projects/:id/services/asana @@ -92,7 +92,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `bamboo_url` | string | true | Bamboo root URL like https://bamboo.example.com | +| `bamboo_url` | string | true | Bamboo root URL. For example, `https://bamboo.example.com`. | | `build_key` | string | true | Bamboo build plan key like KEY | | `username` | string | true | A user with API access, if applicable | | `password` | string | true | Password of the user | @@ -117,7 +117,7 @@ GET /projects/:id/services/bamboo Bugzilla Issue Tracker -### Create/Edit Buildkite service +### Create/Edit Bugzilla service Set Bugzilla service for a project. @@ -168,7 +168,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `token` | string | true | Buildkite project GitLab token | -| `project_url` | string | true | https://buildkite.com/example/project | +| `project_url` | string | true | `https://buildkite.com/example/project` | | `enable_ssl_verification` | boolean | false | Enable SSL verification | ### Delete Buildkite service @@ -278,7 +278,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `token` | string | true | Drone CI project specific token | -| `drone_url` | string | true | http://drone.example.com | +| `drone_url` | string | true | `http://drone.example.com` | | `enable_ssl_verification` | boolean | false | Enable SSL verification | ### Delete Drone CI service @@ -421,7 +421,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Hangouts Chat webhook. e.g. https://chat.googleapis.com/v1/spaces... | +| `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | Send notifications only for the default branch | | `push_events` | boolean | false | Enable notifications for push events | @@ -470,7 +470,7 @@ Parameters: | `notify` | boolean | false | Enable notifications | | `room` | string | false |Room name or ID | | `api_version` | string | false | Leave blank for default (v2) | -| `server` | string | false | Leave blank for default. https://hipchat.example.com | +| `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. | ### Delete HipChat service @@ -496,7 +496,7 @@ Send IRC messages, on update, to a list of recipients through an Irker gateway. Set Irker (IRC gateway) service for a project. -> NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: http://www.catb.org/~esr/irker/security.html. +> NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>. ``` PUT /projects/:id/services/irker @@ -546,7 +546,7 @@ Set JIRA service for a project. > **Notes:** > - Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and -> `project_url` are replaced by `project_key`, `url`. If you are using an +> `project_url` are replaced by `project_key`, `url`. If you are using an > older version, [follow this documentation][old-jira-api]. ``` @@ -557,7 +557,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `url` | string | yes | The URL to the JIRA project which is being linked to this GitLab project, e.g., `https://jira.example.com`. | +| `url` | string | yes | The URL to the JIRA project which is being linked to this GitLab project. For example, `https://jira.example.com`. | | `project_key` | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | | `username` | string | yes | The username of the user created to be used with GitLab/JIRA. | | `password` | string | yes | The password of the user created to be used with GitLab/JIRA. | @@ -589,7 +589,7 @@ PUT /projects/:id/services/kubernetes Parameters: - `namespace` (**required**) - The Kubernetes namespace to use -- `api_url` (**required**) - The URL to the Kubernetes cluster API, e.g., https://kubernetes.example.com +- `api_url` (**required**) - The URL to the Kubernetes cluster API. For example, `https://kubernetes.example.com` - `token` (**required**) - The service token to authenticate against the Kubernetes cluster with - `ca_pem` (optional) - A custom certificate authority bundle to verify the Kubernetes cluster with (PEM format) @@ -658,7 +658,6 @@ Parameters: | --------- | ---- | -------- | ----------- | | `token` | string | yes | The Slack token | - ### Delete Slack slash command service Delete Slack slash command service for a project. @@ -823,7 +822,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `api_url` | string | true | Prometheus API Base URL, like http://prometheus.example.com/ | +| `api_url` | string | true | Prometheus API Base URL. For example, `http://prometheus.example.com/`. | ### Delete Prometheus service @@ -934,7 +933,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `webhook` | string | true | https://hooks.slack.com/services/... | +| `webhook` | string | true | `https://hooks.slack.com/services/...` | | `username` | string | false | username | | `channel` | string | false | Default channel to use if others are not configured | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | @@ -988,7 +987,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Microsoft Teams webhook. e.g. https://outlook.office.com/webhook/... | +| `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` | ### Delete Microsoft Teams service @@ -1024,7 +1023,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Mattermost webhook. e.g. http://mattermost_host/hooks/... | +| `webhook` | string | true | The Mattermost webhook. For example, `http://mattermost_host/hooks/...` | | `username` | string | false | username | | `channel` | string | false | Default channel to use if others are not configured | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | @@ -1080,7 +1079,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `teamcity_url` | string | true | TeamCity root URL like https://teamcity.example.com | +| `teamcity_url` | string | true | TeamCity root URL. For example, `https://teamcity.example.com` | | `build_type` | string | true | Build configuration ID | | `username` | string | true | A user with permissions to trigger a manual build | | `password` | string | true | The password of the user | @@ -1104,7 +1103,6 @@ GET /projects/:id/services/teamcity [jira-doc]: ../user/project/integrations/jira.md [old-jira-api]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/api/services.md#jira - ## MockCI Mock an external CI. See [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) for an example of a companion mock service. @@ -1123,7 +1121,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `mock_service_url` | string | true | http://localhost:4004 | +| `mock_service_url` | string | true | `http://localhost:4004` | ### Delete MockCI service diff --git a/doc/api/settings.md b/doc/api/settings.md index 83fa9b055d1..9b38e3a4eb7 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,3 +1,7 @@ +--- +table_display_block: true +--- + # Application settings API These API calls allow you to read and modify GitLab instance @@ -45,8 +49,6 @@ Example response: "sign_in_text" : null, "container_registry_token_expire_delay": 5, "repository_storages": ["default"], - "koding_enabled": false, - "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, "terminal_max_session_time": 0, @@ -103,8 +105,6 @@ Example response: "after_sign_out_path": "", "container_registry_token_expire_delay": 5, "repository_storages": ["default"], - "koding_enabled": false, - "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, "terminal_max_session_time": 0, @@ -138,11 +138,6 @@ are listed in the descriptions of the relevant settings. | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | -| `circuitbreaker_access_retries` | integer | no | The number of attempts GitLab will make to access a storage. | -| `circuitbreaker_check_interval` | integer | no | Number of seconds in between storage checks. | -| `circuitbreaker_failure_count_threshold` | integer | no | The number of failures after which GitLab will completely prevent access to the storage. | -| `circuitbreaker_failure_reset_time` | integer | no | Time in seconds GitLab will keep storage failure information. When no failures occur during this time, the failure information is reset. | -| `circuitbreaker_storage_timeout` | integer | no | Seconds to wait for a storage access attempt. | | `clientside_sentry_dsn` | string | required by: `clientside_sentry_enabled` | Clientside Sentry Data Source Name. | | `clientside_sentry_enabled` | boolean | no | (**If enabled, requires:** `clientside_sentry_dsn`) Enable Sentry error reporting for the client side. | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | @@ -180,8 +175,6 @@ are listed in the descriptions of the relevant settings. | `html_emails_enabled` | boolean | no | Enable HTML emails. | | `instance_statistics_visibility_private` | boolean | no | When set to `true` Instance statistics will only be available to admins. | | `import_sources` | array of strings | no | Sources to allow project import from, possible values: `github`, `bitbucket`, `gitlab`, `google_code`, `fogbugz`, `git`, and `gitlab_project`. | -| `koding_enabled` | boolean | no | (If enabled, requires: `koding_url`) Enable Koding integration. Default is `false`. | -| `koding_url` | string | required by: `koding_enabled` | The Koding instance URL for integration. | | `max_artifacts_size` | integer | no | Maximum artifacts size in MB | | `max_attachment_size` | integer | no | Limit attachment size in MB | | `max_pages_size` | integer | no | Maximum size of pages repositories in MB | @@ -193,7 +186,7 @@ are listed in the descriptions of the relevant settings. | `metrics_port` | integer | required by: `metrics_enabled` | The UDP port to use for connecting to InfluxDB. | | `metrics_sample_interval` | integer | required by: `metrics_enabled` | The sampling interval in seconds. | | `metrics_timeout` | integer | required by: `metrics_enabled` | The amount of seconds after which InfluxDB will time out. | -| `mirror_available` | boolean | no | Allow mirrors to be setup for projects. If disabled, only admins will be able to setup mirrors in projects. | +| `mirror_available` | boolean | no | Allow mirrors to be set up for projects. If disabled, only admins will be able to set up mirrors in projects. | | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | @@ -219,9 +212,6 @@ are listed in the descriptions of the relevant settings. | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text`) Enable shared runners for new projects. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | -| `sidekiq_throttling_enabled` | boolean | no | (**If enabled, requires:** `sidekiq_throttling_factor` and `sidekiq_throttling_queues`) Enable Sidekiq Job Throttling. | -| `sidekiq_throttling_factor` | decimal | required by: `sidekiq_throttling_enabled` | The factor by which the queues should be throttled. A value between `0.0` and `1.0`, exclusive. | -| `sidekiq_throttling_queues` | array of strings | required by: `sidekiq_throttling_enabled` | Choose which queues you wish to throttle. | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 7892866cd8e..e840e640377 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -37,13 +37,13 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | Integer | yes | The ID of a snippet | -``` bash +```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/1 ``` Example response: -``` json +```json { "id": 1, "title": "test", @@ -65,6 +65,30 @@ Example response: } ``` +## Single snippet contents + +Get a single snippet's raw contents. + +``` +GET /snippets/:id/raw +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | Integer | yes | The ID of a snippet | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/1/raw +``` + +Example response: + +``` +Hello World snippet +``` + ## Create new snippet Creates a new snippet. The user must have permission to create new snippets. @@ -84,7 +108,7 @@ Parameters: | `visibility` | String | no | The snippet's visibility | -``` bash +```bash curl --request POST \ --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ --header 'Content-Type: application/json' \ @@ -94,7 +118,7 @@ curl --request POST \ Example response: -``` json +```json { "id": 1, "title": "This is a snippet", @@ -136,7 +160,7 @@ Parameters: | `visibility` | String | no | The snippet's visibility | -``` bash +```bash curl --request PUT \ --data '{"title": "foo", "content": "bar"}' \ --header 'Content-Type: application/json' \ @@ -146,7 +170,7 @@ curl --request PUT \ Example response: -``` json +```json { "id": 1, "title": "test", @@ -201,13 +225,13 @@ GET /snippets/public | `per_page` | Integer | no | number of snippets to return per page | | `page` | Integer | no | the page to retrieve | -``` bash +```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1 ``` Example response: -``` json +```json [ { "author": { diff --git a/doc/api/tags.md b/doc/api/tags.md index f2a3f9f28d2..826900ca518 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -134,7 +134,7 @@ Parameters: "description": "Amazing release. Wow" }, "name": "v1.0.0", - "target: "2695effb5807a22ff3d138d593fd856244e155e7", + "target": "2695effb5807a22ff3d138d593fd856244e155e7", "message": null } ``` diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md new file mode 100644 index 00000000000..a08b8d33693 --- /dev/null +++ b/doc/api/templates/dockerfiles.md @@ -0,0 +1,113 @@ +# Dockerfiles API + +## List Dockerfile templates + +Get all Dockerfile templates. + +``` +GET /templates/dockerfiles +``` + +```bash +curl https://gitlab.example.com/api/v4/templates/dockerfiles +``` + +Example response: + +```json +[ + { + "key": "Binary", + "name": "Binary" + }, + { + "key": "Binary-alpine", + "name": "Binary-alpine" + }, + { + "key": "Binary-scratch", + "name": "Binary-scratch" + }, + { + "key": "Golang", + "name": "Golang" + }, + { + "key": "Golang-alpine", + "name": "Golang-alpine" + }, + { + "key": "Golang-scratch", + "name": "Golang-scratch" + }, + { + "key": "HTTPd", + "name": "HTTPd" + }, + { + "key": "Node", + "name": "Node" + }, + { + "key": "Node-alpine", + "name": "Node-alpine" + }, + { + "key": "OpenJDK", + "name": "OpenJDK" + }, + { + "key": "OpenJDK-alpine", + "name": "OpenJDK-alpine" + }, + { + "key": "PHP", + "name": "PHP" + }, + { + "key": "Python", + "name": "Python" + }, + { + "key": "Python-alpine", + "name": "Python-alpine" + }, + { + "key": "Python2", + "name": "Python2" + }, + { + "key": "Ruby", + "name": "Ruby" + }, + { + "key": "Ruby-alpine", + "name": "Ruby-alpine" + } +] +``` + +## Single Dockerfile template + +Get a single Dockerfile template. + +``` +GET /templates/dockerfiles/:key +``` + +| Attribute | Type | Required | Description | +| ---------- | ------ | -------- | ----------- | +| `key` | string | yes | The key of the Dockerfile template | + +```bash +curl https://gitlab.example.com/api/v4/templates/dockerfiles/Binary +``` + +Example response: + +```json +{ + "name": "Binary", + "content": "# This file is a template, and might need editing before it works on your project.\n# This Dockerfile installs a compiled binary into a bare system.\n# You must either commit your compiled binary into source control (not recommended)\n# or build the binary first as part of a CI/CD pipeline.\n\nFROM buildpack-deps:jessie\n\nWORKDIR /usr/local/bin\n\n# Change `app` to whatever your binary is called\nAdd app .\nCMD [\"./app\"]\n" +} +``` diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index d3f5c88ca90..3804855129c 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -17,538 +17,84 @@ Example response: ```json [ { - "name": "AppEngine" - }, - { - "name": "Laravel" - }, - { - "name": "Elisp" - }, - { - "name": "SketchUp" + "key": "Actionscript", + "name": "Actionscript" }, { + "key": "Ada", "name": "Ada" }, { - "name": "Ruby" - }, - { - "name": "Kohana" - }, - { - "name": "Nanoc" - }, - { - "name": "Erlang" - }, - { - "name": "OCaml" - }, - { - "name": "Lithium" - }, - { - "name": "Fortran" - }, - { - "name": "Scala" - }, - { - "name": "Node" - }, - { - "name": "Fancy" - }, - { - "name": "Perl" - }, - { - "name": "Zephir" - }, - { - "name": "WordPress" - }, - { - "name": "Symfony" - }, - { - "name": "FuelPHP" - }, - { - "name": "DM" - }, - { - "name": "Sdcc" - }, - { - "name": "Rust" - }, - { - "name": "C" - }, - { - "name": "Umbraco" - }, - { - "name": "Actionscript" + "key": "Agda", + "name": "Agda" }, { + "key": "Android", "name": "Android" }, { - "name": "Grails" - }, - { - "name": "Composer" - }, - { - "name": "ExpressionEngine" - }, - { - "name": "Gcov" - }, - { - "name": "Qt" + "key": "AppEngine", + "name": "AppEngine" }, { - "name": "Phalcon" + "key": "AppceleratorTitanium", + "name": "AppceleratorTitanium" }, { + "key": "ArchLinuxPackages", "name": "ArchLinuxPackages" }, { - "name": "TeX" - }, - { - "name": "SCons" - }, - { - "name": "Lilypond" - }, - { - "name": "CommonLisp" - }, - { - "name": "Rails" - }, - { - "name": "Mercury" - }, - { - "name": "Magento" - }, - { - "name": "ChefCookbook" - }, - { - "name": "GitBook" - }, - { - "name": "C++" - }, - { - "name": "Eagle" - }, - { - "name": "Go" - }, - { - "name": "OpenCart" - }, - { - "name": "Scheme" - }, - { - "name": "Typo3" - }, - { - "name": "SeamGen" - }, - { - "name": "Swift" - }, - { - "name": "Elm" - }, - { - "name": "Unity" - }, - { - "name": "Agda" - }, - { - "name": "CUDA" - }, - { - "name": "VVVV" - }, - { - "name": "Finale" - }, - { - "name": "LemonStand" - }, - { - "name": "Textpattern" - }, - { - "name": "Julia" - }, - { - "name": "Packer" - }, - { - "name": "Scrivener" - }, - { - "name": "Dart" - }, - { - "name": "Plone" - }, - { - "name": "Jekyll" - }, - { - "name": "Xojo" - }, - { - "name": "LabVIEW" - }, - { + "key": "Autotools", "name": "Autotools" }, { - "name": "KiCad" - }, - { - "name": "Prestashop" - }, - { - "name": "ROS" - }, - { - "name": "Smalltalk" - }, - { - "name": "GWT" - }, - { - "name": "OracleForms" - }, - { - "name": "SugarCRM" - }, - { - "name": "Nim" - }, - { - "name": "SymphonyCMS" + "key": "C", + "name": "C" }, { - "name": "Maven" + "key": "C++", + "name": "C++" }, { + "key": "CFWheels", "name": "CFWheels" }, { - "name": "Python" - }, - { - "name": "ZendFramework" - }, - { - "name": "CakePHP" - }, - { - "name": "Concrete5" - }, - { - "name": "PlayFramework" - }, - { - "name": "Terraform" - }, - { - "name": "Elixir" - }, - { + "key": "CMake", "name": "CMake" }, { - "name": "Joomla" - }, - { - "name": "Coq" - }, - { - "name": "Delphi" - }, - { - "name": "Haskell" - }, - { - "name": "Yii" - }, - { - "name": "Java" - }, - { - "name": "UnrealEngine" - }, - { - "name": "AppceleratorTitanium" - }, - { - "name": "CraftCMS" - }, - { - "name": "ForceDotCom" - }, - { - "name": "ExtJs" - }, - { - "name": "MetaProgrammingSystem" - }, - { - "name": "D" - }, - { - "name": "Objective-C" - }, - { - "name": "RhodesRhomobile" - }, - { - "name": "R" - }, - { - "name": "EPiServer" - }, - { - "name": "Yeoman" - }, - { - "name": "VisualStudio" - }, - { - "name": "Processing" - }, - { - "name": "Leiningen" - }, - { - "name": "Stella" - }, - { - "name": "Opa" - }, - { - "name": "Drupal" - }, - { - "name": "TurboGears2" - }, - { - "name": "Idris" - }, - { - "name": "Jboss" - }, - { - "name": "CodeIgniter" - }, - { - "name": "Qooxdoo" - }, - { - "name": "Waf" + "key": "CUDA", + "name": "CUDA" }, { - "name": "Sass" + "key": "CakePHP", + "name": "CakePHP" }, { - "name": "Lua" + "key": "ChefCookbook", + "name": "ChefCookbook" }, { + "key": "Clojure", "name": "Clojure" }, { - "name": "IGORPro" - }, - { - "name": "Gradle" - }, - { - "name": "Archives" - }, - { - "name": "SynopsysVCS" - }, - { - "name": "Ninja" - }, - { - "name": "Tags" - }, - { - "name": "OSX" - }, - { - "name": "Dreamweaver" - }, - { - "name": "CodeKit" - }, - { - "name": "NotepadPP" - }, - { - "name": "VisualStudioCode" - }, - { - "name": "Mercurial" - }, - { - "name": "BricxCC" - }, - { - "name": "DartEditor" - }, - { - "name": "Eclipse" - }, - { - "name": "Cloud9" - }, - { - "name": "TortoiseGit" - }, - { - "name": "NetBeans" - }, - { - "name": "GPG" - }, - { - "name": "Espresso" - }, - { - "name": "Redcar" - }, - { - "name": "Xcode" - }, - { - "name": "Matlab" - }, - { - "name": "LyX" - }, - { - "name": "SlickEdit" - }, - { - "name": "Dropbox" - }, - { - "name": "CVS" - }, - { - "name": "Calabash" - }, - { - "name": "JDeveloper" - }, - { - "name": "Vagrant" - }, - { - "name": "IPythonNotebook" - }, - { - "name": "TextMate" - }, - { - "name": "Ensime" - }, - { - "name": "WebMethods" - }, - { - "name": "VirtualEnv" - }, - { - "name": "Emacs" - }, - { - "name": "Momentics" - }, - { - "name": "JetBrains" - }, - { - "name": "SublimeText" - }, - { - "name": "Kate" - }, - { - "name": "ModelSim" - }, - { - "name": "Redis" - }, - { - "name": "KDevelop4" - }, - { - "name": "Bazaar" - }, - { - "name": "Linux" - }, - { - "name": "Windows" - }, - { - "name": "XilinxISE" - }, - { - "name": "Lazarus" - }, - { - "name": "EiffelStudio" - }, - { - "name": "Anjuta" - }, - { - "name": "Vim" - }, - { - "name": "Otto" - }, - { - "name": "MicrosoftOffice" - }, - { - "name": "LibreOffice" - }, - { - "name": "SBT" + "key": "CodeIgniter", + "name": "CodeIgniter" }, { - "name": "MonoDevelop" + "key": "CommonLisp", + "name": "CommonLisp" }, { - "name": "SVN" + "key": "Composer", + "name": "Composer" }, { - "name": "FlexBuilder" + "key": "Concrete5", + "name": "Concrete5" } ] ``` diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index bdb128fc336..cecfc8cd9b9 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -17,79 +17,84 @@ Example response: ```json [ { - "name": "C++" - }, - { - "name": "Docker" - }, - { - "name": "Elixir" - }, - { - "name": "LaTeX" - }, - { - "name": "Grails" - }, - { - "name": "Rust" + "key": "Android", + "name": "Android" }, { - "name": "Nodejs" + "key": "Auto-DevOps", + "name": "Auto-DevOps" }, { - "name": "Ruby" + "key": "Bash", + "name": "Bash" }, { - "name": "Scala" + "key": "C++", + "name": "C++" }, { - "name": "Maven" + "key": "Chef", + "name": "Chef" }, { - "name": "Harp" + "key": "Clojure", + "name": "Clojure" }, { - "name": "Pelican" + "key": "Crystal", + "name": "Crystal" }, { - "name": "Hyde" + "key": "Django", + "name": "Django" }, { - "name": "Nanoc" + "key": "Docker", + "name": "Docker" }, { - "name": "Octopress" + "key": "Elixir", + "name": "Elixir" }, { - "name": "JBake" + "key": "Go", + "name": "Go" }, { - "name": "HTML" + "key": "Gradle", + "name": "Gradle" }, { - "name": "Hugo" + "key": "Grails", + "name": "Grails" }, { - "name": "Metalsmith" + "key": "Julia", + "name": "Julia" }, { - "name": "Hexo" + "key": "LaTeX", + "name": "LaTeX" }, { - "name": "Lektor" + "key": "Laravel", + "name": "Laravel" }, { - "name": "Doxygen" + "key": "Maven", + "name": "Maven" }, { - "name": "Brunch" + "key": "Mono", + "name": "Mono" }, { - "name": "Jekyll" + "key": "Nodejs", + "name": "Nodejs" }, { - "name": "Middleman" + "key": "OpenShift", + "name": "OpenShift" } ] ``` diff --git a/doc/api/users.md b/doc/api/users.md index b0ae455a025..1cf4444319c 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -59,6 +59,9 @@ GET /users?active=true GET /users?blocked=true ``` +NOTE: **Note:** +Username search is case insensitive. + ### For admins ``` @@ -67,8 +70,8 @@ GET /users | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` | +| `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | | `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | ```json @@ -199,6 +202,7 @@ Parameters: "created_at": "2012-05-23T08:00:58Z", "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -230,6 +234,7 @@ Parameters: "is_admin": false, "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -286,6 +291,7 @@ Parameters: - `provider` (optional) - External provider name - `bio` (optional) - User's biography - `location` (optional) - User's location +- `public_email` (optional) - The public email of the user - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false - `skip_confirmation` (optional) - Skip confirmation - true or false (default) @@ -303,26 +309,27 @@ PUT /users/:id Parameters: -- `email` - Email -- `username` - Username -- `name` - Name -- `password` - Password -- `skype` - Skype ID -- `linkedin` - LinkedIn -- `twitter` - Twitter account -- `website_url` - Website URL -- `organization` - Organization name -- `projects_limit` - Limit projects each user can create -- `extern_uid` - External UID -- `provider` - External provider name -- `bio` - User's biography -- `location` (optional) - User's location -- `admin` (optional) - User is admin - true or false (default) -- `can_create_group` (optional) - User can create groups - true or false +- `email` - Email +- `username` - Username +- `name` - Name +- `password` - Password +- `skype` - Skype ID +- `linkedin` - LinkedIn +- `twitter` - Twitter account +- `website_url` - Website URL +- `organization` - Organization name +- `projects_limit` - Limit projects each user can create +- `extern_uid` - External UID +- `provider` - External provider name +- `bio` - User's biography +- `location` (optional) - User's location +- `public_email` (optional) - The public email of the user +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false - `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default) -- `external` (optional) - Flags the user as external - true or false(default) -- `avatar` (optional) - Image file for user's avatar -- `private_profile` (optional) - User's profile is private - true or false +- `external` (optional) - Flags the user as external - true or false(default) +- `avatar` (optional) - Image file for user's avatar +- `private_profile` (optional) - User's profile is private - true or false On password update, user will be forced to change it upon next login. Note, at the moment this method does only return a `404` error, @@ -367,6 +374,7 @@ GET /user "created_at": "2012-05-23T08:00:58Z", "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -415,6 +423,7 @@ GET /user "is_admin": false, "bio": null, "location": null, + "public_email": "john@example.com", "skype": "", "linkedin": "", "twitter": "", @@ -552,7 +561,7 @@ Parameters: ## List SSH keys for user -Get a list of a specified user's SSH keys. Available only for admin +Get a list of a specified user's SSH keys. ``` GET /users/:id/keys @@ -1063,7 +1072,6 @@ Example response: [ { "active" : true, - "token" : "EsMo-vhKfXGwX9RKrwiy", "scopes" : [ "api" ], @@ -1080,7 +1088,6 @@ Example response: "read_user" ], "revoked" : true, - "token" : "ZcZRpLeEuQRprkRjYydY", "name" : "mytoken2", "created_at" : "2017-03-17T17:19:28.697Z", "id" : 3, @@ -1116,7 +1123,6 @@ Example response: ```json { "active" : true, - "token" : "EsMo-vhKfXGwX9RKrwiy", "scopes" : [ "api" ], @@ -1133,6 +1139,8 @@ Example response: > Requires admin permissions. +> Token values are returned once. Make sure you save it - you won't be able to access it again. + It creates a new impersonation token. Note that only administrators can do this. You are only able to create impersonation tokens to impersonate the user and perform both API calls and Git reads and writes. The user will not see these tokens in their profile diff --git a/doc/api/wikis.md b/doc/api/wikis.md index fb0ec773da5..df3b54e8f89 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -65,14 +65,12 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a Example response: ```json -[ - { - "content" : "home page", - "format" : "markdown", - "slug" : "home", - "title" : "home" - } -] +{ + "content" : "home page", + "format" : "markdown", + "slug" : "home", + "title" : "home" +} ``` ## Create a new wiki page diff --git a/doc/ci/README.md b/doc/ci/README.md index d782d64e971..dba1f38abe2 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -132,5 +132,3 @@ your whole GitLab instance as well as in each project. - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your jobs. There's a new way to access your Git submodules and LFS objects in jobs. - -[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md index cc6c9ec0e0a..1473703542d 100644 --- a/doc/ci/autodeploy/quick_start_guide.md +++ b/doc/ci/autodeploy/quick_start_guide.md @@ -11,7 +11,7 @@ We made a minimal [Ruby application](https://gitlab.com/gitlab-examples/minimal- Let’s start by forking our sample application. Go to [the project page](https://gitlab.com/gitlab-examples/minimal-ruby-app) and press the `Fork` button. Soon you should have a project under your namespace with the necessary files. -## Setup your own cluster on Google Kubernetes Engine +## Set up your own cluster on Google Kubernetes Engine If you do not already have a Google Cloud account, create one at https://console.cloud.google.com. @@ -23,9 +23,9 @@ You need to have the Google Cloud SDK installed. e.g. On OSX, install [homebrew](https://brew.sh): 1. Install Brew Caskroom: `brew install caskroom/cask/brew-cask` -2. Install Google Cloud SDK: `brew cask install google-cloud-sdk` -3. Add `kubectl`: `gcloud components install kubectl` -4. Log in: `gcloud auth login` +1. Install Google Cloud SDK: `brew cask install google-cloud-sdk` +1. Add `kubectl`: `gcloud components install kubectl` +1. Log in: `gcloud auth login` Now go back to the Google interface, find your cluster, and follow the instructions under `Connect to the cluster` and open the Kubernetes Dashboard. It will look something like `gcloud container clusters get-credentials ruby-autodeploy \ --zone europe-west2-c --project api-project-XXXXXXX` and then `kubectl proxy`. @@ -71,7 +71,7 @@ Use this IP address to configure your DNS. This part heavily depends on your pre Use `nslookup minimal-ruby-app-staging.<yourdomain>` to confirm that domain is assigned to the cluster IP. -## Setup Auto Deploy +## Set up Auto Deploy Visit the home page of your GitLab.com project and press "Set up Auto Deploy" button. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index b41101695f6..758ab37861b 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -178,8 +178,8 @@ runs of jobs for things like dependencies and commonly used libraries so they don't have to be re-fetched from the public internet. NOTE: **Note:** -For more examples, check the [GitLab CI Yml](https://gitlab.com/gitlab-org/gitlab-ci-yml) -project. +For more examples, check out our [GitLab CI/CD +templates](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates). ### Caching Nodejs dependencies @@ -190,7 +190,7 @@ Nodejs modules are installed in `node_modules/` and are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Nodejs.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Nodejs.gitlab-ci.yml # image: node:latest @@ -217,7 +217,7 @@ are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/PHP.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/PHP.gitlab-ci.yml # image: php:7.2 @@ -246,14 +246,14 @@ pip's cache is defined under `.cache/pip/` and both are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Python.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml # image: python:latest # Change pip's cache directory to be inside the project directory since we can # only cache local items. variables: - PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache" + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" # Pip's cache doesn't store the python packages # https://pip.pypa.io/en/stable/reference/pip_install/#caching @@ -262,7 +262,7 @@ variables: # them in a virtualenv and cache it as well. cache: paths: - - .cache/ + - .cache/pip - venv/ before_script: @@ -286,7 +286,7 @@ jobs inherit it. Gems are installed in `vendor/ruby/` and are cached per-branch: ```yaml # -# https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Ruby.gitlab-ci.yml +# https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates/Ruby.gitlab-ci.yml # image: ruby:2.5 diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index aa997d15b64..fef367051bf 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -46,18 +46,18 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. --description "My Runner" ``` -2. Install Docker Engine on server. +1. Install Docker Engine on server. For more information how to install Docker Engine on different systems checkout the [Supported installations](https://docs.docker.com/engine/installation/). -3. Add `gitlab-runner` user to `docker` group: +1. Add `gitlab-runner` user to `docker` group: ```bash sudo usermod -aG docker gitlab-runner ``` -4. Verify that `gitlab-runner` has access to Docker: +1. Verify that `gitlab-runner` has access to Docker: ```bash sudo -u gitlab-runner -H docker info @@ -75,7 +75,7 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. - docker run my-docker-image /script/to/run/tests ``` -5. You can now use `docker` command and install `docker-compose` if needed. +1. You can now use `docker` command and install `docker-compose` if needed. NOTE: **Note:** By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions. @@ -314,8 +314,8 @@ build: stage: build script: - docker pull $CONTAINER_IMAGE:latest || true - - docker build --cache-from $CONTAINER_IMAGE:latest --tag $CONTAINER_IMAGE:$CI_BUILD_REF --tag $CONTAINER_IMAGE:latest . - - docker push $CONTAINER_IMAGE:$CI_BUILD_REF + - docker build --cache-from $CONTAINER_IMAGE:latest --tag $CONTAINER_IMAGE:$CI_COMMIT_SHA --tag $CONTAINER_IMAGE:latest . + - docker push $CONTAINER_IMAGE:$CI_COMMIT_SHA - docker push $CONTAINER_IMAGE:latest ``` @@ -395,8 +395,67 @@ If you're running multiple Runners you will have to modify all configuration fil > login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in -[GitLab Container Registry](../../user/project/container_registry.md). For example, -if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml` +[GitLab Container Registry](../../user/project/container_registry.md). +Some things you should be aware of: + +- You must [log in to the container registry](#authenticating-to-the-container-registry) + before running commands. You can do this in the `before_script` if multiple + jobs depend on it. +- Using `docker build --pull` fetches any changes to base + images before building just in case your cache is stale. It takes slightly + longer, but means you don’t get stuck without security patches to base images. +- Doing an explicit `docker pull` before each `docker run` fetches + the latest image that was just built. This is especially important if you are + using multiple runners that cache images locally. Using the git SHA in your + image tag makes this less necessary since each job will be unique and you + shouldn't ever have a stale image. However, it's still possible to have a + stale image if you re-build a given commit after a dependency has changed. +- You don't want to build directly to `latest` tag in case there are multiple jobs + happening simultaneously. + +### Authenticating to the Container Registry + +There are three ways to authenticate to the Container Registry via GitLab CI/CD +and depend on the visibility of your project. + +For all projects, mostly suitable for public ones: + +- **Using the special `gitlab-ci-token` user**: This user is created for you in order to + push to the Registry connected to your project. Its password is automatically + set with the `$CI_JOB_TOKEN` variable. This allows you to automate building and deploying + your Docker images and has read/write access to the Registry. This is ephemeral, + so it's only valid for one job. You can use the following example as-is: + + ```sh + docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + ``` + +For private and internal projects: + +- **Using a personal access token**: You can create and use a + [personal access token](../../user/profile/personal_access_tokens.md) + in case your project is private: + - For read (pull) access, the scope should be `read_registry`. + - For read/write (pull/push) access, use `api`. + Replace the `<username>` and `<access_token>` in the following example: + + ```sh + docker login -u <username> -p <access_token> $CI_REGISTRY + ``` + +- **Using the GitLab Deploy Token**: You can create and use a + [special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) + with your private projects. It provides read-only (pull) access to the Registry. + Once created, you can use the special environment variables, and GitLab CI/CD + will fill them in for you. You can use the following example as-is: + + ```sh + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` + +### Container Registry examples + +If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml` could look like: ```yaml @@ -414,11 +473,6 @@ could look like: - docker push registry.example.com/group/project/image:latest ``` -You have to use the special `gitlab-ci-token` user created for you in order to -push to the Registry connected to your project. Its password is provided in the -`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment -of your Docker images. - You can also make use of [other variables](../variables/README.md) to avoid hardcoding: ```yaml @@ -508,22 +562,6 @@ deploy: - master ``` -Some things you should be aware of when using the Container Registry: - -- You must log in to the container registry before running commands. Putting - this in `before_script` will run it before each job. -- Using `docker build --pull` makes sure that Docker fetches any changes to base - images before building just in case your cache is stale. It takes slightly - longer, but means you don’t get stuck without security patches to base images. -- Doing an explicit `docker pull` before each `docker run` makes sure to fetch - the latest image that was just built. This is especially important if you are - using multiple runners that cache images locally. Using the git SHA in your - image tag makes this less necessary since each job will be unique and you - shouldn't ever have a stale image, but it's still possible if you re-build a - given commit after a dependency has changed. -- You don't want to build directly to `latest` in case there are multiple jobs - happening simultaneously. - [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [2fa]: ../../user/profile/account/two_factor_authentication.md diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 9abedcc6acb..959271d8abc 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -67,6 +67,9 @@ services you need to `.gitlab-ci.yml` or manually modify `config.toml`. Any image found at [Docker Hub][hub] or your private Container Registry can be used as a service. +Services inherit the same DNS servers, search domains, and additional hosts as +the CI container itself. + You can see some widely used services examples in the relevant documentation of [CI services examples](../services/README.md). @@ -461,25 +464,25 @@ that runner. > - If the repository is private you need to authenticate your GitLab Runner in the > registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg]. -As an example, let's assume that you want to use the `registry.example.com/private/image:latest` +As an example, let's assume that you want to use the `registry.example.com:5000/private/image:latest` image which is private and requires you to login into a private container registry. Let's also assume that these are the login credentials: -| Key | Value | -|----------|----------------------| -| registry | registry.example.com | -| username | my_username | -| password | my_password | +| Key | Value | +|----------|---------------------------| +| registry | registry.example.com:5000 | +| username | my_username | +| password | my_password | -To configure access for `registry.example.com`, follow these steps: +To configure access for `registry.example.com:5000`, follow these steps: 1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to accomplish this: - **First way -** Do a `docker login` on your local machine: ```bash - docker login registry.example.com --username my_username --password my_password + docker login registry.example.com:5000 --username my_username --password my_password ``` Then copy the content of `~/.docker/config.json`. @@ -503,7 +506,7 @@ To configure access for `registry.example.com`, follow these steps: ```json { "auths": { - "registry.example.com": { + "registry.example.com:5000": { "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" } } @@ -515,22 +518,28 @@ To configure access for `registry.example.com`, follow these steps: registry from it: ```bash - docker logout registry.example.com + docker logout registry.example.com:5000 ``` -1. You can now use any private image from `registry.example.com` defined in +1. You can now use any private image from `registry.example.com:5000` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: ```yaml - image: my.registry.tld:5000/namespace/image:tag + image: registry.example.com:5000/namespace/image:tag ``` - In the example above, GitLab Runner will look at `my.registry.tld:5000` for the + In the example above, GitLab Runner will look at `registry.example.com:5000` for the image `namespace/image:tag`. You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. +NOTE: **Note:** The full `hostname:port` combination is required everywhere +for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if +`registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, +then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`. +Specifying only `registry.example.com` will not work. + ## Configuring services Many services accept environment variables which allow you to easily change diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 7d4f28e1f47..66f0d429165 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -39,7 +39,7 @@ few important details: In the following example, kaniko is used to build a Docker image and then push it to [GitLab Container Registry](../../user/project/container_registry.md). The job will run only when a tag is pushed. A `config.json` file is created under -`/root/.docker` with the needed GitLab Container Registry credentials taken from the +`/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the [environment variables](../variables/README.md#predefined-variables-environment-variables) GitLab CI/CD provides. In the last step, kaniko uses the `Dockerfile` under the root directory of the project, builds the Docker image and pushes it to the @@ -52,8 +52,7 @@ build: name: gcr.io/kaniko-project/executor:debug entrypoint: [""] script: - - mkdir -p /root/.docker - - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /root/.docker/config.json + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG only: - tags diff --git a/doc/ci/environments.md b/doc/ci/environments.md index f1e5b00e927..315d0c5e7ef 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -370,7 +370,7 @@ review_app: url: https://$CI_COMMIT_REF_SLUG.example.com ``` -It is assumed that the user has already setup NGINX and GitLab Runner in the +It is assumed that the user has already set up NGINX and GitLab Runner in the server this job will run on. >**Note:** @@ -416,19 +416,18 @@ and/or `production`) you can see this information in the merge request itself. ### Go directly from source files to public pages on the environment -> Introduced in GitLab 8.17. +> Introduced in GitLab 8.17. In GitLab 11.5 the file links +are surfaced to the merge request widget. -To go one step further, we can specify a Route Map to get GitLab to show us "View on [environment URL]" buttons to go directly from a file to that file's representation on the deployed website. It will be exposed in a few places: - -| In the diff for a merge request, comparison or commit | In the file view | -| ------ | ------ | -|  |  | +You can specify a Route Map to get GitLab to show "View on <environment URL>" +buttons to go directly from a file to that file's representation on the +[deployed website via Review Apps](review_apps/index.md). To get this to work, you need to tell GitLab how the paths of files in your repository map to paths of pages on your website, using a Route Map. A Route Map is a file inside the repository at `.gitlab/route-map.yml`, which contains a YAML array that maps `source` paths (in the repository) to `public` paths (on the website). - -This is an example of a route map for [Middleman](https://middlemanapp.com) static websites like [http://about.gitlab.com](https://gitlab.com/gitlab-com/www-gitlab-com): +Below is an example of a route map for [Middleman](https://middlemanapp.com) static websites +like <https://gitlab.com/gitlab-com/www-gitlab-com>: ```yaml # Team data @@ -467,6 +466,25 @@ In the example above, the fact that mappings are evaluated in order of their def --- +Once you have the route mapping set up, it will be exposed in a few places: + +- In the merge request widget. The **View app** button will take you to the + environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render + the first 5 matched items from the route map, but you can filter them if more + than 5 are available. + +  + +- In the diff for a merge request, comparison, or commit. + +  + +- In the blob file view. + +  | + +--- + We now have a full development cycle, where our app is tested, built, deployed as a Review app, deployed to a staging server once the merge request is merged, and finally manually deployed to the production server. What we just described @@ -568,13 +586,13 @@ exist, you should see something like: > > - For the monitoring dashboard to appear, you need to: > - Have enabled the [Prometheus integration][prom] -> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md) > - With GitLab 9.2, all deployments to an environment are shown directly on the > monitoring dashboard If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment. -Once configured, GitLab will attempt to retrieve [supported performance metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/metrics.html) for any +Once configured, GitLab will attempt to retrieve [supported performance metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/index.html) for any environment which has had a successful deployment. If monitoring data was successfully retrieved, a Monitoring button will appear for each environment. diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 8eb96ae10b2..a8c119edaa0 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -4,12 +4,12 @@ comments: false # GitLab CI/CD Examples -A collection of `.gitlab-ci.yml` template files is maintained at the [GitLab CI/CD YAML project][gitlab-ci-templates]. When you create a new file via the UI, -GitLab will give you the option to choose one of the templates existent on this project. +A collection of [`.gitlab-ci.yml` template files][gitlab-ci-templates] is maintained in GitLab. When you create a new file via the UI, +GitLab will give you the option to choose one of these templates. If your favorite programming language or framework are missing we would love your help by sending a merge request with a new `.gitlab-ci.yml` to this project. -There's also a collection of repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork an adjust them to your own needs. +There's also a collection of repositories with [example projects](https://gitlab.com/gitlab-examples) for various languages. You can fork and adjust them to your own needs. ## Languages, frameworks, OSs @@ -45,11 +45,11 @@ There's also a collection of repositories with [example projects](https://gitlab ## Test Reports -[Collect test reports in Verify stage](../junit_test_reports.md). +[Collect test reports in Verify stage](../junit_test_reports.md) ## Code Quality analysis -**(Starter)** [Analyze your project's Code Quality](code_quality.md). +**(Starter)** [Analyze your project's Code Quality](code_quality.md) ## Static Application Security Testing (SAST) @@ -65,15 +65,15 @@ There's also a collection of repositories with [example projects](https://gitlab ## Dynamic Application Security Testing (DAST) -Scan your app for vulnerabilities with GitLab [Dynamic Application Security Testing (DAST)](dast.md). +Scan your app for vulnerabilities with GitLab [Dynamic Application Security Testing (DAST)](dast.md) ## Browser Performance Testing with Sitespeed.io -Analyze your [browser performance with Sitespeed.io](browser_performance.md). +Analyze your [browser performance with Sitespeed.io](browser_performance.md) ## GitLab CI/CD for Review Apps -- [Example project](https://gitlab.com/gitlab-examples/review-apps-nginx/) that shows how to use GitLab CI/CD for [Review Apps](../review_apps/index.html). +- [Example project](https://gitlab.com/gitlab-examples/review-apps-nginx/) that shows how to use GitLab CI/CD for [Review Apps](../review_apps/index.html) - [Dockerizing GitLab Review Apps](https://about.gitlab.com/2017/07/11/dockerizing-review-apps/) ## GitLab CI/CD for GitLab Pages @@ -87,4 +87,4 @@ language users and GitLab by sending a merge request with a guide for that langu You may want to apply for the [GitLab Community Writers Program](https://about.gitlab.com/community-writers/) to get paid for writing complete articles for GitLab. -[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml +[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 9657f52159e..6aa0edd87b4 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -16,8 +16,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory You'll create two different projects: -- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep) -- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app) +- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep ) +- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app ) We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/). We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it. diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 0dab07a7f80..7c3b3a65675 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -1,14 +1,20 @@ # Browser Performance Testing with the Sitespeed.io container +CAUTION: **Caution:** +The job definition shown below is supported on GitLab 11.5 and later versions. +It also requires the GitLab Runner 11.5 or later. +For earlier versions, use the [previous job definitions](#previous-job-definitions). + This example shows how to run the [Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) on your code by using GitLab CI/CD and [Sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. -First, you need a GitLab Runner with the +First, you need GitLab Runner with [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). -Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called -`performance`: + +Once you set up the Runner, add a new job to `.gitlab-ci.yml` that +generates the expected report: ```yaml performance: @@ -26,19 +32,22 @@ performance: - mv sitespeed-results/data/performance.json performance.json artifacts: paths: - - performance.json - - sitespeed-results/ + - sitespeed-results/ + reports: + performance: performance.json ``` -The above example will: +The above example will create a `performance` job in your CI/CD pipeline and will run +Sitespeed.io against the webpage you defined in `URL` to gather key metrics. +The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for +Sitespeed.io is downloaded in order to save the report as a +[Performance report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportsperformance) +that you can later download and analyze. +Due to implementation limitations we always take the latest Performance artifact available. -1. Create a `performance` job in your CI/CD pipeline and will run - Sitespeed.io against the webpage you defined in `URL`. -1. The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for - Sitespeed.io is downloaded in order to export key metrics to JSON. The full - HTML Sitespeed.io report will also be saved as an artifact, and if you have - [GitLab Pages](../../user/project/pages/index.md) enabled, it can be viewed - directly in your browser. +The full HTML Sitespeed.io report will also be saved as an artifact, and if you have +[GitLab Pages](../../user/project/pages/index.md) enabled, it can be viewed +directly in your browser. For further customization options of Sitespeed.io, including the ability to provide a list of URLs to test, please consult @@ -46,8 +55,8 @@ provide a list of URLs to test, please consult TIP: **Tip:** For [GitLab Premium](https://about.gitlab.com/pricing/) users, key metrics are automatically -extracted and shown right in the merge request widget. Learn more about -[Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html). +extracted and shown right in the merge request widget. +[Learn more on Browser Performance Testing in merge requests](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). ## Performance testing on Review Apps @@ -106,8 +115,40 @@ performance: - mv sitespeed-results/data/performance.json performance.json artifacts: paths: - - performance.json - sitespeed-results/ + reports: + performance: performance.json ``` -A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml). +A complete example can be found in our [Auto DevOps CI YML](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml). + +## Previous job definitions + +CAUTION: **Caution:** +Before GitLab 11.5, Performance job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained they have been deprecated +and may be removed in next major release, GitLab 12.0. +You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +performance: + stage: performance + image: docker:git + variables: + URL: https://example.com + services: + - docker:stable-dind + script: + - mkdir gitlab-exporter + - wget -O ./gitlab-exporter/index.js https://gitlab.com/gitlab-org/gl-performance/raw/master/index.js + - mkdir sitespeed-results + - docker run --shm-size=1g --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:6.3.1 --plugins.add ./gitlab-exporter --outputFolder sitespeed-results $URL + - mv sitespeed-results/data/performance.json performance.json + artifacts: + paths: + - performance.json + - sitespeed-results/ +```
\ No newline at end of file diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md index 2a7040ecdeb..ae000b9d30d 100644 --- a/doc/ci/examples/code_quality.md +++ b/doc/ci/examples/code_quality.md @@ -1,11 +1,18 @@ # Analyze your project's Code Quality +CAUTION: **Caution:** +The job definition shown below is supported on GitLab 11.5 and later versions. +It also requires the GitLab Runner 11.5 or later. +For earlier versions, use the [previous job definitions](#previous-job-definitions). + This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. -First, you need GitLab Runner with [docker-in-docker executor][dind]. +First, you need GitLab Runner with +[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). -Once you set up the Runner, add a new job to `.gitlab-ci.yml`, called `code_quality`: +Once you set up the Runner, add a new job to `.gitlab-ci.yml` that +generates the expected report: ```yaml code_quality: @@ -23,27 +30,72 @@ code_quality: --volume /var/run/docker.sock:/var/run/docker.sock "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code artifacts: - paths: [gl-code-quality-report.json] + reports: + codequality: gl-code-quality-report.json ``` The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved -as an artifact that you can later download and analyze. +will scan your source code for code quality issues. The report will be saved as a +[Code Quality report artifact](../../ci/yaml/README.md#artifactsreportscodequality) +that you can later download and analyze. +Due to implementation limitations we always take the latest Code Quality artifact available. TIP: **Tip:** -Starting with [GitLab Starter][ee] 9.3, this information will -be automatically extracted and shown right in the merge request widget. To do -so, the CI/CD job must be named `code_quality` and the artifact path must be -`gl-code-quality-report.json`. +For [GitLab Starter][ee] users, this information will be automatically +extracted and shown right in the merge request widget. [Learn more on Code Quality in merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html). +## Previous job definitions + CAUTION: **Caution:** -Code Quality was previously using `codeclimate` and `codequality` for job name and -`codeclimate.json` for the artifact name. While these old names -are still maintained they have been deprecated with GitLab 11.0 and may be removed -in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` -configuration to reflect that change. +Before GitLab 11.5, Code Quality job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained they have been deprecated +and may be removed in next major release, GitLab 12.0. +You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +code_quality: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') + - docker run + --env SOURCE_CODE="$PWD" + --volume "$PWD":/code + --volume /var/run/docker.sock:/var/run/docker.sock + "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code + artifacts: + paths: [gl-code-quality-report.json] +``` + +Alternatively the job name could be `codeclimate` or `codequality` +and the artifact name could be `codeclimate.json`. +These names have been deprecated with GitLab 11.0 +and may be removed in next major release, GitLab 12.0. + +For GitLab 10.3 and earlier, the job should look like: + +```yaml +codequality: + image: docker:latest + variables: + DOCKER_DRIVER: overlay + services: + - docker:dind + script: + - docker pull codeclimate/codeclimate:0.69.0 + - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 init + - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate:0.69.0 analyze -f json > codeclimate.json || true + artifacts: + paths: [codeclimate.json] +``` [cli]: https://github.com/codeclimate/codeclimate -[dind]: ../docker/using_docker_build.md#use-docker-in-docker-executor [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 0f79f7d1b17..68330261910 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -1,13 +1,20 @@ # Container Scanning with GitLab CI/CD +CAUTION: **Caution:** +The job definition shown below is supported on GitLab 11.5 and later versions. +It also requires the GitLab Runner 11.5 or later. +For earlier versions, use the [previous job definitions](#previous-job-definitions). + You can check your Docker images (or more precisely the containers) for known vulnerabilities by using [Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools for Vulnerability Static Analysis for containers. -All you need is a GitLab Runner with the Docker executor (the shared Runners on -GitLab.com will work fine). You can then add a new job to `.gitlab-ci.yml`, -called `container_scanning`: +First, you need GitLab Runner with +[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). + +Once you set up the Runner, add a new job to `.gitlab-ci.yml` that +generates the expected report: ```yaml container_scanning: @@ -36,31 +43,77 @@ container_scanning: - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true artifacts: - paths: [gl-container-scanning-report.json] + reports: + container_scanning: gl-container-scanning-report.json ``` The above example will create a `container_scanning` job in your CI/CD pipeline, pull the image from the [Container Registry](../../user/project/container_registry.md) (whose name is defined from the two `CI_APPLICATION_` variables) and scan it -for possible vulnerabilities. The report will be saved as an artifact that you -can later download and analyze. +for possible vulnerabilities. The report will be saved as a +[Container Scanning report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportscontainer_scanning) +that you can later download and analyze. +Due to implementation limitations we always take the latest Container Scanning artifact available. If you want to whitelist some specific vulnerabilities, you can do so by defining them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file), in our case its named `clair-whitelist.yml`. TIP: **Tip:** -Starting with [GitLab Ultimate][ee] 10.4, this information will -be automatically extracted and shown right in the merge request widget. To do -so, the CI/CD job must be named `container_scanning` and the artifact path must be -`gl-container-scanning-report.json`. -[Learn more on container scanning results shown in merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/container_scanning.html). +For [GitLab Ultimate][ee] users, this information will +be automatically extracted and shown right in the merge request widget. +[Learn more on Container Scanning in merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/container_scanning.html). + +CAUTION: **Caution:** +Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`. +While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and +may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` +configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable. + +## Previous job definitions CAUTION: **Caution:** -Before GitLab 11.0, Container Scanning was previously using `sast:container` for job name and -`gl-sast-container-report.json` for the artifact name. While these old names -are still maintained, they have been deprecated with GitLab 11.0 and may be removed -in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` -configuration to reflect that change. +Before GitLab 11.5, Container Scanning job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained they have been deprecated +and may be removed in next major release, GitLab 12.0. +You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +container_scanning: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + ## Define two new variables based on GitLab's CI/CD predefined variables + ## https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables + CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG + CI_APPLICATION_TAG: $CI_COMMIT_SHA + allow_failure: true + services: + - docker:stable-dind + script: + - docker run -d --name db arminc/clair-db:latest + - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.1 + - apk add -U wget ca-certificates + - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} + - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 + - mv clair-scanner_linux_amd64 clair-scanner + - chmod +x clair-scanner + - touch clair-whitelist.yml + - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done + - retries=0 + - echo "Waiting for clair daemon to start" + - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done + - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true + artifacts: + paths: [gl-container-scanning-report.json] +``` + +Alternatively the job name could be `sast:container` +and the artifact name could be `gl-sast-container-report.json`. +These names have been deprecated with GitLab 11.0 +and may be removed in next major release, GitLab 12.0. [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md index ff20f0b3b5e..0ca89eb6700 100644 --- a/doc/ci/examples/dast.md +++ b/doc/ci/examples/dast.md @@ -1,16 +1,26 @@ # Dynamic Application Security Testing with GitLab CI/CD +CAUTION: **Caution:** +The job definition shown below is supported on GitLab 11.5 and later versions. +It also requires the GitLab Runner 11.5 or later. +For earlier versions, use the [previous job definitions](#previous-job-definitions). + [Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_program_analysis) is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to perform an analysis on your running web application. +Since it is based on [ZAP Baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) +DAST will perform passive scanning only; +it will not actively attack your application. It can be very useful combined with [Review Apps](../review_apps/index.md). ## Example -All you need is a GitLab Runner with the Docker executor (the shared Runners on -GitLab.com will work fine). You can then add a new job to `.gitlab-ci.yml`, -called `dast`: +First, you need GitLab Runner with +[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). + +Once you set up the Runner, add a new job to `.gitlab-ci.yml` that +generates the expected report: ```yaml dast: @@ -23,13 +33,16 @@ dast: - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true - cp /zap/wrk/gl-dast-report.json . artifacts: - paths: [gl-dast-report.json] + reports: + dast: gl-dast-report.json ``` The above example will create a `dast` job in your CI/CD pipeline which will run the tests on the URL defined in the `website` variable (change it to use your -own) and finally write the results in the `gl-dast-report.json` file. You can -then download and analyze the report artifact in JSON format. +own) and scan it for possible vulnerabilities. The report will be saved as a +[DAST report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportsdast) +that you can later download and analyze. +Due to implementation limitations we always take the latest DAST artifact available. It's also possible to authenticate the user before performing DAST checks: @@ -39,25 +52,51 @@ dast: variables: website: "https://example.com" login_url: "https://example.com/sign-in" + username: "john.doe@example.com" + password: "john-doe-password" allow_failure: true script: - mkdir /zap/wrk/ - /zap/zap-baseline.py -J gl-dast-report.json -t $website --auth-url $login_url - --auth-username "john.doe@example.com" - --auth-password "john-doe-password" || true + --auth-username $username + --auth-password $password || true - cp /zap/wrk/gl-dast-report.json . artifacts: - paths: [gl-dast-report.json] + reports: + dast: gl-dast-report.json ``` See [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy) to learn more about authentication settings. TIP: **Tip:** -Starting with [GitLab Ultimate][ee] 10.4, this information will -be automatically extracted and shown right in the merge request widget. To do -so, the CI job must be named `dast` and the artifact path must be -`gl-dast-report.json`. -[Learn more about DAST results shown in merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/dast.html). +For [GitLab Ultimate][ee] users, this information will +be automatically extracted and shown right in the merge request widget. +[Learn more on DAST in merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/dast.html). + +## Previous job definitions + +CAUTION: **Caution:** +Before GitLab 11.5, DAST job and artifact had to be named specifically +to automatically extract report data and show it in the merge request widget. +While these old job definitions are still maintained they have been deprecated +and may be removed in next major release, GitLab 12.0. +You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. + +For GitLab 11.4 and earlier, the job should look like: + +```yaml +dast: + image: registry.gitlab.com/gitlab-org/security-products/zaproxy + variables: + website: "https://example.com" + allow_failure: true + script: + - mkdir /zap/wrk/ + - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true + - cp /zap/wrk/gl-dast-report.json . + artifacts: + paths: [gl-dast-report.json] +``` [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_secret_variables.png b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_secret_variables.png Binary files differdeleted file mode 100644 index 5b5d91ec07a..00000000000 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_secret_variables.png +++ /dev/null diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png Binary files differnew file mode 100644 index 00000000000..28323e2d8de --- /dev/null +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/img/cloud_foundry_variables.png diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md index b88761be56b..40ceef3d554 100644 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md @@ -64,7 +64,7 @@ applications: ## Configure GitLab CI/CD to deploy your application -Now we need to add the the GitLab CI/CD configuration file +Now we need to add the GitLab CI/CD configuration file ([`.gitlab-ci.yml`](../../yaml/README.md)) to our project's root. This is how GitLab figures out what commands need to be run whenever code is pushed to our repository. We will add the following `.gitlab-ci.yml` @@ -106,10 +106,10 @@ Now, since the steps defined in `.gitlab-ci.yml` require credentials to login to CF, you'll need to add your CF credentials as [environment variables](../../variables/README.md#predefined-variables-environment-variables) on GitLab CI/CD. To set the environment variables, navigate to your project's -**Settings > CI/CD** and expand **Secret Variables**. Name the variables +**Settings > CI/CD** and expand **Variables**. Name the variables `CF_USERNAME` and `CF_PASSWORD` and set them to the correct values. - + Once set up, GitLab CI/CD will deploy your app to CF at every push to your repository's deafult branch. To see the build logs or watch your builds running diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index bd60d641493..46effb76d71 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -5,7 +5,7 @@ continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. >**Note:** -We recommend to use Dpl if you're deploying to any of these of these services: +We recommend to use Dpl if you're deploying to any of these services: https://github.com/travis-ci/dpl#supported-providers. ## Requirements @@ -101,12 +101,12 @@ production: We created two deploy jobs that are executed on different events: 1. `staging` is executed for all commits that were pushed to `master` branch, -2. `production` is executed for all pushed tags. +1. `production` is executed for all pushed tags. We also use two secure variables: 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app, -2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. +1. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. ## Storing API keys @@ -120,7 +120,7 @@ is hidden in the job log. You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners): -1. `$SECRET_VARIABLE` - use it for non-Windows runners -2. `%SECRET_VARIABLE%` - use it for Windows Batch runners +1. `$VARIABLE` - use it for non-Windows runners +1. `%VARIABLE%` - use it for Windows Batch runners Read more about the [CI variables](../../variables/README.md). diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index bed379b0254..36358515b84 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -33,9 +33,9 @@ before_script: In this particular case, the `npm deploy` script is a Gulp script that does the following: 1. Compile CSS & JS -2. Create sprites -3. Copy various assets (images, fonts) around -4. Replace some strings +1. Create sprites +1. Copy various assets (images, fonts) around +1. Replace some strings All these operations will put all files into a `build` folder, which is ready to be deployed to a live server. @@ -43,7 +43,7 @@ All these operations will put all files into a `build` folder, which is ready to You have multiple options: rsync, scp, sftp and so on. For now, we will use scp. -To make this work, you need to add a GitLab Secret Variable (accessible on _gitlab.example/your-project-name/variables_). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** ssh key of your server. +To make this work, you need to add a GitLab CI/CD Variable (accessible on _gitlab.example/your-project-name/variables_). That variable will be called `STAGING_PRIVATE_KEY` and it's the **private** ssh key of your server. ### Security tip @@ -62,10 +62,10 @@ before_script: In order, this means that: -1. We check if the `ssh-agent` is available and we install it if it's not; -2. We create the `~/.ssh` folder; -3. We make sure we're running bash; -4. We disable host checking (we don't ask for user accept when we first connect to a server; and since every job will equal a first connect, we kind of need this) +1. We check if the `ssh-agent` is available and we install it if it's not. +1. We create the `~/.ssh` folder. +1. We make sure we're running bash. +1. We disable host checking (we don't ask for user accept when we first connect to a server and since every job will equal a first connect, we kind of need this). And this is basically all you need in the `before_script` section. @@ -91,11 +91,11 @@ stage_deploy: Here's the breakdown: 1. `only:dev` means that this build will run only when something is pushed to the `dev` branch. You can remove this block completely and have everything be ran on every push (but probably this is something you don't want) -2. `ssh-add ...` we will add that private key you added on the web UI to the docker container -3. We will connect via `ssh` and create a new `_tmp` folder -4. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder -5. We will connect again to `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`. -6. We connect to ssh and remove the `_old` folder +1. `ssh-add ...` we will add that private key you added on the web UI to the docker container +1. We will connect via `ssh` and create a new `_tmp` folder +1. We will connect via `scp` and upload the `build` folder (which was generated by a `npm` script) to our previously created `_tmp` folder +1. We will connect again to `ssh` and move the `live` folder to an `_old` folder, then move `_tmp` to `live`. +1. We connect to ssh and remove the `_old` folder What's the deal with the artifacts? We just tell GitLab CI to keep the `build` directory (later on, you can download that as needed). diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index c226b5bfb71..cae051daa56 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -418,7 +418,7 @@ fully understand [IAM Best Practices in AWS](http://docs.aws.amazon.com/IAM/late 1. Click the **Access Keys** section and **Create New Access Key**. Create the key and keep the id and secret around, you'll need them later  1. Go to your GitLab project, click **Settings > CI/CD** on the left sidebar -1. Expand the **Secret Variables** section +1. Expand the **Variables** section  1. Add a key named `AWS_KEY_ID` and copy the key id from Step 2 into the **Value** textbox 1. Add a key named `AWS_KEY_SECRET` and copy the key secret from Step 2 into the **Value** textbox @@ -520,7 +520,7 @@ a lot of breathing room in quickly getting changes to players. Here are some ideas to further investigate that can speed up or improve your pipeline: - [Yarn](https://yarnpkg.com) instead of npm -- Setup a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ci-yml) image that can preload dependencies and tools (like AWS CLI) +- Set up a custom [Docker](../../../ci/docker/using_docker_images.md#define-image-and-services-from-gitlab-ci-yml) image that can preload dependencies and tools (like AWS CLI) - Forward a [custom domain](http://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) to your game's S3 static website - Combine jobs if you find it unnecessary for a small project - Avoid the queues and set up your own [custom GitLab CI/CD runner](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/img/container_registry_checkbox.png b/doc/ci/examples/laravel_with_gitlab_and_envoy/img/container_registry_checkbox.png Binary files differdeleted file mode 100644 index a56c07a0da7..00000000000 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/img/container_registry_checkbox.png +++ /dev/null diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/img/secret_variables_page.png b/doc/ci/examples/laravel_with_gitlab_and_envoy/img/secret_variables_page.png Binary files differdeleted file mode 100644 index b7906d49dcb..00000000000 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/img/secret_variables_page.png +++ /dev/null diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/img/variables_page.png b/doc/ci/examples/laravel_with_gitlab_and_envoy/img/variables_page.png Binary files differnew file mode 100644 index 00000000000..80d8eb0f4fc --- /dev/null +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/img/variables_page.png diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 39c65399332..b1ccce744d8 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -13,7 +13,7 @@ date: 2017-08-31 GitLab features our applications with Continuous Integration, and it is possible to easily deploy the new code changes to the production server whenever we want. -In this tutorial, we'll show you how to initialize a [Laravel](http://laravel.com/) application and setup our [Envoy](https://laravel.com/docs/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). +In this tutorial, we'll show you how to initialize a [Laravel](http://laravel.com/) application and set up our [Envoy](https://laravel.com/docs/envoy) tasks, then we'll jump into see how to test and deploy it with [GitLab CI/CD](../README.md) via [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). We assume you have a basic experience with Laravel, Linux servers, and you know how to use GitLab. @@ -23,7 +23,7 @@ It has a great community with a [fantastic documentation](https://laravel.com/do Aside from the usual routing, controllers, requests, responses, views, and (blade) templates, out of the box Laravel provides plenty of additional services such as cache, events, localization, authentication and many others. We will use [Envoy](https://laravel.com/docs/master/envoy) as an SSH task runner based on PHP. -It uses a clean, minimal [Blade syntax](https://laravel.com/docs/blade) to setup tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/artisan). +It uses a clean, minimal [Blade syntax](https://laravel.com/docs/blade) to set up tasks that can run on remote servers, such as, cloning your project from the repository, installing the Composer dependencies, and running [Artisan commands](https://laravel.com/docs/artisan). ## Initialize our Laravel app on GitLab @@ -120,12 +120,12 @@ Now, let's add it to your GitLab project as a [variable](../../variables/README. Variables are user-defined variables and are stored out of `.gitlab-ci.yml`, for security purposes. They can be added per project by navigating to the project's **Settings** > **CI/CD**. - - To the field **KEY**, add the name `SSH_PRIVATE_KEY`, and to the **VALUE** field, paste the private key you've copied earlier. We'll use this variable in the `.gitlab-ci.yml` later, to easily connect to our remote server as the deployer user without entering its password. -We also need to add the public key to **Project** > **Settings** > **Repository** as [Deploy Keys](../../../ssh/README.md/#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md/#start-working-on-your-project). + + +We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../ssh/README.md#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). ```bash @@ -135,10 +135,10 @@ We also need to add the public key to **Project** > **Settings** > **Repository* cat ~/.ssh/id_rsa.pub ``` - - To the field **Title**, add any name you want, and paste the public key into the **Key** field. + + Now, let's clone our repository on the server just to make sure the `deployer` user has access to the repository. ```bash @@ -273,6 +273,8 @@ The `releases` directory will hold all our deployments: echo 'Cloning repository' [ -d {{ $releases_dir }} ] || mkdir {{ $releases_dir }} git clone --depth 1 {{ $repository }} {{ $new_release_dir }} + cd {{ $releases_dir }} + git reset --hard {{ $commit }} @endtask ... @@ -349,6 +351,8 @@ At the end, our `Envoy.blade.php` file will look like this: echo 'Cloning repository' [ -d {{ $releases_dir }} ] || mkdir {{ $releases_dir }} git clone --depth 1 {{ $repository }} {{ $new_release_dir }} + cd {{ $releases_dir }} + git reset --hard {{ $commit }} @endtask @task('run_composer') @@ -372,13 +376,13 @@ At the end, our `Envoy.blade.php` file will look like this: One more thing we should do before any deployment is to manually copy our application `storage` folder to the `/var/www/app` directory on the server for the first time. You might want to create another Envoy task to do that for you. -We also create the `.env` file in the same path to setup our production environment variables for Laravel. +We also create the `.env` file in the same path to set up our production environment variables for Laravel. These are persistent data and will be shared to every new release. Now, we would need to deploy our app by running `envoy run deploy`, but it won't be necessary since GitLab can handle that for us with CI's [environments](../../environments.md), which will be described [later](#setting-up-gitlab-ci-cd) in this tutorial. Now it's time to commit [Envoy.blade.php](https://gitlab.com/mehranrasulian/laravel-sample/blob/master/Envoy.blade.php) and push it to the `master` branch. -To keep things simple, we commit directly to `master`, without using [feature-branches](../../../workflow/gitlab_flow.md/#github-flow-as-a-simpler-alternative) since collaboration is beyond the scope of this tutorial. +To keep things simple, we commit directly to `master`, without using [feature-branches](../../../workflow/gitlab_flow.md#github-flow-as-a-simpler-alternative) since collaboration is beyond the scope of this tutorial. In a real world project, teams may use [Issue Tracker](../../../user/project/issues/index.md) and [Merge Requests](../../../user/project/merge_requests/index.md) to move their code across branches: ```bash @@ -398,7 +402,7 @@ In the case you're not familiar with Docker, refer to [How to Automate Docker De To be able to build, test, and deploy our app with GitLab CI/CD, we need to prepare our work environment. To do that, we'll use a Docker image which has the minimum requirements that a Laravel app needs to run. -[There are other ways](../php.md/#test-php-projects-using-the-docker-executor) to do that as well, but they may lead our builds run slowly, which is not what we want when there are faster options to use. +[There are other ways](../php.md#test-php-projects-using-the-docker-executor) to do that as well, but they may lead our builds run slowly, which is not what we want when there are faster options to use. With Docker images our builds run incredibly faster! @@ -444,9 +448,7 @@ On your GitLab project repository navigate to the **Registry** tab.  -You may need to [enable Container Registry](../../../user/project/container_registry.md#enable-the-container-registry-for-your-project) to your project to see this tab. You'll find it under your project's **Settings > General > Sharing and permissions**. - - +You may need to [enable Container Registry](../../../user/project/container_registry.md#enable-the-container-registry-for-your-project) to your project to see this tab. You'll find it under your project's **Settings > General > Permissions**. To start using Container Registry on our machine, we first need to login to the GitLab registry using our GitLab username and password: @@ -521,7 +523,7 @@ deploy_production: - mkdir -p ~/.ssh - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config' - - ~/.composer/vendor/bin/envoy run deploy + - ~/.composer/vendor/bin/envoy run deploy --commit="$CI_COMMIT_SHA" environment: name: production url: http://192.168.1.1 @@ -536,7 +538,7 @@ That's a lot to take in, isn't it? Let's run through it step by step. [GitLab Runners](../../runners/README.md) run the script defined by `.gitlab-ci.yml`. The `image` keyword tells the Runners which image to use. -The `services` keyword defines additional images [that are linked to the main image](../../docker/using_docker_images.md/#what-is-a-service). +The `services` keyword defines additional images [that are linked to the main image](../../docker/using_docker_images.md#what-is-a-service). Here we use the container image we created before as our main image and also use MySQL 5.7 as a service. ```yaml @@ -560,7 +562,7 @@ So we should adjust the configuration of MySQL instance by defining `MYSQL_DATAB Find out more about MySQL variables at the [official MySQL Docker Image](https://hub.docker.com/r/_/mysql/). Also set the variables `DB_HOST` to `mysql` and `DB_USERNAME` to `root`, which are Laravel specific variables. -We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md/#how-services-are-linked-to-the-build). +We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md#how-services-are-linked-to-the-build). ```yaml ... @@ -587,7 +589,7 @@ unit_test: script: # Install app dependencies - composer install - # Setup .env + # Set up .env - cp .env.example .env # Generate an environment key - php artisan key:generate @@ -602,7 +604,7 @@ unit_test: #### Deploy to production The job `deploy_production` will deploy the app to the production server. -To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md/#ssh-keys-when-using-the-docker-executor). +To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md#ssh-keys-when-using-the-docker-executor). If the SSH keys have added successfully, we can run Envoy. As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well. diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index a2ba29a4ee2..c1048f3d2e3 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -20,7 +20,7 @@ build environment. Let's first specify the PHP image that will be used for the job process (you can read more about what an image means in the Runner's lingo reading -about [Using Docker images](../docker/using_docker_images.md#what-is-image)). +about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). Start by adding the image to your `.gitlab-ci.yml`: @@ -199,7 +199,7 @@ pecl install <extension> ``` It's not advised to add this to `.gitlab-ci.yml`. You should execute this -command once, only to setup the build environment. +command once, only to set up the build environment. ## Extend your tests diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index 087b317ab73..ec0b5aaed09 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -40,15 +40,17 @@ production: ``` This project has three jobs: -1. `test` - used to test Django application, -2. `staging` - used to automatically deploy staging environment every push to `master` branch -3. `production` - used to automatically deploy production environment for every created tag + +- `test` - used to test Django application, +- `staging` - used to automatically deploy staging environment every push to `master` branch +- `production` - used to automatically deploy production environment for every created tag ## Store API keys You'll need to create two variables in `Settings > CI/CD > Variables` on your GitLab project settings: -1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app, -2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. + +- `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app. +- `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account). diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 7f9ab1f3a5e..33a353f17f5 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -36,16 +36,17 @@ production: ``` This project has three jobs: -1. `test` - used to test Rails application, -2. `staging` - used to automatically deploy staging environment every push to `master` branch -3. `production` - used to automatically deploy production environment for every created tag + +- `test` - used to test Rails application. +- `staging` - used to automatically deploy staging environment every push to `master` branch. +- `production` - used to automatically deploy production environment for every created tag. ## Store API keys You'll need to create two variables in your project's **Settings > CI/CD > Variables**: -1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app, -2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. +- `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app. +- `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app. Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account). diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 09d83c33f95..66bfa41cad9 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -1,6 +1,6 @@ # Test and deploy to Heroku a Scala application -This example demonstrates the integration of Gitlab CI with Scala +This example demonstrates the integration of GitLab CI with Scala applications using SBT. Checkout the example [project](https://gitlab.com/gitlab-examples/scala-sbt) and [build status](https://gitlab.com/gitlab-examples/scala-sbt/builds). @@ -25,7 +25,7 @@ before_script: - apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 642AC823 - apt-get update -y - apt-get install sbt -y - - sbt sbt-version + - sbt sbtVersion test: stage: test diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index b2c73caae2e..c0346d78141 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -398,10 +398,10 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams - [Using Docker images documentation][using-docker] - [Example project: Hello GitLab CI/CD on GitLab][hello-gitlab] -[phoenix-site]: http://phoenixframework.org/ "Phoenix Framework" +[phoenix-site]: https://phoenixframework.org/ "Phoenix Framework" [phoenix-learning-guide]: https://hexdocs.pm/phoenix/learning.html "Phoenix Learning Guide" -[phoenix-install]: http://www.phoenixframework.org/docs/installation "Phoenix Installation" -[phoenix-mysql]: http://www.phoenixframework.org/docs/using-mysql "Phoenix with MySQL" +[phoenix-install]: https://hexdocs.pm/phoenix/installation.html "Phoenix Installation" +[phoenix-mysql]: https://hexdocs.pm/phoenix/ecto.html#using-mysql "Phoenix with MySQL" [elixir-site]: http://elixir-lang.org/ "Elixir" [elixir-mix]: http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix" [elixir-docs]: http://elixir-lang.org/getting-started/introduction.html "Elixir Documentation" diff --git a/doc/ci/img/pipeline_incremental_rollout.png b/doc/ci/img/pipeline_incremental_rollout.png Binary files differnew file mode 100644 index 00000000000..b3498e9a5a5 --- /dev/null +++ b/doc/ci/img/pipeline_incremental_rollout.png diff --git a/doc/ci/img/pipelines-goal.png b/doc/ci/img/pipelines-goal.png Binary files differnew file mode 100644 index 00000000000..a96368e562b --- /dev/null +++ b/doc/ci/img/pipelines-goal.png diff --git a/doc/ci/img/pipelines-goal.svg b/doc/ci/img/pipelines-goal.svg deleted file mode 100644 index a925e2282a4..00000000000 --- a/doc/ci/img/pipelines-goal.svg +++ /dev/null @@ -1,4 +0,0 @@ -<?xml version="1.0" standalone="yes"?> - -<svg version="1.1" viewBox="0.0 0.0 1091.020997375328 262.04461942257217" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><clipPath id="p.0"><path d="m0 0l1091.021 0l0 262.04462l-1091.021 0l0 -262.04462z" clip-rule="nonzero"></path></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l1091.021 0l0 262.04462l-1091.021 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m226.93439 3.7664042l860.7559 0l0 249.5748l-860.7559 0z" fill-rule="nonzero"></path><path stroke="#666666" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m226.93439 3.7664042l860.7559 0l0 249.5748l-860.7559 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m67.72179 27.199474l147.2126 0l0 39.464565l-147.2126 0z" fill-rule="nonzero"></path><path fill="#000000" d="m126.91313 49.353848l1.796875 0.453125q-0.5625 2.21875 -2.03125 3.390625q-1.46875 1.15625 -3.59375 1.15625q-2.203125 0 -3.578125 -0.890625q-1.375 -0.90625 -2.09375 -2.59375q-0.71875 -1.703125 -0.71875 -3.65625q0 -2.125 0.796875 -3.703125q0.8125 -1.578125 2.3125 -2.390625q1.5 -0.828125 3.296875 -0.828125q2.046875 0 3.4375 1.046875q1.390625 1.03125 1.9375 2.90625l-1.765625 0.421875q-0.46875 -1.484375 -1.375 -2.15625q-0.90625 -0.6875 -2.265625 -0.6875q-1.5625 0 -2.625 0.75q-1.046875 0.75 -1.484375 2.03125q-0.421875 1.265625 -0.421875 2.609375q0 1.734375 0.5 3.03125q0.515625 1.28125 1.578125 1.921875q1.078125 0.640625 2.3125 0.640625q1.515625 0 2.5625 -0.859375q1.046875 -0.875 1.421875 -2.59375zm3.5354462 4.765625l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.978302 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm15.547592 4.65625q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.735092 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277054 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm14.449646 5.875l0 -13.59375l2.71875 0l3.21875 9.625q0.4375 1.34375 0.640625 2.015625q0.234375 -0.75 0.734375 -2.1875l3.25 -9.453125l2.421875 0l0 13.59375l-1.734375 0l0 -11.390625l-3.953125 11.390625l-1.625 0l-3.9375 -11.578125l0 11.578125l-1.734375 0zm15.634552 0l0 -13.59375l6.03125 0q1.8125 0 2.75 0.359375q0.953125 0.359375 1.515625 1.296875q0.5625 0.921875 0.5625 2.046875q0 1.453125 -0.9375 2.453125q-0.921875 0.984375 -2.890625 1.25q0.71875 0.34375 1.09375 0.671875q0.78125 0.734375 1.484375 1.8125l2.375 3.703125l-2.265625 0l-1.796875 -2.828125q-0.796875 -1.21875 -1.3125 -1.875q-0.5 -0.65625 -0.90625 -0.90625q-0.40625 -0.265625 -0.8125 -0.359375q-0.3125 -0.078125 -1.015625 -0.078125l-2.078125 0l0 6.046875l-1.796875 0zm1.796875 -7.59375l3.859375 0q1.234375 0 1.921875 -0.25q0.703125 -0.265625 1.0625 -0.828125q0.375 -0.5625 0.375 -1.21875q0 -0.96875 -0.703125 -1.578125q-0.703125 -0.625 -2.21875 -0.625l-4.296875 0l0 4.5z" fill-rule="nonzero"></path><path fill="#efefef" d="m765.3307 106.94125l147.21265 0l0 59.74803l-147.21265 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m765.3307 106.94125l147.21265 0l0 59.74803l-147.21265 0z" fill-rule="nonzero"></path><path fill="#000000" d="m800.99805 132.73526l0 -13.593742l4.6875 0q1.578125 0 2.421875 0.1875q1.15625 0.265625 1.984375 0.96875q1.078125 0.921875 1.609375 2.34375q0.53125 1.40625 0.53125 3.21875q0 1.546875 -0.359375 2.7499924q-0.359375 1.1875 -0.921875 1.984375q-0.5625 0.78125 -1.234375 1.234375q-0.671875 0.4375 -1.625 0.671875q-0.953125 0.234375 -2.1875 0.234375l-4.90625 0zm1.796875 -1.609375l2.90625 0q1.34375 0 2.109375 -0.25q0.765625 -0.25 1.21875 -0.703125q0.640625 -0.640625 1.0 -1.71875q0.359375 -1.0781174 0.359375 -2.6249924q0 -2.125 -0.703125 -3.265625q-0.703125 -1.15625 -1.703125 -1.546875q-0.71875 -0.28125 -2.328125 -0.28125l-2.859375 0l0 10.390617zm18.207336 -1.5625l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.7343674q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.43749237l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.7031174l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.110107 9.656242l0 -13.640617l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.5156174 -0.546875 2.7343674q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.656242q0 1.9062424 0.765625 2.8124924q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.9218674q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm8.828857 4.8749924l0 -13.593742l1.671875 0l0 13.593742l-1.671875 0zm3.5510254 -4.9218674q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.9062424 -0.578125 2.9999924q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8124924zm1.71875 0q0 1.8906174 0.828125 2.8281174q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.8906174q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.203857 8.718742l-0.171875 -1.5625q0.546875 0.140625 0.953125 0.140625q0.546875 0 0.875 -0.1875q0.34375 -0.1875 0.5625 -0.515625q0.15625 -0.25 0.5 -1.25q0.046875 -0.140625 0.15625 -0.40625l-3.734375 -9.874992l1.796875 0l2.046875 5.7187424q0.40625 1.078125 0.71875 2.28125q0.28125 -1.15625 0.6875 -2.25l2.09375 -5.7499924l1.671875 0l-3.75 10.031242q-0.59375 1.625 -0.9375 2.234375q-0.4375 0.828125 -1.015625 1.203125q-0.578125 0.390625 -1.375 0.390625q-0.484375 0 -1.078125 -0.203125zm18.245789 -5.296875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.6562424l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.7499924q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.9020996 -3.4218674q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.9062424 -0.578125 2.9999924q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8124924zm1.71875 0q0 1.8906174 0.828125 2.8281174q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.8906174q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125z" fill-rule="nonzero"></path><path fill="#000000" d="m808.1591 150.36026l1.6875 -0.140625q0.125 1.015625 0.5625 1.671875q0.4375 0.65625 1.359375 1.0625q0.9375 0.40625 2.09375 0.40625q1.03125 0 1.8125 -0.3125q0.796875 -0.3125 1.1875 -0.84375q0.390625 -0.53125 0.390625 -1.15625q0 -0.640625 -0.375 -1.109375q-0.375 -0.484375 -1.234375 -0.8125q-0.546875 -0.21875 -2.421875 -0.65625q-1.875 -0.453125 -2.625 -0.859375q-0.96875 -0.515625 -1.453125 -1.265625q-0.46875 -0.75 -0.46875 -1.6875q0 -1.03125 0.578125 -1.921875q0.59375 -0.90625 1.703125 -1.359375q1.125 -0.46875 2.5 -0.46875q1.515625 0 2.671875 0.484375q1.15625 0.484375 1.765625 1.4375q0.625 0.9375 0.671875 2.140625l-1.71875 0.125q-0.140625 -1.28125 -0.953125 -1.9375q-0.796875 -0.671875 -2.359375 -0.671875q-1.625 0 -2.375 0.609375q-0.75 0.59375 -0.75 1.4375q0 0.734375 0.53125 1.203125q0.515625 0.46875 2.703125 0.96875q2.203125 0.5 3.015625 0.875q1.1875 0.546875 1.75 1.390625q0.578125 0.828125 0.578125 1.921875q0 1.09375 -0.625 2.0625q-0.625 0.953125 -1.796875 1.484375q-1.15625 0.53125 -2.609375 0.53125q-1.84375 0 -3.09375 -0.53125q-1.25 -0.546875 -1.96875 -1.625q-0.703125 -1.078125 -0.734375 -2.453125zm16.490417 2.875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm7.9645386 0.28125q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm3.7819824 5.75l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.313232 -6.578125l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm10.078796 0.8125l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875z" fill-rule="nonzero"></path><path fill="#efefef" d="m925.54333 177.39108l147.21252 0l0 59.74803l-147.21252 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m925.54333 177.39108l147.21252 0l0 59.74803l-147.21252 0z" fill-rule="nonzero"></path><path fill="#000000" d="m961.2107 203.18509l0 -13.59375l4.6875 0q1.578125 0 2.421875 0.1875q1.15625 0.265625 1.984375 0.96875q1.078125 0.921875 1.609375 2.34375q0.53125 1.40625 0.53125 3.21875q0 1.546875 -0.359375 2.75q-0.359375 1.1875 -0.921875 1.984375q-0.5625 0.78125 -1.234375 1.234375q-0.671875 0.4375 -1.625 0.671875q-0.953125 0.234375 -2.1875 0.234375l-4.90625 0zm1.796875 -1.609375l2.90625 0q1.34375 0 2.109375 -0.25q0.765625 -0.25 1.21875 -0.703125q0.640625 -0.640625 1.0 -1.71875q0.359375 -1.078125 0.359375 -2.625q0 -2.125 -0.703125 -3.265625q-0.703125 -1.15625 -1.703125 -1.546875q-0.71875 -0.28125 -2.328125 -0.28125l-2.859375 0l0 10.390625zm18.207275 -1.5625l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.110107 9.65625l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm8.828857 4.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm3.5510864 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.203796 8.71875l-0.171875 -1.5625q0.546875 0.140625 0.953125 0.140625q0.546875 0 0.875 -0.1875q0.34375 -0.1875 0.5625 -0.515625q0.15625 -0.25 0.5 -1.25q0.046875 -0.140625 0.15625 -0.40625l-3.734375 -9.875l1.796875 0l2.046875 5.71875q0.40625 1.078125 0.71875 2.28125q0.28125 -1.15625 0.6875 -2.25l2.09375 -5.75l1.671875 0l-3.75 10.03125q-0.59375 1.625 -0.9375 2.234375q-0.4375 0.828125 -1.015625 1.203125q-0.578125 0.390625 -1.375 0.390625q-0.484375 0 -1.078125 -0.203125zm18.24585 -5.296875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.90197754 -3.421875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125z" fill-rule="nonzero"></path><path fill="#000000" d="m956.0228 225.18509l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.4122925 7.140625l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.6033325 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672607 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm15.719421 4.921875l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm10.360107 -3.609375l1.640625 0.21875q-0.265625 1.6875 -1.375 2.65625q-1.109375 0.953125 -2.734375 0.953125q-2.015625 0 -3.25 -1.3125q-1.21875 -1.328125 -1.21875 -3.796875q0 -1.59375 0.515625 -2.78125q0.53125 -1.203125 1.609375 -1.796875q1.09375 -0.609375 2.359375 -0.609375q1.609375 0 2.625 0.8125q1.015625 0.8125 1.3125 2.3125l-1.625 0.25q-0.234375 -1.0 -0.828125 -1.5q-0.59375 -0.5 -1.421875 -0.5q-1.265625 0 -2.0625 0.90625q-0.78125 0.90625 -0.78125 2.859375q0 1.984375 0.765625 2.890625q0.765625 0.890625 1.984375 0.890625q0.984375 0 1.640625 -0.59375q0.65625 -0.609375 0.84375 -1.859375zm6.546875 2.109375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.531311 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.281311 -1.328125 -1.281311 -3.8125zm1.718811 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.28186 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m57.989502 117.082985l156.94489 0l0 39.46456l-156.94489 0z" fill-rule="nonzero"></path><path fill="#000000" d="m71.518036 144.00298l0 -13.59375l2.71875 0l3.21875 9.625q0.4375 1.34375 0.640625 2.015625q0.234375 -0.75 0.734375 -2.1875l3.25 -9.453125l2.421875 0l0 13.59375l-1.734375 0l0 -11.390625l-3.953125 11.390625l-1.625 0l-3.9375 -11.578125l0 11.578125l-1.734375 0zm22.134552 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.094467 5.875l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.931427 0.8125l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm16.047592 1.9375l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm17.949646 4.375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.90205383 -3.421875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm14.621521 4.921875l0 -13.59375l2.71875 0l3.21875 9.625q0.4375 1.34375 0.640625 2.015625q0.234375 -0.75 0.734375 -2.1875l3.25 -9.453125l2.421875 0l0 13.59375l-1.734375 0l0 -11.390625l-3.953125 11.390625l-1.625 0l-3.9375 -11.578125l0 11.578125l-1.734375 0zm21.822052 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm3.4069672 2.0l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277054 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.094467 5.875l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m5.0104985 187.5328l209.95276 0l0 39.46457l-209.95276 0z" fill-rule="nonzero"></path><path fill="#000000" d="m34.188858 214.4528l0 -13.59375l2.71875 0l3.21875 9.625q0.4375 1.34375 0.640625 2.015625q0.234375 -0.75 0.734375 -2.1875l3.25 -9.453125l2.421875 0l0 13.59375l-1.734375 0l0 -11.390625l-3.953125 11.390625l-1.625 0l-3.9375 -11.578125l0 11.578125l-1.734375 0zm22.134552 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.094467 5.875l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.931427 0.8125l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm16.047592 1.9375l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm17.949646 4.375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.90205383 -3.421875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm14.684021 4.921875l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.412323 7.140625l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.603302 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672592 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm15.719467 4.921875l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm10.360092 -3.609375l1.640625 0.21875q-0.265625 1.6875 -1.375 2.65625q-1.109375 0.953125 -2.734375 0.953125q-2.015625 0 -3.25 -1.3125q-1.21875 -1.328125 -1.21875 -3.796875q0 -1.59375 0.515625 -2.78125q0.53125 -1.203125 1.609375 -1.796875q1.09375 -0.609375 2.359375 -0.609375q1.609375 0 2.625 0.8125q1.015625 0.8125 1.3125 2.3125l-1.625 0.25q-0.234375 -1.0 -0.828125 -1.5q-0.59375 -0.5 -1.421875 -0.5q-1.265625 0 -2.0625 0.90625q-0.78125 0.90625 -0.78125 2.859375q0 1.984375 0.765625 2.890625q0.765625 0.890625 1.984375 0.890625q0.984375 0 1.640625 -0.59375q0.65625 -0.609375 0.84375 -1.859375zm6.546875 2.109375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426788 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5041962 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281967 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm10.813217 0l0 -1.90625l1.90625 0l0 1.90625q0 1.046875 -0.375 1.6875q-0.375 0.65625 -1.171875 1.0l-0.46875 -0.71875q0.53125 -0.21875 0.78125 -0.671875q0.25 -0.453125 0.28125 -1.296875l-0.953125 0z" fill-rule="nonzero"></path><path fill="#000000" d="m51.19565 236.4528l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.161606 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm3.7819672 5.75l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm14.887146 5.109375l0 -8.546875l-1.484375 0l0 -1.3125l1.484375 0l0 -1.046875q0 -0.984375 0.171875 -1.46875q0.234375 -0.65625 0.84375 -1.046875q0.609375 -0.40625 1.703125 -0.40625q0.703125 0 1.5625 0.15625l-0.25 1.46875q-0.515625 -0.09375 -0.984375 -0.09375q-0.765625 0 -1.078125 0.328125q-0.3125 0.3125 -0.3125 1.203125l0 0.90625l1.921875 0l0 1.3125l-1.921875 0l0 8.546875l-1.65625 0zm4.152054 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.266342 4.921875l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm11.661606 0l0 -13.59375l6.03125 0q1.8125 0 2.75 0.359375q0.953125 0.359375 1.515625 1.296875q0.5625 0.921875 0.5625 2.046875q0 1.453125 -0.9375 2.453125q-0.921875 0.984375 -2.890625 1.25q0.71875 0.34375 1.09375 0.671875q0.78125 0.734375 1.484375 1.8125l2.375 3.703125l-2.265625 0l-1.796875 -2.828125q-0.796875 -1.21875 -1.3125 -1.875q-0.5 -0.65625 -0.90625 -0.90625q-0.40625 -0.265625 -0.8125 -0.359375q-0.3125 -0.078125 -1.015625 -0.078125l-2.078125 0l0 6.046875l-1.796875 0zm1.796875 -7.59375l3.859375 0q1.234375 0 1.921875 -0.25q0.703125 -0.265625 1.0625 -0.828125q0.375 -0.5625 0.375 -1.21875q0 -0.96875 -0.703125 -1.578125q-0.703125 -0.625 -2.21875 -0.625l-4.296875 0l0 4.5zm18.176071 4.421875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078842 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.926071 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm15.547592 4.65625q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm3.4069672 2.0l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm16.75 -0.234375l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.547592 5.875l0 -1.90625l1.90625 0l0 1.90625q0 1.046875 -0.375 1.6875q-0.375 0.65625 -1.171875 1.0l-0.46875 -0.71875q0.53125 -0.21875 0.78125 -0.671875q0.25 -0.453125 0.28125 -1.296875l-0.953125 0zm9.304108 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.266342 4.921875l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m88.11708 258.45282l0 -13.593765l2.71875 0l3.21875 9.625q0.4375 1.34375 0.640625 2.0156403q0.234375 -0.75001526 0.734375 -2.1875153l3.25 -9.453125l2.421875 0l0 13.593765l-1.734375 0l0 -11.39064l-3.953125 11.39064l-1.625 0l-3.9375 -11.57814l0 11.57814l-1.734375 0zm21.822052 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.0312653q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.3281403 0.09375 2.9531403q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.7187653q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.67189026 0.5 1.1250153q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.1562653q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm4.078842 4.9375153l0 -9.85939l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625153l-1.671875 0l0 -6.0000153q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.3750153l-1.671875 0zm16.828842 0l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.50001526 -0.09375 -1.5625153l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65626526 0.671875 1.0312653q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.0468903q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.85939l-1.5 0zm10.360092 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.0312653q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.3281403 0.09375 2.9531403q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.7187653q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.67189026 0.5 1.1250153q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.1562653q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm4.047592 4.9375153l0 -13.593765l1.671875 0l0 13.593765l-1.671875 0zm13.015625 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.9843903l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71876526 0.078125 0.92189026q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5114288 1.5l0 -9.85939l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.1562653l-1.671875 0zm6.243927 -11.687515l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.687515l0 -9.85939l1.671875 0l0 9.85939l-1.671875 0zm3.8323212 0.8125l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.4687653 -1.109375 -3.5156403q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.51564q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.9218903q0 1.953125 0.765625 2.8437653q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.89064026 0.78125 -2.7812653q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.000717 5.9218903l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.4687653 -1.109375 -3.5156403q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.51564q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.9218903q0 1.953125 0.765625 2.8437653q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.89064026 0.78125 -2.7812653q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm16.047592 1.9375l1.71875 0.21875q-0.40625 1.5000153 -1.515625 2.3437653q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.7343903q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.4843903q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.5468903zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.094467 5.8750153l0 -9.85939l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.1562653l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m214.93439 46.93176l13.599762 0l0 0.062992096l13.612839 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m214.93439 46.93176l13.599747 0l0 0.062992096l7.612854 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m236.14699 48.646484l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#efefef" d="m242.13387 17.057743l147.2126 0l0 59.748028l-147.2126 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m242.13387 17.057743l147.2126 0l0 59.748028l-147.2126 0z" fill-rule="nonzero"></path><path fill="#000000" d="m296.38846 53.851757l0 -13.59375l5.109375 0q1.546875 0 2.484375 0.40625q0.953125 0.40625 1.484375 1.265625q0.53125 0.859375 0.53125 1.796875q0 0.875 -0.46875 1.65625q-0.46875 0.765625 -1.4375 1.234375q1.234375 0.359375 1.890625 1.234375q0.671875 0.875 0.671875 2.0625q0 0.953125 -0.40625 1.78125q-0.390625 0.8125 -0.984375 1.265625q-0.59375 0.4375 -1.5 0.671875q-0.890625 0.21875 -2.1875 0.21875l-5.1875 0zm1.796875 -7.890625l2.9375 0q1.203125 0 1.71875 -0.15625q0.6875 -0.203125 1.03125 -0.671875q0.359375 -0.46875 0.359375 -1.1875q0 -0.671875 -0.328125 -1.1875q-0.328125 -0.515625 -0.9375 -0.703125q-0.59375 -0.203125 -2.0625 -0.203125l-2.71875 0l0 4.109375zm0 6.28125l3.390625 0q0.875 0 1.21875 -0.0625q0.625 -0.109375 1.046875 -0.359375q0.421875 -0.265625 0.6875 -0.765625q0.265625 -0.5 0.265625 -1.140625q0 -0.765625 -0.390625 -1.328125q-0.390625 -0.5625 -1.078125 -0.78125q-0.6875 -0.234375 -1.984375 -0.234375l-3.15625 0l0 4.671875zm16.959198 1.609375l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm3.9382324 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.097931 0l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.566711 0l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375z" fill-rule="nonzero"></path><path fill="#efefef" d="m408.5328 17.057743l147.21262 0l0 59.748028l-147.21262 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m408.5328 17.057743l147.21262 0l0 59.748028l-147.21262 0z" fill-rule="nonzero"></path><path fill="#000000" d="m455.20813 40.258007l1.796875 0l0 7.84375q0 2.0625 -0.46875 3.265625q-0.453125 1.203125 -1.671875 1.96875q-1.203125 0.75 -3.171875 0.75q-1.90625 0 -3.125 -0.65625q-1.21875 -0.65625 -1.734375 -1.90625q-0.515625 -1.25 -0.515625 -3.421875l0 -7.84375l1.796875 0l0 7.84375q0 1.765625 0.328125 2.609375q0.328125 0.84375 1.125 1.296875q0.8125 0.453125 1.96875 0.453125q1.984375 0 2.828125 -0.890625q0.84375 -0.90625 0.84375 -3.46875l0 -7.84375zm4.332306 13.59375l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm10.391357 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm7.785431 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm10.382233 1.5l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438202 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m594.1181 37.30971l147.21259 0l0 59.748028l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m594.1181 37.30971l147.21259 0l0 59.748028l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m625.4092 63.103725l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.6676636 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031982 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277039 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813232 6.6875l1.609375 0.24999619q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.2812462q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3124962 -0.46875 3.2656212q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.3906212zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6657715 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351074 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m654.5047 85.10372l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438232 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m584.5302 27.199474l147.21259 0l0 59.748035l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m584.5302 27.199474l147.21259 0l0 59.748035l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m615.8212 52.99349l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.6677246 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031921 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.2771 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813171 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6658325 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7350464 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5427246 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5041504 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m644.9168 74.99349l0 -12.000004l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.000004l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438171 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375038l1.65625 -1.0l0 3.4375038l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m574.93176 17.057743l147.21259 0l0 59.748028l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m574.93176 17.057743l147.21259 0l0 59.748028l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m606.22284 42.851757l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.6676636 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031982 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277039 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813232 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6657715 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351074 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m635.31836 64.85175l0 -11.999996l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 11.999996l-1.796875 0zm14.474121 -3.1718712l1.71875 0.21875q-0.40625 1.5 -1.515625 2.3437462q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.3281212q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438232 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.7343712 -1.40625 1.1406212q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.7968712 -1.28125 -2.3593712zm13.65625 1.4375l0.234375 1.4843712q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.7499962q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m389.34647 46.93176l9.593231 0l0 0.062992096l9.58786 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m389.34647 46.93176l9.593201 0l0 0.062992096l3.5878906 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m402.52756 48.646484l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m555.7454 46.93176l9.593201 0l0 0.062992096l9.587891 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m555.7454 46.93176l9.593201 0l0 0.062992096l3.5878906 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m568.9265 48.646484l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m214.96326 207.26509l355.29132 0l0 0.06298828l355.29138 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m214.96326 207.26509l355.29132 0l0 0.06298828l349.29138 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m919.54596 208.97981l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m214.93439 136.81526l14.661118 0l0 0.06300354l14.661713 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m214.93439 136.81526l14.661133 0l0 0.06300354l8.661697 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m238.25722 138.53l4.538101 -1.6517334l-4.538101 -1.6517334z" fill-rule="evenodd"></path><path fill="#efefef" d="m244.25691 106.94125l147.2126 0l0 59.74803l-147.2126 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m244.25691 106.94125l147.2126 0l0 59.74803l-147.2126 0z" fill-rule="nonzero"></path><path fill="#000000" d="m298.5115 143.73526l0 -13.59375l5.109375 0q1.546875 0 2.484375 0.40625q0.953125 0.40625 1.484375 1.265625q0.53125 0.859375 0.53125 1.796875q0 0.875 -0.46875 1.65625q-0.46875 0.765625 -1.4375 1.234375q1.234375 0.359375 1.890625 1.234375q0.671875 0.875 0.671875 2.0625q0 0.953125 -0.40625 1.78125q-0.390625 0.8125 -0.984375 1.265625q-0.59375 0.4375 -1.5 0.671875q-0.890625 0.21875 -2.1875 0.21875l-5.1875 0zm1.796875 -7.890625l2.9375 0q1.203125 0 1.71875 -0.15625q0.6875 -0.203125 1.03125 -0.671875q0.359375 -0.46875 0.359375 -1.1875q0 -0.671875 -0.328125 -1.1875q-0.328125 -0.515625 -0.9375 -0.703125q-0.59375 -0.203125 -2.0625 -0.203125l-2.71875 0l0 4.109375zm0 6.28125l3.390625 0q0.875 0 1.21875 -0.0625q0.625 -0.109375 1.046875 -0.359375q0.421875 -0.265625 0.6875 -0.765625q0.265625 -0.5 0.265625 -1.140625q0 -0.765625 -0.390625 -1.328125q-0.390625 -0.5625 -1.078125 -0.78125q-0.6875 -0.234375 -1.984375 -0.234375l-3.15625 0l0 4.671875zm16.959198 1.609375l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm3.9382324 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.097931 0l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.566711 0l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375z" fill-rule="nonzero"></path><path fill="#efefef" d="m410.65585 106.94125l147.21262 0l0 59.74803l-147.21262 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m410.65585 106.94125l147.21262 0l0 59.74803l-147.21262 0z" fill-rule="nonzero"></path><path fill="#000000" d="m457.33118 130.14151l1.796875 0l0 7.84375q0 2.0625 -0.46875 3.265625q-0.453125 1.203125 -1.671875 1.96875q-1.203125 0.75 -3.171875 0.75q-1.90625 0 -3.125 -0.65625q-1.21875 -0.65625 -1.734375 -1.90625q-0.515625 -1.25 -0.515625 -3.421875l0 -7.84375l1.796875 0l0 7.84375q0 1.765625 0.328125 2.609375q0.328125 0.84375 1.125 1.296875q0.8125 0.453125 1.96875 0.453125q1.984375 0 2.828125 -0.890625q0.84375 -0.90625 0.84375 -3.46875l0 -7.84375zm4.332306 13.59375l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm10.391357 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm7.785431 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm10.382233 1.5l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438202 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m596.24115 127.19322l147.21259 0l0 59.74803l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m596.24115 127.19322l147.21259 0l0 59.74803l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m627.5322 152.98723l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.6676636 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031982 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277039 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813232 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6657715 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351074 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m656.62775 174.98723l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438232 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m586.65326 117.082985l147.21259 0l0 59.748024l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m586.65326 117.082985l147.21259 0l0 59.748024l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m617.9443 142.877l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.6677246 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031921 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.2771 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813171 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6658325 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7350464 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5427246 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5041504 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m647.03986 164.877l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438171 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#efefef" d="m577.0548 106.94125l147.21259 0l0 59.74803l-147.21259 0z" fill-rule="nonzero"></path><path stroke="#999999" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m577.0548 106.94125l147.21259 0l0 59.74803l-147.21259 0z" fill-rule="nonzero"></path><path fill="#000000" d="m608.3459 132.73526l0 -13.593742l1.8125 0l0 13.593742l-1.8125 0zm4.6676636 0l0 -9.859367l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0624924l-1.671875 0l0 -5.9999924q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.3749924l-1.671875 0zm14.031982 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.6562424l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.7499924q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277039 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.7343674q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.43749237l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.7031174l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813232 6.6874924l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.5156174q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515617q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.9218674q0 1.9531174 0.765625 2.8437424q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.7812424q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.1093674l0 -9.859367l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.1562424l-1.671875 0zm12.6657715 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.9531174q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.2343674q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.7187424q-0.90625 0.35936737 -2.734375 0.6249924q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.6093674zm7.7351074 3.4374924l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.6562424l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.7499924q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.187492l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.687492l0 -9.859367l1.671875 0l0 9.859367l-1.671875 0zm3.5042114 -4.9218674q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.9062424 -0.578125 2.9999924q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8124924zm1.71875 0q0 1.8906174 0.828125 2.8281174q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.8906174q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.9218674l0 -9.859367l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0624924l-1.671875 0l0 -5.9999924q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.3749924l-1.671875 0z" fill-rule="nonzero"></path><path fill="#000000" d="m637.4414 154.73526l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438232 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m391.4695 136.81526l9.593231 0l0 0.06300354l9.58786 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m391.46954 136.81526l9.593201 0l0 0.06300354l3.5878906 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m404.65063 138.53l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m557.86847 136.81526l9.593201 0l0 0.06300354l9.587891 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m557.86847 136.81526l9.593201 0l0 0.06300354l3.5878906 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m571.04956 138.53l4.538147 -1.6517334l-4.538147 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m724.2674 136.81526l20.531738 0l0 0.06300354l20.539124 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m724.2674 136.81526l20.531738 0l0 0.06300354l14.539124 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m759.33826 138.53l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path></g></svg> - diff --git a/doc/ci/img/types-of-pipelines.png b/doc/ci/img/types-of-pipelines.png Binary files differnew file mode 100644 index 00000000000..bd809de5e68 --- /dev/null +++ b/doc/ci/img/types-of-pipelines.png diff --git a/doc/ci/img/types-of-pipelines.svg b/doc/ci/img/types-of-pipelines.svg deleted file mode 100644 index b63b5f56ba6..00000000000 --- a/doc/ci/img/types-of-pipelines.svg +++ /dev/null @@ -1,4 +0,0 @@ -<?xml version="1.0" standalone="yes"?> - -<svg version="1.1" viewBox="0.0 0.0 740.6272965879265 293.7795275590551" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><clipPath id="p.0"><path d="m0 0l740.6273 0l0 293.77954l-740.6273 0l0 -293.77954z" clip-rule="nonzero"></path></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l740.6273 0l0 293.77954l-740.6273 0z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m176.05511 4.632546l282.4567 0l0 129.10236l-282.4567 0z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m176.05511 4.632546l282.4567 0l0 129.10236l-282.4567 0z" fill-rule="nonzero"></path><path fill="#ff0000" d="m283.34512 115.88928l1.796875 0.453125q-0.5625 2.21875 -2.03125 3.390625q-1.46875 1.15625 -3.59375 1.15625q-2.203125 0 -3.578125 -0.890625q-1.375 -0.90625 -2.09375 -2.59375q-0.71875 -1.703125 -0.71875 -3.65625q0 -2.125 0.796875 -3.703125q0.8125 -1.578125 2.3125 -2.390625q1.5 -0.828125 3.296875 -0.828125q2.046875 0 3.4375 1.046875q1.390625 1.03125 1.9375 2.90625l-1.765625 0.421875q-0.46875 -1.484375 -1.375 -2.15625q-0.90625 -0.6875 -2.265625 -0.6875q-1.5625 0 -2.625 0.75q-1.046875 0.75 -1.484375 2.03125q-0.421875 1.265625 -0.421875 2.609375q0 1.734375 0.5 3.03125q0.515625 1.28125 1.578125 1.921875q1.078125 0.640625 2.3125 0.640625q1.515625 0 2.5625 -0.859375q1.046875 -0.875 1.421875 -2.59375zm4.066681 4.765625l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm10.069733 0l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.443573 -4.546875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 3.78125l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm15.610077 1.703125l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078857 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm4.191681 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm17.125702 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m482.78796 22.986877l110.11023 0l0 59.74803l-110.11023 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m482.78796 22.986877l110.11023 0l0 59.74803l-110.11023 0z" fill-rule="nonzero"></path><path fill="#434343" d="m499.90414 48.78089l0 -13.59375l4.6875 0q1.578125 0 2.421875 0.1875q1.15625 0.265625 1.984375 0.96875q1.078125 0.921875 1.609375 2.34375q0.53125 1.40625 0.53125 3.21875q0 1.546875 -0.359375 2.75q-0.359375 1.1875 -0.921875 1.984375q-0.5625 0.78125 -1.234375 1.234375q-0.671875 0.4375 -1.625 0.671875q-0.953125 0.234375 -2.1875 0.234375l-4.90625 0zm1.796875 -1.609375l2.90625 0q1.34375 0 2.109375 -0.25q0.765625 -0.25 1.21875 -0.703125q0.640625 -0.640625 1.0 -1.71875q0.359375 -1.078125 0.359375 -2.625q0 -2.125 -0.703125 -3.265625q-0.703125 -1.15625 -1.703125 -1.546875q-0.71875 -0.28125 -2.328125 -0.28125l-2.859375 0l0 10.390625zm18.207306 -1.5625l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.110107 9.65625l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm8.828857 4.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm3.5510864 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.203796 8.71875l-0.171875 -1.5625q0.546875 0.140625 0.953125 0.140625q0.546875 0 0.875 -0.1875q0.34375 -0.1875 0.5625 -0.515625q0.15625 -0.25 0.5 -1.25q0.046875 -0.140625 0.15625 -0.40625l-3.734375 -9.875l1.796875 0l2.046875 5.71875q0.40625 1.078125 0.71875 2.28125q0.28125 -1.15625 0.6875 -2.25l2.09375 -5.75l1.671875 0l-3.75 10.03125q-0.59375 1.625 -0.9375 2.234375q-0.4375 0.828125 -1.015625 1.203125q-0.578125 0.390625 -1.375 0.390625q-0.484375 0 -1.078125 -0.203125zm18.245789 -5.296875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.9020996 -3.421875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125z" fill-rule="nonzero"></path><path fill="#434343" d="m507.0652 66.40589l1.6875 -0.140625q0.125 1.015625 0.5625 1.671875q0.4375 0.65625 1.359375 1.0625q0.9375 0.40625 2.09375 0.40625q1.03125 0 1.8125 -0.3125q0.796875 -0.3125 1.1875 -0.84375q0.390625 -0.53125 0.390625 -1.15625q0 -0.640625 -0.375 -1.109375q-0.375 -0.484375 -1.234375 -0.8125q-0.546875 -0.21875 -2.421875 -0.65625q-1.875 -0.453125 -2.625 -0.859375q-0.96875 -0.515625 -1.453125 -1.265625q-0.46875 -0.75 -0.46875 -1.6875q0 -1.03125 0.578125 -1.921875q0.59375 -0.90625 1.703125 -1.359375q1.125 -0.46875 2.5 -0.46875q1.515625 0 2.671875 0.484375q1.15625 0.484375 1.765625 1.4375q0.625 0.9375 0.671875 2.140625l-1.71875 0.125q-0.140625 -1.28125 -0.953125 -1.9375q-0.796875 -0.671875 -2.359375 -0.671875q-1.625 0 -2.375 0.609375q-0.75 0.59375 -0.75 1.4375q0 0.734375 0.53125 1.203125q0.515625 0.46875 2.703125 0.96875q2.203125 0.5 3.015625 0.875q1.1875 0.546875 1.75 1.390625q0.578125 0.828125 0.578125 1.921875q0 1.09375 -0.625 2.0625q-0.625 0.953125 -1.796875 1.484375q-1.15625 0.53125 -2.609375 0.53125q-1.84375 0 -3.09375 -0.53125q-1.25 -0.546875 -1.96875 -1.625q-0.703125 -1.078125 -0.734375 -2.453125zm16.490417 2.875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm7.9645996 0.28125q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm3.7819214 5.75l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.313232 -6.578125l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm10.078796 0.8125l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m606.1778 23.019379l110.11023 0l0 59.74803l-110.11023 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m606.1778 23.019379l110.11023 0l0 59.74803l-110.11023 0z" fill-rule="nonzero"></path><path fill="#434343" d="m623.29395 48.813393l0 -13.59375l4.6875 0q1.578125 0 2.421875 0.1875q1.15625 0.265625 1.984375 0.96875q1.078125 0.921875 1.609375 2.34375q0.53125 1.40625 0.53125 3.21875q0 1.546875 -0.359375 2.75q-0.359375 1.1875 -0.921875 1.984375q-0.5625 0.78125 -1.234375 1.234375q-0.671875 0.4375 -1.625 0.671875q-0.953125 0.234375 -2.1875 0.234375l-4.90625 0zm1.796875 -1.609375l2.90625 0q1.34375 0 2.109375 -0.25q0.765625 -0.25 1.21875 -0.703125q0.640625 -0.640625 1.0 -1.71875q0.359375 -1.078125 0.359375 -2.625q0 -2.125 -0.703125 -3.265625q-0.703125 -1.15625 -1.703125 -1.546875q-0.71875 -0.28125 -2.328125 -0.28125l-2.859375 0l0 10.390625zm18.207336 -1.5625l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.110107 9.65625l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm8.828857 4.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm3.5510254 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.203857 8.71875l-0.171875 -1.5625q0.546875 0.140625 0.953125 0.140625q0.546875 0 0.875 -0.1875q0.34375 -0.1875 0.5625 -0.515625q0.15625 -0.25 0.5 -1.25q0.046875 -0.140625 0.15625 -0.40625l-3.734375 -9.875l1.796875 0l2.046875 5.71875q0.40625 1.078125 0.71875 2.28125q0.28125 -1.15625 0.6875 -2.25l2.09375 -5.75l1.671875 0l-3.75 10.03125q-0.59375 1.625 -0.9375 2.234375q-0.4375 0.828125 -1.015625 1.203125q-0.578125 0.390625 -1.375 0.390625q-0.484375 0 -1.078125 -0.203125zm18.245789 -5.296875l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.9020996 -3.421875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125z" fill-rule="nonzero"></path><path fill="#434343" d="m618.10614 70.81339l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.4122925 7.140625l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.6033325 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672546 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm15.719482 4.921875l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm10.360107 -3.609375l1.640625 0.21875q-0.265625 1.6875 -1.375 2.65625q-1.109375 0.953125 -2.734375 0.953125q-2.015625 0 -3.25 -1.3125q-1.21875 -1.328125 -1.21875 -3.796875q0 -1.59375 0.515625 -2.78125q0.53125 -1.203125 1.609375 -1.796875q1.09375 -0.609375 2.359375 -0.609375q1.609375 0 2.625 0.8125q1.015625 0.8125 1.3125 2.3125l-1.625 0.25q-0.234375 -1.0 -0.828125 -1.5q-0.59375 -0.5 -1.421875 -0.5q-1.265625 0 -2.0625 0.90625q-0.78125 0.90625 -0.78125 2.859375q0 1.984375 0.765625 2.890625q0.765625 0.890625 1.984375 0.890625q0.984375 0 1.640625 -0.59375q0.65625 -0.609375 0.84375 -1.859375zm6.546875 2.109375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m192.52992 22.986877l110.07875 0l0 59.74803l-110.07875 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m192.52992 22.986877l110.07875 0l0 59.74803l-110.07875 0z" fill-rule="nonzero"></path><path fill="#434343" d="m228.21759 59.78089l0 -13.59375l5.109375 0q1.546875 0 2.484375 0.40625q0.953125 0.40625 1.484375 1.265625q0.53125 0.859375 0.53125 1.796875q0 0.875 -0.46875 1.65625q-0.46875 0.765625 -1.4375 1.234375q1.234375 0.359375 1.890625 1.234375q0.671875 0.875 0.671875 2.0625q0 0.953125 -0.40625 1.78125q-0.390625 0.8125 -0.984375 1.265625q-0.59375 0.4375 -1.5 0.671875q-0.890625 0.21875 -2.1875 0.21875l-5.1875 0zm1.796875 -7.890625l2.9375 0q1.203125 0 1.71875 -0.15625q0.6875 -0.203125 1.03125 -0.671875q0.359375 -0.46875 0.359375 -1.1875q0 -0.671875 -0.328125 -1.1875q-0.328125 -0.515625 -0.9375 -0.703125q-0.59375 -0.203125 -2.0625 -0.203125l-2.71875 0l0 4.109375zm0 6.28125l3.390625 0q0.875 0 1.21875 -0.0625q0.625 -0.109375 1.046875 -0.359375q0.421875 -0.265625 0.6875 -0.765625q0.265625 -0.5 0.265625 -1.140625q0 -0.765625 -0.390625 -1.328125q-0.390625 -0.5625 -1.078125 -0.78125q-0.6875 -0.234375 -1.984375 -0.234375l-3.15625 0l0 4.671875zm16.959198 1.609375l0 -1.453125q-1.140625 1.671875 -3.125 1.671875q-0.859375 0 -1.625 -0.328125q-0.75 -0.34375 -1.125 -0.84375q-0.359375 -0.5 -0.515625 -1.234375q-0.09375 -0.5 -0.09375 -1.5625l0 -6.109375l1.671875 0l0 5.46875q0 1.3125 0.09375 1.765625q0.15625 0.65625 0.671875 1.03125q0.515625 0.375 1.265625 0.375q0.75 0 1.40625 -0.375q0.65625 -0.390625 0.921875 -1.046875q0.28125 -0.671875 0.28125 -1.9375l0 -5.28125l1.671875 0l0 9.859375l-1.5 0zm3.9382172 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.097946 0l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.566681 0l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m331.2466 43.238846l110.078735 0l0 59.74803l-110.078735 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m331.2466 43.238846l110.078735 0l0 59.74803l-110.078735 0z" fill-rule="nonzero"></path><path fill="#434343" d="m343.97073 69.03286l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.667694 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031952 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277069 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813202 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.665802 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.735077 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426941 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.504181 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281982 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#434343" d="m373.06628 91.03286l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438202 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m324.0777 33.12861l110.078766 0l0 59.74803l-110.078766 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m324.0777 33.12861l110.078766 0l0 59.74803l-110.078766 0z" fill-rule="nonzero"></path><path fill="#434343" d="m336.80185 58.922623l0 -13.59375l1.8125 0l0 13.59375l-1.8125 0zm4.667694 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm14.031952 -1.5l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277069 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.813202 6.6875l1.609375 0.25q0.109375 0.75 0.578125 1.09375q0.609375 0.453125 1.6875 0.453125q1.171875 0 1.796875 -0.46875q0.625 -0.453125 0.859375 -1.28125q0.125 -0.515625 0.109375 -2.15625q-1.09375 1.296875 -2.71875 1.296875q-2.03125 0 -3.15625 -1.46875q-1.109375 -1.46875 -1.109375 -3.515625q0 -1.40625 0.515625 -2.59375q0.515625 -1.203125 1.484375 -1.84375q0.96875 -0.65625 2.265625 -0.65625q1.75 0 2.875 1.40625l0 -1.1875l1.546875 0l0 8.515625q0 2.3125 -0.46875 3.265625q-0.46875 0.96875 -1.484375 1.515625q-1.015625 0.5625 -2.5 0.5625q-1.765625 0 -2.859375 -0.796875q-1.078125 -0.796875 -1.03125 -2.390625zm1.375 -5.921875q0 1.953125 0.765625 2.84375q0.78125 0.890625 1.9375 0.890625q1.140625 0 1.921875 -0.890625q0.78125 -0.890625 0.78125 -2.78125q0 -1.8125 -0.8125 -2.71875q-0.796875 -0.921875 -1.921875 -0.921875q-1.109375 0 -1.890625 0.90625q-0.78125 0.890625 -0.78125 2.671875zm9.281982 5.109375l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm12.6657715 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.8593445 0.3125 -1.8437195 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.0312195 -0.25 2.9843445 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.9062195 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.2499695 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.7343445 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.9687195 0 1.7187195 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351074 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm1.5426636 -10.1875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm3.5042114 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281952 4.921875l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0z" fill-rule="nonzero"></path><path fill="#434343" d="m365.8974 80.92262l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474091 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438232 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125z" fill-rule="nonzero"></path><path fill="#f3f3f3" d="m316.90097 22.986877l110.078735 0l0 59.74803l-110.078735 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m316.90097 22.986877l110.078735 0l0 59.74803l-110.078735 0z" fill-rule="nonzero"></path><path fill="#434343" d="m354.05658 59.78089l0 -12.0l-4.46875 0l0 -1.59375l10.765625 0l0 1.59375l-4.5 0l0 12.0l-1.796875 0zm14.474121 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm8.438202 2.9375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375zm13.65625 1.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm0.8551941 -1.4375l1.65625 -0.265625q0.140625 1.0 0.765625 1.53125q0.640625 0.515625 1.78125 0.515625q1.15625 0 1.703125 -0.46875q0.5625 -0.46875 0.5625 -1.09375q0 -0.5625 -0.484375 -0.890625q-0.34375 -0.21875 -1.703125 -0.5625q-1.84375 -0.46875 -2.5625 -0.796875q-0.703125 -0.34375 -1.078125 -0.9375q-0.359375 -0.609375 -0.359375 -1.328125q0 -0.65625 0.296875 -1.21875q0.3125 -0.5625 0.828125 -0.9375q0.390625 -0.28125 1.0625 -0.484375q0.671875 -0.203125 1.4375 -0.203125q1.171875 0 2.046875 0.34375q0.875 0.328125 1.28125 0.90625q0.421875 0.5625 0.578125 1.515625l-1.625 0.21875q-0.109375 -0.75 -0.65625 -1.171875q-0.53125 -0.4375 -1.5 -0.4375q-1.15625 0 -1.640625 0.390625q-0.484375 0.375 -0.484375 0.875q0 0.328125 0.203125 0.59375q0.203125 0.265625 0.640625 0.4375q0.25 0.09375 1.46875 0.4375q1.765625 0.46875 2.46875 0.765625q0.703125 0.296875 1.09375 0.875q0.40625 0.578125 0.40625 1.4375q0 0.828125 -0.484375 1.578125q-0.484375 0.734375 -1.40625 1.140625q-0.921875 0.390625 -2.078125 0.390625q-1.921875 0 -2.9375 -0.796875q-1.0 -0.796875 -1.28125 -2.359375z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m302.60867 52.860893l7.165344 0l0 0.062992096l7.165344 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m302.60864 52.860893l7.1653748 0l0 0.062992096l1.1653442 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m310.93936 54.57562l4.5381165 -1.6517334l-4.5381165 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m426.9797 52.860893l27.904388 0l0 0.062992096l27.906647 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m426.9797 52.860893l27.904388 0l0 0.062992096l21.906616 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m476.7907 54.57562l4.5381165 -1.6517334l-4.5381165 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m592.8982 52.860893l6.6398315 0l0 0.062992096l6.6514893 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m592.8982 52.860893l6.6398315 0l0 0.062992096l0.6515503 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m600.1896 54.57562l4.538086 -1.6517334l-4.538086 -1.6517334z" fill-rule="evenodd"></path><path fill="#f3f3f3" d="m26.104986 22.986877l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m26.104986 22.986877l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path fill="#434343" d="m70.03193 55.015266l1.796875 0.453125q-0.5625 2.21875 -2.03125 3.390625q-1.46875 1.15625 -3.59375 1.15625q-2.203125 0 -3.5781212 -0.890625q-1.375 -0.90625 -2.09375 -2.59375q-0.71875 -1.703125 -0.71875 -3.65625q0 -2.125 0.796875 -3.703125q0.8125 -1.578125 2.3125 -2.390625q1.4999962 -0.828125 3.2968712 -0.828125q2.046875 0 3.4375 1.046875q1.390625 1.03125 1.9375 2.90625l-1.765625 0.421875q-0.46875 -1.484375 -1.375 -2.15625q-0.90625 -0.6875 -2.265625 -0.6875q-1.5625 0 -2.6249962 0.75q-1.046875 0.75 -1.484375 2.03125q-0.421875 1.265625 -0.421875 2.609375q0 1.734375 0.5 3.03125q0.515625 1.28125 1.578125 1.921875q1.0781212 0.640625 2.3124962 0.640625q1.515625 0 2.5625 -0.859375q1.046875 -0.875 1.421875 -2.59375zm2.9260712 -0.15625q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672592 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm16.016342 1.75l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m136.21523 52.860893l28.15747 0l0 0.062992096l28.157486 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m136.21523 52.860893l28.15747 0l0 0.062992096l22.157486 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m186.53018 54.57562l4.538101 -1.6517334l-4.538101 -1.6517334z" fill-rule="evenodd"></path><path fill="#f3f3f3" d="m26.104986 120.98688l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m26.104986 120.98688l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path fill="#434343" d="m50.508137 146.78088l0 -13.59375l6.03125 0q1.8125 0 2.75 0.359375q0.953125 0.359375 1.515625 1.296875q0.5625 0.921875 0.5625 2.046875q0 1.453125 -0.9375 2.453125q-0.921875 0.984375 -2.890625 1.25q0.71875 0.34375 1.09375 0.671875q0.78125 0.734375 1.484375 1.8125l2.375 3.703125l-2.265625 0l-1.796875 -2.828125q-0.796875 -1.21875 -1.3125 -1.875q-0.5 -0.65625 -0.90625 -0.90625q-0.40625 -0.265625 -0.8125 -0.359375q-0.3125 -0.078125 -1.015625 -0.078125l-2.078125 0l0 6.046875l-1.796875 0zm1.796875 -7.59375l3.859375 0q1.234375 0 1.921875 -0.25q0.703125 -0.265625 1.0625 -0.828125q0.375 -0.5625 0.375 -1.21875q0 -0.96875 -0.703125 -1.578125q-0.703125 -0.625 -2.21875 -0.625l-4.296875 0l0 4.5zm18.176067 4.421875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.2656212 -1.328125 -1.2656212 -3.734375q0 -2.484375 1.2656212 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078842 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.613571 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.4062576 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.6562576 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277054 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm15.500717 5.875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375z" fill-rule="nonzero"></path><path fill="#434343" d="m70.03193 164.01526l1.796875 0.453125q-0.5625 2.21875 -2.03125 3.390625q-1.46875 1.15625 -3.59375 1.15625q-2.203125 0 -3.5781212 -0.890625q-1.375 -0.90625 -2.09375 -2.59375q-0.71875 -1.703125 -0.71875 -3.65625q0 -2.125 0.796875 -3.703125q0.8125 -1.578125 2.3125 -2.390625q1.4999962 -0.828125 3.2968712 -0.828125q2.046875 0 3.4375 1.046875q1.390625 1.03125 1.9375 2.90625l-1.765625 0.421875q-0.46875 -1.484375 -1.375 -2.15625q-0.90625 -0.6875 -2.265625 -0.6875q-1.5625 0 -2.6249962 0.75q-1.046875 0.75 -1.484375 2.03125q-0.421875 1.265625 -0.421875 2.609375q0 1.734375 0.5 3.03125q0.515625 1.28125 1.578125 1.921875q1.0781212 0.640625 2.3124962 0.640625q1.515625 0 2.5625 -0.859375q1.046875 -0.875 1.421875 -2.59375zm2.9260712 -0.15625q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672592 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm16.016342 1.75l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m136.21523 150.86089l28.15747 0l0 -98.01574l28.157486 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m136.21523 150.86089l28.15747 0l0 -98.01574l22.157486 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m186.53018 54.496876l4.538101 -1.6517296l-4.538101 -1.6517334z" fill-rule="evenodd"></path><path fill="#f3f3f3" d="m26.104986 190.98688l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path stroke="#b7b7b7" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m26.104986 190.98688l110.11024 0l0 59.74803l-110.11024 0z" fill-rule="nonzero"></path><path fill="#434343" d="m50.508137 216.78088l0 -13.59375l6.03125 0q1.8125 0 2.75 0.359375q0.953125 0.359375 1.515625 1.296875q0.5625 0.921875 0.5625 2.046875q0 1.453125 -0.9375 2.453125q-0.921875 0.984375 -2.890625 1.25q0.71875 0.34375 1.09375 0.671875q0.78125 0.734375 1.484375 1.8125l2.375 3.703125l-2.265625 0l-1.796875 -2.828125q-0.796875 -1.21875 -1.3125 -1.875q-0.5 -0.65625 -0.90625 -0.90625q-0.40625 -0.265625 -0.8125 -0.359375q-0.3125 -0.078125 -1.015625 -0.078125l-2.078125 0l0 6.046875l-1.796875 0zm1.796875 -7.59375l3.859375 0q1.234375 0 1.921875 -0.25q0.703125 -0.265625 1.0625 -0.828125q0.375 -0.5625 0.375 -1.21875q0 -0.96875 -0.703125 -1.578125q-0.703125 -0.625 -2.21875 -0.625l-4.296875 0l0 4.5zm18.176067 4.421875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.2656212 -1.328125 -1.2656212 -3.734375q0 -2.484375 1.2656212 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078842 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm10.613571 -1.21875q-0.9375 0.796875 -1.796875 1.125q-0.859375 0.3125 -1.84375 0.3125q-1.609375 0 -2.484375 -0.78125q-0.875 -0.796875 -0.875 -2.03125q0 -0.734375 0.328125 -1.328125q0.328125 -0.59375 0.859375 -0.953125q0.53125 -0.359375 1.203125 -0.546875q0.5 -0.140625 1.484375 -0.25q2.03125 -0.25 2.984375 -0.578125q0 -0.34375 0 -0.4375q0 -1.015625 -0.46875 -1.4375q-0.640625 -0.5625 -1.90625 -0.5625q-1.171875 0 -1.734375 0.40625q-0.5625 0.40625 -0.828125 1.46875l-1.640625 -0.234375q0.234375 -1.046875 0.734375 -1.6875q0.515625 -0.640625 1.46875 -0.984375q0.96875 -0.359375 2.25 -0.359375q1.265625 0 2.046875 0.296875q0.78125 0.296875 1.15625 0.75q0.375 0.453125 0.515625 1.140625q0.09375 0.421875 0.09375 1.53125l0 2.234375q0 2.328125 0.09375 2.953125q0.109375 0.609375 0.4375 1.171875l-1.75 0q-0.265625 -0.515625 -0.328125 -1.21875zm-0.140625 -3.71875q-0.90625 0.359375 -2.734375 0.625q-1.03125 0.140625 -1.453125 0.328125q-0.421875 0.1875 -0.65625 0.546875q-0.234375 0.359375 -0.234375 0.796875q0 0.671875 0.5 1.125q0.515625 0.4375 1.484375 0.4375q0.96875 0 1.71875 -0.421875q0.75 -0.4375 1.109375 -1.15625q0.265625 -0.578125 0.265625 -1.671875l0 -0.609375zm7.7351 3.4375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.4062576 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.6562576 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm8.277054 -1.671875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm15.500717 5.875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375z" fill-rule="nonzero"></path><path fill="#434343" d="m70.03193 234.01526l1.796875 0.453125q-0.5625 2.21875 -2.03125 3.390625q-1.46875 1.15625 -3.59375 1.15625q-2.203125 0 -3.5781212 -0.890625q-1.375 -0.90625 -2.09375 -2.59375q-0.71875 -1.703125 -0.71875 -3.65625q0 -2.125 0.796875 -3.703125q0.8125 -1.578125 2.3125 -2.390625q1.4999962 -0.828125 3.2968712 -0.828125q2.046875 0 3.4375 1.046875q1.390625 1.03125 1.9375 2.90625l-1.765625 0.421875q-0.46875 -1.484375 -1.375 -2.15625q-0.90625 -0.6875 -2.265625 -0.6875q-1.5625 0 -2.6249962 0.75q-1.046875 0.75 -1.484375 2.03125q-0.421875 1.265625 -0.421875 2.609375q0 1.734375 0.5 3.03125q0.515625 1.28125 1.578125 1.921875q1.0781212 0.640625 2.3124962 0.640625q1.515625 0 2.5625 -0.859375q1.046875 -0.875 1.421875 -2.59375zm2.9260712 -0.15625q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm15.672592 4.921875l0 -1.25q-0.9375 1.46875 -2.75 1.46875q-1.171875 0 -2.171875 -0.640625q-0.984375 -0.65625 -1.53125 -1.8125q-0.53125 -1.171875 -0.53125 -2.6875q0 -1.46875 0.484375 -2.671875q0.5 -1.203125 1.46875 -1.84375q0.984375 -0.640625 2.203125 -0.640625q0.890625 0 1.578125 0.375q0.703125 0.375 1.140625 0.984375l0 -4.875l1.65625 0l0 13.59375l-1.546875 0zm-5.28125 -4.921875q0 1.890625 0.796875 2.828125q0.8125 0.9375 1.890625 0.9375q1.09375 0 1.859375 -0.890625q0.765625 -0.890625 0.765625 -2.734375q0 -2.015625 -0.78125 -2.953125q-0.78125 -0.953125 -1.921875 -0.953125q-1.109375 0 -1.859375 0.90625q-0.75 0.90625 -0.75 2.859375zm16.016342 1.75l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m136.21523 220.86089l28.15747 0l0 -168.0l28.157486 0" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" d="m136.21523 220.86089l28.15747 0l0 -168.0l22.157486 0" fill-rule="evenodd"></path><path fill="#000000" stroke="#000000" stroke-width="1.0" stroke-linecap="butt" d="m186.53018 54.512627l4.538101 -1.6517334l-4.538101 -1.6517334z" fill-rule="evenodd"></path><path fill="#000000" fill-opacity="0.0" d="m5.1522307 4.632546l165.85826 0l0 283.52756l-165.85826 0z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m5.1522307 4.632546l165.85826 0l0 283.52756l-165.85826 0z" fill-rule="nonzero"></path><path fill="#ff0000" d="m24.73604 275.0801l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q0.9999981 0.171875 1.6718731 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984373 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.468748 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.1249981 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.412321 7.140625l0 -9.859375l1.5 0l0 1.5q0.578125 -1.046875 1.0625 -1.375q0.484375 -0.34375 1.078125 -0.34375q0.84375 0 1.71875 0.546875l-0.578125 1.546875q-0.609375 -0.359375 -1.234375 -0.359375q-0.546875 0 -0.984375 0.328125q-0.421875 0.328125 -0.609375 0.90625q-0.28125 0.890625 -0.28125 1.953125l0 5.15625l-1.671875 0zm5.603302 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.281967 -6.734375l0 -1.9375l1.65625 0l0 1.9375l-1.65625 0zm-2.125 15.484375l0.3125 -1.421875q0.5 0.125 0.796875 0.125q0.515625 0 0.765625 -0.34375q0.25 -0.328125 0.25 -1.6875l0 -10.359375l1.65625 0l0 10.390625q0 1.828125 -0.46875 2.546875q-0.59375 0.921875 -2.0 0.921875q-0.671875 0 -1.3125 -0.171875zm13.019821 -7.0l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm15.547592 2.265625l1.640625 0.21875q-0.265625 1.6875 -1.375 2.65625q-1.109375 0.953125 -2.734375 0.953125q-2.015625 0 -3.25 -1.3125q-1.21875 -1.328125 -1.21875 -3.796875q0 -1.59375 0.515625 -2.78125q0.53125 -1.203125 1.609375 -1.796875q1.09375 -0.609375 2.359375 -0.609375q1.609375 0 2.625 0.8125q1.015625 0.8125 1.3125 2.3125l-1.625 0.25q-0.234375 -1.0 -0.828125 -1.5q-0.59375 -0.5 -1.421875 -0.5q-1.265625 0 -2.0625 0.90625q-0.78125 0.90625 -0.78125 2.859375q0 1.984375 0.765625 2.890625q0.765625 0.890625 1.984375 0.890625q0.984375 0 1.640625 -0.59375q0.65625 -0.609375 0.84375 -1.859375zm6.546875 2.109375l0.234375 1.484375q-0.703125 0.140625 -1.265625 0.140625q-0.90625 0 -1.40625 -0.28125q-0.5 -0.296875 -0.703125 -0.75q-0.203125 -0.46875 -0.203125 -1.984375l0 -5.65625l-1.234375 0l0 -1.3125l1.234375 0l0 -2.4375l1.65625 -1.0l0 3.4375l1.6875 0l0 1.3125l-1.6875 0l0 5.75q0 0.71875 0.078125 0.921875q0.09375 0.203125 0.296875 0.328125q0.203125 0.125 0.578125 0.125q0.265625 0 0.734375 -0.078125zm6.9291077 1.5l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.443573 -4.546875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.129196 3.78125l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm15.610092 1.703125l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078842 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm4.191696 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.129196 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm17.125732 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path><path fill="#000000" fill-opacity="0.0" d="m464.70865 4.632546l270.23624 0l0 129.10236l-270.23624 0z" fill-rule="nonzero"></path><path stroke="#000000" stroke-width="1.0" stroke-linejoin="round" stroke-linecap="butt" stroke-dasharray="4.0,3.0" d="m464.70865 4.632546l270.23624 0l0 129.10236l-270.23624 0z" fill-rule="nonzero"></path><path fill="#ff0000" d="m536.47687 120.65491l0 -13.59375l4.6875 0q1.578125 0 2.421875 0.1875q1.15625 0.265625 1.984375 0.96875q1.078125 0.921875 1.609375 2.34375q0.53125 1.40625 0.53125 3.21875q0 1.546875 -0.359375 2.75q-0.359375 1.1875 -0.921875 1.984375q-0.5625 0.78125 -1.234375 1.234375q-0.671875 0.4375 -1.625 0.671875q-0.953125 0.234375 -2.1875 0.234375l-4.90625 0zm1.796875 -1.609375l2.90625 0q1.34375 0 2.109375 -0.25q0.765625 -0.25 1.21875 -0.703125q0.640625 -0.640625 1.0 -1.71875q0.359375 -1.078125 0.359375 -2.625q0 -2.125 -0.703125 -3.265625q-0.703125 -1.15625 -1.703125 -1.546875q-0.71875 -0.28125 -2.328125 -0.28125l-2.859375 0l0 10.390625zm18.207336 -1.5625l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.110107 9.65625l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm8.828857 4.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm3.5510254 -4.921875q0 -2.734375 1.53125 -4.0625q1.265625 -1.09375 3.09375 -1.09375q2.03125 0 3.3125 1.34375q1.296875 1.328125 1.296875 3.671875q0 1.90625 -0.578125 3.0q-0.5625 1.078125 -1.65625 1.6875q-1.078125 0.59375 -2.375 0.59375q-2.0625 0 -3.34375 -1.328125q-1.28125 -1.328125 -1.28125 -3.8125zm1.71875 0q0 1.890625 0.828125 2.828125q0.828125 0.9375 2.078125 0.9375q1.25 0 2.0625 -0.9375q0.828125 -0.953125 0.828125 -2.890625q0 -1.828125 -0.828125 -2.765625q-0.828125 -0.9375 -2.0625 -0.9375q-1.25 0 -2.078125 0.9375q-0.828125 0.9375 -0.828125 2.828125zm9.203857 8.71875l-0.171875 -1.5625q0.546875 0.140625 0.953125 0.140625q0.546875 0 0.875 -0.1875q0.34375 -0.1875 0.5625 -0.515625q0.15625 -0.25 0.5 -1.25q0.046875 -0.140625 0.15625 -0.40625l-3.734375 -9.875l1.796875 0l2.046875 5.71875q0.40625 1.078125 0.71875 2.28125q0.28125 -1.15625 0.6875 -2.25l2.09375 -5.75l1.671875 0l-3.75 10.03125q-0.59375 1.625 -0.9375 2.234375q-0.4375 0.828125 -1.015625 1.203125q-0.578125 0.390625 -1.375 0.390625q-0.484375 0 -1.078125 -0.203125zm14.808289 -3.796875l0 -13.59375l5.125 0q1.359375 0 2.078125 0.125q1.0 0.171875 1.671875 0.640625q0.671875 0.46875 1.078125 1.3125q0.421875 0.84375 0.421875 1.84375q0 1.734375 -1.109375 2.9375q-1.09375 1.203125 -3.984375 1.203125l-3.484375 0l0 5.53125l-1.796875 0zm1.796875 -7.140625l3.515625 0q1.75 0 2.46875 -0.640625q0.734375 -0.65625 0.734375 -1.828125q0 -0.859375 -0.4375 -1.46875q-0.421875 -0.609375 -1.125 -0.796875q-0.453125 -0.125 -1.671875 -0.125l-3.484375 0l0 4.859375zm10.4436035 -4.546875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 3.78125l0 -13.640625l1.53125 0l0 1.28125q0.53125 -0.75 1.203125 -1.125q0.6875 -0.375 1.640625 -0.375q1.265625 0 2.234375 0.65625q0.96875 0.640625 1.453125 1.828125q0.5 1.1875 0.5 2.59375q0 1.515625 -0.546875 2.734375q-0.546875 1.203125 -1.578125 1.84375q-1.03125 0.640625 -2.171875 0.640625q-0.84375 0 -1.515625 -0.34375q-0.65625 -0.359375 -1.078125 -0.890625l0 4.796875l-1.671875 0zm1.515625 -8.65625q0 1.90625 0.765625 2.8125q0.78125 0.90625 1.875 0.90625q1.109375 0 1.890625 -0.9375q0.796875 -0.9375 0.796875 -2.921875q0 -1.875 -0.78125 -2.8125q-0.765625 -0.9375 -1.84375 -0.9375q-1.0625 0 -1.890625 1.0q-0.8125 1.0 -0.8125 2.890625zm15.610046 1.703125l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875zm9.078857 5.875l0 -13.59375l1.671875 0l0 13.59375l-1.671875 0zm4.1917114 -11.6875l0 -1.90625l1.671875 0l0 1.90625l-1.671875 0zm0 11.6875l0 -9.859375l1.671875 0l0 9.859375l-1.671875 0zm4.1292114 0l0 -9.859375l1.5 0l0 1.40625q1.09375 -1.625 3.140625 -1.625q0.890625 0 1.640625 0.328125q0.75 0.3125 1.109375 0.84375q0.375 0.515625 0.53125 1.21875q0.09375 0.46875 0.09375 1.625l0 6.0625l-1.671875 0l0 -6.0q0 -1.015625 -0.203125 -1.515625q-0.1875 -0.515625 -0.6875 -0.8125q-0.5 -0.296875 -1.171875 -0.296875q-1.0625 0 -1.84375 0.671875q-0.765625 0.671875 -0.765625 2.578125l0 5.375l-1.671875 0zm17.125671 -3.171875l1.71875 0.21875q-0.40625 1.5 -1.515625 2.34375q-1.09375 0.828125 -2.8125 0.828125q-2.15625 0 -3.421875 -1.328125q-1.265625 -1.328125 -1.265625 -3.734375q0 -2.484375 1.265625 -3.859375q1.28125 -1.375 3.328125 -1.375q1.984375 0 3.234375 1.34375q1.25 1.34375 1.25 3.796875q0 0.140625 -0.015625 0.4375l-7.34375 0q0.09375 1.625 0.921875 2.484375q0.828125 0.859375 2.0625 0.859375q0.90625 0 1.546875 -0.46875q0.65625 -0.484375 1.046875 -1.546875zm-5.484375 -2.703125l5.5 0q-0.109375 -1.234375 -0.625 -1.859375q-0.796875 -0.96875 -2.078125 -0.96875q-1.140625 0 -1.9375 0.78125q-0.78125 0.765625 -0.859375 2.046875z" fill-rule="nonzero"></path></g></svg> - diff --git a/doc/ci/img/view_on_env_blob.png b/doc/ci/img/view_on_env_blob.png Binary files differindex dd9ca40280a..acc457fbb38 100644 --- a/doc/ci/img/view_on_env_blob.png +++ b/doc/ci/img/view_on_env_blob.png diff --git a/doc/ci/img/view_on_mr_widget.png b/doc/ci/img/view_on_mr_widget.png Binary files differnew file mode 100644 index 00000000000..04f4b58df62 --- /dev/null +++ b/doc/ci/img/view_on_mr_widget.png diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 8ce4fe55cec..2c799e83a5f 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,15 +1,14 @@ -# Getting started with interactive web terminals +# Getting started with interactive web terminals **[CORE ONLY]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for -running one-of commands for their CI pipeline. +running one-off commands for their CI pipeline. NOTE: **Note:** -This is not available for the shared Runners on GitLab.com. -To make use of this feature, you need to provide your -[own Runner](https://docs.gitlab.com/runner/install/) and properly -[configure it](#configuration). +GitLab.com does not support interactive web terminal at the moment. Please +follow [this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611) for +progress. ## Configuration @@ -17,7 +16,7 @@ Two things need to be configured for the interactive web terminal to work: - The Runner needs to have [`[session_server]` configured properly][session-server] -- Web terminals need to be +- If you are using a reverse proxy with your GitLab instance, web terminals need to be [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support) ## Debugging a running job @@ -25,6 +24,12 @@ Two things need to be configured for the interactive web terminal to work: NOTE: **Note:** Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart). +NOTE: **Note:** The `docker` executor does not keep running +after the build script is finished. At that point, the terminal will automatically +disconnect and will not wait for the user to finish. Please follow [this +issue](https://gitlab.com/gitlab-org/gitlab-runner/issues/3605) for updates on +improving this behavior. + Sometimes, when a job is running, things don't go as you would expect, and it would be helpful if one can have a shell to aid debugging. When a job is running, on the right panel you can see a button `debug` that will open the terminal diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index cf22450914c..91a0ae327bf 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -61,7 +61,7 @@ For a list of supported languages on JUnit tests, check the [Wikipedia article](https://en.wikipedia.org/wiki/JUnit#Ports). To enable the JUnit reports in merge requests, you need to add -[`artifacts:reports:junit`](yaml/README.md#artifacts-reports-junit) +[`artifacts:reports:junit`](yaml/README.md#artifactsreportsjunit) in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports. In the following examples, the job in the `test` stage runs and GitLab @@ -69,6 +69,10 @@ collects the JUnit test report from each job. After each job is executed, the XML reports are stored in GitLab as artifacts and their results are shown in the merge request widget. +NOTE: **Note:** +If you also want the ability to browse JUnit output files, include the +[`artifacts:paths`](yaml/README.md#artifactspaths) keyword. + ### Ruby example Use the following job in `.gitlab-ci.yml`: @@ -140,6 +144,27 @@ java: - target/failsafe-reports/TEST-*.xml ``` +### C/C++ example + +There are a few tools that can produce JUnit reports in C/C++. + +#### GoogleTest + +In the following example, `gtest` is used to generate the test reports. +If there are multiple gtest executables created for different architectures (`x86`, `x64` or `arm`), +you will be required to run each test providing a unique filename. The results +will then be aggregated together. + +```yaml +cpp: + stage: test + script: + - gtest.exe --gtest_output="xml:report.xml" + artifacts: + reports: + junit: report.xml +``` + ## Limitations Currently, the following tools might not work because their XML formats are unsupported in GitLab. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index ea47d676edb..f8cf9de9aff 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -27,7 +27,7 @@ GitLab capitalizes the stages' names when shown in the [pipeline graphs](#pipeli There are three types of pipelines that often use the single shorthand of "pipeline". People often talk about them as if each one is "the" pipeline, but really, they're just pieces of a single, comprehensive pipeline. - + 1. **CI Pipeline**: Build and test stages defined in `.gitlab-ci.yml`. 1. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production. @@ -43,7 +43,7 @@ Pipelines accommodate several development workflows: Example continuous delivery flow: - + ## Jobs @@ -193,6 +193,18 @@ stage has a job with a manual action.  +### Delay a particular job in the pipeline graph + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4. + +When you do not want to run a job immediately, you can [delay the job to run after a certain period](yaml/README.md#when-delayed). +This is especially useful for timed incremental rollout that new code is rolled out gradually. +For example, if you start rolling out new code and users do not experience trouble, GitLab automatically completes the deployment from 0% to 100%. +Alternatively, if you start rolling out and you noticed that a few users experience trouble with the version, +you can stop the timed incremental rollout by canceling the pipeline, and [rolling](environments.md#rolling-back-changes) it back to the stable version. + + + ### Ordering of jobs in pipeline graphs **Regular pipeline graph** @@ -211,6 +223,7 @@ by name. The order of severity is: - pending - running - manual +- scheduled - canceled - success - skipped @@ -281,7 +294,7 @@ runners will not use regular runners, they must be tagged accordingly. [jobs]: #jobs [jobs-yaml]: yaml/README.md#jobs -[manual]: yaml/README.md#manual +[manual]: yaml/README.md#whenmanual [env-manual]: environments.md#manually-deploying-to-environments [stages]: yaml/README.md#stages [runners]: runners/README.html diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 636117536a2..bdc593493ea 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -168,7 +168,7 @@ can be found at <https://docs.gitlab.com/runner/>. In order to have a functional Runner you need to follow two steps: 1. [Install it][runner-install] -2. [Configure it](../runners/README.md#registering-a-specific-runner) +1. [Configure it](../runners/README.md#registering-a-specific-runner) Follow the links above to set up your own Runner or use a Shared Runner as described in the next section. diff --git a/doc/ci/review_apps/img/continuous-delivery-review-apps.svg b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg new file mode 100644 index 00000000000..90ac763a01e --- /dev/null +++ b/doc/ci/review_apps/img/continuous-delivery-review-apps.svg @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg width="1170px" height="638px" viewBox="0 0 1170 638" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <!-- Generator: Sketch 41 (35326) - http://www.bohemiancoding.com/sketch --> + <title>review-apps-CD-outlined</title> + <desc>Created with Sketch.</desc> + <defs></defs> + <g id="Page-2" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> + <g id="review-apps-CD-outlined"> + <g id="Group-4-Copy" transform="translate(22.000000, 43.000000)"> + <polygon id="Line-Copy-25" fill="#E0513E" points="163.545966 259 858.690432 259 858.690432 255 163.545966 255"></polygon> + <path d="M870.470919,266.702602 C875.287562,266.702602 879.19137,262.80085 879.19137,257.988848 C879.19137,253.176845 875.287562,249.275093 870.470919,249.275093 C865.654276,249.275093 861.750469,253.176845 861.750469,257.988848 C861.750469,262.80085 865.654276,266.702602 870.470919,266.702602 Z M870.470919,270.702602 C863.445609,270.702602 857.750469,265.01046 857.750469,257.988848 C857.750469,250.967235 863.445609,245.275093 870.470919,245.275093 C877.49623,245.275093 883.19137,250.967235 883.19137,257.988848 C883.19137,265.01046 877.49623,270.702602 870.470919,270.702602 Z" id="Oval-Copy-20" fill="#E04733"></path> + <path d="M991.315197,145.921933 C996.13184,145.921933 1000.03565,142.020181 1000.03565,137.208178 C1000.03565,132.396176 996.13184,128.494424 991.315197,128.494424 C986.498554,128.494424 982.594747,132.396176 982.594747,137.208178 C982.594747,142.020181 986.498554,145.921933 991.315197,145.921933 Z M991.315197,149.921933 C984.289886,149.921933 978.594747,144.229791 978.594747,137.208178 C978.594747,130.186566 984.289886,124.494424 991.315197,124.494424 C998.340508,124.494424 1004.03565,130.186566 1004.03565,137.208178 C1004.03565,144.229791 998.340508,149.921933 991.315197,149.921933 Z" id="Oval-Copy-22" fill="#E04733"></path> + <g id="Group-7" transform="translate(0.000000, 236.799257)" fill="#E04733"> + <path d="M151.765478,29.9033457 C156.582121,29.9033457 160.485929,26.0015933 160.485929,21.1895911 C160.485929,16.3775889 156.582121,12.4758364 151.765478,12.4758364 C146.948835,12.4758364 143.045028,16.3775889 143.045028,21.1895911 C143.045028,26.0015933 146.948835,29.9033457 151.765478,29.9033457 Z M151.765478,33.9033457 C144.740168,33.9033457 139.045028,28.2112039 139.045028,21.1895911 C139.045028,14.1679783 144.740168,8.47583643 151.765478,8.47583643 C158.790789,8.47583643 164.485929,14.1679783 164.485929,21.1895911 C164.485929,28.2112039 158.790789,33.9033457 151.765478,33.9033457 Z" id="Oval-Copy-10"></path> + <path d="M0.187705647,10.1392011 L3.30410548,10.1392011 L7.34270526,21.3328005 L8.86910518,25.5940003 L8.99630517,25.5940003 L10.4591051,21.3328005 L14.4659049,10.1392011 L17.5823047,10.1392011 L17.5823047,31 L15.0701048,31 L15.0701048,19.5202006 C15.0701048,18.587396 15.1072045,17.5592063 15.1814048,16.4356008 C15.2556052,15.3119952 15.3351044,14.2838056 15.4199048,13.351001 L15.2927048,13.351001 L13.6073049,17.9938007 L9.60050514,28.9012001 L8.10590522,28.9012001 L4.06730544,17.9938007 L2.41370553,13.351001 L2.28650553,13.351001 C2.35010585,14.2838056 2.4243051,15.3119952 2.50910552,16.4356008 C2.59390594,17.5592063 2.63630552,18.587396 2.63630552,19.5202006 L2.63630552,31 L0.187705647,31 L0.187705647,10.1392011 Z M32.1785039,22.5094005 L31.192704,19.3294006 C30.8111021,18.1633949 30.4507057,17.0027065 30.111504,15.8473008 C29.7723024,14.6918951 29.4331058,13.510007 29.0939041,12.301601 L28.9667041,12.301601 C28.6487025,13.510007 28.3201058,14.6918951 27.9809041,15.8473008 C27.6417025,17.0027065 27.2813061,18.1633949 26.8997042,19.3294006 L25.9139043,22.5094005 L32.1785039,22.5094005 Z M32.8463039,24.6400003 L25.2461043,24.6400003 L23.2427044,31 L20.5397045,31 L27.5993042,10.1392011 L30.588504,10.1392011 L37.6481036,31 L34.8179038,31 L32.8463039,24.6400003 Z M40.6691035,26.4526002 C41.4111071,27.2370041 42.2855983,27.8676978 43.2926033,28.3447001 C44.2996083,28.8217025 45.3436978,29.0602001 46.4249032,29.0602001 C47.80291,29.0602001 48.8734992,28.7475032 49.636703,28.1221002 C50.3999068,27.4966971 50.7815029,26.6752053 50.7815029,25.6576003 C50.7815029,25.1275977 50.6914038,24.6771022 50.5112029,24.3061004 C50.331002,23.9350985 50.0872045,23.6171017 49.779803,23.3521004 C49.4724014,23.0870991 49.1067051,22.8486015 48.682703,22.6366005 C48.2587009,22.4245994 47.8029055,22.2020016 47.3153031,21.9688005 L44.3261033,20.6650006 C43.8385009,20.4529995 43.3403059,20.1986021 42.8315033,19.9018006 C42.3227008,19.6049991 41.8669054,19.2446028 41.4641034,18.8206007 C41.0613014,18.3965986 40.7327047,17.8931036 40.4783035,17.3101007 C40.2239022,16.7270979 40.0967035,16.0540046 40.0967035,15.2908008 C40.0967035,14.506397 40.2610018,13.7750043 40.5896035,13.096601 C40.9182051,12.4181976 41.3740005,11.8299035 41.9570034,11.3317011 C42.5400063,10.8334986 43.2289993,10.4466025 44.0240033,10.1710011 C44.8190072,9.89539976 45.6934984,9.75760115 46.6475031,9.75760115 C47.8983093,9.75760115 49.0536977,9.99609875 50.113703,10.4731011 C51.1737082,10.9501035 52.0746991,11.5701972 52.8167028,12.333401 L51.3857029,14.0506009 C50.7496997,13.4357979 50.0448068,12.9535027 49.271003,12.603701 C48.4971992,12.2538993 47.622708,12.079001 46.6475031,12.079001 C45.4814974,12.079001 44.5434068,12.3492983 43.8332033,12.889901 C43.1229998,13.4305037 42.7679033,14.1777961 42.7679033,15.1318009 C42.7679033,15.6406034 42.8686023,16.0698991 43.0700033,16.4197008 C43.2714043,16.7695025 43.5417016,17.0768994 43.8809033,17.3419007 C44.220105,17.606902 44.5911012,17.8400997 44.9939032,18.0415007 C45.3967052,18.2429017 45.8101011,18.4283998 46.2341032,18.5980007 L49.191503,19.8700006 C49.7851059,20.1244019 50.3469003,20.4158989 50.8769029,20.7445006 C51.4069055,21.0731022 51.8627009,21.4546983 52.2443028,21.8893005 C52.6259047,22.3239026 52.9280017,22.8326975 53.1506028,23.4157004 C53.3732039,23.9987033 53.4845028,24.6717965 53.4845028,25.4350003 C53.4845028,26.2618044 53.3202044,27.0355966 52.9916028,27.7564002 C52.6630012,28.4772037 52.1913059,29.1078974 51.5765029,29.6485001 C50.9616998,30.1891027 50.2197073,30.6130985 49.350503,30.9205 C48.4812987,31.2279015 47.4955086,31.3816 46.3931032,31.3816 C44.9302959,31.3816 43.5735096,31.1060028 42.3227034,30.5548 C41.0718972,30.0035973 39.9907081,29.2510049 39.0791035,28.2970001 L40.6691035,26.4526002 Z M61.9115023,12.365201 L55.6151027,12.365201 L55.6151027,10.1392011 L70.8791018,10.1392011 L70.8791018,12.365201 L64.5827022,12.365201 L64.5827022,31 L61.9115023,31 L61.9115023,12.365201 Z M74.6315016,10.1392011 L86.651901,10.1392011 L86.651901,12.365201 L77.2709015,12.365201 L77.2709015,18.9160007 L85.1891011,18.9160007 L85.1891011,21.1738005 L77.2709015,21.1738005 L77.2709015,28.7422001 L86.969901,28.7422001 L86.969901,31 L74.6315016,31 L74.6315016,10.1392011 Z M94.0295006,20.0290006 L97.5275004,20.0290006 C99.1599085,20.0290006 100.410696,19.6951039 101.2799,19.0273006 C102.149104,18.3594973 102.5837,17.3472075 102.5837,15.9904008 C102.5837,14.612394 102.149104,13.6478037 101.2799,13.096601 C100.410696,12.5453982 99.1599085,12.269801 97.5275004,12.269801 L94.0295006,12.269801 L94.0295006,20.0290006 Z M102.8381,31 L97.8137004,22.1914005 L94.0295006,22.1914005 L94.0295006,31 L91.3901007,31 L91.3901007,10.1392011 L97.9091004,10.1392011 C98.9691056,10.1392011 99.9495958,10.2399001 100.8506,10.4413011 C101.751605,10.6427021 102.525397,10.9765987 103.172,11.4430011 C103.818603,11.9094034 104.322098,12.5135973 104.6825,13.255601 C105.042902,13.9976046 105.2231,14.9091955 105.2231,15.9904008 C105.2231,17.6228089 104.799104,18.9265958 103.9511,19.9018006 C103.103096,20.8770054 101.968907,21.5447987 100.5485,21.9052005 L105.8273,31 L102.8381,31 Z" id="MASTER"></path> + </g> + <path d="M829.454852,142.471188 C830.196855,143.255591 831.071347,143.886285 832.078351,144.363288 C833.085356,144.84029 834.129446,145.078787 835.210651,145.078787 C836.588658,145.078787 837.659247,144.766091 838.422451,144.140688 C839.185655,143.515284 839.567251,142.693793 839.567251,141.676188 C839.567251,141.146185 839.477152,140.69569 839.296951,140.324688 C839.11675,139.953686 838.872953,139.635689 838.565551,139.370688 C838.25815,139.105686 837.892453,138.867189 837.468451,138.655188 C837.044449,138.443187 836.588654,138.220589 836.101051,137.987388 L833.111851,136.683588 C832.624249,136.471587 832.126054,136.217189 831.617252,135.920388 C831.108449,135.623586 830.652654,135.26319 830.249852,134.839188 C829.84705,134.415186 829.518453,133.911691 829.264052,133.328688 C829.00965,132.745685 828.882452,132.072592 828.882452,131.309388 C828.882452,130.524984 829.04675,129.793592 829.375352,129.115188 C829.703953,128.436785 830.159749,127.848491 830.742752,127.350288 C831.325754,126.852086 832.014748,126.46519 832.809751,126.189588 C833.604755,125.913987 834.479247,125.776189 835.433251,125.776189 C836.684057,125.776189 837.839446,126.014686 838.899451,126.491688 C839.959456,126.968691 840.860447,127.588785 841.602451,128.351988 L840.171451,130.069188 C839.535448,129.454385 838.830555,128.97209 838.056751,128.622288 C837.282947,128.272487 836.408456,128.097588 835.433251,128.097588 C834.267246,128.097588 833.329155,128.367886 832.618951,128.908488 C831.908748,129.449091 831.553652,130.196383 831.553652,131.150388 C831.553652,131.659191 831.654351,132.088486 831.855752,132.438288 C832.057152,132.78809 832.32745,133.095487 832.666651,133.360488 C833.005853,133.625489 833.376849,133.858687 833.779651,134.060088 C834.182453,134.261489 834.595849,134.446987 835.019851,134.616588 L837.977251,135.888588 C838.570854,136.142989 839.132648,136.434486 839.662651,136.763088 C840.192654,137.09169 840.648449,137.473286 841.030051,137.907888 C841.411653,138.34249 841.71375,138.851285 841.936351,139.434288 C842.158952,140.017291 842.270251,140.690384 842.270251,141.453588 C842.270251,142.280392 842.105953,143.054184 841.777351,143.774988 C841.448749,144.495791 840.977054,145.126485 840.362251,145.667087 C839.747448,146.20769 839.005455,146.631686 838.136251,146.939087 C837.267047,147.246489 836.281257,147.400187 835.178851,147.400187 C833.716044,147.400187 832.359258,147.12459 831.108452,146.573387 C829.857645,146.022185 828.776456,145.269592 827.864852,144.315588 L829.454852,142.471188 Z M850.69725,128.383788 L844.400851,128.383788 L844.400851,126.157788 L859.66485,126.157788 L859.66485,128.383788 L853.36845,128.383788 L853.36845,147.018587 L850.69725,147.018587 L850.69725,128.383788 Z M872.289449,138.527988 L871.303649,135.347988 C870.922047,134.181982 870.561651,133.021294 870.222449,131.865888 C869.883248,130.710482 869.544051,129.528594 869.204849,128.320188 L869.077649,128.320188 C868.759648,129.528594 868.431051,130.710482 868.09185,131.865888 C867.752648,133.021294 867.392251,134.181982 867.01065,135.347988 L866.02485,138.527988 L872.289449,138.527988 Z M872.957249,140.658588 L865.35705,140.658588 L863.35365,147.018587 L860.65065,147.018587 L867.71025,126.157788 L870.699449,126.157788 L877.759049,147.018587 L874.928849,147.018587 L872.957249,140.658588 Z M879.508049,136.588188 C879.508049,134.91338 879.746547,133.408195 880.223549,132.072588 C880.700551,130.736982 881.368345,129.602793 882.226949,128.669988 C883.085553,127.737184 884.097843,127.021691 885.263849,126.523488 C886.429854,126.025286 887.712441,125.776189 889.111648,125.776189 C890.553256,125.776189 891.756343,126.046486 892.720948,126.587088 C893.685553,127.127691 894.475245,127.715985 895.090048,128.351988 L893.595448,130.037388 C893.065446,129.486186 892.455952,129.02509 891.766948,128.654088 C891.077945,128.283087 890.203454,128.097588 889.143448,128.097588 C888.083443,128.097588 887.129453,128.293686 886.281449,128.685888 C885.433444,129.07809 884.712652,129.639885 884.119049,130.371288 C883.525446,131.102692 883.06435,131.987783 882.735749,133.026588 C882.407147,134.065393 882.242849,135.231382 882.242849,136.524588 C882.242849,137.838994 882.396547,139.020883 882.703949,140.070288 C883.01135,141.119693 883.456546,142.015384 884.039549,142.757388 C884.622552,143.499391 885.343344,144.071786 886.201949,144.474587 C887.060553,144.877389 888.051643,145.078787 889.175248,145.078787 C889.917252,145.078787 890.622145,144.967489 891.289948,144.744887 C891.957752,144.522286 892.503646,144.220189 892.927648,143.838588 L892.927648,138.400788 L888.507448,138.400788 L888.507448,136.206588 L895.344448,136.206588 L895.344448,144.983387 C894.666045,145.682991 893.770354,146.260685 892.657348,146.716487 C891.544343,147.17229 890.288255,147.400187 888.889048,147.400187 C887.511042,147.400187 886.249654,147.15639 885.104849,146.668787 C883.960043,146.181185 882.974253,145.476292 882.147449,144.554087 C881.320645,143.631883 880.674051,142.497694 880.207649,141.151488 C879.741247,139.805281 879.508049,138.284196 879.508049,136.588188 Z M900.337048,126.157788 L902.976448,126.157788 L902.976448,147.018587 L900.337048,147.018587 L900.337048,126.157788 Z M908.700447,126.157788 L911.435247,126.157788 L918.971847,139.259388 L921.229647,143.584188 L921.356847,143.584188 C921.293246,142.524182 921.224347,141.427093 921.150147,140.292888 C921.075946,139.158682 921.038847,138.040393 921.038847,136.937988 L921.038847,126.157788 L923.551047,126.157788 L923.551047,147.018587 L920.816247,147.018587 L913.247847,133.885188 L910.990047,129.592188 L910.862847,129.592188 C910.947648,130.652194 911.027147,131.728083 911.101347,132.819888 C911.175548,133.911694 911.212647,135.008782 911.212647,136.111188 L911.212647,147.018587 L908.700447,147.018587 L908.700447,126.157788 Z M928.066646,136.588188 C928.066646,134.91338 928.305144,133.408195 928.782146,132.072588 C929.259149,130.736982 929.926942,129.602793 930.785546,128.669988 C931.64415,127.737184 932.65644,127.021691 933.822446,126.523488 C934.988452,126.025286 936.271039,125.776189 937.670246,125.776189 C939.111853,125.776189 940.314941,126.046486 941.279546,126.587088 C942.24415,127.127691 943.033842,127.715985 943.648645,128.351988 L942.154046,130.037388 C941.624043,129.486186 941.014549,129.02509 940.325546,128.654088 C939.636542,128.283087 938.762051,128.097588 937.702046,128.097588 C936.642041,128.097588 935.68805,128.293686 934.840046,128.685888 C933.992042,129.07809 933.271249,129.639885 932.677646,130.371288 C932.084043,131.102692 931.622948,131.987783 931.294346,133.026588 C930.965745,134.065393 930.801446,135.231382 930.801446,136.524588 C930.801446,137.838994 930.955145,139.020883 931.262546,140.070288 C931.569948,141.119693 932.015143,142.015384 932.598146,142.757388 C933.181149,143.499391 933.901942,144.071786 934.760546,144.474587 C935.61915,144.877389 936.61024,145.078787 937.733846,145.078787 C938.475849,145.078787 939.180742,144.967489 939.848546,144.744887 C940.516349,144.522286 941.062243,144.220189 941.486246,143.838588 L941.486246,138.400788 L937.066046,138.400788 L937.066046,136.206588 L943.903045,136.206588 L943.903045,144.983387 C943.224642,145.682991 942.328951,146.260685 941.215946,146.716487 C940.10294,147.17229 938.846853,147.400187 937.447646,147.400187 C936.069639,147.400187 934.808252,147.15639 933.663446,146.668787 C932.51864,146.181185 931.53285,145.476292 930.706046,144.554087 C929.879242,143.631883 929.232649,142.497694 928.766246,141.151488 C928.299844,139.805281 928.066646,138.284196 928.066646,136.588188 Z" id="STAGING" fill="#E04733"></path> + <path d="M888.668416,1.13920113 L895.060216,1.13920113 C896.205021,1.13920113 897.254411,1.24520006 898.208415,1.45720111 C899.16242,1.66920216 899.973312,2.01369869 900.641115,2.49070105 C901.308919,2.96770341 901.828313,3.59839707 902.199315,4.38280095 C902.570317,5.16720483 902.755815,6.13179513 902.755815,7.27660079 C902.755815,8.37900625 902.570317,9.33299666 902.199315,10.1386006 C901.828313,10.9442046 901.303619,11.6119979 900.625215,12.1420005 C899.946812,12.6720032 899.13592,13.0694992 898.192515,13.3345005 C897.249111,13.5995018 896.205021,13.7320004 895.060216,13.7320004 L891.307816,13.7320004 L891.307816,22 L888.668416,22 L888.668416,1.13920113 Z M894.742216,11.5696006 C896.565425,11.5696006 897.916911,11.225104 898.796715,10.5361006 C899.67652,9.84709721 900.116415,8.76060813 900.116415,7.27660079 C900.116415,5.77139335 899.67122,4.72730385 898.780815,4.14430096 C897.890411,3.56129808 896.544224,3.26980101 894.742216,3.26980101 L891.307816,3.26980101 L891.307816,11.5696006 L894.742216,11.5696006 Z M909.624615,11.0290006 L913.122615,11.0290006 C914.755023,11.0290006 916.00581,10.6951039 916.875014,10.0273006 C917.744219,9.35949734 918.178814,8.34720752 918.178814,6.99040081 C918.178814,5.61239399 917.744219,4.64780369 916.875014,4.09660097 C916.00581,3.54539824 914.755023,3.26980101 913.122615,3.26980101 L909.624615,3.26980101 L909.624615,11.0290006 Z M918.433214,22 L913.408815,13.1914005 L909.624615,13.1914005 L909.624615,22 L906.985215,22 L906.985215,1.13920113 L913.504215,1.13920113 C914.56422,1.13920113 915.54471,1.23990011 916.445714,1.44130111 C917.346719,1.64270211 918.120511,1.97659875 918.767114,2.44300106 C919.413717,2.90940336 919.917212,3.51359729 920.277614,4.25560096 C920.638016,4.99760463 920.818214,5.90919546 920.818214,6.99040081 C920.818214,8.62280888 920.394218,9.92659578 919.546214,10.9018006 C918.69821,11.8770054 917.564021,12.5447987 916.143614,12.9052005 L921.422414,22 L918.433214,22 Z M933.156613,22.3816 C931.842207,22.3816 930.639119,22.1272025 929.547314,21.6184 C928.455508,21.1095975 927.517418,20.3835048 926.733014,19.4401001 C925.94861,18.4966955 925.339116,17.351907 924.904514,16.0057003 C924.469912,14.6594937 924.252614,13.1490089 924.252614,11.4742006 C924.252614,9.79939228 924.469912,8.29950736 924.904514,6.97450081 C925.339116,5.64949426 925.94861,4.52590555 926.733014,3.60370099 C927.517418,2.68149643 928.455508,1.97660352 929.547314,1.48900111 C930.639119,1.0013987 931.842207,0.757601147 933.156613,0.757601147 C934.47102,0.757601147 935.674108,1.00669864 936.765913,1.50490111 C937.857719,2.00310357 938.801109,2.71329643 939.596113,3.63550099 C940.391117,4.55770555 941.005911,5.68129426 941.440513,7.00630081 C941.875115,8.33130736 942.092413,9.82059239 942.092413,11.4742006 C942.092413,13.1490089 941.875115,14.6594937 941.440513,16.0057003 C941.005911,17.351907 940.391117,18.4966955 939.596113,19.4401001 C938.801109,20.3835048 937.857719,21.1095975 936.765913,21.6184 C935.674108,22.1272025 934.47102,22.3816 933.156613,22.3816 Z M933.156613,20.0602001 C934.089418,20.0602001 934.93211,19.8588021 935.684713,19.4560001 C936.437317,19.0531981 937.083911,18.475504 937.624513,17.7229002 C938.165116,16.9702965 938.583812,16.0693056 938.880613,15.0199004 C939.177415,13.9704952 939.325813,12.7886071 939.325813,11.4742006 C939.325813,10.1809942 939.177415,9.01500589 938.880613,7.97620076 C938.583812,6.93739562 938.165116,6.05760446 937.624513,5.3368009 C937.083911,4.61599733 936.437317,4.05950293 935.684713,3.66730099 C934.93211,3.27509905 934.089418,3.07900102 933.156613,3.07900102 C932.223809,3.07900102 931.381117,3.27509905 930.628514,3.66730099 C929.87591,4.05950293 929.229316,4.61599733 928.688714,5.3368009 C928.148111,6.05760446 927.729415,6.93739562 927.432614,7.97620076 C927.135812,9.01500589 926.987414,10.1809942 926.987414,11.4742006 C926.987414,12.7886071 927.135812,13.9704952 927.432614,15.0199004 C927.729415,16.0693056 928.148111,16.9702965 928.688714,17.7229002 C929.229316,18.475504 929.87591,19.0531981 930.628514,19.4560001 C931.381117,19.8588021 932.223809,20.0602001 933.156613,20.0602001 Z M946.576213,1.13920113 L951.791412,1.13920113 C955.013828,1.13920113 957.462404,2.02959217 959.137212,3.81040098 C960.81202,5.59120979 961.649412,8.14578411 961.649412,11.4742006 C961.649412,13.1278087 961.437414,14.6064939 961.013412,15.9103003 C960.58941,17.2141068 959.964016,18.3164957 959.137212,19.2175002 C958.310408,20.1185046 957.292818,20.8074977 956.084412,21.2845 C954.876006,21.7615024 953.48742,22 951.918612,22 L946.576213,22 L946.576213,1.13920113 Z M951.600612,19.8376001 C954.038625,19.8376001 955.867106,19.1062075 957.086112,17.6434002 C958.305118,16.180593 958.914612,14.1242137 958.914612,11.4742006 C958.914612,8.82418746 958.305118,6.79960782 957.086112,5.4004009 C955.867106,4.00119398 954.038625,3.30160101 951.600612,3.30160101 L949.215613,3.30160101 L949.215613,19.8376001 L951.600612,19.8376001 Z M966.037812,1.13920113 L968.677212,1.13920113 L968.677212,13.4458005 C968.677212,14.6966066 968.80441,15.7459961 969.058812,16.5940003 C969.313213,17.4420045 969.657709,18.1203977 970.092311,18.6292002 C970.526914,19.1380027 971.041008,19.503699 971.634611,19.7263001 C972.228214,19.9489012 972.864208,20.0602001 973.542611,20.0602001 C974.242215,20.0602001 974.888808,19.9489012 975.482411,19.7263001 C976.076014,19.503699 976.595409,19.1380027 977.040611,18.6292002 C977.485813,18.1203977 977.83561,17.4420045 978.090011,16.5940003 C978.344412,15.7459961 978.471611,14.6966066 978.471611,13.4458005 L978.471611,1.13920113 L981.015611,1.13920113 L981.015611,13.3822005 C981.015611,15.0570087 980.824813,16.4667946 980.443211,17.6116002 C980.061609,18.7564059 979.536914,19.6838966 978.869111,20.3941001 C978.201308,21.1043036 977.411616,21.6130985 976.500011,21.9205 C975.588407,22.2279015 974.602617,22.3816 973.542611,22.3816 C972.482606,22.3816 971.491516,22.2279015 970.569311,21.9205 C969.647107,21.6130985 968.852115,21.1043036 968.184312,20.3941001 C967.516508,19.6838966 966.991814,18.7564059 966.610212,17.6116002 C966.22861,16.4667946 966.037812,15.0570087 966.037812,13.3822005 L966.037812,1.13920113 Z M985.435811,11.5696006 C985.435811,9.89479228 985.669008,8.38960741 986.135411,7.05400081 C986.601813,5.7183942 987.248406,4.5842056 988.07521,3.65140099 C988.902015,2.71859638 989.882505,2.00310357 991.01671,1.50490111 C992.150916,1.00669864 993.385804,0.757601147 994.72141,0.757601147 C995.993416,0.757601147 997.106405,1.01729854 998.06041,1.5367011 C999.014415,2.05610367 999.798807,2.65499765 1000.41361,3.33340101 L998.91901,5.01880092 C998.367807,4.42519798 997.758313,3.95350272 997.09051,3.60370099 C996.422707,3.25389926 995.643615,3.07900102 994.75321,3.07900102 C993.756805,3.07900102 992.855814,3.27509905 992.05021,3.66730099 C991.244606,4.05950293 990.555613,4.62129728 989.98321,5.3527009 C989.410808,6.08410452 988.965612,6.96919562 988.64761,8.00800076 C988.329609,9.04680589 988.17061,10.2127942 988.17061,11.5060006 C988.17061,12.8204071 988.324309,14.0022952 988.63171,15.0517004 C988.939112,16.1011056 989.368408,16.9967966 989.91961,17.7388002 C990.470813,18.4808039 991.143906,19.0531981 991.93891,19.4560001 C992.733914,19.8588021 993.629605,20.0602001 994.62601,20.0602001 C995.643615,20.0602001 996.528706,19.8588021 997.28131,19.4560001 C998.033914,19.0531981 998.749407,18.4808039 999.42781,17.7388002 L1000.92241,19.3606001 C1000.09561,20.3146049 999.162815,21.0565974 998.12401,21.5866 C997.085205,22.1166026 995.898017,22.3816 994.56241,22.3816 C993.248004,22.3816 992.034316,22.1378024 990.92131,21.6502 C989.808305,21.1625976 988.843715,20.4577047 988.02751,19.5355001 C987.211306,18.6132956 986.575313,17.479107 986.119511,16.1329003 C985.663708,14.7866937 985.435811,13.265609 985.435811,11.5696006 Z M1009.12681,3.36520101 L1002.83041,3.36520101 L1002.83041,1.13920113 L1018.09441,1.13920113 L1018.09441,3.36520101 L1011.79801,3.36520101 L1011.79801,22 L1009.12681,22 L1009.12681,3.36520101 Z M1021.84681,1.13920113 L1024.48621,1.13920113 L1024.48621,22 L1021.84681,22 L1021.84681,1.13920113 Z M1037.90581,22.3816 C1036.5914,22.3816 1035.38831,22.1272025 1034.29651,21.6184 C1033.2047,21.1095975 1032.26661,20.3835048 1031.48221,19.4401001 C1030.6978,18.4966955 1030.08831,17.351907 1029.65371,16.0057003 C1029.21911,14.6594937 1029.00181,13.1490089 1029.00181,11.4742006 C1029.00181,9.79939228 1029.21911,8.29950736 1029.65371,6.97450081 C1030.08831,5.64949426 1030.6978,4.52590555 1031.48221,3.60370099 C1032.26661,2.68149643 1033.2047,1.97660352 1034.29651,1.48900111 C1035.38831,1.0013987 1036.5914,0.757601147 1037.90581,0.757601147 C1039.22021,0.757601147 1040.4233,1.00669864 1041.51511,1.50490111 C1042.60691,2.00310357 1043.5503,2.71329643 1044.34531,3.63550099 C1045.14031,4.55770555 1045.75511,5.68129426 1046.18971,7.00630081 C1046.62431,8.33130736 1046.84161,9.82059239 1046.84161,11.4742006 C1046.84161,13.1490089 1046.62431,14.6594937 1046.18971,16.0057003 C1045.75511,17.351907 1045.14031,18.4966955 1044.34531,19.4401001 C1043.5503,20.3835048 1042.60691,21.1095975 1041.51511,21.6184 C1040.4233,22.1272025 1039.22021,22.3816 1037.90581,22.3816 Z M1037.90581,20.0602001 C1038.83861,20.0602001 1039.6813,19.8588021 1040.43391,19.4560001 C1041.18651,19.0531981 1041.8331,18.475504 1042.37371,17.7229002 C1042.91431,16.9702965 1043.33301,16.0693056 1043.62981,15.0199004 C1043.92661,13.9704952 1044.07501,12.7886071 1044.07501,11.4742006 C1044.07501,10.1809942 1043.92661,9.01500589 1043.62981,7.97620076 C1043.33301,6.93739562 1042.91431,6.05760446 1042.37371,5.3368009 C1041.8331,4.61599733 1041.18651,4.05950293 1040.43391,3.66730099 C1039.6813,3.27509905 1038.83861,3.07900102 1037.90581,3.07900102 C1036.973,3.07900102 1036.13031,3.27509905 1035.37771,3.66730099 C1034.6251,4.05950293 1033.97851,4.61599733 1033.43791,5.3368009 C1032.89731,6.05760446 1032.47861,6.93739562 1032.18181,7.97620076 C1031.88501,9.01500589 1031.73661,10.1809942 1031.73661,11.4742006 C1031.73661,12.7886071 1031.88501,13.9704952 1032.18181,15.0199004 C1032.47861,16.0693056 1032.89731,16.9702965 1033.43791,17.7229002 C1033.97851,18.475504 1034.6251,19.0531981 1035.37771,19.4560001 C1036.13031,19.8588021 1036.973,20.0602001 1037.90581,20.0602001 Z M1051.32541,1.13920113 L1054.06021,1.13920113 L1061.59681,14.2408004 L1063.85461,18.5656002 L1063.98181,18.5656002 C1063.91821,17.5055949 1063.84931,16.408506 1063.77511,15.2743004 C1063.70091,14.1400948 1063.66381,13.021806 1063.66381,11.9194005 L1063.66381,1.13920113 L1066.17601,1.13920113 L1066.17601,22 L1063.44121,22 L1055.87281,8.86660071 L1053.61501,4.57360094 L1053.48781,4.57360094 C1053.57261,5.63360618 1053.65211,6.70949537 1053.72631,7.80130077 C1053.80051,8.89310617 1053.83761,9.99019514 1053.83761,11.0926006 L1053.83761,22 L1051.32541,22 L1051.32541,1.13920113 Z" id="PRODUCTION-Copy-2" fill="#E04733"></path> + <polygon id="Line-Copy-17" fill="#E0513E" points="282.270169 382 498.277674 382 498.277674 378 282.270169 378"></polygon> + <path d="M277.201592,391.484016 L283.029685,397.309042 L285.857368,394.47987 L280.029274,388.654844 L277.201592,391.484016 Z M286.198357,400.476046 L292.02645,406.301071 L294.854133,403.4719 L289.026039,397.646874 L286.198357,400.476046 Z M295.195122,409.468075 L301.023216,415.293101 L303.850898,412.463929 L298.022805,406.638904 L295.195122,409.468075 Z M304.191888,418.460105 L310.019981,424.285131 L312.847663,421.455959 L307.01957,415.630933 L304.191888,418.460105 Z M313.188653,427.452135 L319.016746,433.27716 L321.844429,430.447989 L316.016335,424.622963 L313.188653,427.452135 Z M322.185418,436.444164 L328.013511,442.26919 L330.841194,439.440018 L325.0131,433.614993 L322.185418,436.444164 Z M331.182183,445.436194 L337.010277,451.26122 L339.837959,448.432048 L334.009866,442.607022 L331.182183,445.436194 Z M340.178949,454.428224 L346.007042,460.253249 L348.834724,457.424078 L343.006631,451.599052 L340.178949,454.428224 Z M349.175714,463.420253 L355.003807,469.245279 L357.83149,466.416107 L352.003396,460.591082 L349.175714,463.420253 Z M358.172479,472.412283 L364.000572,478.237309 L366.828255,475.408137 L361.000162,469.583111 L358.172479,472.412283 Z M367.169244,481.404313 L372.997338,487.229338 L375.82502,484.400167 L369.996927,478.575141 L367.169244,481.404313 Z M376.16601,490.396342 L381.994103,496.221368 L384.821785,493.392196 L378.993692,487.567171 L376.16601,490.396342 Z" id="Line-Copy-18" fill="#E0513E"></path> + <path d="M516.770072,391.484016 L522.598165,397.309042 L525.425848,394.47987 L519.597754,388.654844 L516.770072,391.484016 Z M525.766837,400.476046 L531.594931,406.301071 L534.422613,403.4719 L528.59452,397.646874 L525.766837,400.476046 Z M534.763603,409.468075 L540.591696,415.293101 L543.419378,412.463929 L537.591285,406.638904 L534.763603,409.468075 Z M543.760368,418.460105 L549.588461,424.285131 L552.416144,421.455959 L546.58805,415.630933 L543.760368,418.460105 Z M552.757133,427.452135 L558.585226,433.27716 L561.412909,430.447989 L555.584816,424.622963 L552.757133,427.452135 Z M561.753898,436.444164 L567.581992,442.26919 L570.409674,439.440018 L564.581581,433.614993 L561.753898,436.444164 Z M570.750664,445.436194 L576.578757,451.26122 L579.406439,448.432048 L573.578346,442.607022 L570.750664,445.436194 Z M579.747429,454.428224 L585.575522,460.253249 L588.403205,457.424078 L582.575111,451.599052 L579.747429,454.428224 Z M588.744194,463.420253 L594.572288,469.245279 L597.39997,466.416107 L591.571877,460.591082 L588.744194,463.420253 Z M597.740959,472.412283 L603.569053,478.237309 L606.396735,475.408137 L600.568642,469.583111 L597.740959,472.412283 Z M606.737725,481.404313 L612.565818,487.229338 L615.3935,484.400167 L609.565407,478.575141 L606.737725,481.404313 Z M615.73449,490.396342 L621.562583,496.221368 L624.390266,493.392196 L618.562172,487.567171 L615.73449,490.396342 Z" id="Line-Copy-22" fill="#E0513E"></path> + <path d="M756.338552,391.484016 L762.166646,397.309042 L764.994328,394.47987 L759.166235,388.654844 L756.338552,391.484016 Z M765.335318,400.476046 L771.163411,406.301071 L773.991093,403.4719 L768.163,397.646874 L765.335318,400.476046 Z M774.332083,409.468075 L780.160176,415.293101 L782.987859,412.463929 L777.159765,406.638904 L774.332083,409.468075 Z M783.328848,418.460105 L789.156941,424.285131 L791.984624,421.455959 L786.156531,415.630933 L783.328848,418.460105 Z M792.325613,427.452135 L798.153707,433.27716 L800.981389,430.447989 L795.153296,424.622963 L792.325613,427.452135 Z M801.322379,436.444164 L807.150472,442.26919 L809.978154,439.440018 L804.150061,433.614993 L801.322379,436.444164 Z M810.319144,445.436194 L816.147237,451.26122 L818.97492,448.432048 L813.146826,442.607022 L810.319144,445.436194 Z M819.315909,454.428224 L825.144003,460.253249 L827.971685,457.424078 L822.143592,451.599052 L819.315909,454.428224 Z M828.312674,463.420253 L834.140768,469.245279 L836.96845,466.416107 L831.140357,460.591082 L828.312674,463.420253 Z M837.30944,472.412283 L843.137533,478.237309 L845.965216,475.408137 L840.137122,469.583111 L837.30944,472.412283 Z M846.306205,481.404313 L852.134298,487.229338 L854.961981,484.400167 L849.133887,478.575141 L846.306205,481.404313 Z M855.30297,490.396342 L861.131064,496.221368 L863.958746,493.392196 L858.130653,487.567171 L855.30297,490.396342 Z" id="Line-Copy-23" fill="#E0513E"></path> + <path d="M880.010512,252.341438 L885.838606,246.516413 L883.010923,243.687241 L877.18283,249.512267 L880.010512,252.341438 Z M889.007278,243.349409 L894.835371,237.524383 L892.007689,234.695211 L886.179595,240.520237 L889.007278,243.349409 Z M898.004043,234.357379 L903.832136,228.532353 L901.004454,225.703182 L895.176361,231.528207 L898.004043,234.357379 Z M907.000808,225.365349 L912.828902,219.540324 L910.001219,216.711152 L904.173126,222.536178 L907.000808,225.365349 Z M915.997573,216.37332 L921.825667,210.548294 L918.997984,207.719122 L913.169891,213.544148 L915.997573,216.37332 Z M924.994339,207.38129 L930.822432,201.556264 L927.99475,198.727093 L922.166656,204.552118 L924.994339,207.38129 Z M933.991104,198.38926 L939.819197,192.564235 L936.991515,189.735063 L931.163422,195.560089 L933.991104,198.38926 Z M942.987869,189.397231 L948.815963,183.572205 L945.98828,180.743033 L940.160187,186.568059 L942.987869,189.397231 Z M951.984635,180.405201 L957.812728,174.580175 L954.985045,171.751004 L949.156952,177.576029 L951.984635,180.405201 Z M960.9814,171.413171 L966.809493,165.588146 L963.981811,162.758974 L958.153717,168.584 L960.9814,171.413171 Z M969.978165,162.421142 L975.806258,156.596116 L972.978576,153.766944 L967.150483,159.59197 L969.978165,162.421142 Z M978.97493,153.429112 L984.803024,147.604086 L981.975341,144.774915 L976.147248,150.59994 L978.97493,153.429112 Z" id="Line-Copy-27" fill="#E0513E"></path> + <path d="M1114.27955,23.0223048 C1119.09619,23.0223048 1123,19.1205524 1123,14.3085502 C1123,9.49654797 1119.09619,5.59479554 1114.27955,5.59479554 C1109.46291,5.59479554 1105.5591,9.49654797 1105.5591,14.3085502 C1105.5591,19.1205524 1109.46291,23.0223048 1114.27955,23.0223048 Z M1114.27955,27.0223048 C1107.25424,27.0223048 1101.5591,21.330163 1101.5591,14.3085502 C1101.5591,7.28693738 1107.25424,1.59479554 1114.27955,1.59479554 C1121.30486,1.59479554 1127,7.28693738 1127,14.3085502 C1127,21.330163 1121.30486,27.0223048 1114.27955,27.0223048 Z" id="Oval-Copy-24" fill="#E04733"></path> + <polygon id="Line" fill="#E04733" points="758.424239 374.304508 864.800215 266.404117 861.951738 263.595883 755.575761 371.496274"></polygon> + <polygon id="Line-Copy" fill="#E04733" points="1000.57718 131.539201 1109.53226 24.6788494 1106.73141 21.8231038 997.776337 128.683455"></polygon> + <path d="M510.058161,389.60223 C514.874804,389.60223 518.778612,385.700478 518.778612,380.888476 C518.778612,376.076474 514.874804,372.174721 510.058161,372.174721 C505.241518,372.174721 501.337711,376.076474 501.337711,380.888476 C501.337711,385.700478 505.241518,389.60223 510.058161,389.60223 Z M510.058161,393.60223 C503.032851,393.60223 497.337711,387.910089 497.337711,380.888476 C497.337711,373.866863 503.032851,368.174721 510.058161,368.174721 C517.083472,368.174721 522.778612,373.866863 522.778612,380.888476 C522.778612,387.910089 517.083472,393.60223 510.058161,393.60223 Z" id="Oval-Copy-15" fill="#E04733"></path> + <polygon id="Line-Copy-19" fill="#E0513E" points="521.838649 382 737.846154 382 737.846154 378 521.838649 378"></polygon> + <path d="M749.626642,389.60223 C754.443285,389.60223 758.347092,385.700478 758.347092,380.888476 C758.347092,376.076474 754.443285,372.174721 749.626642,372.174721 C744.809999,372.174721 740.906191,376.076474 740.906191,380.888476 C740.906191,385.700478 744.809999,389.60223 749.626642,389.60223 Z M749.626642,393.60223 C742.601331,393.60223 736.906191,387.910089 736.906191,380.888476 C736.906191,373.866863 742.601331,368.174721 749.626642,368.174721 C756.651952,368.174721 762.347092,373.866863 762.347092,380.888476 C762.347092,387.910089 756.651952,393.60223 749.626642,393.60223 Z" id="Oval-Copy-16" fill="#E04733"></path> + <path d="M270.489681,389.60223 C275.306324,389.60223 279.210131,385.700478 279.210131,380.888476 C279.210131,376.076474 275.306324,372.174721 270.489681,372.174721 C265.673038,372.174721 261.769231,376.076474 261.769231,380.888476 C261.769231,385.700478 265.673038,389.60223 270.489681,389.60223 Z M270.489681,393.60223 C263.46437,393.60223 257.769231,387.910089 257.769231,380.888476 C257.769231,373.866863 263.46437,368.174721 270.489681,368.174721 C277.514992,368.174721 283.210131,373.866863 283.210131,380.888476 C283.210131,387.910089 277.514992,393.60223 270.489681,393.60223 Z" id="Oval-Copy-14" fill="#E04733"></path> + <path d="M630.902439,510.3829 C635.719082,510.3829 639.622889,506.481147 639.622889,501.669145 C639.622889,496.857143 635.719082,492.95539 630.902439,492.95539 C626.085796,492.95539 622.181989,496.857143 622.181989,501.669145 C622.181989,506.481147 626.085796,510.3829 630.902439,510.3829 Z M630.902439,514.3829 C623.877128,514.3829 618.181989,508.690758 618.181989,501.669145 C618.181989,494.647532 623.877128,488.95539 630.902439,488.95539 C637.92775,488.95539 643.622889,494.647532 643.622889,501.669145 C643.622889,508.690758 637.92775,514.3829 630.902439,514.3829 Z" id="Oval-Copy-19" fill="#E04733"></path> + <path d="M870.470919,510.3829 C875.287562,510.3829 879.19137,506.481147 879.19137,501.669145 C879.19137,496.857143 875.287562,492.95539 870.470919,492.95539 C865.654276,492.95539 861.750469,496.857143 861.750469,501.669145 C861.750469,506.481147 865.654276,510.3829 870.470919,510.3829 Z M870.470919,514.3829 C863.445609,514.3829 857.750469,508.690758 857.750469,501.669145 C857.750469,494.647532 863.445609,488.95539 870.470919,488.95539 C877.49623,488.95539 883.19137,494.647532 883.19137,501.669145 C883.19137,508.690758 877.49623,514.3829 870.470919,514.3829 Z" id="Oval-Copy-18" fill="#E04733"></path> + <path d="M391.333959,510.3829 C396.150602,510.3829 400.054409,506.481147 400.054409,501.669145 C400.054409,496.857143 396.150602,492.95539 391.333959,492.95539 C386.517316,492.95539 382.613508,496.857143 382.613508,501.669145 C382.613508,506.481147 386.517316,510.3829 391.333959,510.3829 Z M391.333959,514.3829 C384.308648,514.3829 378.613508,508.690758 378.613508,501.669145 C378.613508,494.647532 384.308648,488.95539 391.333959,488.95539 C398.359269,488.95539 404.054409,494.647532 404.054409,501.669145 C404.054409,508.690758 398.359269,514.3829 391.333959,514.3829 Z" id="Oval-Copy-17" fill="#E04733"></path> + <path d="M28.833894,372.064086 L22.5374943,372.064086 L22.5374943,369.838086 L37.8014935,369.838086 L37.8014935,372.064086 L31.5050938,372.064086 L31.5050938,390.698885 L28.833894,390.698885 L28.833894,372.064086 Z M49.2494929,391.080485 C47.9350864,391.080485 46.7319985,390.826087 45.6401931,390.317285 C44.5483877,389.808482 43.6102971,389.08239 42.8258932,388.138985 C42.0414893,387.19558 41.4319955,386.050792 40.9973933,384.704585 C40.5627912,383.358378 40.3454934,381.847894 40.3454934,380.173085 C40.3454934,378.498277 40.5627912,376.998392 40.9973933,375.673386 C41.4319955,374.348379 42.0414893,373.22479 42.8258932,372.302586 C43.6102971,371.380381 44.5483877,370.675488 45.6401931,370.187886 C46.7319985,369.700283 47.9350864,369.456486 49.2494929,369.456486 C50.5638994,369.456486 51.7669873,369.705583 52.8587927,370.203786 C53.9505981,370.701988 54.8939886,371.412181 55.6889925,372.334386 C56.4839965,373.25659 57.0987903,374.380179 57.5333924,375.705186 C57.9679946,377.030192 58.1852924,378.519477 58.1852924,380.173085 C58.1852924,381.847894 57.9679946,383.358378 57.5333924,384.704585 C57.0987903,386.050792 56.4839965,387.19558 55.6889925,388.138985 C54.8939886,389.08239 53.9505981,389.808482 52.8587927,390.317285 C51.7669873,390.826087 50.5638994,391.080485 49.2494929,391.080485 Z M49.2494929,388.759085 C50.1822975,388.759085 51.024989,388.557687 51.7775927,388.154885 C52.5301965,387.752083 53.17679,387.174389 53.7173926,386.421785 C54.2579953,385.669181 54.6766911,384.76819 54.9734926,383.718785 C55.270294,382.66938 55.4186925,381.487492 55.4186925,380.173085 C55.4186925,378.879879 55.270294,377.713891 54.9734926,376.675086 C54.6766911,375.63628 54.2579953,374.756489 53.7173926,374.035686 C53.17679,373.314882 52.5301965,372.758388 51.7775927,372.366186 C51.024989,371.973984 50.1822975,371.777886 49.2494929,371.777886 C48.3166883,371.777886 47.4739967,371.973984 46.721393,372.366186 C45.9687893,372.758388 45.3221958,373.314882 44.7815931,374.035686 C44.2409904,374.756489 43.8222947,375.63628 43.5254932,376.675086 C43.2286917,377.713891 43.0802932,378.879879 43.0802932,380.173085 C43.0802932,381.487492 43.2286917,382.66938 43.5254932,383.718785 C43.8222947,384.76819 44.2409904,385.669181 44.7815931,386.421785 C45.3221958,387.174389 45.9687893,387.752083 46.721393,388.154885 C47.4739967,388.557687 48.3166883,388.759085 49.2494929,388.759085 Z M62.6690922,369.838086 L69.0608918,369.838086 C70.2056975,369.838086 71.2550869,369.944085 72.2090916,370.156086 C73.1630964,370.368087 73.9739882,370.712583 74.6417915,371.189586 C75.3095948,371.666588 75.8289896,372.297282 76.1999914,373.081686 C76.5709933,373.86609 76.7564914,374.83068 76.7564914,375.975486 C76.7564914,377.077891 76.5709933,378.031881 76.1999914,378.837485 C75.8289896,379.643089 75.3042949,380.310883 74.6258915,380.840885 C73.9474882,381.370888 73.1365963,381.768384 72.1931916,382.033385 C71.249787,382.298387 70.2056975,382.430885 69.0608918,382.430885 L65.308492,382.430885 L65.308492,390.698885 L62.6690922,390.698885 L62.6690922,369.838086 Z M68.7428918,380.268485 C70.5661008,380.268485 71.9175873,379.923989 72.7973916,379.234985 C73.677196,378.545982 74.1170915,377.459493 74.1170915,375.975486 C74.1170915,374.470278 73.671896,373.426189 72.7814916,372.843186 C71.8910872,372.260183 70.5449007,371.968686 68.7428918,371.968686 L65.308492,371.968686 L65.308492,380.268485 L68.7428918,380.268485 Z M80.9858912,369.838086 L83.625291,369.838086 L83.625291,390.698885 L80.9858912,390.698885 L80.9858912,369.838086 Z M88.1408908,380.268485 C88.1408908,378.593677 88.3740884,377.088492 88.8404907,375.752886 C89.306893,374.417279 89.9534865,373.28309 90.7802906,372.350286 C91.6070947,371.417481 92.5875849,370.701988 93.7217905,370.203786 C94.8559961,369.705583 96.0908837,369.456486 97.4264903,369.456486 C98.6984966,369.456486 99.8114854,369.716183 100.76549,370.235586 C101.719495,370.754988 102.503887,371.353882 103.11869,372.032286 L101.62409,373.717686 C101.072887,373.124083 100.463393,372.652387 99.7955901,372.302586 C99.1277868,371.952784 98.3486947,371.777886 97.4582903,371.777886 C96.4618853,371.777886 95.5608944,371.973984 94.7552904,372.366186 C93.9496864,372.758388 93.2606934,373.320182 92.6882905,374.051586 C92.1158877,374.782989 91.6706922,375.66808 91.3526906,376.706886 C91.034689,377.745691 90.8756906,378.911679 90.8756906,380.204885 C90.8756906,381.519292 91.0293891,382.70118 91.3367906,383.750585 C91.6441921,384.79999 92.0734878,385.695681 92.6246905,386.437685 C93.1758933,387.179689 93.8489865,387.752083 94.6439904,388.154885 C95.4389944,388.557687 96.3346854,388.759085 97.3310903,388.759085 C98.3486953,388.759085 99.2337864,388.557687 99.9863901,388.154885 C100.738994,387.752083 101.454487,387.179689 102.13289,386.437685 L103.62749,388.059485 C102.800686,389.01349 101.867895,389.755482 100.82909,390.285485 C99.790285,390.815487 98.6030969,391.080485 97.2674903,391.080485 C95.9530838,391.080485 94.739396,390.836687 93.6263905,390.349085 C92.513385,389.861482 91.5487947,389.156589 90.7325906,388.234385 C89.9163866,387.31218 89.280393,386.177992 88.8245907,384.831785 C88.3687885,383.485578 88.1408908,381.964494 88.1408908,380.268485 Z M113.930689,369.838086 L120.131689,369.838086 C121.191694,369.838086 122.161585,369.933485 123.041389,370.124286 C123.921193,370.315087 124.673786,370.611884 125.299189,371.014686 C125.924592,371.417488 126.412187,371.942183 126.761989,372.588786 C127.11179,373.235389 127.286689,374.014481 127.286689,374.926086 C127.286689,375.964891 126.989892,376.902981 126.396289,377.740385 C125.802686,378.57779 124.891095,379.155484 123.661489,379.473485 L123.661489,379.600685 C125.187896,379.833887 126.375084,380.363881 127.223089,381.190685 C128.071093,382.017489 128.495089,383.151678 128.495089,384.593285 C128.495089,385.61089 128.304291,386.501281 127.922689,387.264485 C127.541087,388.027689 127.000492,388.663682 126.300889,389.172485 C125.601285,389.681287 124.763894,390.062884 123.788689,390.317285 C122.813484,390.571686 121.742895,390.698885 120.576889,390.698885 L113.930689,390.698885 L113.930689,369.838086 Z M119.654689,378.742085 C121.456698,378.742085 122.744585,378.434688 123.518389,377.819885 C124.292193,377.205082 124.679089,376.314691 124.679089,375.148686 C124.679089,374.00388 124.270993,373.182388 123.454789,372.684186 C122.638585,372.185983 121.414297,371.936886 119.781889,371.936886 L116.570089,371.936886 L116.570089,378.742085 L119.654689,378.742085 Z M120.195289,388.600085 C121.997298,388.600085 123.396484,388.266188 124.392889,387.598385 C125.389294,386.930582 125.887489,385.886492 125.887489,384.466085 C125.887489,383.172879 125.399894,382.224188 124.424689,381.619985 C123.449484,381.015782 122.039698,380.713685 120.195289,380.713685 L116.570089,380.713685 L116.570089,388.600085 L120.195289,388.600085 Z M135.268488,379.727885 L138.766488,379.727885 C140.398896,379.727885 141.649684,379.393989 142.518888,378.726185 C143.388092,378.058382 143.822688,377.046092 143.822688,375.689286 C143.822688,374.311279 143.388092,373.346688 142.518888,372.795486 C141.649684,372.244283 140.398896,371.968686 138.766488,371.968686 L135.268488,371.968686 L135.268488,379.727885 Z M144.077088,390.698885 L139.052688,381.890285 L135.268488,381.890285 L135.268488,390.698885 L132.629088,390.698885 L132.629088,369.838086 L139.148088,369.838086 C140.208093,369.838086 141.188583,369.938785 142.089588,370.140186 C142.990592,370.341587 143.764385,370.675484 144.410988,371.141886 C145.057591,371.608288 145.561086,372.212482 145.921488,372.954486 C146.281889,373.696489 146.462088,374.60808 146.462088,375.689286 C146.462088,377.321694 146.038092,378.625481 145.190088,379.600685 C144.342084,380.57589 143.207895,381.243683 141.787488,381.604085 L147.066288,390.698885 L144.077088,390.698885 Z M159.977087,382.208285 L158.991287,379.028285 C158.609685,377.86228 158.249289,376.701591 157.910087,375.546186 C157.570885,374.39078 157.231689,373.208892 156.892487,372.000486 L156.765287,372.000486 C156.447286,373.208892 156.118689,374.39078 155.779487,375.546186 C155.440285,376.701591 155.079889,377.86228 154.698287,379.028285 L153.712487,382.208285 L159.977087,382.208285 Z M160.644887,384.338885 L153.044687,384.338885 L151.041287,390.698885 L148.338288,390.698885 L155.397887,369.838086 L158.387087,369.838086 L165.446687,390.698885 L162.616487,390.698885 L160.644887,384.338885 Z M168.404086,369.838086 L171.138886,369.838086 L178.675486,382.939685 L180.933286,387.264485 L181.060486,387.264485 C180.996885,386.20448 180.927986,385.107391 180.853786,383.973185 C180.779585,382.83898 180.742486,381.720691 180.742486,380.618285 L180.742486,369.838086 L183.254686,369.838086 L183.254686,390.698885 L180.519886,390.698885 L172.951486,377.565485 L170.693686,373.272486 L170.566486,373.272486 C170.651287,374.332491 170.730786,375.40838 170.804986,376.500186 C170.879187,377.591991 170.916286,378.68908 170.916286,379.791485 L170.916286,390.698885 L168.404086,390.698885 L168.404086,369.838086 Z M187.770285,380.268485 C187.770285,378.593677 188.003483,377.088492 188.469885,375.752886 C188.936288,374.417279 189.582881,373.28309 190.409685,372.350286 C191.236489,371.417481 192.216979,370.701988 193.351185,370.203786 C194.485391,369.705583 195.720278,369.456486 197.055885,369.456486 C198.327891,369.456486 199.44088,369.716183 200.394885,370.235586 C201.348889,370.754988 202.133282,371.353882 202.748085,372.032286 L201.253485,373.717686 C200.702282,373.124083 200.092788,372.652387 199.424985,372.302586 C198.757181,371.952784 197.978089,371.777886 197.087685,371.777886 C196.09128,371.777886 195.190289,371.973984 194.384685,372.366186 C193.579081,372.758388 192.890088,373.320182 192.317685,374.051586 C191.745282,374.782989 191.300087,375.66808 190.982085,376.706886 C190.664084,377.745691 190.505085,378.911679 190.505085,380.204885 C190.505085,381.519292 190.658784,382.70118 190.966185,383.750585 C191.273587,384.79999 191.702882,385.695681 192.254085,386.437685 C192.805288,387.179689 193.478381,387.752083 194.273385,388.154885 C195.068389,388.557687 195.96408,388.759085 196.960485,388.759085 C197.97809,388.759085 198.863181,388.557687 199.615785,388.154885 C200.368388,387.752083 201.083881,387.179689 201.762285,386.437685 L203.256885,388.059485 C202.43008,389.01349 201.49729,389.755482 200.458485,390.285485 C199.41968,390.815487 198.232492,391.080485 196.896885,391.080485 C195.582478,391.080485 194.368791,390.836687 193.255785,390.349085 C192.14278,389.861482 191.178189,389.156589 190.361985,388.234385 C189.545781,387.31218 188.909788,386.177992 188.453985,384.831785 C187.998183,383.485578 187.770285,381.964494 187.770285,380.268485 Z M207.136484,369.838086 L209.775884,369.838086 L209.775884,378.583085 L219.474884,378.583085 L219.474884,369.838086 L222.146084,369.838086 L222.146084,390.698885 L219.474884,390.698885 L219.474884,380.872685 L209.775884,380.872685 L209.775884,390.698885 L207.136484,390.698885 L207.136484,369.838086 Z" id="TOPIC-BRANCH" fill="#E04733"></path> + <path d="M687.15753,304.150354 L690.273929,304.150354 L694.312529,315.343953 L695.838929,319.605153 L695.966129,319.605153 L697.428929,315.343953 L701.435729,304.150354 L704.552129,304.150354 L704.552129,325.011152 L702.039929,325.011152 L702.039929,313.531353 C702.039929,312.598548 702.077028,311.570359 702.151229,310.446753 C702.225429,309.323148 702.304928,308.294958 702.389729,307.362153 L702.262529,307.362153 L700.577129,312.004953 L696.570329,322.912353 L695.075729,322.912353 L691.037129,312.004953 L689.383529,307.362153 L689.256329,307.362153 C689.31993,308.294958 689.394129,309.323148 689.478929,310.446753 C689.56373,311.570359 689.606129,312.598548 689.606129,313.531353 L689.606129,325.011152 L687.15753,325.011152 L687.15753,304.150354 Z M710.276128,304.150354 L722.296528,304.150354 L722.296528,306.376353 L712.915528,306.376353 L712.915528,312.927153 L720.833728,312.927153 L720.833728,315.184953 L712.915528,315.184953 L712.915528,322.753353 L722.614528,322.753353 L722.614528,325.011152 L710.276128,325.011152 L710.276128,304.150354 Z M729.674127,314.040153 L733.172127,314.040153 C734.804535,314.040153 736.055323,313.706256 736.924527,313.038453 C737.793731,312.37065 738.228327,311.35836 738.228327,310.001553 C738.228327,308.623546 737.793731,307.658956 736.924527,307.107753 C736.055323,306.556551 734.804535,306.280953 733.172127,306.280953 L729.674127,306.280953 L729.674127,314.040153 Z M738.482727,325.011152 L733.458327,316.202553 L729.674127,316.202553 L729.674127,325.011152 L727.034727,325.011152 L727.034727,304.150354 L733.553727,304.150354 C734.613732,304.150354 735.594222,304.251053 736.495227,304.452454 C737.396231,304.653855 738.170024,304.987751 738.816627,305.454153 C739.46323,305.920556 739.966725,306.52475 740.327127,307.266753 C740.687528,308.008757 740.867727,308.920348 740.867727,310.001553 C740.867727,311.633961 740.443731,312.937748 739.595727,313.912953 C738.747723,314.888158 737.613534,315.555951 736.193127,315.916353 L741.471927,325.011152 L738.482727,325.011152 Z M744.302126,314.580753 C744.302126,312.905945 744.540624,311.40076 745.017626,310.065153 C745.494629,308.729547 746.162422,307.595358 747.021026,306.662553 C747.879631,305.729749 748.89192,305.014256 750.057926,304.516054 C751.223932,304.017851 752.506519,303.768754 753.905726,303.768754 C755.347333,303.768754 756.550421,304.039051 757.515026,304.579654 C758.479631,305.120256 759.269323,305.70855 759.884126,306.344553 L758.389526,308.029953 C757.859523,307.478751 757.250029,307.017655 756.561026,306.646653 C755.872022,306.275652 754.997531,306.090153 753.937526,306.090153 C752.877521,306.090153 751.92353,306.286251 751.075526,306.678453 C750.227522,307.070655 749.506729,307.63245 748.913126,308.363853 C748.319523,309.095257 747.858428,309.980348 747.529826,311.019153 C747.201225,312.057958 747.036926,313.223947 747.036926,314.517153 C747.036926,315.831559 747.190625,317.013448 747.498026,318.062853 C747.805428,319.112258 748.250623,320.007949 748.833626,320.749953 C749.416629,321.491956 750.137422,322.064351 750.996026,322.467153 C751.85463,322.869955 752.84572,323.071353 753.969326,323.071353 C754.71133,323.071353 755.416223,322.960054 756.084026,322.737453 C756.751829,322.514851 757.297724,322.212754 757.721726,321.831153 L757.721726,316.393353 L753.301526,316.393353 L753.301526,314.199153 L760.138526,314.199153 L760.138526,322.975953 C759.460122,323.675556 758.564431,324.25325 757.451426,324.709052 C756.33842,325.164855 755.082333,325.392752 753.683126,325.392752 C752.305119,325.392752 751.043732,325.148955 749.898926,324.661352 C748.754121,324.17375 747.76833,323.468857 746.941526,322.546653 C746.114722,321.624448 745.468129,320.490259 745.001726,319.144053 C744.535324,317.797846 744.302126,316.276761 744.302126,314.580753 Z M765.131125,304.150354 L777.151525,304.150354 L777.151525,306.376353 L767.770525,306.376353 L767.770525,312.927153 L775.688725,312.927153 L775.688725,315.184953 L767.770525,315.184953 L767.770525,322.753353 L777.469525,322.753353 L777.469525,325.011152 L765.131125,325.011152 L765.131125,304.150354 Z" id="MERGE" fill="#E04733"></path> + <path d="M189.429182,500.508554 L192.927182,500.508554 C194.55959,500.508554 195.810377,500.174658 196.679581,499.506855 C197.548786,498.839051 197.983381,497.826761 197.983381,496.469955 C197.983381,495.091948 197.548786,494.127358 196.679581,493.576155 C195.810377,493.024952 194.55959,492.749355 192.927182,492.749355 L189.429182,492.749355 L189.429182,500.508554 Z M198.237781,511.479554 L193.213382,502.670954 L189.429182,502.670954 L189.429182,511.479554 L186.789782,511.479554 L186.789782,490.618755 L193.308782,490.618755 C194.368787,490.618755 195.349277,490.719454 196.250281,490.920855 C197.151286,491.122256 197.925078,491.456153 198.571681,491.922555 C199.218284,492.388957 199.721779,492.993151 200.082181,493.735155 C200.442583,494.477159 200.622781,495.388749 200.622781,496.469955 C200.622781,498.102363 200.198785,499.40615 199.350781,500.381355 C198.502777,501.356559 197.368588,502.024353 195.948181,502.384754 L201.226981,511.479554 L198.237781,511.479554 Z M205.265581,490.618755 L217.28598,490.618755 L217.28598,492.844755 L207.904981,492.844755 L207.904981,499.395555 L215.82318,499.395555 L215.82318,501.653354 L207.904981,501.653354 L207.904981,509.221754 L217.60398,509.221754 L217.60398,511.479554 L205.265581,511.479554 L205.265581,490.618755 Z M219.16218,490.618755 L221.99238,490.618755 L225.33138,501.875954 C225.712982,503.126761 226.046878,504.282149 226.33308,505.342154 C226.619281,506.402159 226.963778,507.546948 227.36658,508.776554 L227.49378,508.776554 C227.875382,507.546948 228.214578,506.402159 228.51138,505.342154 C228.808181,504.282149 229.136778,503.126761 229.49718,501.875954 L232.836179,490.618755 L235.539179,490.618755 L228.92478,511.479554 L225.84018,511.479554 L219.16218,490.618755 Z M238.401179,490.618755 L241.040579,490.618755 L241.040579,511.479554 L238.401179,511.479554 L238.401179,490.618755 Z M246.764579,490.618755 L258.784978,490.618755 L258.784978,492.844755 L249.403978,492.844755 L249.403978,499.395555 L257.322178,499.395555 L257.322178,501.653354 L249.403978,501.653354 L249.403978,509.221754 L259.102978,509.221754 L259.102978,511.479554 L246.764579,511.479554 L246.764579,490.618755 Z M261.392578,490.618755 L264.127378,490.618755 L266.321578,501.971354 C266.512379,503.11616 266.713776,504.239749 266.925778,505.342154 C267.137779,506.44456 267.339177,507.568148 267.529977,508.712954 L267.657177,508.712954 C267.890379,507.568148 268.134176,506.43926 268.388577,505.326254 C268.642979,504.213249 268.886776,503.09496 269.119977,501.971354 L272.013777,490.618755 L274.430577,490.618755 L277.324377,501.971354 C277.578778,503.07376 277.833176,504.186749 278.087577,505.310354 C278.341978,506.43396 278.596376,507.568148 278.850777,508.712954 L278.977977,508.712954 C279.168778,507.568148 279.359576,506.43926 279.550377,505.326254 C279.741178,504.213249 279.942576,503.09496 280.154577,501.971354 L282.348777,490.618755 L284.892777,490.618755 L280.567977,511.479554 L277.387977,511.479554 L274.239777,498.918555 C274.048976,498.112951 273.874078,497.323259 273.715077,496.549455 C273.556076,495.775651 273.391778,494.985959 273.222177,494.180355 L273.094977,494.180355 C272.925376,494.985959 272.750478,495.775651 272.570277,496.549455 C272.390076,497.323259 272.215178,498.112951 272.045577,498.918555 L268.960977,511.479554 L265.812778,511.479554 L261.392578,490.618755 Z M303.813776,502.988954 L302.827976,499.808955 C302.446374,498.642949 302.085977,497.48226 301.746776,496.326855 C301.407574,495.171449 301.068377,493.989561 300.729176,492.781155 L300.601976,492.781155 C300.283974,493.989561 299.955377,495.171449 299.616176,496.326855 C299.276974,497.48226 298.916578,498.642949 298.534976,499.808955 L297.549176,502.988954 L303.813776,502.988954 Z M304.481576,505.119554 L296.881376,505.119554 L294.877976,511.479554 L292.174976,511.479554 L299.234576,490.618755 L302.223776,490.618755 L309.283375,511.479554 L306.453175,511.479554 L304.481576,505.119554 Z M312.240775,490.618755 L318.632575,490.618755 C319.77738,490.618755 320.82677,490.724754 321.780775,490.936755 C322.734779,491.148756 323.545671,491.493253 324.213474,491.970255 C324.881278,492.447257 325.400673,493.077951 325.771674,493.862355 C326.142676,494.646759 326.328174,495.611349 326.328174,496.756155 C326.328174,497.85856 326.142676,498.812551 325.771674,499.618155 C325.400673,500.423759 324.875978,501.091552 324.197574,501.621554 C323.519171,502.151557 322.708279,502.549053 321.764875,502.814054 C320.82147,503.079056 319.77738,503.211554 318.632575,503.211554 L314.880175,503.211554 L314.880175,511.479554 L312.240775,511.479554 L312.240775,490.618755 Z M318.314575,501.049154 C320.137784,501.049154 321.48927,500.704658 322.369075,500.015655 C323.248879,499.326651 323.688774,498.240162 323.688774,496.756155 C323.688774,495.250947 323.243579,494.206858 322.353175,493.623855 C321.46277,493.040852 320.116584,492.749355 318.314575,492.749355 L314.880175,492.749355 L314.880175,501.049154 L318.314575,501.049154 Z M330.557574,490.618755 L336.949374,490.618755 C338.094179,490.618755 339.143569,490.724754 340.097574,490.936755 C341.051578,491.148756 341.86247,491.493253 342.530273,491.970255 C343.198077,492.447257 343.717472,493.077951 344.088473,493.862355 C344.459475,494.646759 344.644973,495.611349 344.644973,496.756155 C344.644973,497.85856 344.459475,498.812551 344.088473,499.618155 C343.717472,500.423759 343.192777,501.091552 342.514373,501.621554 C341.83597,502.151557 341.025078,502.549053 340.081674,502.814054 C339.138269,503.079056 338.094179,503.211554 336.949374,503.211554 L333.196974,503.211554 L333.196974,511.479554 L330.557574,511.479554 L330.557574,490.618755 Z M336.631374,501.049154 C338.454583,501.049154 339.806069,500.704658 340.685874,500.015655 C341.565678,499.326651 342.005573,498.240162 342.005573,496.756155 C342.005573,495.250947 341.560378,494.206858 340.669974,493.623855 C339.779569,493.040852 338.433383,492.749355 336.631374,492.749355 L333.196974,492.749355 L333.196974,501.049154 L336.631374,501.049154 Z" id="REVIEW-APP" fill="#E04733"></path> + <path d="M281.839315,443.148434 C281.839315,441.89441 281.395681,440.823773 280.5084,439.936492 C279.621119,439.049211 278.550482,438.605577 277.296458,438.605577 C276.042434,438.605577 274.971797,439.049211 274.084516,439.936492 C273.197235,440.823773 272.753601,441.89441 272.753601,443.148434 C272.753601,444.402458 273.197235,445.473095 274.084516,446.360376 C274.971797,447.247657 276.042434,447.691291 277.296458,447.691291 C278.550482,447.691291 279.621119,447.247657 280.5084,446.360376 C281.395681,445.473095 281.839315,444.402458 281.839315,443.148434 Z M295.467886,452.234148 C295.467886,451.618966 295.243111,451.086605 294.793555,450.63705 C294.343999,450.187494 293.811639,449.962719 293.196457,449.962719 C292.581275,449.962719 292.048915,450.187494 291.599359,450.63705 C291.149803,451.086605 290.925029,451.618966 290.925029,452.234148 C290.925029,452.86116 291.146846,453.396478 291.590486,453.840119 C292.034127,454.283759 292.569445,454.505576 293.196457,454.505576 C293.823469,454.505576 294.358787,454.283759 294.802428,453.840119 C295.246069,453.396478 295.467886,452.86116 295.467886,452.234148 Z M295.467886,434.06272 C295.467886,433.447539 295.243111,432.915178 294.793555,432.465622 C294.343999,432.016066 293.811639,431.791292 293.196457,431.791292 C292.581275,431.791292 292.048915,432.016066 291.599359,432.465622 C291.149803,432.915178 290.925029,433.447539 290.925029,434.06272 C290.925029,434.689732 291.146846,435.22505 291.590486,435.668691 C292.034127,436.112332 292.569445,436.334149 293.196457,436.334149 C293.823469,436.334149 294.358787,436.112332 294.802428,435.668691 C295.246069,435.22505 295.467886,434.689732 295.467886,434.06272 Z M288.6536,441.53359 L288.6536,444.816514 C288.6536,444.934818 288.612194,445.050163 288.529381,445.162552 C288.446569,445.274941 288.351927,445.33705 288.245453,445.34888 L285.494895,445.774773 C285.36476,446.188838 285.175477,446.638387 284.927038,447.123434 C285.329272,447.691294 285.861633,448.371532 286.524136,449.16417 C286.606949,449.282474 286.648355,449.400777 286.648355,449.519081 C286.648355,449.661046 286.606949,449.773433 286.524136,449.856246 C286.252036,450.211159 285.764039,450.740562 285.060129,451.444471 C284.35622,452.148381 283.891883,452.500331 283.667105,452.500331 C283.53697,452.500331 283.412753,452.458925 283.294449,452.376112 L281.253712,450.779014 C280.815987,451.003792 280.360523,451.18716 279.887306,451.329125 C279.757171,452.60681 279.621124,453.523654 279.479159,454.079683 C279.396346,454.363613 279.218892,454.505576 278.946793,454.505576 L275.646123,454.505576 C275.515989,454.505576 275.397686,454.461213 275.291212,454.372485 C275.184739,454.283757 275.125588,454.180242 275.113757,454.061938 L274.70561,451.346871 C274.303376,451.228567 273.859742,451.045198 273.374695,450.796759 L271.280722,452.376112 C271.197909,452.458925 271.079606,452.500331 270.925811,452.500331 C270.795676,452.500331 270.671459,452.45301 270.553155,452.358367 C268.849575,450.784921 267.997798,449.838502 267.997798,449.519081 C267.997798,449.412607 268.039204,449.30022 268.122016,449.181916 C268.240321,449.01629 268.48284,448.702789 268.849583,448.241402 C269.216326,447.780016 269.494337,447.419194 269.683624,447.158925 C269.411524,446.638387 269.204495,446.153347 269.06253,445.703791 L266.365209,445.277898 C266.246904,445.266068 266.146347,445.209874 266.063534,445.109316 C265.980722,445.008757 265.939316,444.893412 265.939316,444.763278 L265.939316,441.480354 C265.939316,441.36205 265.980722,441.246705 266.063534,441.134316 C266.146347,441.021927 266.240989,440.959818 266.347463,440.947988 L269.098021,440.522095 C269.228155,440.10803 269.417439,439.658481 269.665878,439.173434 C269.263644,438.605574 268.731283,437.925336 268.06878,437.132698 C267.985967,437.002563 267.944561,436.884261 267.944561,436.777787 C267.944561,436.635822 267.985967,436.51752 268.06878,436.422876 C268.329049,436.067964 268.814089,435.541518 269.523914,434.843524 C270.233739,434.145529 270.701033,433.796537 270.925811,433.796537 C271.055946,433.796537 271.180163,433.837943 271.298467,433.920756 L273.339204,435.517854 C273.741438,435.304907 274.196902,435.115623 274.70561,434.949997 C274.835744,433.672312 274.971792,432.761384 275.113757,432.217185 C275.19657,431.933255 275.374024,431.791292 275.646123,431.791292 L278.946793,431.791292 C279.076927,431.791292 279.19523,431.835655 279.301703,431.924383 C279.408177,432.013111 279.467328,432.116626 279.479159,432.23493 L279.887306,434.949997 C280.28954,435.068301 280.733174,435.25167 281.218221,435.500108 L283.312194,433.920756 C283.406838,433.837943 283.52514,433.796537 283.667105,433.796537 C283.797239,433.796537 283.921457,433.843858 284.039761,433.938501 C285.743341,435.511947 286.595118,436.458366 286.595118,436.777787 C286.595118,436.884261 286.553712,436.996648 286.470899,437.114952 C286.328934,437.304239 286.080499,437.623655 285.725587,438.073211 C285.370674,438.522767 285.104494,438.877674 284.927038,439.137943 C285.199137,439.705803 285.400251,440.190843 285.530386,440.593077 L288.227707,441.001224 C288.346011,441.024885 288.446569,441.086994 288.529381,441.187552 C288.612194,441.288111 288.6536,441.403456 288.6536,441.53359 Z M300.010742,450.99196 L300.010742,453.476335 C300.010742,453.665622 299.12939,453.848991 297.366658,454.026447 C297.224693,454.345868 297.047239,454.653454 296.834292,454.949215 C297.437643,456.286052 297.739314,457.102338 297.739314,457.398098 C297.739314,457.44542 297.715653,457.486826 297.668332,457.522317 C296.225021,458.362277 295.491546,458.78225 295.467886,458.78225 C295.373242,458.78225 295.101147,458.504239 294.651591,457.94821 C294.202035,457.39218 293.894449,456.989952 293.728823,456.741514 C293.492215,456.765174 293.314761,456.777005 293.196457,456.777005 C293.078153,456.777005 292.900699,456.765174 292.664091,456.741514 C292.498465,456.989952 292.190879,457.39218 291.741323,457.94821 C291.291767,458.504239 291.019672,458.78225 290.925029,458.78225 C290.901368,458.78225 290.167893,458.362277 288.724582,457.522317 C288.677261,457.486826 288.6536,457.44542 288.6536,457.398098 C288.6536,457.102338 288.955271,456.286052 289.558622,454.949215 C289.345675,454.653454 289.168221,454.345868 289.026256,454.026447 C287.263524,453.848991 286.382172,453.665622 286.382172,453.476335 L286.382172,450.99196 C286.382172,450.802674 287.263524,450.619305 289.026256,450.441849 C289.180052,450.098767 289.357505,449.791181 289.558622,449.519081 C288.955271,448.182244 288.6536,447.365958 288.6536,447.070197 C288.6536,447.022875 288.677261,446.98147 288.724582,446.945978 C288.771904,446.922318 288.978933,446.804015 289.345676,446.591068 C289.712419,446.37812 290.061411,446.177006 290.392663,445.98772 C290.723914,445.798433 290.901368,445.703791 290.925029,445.703791 C291.019672,445.703791 291.291767,445.978844 291.741323,446.528958 C292.190879,447.079073 292.498465,447.478343 292.664091,447.726782 C292.900699,447.703121 293.078153,447.691291 293.196457,447.691291 C293.314761,447.691291 293.492215,447.703121 293.728823,447.726782 C294.332174,446.886822 294.876365,446.224329 295.361412,445.739282 L295.467886,445.703791 C295.515207,445.703791 296.248682,446.117849 297.668332,446.945978 C297.715653,446.98147 297.739314,447.022875 297.739314,447.070197 C297.739314,447.365958 297.437643,448.182244 296.834292,449.519081 C297.035409,449.791181 297.212862,450.098767 297.366658,450.441849 C299.12939,450.619305 300.010742,450.802674 300.010742,450.99196 Z M300.010742,432.820533 L300.010742,435.304908 C300.010742,435.494194 299.12939,435.677563 297.366658,435.855019 C297.224693,436.17444 297.047239,436.482027 296.834292,436.777787 C297.437643,438.114624 297.739314,438.93091 297.739314,439.226671 C297.739314,439.273992 297.715653,439.315398 297.668332,439.35089 C296.225021,440.190849 295.491546,440.610822 295.467886,440.610822 C295.373242,440.610822 295.101147,440.332812 294.651591,439.776782 C294.202035,439.220753 293.894449,438.818525 293.728823,438.570086 C293.492215,438.593747 293.314761,438.605577 293.196457,438.605577 C293.078153,438.605577 292.900699,438.593747 292.664091,438.570086 C292.498465,438.818525 292.190879,439.220753 291.741323,439.776782 C291.291767,440.332812 291.019672,440.610822 290.925029,440.610822 C290.901368,440.610822 290.167893,440.190849 288.724582,439.35089 C288.677261,439.315398 288.6536,439.273992 288.6536,439.226671 C288.6536,438.93091 288.955271,438.114624 289.558622,436.777787 C289.345675,436.482027 289.168221,436.17444 289.026256,435.855019 C287.263524,435.677563 286.382172,435.494194 286.382172,435.304908 L286.382172,432.820533 C286.382172,432.631246 287.263524,432.447877 289.026256,432.270421 C289.180052,431.927339 289.357505,431.619753 289.558622,431.347653 C288.955271,430.010816 288.6536,429.19453 288.6536,428.89877 C288.6536,428.851448 288.677261,428.810042 288.724582,428.774551 C288.771904,428.75089 288.978933,428.632588 289.345676,428.41964 C289.712419,428.206693 290.061411,428.005579 290.392663,427.816292 C290.723914,427.627005 290.901368,427.532363 290.925029,427.532363 C291.019672,427.532363 291.291767,427.807416 291.741323,428.357531 C292.190879,428.907645 292.498465,429.306916 292.664091,429.555354 C292.900699,429.531694 293.078153,429.519863 293.196457,429.519863 C293.314761,429.519863 293.492215,429.531694 293.728823,429.555354 C294.332174,428.715395 294.876365,428.052901 295.361412,427.567854 L295.467886,427.532363 C295.515207,427.532363 296.248682,427.946422 297.668332,428.774551 C297.715653,428.810042 297.739314,428.851448 297.739314,428.89877 C297.739314,429.19453 297.437643,430.010816 296.834292,431.347653 C297.035409,431.619753 297.212862,431.927339 297.366658,432.270421 C299.12939,432.447877 300.010742,432.631246 300.010742,432.820533 Z" id="" fill="#E04733"></path> + <path d="M518.847717,443.148434 C518.847717,441.89441 518.404083,440.823773 517.516802,439.936492 C516.629521,439.049211 515.558884,438.605577 514.30486,438.605577 C513.050836,438.605577 511.9802,439.049211 511.092919,439.936492 C510.205637,440.823773 509.762003,441.89441 509.762003,443.148434 C509.762003,444.402458 510.205637,445.473095 511.092919,446.360376 C511.9802,447.247657 513.050836,447.691291 514.30486,447.691291 C515.558884,447.691291 516.629521,447.247657 517.516802,446.360376 C518.404083,445.473095 518.847717,444.402458 518.847717,443.148434 Z M532.476288,452.234148 C532.476288,451.618966 532.251513,451.086605 531.801958,450.63705 C531.352402,450.187494 530.820041,449.962719 530.20486,449.962719 C529.589678,449.962719 529.057317,450.187494 528.607761,450.63705 C528.158206,451.086605 527.933431,451.618966 527.933431,452.234148 C527.933431,452.86116 528.155248,453.396478 528.598889,453.840119 C529.042529,454.283759 529.577847,454.505576 530.20486,454.505576 C530.831872,454.505576 531.36719,454.283759 531.81083,453.840119 C532.254471,453.396478 532.476288,452.86116 532.476288,452.234148 Z M532.476288,434.06272 C532.476288,433.447539 532.251513,432.915178 531.801958,432.465622 C531.352402,432.016066 530.820041,431.791292 530.20486,431.791292 C529.589678,431.791292 529.057317,432.016066 528.607761,432.465622 C528.158206,432.915178 527.933431,433.447539 527.933431,434.06272 C527.933431,434.689732 528.155248,435.22505 528.598889,435.668691 C529.042529,436.112332 529.577847,436.334149 530.20486,436.334149 C530.831872,436.334149 531.36719,436.112332 531.81083,435.668691 C532.254471,435.22505 532.476288,434.689732 532.476288,434.06272 Z M525.662003,441.53359 L525.662003,444.816514 C525.662003,444.934818 525.620597,445.050163 525.537784,445.162552 C525.454971,445.274941 525.360329,445.33705 525.253855,445.34888 L522.503297,445.774773 C522.373163,446.188838 522.183879,446.638387 521.93544,447.123434 C522.337674,447.691294 522.870035,448.371532 523.532538,449.16417 C523.615351,449.282474 523.656757,449.400777 523.656757,449.519081 C523.656757,449.661046 523.615351,449.773433 523.532538,449.856246 C523.260439,450.211159 522.772442,450.740562 522.068532,451.444471 C521.364622,452.148381 520.900285,452.500331 520.675507,452.500331 C520.545373,452.500331 520.421155,452.458925 520.302851,452.376112 L518.262115,450.779014 C517.824389,451.003792 517.368925,451.18716 516.895708,451.329125 C516.765574,452.60681 516.629526,453.523654 516.487561,454.079683 C516.404748,454.363613 516.227295,454.505576 515.955195,454.505576 L512.654526,454.505576 C512.524391,454.505576 512.406089,454.461213 512.299615,454.372485 C512.193141,454.283757 512.13399,454.180242 512.12216,454.061938 L511.714012,451.346871 C511.311778,451.228567 510.868144,451.045198 510.383097,450.796759 L508.289124,452.376112 C508.206311,452.458925 508.088009,452.500331 507.934213,452.500331 C507.804079,452.500331 507.679861,452.45301 507.561557,452.358367 C505.857977,450.784921 505.0062,449.838502 505.0062,449.519081 C505.0062,449.412607 505.047606,449.30022 505.130419,449.181916 C505.248723,449.01629 505.491243,448.702789 505.857986,448.241402 C506.224729,447.780016 506.502739,447.419194 506.692026,447.158925 C506.419926,446.638387 506.212897,446.153347 506.070932,445.703791 L503.373611,445.277898 C503.255307,445.266068 503.15475,445.209874 503.071937,445.109316 C502.989124,445.008757 502.947718,444.893412 502.947718,444.763278 L502.947718,441.480354 C502.947718,441.36205 502.989124,441.246705 503.071937,441.134316 C503.15475,441.021927 503.249392,440.959818 503.355865,440.947988 L506.106423,440.522095 C506.236558,440.10803 506.425842,439.658481 506.67428,439.173434 C506.272046,438.605574 505.739686,437.925336 505.077182,437.132698 C504.994369,437.002563 504.952964,436.884261 504.952964,436.777787 C504.952964,436.635822 504.994369,436.51752 505.077182,436.422876 C505.337451,436.067964 505.822491,435.541518 506.532316,434.843524 C507.242141,434.145529 507.709436,433.796537 507.934213,433.796537 C508.064348,433.796537 508.188565,433.837943 508.30687,433.920756 L510.347606,435.517854 C510.74984,435.304907 511.205304,435.115623 511.714012,434.949997 C511.844147,433.672312 511.980195,432.761384 512.12216,432.217185 C512.204973,431.933255 512.382426,431.791292 512.654526,431.791292 L515.955195,431.791292 C516.08533,431.791292 516.203632,431.835655 516.310106,431.924383 C516.41658,432.013111 516.475731,432.116626 516.487561,432.23493 L516.895708,434.949997 C517.297943,435.068301 517.741577,435.25167 518.226624,435.500108 L520.320597,433.920756 C520.41524,433.837943 520.533542,433.796537 520.675507,433.796537 C520.805642,433.796537 520.929859,433.843858 521.048164,433.938501 C522.751743,435.511947 523.603521,436.458366 523.603521,436.777787 C523.603521,436.884261 523.562115,436.996648 523.479302,437.114952 C523.337337,437.304239 523.088902,437.623655 522.733989,438.073211 C522.379077,438.522767 522.112897,438.877674 521.93544,439.137943 C522.20754,439.705803 522.408654,440.190843 522.538789,440.593077 L525.23611,441.001224 C525.354414,441.024885 525.454971,441.086994 525.537784,441.187552 C525.620597,441.288111 525.662003,441.403456 525.662003,441.53359 Z M537.019145,450.99196 L537.019145,453.476335 C537.019145,453.665622 536.137792,453.848991 534.37506,454.026447 C534.233095,454.345868 534.055642,454.653454 533.842694,454.949215 C534.446045,456.286052 534.747716,457.102338 534.747716,457.398098 C534.747716,457.44542 534.724056,457.486826 534.676734,457.522317 C533.233424,458.362277 532.499949,458.78225 532.476288,458.78225 C532.381645,458.78225 532.109549,458.504239 531.659993,457.94821 C531.210438,457.39218 530.902851,456.989952 530.737226,456.741514 C530.500617,456.765174 530.323164,456.777005 530.20486,456.777005 C530.086555,456.777005 529.909102,456.765174 529.672493,456.741514 C529.506868,456.989952 529.199281,457.39218 528.749726,457.94821 C528.30017,458.504239 528.028074,458.78225 527.933431,458.78225 C527.90977,458.78225 527.176295,458.362277 525.732985,457.522317 C525.685663,457.486826 525.662003,457.44542 525.662003,457.398098 C525.662003,457.102338 525.963674,456.286052 526.567025,454.949215 C526.354077,454.653454 526.176624,454.345868 526.034659,454.026447 C524.271927,453.848991 523.390574,453.665622 523.390574,453.476335 L523.390574,450.99196 C523.390574,450.802674 524.271927,450.619305 526.034659,450.441849 C526.188454,450.098767 526.365908,449.791181 526.567025,449.519081 C525.963674,448.182244 525.662003,447.365958 525.662003,447.070197 C525.662003,447.022875 525.685663,446.98147 525.732985,446.945978 C525.780306,446.922318 525.987336,446.804015 526.354078,446.591068 C526.720821,446.37812 527.069813,446.177006 527.401065,445.98772 C527.732317,445.798433 527.90977,445.703791 527.933431,445.703791 C528.028074,445.703791 528.30017,445.978844 528.749726,446.528958 C529.199281,447.079073 529.506868,447.478343 529.672493,447.726782 C529.909102,447.703121 530.086555,447.691291 530.20486,447.691291 C530.323164,447.691291 530.500617,447.703121 530.737226,447.726782 C531.340577,446.886822 531.884768,446.224329 532.369815,445.739282 L532.476288,445.703791 C532.52361,445.703791 533.257084,446.117849 534.676734,446.945978 C534.724056,446.98147 534.747716,447.022875 534.747716,447.070197 C534.747716,447.365958 534.446045,448.182244 533.842694,449.519081 C534.043811,449.791181 534.221265,450.098767 534.37506,450.441849 C536.137792,450.619305 537.019145,450.802674 537.019145,450.99196 Z M537.019145,432.820533 L537.019145,435.304908 C537.019145,435.494194 536.137792,435.677563 534.37506,435.855019 C534.233095,436.17444 534.055642,436.482027 533.842694,436.777787 C534.446045,438.114624 534.747716,438.93091 534.747716,439.226671 C534.747716,439.273992 534.724056,439.315398 534.676734,439.35089 C533.233424,440.190849 532.499949,440.610822 532.476288,440.610822 C532.381645,440.610822 532.109549,440.332812 531.659993,439.776782 C531.210438,439.220753 530.902851,438.818525 530.737226,438.570086 C530.500617,438.593747 530.323164,438.605577 530.20486,438.605577 C530.086555,438.605577 529.909102,438.593747 529.672493,438.570086 C529.506868,438.818525 529.199281,439.220753 528.749726,439.776782 C528.30017,440.332812 528.028074,440.610822 527.933431,440.610822 C527.90977,440.610822 527.176295,440.190849 525.732985,439.35089 C525.685663,439.315398 525.662003,439.273992 525.662003,439.226671 C525.662003,438.93091 525.963674,438.114624 526.567025,436.777787 C526.354077,436.482027 526.176624,436.17444 526.034659,435.855019 C524.271927,435.677563 523.390574,435.494194 523.390574,435.304908 L523.390574,432.820533 C523.390574,432.631246 524.271927,432.447877 526.034659,432.270421 C526.188454,431.927339 526.365908,431.619753 526.567025,431.347653 C525.963674,430.010816 525.662003,429.19453 525.662003,428.89877 C525.662003,428.851448 525.685663,428.810042 525.732985,428.774551 C525.780306,428.75089 525.987336,428.632588 526.354078,428.41964 C526.720821,428.206693 527.069813,428.005579 527.401065,427.816292 C527.732317,427.627005 527.90977,427.532363 527.933431,427.532363 C528.028074,427.532363 528.30017,427.807416 528.749726,428.357531 C529.199281,428.907645 529.506868,429.306916 529.672493,429.555354 C529.909102,429.531694 530.086555,429.519863 530.20486,429.519863 C530.323164,429.519863 530.500617,429.531694 530.737226,429.555354 C531.340577,428.715395 531.884768,428.052901 532.369815,427.567854 L532.476288,427.532363 C532.52361,427.532363 533.257084,427.946422 534.676734,428.774551 C534.724056,428.810042 534.747716,428.851448 534.747716,428.89877 C534.747716,429.19453 534.446045,430.010816 533.842694,431.347653 C534.043811,431.619753 534.221265,431.927339 534.37506,432.270421 C536.137792,432.447877 537.019145,432.631246 537.019145,432.820533 Z" id="-copy" fill="#E04733"></path> + <path d="M859.734507,544.858471 C857.81798,544.917623 856.250474,545.674758 855.031941,547.1299 L852.654039,547.1299 C851.683945,547.1299 850.867659,546.890337 850.205155,546.411205 C849.542652,545.932074 849.211405,545.231132 849.211405,544.30836 C849.211405,540.132223 849.94488,538.044186 851.411852,538.044186 C851.482834,538.044186 851.740142,538.168403 852.183782,538.416842 C852.627423,538.665281 853.204147,538.916673 853.913972,539.171027 C854.623797,539.425381 855.327696,539.552556 856.025691,539.552556 C856.818329,539.552556 857.605039,539.416509 858.385847,539.144409 C858.326695,539.582134 858.297119,539.972532 858.297119,540.315614 C858.297119,541.960042 858.776244,543.474313 859.734507,544.858471 Z M878.739975,556.162377 C878.739975,557.582027 878.308171,558.702942 877.444551,559.525156 C876.580931,560.34737 875.433398,560.75847 874.001917,560.75847 L858.49232,560.75847 C857.06084,560.75847 855.913307,560.34737 855.049686,559.525156 C854.186066,558.702942 853.754262,557.582027 853.754262,556.162377 C853.754262,555.535365 853.774965,554.92315 853.816372,554.325714 C853.857778,553.728278 853.94059,553.08353 854.064809,552.391451 C854.189028,551.699371 854.345779,551.057581 854.535066,550.46606 C854.724352,549.874539 854.978703,549.297815 855.298124,548.73587 C855.617545,548.173926 855.984282,547.694801 856.398347,547.298482 C856.812411,546.902163 857.318154,546.585704 857.91559,546.349096 C858.513026,546.112488 859.172562,545.994185 859.894217,545.994185 C860.012521,545.994185 860.266872,546.12136 860.657275,546.375714 C861.047679,546.630068 861.479483,546.913994 861.952699,547.2275 C862.425916,547.541006 863.058834,547.824932 863.851471,548.079286 C864.644109,548.33364 865.44265,548.460815 866.247119,548.460815 C867.051587,548.460815 867.850128,548.33364 868.642766,548.079286 C869.435404,547.824932 870.068321,547.541006 870.541538,547.2275 C871.014755,546.913994 871.446558,546.630068 871.836962,546.375714 C872.227366,546.12136 872.481716,545.994185 872.60002,545.994185 C873.321675,545.994185 873.981211,546.112488 874.578647,546.349096 C875.176083,546.585704 875.681826,546.902163 876.09589,547.298482 C876.509955,547.694801 876.876692,548.173926 877.196114,548.73587 C877.515535,549.297815 877.769885,549.874539 877.959172,550.46606 C878.148458,551.057581 878.305209,551.699371 878.429428,552.391451 C878.553648,553.08353 878.636459,553.728278 878.677866,554.325714 C878.719272,554.92315 878.739975,555.535365 878.739975,556.162377 Z M860.568548,533.501329 C860.568548,534.755353 860.124914,535.82599 859.237632,536.713271 C858.350351,537.600552 857.279715,538.044186 856.025691,538.044186 C854.771667,538.044186 853.70103,537.600552 852.813749,536.713271 C851.926468,535.82599 851.482834,534.755353 851.482834,533.501329 C851.482834,532.247305 851.926468,531.176668 852.813749,530.289387 C853.70103,529.402106 854.771667,528.958472 856.025691,528.958472 C857.279715,528.958472 858.350351,529.402106 859.237632,530.289387 C860.124914,531.176668 860.568548,532.247305 860.568548,533.501329 Z M873.061404,540.315614 C873.061404,542.19665 872.395953,543.802605 871.065031,545.133527 C869.73411,546.464449 868.128155,547.1299 866.247119,547.1299 C864.366083,547.1299 862.760128,546.464449 861.429206,545.133527 C860.098284,543.802605 859.432833,542.19665 859.432833,540.315614 C859.432833,538.434578 860.098284,536.828623 861.429206,535.497702 C862.760128,534.16678 864.366083,533.501329 866.247119,533.501329 C868.128155,533.501329 869.73411,534.16678 871.065031,535.497702 C872.395953,536.828623 873.061404,538.434578 873.061404,540.315614 Z M883.282832,544.30836 C883.282832,545.231132 882.951585,545.932074 882.289082,546.411205 C881.626579,546.890337 880.810292,547.1299 879.840198,547.1299 L877.462297,547.1299 C876.243764,545.674758 874.676257,544.917623 872.75973,544.858471 C873.717994,543.474313 874.197118,541.960042 874.197118,540.315614 C874.197118,539.972532 874.167543,539.582134 874.108391,539.144409 C874.889198,539.416509 875.675909,539.552556 876.468547,539.552556 C877.166541,539.552556 877.87044,539.425381 878.580265,539.171027 C879.29009,538.916673 879.866814,538.665281 880.310455,538.416842 C880.754096,538.168403 881.011403,538.044186 881.082386,538.044186 C882.549357,538.044186 883.282832,540.132223 883.282832,544.30836 Z M881.011404,533.501329 C881.011404,534.755353 880.56777,535.82599 879.680489,536.713271 C878.793207,537.600552 877.722571,538.044186 876.468547,538.044186 C875.214523,538.044186 874.143886,537.600552 873.256605,536.713271 C872.369324,535.82599 871.92569,534.755353 871.92569,533.501329 C871.92569,532.247305 872.369324,531.176668 873.256605,530.289387 C874.143886,529.402106 875.214523,528.958472 876.468547,528.958472 C877.722571,528.958472 878.793207,529.402106 879.680489,530.289387 C880.56777,531.176668 881.011404,532.247305 881.011404,533.501329 Z M920.88562,539.002445 C920.88562,539.475661 920.719997,539.877889 920.388745,540.209141 L905.127585,555.470301 C904.796334,555.801553 904.394106,555.967176 903.920889,555.967176 C903.447672,555.967176 903.045444,555.801553 902.714193,555.470301 L893.876916,546.633025 C893.545665,546.301773 893.380041,545.899545 893.380041,545.426328 C893.380041,544.953112 893.545665,544.550884 893.876916,544.219632 L896.290309,541.806239 C896.621561,541.474988 897.023789,541.309364 897.497005,541.309364 C897.970222,541.309364 898.37245,541.474988 898.703702,541.806239 L903.920889,547.041172 L915.56196,535.382356 C915.893211,535.051104 916.29544,534.885481 916.768656,534.885481 C917.241873,534.885481 917.644101,535.051104 917.975353,535.382356 L920.388745,537.795748 C920.719997,538.127 920.88562,538.529228 920.88562,539.002445 Z" id="--copy" fill="#E04733"></path> + <path d="M1045.7411,135.899363 C1043.82457,135.958515 1042.25707,136.715651 1041.03854,138.170792 L1038.66063,138.170792 C1037.69054,138.170792 1036.87425,137.931229 1036.21175,137.452098 C1035.54925,136.972966 1035.218,136.272024 1035.218,135.349252 C1035.218,131.173115 1035.95147,129.085078 1037.41845,129.085078 C1037.48943,129.085078 1037.74674,129.209295 1038.19038,129.457734 C1038.63402,129.706173 1039.21074,129.957566 1039.92057,130.211919 C1040.63039,130.466273 1041.33429,130.593448 1042.03229,130.593448 C1042.82492,130.593448 1043.61163,130.457401 1044.39244,130.185301 C1044.33329,130.623027 1044.30371,131.013424 1044.30371,131.356506 C1044.30371,133.000934 1044.78284,134.515205 1045.7411,135.899363 Z M1064.74657,147.203269 C1064.74657,148.622919 1064.31477,149.743834 1063.45115,150.566048 C1062.58753,151.388262 1061.43999,151.799362 1060.00851,151.799362 L1044.49891,151.799362 C1043.06743,151.799362 1041.9199,151.388262 1041.05628,150.566048 C1040.19266,149.743834 1039.76086,148.622919 1039.76086,147.203269 C1039.76086,146.576257 1039.78156,145.964042 1039.82297,145.366606 C1039.86437,144.76917 1039.94718,144.124422 1040.0714,143.432343 C1040.19562,142.740264 1040.35237,142.098473 1040.54166,141.506952 C1040.73095,140.915432 1040.9853,140.338707 1041.30472,139.776763 C1041.62414,139.214818 1041.99088,138.735693 1042.40494,138.339374 C1042.81901,137.943055 1043.32475,137.626597 1043.92218,137.389988 C1044.51962,137.15338 1045.17916,137.035078 1045.90081,137.035078 C1046.01912,137.035078 1046.27347,137.162253 1046.66387,137.416607 C1047.05427,137.67096 1047.48608,137.954886 1047.95929,138.268392 C1048.43251,138.581898 1049.06543,138.865824 1049.85807,139.120178 C1050.6507,139.374532 1051.44924,139.501707 1052.25371,139.501707 C1053.05818,139.501707 1053.85672,139.374532 1054.64936,139.120178 C1055.442,138.865824 1056.07492,138.581898 1056.54813,138.268392 C1057.02135,137.954886 1057.45315,137.67096 1057.84356,137.416607 C1058.23396,137.162253 1058.48831,137.035078 1058.60661,137.035078 C1059.32827,137.035078 1059.98781,137.15338 1060.58524,137.389988 C1061.18268,137.626597 1061.68842,137.943055 1062.10248,138.339374 C1062.51655,138.735693 1062.88329,139.214818 1063.20271,139.776763 C1063.52213,140.338707 1063.77648,140.915432 1063.96577,141.506952 C1064.15505,142.098473 1064.3118,142.740264 1064.43602,143.432343 C1064.56024,144.124422 1064.64305,144.76917 1064.68446,145.366606 C1064.72587,145.964042 1064.74657,146.576257 1064.74657,147.203269 Z M1046.57514,124.542221 C1046.57514,125.796245 1046.13151,126.866882 1045.24423,127.754163 C1044.35695,128.641444 1043.28631,129.085078 1042.03229,129.085078 C1040.77826,129.085078 1039.70762,128.641444 1038.82034,127.754163 C1037.93306,126.866882 1037.48943,125.796245 1037.48943,124.542221 C1037.48943,123.288197 1037.93306,122.21756 1038.82034,121.330279 C1039.70762,120.442998 1040.77826,119.999364 1042.03229,119.999364 C1043.28631,119.999364 1044.35695,120.442998 1045.24423,121.330279 C1046.13151,122.21756 1046.57514,123.288197 1046.57514,124.542221 Z M1059.068,131.356506 C1059.068,133.237543 1058.40255,134.843497 1057.07163,136.174419 C1055.7407,137.505341 1054.13475,138.170792 1052.25371,138.170792 C1050.37268,138.170792 1048.76672,137.505341 1047.4358,136.174419 C1046.10488,134.843497 1045.43943,133.237543 1045.43943,131.356506 C1045.43943,129.47547 1046.10488,127.869516 1047.4358,126.538594 C1048.76672,125.207672 1050.37268,124.542221 1052.25371,124.542221 C1054.13475,124.542221 1055.7407,125.207672 1057.07163,126.538594 C1058.40255,127.869516 1059.068,129.47547 1059.068,131.356506 Z M1069.28943,135.349252 C1069.28943,136.272024 1068.95818,136.972966 1068.29568,137.452098 C1067.63317,137.931229 1066.81689,138.170792 1065.84679,138.170792 L1063.46889,138.170792 C1062.25036,136.715651 1060.68285,135.958515 1058.76632,135.899363 C1059.72459,134.515205 1060.20371,133.000934 1060.20371,131.356506 C1060.20371,131.013424 1060.17414,130.623027 1060.11498,130.185301 C1060.89579,130.457401 1061.6825,130.593448 1062.47514,130.593448 C1063.17314,130.593448 1063.87703,130.466273 1064.58686,130.211919 C1065.29668,129.957566 1065.87341,129.706173 1066.31705,129.457734 C1066.76069,129.209295 1067.018,129.085078 1067.08898,129.085078 C1068.55595,129.085078 1069.28943,131.173115 1069.28943,135.349252 Z M1067.018,124.542221 C1067.018,125.796245 1066.57436,126.866882 1065.68708,127.754163 C1064.7998,128.641444 1063.72917,129.085078 1062.47514,129.085078 C1061.22112,129.085078 1060.15048,128.641444 1059.2632,127.754163 C1058.37592,126.866882 1057.93228,125.796245 1057.93228,124.542221 C1057.93228,123.288197 1058.37592,122.21756 1059.2632,121.330279 C1060.15048,120.442998 1061.22112,119.999364 1062.47514,119.999364 C1063.72917,119.999364 1064.7998,120.442998 1065.68708,121.330279 C1066.57436,122.21756 1067.018,123.288197 1067.018,124.542221 Z M1106.89221,130.043337 C1106.89221,130.516553 1106.72659,130.918782 1106.39534,131.250033 L1091.13418,146.511193 C1090.80293,146.842445 1090.4007,147.008068 1089.92748,147.008068 C1089.45427,147.008068 1089.05204,146.842445 1088.72079,146.511193 L1079.88351,137.673917 C1079.55226,137.342665 1079.38664,136.940437 1079.38664,136.46722 C1079.38664,135.994004 1079.55226,135.591776 1079.88351,135.260524 L1082.2969,132.847131 C1082.62816,132.51588 1083.03038,132.350256 1083.5036,132.350256 C1083.97682,132.350256 1084.37904,132.51588 1084.7103,132.847131 L1089.92748,138.082064 L1101.56855,126.423248 C1101.89981,126.091996 1102.30203,125.926373 1102.77525,125.926373 C1103.24847,125.926373 1103.6507,126.091996 1103.98195,126.423248 L1106.39534,128.83664 C1106.72659,129.167892 1106.89221,129.57012 1106.89221,130.043337 Z" id="--copy-2" fill="#E04733"></path> + <path d="M385.53174,544.858471 C383.615212,544.917623 382.047706,545.674758 380.829173,547.1299 L378.451271,547.1299 C377.481177,547.1299 376.664891,546.890337 376.002387,546.411205 C375.339884,545.932074 375.008638,545.231132 375.008638,544.30836 C375.008638,540.132223 375.742112,538.044186 377.209084,538.044186 C377.280066,538.044186 377.537374,538.168403 377.981015,538.416842 C378.424655,538.665281 379.001379,538.916673 379.711204,539.171027 C380.421029,539.425381 381.124928,539.552556 381.822923,539.552556 C382.615561,539.552556 383.402272,539.416509 384.183079,539.144409 C384.123927,539.582134 384.094351,539.972532 384.094351,540.315614 C384.094351,541.960042 384.573476,543.474313 385.53174,544.858471 Z M404.537207,556.162377 C404.537207,557.582027 404.105404,558.702942 403.241783,559.525156 C402.378163,560.34737 401.23063,560.75847 399.79915,560.75847 L384.289552,560.75847 C382.858072,560.75847 381.710539,560.34737 380.846918,559.525156 C379.983298,558.702942 379.551494,557.582027 379.551494,556.162377 C379.551494,555.535365 379.572197,554.92315 379.613604,554.325714 C379.65501,553.728278 379.737822,553.08353 379.862041,552.391451 C379.986261,551.699371 380.143011,551.057581 380.332298,550.46606 C380.521585,549.874539 380.775935,549.297815 381.095356,548.73587 C381.414777,548.173926 381.781515,547.694801 382.195579,547.298482 C382.609644,546.902163 383.115386,546.585704 383.712822,546.349096 C384.310258,546.112488 384.969794,545.994185 385.691449,545.994185 C385.809754,545.994185 386.064104,546.12136 386.454507,546.375714 C386.844911,546.630068 387.276715,546.913994 387.749932,547.2275 C388.223148,547.541006 388.856066,547.824932 389.648704,548.079286 C390.441342,548.33364 391.239883,548.460815 392.044351,548.460815 C392.848819,548.460815 393.64736,548.33364 394.439998,548.079286 C395.232636,547.824932 395.865554,547.541006 396.33877,547.2275 C396.811987,546.913994 397.243791,546.630068 397.634194,546.375714 C398.024598,546.12136 398.278948,545.994185 398.397252,545.994185 C399.118908,545.994185 399.778443,546.112488 400.375879,546.349096 C400.973315,546.585704 401.479058,546.902163 401.893123,547.298482 C402.307187,547.694801 402.673925,548.173926 402.993346,548.73587 C403.312767,549.297815 403.567117,549.874539 403.756404,550.46606 C403.945691,551.057581 404.102441,551.699371 404.226661,552.391451 C404.35088,553.08353 404.433692,553.728278 404.475098,554.325714 C404.516504,554.92315 404.537207,555.535365 404.537207,556.162377 Z M386.36578,533.501329 C386.36578,534.755353 385.922146,535.82599 385.034865,536.713271 C384.147584,537.600552 383.076947,538.044186 381.822923,538.044186 C380.568899,538.044186 379.498262,537.600552 378.610981,536.713271 C377.7237,535.82599 377.280066,534.755353 377.280066,533.501329 C377.280066,532.247305 377.7237,531.176668 378.610981,530.289387 C379.498262,529.402106 380.568899,528.958472 381.822923,528.958472 C383.076947,528.958472 384.147584,529.402106 385.034865,530.289387 C385.922146,531.176668 386.36578,532.247305 386.36578,533.501329 Z M398.858636,540.315614 C398.858636,542.19665 398.193185,543.802605 396.862264,545.133527 C395.531342,546.464449 393.925387,547.1299 392.044351,547.1299 C390.163315,547.1299 388.55736,546.464449 387.226438,545.133527 C385.895516,543.802605 385.230066,542.19665 385.230066,540.315614 C385.230066,538.434578 385.895516,536.828623 387.226438,535.497702 C388.55736,534.16678 390.163315,533.501329 392.044351,533.501329 C393.925387,533.501329 395.531342,534.16678 396.862264,535.497702 C398.193185,536.828623 398.858636,538.434578 398.858636,540.315614 Z M409.080064,544.30836 C409.080064,545.231132 408.748818,545.932074 408.086314,546.411205 C407.423811,546.890337 406.607525,547.1299 405.637431,547.1299 L403.259529,547.1299 C402.040996,545.674758 400.47349,544.917623 398.556962,544.858471 C399.515226,543.474313 399.99435,541.960042 399.99435,540.315614 C399.99435,539.972532 399.964775,539.582134 399.905623,539.144409 C400.68643,539.416509 401.473141,539.552556 402.265779,539.552556 C402.963773,539.552556 403.667673,539.425381 404.377498,539.171027 C405.087323,538.916673 405.664047,538.665281 406.107687,538.416842 C406.551328,538.168403 406.808635,538.044186 406.879618,538.044186 C408.34659,538.044186 409.080064,540.132223 409.080064,544.30836 Z M406.808636,533.501329 C406.808636,534.755353 406.365002,535.82599 405.477721,536.713271 C404.59044,537.600552 403.519803,538.044186 402.265779,538.044186 C401.011755,538.044186 399.941118,537.600552 399.053837,536.713271 C398.166556,535.82599 397.722922,534.755353 397.722922,533.501329 C397.722922,532.247305 398.166556,531.176668 399.053837,530.289387 C399.941118,529.402106 401.011755,528.958472 402.265779,528.958472 C403.519803,528.958472 404.59044,529.402106 405.477721,530.289387 C406.365002,531.176668 406.808636,532.247305 406.808636,533.501329 Z M440.063768,552.418069 C440.063768,552.891286 439.898145,553.293514 439.566893,553.624765 L437.1535,556.038158 C436.822249,556.36941 436.420021,556.535033 435.946804,556.535033 C435.473587,556.535033 435.071359,556.36941 434.740108,556.038158 L429.52292,550.820971 L424.305733,556.038158 C423.974481,556.36941 423.572253,556.535033 423.099037,556.535033 C422.62582,556.535033 422.223592,556.36941 421.89234,556.038158 L419.478948,553.624765 C419.147696,553.293514 418.982073,552.891286 418.982073,552.418069 C418.982073,551.944852 419.147696,551.542624 419.478948,551.211373 L424.696135,545.994185 L419.478948,540.776998 C419.147696,540.445747 418.982073,540.043518 418.982073,539.570302 C418.982073,539.097085 419.147696,538.694857 419.478948,538.363605 L421.89234,535.950213 C422.223592,535.618961 422.62582,535.453338 423.099037,535.453338 C423.572253,535.453338 423.974481,535.618961 424.305733,535.950213 L429.52292,541.1674 L434.740108,535.950213 C435.071359,535.618961 435.473587,535.453338 435.946804,535.453338 C436.420021,535.453338 436.822249,535.618961 437.1535,535.950213 L439.566893,538.363605 C439.898145,538.694857 440.063768,539.097085 440.063768,539.570302 C440.063768,540.043518 439.898145,540.445747 439.566893,540.776998 L434.349706,545.994185 L439.566893,551.211373 C439.898145,551.542624 440.063768,551.944852 440.063768,552.418069 Z" id="-" fill="#E04733"></path> + <path d="M622.540142,544.858471 C620.623615,544.917623 619.056108,545.674758 617.837575,547.1299 L615.459674,547.1299 C614.48958,547.1299 613.673293,546.890337 613.01079,546.411205 C612.348287,545.932074 612.01704,545.231132 612.01704,544.30836 C612.01704,540.132223 612.750515,538.044186 614.217486,538.044186 C614.288469,538.044186 614.545777,538.168403 614.989417,538.416842 C615.433058,538.665281 616.009782,538.916673 616.719607,539.171027 C617.429432,539.425381 618.133331,539.552556 618.831325,539.552556 C619.623963,539.552556 620.410674,539.416509 621.191481,539.144409 C621.132329,539.582134 621.102754,539.972532 621.102754,540.315614 C621.102754,541.960042 621.581878,543.474313 622.540142,544.858471 Z M641.54561,556.162377 C641.54561,557.582027 641.113806,558.702942 640.250186,559.525156 C639.386565,560.34737 638.239032,560.75847 636.807552,560.75847 L621.297955,560.75847 C619.866474,560.75847 618.718941,560.34737 617.855321,559.525156 C616.991701,558.702942 616.559897,557.582027 616.559897,556.162377 C616.559897,555.535365 616.5806,554.92315 616.622006,554.325714 C616.663413,553.728278 616.746224,553.08353 616.870444,552.391451 C616.994663,551.699371 617.151414,551.057581 617.3407,550.46606 C617.529987,549.874539 617.784337,549.297815 618.103758,548.73587 C618.42318,548.173926 618.789917,547.694801 619.203982,547.298482 C619.618046,546.902163 620.123789,546.585704 620.721225,546.349096 C621.318661,546.112488 621.978197,545.994185 622.699852,545.994185 C622.818156,545.994185 623.072506,546.12136 623.46291,546.375714 C623.853314,546.630068 624.285117,546.913994 624.758334,547.2275 C625.231551,547.541006 625.864468,547.824932 626.657106,548.079286 C627.449744,548.33364 628.248285,548.460815 629.052753,548.460815 C629.857222,548.460815 630.655763,548.33364 631.448401,548.079286 C632.241038,547.824932 632.873956,547.541006 633.347173,547.2275 C633.820389,546.913994 634.252193,546.630068 634.642597,546.375714 C635.033001,546.12136 635.287351,545.994185 635.405655,545.994185 C636.12731,545.994185 636.786846,546.112488 637.384282,546.349096 C637.981718,546.585704 638.487461,546.902163 638.901525,547.298482 C639.31559,547.694801 639.682327,548.173926 640.001748,548.73587 C640.32117,549.297815 640.57552,549.874539 640.764806,550.46606 C640.954093,551.057581 641.110844,551.699371 641.235063,552.391451 C641.359282,553.08353 641.442094,553.728278 641.4835,554.325714 C641.524907,554.92315 641.54561,555.535365 641.54561,556.162377 Z M623.374182,533.501329 C623.374182,534.755353 622.930548,535.82599 622.043267,536.713271 C621.155986,537.600552 620.085349,538.044186 618.831325,538.044186 C617.577301,538.044186 616.506665,537.600552 615.619384,536.713271 C614.732102,535.82599 614.288468,534.755353 614.288468,533.501329 C614.288468,532.247305 614.732102,531.176668 615.619384,530.289387 C616.506665,529.402106 617.577301,528.958472 618.831325,528.958472 C620.085349,528.958472 621.155986,529.402106 622.043267,530.289387 C622.930548,531.176668 623.374182,532.247305 623.374182,533.501329 Z M635.867039,540.315614 C635.867039,542.19665 635.201588,543.802605 633.870666,545.133527 C632.539744,546.464449 630.933789,547.1299 629.052753,547.1299 C627.171717,547.1299 625.565762,546.464449 624.234841,545.133527 C622.903919,543.802605 622.238468,542.19665 622.238468,540.315614 C622.238468,538.434578 622.903919,536.828623 624.234841,535.497702 C625.565762,534.16678 627.171717,533.501329 629.052753,533.501329 C630.933789,533.501329 632.539744,534.16678 633.870666,535.497702 C635.201588,536.828623 635.867039,538.434578 635.867039,540.315614 Z M646.088467,544.30836 C646.088467,545.231132 645.75722,545.932074 645.094717,546.411205 C644.432214,546.890337 643.615927,547.1299 642.645833,547.1299 L640.267931,547.1299 C639.049399,545.674758 637.481892,544.917623 635.565365,544.858471 C636.523628,543.474313 637.002753,541.960042 637.002753,540.315614 C637.002753,539.972532 636.973177,539.582134 636.914025,539.144409 C637.694833,539.416509 638.481544,539.552556 639.274181,539.552556 C639.972176,539.552556 640.676075,539.425381 641.3859,539.171027 C642.095725,538.916673 642.672449,538.665281 643.11609,538.416842 C643.55973,538.168403 643.817038,538.044186 643.88802,538.044186 C645.354992,538.044186 646.088467,540.132223 646.088467,544.30836 Z M643.817038,533.501329 C643.817038,534.755353 643.373404,535.82599 642.486123,536.713271 C641.598842,537.600552 640.528205,538.044186 639.274181,538.044186 C638.020157,538.044186 636.949521,537.600552 636.06224,536.713271 C635.174958,535.82599 634.731325,534.755353 634.731325,533.501329 C634.731325,532.247305 635.174958,531.176668 636.06224,530.289387 C636.949521,529.402106 638.020157,528.958472 639.274181,528.958472 C640.528205,528.958472 641.598842,529.402106 642.486123,530.289387 C643.373404,531.176668 643.817038,532.247305 643.817038,533.501329 Z M677.07217,552.418069 C677.07217,552.891286 676.906547,553.293514 676.575295,553.624765 L674.161903,556.038158 C673.830651,556.36941 673.428423,556.535033 672.955206,556.535033 C672.48199,556.535033 672.079762,556.36941 671.74851,556.038158 L666.531323,550.820971 L661.314136,556.038158 C660.982884,556.36941 660.580656,556.535033 660.107439,556.535033 C659.634223,556.535033 659.231994,556.36941 658.900743,556.038158 L656.48735,553.624765 C656.156098,553.293514 655.990475,552.891286 655.990475,552.418069 C655.990475,551.944852 656.156098,551.542624 656.48735,551.211373 L661.704537,545.994185 L656.48735,540.776998 C656.156098,540.445747 655.990475,540.043518 655.990475,539.570302 C655.990475,539.097085 656.156098,538.694857 656.48735,538.363605 L658.900743,535.950213 C659.231994,535.618961 659.634223,535.453338 660.107439,535.453338 C660.580656,535.453338 660.982884,535.618961 661.314136,535.950213 L666.531323,541.1674 L671.74851,535.950213 C672.079762,535.618961 672.48199,535.453338 672.955206,535.453338 C673.428423,535.453338 673.830651,535.618961 674.161903,535.950213 L676.575295,538.363605 C676.906547,538.694857 677.07217,539.097085 677.07217,539.570302 C677.07217,540.043518 676.906547,540.445747 676.575295,540.776998 L671.358108,545.994185 L676.575295,551.211373 C676.906547,551.542624 677.07217,551.944852 677.07217,552.418069 Z" id="--copy" fill="#E04733"></path> + <path d="M756.856155,443.148434 C756.856155,441.89441 756.412521,440.823773 755.52524,439.936492 C754.637959,439.049211 753.567322,438.605577 752.313298,438.605577 C751.059274,438.605577 749.988638,439.049211 749.101357,439.936492 C748.214075,440.823773 747.770441,441.89441 747.770441,443.148434 C747.770441,444.402458 748.214075,445.473095 749.101357,446.360376 C749.988638,447.247657 751.059274,447.691291 752.313298,447.691291 C753.567322,447.691291 754.637959,447.247657 755.52524,446.360376 C756.412521,445.473095 756.856155,444.402458 756.856155,443.148434 Z M770.484726,452.234148 C770.484726,451.618966 770.259951,451.086605 769.810396,450.63705 C769.36084,450.187494 768.828479,449.962719 768.213297,449.962719 C767.598116,449.962719 767.065755,450.187494 766.616199,450.63705 C766.166644,451.086605 765.941869,451.618966 765.941869,452.234148 C765.941869,452.86116 766.163686,453.396478 766.607327,453.840119 C767.050967,454.283759 767.586285,454.505576 768.213297,454.505576 C768.840309,454.505576 769.375628,454.283759 769.819268,453.840119 C770.262909,453.396478 770.484726,452.86116 770.484726,452.234148 Z M770.484726,434.06272 C770.484726,433.447539 770.259951,432.915178 769.810396,432.465622 C769.36084,432.016066 768.828479,431.791292 768.213297,431.791292 C767.598116,431.791292 767.065755,432.016066 766.616199,432.465622 C766.166644,432.915178 765.941869,433.447539 765.941869,434.06272 C765.941869,434.689732 766.163686,435.22505 766.607327,435.668691 C767.050967,436.112332 767.586285,436.334149 768.213297,436.334149 C768.840309,436.334149 769.375628,436.112332 769.819268,435.668691 C770.262909,435.22505 770.484726,434.689732 770.484726,434.06272 Z M763.670441,441.53359 L763.670441,444.816514 C763.670441,444.934818 763.629035,445.050163 763.546222,445.162552 C763.463409,445.274941 763.368767,445.33705 763.262293,445.34888 L760.511735,445.774773 C760.381601,446.188838 760.192317,446.638387 759.943878,447.123434 C760.346112,447.691294 760.878473,448.371532 761.540976,449.16417 C761.623789,449.282474 761.665195,449.400777 761.665195,449.519081 C761.665195,449.661046 761.623789,449.773433 761.540976,449.856246 C761.268877,450.211159 760.780879,450.740562 760.07697,451.444471 C759.37306,452.148381 758.908723,452.500331 758.683945,452.500331 C758.553811,452.500331 758.429593,452.458925 758.311289,452.376112 L756.270553,450.779014 C755.832827,451.003792 755.377363,451.18716 754.904146,451.329125 C754.774012,452.60681 754.637964,453.523654 754.495999,454.079683 C754.413186,454.363613 754.235733,454.505576 753.963633,454.505576 L750.662964,454.505576 C750.532829,454.505576 750.414527,454.461213 750.308053,454.372485 C750.201579,454.283757 750.142428,454.180242 750.130598,454.061938 L749.72245,451.346871 C749.320216,451.228567 748.876582,451.045198 748.391535,450.796759 L746.297562,452.376112 C746.214749,452.458925 746.096447,452.500331 745.942651,452.500331 C745.812517,452.500331 745.688299,452.45301 745.569995,452.358367 C743.866415,450.784921 743.014638,449.838502 743.014638,449.519081 C743.014638,449.412607 743.056044,449.30022 743.138857,449.181916 C743.257161,449.01629 743.499681,448.702789 743.866424,448.241402 C744.233167,447.780016 744.511177,447.419194 744.700464,447.158925 C744.428364,446.638387 744.221335,446.153347 744.07937,445.703791 L741.382049,445.277898 C741.263745,445.266068 741.163188,445.209874 741.080375,445.109316 C740.997562,445.008757 740.956156,444.893412 740.956156,444.763278 L740.956156,441.480354 C740.956156,441.36205 740.997562,441.246705 741.080375,441.134316 C741.163188,441.021927 741.25783,440.959818 741.364303,440.947988 L744.114861,440.522095 C744.244996,440.10803 744.43428,439.658481 744.682718,439.173434 C744.280484,438.605574 743.748124,437.925336 743.08562,437.132698 C743.002807,437.002563 742.961401,436.884261 742.961401,436.777787 C742.961401,436.635822 743.002807,436.51752 743.08562,436.422876 C743.345889,436.067964 743.830929,435.541518 744.540754,434.843524 C745.250579,434.145529 745.717873,433.796537 745.942651,433.796537 C746.072786,433.796537 746.197003,433.837943 746.315308,433.920756 L748.356044,435.517854 C748.758278,435.304907 749.213742,435.115623 749.72245,434.949997 C749.852585,433.672312 749.988633,432.761384 750.130598,432.217185 C750.21341,431.933255 750.390864,431.791292 750.662964,431.791292 L753.963633,431.791292 C754.093768,431.791292 754.21207,431.835655 754.318544,431.924383 C754.425017,432.013111 754.484169,432.116626 754.495999,432.23493 L754.904146,434.949997 C755.306381,435.068301 755.750014,435.25167 756.235061,435.500108 L758.329035,433.920756 C758.423678,433.837943 758.54198,433.796537 758.683945,433.796537 C758.81408,433.796537 758.938297,433.843858 759.056602,433.938501 C760.760181,435.511947 761.611959,436.458366 761.611959,436.777787 C761.611959,436.884261 761.570553,436.996648 761.48774,437.114952 C761.345775,437.304239 761.09734,437.623655 760.742427,438.073211 C760.387515,438.522767 760.121334,438.877674 759.943878,439.137943 C760.215978,439.705803 760.417092,440.190843 760.547226,440.593077 L763.244548,441.001224 C763.362852,441.024885 763.463409,441.086994 763.546222,441.187552 C763.629035,441.288111 763.670441,441.403456 763.670441,441.53359 Z M775.027583,450.99196 L775.027583,453.476335 C775.027583,453.665622 774.14623,453.848991 772.383498,454.026447 C772.241533,454.345868 772.06408,454.653454 771.851132,454.949215 C772.454483,456.286052 772.756154,457.102338 772.756154,457.398098 C772.756154,457.44542 772.732494,457.486826 772.685172,457.522317 C771.241861,458.362277 770.508387,458.78225 770.484726,458.78225 C770.390083,458.78225 770.117987,458.504239 769.668431,457.94821 C769.218876,457.39218 768.911289,456.989952 768.745663,456.741514 C768.509055,456.765174 768.331602,456.777005 768.213297,456.777005 C768.094993,456.777005 767.91754,456.765174 767.680931,456.741514 C767.515306,456.989952 767.207719,457.39218 766.758164,457.94821 C766.308608,458.504239 766.036512,458.78225 765.941869,458.78225 C765.918208,458.78225 765.184733,458.362277 763.741423,457.522317 C763.694101,457.486826 763.670441,457.44542 763.670441,457.398098 C763.670441,457.102338 763.972112,456.286052 764.575463,454.949215 C764.362515,454.653454 764.185062,454.345868 764.043097,454.026447 C762.280365,453.848991 761.399012,453.665622 761.399012,453.476335 L761.399012,450.99196 C761.399012,450.802674 762.280365,450.619305 764.043097,450.441849 C764.196892,450.098767 764.374346,449.791181 764.575463,449.519081 C763.972112,448.182244 763.670441,447.365958 763.670441,447.070197 C763.670441,447.022875 763.694101,446.98147 763.741423,446.945978 C763.788744,446.922318 763.995774,446.804015 764.362516,446.591068 C764.729259,446.37812 765.078251,446.177006 765.409503,445.98772 C765.740755,445.798433 765.918208,445.703791 765.941869,445.703791 C766.036512,445.703791 766.308608,445.978844 766.758164,446.528958 C767.207719,447.079073 767.515306,447.478343 767.680931,447.726782 C767.91754,447.703121 768.094993,447.691291 768.213297,447.691291 C768.331602,447.691291 768.509055,447.703121 768.745663,447.726782 C769.349015,446.886822 769.893206,446.224329 770.378253,445.739282 L770.484726,445.703791 C770.532048,445.703791 771.265522,446.117849 772.685172,446.945978 C772.732494,446.98147 772.756154,447.022875 772.756154,447.070197 C772.756154,447.365958 772.454483,448.182244 771.851132,449.519081 C772.052249,449.791181 772.229703,450.098767 772.383498,450.441849 C774.14623,450.619305 775.027583,450.802674 775.027583,450.99196 Z M775.027583,432.820533 L775.027583,435.304908 C775.027583,435.494194 774.14623,435.677563 772.383498,435.855019 C772.241533,436.17444 772.06408,436.482027 771.851132,436.777787 C772.454483,438.114624 772.756154,438.93091 772.756154,439.226671 C772.756154,439.273992 772.732494,439.315398 772.685172,439.35089 C771.241861,440.190849 770.508387,440.610822 770.484726,440.610822 C770.390083,440.610822 770.117987,440.332812 769.668431,439.776782 C769.218876,439.220753 768.911289,438.818525 768.745663,438.570086 C768.509055,438.593747 768.331602,438.605577 768.213297,438.605577 C768.094993,438.605577 767.91754,438.593747 767.680931,438.570086 C767.515306,438.818525 767.207719,439.220753 766.758164,439.776782 C766.308608,440.332812 766.036512,440.610822 765.941869,440.610822 C765.918208,440.610822 765.184733,440.190849 763.741423,439.35089 C763.694101,439.315398 763.670441,439.273992 763.670441,439.226671 C763.670441,438.93091 763.972112,438.114624 764.575463,436.777787 C764.362515,436.482027 764.185062,436.17444 764.043097,435.855019 C762.280365,435.677563 761.399012,435.494194 761.399012,435.304908 L761.399012,432.820533 C761.399012,432.631246 762.280365,432.447877 764.043097,432.270421 C764.196892,431.927339 764.374346,431.619753 764.575463,431.347653 C763.972112,430.010816 763.670441,429.19453 763.670441,428.89877 C763.670441,428.851448 763.694101,428.810042 763.741423,428.774551 C763.788744,428.75089 763.995774,428.632588 764.362516,428.41964 C764.729259,428.206693 765.078251,428.005579 765.409503,427.816292 C765.740755,427.627005 765.918208,427.532363 765.941869,427.532363 C766.036512,427.532363 766.308608,427.807416 766.758164,428.357531 C767.207719,428.907645 767.515306,429.306916 767.680931,429.555354 C767.91754,429.531694 768.094993,429.519863 768.213297,429.519863 C768.331602,429.519863 768.509055,429.531694 768.745663,429.555354 C769.349015,428.715395 769.893206,428.052901 770.378253,427.567854 L770.484726,427.532363 C770.532048,427.532363 771.265522,427.946422 772.685172,428.774551 C772.732494,428.810042 772.756154,428.851448 772.756154,428.89877 C772.756154,429.19453 772.454483,430.010816 771.851132,431.347653 C772.052249,431.619753 772.229703,431.927339 772.383498,432.270421 C774.14623,432.447877 775.027583,432.631246 775.027583,432.820533 Z" id="-copy-2" fill="#E04733"></path> + <path d="M885.860729,188.873341 C885.860729,187.619317 885.417095,186.54868 884.529814,185.661399 C883.642532,184.774118 882.571896,184.330484 881.317872,184.330484 C880.063848,184.330484 878.993211,184.774118 878.10593,185.661399 C877.218649,186.54868 876.775015,187.619317 876.775015,188.873341 C876.775015,190.127365 877.218649,191.198002 878.10593,192.085283 C878.993211,192.972564 880.063848,193.416198 881.317872,193.416198 C882.571896,193.416198 883.642532,192.972564 884.529814,192.085283 C885.417095,191.198002 885.860729,190.127365 885.860729,188.873341 Z M899.489299,197.959055 C899.489299,197.343873 899.264525,196.811512 898.814969,196.361957 C898.365413,195.912401 897.833053,195.687626 897.217871,195.687626 C896.602689,195.687626 896.070329,195.912401 895.620773,196.361957 C895.171217,196.811512 894.946442,197.343873 894.946442,197.959055 C894.946442,198.586067 895.168259,199.121385 895.6119,199.565026 C896.055541,200.008666 896.590859,200.230483 897.217871,200.230483 C897.844883,200.230483 898.380201,200.008666 898.823842,199.565026 C899.267482,199.121385 899.489299,198.586067 899.489299,197.959055 Z M899.489299,179.787627 C899.489299,179.172446 899.264525,178.640085 898.814969,178.190529 C898.365413,177.740973 897.833053,177.516199 897.217871,177.516199 C896.602689,177.516199 896.070329,177.740973 895.620773,178.190529 C895.171217,178.640085 894.946442,179.172446 894.946442,179.787627 C894.946442,180.414639 895.168259,180.949958 895.6119,181.393598 C896.055541,181.837239 896.590859,182.059056 897.217871,182.059056 C897.844883,182.059056 898.380201,181.837239 898.823842,181.393598 C899.267482,180.949958 899.489299,180.414639 899.489299,179.787627 Z M892.675014,187.258497 L892.675014,190.541421 C892.675014,190.659725 892.633608,190.77507 892.550795,190.887459 C892.467982,190.999848 892.37334,191.061957 892.266867,191.073787 L889.516309,191.49968 C889.386174,191.913745 889.19689,192.363294 888.948452,192.848341 C889.350686,193.416201 889.883047,194.096439 890.54555,194.889077 C890.628363,195.007381 890.669769,195.125684 890.669769,195.243988 C890.669769,195.385953 890.628363,195.49834 890.54555,195.581153 C890.27345,195.936066 889.785453,196.465469 889.081543,197.169379 C888.377634,197.873288 887.913297,198.225238 887.688519,198.225238 C887.558384,198.225238 887.434167,198.183832 887.315863,198.101019 L885.275126,196.503921 C884.837401,196.728699 884.381937,196.912068 883.90872,197.054033 C883.778585,198.331717 883.642538,199.248561 883.500573,199.80459 C883.41776,200.08852 883.240306,200.230483 882.968207,200.230483 L879.667537,200.230483 C879.537403,200.230483 879.4191,200.18612 879.312626,200.097392 C879.206153,200.008664 879.147001,199.905149 879.135171,199.786845 L878.727024,197.071778 C878.32479,196.953474 877.881156,196.770105 877.396109,196.521667 L875.302136,198.101019 C875.219323,198.183832 875.10102,198.225238 874.947225,198.225238 C874.81709,198.225238 874.692873,198.177917 874.574569,198.083274 C872.870989,196.509828 872.019212,195.563409 872.019212,195.243988 C872.019212,195.137514 872.060617,195.025127 872.14343,194.906823 C872.261734,194.741197 872.504254,194.427696 872.870997,193.96631 C873.23774,193.504923 873.515751,193.144101 873.705037,192.883832 C873.432938,192.363294 873.225909,191.878254 873.083944,191.428698 L870.386622,191.002805 C870.268318,190.990975 870.167761,190.934781 870.084948,190.834223 C870.002135,190.733664 869.96073,190.618319 869.96073,190.488185 L869.96073,187.205261 C869.96073,187.086957 870.002135,186.971612 870.084948,186.859223 C870.167761,186.746834 870.262403,186.684725 870.368877,186.672895 L873.119435,186.247002 C873.249569,185.832937 873.438853,185.383388 873.687292,184.898341 C873.285058,184.330481 872.752697,183.650243 872.090194,182.857605 C872.007381,182.72747 871.965975,182.609168 871.965975,182.502694 C871.965975,182.360729 872.007381,182.242427 872.090194,182.147783 C872.350463,181.792871 872.835503,181.266425 873.545328,180.568431 C874.255153,179.870436 874.722447,179.521444 874.947225,179.521444 C875.077359,179.521444 875.201577,179.56285 875.319881,179.645663 L877.360618,181.242761 C877.762852,181.029814 878.218316,180.84053 878.727024,180.674904 C878.857158,179.397219 878.993206,178.486291 879.135171,177.942092 C879.217984,177.658162 879.395438,177.516199 879.667537,177.516199 L882.968207,177.516199 C883.098341,177.516199 883.216643,177.560562 883.323117,177.64929 C883.429591,177.738018 883.488742,177.841533 883.500573,177.959837 L883.90872,180.674904 C884.310954,180.793208 884.754588,180.976577 885.239635,181.225016 L887.333608,179.645663 C887.428251,179.56285 887.546554,179.521444 887.688519,179.521444 C887.818653,179.521444 887.942871,179.568765 888.061175,179.663408 C889.764755,181.236854 890.616532,182.183273 890.616532,182.502694 C890.616532,182.609168 890.575126,182.721555 890.492313,182.839859 C890.350348,183.029146 890.101913,183.348562 889.747001,183.798118 C889.392088,184.247674 889.125908,184.602581 888.948452,184.86285 C889.220551,185.43071 889.421665,185.91575 889.5518,186.317984 L892.249121,186.726131 C892.367425,186.749792 892.467982,186.811901 892.550795,186.912459 C892.633608,187.013018 892.675014,187.128363 892.675014,187.258497 Z M904.032156,196.716867 L904.032156,199.201242 C904.032156,199.390529 903.150804,199.573898 901.388072,199.751354 C901.246107,200.070775 901.068653,200.378361 900.855706,200.674122 C901.459057,202.010959 901.760728,202.827245 901.760728,203.123005 C901.760728,203.170327 901.737067,203.211733 901.689746,203.247224 C900.246435,204.087184 899.51296,204.507157 899.489299,204.507157 C899.394656,204.507157 899.122561,204.229147 898.673005,203.673117 C898.223449,203.117087 897.915863,202.714859 897.750237,202.466421 C897.513629,202.490081 897.336175,202.501912 897.217871,202.501912 C897.099567,202.501912 896.922113,202.490081 896.685505,202.466421 C896.519879,202.714859 896.212293,203.117087 895.762737,203.673117 C895.313181,204.229147 895.041086,204.507157 894.946442,204.507157 C894.922782,204.507157 894.189307,204.087184 892.745996,203.247224 C892.698675,203.211733 892.675014,203.170327 892.675014,203.123005 C892.675014,202.827245 892.976685,202.010959 893.580036,200.674122 C893.367089,200.378361 893.189635,200.070775 893.04767,199.751354 C891.284938,199.573898 890.403586,199.390529 890.403586,199.201242 L890.403586,196.716867 C890.403586,196.527581 891.284938,196.344212 893.04767,196.166756 C893.201466,195.823674 893.378919,195.516088 893.580036,195.243988 C892.976685,193.907151 892.675014,193.090865 892.675014,192.795104 C892.675014,192.747783 892.698675,192.706377 892.745996,192.670885 C892.793318,192.647225 893.000347,192.528922 893.36709,192.315975 C893.733833,192.103027 894.082825,191.901913 894.414076,191.712627 C894.745328,191.52334 894.922782,191.428698 894.946442,191.428698 C895.041086,191.428698 895.313181,191.703751 895.762737,192.253865 C896.212293,192.80398 896.519879,193.20325 896.685505,193.451689 C896.922113,193.428028 897.099567,193.416198 897.217871,193.416198 C897.336175,193.416198 897.513629,193.428028 897.750237,193.451689 C898.353588,192.611729 898.897779,191.949236 899.382826,191.464189 L899.489299,191.428698 C899.536621,191.428698 900.270096,191.842756 901.689746,192.670885 C901.737067,192.706377 901.760728,192.747783 901.760728,192.795104 C901.760728,193.090865 901.459057,193.907151 900.855706,195.243988 C901.056823,195.516088 901.234276,195.823674 901.388072,196.166756 C903.150804,196.344212 904.032156,196.527581 904.032156,196.716867 Z M904.032156,178.54544 L904.032156,181.029815 C904.032156,181.219101 903.150804,181.40247 901.388072,181.579926 C901.246107,181.899347 901.068653,182.206934 900.855706,182.502694 C901.459057,183.839531 901.760728,184.655817 901.760728,184.951578 C901.760728,184.9989 901.737067,185.040305 901.689746,185.075797 C900.246435,185.915756 899.51296,186.33573 899.489299,186.33573 C899.394656,186.33573 899.122561,186.057719 898.673005,185.501689 C898.223449,184.94566 897.915863,184.543432 897.750237,184.294993 C897.513629,184.318654 897.336175,184.330484 897.217871,184.330484 C897.099567,184.330484 896.922113,184.318654 896.685505,184.294993 C896.519879,184.543432 896.212293,184.94566 895.762737,185.501689 C895.313181,186.057719 895.041086,186.33573 894.946442,186.33573 C894.922782,186.33573 894.189307,185.915756 892.745996,185.075797 C892.698675,185.040305 892.675014,184.9989 892.675014,184.951578 C892.675014,184.655817 892.976685,183.839531 893.580036,182.502694 C893.367089,182.206934 893.189635,181.899347 893.04767,181.579926 C891.284938,181.40247 890.403586,181.219101 890.403586,181.029815 L890.403586,178.54544 C890.403586,178.356153 891.284938,178.172784 893.04767,177.995328 C893.201466,177.652246 893.378919,177.34466 893.580036,177.07256 C892.976685,175.735723 892.675014,174.919437 892.675014,174.623677 C892.675014,174.576355 892.698675,174.534949 892.745996,174.499458 C892.793318,174.475797 893.000347,174.357495 893.36709,174.144547 C893.733833,173.9316 894.082825,173.730486 894.414076,173.541199 C894.745328,173.351912 894.922782,173.25727 894.946442,173.25727 C895.041086,173.25727 895.313181,173.532323 895.762737,174.082438 C896.212293,174.632552 896.519879,175.031823 896.685505,175.280261 C896.922113,175.256601 897.099567,175.24477 897.217871,175.24477 C897.336175,175.24477 897.513629,175.256601 897.750237,175.280261 C898.353588,174.440302 898.897779,173.777809 899.382826,173.292762 L899.489299,173.25727 C899.536621,173.25727 900.270096,173.671329 901.689746,174.499458 C901.737067,174.534949 901.760728,174.576355 901.760728,174.623677 C901.760728,174.919437 901.459057,175.735723 900.855706,177.07256 C901.056823,177.34466 901.234276,177.652246 901.388072,177.995328 C903.150804,178.172784 904.032156,178.356153 904.032156,178.54544 Z" id="-copy-3" fill="#E04733"></path> + </g> + </g> + </g> +</svg>
\ No newline at end of file diff --git a/doc/ci/review_apps/img/review_apps_preview_in_mr.png b/doc/ci/review_apps/img/review_apps_preview_in_mr.png Binary files differindex 7d0923f198f..3e6506a6a3a 100644 --- a/doc/ci/review_apps/img/review_apps_preview_in_mr.png +++ b/doc/ci/review_apps/img/review_apps_preview_in_mr.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 1b17f6ac5ea..64be011008e 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -1,95 +1,94 @@ -# Getting started with Review Apps +# Review Apps -> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab -> 8.13 and 8.14. -> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by -> [Fourchette]. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14. +> - Inspired by [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), which itself was inspired by [Fourchette](https://github.com/rainforestapp/fourchette). -The basis of Review Apps is the [dynamic environments] which allow you to create -a new environment (dynamically) for each one of your branches. +For a video introduction to Review Apps, see [8.14 Webcast: Review Apps & Time Tracking Beta (EE) - GitLab Release](https://www.youtube.com/watch?v=CteZol_7pxo). -A Review App can then be visible as a link when you visit the [merge request] -relevant to the branch. That way, you are able to see live all changes introduced -by the merge request changes. Reviewing anything, from performance to interface -changes, becomes much easier with a live environment and as such, Review Apps -can make a huge impact on your development flow. +## Overview -They mostly make sense to be used with web applications, but you can use them -any way you'd like. +Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes. -## Overview +Review Apps: + +- Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests. +- Allow designers and product manages to see your changes without needing to check out your branch and run your changes in a sandbox environment. +- Are fully integrated with the [GitLab DevOps LifeCycle](../../README.md#complete-devops-with-gitlab). +- Allow you to deploy your changes wherever you want. + + + +Reviewing anything, from performance to interface changes, becomes much easier with a live environment and so Review Apps can make a large impact on your development flow. -Simply put, a Review App is a mapping of a branch with an environment as there -is a 1:1 relation between them. +## What are Review Apps? -Here's an example of what it looks like when viewing a merge request with a -dynamically set environment. +A Review App is a mapping of a branch with an [environment](../environments.md). The following is an example of a merge request with an environment set dynamically.  -In the image above you can see that the `add-new-line` branch was successfully -built and deployed under a dynamic environment and can be previewed with an -also dynamically URL. +In this example, you can see a branch was: + +- Successfully built. +- Deployed under a dynamic environment that can be reached by clicking on the **View app** button. + +## How do Review Apps work? + +The basis of Review Apps in GitLab is [dynamic environments](../environments.md#dynamic-environments), which allow you to dynamically create a new environment for each branch. + +Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment. -The details of the Review Apps implementation depend widely on your real -technology stack and on your deployment process. The simplest case is to -deploy a simple static HTML website, but it will not be that straightforward -when your app is using a database for example. To make a branch be deployed -on a temporary instance and booting up this instance with all required software -and services automatically on the fly is not a trivial task. However, it is -doable, especially if you use Docker, or at least a configuration management -tool like Chef, Puppet, Ansible or Salt. +## Use cases -## Prerequisites +Some supported use cases include the: -To get a better understanding of Review Apps, you must first learn how -environments and deployments work. The following docs will help you grasp that -knowledge: +- Simple case of deploying a simple static HTML website. +- More complicated case of an application that uses a database. Deploying a branch on a temporary instance and booting up this instance with all required software and services automatically on the fly is not a trivial task. However, it is possible, especially if you use Docker or a configuration management tool like Chef, Puppet, Ansible, or Salt. -1. First, learn about [environments][] and their role in the development workflow. -1. Then make a small stop to learn about [CI variables][variables] and how they - can be used in your CI jobs. -1. Next, explore the [`environment` syntax][yaml-env] as defined in `.gitlab-ci.yml`. - This will be your primary reference when you are finally comfortable with - how environments work. -1. Additionally, find out about [manual actions][] and how you can use them to - deploy to critical environments like production with the push of a button. -1. And as a last step, follow the [example tutorials](#examples) which will - guide you step by step to set up the infrastructure and make use of - Review Apps. +Review Apps usually make sense with web applications, but you can use them any way you'd like. -## Configuration +## Implementing Review Apps -The configuration of Review apps depends on your technology stack and your -infrastructure. Read the [dynamic environments] documentation to understand -how to define and create them. +Implementing Review Apps depends on your: -## Creating and destroying Review Apps +- Technology stack. +- Deployment process. -The creation and destruction of a Review App is defined in `.gitlab-ci.yml` -at a job level under the `environment` keyword. +### Prerequisite Knowledge -Check the [environments] documentation how to do so. +To get a better understanding of Review Apps, review documentation on how environments and deployments work. Before you implement your own Review Apps: -## A simple workflow +1. Learn about [environments](../environments.md) and their role in the development workflow. +1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. +1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. +1. Additionally, find out about [manual actions](../environments.md#manual-actions) and how you can use them to deploy to critical environments like production with the push of a button. +1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. -The process of adding Review Apps in your workflow would look like: +### Configuring dynamic environments + +Configuring Review Apps dynamic environments depends on your technology stack and infrastructure. + +For more information, see [dynamic environments](../environments.md#dynamic-environments) documentation to understand how to define and create them. + +### Creating and destroying Review Apps + +Creating and destroying Review Apps is defined in `.gitlab-ci.yml` at a job level under the `environment` keyword. + +For more information, see [Introduction to environments and deployments](../environments.md). + +### Adding Review Apps to your workflow + +The process of adding Review Apps in your workflow is as follows: 1. Set up the infrastructure to host and deploy the Review Apps. -1. [Install][install-runner] and [configure][conf-runner] a Runner that does - the deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the predefined - [predefined CI environment variable][variables] `${CI_COMMIT_REF_NAME}` to - create dynamic environments and restrict it to run only on branches. -1. Optionally set a job that [manually stops][manual-env] the Review Apps. +1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment. +1. Set up a job in `.gitlab-ci.yml` that uses the predefined [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. +1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps. -From there on, you would follow the branched Git flow: +After adding Review Apps to your workflow, you follow the branched Git flow. That is: -1. Push a branch and let the Runner deploy the Review App based on the `script` - definition of the dynamic environment job. -1. Wait for the Runner to build and/or deploy your web app. -1. Click on the link that's present in the MR related to the branch and see the - changes live. +1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job. +1. Wait for the Runner to build and deploy your web application. +1. Click on the link that provided in the merge request related to the branch to see the changes live. ## Limitations @@ -97,27 +96,9 @@ Check the [environments limitations](../environments.md#limitations). ## Examples -A list of examples used with Review Apps can be found below: - -- [Use with NGINX][app-nginx] - Use NGINX and the shell executor of GitLab Runner - to deploy a simple HTML website. - -And below is a soon to be added examples list: - -- Use with Amazon S3 -- Use on Heroku with dpl -- Use with OpenShift/kubernetes - -[app-nginx]: https://gitlab.com/gitlab-examples/review-apps-nginx -[ce-21971]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21971 -[dynamic environments]: ../environments.md#dynamic-environments -[environments]: ../environments.md -[fourchette]: https://github.com/rainforestapp/fourchette -[heroku-apps]: https://devcenter.heroku.com/articles/github-integration-review-apps -[manual actions]: ../environments.md#manual-actions -[merge request]: ../../user/project/merge_requests.md -[variables]: ../variables/README.md -[yaml-env]: ../yaml/README.md#environment -[install-runner]: https://docs.gitlab.com/runner/install/ -[conf-runner]: https://docs.gitlab.com/runner/commands/ -[manual-env]: ../environments.md#stopping-an-environment +The following are example projects that use Review Apps with: + +- [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). +- [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). + +See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 7859d2ec631..9c9ea651678 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -29,7 +29,7 @@ are: - **Specific Runners** are useful for jobs that have special requirements or for projects with a specific demand. If a job has certain requirements, you can set up the specific Runner with this in mind, while not having to do this for all - Runners. For example, if you want to deploy a certain project, you can setup + Runners. For example, if you want to deploy a certain project, you can set up a specific Runner to have the right credentials for this. The [usage of tags](#using-tags) may be useful in this case. Specific Runners process jobs using a [FIFO] queue. - **Group Runners** are useful when you have multiple projects under one group @@ -138,9 +138,9 @@ project without requiring your authorization, so use it with caution. An admin can enable/disable a specific Runner for projects: 1. Navigate to **Admin > Runners** -2. Find the Runner you wish to enable/disable -3. Click edit on the Runner -4. Click **Enable** or **Disable** on the project +1. Find the Runner you wish to enable/disable +1. Click edit on the Runner +1. Click **Enable** or **Disable** on the project ## Protected Runners @@ -222,7 +222,7 @@ should keep in mind. ### Using tags -You must setup a Runner to be able to run all the different types of jobs +You must set up a Runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it wasn't for tags. @@ -298,7 +298,7 @@ and using more secure [Runner Executors](https://docs.gitlab.com/runner/executor ### Forks Whenever a project is forked, it copies the settings of the jobs that relate -to it. This means that if you have shared Runners setup for a project and +to it. This means that if you have shared Runners set up for a project and someone forks that project, the shared Runners will also serve jobs of this project. @@ -312,7 +312,7 @@ We're always looking for contributions that can mitigate these If you think that registration token for a Project was revealed, you should reset them. It's recommended because such token can be used to register another -Runner to thi Project. It may be next used to obtain the values of secret +Runner to the Project. It may be next used to obtain the values of secret variables or clone the project code, that normally may be unavailable for the attacker. diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 338368dbbc9..b76f9618fc9 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -31,7 +31,7 @@ Database: el_duderino ``` If you are wondering why we used `mysql` for the `Host`, read more at -[How is service linked to the job](../docker/using_docker_images.md#how-is-service-linked-to-the-job). +[How services are linked to the job](../docker/using_docker_images.md#how-services-are-linked-to-the-job). You can also use any other docker image available on [Docker Hub][hub-mysql]. For example, to use MySQL 5.5 the service becomes `mysql:5.5`. diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index 554c321fd0c..36f71427ae7 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -43,7 +43,7 @@ sudo apt-get install redis-server Verify that you can connect to the server with the `gitlab-runner` user: ```bash -# Try connecting the the Redis server +# Try connecting the Redis server sudo -u gitlab-runner -H redis-cli # Quit the session diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index cf92d90ba30..bffb0121603 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -2,7 +2,7 @@ > **Notes**: > -> - [Introduced][ci-229] in GitLab CE 7.14. +> - [Introduced](https://about.gitlab.com/2015/08/22/gitlab-7-14-released/) in GitLab 7.14. > - GitLab 8.12 has a completely redesigned job permissions system. Read all > about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). @@ -154,10 +154,10 @@ This information is also exposed in the UI. Using trigger variables can be proven useful for a variety of reasons: -* Identifiable jobs. Since the variable is exposed in the UI you can know +- Identifiable jobs. Since the variable is exposed in the UI you can know why the rebuild was triggered if you pass a variable that explains the purpose. -* Conditional job processing. You can have conditional jobs that run whenever +- Conditional job processing. You can have conditional jobs that run whenever a certain variable is present. Consider the following `.gitlab-ci.yml` where we set three @@ -221,7 +221,6 @@ removed with one of the future versions of GitLab. You are advised to [take ownership](#taking-ownership) of any legacy triggers. [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 -[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 [ee]: https://about.gitlab.com/pricing/ [variables]: ../variables/README.md [predef]: ../variables/README.md#predefined-variables-environment-variables diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index f11949da64e..bdbcf8c9435 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -65,6 +65,8 @@ future GitLab releases.** | **CI_JOB_NAME** | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | | **CI_JOB_STAGE** | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | | **CI_JOB_TOKEN** | 9.0 | 1.2 | Token used for authenticating with the [GitLab Container Registry][registry] and downloading [dependent repositories][dependent-repositories] | +| **CI_NODE_INDEX** | 11.5 | all | Index of the job in the job set. If the job is not parallelized, this variable is not set. | +| **CI_NODE_TOTAL** | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | **CI_JOB_URL** | 11.1 | 0.5 | Job details URL | | **CI_REPOSITORY_URL** | 9.0 | all | The URL to clone the Git repository | | **CI_RUNNER_DESCRIPTION** | 8.10 | 0.5 | The description of the runner as saved in GitLab | @@ -94,6 +96,9 @@ future GitLab releases.** | **CI_SERVER_NAME** | all | all | The name of CI server that is used to coordinate jobs | | **CI_SERVER_REVISION** | all | all | GitLab revision that is used to schedule jobs | | **CI_SERVER_VERSION** | all | all | GitLab version that is used to schedule jobs | +| **CI_SERVER_VERSION_MAJOR** | 11.4 | all | GitLab version major component | +| **CI_SERVER_VERSION_MINOR** | 11.4 | all | GitLab version minor component | +| **CI_SERVER_VERSION_PATCH** | 11.4 | all | GitLab version patch component | | **CI_SHARED_ENVIRONMENT** | all | 10.1 | Marks that the job is executed in a shared environment (something that is persisted across CI invocations like `shell` or `ssh` executor). If the environment is shared, it is set to true, otherwise it is not defined at all. | | **GET_SOURCES_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to fetch sources running a job | | **GITLAB_CI** | all | all | Mark that job is executed in GitLab CI environment | @@ -194,7 +199,7 @@ Likewise, group-level variables can be added by going to your group's **Settings > CI/CD**, then finding the section called **Variables**. Any variables of [subgroups] will be inherited recursively. - + Once you set them, they will be available for all subsequent pipelines. You can also [protect your variables](#protected-variables). @@ -323,6 +328,12 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_SERVER_NAME='GitLab CI' ++ export CI_SERVER_VERSION= ++ CI_SERVER_VERSION= +++ export CI_SERVER_VERSION_MAJOR= +++ CI_SERVER_VERSION_MAJOR= +++ export CI_SERVER_VERSION_MINOR= +++ CI_SERVER_VERSION_MINOR= +++ export CI_SERVER_VERSION_PATCH= +++ CI_SERVER_VERSION_PATCH= ++ export CI_SERVER_REVISION= ++ CI_SERVER_REVISION= ++ export GITLAB_CI=true @@ -468,6 +479,9 @@ export CI_SERVER="yes" export CI_SERVER_NAME="GitLab" export CI_SERVER_REVISION="70606bf" export CI_SERVER_VERSION="8.9.0" +export CI_SERVER_VERSION_MAJOR="8" +export CI_SERVER_VERSION_MINOR="9" +export CI_SERVER_VERSION_PATCH="0" export GITLAB_USER_ID="42" export GITLAB_USER_EMAIL="user@example.com" export CI_REGISTRY_USER="gitlab-ci-token" diff --git a/doc/ci/variables/img/secret_variables.png b/doc/ci/variables/img/secret_variables.png Binary files differdeleted file mode 100644 index 3c1aa361dc2..00000000000 --- a/doc/ci/variables/img/secret_variables.png +++ /dev/null diff --git a/doc/ci/variables/img/variables.png b/doc/ci/variables/img/variables.png Binary files differnew file mode 100644 index 00000000000..d2dc99bbac0 --- /dev/null +++ b/doc/ci/variables/img/variables.png diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index b0d2ea6484d..1d98e8426fe 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -17,8 +17,8 @@ There are two places defined variables can be used. On the: | Definition | Can be expanded? | Expansion place | Description | |--------------------------------------|-------------------|-----------------|--------------| -| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<ul><li>**Supported:** all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules)</li><li>**Not suported:** variables defined in Runner's `config.toml` and variables created in job's `script`</li></ul> | -| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion **doesn't support**: <ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | +| `environment:url` | yes | GitLab | The variable expansion is made by GitLab's [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism).<ul><li>Supported: all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules)</li><li>Not supported: variables defined in Runner's `config.toml` and variables created in job's `script`</li></ul> | +| `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support: <ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | | `variables` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `services:[]` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -26,7 +26,7 @@ There are two places defined variables can be used. On the: | `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment | | `script`, `before_script`, `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) | -| `only:variables:[]`, `except:variables:[]` | no | n/a | The variable must be in the form of `$variable`.<br/>**Not supported:**<ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | +| `only:variables:[]`, `except:variables:[]` | no | n/a | The variable must be in the form of `$variable`.<br/>Not supported:<ul><li>variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`)</li><li>any other variables related to environment (currently only `CI_ENVIRONMENT_URL`)</li><li>[persisted variables](#persisted-variables)</li></ul> | ### `config.toml` file @@ -55,9 +55,9 @@ since the expansion is done in GitLab before any Runner will get the job. ### GitLab Runner internal variable expansion mechanism -- **Supported:** project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and +- Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and variables from triggers, pipeline schedules, and manual pipelines. -- **Not supported:** variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). +- Not supported: variables defined inside of scripts (e.g., `export MY_VARIABLE="test"`). The Runner uses Go's `os.Expand()` method for variable expansion. It means that it will handle only variables defined as `$variable` and `${variable}`. What's also important, is that @@ -73,7 +73,7 @@ by bash/sh (leaving empty strings or some values depending whether the variables defined or not), but will not work with Windows' cmd/PowerShell, since these shells are using a different variables syntax. -**Supported:** +Supported: - The `script` may use all available variables that are default for the shell (e.g., `$PATH` which should be present in all bash/sh shells) and all variables defined by GitLab CI/CD (project/group variables, @@ -106,7 +106,9 @@ The following variables are known as "persisted": They are: -- **Supported** for all definitions as [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "Runner". -- **Not supported:** - - By the definitions [described in the table](#gitlab-ci-yml-file) where the "Expansion place" is "GitLab". +- Supported for definitions where the ["Expansion place"](#gitlab-ci-yml-file) is: + - Runner. + - Script execution shell. +- Not supported: + - For definitions where the ["Expansion place"](#gitlab-ci-yml-file) is GitLab. - In the `only` and `except` [variables expressions](README.md#variables-expressions). diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 31a065bc196..af7e41db443 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -74,7 +74,8 @@ A job is defined by a list of parameters that define the job behavior. | after_script | no | Override a set of commands that are executed after job | | environment | no | Defines a name of environment to which deployment is done by this job | | coverage | no | Define code coverage settings for a given job | -| retry | no | Define how many times a job can be auto-retried in case of a failure | +| retry | no | Define when and how many times a job can be auto-retried in case of a failure | +| parallel | no | Defines how many instances of a job should be run in parallel | ### `extends` @@ -102,10 +103,13 @@ rspec: - $RSPEC ``` -In the example above, the `rspec` job is going to inherit from the `.tests` -template job. GitLab will perform a reverse deep merge, which means that it will -merge the `rspec` contents into `.tests` recursively, and this is going to result in -the following `rspec` job: +In the example above, the `rspec` job inherits from the `.tests` template job. +GitLab will perform a reverse deep merge based on the keys. GitLab will: + +- Merge the `rspec` contents into `.tests` recursively. +- Not merge the values of the keys. + +This results in the following `rspec` job: ```yaml rspec: @@ -118,6 +122,11 @@ rspec: - $RSPEC ``` +NOTE: **Note:** +Note that `script: rake test` has been overwritten by `script: rake rspec`. + +If you do want to include the `rake test`, have a look at [before_script-and-after_script](#before_script-and-after_script). + `.tests` in this example is a [hidden key](#hidden-keys-jobs), but it's possible to inherit from regular jobs as well. @@ -188,7 +197,7 @@ used for time of the job. The configuration of this feature is covered in ## `before_script` and `after_script` -> Introduced in GitLab 8.7 and requires Gitlab Runner v1.2 +> Introduced in GitLab 8.7 and requires GitLab Runner v1.2 `before_script` is used to define the command that should be run before all jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts). @@ -325,7 +334,7 @@ There are a few rules that apply to the usage of job policy: * `only` and `except` are inclusive. If both `only` and `except` are defined in a job specification, the ref is filtered by `only` and `except`. -* `only` and `except` allow the use of regular expressions. +* `only` and `except` allow the use of regular expressions (using [Ruby regexp syntax](https://ruby-doc.org/core/Regexp.html)). * `only` and `except` allow to specify a repository path to filter jobs for forks. @@ -387,9 +396,11 @@ except master. > `refs` and `kubernetes` policies introduced in GitLab 10.0 > > `variables` policy introduced in 10.7 +> +> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in 11.4 CAUTION: **Warning:** -This an _alpha_ feature, and it it subject to change at any time without +This an _alpha_ feature, and it is subject to change at any time without prior notice! Since GitLab 10.0 it is possible to define a more elaborate only/except job @@ -398,10 +409,15 @@ policy configuration. GitLab now supports both, simple and complex strategies, so it is possible to use an array and a hash configuration scheme. -Three keys are now available: `refs`, `kubernetes` and `variables`. +Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`. + +### `refs` and `kubernetes` + Refs strategy equals to simplified only/except configuration, whereas kubernetes strategy accepts only `active` keyword. +### `only:variables` + `variables` keyword is used to define variables expressions. In other words you can use predefined variables / project / group or environment-scoped variables to define an expression GitLab is going to @@ -445,6 +461,50 @@ end-to-end: Learn more about variables expressions on [a separate page][variables-expressions]. +### `only:changes` + +Using `changes` keyword with `only` or `except` makes it possible to define if +a job should be created based on files modified by a git push event. + +For example: + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + only: + changes: + - Dockerfile + - docker/scripts/* + - dockerfiles/**/* + - more_scripts/*.{rb,py,sh} +``` + +In the scenario above, if you are pushing multiple commits to GitLab to an +existing branch, GitLab creates and triggers `docker build` job, provided that +one of the commits contains changes to either: + +- The `Dockerfile` file. +- Any of the files inside `docker/scripts/` directory. +- Any of the files and subfolders inside `dockerfiles` directory. +- Any of the files with `rb`, `py`, `sh` extensions inside `more_scripts` directory. + +CAUTION: **Warning:** +There are some caveats when using this feature with new branches and tags. See +the section below. + +#### Using `changes` with new branches and tags + +If you are pushing a **new** branch or a **new** tag to GitLab, the policy +always evaluates to true and GitLab will create a job. This feature is not +connected with merge requests yet, and because GitLab is creating pipelines +before an user can create a merge request we don't know a target branch at +this point. + +Without a target branch, it is not possible to know what the common ancestor is, +thus we always create a job in that case. This feature works best for stable +branches like `master` because in that case GitLab uses the previous commit +that is present in a branch to compare against the latest SHA that was pushed. + ## `tags` `tags` is used to select specific Runners from the list of all Runners that are @@ -492,6 +552,7 @@ osx job: `allow_failure` is used when you want to allow a job to fail without impacting the rest of the CI suite. Failed jobs don't contribute to the commit status. +The default value is `false`. When enabled and the job fails, the pipeline will be successful/green for all intents and purposes, but a "CI build passed with warnings" message will be @@ -617,6 +678,42 @@ user wants to trigger an action. In other words, in order to trigger a manual action assigned to a branch that the pipeline is running for, user needs to have ability to merge to this branch. +### `when:delayed` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4. + +Delayed job are for executing scripts after a certain period. +This is useful if you want to avoid jobs entering `pending` state immediately. + +You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is +provided. `start_in` key must be less than or equal to one hour. Examples of valid values include: + +- `10 seconds` +- `30 minutes` +- `1 hour` + +When there is a delayed job in a stage, the pipeline will not progress until the delayed job has finished. +This means this keyword can also be used for inserting delays between different stages. + +The timer of a delayed job starts immediately after the previous stage has completed. +Similar to other types of jobs, a delayed job's timer will not start unless the previous stage passed. + +The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: + +```yaml +timed rollout 10%: + stage: deploy + script: echo 'Rolling out 10% ...' + when: delayed + start_in: 30 minutes +``` + +You can stop the active timer of a delayed job by clicking the **Unschedule** button. +This job will never be executed in the future unless you execute the job manually. + +You can start a delayed job immediately by clicking the **Play** button. +GitLab runner will pick your job soon and start the job. + ## `environment` > **Notes:** @@ -717,7 +814,7 @@ deploy to production: > defined, GitLab will automatically trigger a stop action when the associated > branch is deleted. -Closing (stoping) environments can be achieved with the `on_stop` keyword defined under +Closing (stopping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close the environment. @@ -1200,13 +1297,17 @@ GitLab 11.2. Requires GitLab Runner 11.2 and above. The `reports` keyword is used for collecting test reports from jobs and exposing them in GitLab's UI (merge requests, pipeline views). Read how to use -this with [JUnit reports](#artifacts-reports-junit). +this with [JUnit reports](#artifactsreportsjunit). NOTE: **Note:** The test reports are collected regardless of the job results (success or failure). You can use [`artifacts:expire_in`](#artifacts-expire_in) to set up an expiration date for their artifacts. +NOTE: **Note:** +If you also want the ability to browse the report output files, include the +[`artifacts:paths`](#artifactspaths) keyword. + #### `artifacts:reports:junit` > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20390) in @@ -1215,8 +1316,9 @@ GitLab 11.2. Requires GitLab Runner 11.2 and above. The `junit` report collects [JUnit XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html) as artifacts. Although JUnit was originally developed in Java, there are many [third party ports](https://en.wikipedia.org/wiki/JUnit#Ports) for other -languages like Javascript, Python, Ruby, etc. +languages like JavaScript, Python, Ruby, etc. +See [JUnit test reports](../junit_test_reports.md) for more details and examples. Below is an example of collecting a JUnit XML file from Ruby's RSpec test tool: ```yaml @@ -1233,8 +1335,6 @@ rspec: The collected JUnit reports will be uploaded to GitLab as an artifact and will be automatically shown in merge requests. -For more examples, see [JUnit test reports](../junit_test_reports.md). - NOTE: **Note:** In case the JUnit tool you use exports to multiple XML files, you can specify multiple test report paths within a single job and they will be automatically @@ -1242,6 +1342,81 @@ concatenated into a single file. Use a filename pattern (`junit: rspec-*.xml`), an array of filenames (`junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]`), or a combination thereof (`junit: [rspec.xml, test-results/TEST-*.xml]`). +#### `artifacts:reports:codequality` **[STARTER]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `codequality` report collects [CodeQuality issues](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html) +as artifacts. + +The collected Code Quality report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests. + +#### `artifacts:reports:sast` **[ULTIMATE]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `sast` report collects [SAST vulnerabilities](https://docs.gitlab.com/ee/user/project/merge_requests/sast.html) +as artifacts. + +The collected SAST report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests, pipeline view and provide data for security +dashboards. + +#### `artifacts:reports:dependency_scanning` **[ULTIMATE]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `dependency_scanning` report collects [Dependency Scanning vulnerabilities](https://docs.gitlab.com/ee/user/project/merge_requests/dependency_scanning.html) +as artifacts. + +The collected Dependency Scanning report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests, pipeline view and provide data for security +dashboards. + +#### `artifacts:reports:container_scanning` **[ULTIMATE]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `container_scanning` report collects [Container Scanning vulnerabilities](https://docs.gitlab.com/ee/user/project/merge_requests/container_scanning.html) +as artifacts. + +The collected Container Scanning report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests, pipeline view and provide data for security +dashboards. + +#### `artifacts:reports:dast` **[ULTIMATE]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `dast` report collects [DAST vulnerabilities](https://docs.gitlab.com/ee/user/project/merge_requests/dast.html) +as artifacts. + +The collected DAST report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests, pipeline view and provide data for security +dashboards. + +#### `artifacts:reports:license_management` **[ULTIMATE]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `license_management` report collects [Licenses](https://docs.gitlab.com/ee/user/project/merge_requests/license_management.html) +as artifacts. + +The collected License Management report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests, pipeline view and provide data for security +dashboards. + +#### `artifacts:reports:performance` **[PREMIUM]** + +> Introduced in GitLab 11.5. Requires GitLab Runner 11.5 and above. + +The `performance` report collects [Performance metrics](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html) +as artifacts. + +The collected Performance report will be uploaded to GitLab as an artifact and will +be automatically shown in merge requests. + ## `dependencies` > Introduced in GitLab 8.6 and GitLab Runner v1.1.1. @@ -1338,18 +1513,20 @@ job1: ## `retry` > [Introduced][ce-12909] in GitLab 9.5. +> [Behaviour expanded](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21758) +> in GitLab 11.5 to control on which failures to retry. `retry` allows you to configure how many times a job is going to be retried in case of a failure. -When a job fails, and has `retry` configured it is going to be processed again +When a job fails and has `retry` configured, it is going to be processed again up to the amount of times specified by the `retry` keyword. If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried again. `retry` value has to be a positive integer, equal or larger than 0, but lower or equal to 2 (two retries maximum, three runs in total). -A simple example: +A simple example to retry in all failure cases: ```yaml test: @@ -1357,12 +1534,84 @@ test: retry: 2 ``` +By default, a job will be retried on all failure cases. To have a better control +on which failures to retry, `retry` can be a hash with the following keys: + +- `max`: The maximum number of retries. +- `when`: The failure cases to retry. + +To retry only runner system failures at maximum two times: + +```yaml +test: + script: rspec + retry: + max: 2 + when: runner_system_failure +``` + +If there is another failure, other than a runner system failure, the job will +not be retried. + +To retry on multiple failure cases, `when` can also be an array of failures: + +```yaml +test: + script: rspec + retry: + max: 2 + when: + - runner_system_failure + - stuck_or_timeout_failure +``` + +Possible values for `when` are: + +<!-- + Please make sure to update `RETRY_WHEN_IN_DOCUMENTATION` array in + `spec/lib/gitlab/ci/config/entry/retry_spec.rb` if you change any of + the documented values below. The test there makes sure that all documented + values are really valid as a config option and therefore should always + stay in sync with this documentation. + --> + +- `always`: Retry on any failure (default). +- `unknown_failure`: Retry when the failure reason is unknown. +- `script_failure`: Retry when the script failed. +- `api_failure`: Retry on API failure. +- `stuck_or_timeout_failure`: Retry when the job got stuck or timed out. +- `runner_system_failure`: Retry if there was a runner system failure (e.g. setting up the job failed). +- `missing_dependency_failure`: Retry if a dependency was missing. +- `runner_unsupported`: Retry if the runner was unsupported. + + +## `parallel` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22631) in GitLab 11.5. + +`parallel` allows you to configure how many instances of a job to run in +parallel. This value has to be greater than or equal to two (2) and less than or equal to 50. + +This creates N instances of the same job that run in parallel. They're named +sequentially from `job_name 1/N` to `job_name N/N`. + +For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.html#predefined-variables-environment-variables) are set. + +A simple example: + +```yaml +test: + script: rspec + parallel: 5 +``` + ## `include` -> Introduced in [GitLab Edition Premium][ee] 10.5. -> Available for Starter, Premium and Ultimate [versions][gitlab-versions] since 10.6. +> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. +> Available for Starter, Premium and Ultimate since 10.6. > Behaviour expanded in GitLab 10.8 to allow more flexible overriding. -> Available for Libre since [11.4](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21603) +> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21603) +to GitLab Core in 11.4 Using the `include` keyword, you can allow the inclusion of external YAML files. @@ -1388,6 +1637,10 @@ rspec: - bundle exec rspec ``` +NOTE: **Note:** +`include` requires the external YAML files to have the extensions `.yml` or `.yaml`. +The external file will not be included if the extension is missing. + You can define it either as a single string, or, in case you want to include more than one files, an array of different values . The following examples are both valid cases: @@ -1436,6 +1689,11 @@ include: NOTE: **Note:** The remote file must be publicly accessible through a simple GET request, as we don't support authentication schemas in the remote URL. + NOTE: **Note:** + In order to include files from another repository inside your local network, + you may need to enable the **Allow requests to the local network from hooks and services** checkbox + located in the **Settings > Network > Outbound requests** section within the **Admin area**. + --- @@ -1524,7 +1782,7 @@ stages: production: script: - - install_depedencies + - install_dependencies - deploy - notify_owner ``` @@ -1563,13 +1821,6 @@ These variables can be later used in all executed commands and scripts. The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them. -To turn off global defined variables in a specific job, define an empty hash: - -```yaml -job_name: - variables: {} -``` - Except for the user defined variables, there are also the ones [set up by the Runner itself](../variables/README.md#predefined-variables-environment-variables). One example would be `CI_COMMIT_REF_NAME` which has the value of @@ -1939,3 +2190,5 @@ CI with various languages. [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md [variables-expressions]: ../variables/README.md#variables-expressions +[ee]: https://about.gitlab.com/gitlab-ee/ +[gitlab-versions]: https://about.gitlab.com/products/ diff --git a/doc/development/README.md b/doc/development/README.md index 94e604d125d..bcf57a223f5 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -7,8 +7,8 @@ description: 'Learn how to contribute to GitLab.' ## Get started! -- Setup GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) -- [GitLab contributing guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md) +- Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) +- [GitLab contributing guide](contributing/index.md) - [Architecture](architecture.md) of GitLab - [Rake tasks](rake_tasks.md) for development @@ -23,13 +23,14 @@ description: 'Learn how to contribute to GitLab.' ## UX and frontend guides -- [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements +- [GitLab Design System](https://design.gitlab.com/) for building GitLab with existing CSS styles and elements - [Frontend guidelines](fe_guide/index.md) - [Emoji guide](fe_guide/emojis.md) ## Backend guides - [GitLab utilities](utilities.md) +- [Logging](logging.md) - [API styleguide](api_styleguide.md) Use this styleguide if you are contributing to the API. - [GraphQL API styleguide](api_graphql_styleguide.md) Use this @@ -50,6 +51,8 @@ description: 'Learn how to contribute to GitLab.' - [Permissions](permissions.md) - [Prometheus metrics](prometheus_metrics.md) - [Guidelines for reusing abstractions](reusing_abstractions.md) +- [DeclarativePolicy framework](policies.md) +- [Switching to Rails 5](switching_to_rails5.md) ## Performance guides diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index ea6f14da3b9..d1d2b8c4907 100644 --- a/doc/development/adding_database_indexes.md +++ b/doc/development/adding_database_indexes.md @@ -28,9 +28,9 @@ to filter data by. Instead one should ask themselves the following questions: 1. Can I write my query in such a way that it re-uses as many existing indexes as possible? -2. Is the data going to be large enough that using an index will actually be +1. Is the data going to be large enough that using an index will actually be faster than just iterating over the rows in the table? -3. Is the overhead of maintaining the index worth the reduction in query +1. Is the overhead of maintaining the index worth the reduction in query timings? We'll explore every question in detail below. @@ -62,7 +62,7 @@ In short: 1. Try to write your query in such a way that it re-uses as many existing indexes as possible. -2. Run the query using `EXPLAIN ANALYZE` and study the output to find the most +1. Run the query using `EXPLAIN ANALYZE` and study the output to find the most ideal query. ## Data Size diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 6c6e198a7c3..95722c027ba 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -379,7 +379,7 @@ let(:mutation) do ) end -it 'returns a successfull response' do +it 'returns a successful response' do post_graphql_mutation(mutation, current_user: user) expect(response).to have_gitlab_http_status(:success) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 66d8a4f2f6e..e65c5f05505 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -10,39 +10,182 @@ For information, see the [GitLab Release Process](https://gitlab.com/gitlab-org/ Both EE and CE require some add-on components called gitlab-shell and Gitaly. These components are available from the [gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master) and [gitaly](https://gitlab.com/gitlab-org/gitaly/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical. -## Physical office analogy +## GitLab Omnibus Component by Component -You can imagine GitLab as a physical office. +This document is designed to be consumed by systems adminstrators and GitLab Support Engineers who want to understand more about the internals of GitLab and how they work together. -**The repositories** are the goods GitLab handles. -They can be stored in a warehouse. -This can be either a hard disk, or something more complex, such as a NFS filesystem; +When deployed, GitLab should be considered the amalgamation of the below processes. When troubleshooting or debugging, be as specific as possible as to which component you are referencing. That should increase clarity and reduce confusion. -**Nginx** acts like the front-desk. -Users come to Nginx and request actions to be done by workers in the office; +### GitLab Process Descriptions -**The database** is a series of metal file cabinets with information on: - - The goods in the warehouse (metadata, issues, merge requests etc); - - The users coming to the front desk (permissions) +As of this writing, a fresh GitLab 11.3.0 install will show the following processes with `gitlab-ctl status`: -**Redis** is a communication board with “cubby holes” that can contain tasks for office workers; +``` +run: alertmanager: (pid 30829) 14207s; run: log: (pid 13906) 2432044s +run: gitaly: (pid 30771) 14210s; run: log: (pid 13843) 2432046s +run: gitlab-monitor: (pid 30788) 14209s; run: log: (pid 13868) 2432045s +run: gitlab-workhorse: (pid 30758) 14210s; run: log: (pid 13855) 2432046s +run: logrotate: (pid 30246) 3407s; run: log: (pid 13825) 2432047s +run: nginx: (pid 30849) 14207s; run: log: (pid 13856) 2432046s +run: node-exporter: (pid 30929) 14206s; run: log: (pid 13877) 2432045s +run: postgres-exporter: (pid 30935) 14206s; run: log: (pid 13931) 2432044s +run: postgresql: (pid 13133) 2432214s; run: log: (pid 13848) 2432046s +run: prometheus: (pid 30807) 14209s; run: log: (pid 13884) 2432045s +run: redis: (pid 30560) 14274s; run: log: (pid 13807) 2432047s +run: redis-exporter: (pid 30946) 14205s; run: log: (pid 13869) 2432045s +run: sidekiq: (pid 30953) 14205s; run: log: (pid 13810) 2432047s +run: unicorn: (pid 30960) 14204s; run: log: (pid 13809) 2432047s +``` + +### Layers + +GitLab can be considered to have two layers from a process perspective: + +- **Monitoring**: Anything from this layer is not required to deliver GitLab the application, but will allow administrators more insight into their infrastructure and what the service as a whole is doing. +- **Core**: Any process that is vital for the delivery of GitLab as a platform. If any of these processes halt there will be a GitLab outage. For the Core layer, you can further divide into: + - **Processors**: These processes are responsible for actually performing operations and presenting the service. + - **Data**: These services store/expose structured data for the GitLab service. + +### alertmanager + +- Omnibus configuration options +- Layer: Monitoring + +[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue gitlab-ce#45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. + +### gitaly + +- [Omnibus configuration options](https://gitlab.com/gitlab-org/gitaly/tree/master/doc/configuration) +- Layer: Core Service (Data) + +Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab. (Think GitLab.com or High Availablity Deployments) As of 11.3.0, This service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly). + +### gitlab-monitor + +- Omnibus configuration options +- Layer: Monitoring + +GitLab Monitor is a process disigned in house that allows us to export metrics about GitLab application internals to prometheus. You can read more [in the project's readme](https://gitlab.com/gitlab-org/gitlab-monitor) + +### gitlab-workhorse + +- Omnibus configuration options +- Layer: Core Service (Processor) + +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) is a program designed at GitLab to help alieviate pressure from unicorn. You can read more about the [historical reasons for developing](https://about.gitlab.com/2016/04/12/a-brief-history-of-gitlab-workhorse/). It's designed to act as a smart reverse proxy to help speed up GitLab as a whole. + +### logrotate + +- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate) +- Layer: Core Service + +GitLab is comprised of a large number of services that all log. We started bundling our own logrotate as of 7.4 to make sure we were logging responsibly. This is just a packaged version of the common opensource offering. + +### nginx + +- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/nginx.html) +- Layer: Core Service (Processor) + +Nginx as an ingress port for all HTTP requests and routes them to the approriate sub-systems within GitLab. We are bundling an unmodified version of the popular open source webserver. + +### node-exporter + +- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/node_exporter.html) +- Layer: Monitoring + +[Node Exporter](https://github.com/prometheus/node_exporter) is a Prometheus tool that gives us metrics on the underlying machine. (Think CPU/Disk/Load) It's just a packaged version of the common open source offering from the Prometheus project. + +### postgres-exporter + +- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/postgres_exporter.html) +- Layer: Monitoring + +[Postgres-exporter](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that will deliver data about Postgres to prometheus for use in Grafana Dashboards. + +### postgresql + +- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/database.html) +- Layer: Core Service (Data) + +GitLab packages the popular Database to provide storage for Application meta data and user information. + +### prometheus + +- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/) +- Layer: Monitoring + +Prometheus is a time-series tool that helps GitLab administrators expose metrics about the individual processes used to provide GitLab the service. + +### redis + +- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/redis.html) +- Layer: Core Service (Data) + +Redis is packaged to provide a place to store: + +- session data +- temporary cache information +- background job queues. + +### redis-exporter + +- [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/redis_exporter.html) +- Layer: Monitoring + +[Redis Exporter](https://github.com/oliver006/redis_exporter) is designed to give specific metrics about the Redis process to Prometheus so that we can graph these metrics in Graphana. + +### sidekiq + +- Omnibus configuration options +- Layer: Core Service (Processor) + +Sidekiq is a Ruby background job processor that pulls jobs from the redis queue and processes them. Background jobs allow GitLab to provide a faster request/response cycle by moving work into the background. + +### unicorn + +- [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/unicorn.html) +- Layer: Core Service (Processor) + +[Unicorn](https://bogomips.org/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. + +### Additional Processes + +### GitLab Pages + +TODO + +### Mattermost + +TODO + +## GitLab by Request Type + +GitLab provides two "interfaces" for end users to access the service: + +- Web HTTP Requests (Viewing the UI/API) +- Git HTTP/SSH Requests (Pushing/Pulling Git Data) + +It's important to understand the distinction as some processes are used in both and others are exclusive to a specific request type. + +### GitLab Web HTTP Request Cycle + +When making a request to an HTTP Endpoint (Think `/users/sign_in`) the request will take the following path through the GitLab Service: + +- nginx - Acts as our first line reverse proxy +- gitlab-workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on unicorn. +- unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn. +- Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retreive data. -**Sidekiq** is a worker that primarily handles sending out emails. -It takes tasks from the Redis communication board; -**A Unicorn worker** is a worker that handles quick/mundane tasks. -They work with the communication board (Redis). -Their job description: - - check permissions by checking the user session stored in a Redis “cubby hole”; - - make tasks for Sidekiq; - - fetch stuff from the warehouse or move things around in there; +### GitLab Git Request Cycle -**GitLab-shell** is a third kind of worker that takes orders from a fax machine (SSH) instead of the front desk (HTTP). -GitLab-shell communicates with Sidekiq via the “communication board” (Redis), and asks quick questions of the Unicorn workers either directly or via the front desk. +Below we describe the different pathing that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences. -**Gitaly** is a back desk that is specialized on reaching the disks to perform git operations efficiently and keep a copy of the result of costly operations. All git operations go through Gitaly. +### Web Request (80/443) +TODO -**GitLab Enterprise Edition (the application)** is the collection of processes and business practices that the office is run by. +### SSH Request (22) +TODO ## System Layout diff --git a/doc/development/automatic_ce_ee_merge.md b/doc/development/automatic_ce_ee_merge.md index f6509b5c1dd..58e08d432cc 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -17,6 +17,9 @@ This merge is done automatically in a 1. If all conflicts are resolved after your resolution is pushed, keep the merge request assigned to you: **you are now responsible for the merge request to be green** +1. If you are the last person to resolve the conflicts, the pipeline is green, + and you have merge rights, merge the MR, but **do not** choose to squash. + Otherwise, assign the MR to someone that can merge. 1. If you need any help, you can ping the current [release managers], or ask in the `#ce-to-ee` Slack channel @@ -63,7 +66,7 @@ EE version of your CE merge request. For each commit (except on `master`), the `ee_compat_check` CI job tries to detect if the current branch's changes will conflict during the CE->EE merge. -The job reports what files are conflicting and how to setup a merge request +The job reports what files are conflicting and how to set up a merge request against EE. #### How the job works diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md index 439d228baef..c5f6adfeaeb 100644 --- a/doc/development/build_test_package.md +++ b/doc/development/build_test_package.md @@ -4,12 +4,13 @@ While developing a new feature or modifying an existing one, it is helpful if an installable package (or a docker image) containing those changes is available for testing. For this very purpose, a manual job is provided in the GitLab CI/CD pipeline that can be used to trigger a pipeline in the omnibus-gitlab repository -that will create -1. A deb package for Ubuntu 16.04, available as a build artifact, and -2. A docker image, which is pushed to [Omnibus GitLab's container -registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry) -(images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the -commit which triggered the pipeline). +that will create: + +- A deb package for Ubuntu 16.04, available as a build artifact, and +- A docker image, which is pushed to [Omnibus GitLab's container + registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry) + (images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the + commit which triggered the pipeline). When you push a commit to either the gitlab-ce or gitlab-ee project, the pipeline for that commit will have a `build-package` manual action you can diff --git a/doc/development/changelog.md b/doc/development/changelog.md index 9e0c81b3d60..cd0a1f46d27 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -110,7 +110,8 @@ At this point the script would ask you to select the category of the change (map 4. New deprecation 5. Feature removal 6. Security fix -7. Other +7. Performance improvement +8. Other ``` The entry filename is based on the name of the current Git branch. If you run @@ -132,15 +133,15 @@ If you're working on the GitLab EE repository, the entry will be added to ### Arguments -| Argument | Shorthand | Purpose | -| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------- | -| [`--amend`] | | Amend the previous commit | -| [`--force`] | `-f` | Overwrite an existing entry | -| [`--merge-request`] | `-m` | Set merge request ID | -| [`--dry-run`] | `-n` | Don't actually write anything, just print | -| [`--git-username`] | `-u` | Use Git user.name configuration as the author | -| [`--type`] | `-t` | The category of the change, valid options are: added, fixed, changed, deprecated, removed, security, other | -| [`--help`] | `-h` | Print help message | +| Argument | Shorthand | Purpose | +| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| [`--amend`] | | Amend the previous commit | +| [`--force`] | `-f` | Overwrite an existing entry | +| [`--merge-request`] | `-m` | Set merge request ID | +| [`--dry-run`] | `-n` | Don't actually write anything, just print | +| [`--git-username`] | `-u` | Use Git user.name configuration as the author | +| [`--type`] | `-t` | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` | +| [`--help`] | `-h` | Print help message | [`--amend`]: #-amend [`--force`]: #-force-or-f diff --git a/doc/development/chaos_endpoints.md b/doc/development/chaos_endpoints.md new file mode 100644 index 00000000000..403a5b21827 --- /dev/null +++ b/doc/development/chaos_endpoints.md @@ -0,0 +1,117 @@ +# Generating chaos in a test GitLab instance + +As [Werner Vogels](https://twitter.com/Werner), the CTO at Amazon Web Services, famously put it, **Everything fails, all the time**. + +As a developer, it's as important to consider the failure modes in which your software will operate as much as normal operation. Doing so can mean the difference between a minor hiccup leading to a scattering of `500` errors experienced by a tiny fraction of users and a full site outage that affects all users for an extended period. + +To paraphrase [Tolstoy](https://en.wikipedia.org/wiki/Anna_Karenina_principle), _all happy servers are alike, but all failing servers are failing in their own way_. Luckily, there are ways we can attempt to simulate these failure modes, and the chaos endpoints are tools for assisting in this process. + +Currently, there are four endpoints for simulating the following conditions: + +- Slow requests. +- CPU-bound requests. +- Memory leaks. +- Unexpected process crashes. + +## Enabling chaos endpoints + +For obvious reasons, these endpoints are not enabled by default. They can be enabled by setting the `GITLAB_ENABLE_CHAOS_ENDPOINTS` environment variable to `1`. + +For example, if you're using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command: + +```bash +GITLAB_ENABLE_CHAOS_ENDPOINTS=1 gdk run +``` + +## Securing the chaos endpoints + +DANGER: **Danger:** +It is highly recommended that you secure access to the chaos endpoints using a secret token. This is recommended when enabling these endpoints locally and essential when running in a staging or other shared environment. You should not enable them in production unless you absolutely know what you're doing. + +A secret token can be set through the `GITLAB_CHAOS_SECRET` environment variable. For example, when using the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) this can be done with the following command: + +```bash +GITLAB_ENABLE_CHAOS_ENDPOINTS=1 GITLAB_CHAOS_SECRET=secret gdk run +``` + +Replace `secret` with your own secret token. + +## Invoking chaos + +Once you have enabled the chaos endpoints and restarted the application, you can start testing using the endpoints. + +## Memory leaks + +To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint. + +NOTE: **Note:** +The memory is not retained after the request finishes. Once the request has completed, the Ruby garbage collector will attempt to recover the memory. + +``` +GET /-/chaos/leakmem +GET /-/chaos/leakmem?memory_mb=1024 +GET /-/chaos/leakmem?memory_mb=1024&duration_s=50 +``` + +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ---------------------------------------------------------------------------------- | +| `memory_mb` | integer | no | How much memory, in MB, should be leaked. Defaults to 100MB. | +| `duration_s` | integer | no | Minimum duration, in seconds, that the memory should be retained. Defaults to 30s. | + +```bash +curl http://localhost:3000/-/chaos/leakmem?memory_mb=1024&duration_s=10 --header 'X-Chaos-Secret: secret' +``` + +## CPU spin + +This endpoint attempts to fully utilise a single core, at 100%, for the given period. + +Depending on your rack server setup, your request may timeout after a predermined period (normally 60 seconds). +If you're using Unicorn, this is done by killing the worker process. + +``` +GET /-/chaos/cpuspin +GET /-/chaos/cpuspin?duration_s=50 +``` + +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | --------------------------------------------------------------------- | +| `duration_s` | integer | no | Duration, in seconds, that the core will be utilised. Defaults to 30s | + +```bash +curl http://localhost:3000/-/chaos/cpuspin?duration_s=60 --header 'X-Chaos-Secret: secret' +``` + +## Sleep + +This endpoint is similar to the CPU Spin endpoint but simulates off-processor activity, such as network calls to backend services. It will sleep for a given duration. + +As with the CPU Spin endpoint, this may lead to your request timing out if duration exceeds the configured limit. + +``` +GET /-/chaos/sleep +GET /-/chaos/sleep?duration_s=50 +``` + +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ---------------------------------------------------------------------- | +| `duration_s` | integer | no | Duration, in seconds, that the request will sleep for. Defaults to 30s | + +```bash +curl http://localhost:3000/-/chaos/sleep?duration_s=60 --header 'X-Chaos-Secret: secret' +``` + +## Kill + +This endpoint will simulate the unexpected death of a worker process using a `kill` signal. + +NOTE: **Note:** +Since this endpoint uses the `KILL` signal, the worker is not given a chance to cleanup or shutdown. + +``` +GET /-/chaos/kill +``` + +```bash +curl http://localhost:3000/-/chaos/kill --header 'X-Chaos-Secret: secret' +``` diff --git a/doc/development/code_review.md b/doc/development/code_review.md index edf0b6f46df..7788d155154 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -1,55 +1,153 @@ # Code Review Guidelines +This guide contains advice and best practices for performing code review, and +having your code reviewed. + +All merge requests for GitLab CE and EE, whether written by a GitLab team member +or a volunteer contributor, must go through a code review process to ensure the +code is effective, understandable, maintainable, and secure. + ## Getting your merge request reviewed, approved, and merged -There are a few rules to get your merge request accepted: +You are strongly encouraged to get your code **reviewed** by a +[reviewer](https://about.gitlab.com/handbook/engineering/#reviewer) as soon as +there is any code to review, to get a second opinion on the chosen solution and +implementation, and an extra pair of eyes looking for bugs, logic problems, or +uncovered edge cases. The reviewer can be from a different team, but it is +recommended to pick someone who knows the domain well. You can read more about the +importance of involving reviewer(s) in the section on the responsibility of the author below. + +If you need some guidance (e.g. it's your first merge request), feel free to ask +one of the [Merge request coaches][team]. + +If you need assistance with security scans or comments, feel free to include the +Security Team (`@gitlab-com/gl-security`) in the review. + +Depending on the areas your merge request touches, it must be **approved** by one +or more [maintainers](https://about.gitlab.com/handbook/engineering/#maintainer): + +For approvals, we use the approval functionality found in the merge request +widget. Reviewers can add their approval by [approving additionally](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html#adding-or-removing-an-approval). + +Getting your merge request **merged** also requires a maintainer. If it requires +more than one approval, the last maintainer to review and approve it will also merge it. + +### Approval guidelines -1. Your merge request should only be **merged by a [maintainer][team]**. - 1. If your merge request includes only backend changes [^1], it must be - **approved by a [backend maintainer][projects]**. - 1. If your merge request includes only frontend changes [^1], it must be - **approved by a [frontend maintainer][projects]**. - 1. If your merge request includes UX changes [^1], it must - be **approved by a [UX team member][team]**. +As described in the section on the responsibility of the maintainer below, you +are recommended to get your merge request approved and merged by maintainer(s) +from teams other than your own. + + 1. If your merge request includes backend changes [^1], it must be + **approved by a [backend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_backend)**. + 1. If your merge request includes frontend changes [^1], it must be + **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_frontend)**. + 1. If your merge request includes UX changes [^1], it must be + **approved by a [UX team member][team]**. 1. If your merge request includes adding a new JavaScript library [^1], it must be **approved by a [frontend lead][team]**. 1. If your merge request includes adding a new UI/UX paradigm [^1], it must be **approved by a [UX lead][team]**. - 1. If your merge request includes frontend and backend changes [^1], it must - be **approved by a [frontend and a backend maintainer][projects]**. - 1. If your merge request includes UX and frontend changes [^1], it must - be **approved by a [UX team member and a frontend maintainer][team]**. - 1. If your merge request includes UX, frontend and backend changes [^1], it must - be **approved by a [UX team member, a frontend and a backend maintainer][team]**. - 1. If your merge request includes a new dependency or a filesystem change, it must - be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) -1. To lower the amount of merge requests maintainers need to review, you can - ask or assign any [reviewers][projects] for a first review. - 1. If you need some guidance (e.g. it's your first merge request), feel free - to ask one of the [Merge request coaches][team]. - 1. It is recommended that you assign a maintainer that is from a different team than your own. - This ensures that all code across GitLab is consistent and can be easily understood by all contributors. - -1. Keep in mind that maintainers are also going to perform a final code review. - The ideal scenario is that the reviewer has already addressed any concerns - the maintainer would have found, and the maintainer only has to perform the - merge, but be prepared for further review comments. - -For more guidance, see [CONTRIBUTING.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md). + 1. If your merge request includes a new dependency or a filesystem change, it must be + **approved by a [Distribution team member][team]**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/) for more details. -## Best practices +#### Security requirements -This guide contains advice and best practices for performing code review, and -having your code reviewed. + 1. If your merge request is processing, storing, or transferring any kind of [RED or ORANGE data](https://docs.google.com/document/d/15eNKGA3zyZazsJMldqTBFbYMnVUSQSpU14lo22JMZQY/edit) (this is a confidential document), it must be + **approved by a [Security Engineer][team]**. + 1. If your merge request involves implementing, utilizing, or is otherwise related to any type of authentication, authorization, or session handling mechanism, it must be + **approved by a [Security Engineer][team]**. + 1. If your merge request has a goal which requires a cryptographic function such as: confidentiality, integrity, authentication, or non-repudiation, it must be + **approved by a [Security Engineer][team]**. -All merge requests for GitLab CE and EE, whether written by a GitLab team member -or a volunteer contributor, must go through a code review process to ensure the -code is effective, understandable, and maintainable. +### The responsibility of the merge request author + +The responsibility to find the best solution and implement it lies with the +merge request author. + +Before assigning a merge request to a maintainer for approval and merge, they +should be confident that it actually solves the problem it was meant to solve, +that it does so in the most appropriate way, that it satisfies all requirements, +and that there are no remaining bugs, logical problems, uncovered edge cases, +or known vulnerabilities. The merge request should also have a completed task +list in its description and a passing CI pipeline to avoid unnecessary back and +forth. + +To reach the required level of confidence in their solution, an author is expected +to involve other people in the investigation and implementation processes as +appropriate. + +They are encouraged to reach out to domain experts to discuss different solutions +or get an implementation reviewed, to product managers and UX designers to clear +up confusion or verify that the end result matches what they had in mind, to +database specialists to get input on the data model or specific queries, or to +any other developer to get an in-depth review of the solution. + +If an author is unsure if a merge request needs a domain expert's opinion, that's +usually a pretty good sign that it does, since without it the required level of +confidence in their solution will not have been reached. -Any developer can, and is encouraged to, perform code review on merge requests -of colleagues and contributors. However, the final decision to accept a merge -request is up to one the project's maintainers, denoted on the -[engineering projects][projects]. +Before the review, the author is requested to submit comments on the merge +request diff alerting the reviewer to anything important as well as for anything +that demands further explanation or attention. Examples of content that may +warrant a comment could be: + +- The addition of a linting rule (Rubocop, JS etc) +- The addition of a library (Ruby gem, JS lib etc) +- Where not obvious, a link to the parent class or method +- Any benchmarking performed to complement the change +- Potentially insecure code + +Do not add these comments directly to the source code, unless the +reviewer requires you to do so. + +This +[saves reviewers time and helps authors catch mistakes earlier](https://www.ibm.com/developerworks/rational/library/11-proven-practices-for-peer-review/index.html#__RefHeading__97_174136755). + +### The responsibility of the maintainer + +Maintainers are responsible for the overall health, quality, and consistency of +the GitLab codebase, across domains and product areas. + +Consequently, their reviews will focus primarily on things like overall +architecture, code organization, separation of concerns, tests, DRYness, +consistency, and readability. + +Since a maintainer's job only depends on their knowledge of the overall GitLab +codebase, and not that of any specific domain, they can review, approve and merge +merge requests from any team and in any product area. + +In fact, authors are encouraged to get their merge requests merged by maintainers +from teams other than their own, to ensure that all code across GitLab is consistent +and can be easily understood by all contributors, from both inside and outside the +company, without requiring team-specific expertise. + +Maintainers will do their best to also review the specifics of the chosen solution +before merging, but as they are not necessarily domain experts, they may be poorly +placed to do so without an unreasonable investment of time. In those cases, they +will defer to the judgment of the author and earlier reviewers and involved domain +experts, in favor of focusing on their primary responsibilities. + +If a developer who happens to also be a maintainer was involved in a merge request +as a domain expert and/or reviewer, it is recommended that they are not also picked +as the maintainer to ultimately approve and merge it. + +Maintainers should check before merging if the merge request is approved by the +required approvers. + +Maintainers must check before merging if the merge request is introducing new +vulnerabilities, by inspecting the list in the Merge Request [Security +Widget](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate). +When in doubt, a [Security Engineer][team] can be involved. The list of detected +vulnerabilities must be either empty or containing: + +- dismissed vulnerabilities in case of false positives +- vulnerabilities converted to issues + +Maintainers should **never** dismiss vulnerabilities to "empty" the list, +without duly verifying them. + +## Best practices ### Everyone @@ -97,6 +195,20 @@ first time. branch. Do not squash until the branch is ready to merge. Reviewers should be able to read individual updates based on their earlier feedback. +### Assigning a merge request for a review + +If you want to have your merge request reviewed, you can assign it to any reviewer. The list of reviewers can be found on [Engineering projects](https://about.gitlab.com/handbook/engineering/projects/) page. + +You can also use `ready for review` label. That means that your merge request is ready to be reviewed and any reviewer can pick it. It is recommended to use that label only if there isn't time pressure and make sure the merge request is assigned to a reviewer. + +When your merge request was reviewed and can be passed to a maintainer you can either pick a specific maintainer or use a label `ready for merge`. + +It is responsibility of the author of a merge request that the merge request is reviewed. If it stays in `ready for review` state too long it is recommended to assign it to a specific reviewer. + +### List of merge requests ready for review + +Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&label_name%5B%5D=ready%20for%20review) and assign any merge request they want to review. + ### Reviewing code Understand why the change is necessary (fixes a bug, improves the user @@ -121,6 +233,9 @@ experience, refactors the existing code). Then: subsequent revisions for anything that would be spotted after that. - Consider using the [Squash and merge][squash-and-merge] feature when the merge request has a lot of commits. + When merging code a maintainer should only use the squash feature if the + author has already set this option or if the merge request clearly contains a + messy commit history that is intended to be squashed. [squash-and-merge]: https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html#squash-and-merge @@ -162,41 +277,41 @@ Enterprise Edition instance. This has some implications: 1. **Query changes** should be tested to ensure that they don't result in worse performance at the scale of GitLab.com: 1. Generating large quantities of data locally can help. - 2. Asking for query plans from GitLab.com is the most reliable way to validate + 1. Asking for query plans from GitLab.com is the most reliable way to validate these. -2. **Database migrations** must be: +1. **Database migrations** must be: 1. Reversible. - 2. Performant at the scale of GitLab.com - ask a maintainer to test the + 1. Performant at the scale of GitLab.com - ask a maintainer to test the migration on the staging environment if you aren't sure. - 3. Categorised correctly: + 1. Categorised correctly: - Regular migrations run before the new code is running on the instance. - [Post-deployment migrations](post_deployment_migrations.md) run _after_ the new code is deployed, when the instance is configured to do that. - [Background migrations](background_migrations.md) run in Sidekiq, and should only be done for migrations that would take an extreme amount of time at GitLab.com scale. -3. **Sidekiq workers** +1. **Sidekiq workers** [cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues): 1. Sidekiq queues are not drained before a deploy happens, so there will be workers in the queue from the previous version of GitLab. - 2. If you need to change a method signature, try to do so across two releases, + 1. If you need to change a method signature, try to do so across two releases, and accept both the old and new arguments in the first of those. - 3. Similarly, if you need to remove a worker, stop it from being scheduled in + 1. Similarly, if you need to remove a worker, stop it from being scheduled in one release, then remove it in the next. This will allow existing jobs to execute. - 4. Don't forget, not every instance will upgrade to every intermediate version + 1. Don't forget, not every instance will upgrade to every intermediate version (some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so try to be liberal in accepting the old format if it is cheap to do so. -4. **Cached values** may persist across releases. If you are changing the type a +1. **Cached values** may persist across releases. If you are changing the type a cached value returns (say, from a string or nil to an array), change the cache key at the same time. -5. **Settings** should be added as a +1. **Settings** should be added as a [last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration). If you're adding a new setting in `gitlab.yml`: 1. Try to avoid that, and add to `ApplicationSetting` instead. - 2. Ensure that it is also + 1. Ensure that it is also [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). -6. **Filesystem access** can be slow, so try to avoid +1. **Filesystem access** can be slow, so try to avoid [shared files](shared_files.md) when an alternative solution is available. ### Credits diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md new file mode 100644 index 00000000000..b9c369286d2 --- /dev/null +++ b/doc/development/contributing/community_roles.md @@ -0,0 +1,16 @@ +### Community members & roles + +GitLab community members and their privileges/responsibilities. + +| Roles | Responsibilities | Requirements | +|-------|------------------|--------------| +| Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/team/). An expert on code reviews and knows the product/code base | +| Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/team/) | +| Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) | +| Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | + +[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). + +--- + +[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 45fe8c26591..79750878aac 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -1,13 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Implement design & UI elements](#implement-design--ui-elements) -- [Style guides](#style-guides) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Implement design & UI elements +# Implement design & UI elements For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/). @@ -22,7 +13,10 @@ There is a special type label called ~"product discovery". It represents a disco ~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. -The initial issue should be about the problem we are solving. If a separate [product discovery issue](#product-discovery-issues) is needed for additional research and design work, it will be created by a PM or UX person. Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery +The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels) +is needed for additional research and design work, it will be created by a PM or UX person. +Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and +use a title that makes it clear that the scheduled issue is product discovery (e.g. `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: @@ -32,34 +26,6 @@ In order to complete a product discovery issue in a release, you must complete t 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. -## Style guides - -1. [Ruby](https://github.com/bbatsov/ruby-style-guide). - Important sections include [Source Code Layout][rss-source] and - [Naming][rss-naming]. Use: - - multi-line method chaining style **Option A**: dot `.` on the second line - - string literal quoting style **Option A**: single quoted by default -1. [Rails](https://github.com/bbatsov/rails-style-guide) -1. [Newlines styleguide][newlines-styleguide] -1. [Testing][testing] -1. [JavaScript styleguide][js-styleguide] -1. [SCSS styleguide][scss-styleguide] -1. [Shell commands](../shell_commands.md) created by GitLab - contributors to enhance security -1. [Database Migrations](../migration_style_guide.md) -1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) -1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) -1. Interface text should be written subjectively instead of objectively. It - should be the GitLab core team addressing a person. It should be written in - present time and never use past tense (has been/was). For example instead - of _prohibited this user from being saved due to the following errors:_ the - text should be _sorry, we could not create your account because:_ -1. Code should be written in [US English][us-english] - -This is also the style used by linting tools such as -[RuboCop](https://github.com/bbatsov/rubocop), -[PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com). - --- [Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index eac7cb44c40..9da4c66933c 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,59 +1,26 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Contribute to GitLab](#contribute-to-gitlab) -- [Security vulnerability disclosure](#security-vulnerability-disclosure) -- [Code of conduct](#code-of-conduct) -- [Closing policy for issues and merge requests](#closing-policy-for-issues-and-merge-requests) -- [Helping others](#helping-others) -- [I want to contribute!](#i-want-to-contribute) -- [Contribution Flow](#contribution-flow) -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Milestone labels](#milestone-labels) - - [Bug Priority labels](#bug-priority-labels) - - [Bug Severity labels](#bug-severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) -- [Implement design & UI elements](#implement-design--ui-elements) -- [Issue tracker](#issue-tracker) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) -- [Style guides](#style-guides) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Contribute to GitLab - -For a first-time step-by-step guide to the contribution process, see -["Contributing to GitLab"](https://about.gitlab.com/contributing/). +# Contribute to GitLab Thank you for your interest in contributing to GitLab. This guide details how -to contribute to GitLab in a way that is efficient for everyone. +to contribute to GitLab in a way that is easy for everyone. + +We want to create a welcoming environment for everyone who is interested in contributing. Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our committment to an open and welcoming environment. + +For a first-time step-by-step guide to the contribution process, please see +["Contributing to GitLab"](https://about.gitlab.com/contributing/). -Looking for something to work on? Look for issues with the label [Accepting Merge Requests](#i-want-to-contribute). +Looking for something to work on? Look for issues with the label [`Accepting merge requests`](#i-want-to-contribute). -GitLab comes into two flavors, GitLab Community Edition (CE) our free and open +GitLab comes in two flavors, GitLab Community Edition (CE) our free and open source edition, and GitLab Enterprise Edition (EE) which is our commercial edition. Throughout this guide you will see references to CE and EE for abbreviation. -If you have read this guide and want to know how the GitLab [core team] +To get an overview of GitLab community membership including those that would be reviewing or merging your contributions, please visit [the community roles page](community_roles.md). + +If you want to know how the GitLab [core team] operates please see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md). -- [GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/) +[GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/) ## Security vulnerability disclosure @@ -65,33 +32,8 @@ vulnerabilities. ## Code of conduct -As contributors and maintainers of this project, we pledge to respect all -people who contribute through reporting issues, posting feature requests, -updating documentation, submitting pull requests or patches, and other -activities. - -We are committed to making participation in this project a harassment-free -experience for everyone, regardless of level of experience, gender, gender -identity and expression, sexual orientation, disability, personal appearance, -body size, race, ethnicity, age, or religion. - -Examples of unacceptable behavior by participants include the use of sexual -language or imagery, derogatory comments or personal attacks, trolling, public -or private harassment, insults, or other unprofessional conduct. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. Project maintainers who do not -follow the Code of Conduct may be removed from the project team. - -This code of conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. - -Instances of abusive, harassing, or otherwise unacceptable behavior can be -reported by emailing `contact@gitlab.com`. - -This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant], version 1.1.0, -available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/). +Our code of conduct can be found on the +["Contributing to GitLab"](https://about.gitlab.com/contributing/) page. ## Closing policy for issues and merge requests @@ -124,10 +66,10 @@ the remaining issues on the GitHub issue tracker. ## I want to contribute! -If you want to contribute to GitLab [issues with the label `Accepting Merge Requests` and small weight][accepting-mrs-weight] -is a great place to start. Issues with a lower weight (1 or 2) are deemed -suitable for beginners. These issues will be of reasonable size and challenge, -for anyone to start contributing to GitLab. If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to +If you want to contribute to GitLab, +[issues with the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors) +are a great place to start. +If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to learn how to communicate with GitLab. If you're looking for a Gitter or Slack channel please consider we favor [asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real time communication. Thanks for your contribution! @@ -154,93 +96,38 @@ When your code contains more than 500 changes, any major breaking changes, or an This [documentation](issue_workflow.md) outlines the current workflow labels. -### Type labels - -This [documentation](issue_workflow.md) outlines the current type labels. - -### Subject labels - -This [documentation](issue_workflow.md) outlines the current subject labels. - -### Team labels - -This [documentation](issue_workflow.md) outlines the current team labels. - -### Milestone labels - -This [documentation](issue_workflow.md) outlines the current milestone labels. - -### Bug Priority labels - -This [documentation](issue_workflow.md) outlines the current bug priority labels. - -### Bug Severity labels - -This [documentation](issue_workflow.md) outlines the current severity labels. - -#### Severity impact guidance - -This [documentation](issue_workflow.md) outlines the current severity impact guidance. - -### Label for community contributors - -This [documentation](issue_workflow.md) outlines the current policy regarding community contributor issues. - -## Implement design & UI elements - -This [documentation](design.md) outlines the current design and UI guidelines. - -## Issue tracker - -This [documentation](issue_workflow.md) outlines the issue tracker process. - -### Issue triaging - -This [documentation](issue_workflow.md) outlines the current issue triaging process. - -### Feature proposals - -This [documentation](issue_workflow.md) outlines the feature proposal process. - -### Issue tracker guidelines - -This [documentation](issue_workflow.md) outlines the issue tracker guidelines. - -### Issue weight - -This [documentation](issue_workflow.md) outlines the issue weight guidelines. - -### Regression issues - -This [documentation](issue_workflow.md) outlines the regression issue process. - -### Technical and UX debt - -This [documentation](issue_workflow.md) about technical and UX debt has been moved. - -### Stewardship - -This [documentation](issue_workflow.md) outlines the stewardship process. +* [Type labels](issue_workflow.md#type-labels) +* [Subject labels](issue_workflow.md#subject-labels) +* [Team labels](issue_workflow.md#team-labels) +* [Release Scoping labels](issue_workflow.md#release-scoping-labels) +* [Priority labels](issue_workflow.md#priority-labels) +* [Severity labels](issue_workflow.md#severity-labels) +* [Label for community contributors](issue_workflow.md#label-for-community-contributors) +* [Issue triaging](issue_workflow.md#issue-triaging) +* [Feature proposals](issue_workflow.md#feature-proposals) +* [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) +* [Issue weight](issue_workflow.md#issue-weight) +* [Regression issues](issue_workflow.md#regression-issues) +* [Technical and UX debt](issue_workflow.md#technical-and-ux-debt) +* [Stewardship](issue_workflow.md#stewardship) ## Merge requests This [documentation](merge_request_workflow.md) outlines the current merge request process. -### Merge request guidelines - -This [documentation](merge_request_workflow.md) outlines the current merge request guidelines. - -### Contribution acceptance criteria - -This [documentation](merge_request_workflow.md) outlines the current acceptance criteria for contributions. - -## Definition of done - -This [documentation](merge_request_workflow.md) outlines the definition of done. +* [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines) +* [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) +* [Definition of done](merge_request_workflow.md#definition-of-done) ## Style guides -This [documentation](design.md) outlines the current style guidelines. + +This [documentation](style_guides.md) outlines the current style guidelines. --- [Return to Development documentation](../README.md) + +[core team]: https://about.gitlab.com/core-team/ +[team]: https://about.gitlab.com/team/ +[getting-help]: https://about.gitlab.com/getting-help/ +[codetriage]: http://www.codetriage.com/gitlabhq/gitlabhq diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 08042fa2aec..7c7da50a149 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,27 +1,4 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Workflow labels](#workflow-labels) - - [Type labels](#type-labels) - - [Subject labels](#subject-labels) - - [Team labels](#team-labels) - - [Release Scoping labels](#release-scoping-labels) - - [Priority labels](#priority-labels) - - [Severity labels](#severity-labels) - - [Severity impact guidance](#severity-impact-guidance) - - [Label for community contributors](#label-for-community-contributors) - - [Issue triaging](#issue-triaging) - - [Feature proposals](#feature-proposals) - - [Issue tracker guidelines](#issue-tracker-guidelines) - - [Issue weight](#issue-weight) - - [Regression issues](#regression-issues) - - [Technical and UX debt](#technical-and-ux-debt) - - [Stewardship](#stewardship) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Workflow labels +# Workflow labels To allow for asynchronous issue handling, we use [milestones][milestones-page] and [labels][labels-page]. Leads and product managers handle most of the @@ -31,7 +8,8 @@ Most issues will have labels for at least one of the following: - Type: ~"feature proposal", ~bug, ~customer, etc. - Subject: ~wiki, ~"container registry", ~ldap, ~api, ~frontend, etc. -- Team: ~"CI/CD", ~Plan, ~Manage, ~Quality, etc. +- Team: ~Plan, ~Manage, ~Quality, etc. +- Stage: ~"devops:plan", ~"devops:create", etc. - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release" - Priority: ~P1, ~P2, ~P3, ~P4 - Severity: ~S1, ~S2, ~S3, ~S4 @@ -43,9 +21,8 @@ If you come across an issue that has none of these, and you're allowed to set labels, you can _always_ add the team and type, and often also the subject. [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones -[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels -### Type labels +## Type labels Type labels are very important. They define what kind of issue this is. Every issue should have one or more. @@ -61,7 +38,7 @@ already reserved for subject labels). The descriptions on the [labels page][labels-page] explain what falls under each type label. -### Subject labels +## Subject labels Subject labels are labels that define what area or feature of GitLab this issue hits. They are not always necessary, but very convenient. @@ -75,7 +52,7 @@ issue is labeled with a subject label corresponding to your expertise. Subject labels are always all-lowercase. -### Team labels +## Team labels Team labels specify what team is responsible for this issue. Assigning a team label makes sure issues get the attention of the appropriate @@ -83,8 +60,7 @@ people. The current team labels are: -- ~Configuration -- ~"CI/CD" +- ~Configure - ~Create - ~Distribution - ~Documentation @@ -97,6 +73,7 @@ The current team labels are: - ~Release - ~Secure - ~UX +- ~Verify The descriptions on the [labels page][labels-page] explain what falls under the responsibility of each team. @@ -107,7 +84,40 @@ indicate if an issue needs backend work, frontend work, or both. Team labels are always capitalized so that they show up as the first label for any issue. -### Release Scoping labels +## Stage labels + +Stage labels specify which [DevOps stage][devops-stages] the issue belongs to. + +The current stage labels are: + +- ~"devops:manage" +- ~"devops:plan" +- ~"devops:create" +- ~"devops:verify" +- ~"devops:package" +- ~"devops:release" +- ~"devops:configure" +- ~"devops:monitor" +- ~"devops:secure" + +These labels should be mutually exclusive. If an issue belongs to multiple +stages, the most relevant should be used. + +They differ from the [Team labels](#team-labels) because teams may work on +issues outside their stage. + +Normally there is a 1:1 relationship between Stage labels and Team labels, but +any issue can be picked up by any team, depending on current priorities. +So, an issue labeled ~"devops:create" may be scheduled by the ~Plan team, for +example. In such cases, it's usual to include both team labels so each team can +be aware of the progress. + +The Stage labels are used to generate the [direction pages][direction-pages] automatically. + +[devops-stages]: https://about.gitlab.com/direction/#devops-stages +[direction-pages]: https://about.gitlab.com/direction/ + +## Release Scoping labels Release Scoping labels help us clearly communicate expectations of the work for the release. There are three levels of Release Scoping labels: @@ -131,14 +141,17 @@ Priority labels help us define the time a ~bug fix should be completed. Priority If there are multiple defects, the priority decides which defect has to be fixed immediately versus later. This label documents the planned timeline & urgency which is used to measure against our actual SLA on delivering ~bug fixes. -| Label | Meaning | Estimate time to fix | -|-------|-----------------|------------------------------------------------------------------| -| ~P1 | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com | -| ~P2 | High Priority | The next release | -| ~P3 | Medium Priority | Within the next 3 releases (approx one quarter) | -| ~P4 | Low Priority | Anything outside the next 3 releases (approx beyond one quarter) | +| Label | Meaning | Defect SLA (applies only to ~bug and ~security defects) | +|-------|-----------------|----------------------------------------------------------------------------| +| ~P1 | Urgent Priority | The current release + potentially immediate hotfix to GitLab.com (30 days) | +| ~P2 | High Priority | The next release (60 days) | +| ~P3 | Medium Priority | Within the next 3 releases (approx one quarter or 90 days) | +| ~P4 | Low Priority | Anything outside the next 3 releases (more than one quarter or 120 days) | -### Severity labels +If an issue seems to fall between two priority labels, assign it to the higher- +priority label. + +## Severity labels Severity labels help us clearly communicate the impact of a ~bug on users. @@ -149,7 +162,11 @@ Severity labels help us clearly communicate the impact of a ~bug on users. | ~S3 | Major Severity | Broken Feature, workaround acceptable | Can create merge requests only from the Merge Requests page, not through the Issue. | | ~S4 | Low Severity | Functionality inconvenience or cosmetic issue | Label colors are incorrect / not being displayed. | -#### Severity impact guidance +If an issue seems to fall between two severity labels, even taking the +[severity impact guidance](#severity-impact-guidance) into account, assign +it to the higher-severity label. + +### Severity impact guidance Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline. @@ -158,16 +175,16 @@ Severity levels can be applied further depending on the facet of the impact; e.g | ~S1 | >50% users affected (possible company extinction level event) | Significant impact on all of GitLab.com | | | ~S2 | Many users or multiple paid customers affected (but not apocalyptic)| Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future | | ~S3 | A few users or a single paid customer affected | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future | -| ~S4 | No paid users/customer affected, or expected to in the near future | Minor impact on on GitLab.com | Degradation _may_ occur but it's not likely | +| ~S4 | No paid users/customer affected, or expected to in the near future | Minor impact on GitLab.com | Degradation _may_ occur but it's not likely | -### Label for community contributors +## Label for community contributors Issues that are beneficial to our users, 'nice to haves', that we currently do not have the capacity for or want to give the priority to, are labeled as -~"Accepting Merge Requests", so the community can make a contribution. +~"Accepting merge requests", so the community can make a contribution. Community contributors can submit merge requests for any issue they want, but -the ~"Accepting Merge Requests" label has a special meaning. It points to +the ~"Accepting merge requests" label has a special meaning. It points to changes that: 1. We already agreed on, @@ -175,43 +192,42 @@ changes that: 1. Are likely to get accepted by a maintainer. We want to avoid a situation when a contributor picks an -~"Accepting Merge Requests" issue and then their merge request gets closed, +~"Accepting merge requests" issue and then their merge request gets closed, because we realize that it does not fit our vision, or we want to solve it in a different way. -We add the ~"Accepting Merge Requests" label to: +We add the ~"Accepting merge requests" label to: - Low priority ~bug issues (i.e. we do not add it to the bugs that we want to solve in the ~"Next Patch Release") - Small ~"feature proposal" - Small ~"technical debt" issues -After adding the ~"Accepting Merge Requests" label, we try to estimate the +After adding the ~"Accepting merge requests" label, we try to estimate the [weight](#issue-weight) of the issue. We use issue weight to let contributors know how difficult the issue is. Additionally: -- We advertise ["Accepting Merge Requests" issues with weight < 5][up-for-grabs] +- We advertise [`Accepting merge requests` issues with weight < 5][up-for-grabs] as suitable for people that have never contributed to GitLab before on the [Up For Grabs campaign](http://up-for-grabs.net) - We encourage people that have never contributed to any open source project to - look for ["Accepting Merge Requests" issues with a weight of 1][firt-timers] + look for [`Accepting merge requests` issues with a weight of 1][firt-timers] If you've decided that you would like to work on an issue, please @-mention the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what) as soon as possible. The product manager will then pull in appropriate GitLab team members to further discuss scope, design, and technical considerations. This will -ensure that that your contribution is aligned with the GitLab product and minimize +ensure that your contribution is aligned with the GitLab product and minimize any rework and delay in getting it merged into master. -GitLab team members who apply the ~"Accepting Merge Requests" label to an issue +GitLab team members who apply the ~"Accepting merge requests" label to an issue should update the issue description with a responsible product manager, inviting any potential community contributor to @-mention per above. -[up-for-grabs]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=Accepting+Merge+Requests&scope=all&sort=weight_asc&state=opened -[firt-timers]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name%5B%5D=Accepting+Merge+Requests&scope=all&sort=upvotes_desc&state=opened&weight=1 +[up-for-grabs]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight +[firt-timers]: https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=0&sort=weight&weight=1 - -### Issue triaging +## Issue triaging Our issue triage policies are [described in our handbook]. You are very welcome to help the GitLab team triage issues. We also organize [issue bash events] once @@ -224,7 +240,7 @@ on those issues. Please select someone with relevant experience from the the commit history for the affected files to find someone. We also use [GitLab Triage] to automate some triaging policies. This is -currently setup as a [scheduled pipeline] running on [quality/triage-ops] +currently set up as a [scheduled pipeline] running on [quality/triage-ops] project. [described in our handbook]: https://about.gitlab.com/handbook/engineering/issue-triage/ @@ -232,8 +248,9 @@ project. [GitLab Triage]: https://gitlab.com/gitlab-org/gitlab-triage [scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit [quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops +[team]: https://about.gitlab.com/team/ -### Feature proposals +## Feature proposals To create a feature proposal for CE, open an issue on the [issue tracker of CE][ce-tracker]. @@ -250,7 +267,7 @@ code snippet right after your description in a new line: `~"feature proposal"`. Please keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. -Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20Proposal.md) provided on the issue tracker. +Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20proposal.md) provided on the issue tracker. For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may @@ -259,7 +276,9 @@ need to ask one of the [core team] members to add the label, if you do not have If you want to create something yourself, consider opening an issue first to discuss whether it is interesting to include this in GitLab. -### Issue tracker guidelines +[fpl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature+proposal + +## Issue tracker guidelines **[Search the issue tracker][ce-tracker]** for similar entries before submitting your own, there's a good chance somebody else had the same issue or @@ -271,7 +290,7 @@ The text in the parenthesis is there to help you with what to include. Omit it when submitting the actual issue. You can copy-paste it and then edit as you see fit. -### Issue weight +## Issue weight Issue weight allows us to get an idea of the amount of work required to solve one or multiple issues. This makes it possible to schedule work more accurately. @@ -293,7 +312,7 @@ is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. issues or chunks. You can simply not set the weight of a parent issue and set weights to children issues. -### Regression issues +## Regression issues Every monthly release has a corresponding issue on the CE issue tracker to keep track of functionality broken by that release and any fixes that need to be @@ -313,7 +332,7 @@ addressed. [8.3 Regressions]: https://gitlab.com/gitlab-org/gitlab-ce/issues/4127 [update the notes]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue -### Technical and UX debt +## Technical and UX debt In order to track things that can be improved in GitLab's codebase, we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker]. @@ -337,7 +356,46 @@ for a release by the appropriate person. Make sure to mention the merge request that the ~"technical debt" issue or ~"UX debt" issue is associated with in the description of the issue. -### Stewardship +## Technical debt in follow-up issues + +It's common to discover technical debt during development of a new feature. In +the spirit of "minimum viable change", resolution is often deferred to a +follow-up issue. However, this cannot be used as an excuse to merge poor-quality +code that would otherwise not pass review, or to overlook trivial matters that +don't deserve the be scheduled independently, and would be best resolved in the +original merge request - or not tracked at all! + +The overheads of scheduling, and rate of change in the GitLab codebase, mean +that the cost of a trivial technical debt issue can quickly exceed the value of +tracking it. This generally means we should resolve these in the original merge +request - or simply not create a follow-up issue at all. + +For example, a typo in a comment that is being copied between files is worth +fixing in the same MR, but not worth creating a follow-up issue for. Renaming a +method that is used in many places to make its intent slightly clearer may be +worth fixing, but it should not happen in the same MR, and is generally not +worth the overhead of having an issue of its own. These issues would invariably +be labelled `~P4 ~S4` if we were to create them. + +More severe technical debt can have implications for development velocity. If +it isn't addressed in a timely manner, the codebase becomes needlessly difficult +to change, new features become difficult to add, and regressions abound. + +Discoveries of this kind of technical debt should be treated seriously, and +while resolution in a follow-up issue may be appropriate, maintainers should +generally obtain a scheduling commitment from the author of the original MR, or +the engineering or product manager for the relevant area. This may take the form +of appropriate Priority / Severity labels on the issue, or an explicit milestone +and assignee. + +The maintainer must always agree before an outstanding discussion is resolved in +this manner, and will be the one to create the issue. The title and description +should be of the same quality as those created +[in the usual manner](#technical-and-ux-debt) - in particular, the issue title +**must not** begin with `Follow-up`! The creating maintainer should also expect +to be involved in some capacity when work begins on the follow-up issue. + +## Stewardship For issues related to the open source stewardship of GitLab, there is the ~"stewardship" label. @@ -355,3 +413,7 @@ A recent example of this was the issue for --- [Return to Contributing documentation](index.md) + +[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels +[ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues +[ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 685287f7a0c..5b32b5cd46f 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,22 +1,10 @@ -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Merge requests](#merge-requests) - - [Merge request guidelines](#merge-request-guidelines) - - [Contribution acceptance criteria](#contribution-acceptance-criteria) -- [Definition of done](#definition-of-done) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Merge requests +# Merge requests We welcome merge requests with fixes and improvements to GitLab code, tests, and/or documentation. The issues that are specifically suitable for -community contributions are listed with the label -[`Accepting Merge Requests` on our issue tracker for CE][accepting-mrs-ce] -and [EE][accepting-mrs-ee], but you are free to contribute to any other issue -you want. +community contributions are listed with +[the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors), +but you are free to contribute to any other issue you want. Please note that if an issue is marked for the current milestone either before or while you are working on it, a team member may take over the merge request @@ -30,13 +18,16 @@ wireframes if the feature will also change the UI. Merge requests should be opened at [GitLab.com][gitlab-mr-tracker]. If you are new to GitLab development (or web development in general), see the -[I want to contribute!](#i-want-to-contribute) section to get you started with +[I want to contribute!](index.md#i-want-to-contribute) section to get you started with some potentially easy issues. To start with GitLab development download the [GitLab Development Kit][gdk] and -see the [Development section](../README.md) for some guidelines. +see the [Development section](../../README.md) for some guidelines. + +[gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests +[gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit -### Merge request guidelines +## Merge request guidelines If you can, please submit a merge request with the fix or improvements including tests. If you don't know how to fix the issue but can write a test @@ -114,7 +105,11 @@ Please ensure that your merge request meets the contribution acceptance criteria When having your code reviewed and when reviewing merge requests please take the [code review guidelines](../code_review.md) into account. -### Contribution acceptance criteria +[git-squash]: https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits +[closed-merge-requests]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests?assignee_id=&label_name=&milestone_id=&scope=&sort=&state=closed +[team]: https://about.gitlab.com/team/ + +## Contribution acceptance criteria 1. The change is as small as possible 1. Include proper tests and make all tests pass (unless it contains a test @@ -144,7 +139,7 @@ When having your code reviewed and when reviewing merge requests please take the [polling with ETag caching][polling-etag]. 1. Changes after submitting the merge request should be in separate commits (no squashing). -1. It conforms to the [style guides](#style-guides) and the following: +1. It conforms to the [style guides](style_guides.md) and the following: - If your change touches a line that does not follow the style, modify the entire line to follow it. This prevents linting tools from generating warnings. - Don't touch neighbouring lines. As an exception, automatic mass @@ -155,6 +150,9 @@ When having your code reviewed and when reviewing merge requests please take the "license-finder" test with a "Dependencies that need approval" error. 1. The merge request meets the [definition of done](#definition-of-done). +[license-finder-doc]: ../licensing.md +[polling-etag]: ../polling.md + ## Definition of done If you contribute to GitLab please know that changes involve more than just @@ -167,12 +165,13 @@ the feature you contribute through all of these steps. 1. Performance/scalability implications have been considered, addressed, and tested 1. [Documented][doc-guidelines] in the `/doc` directory 1. [Changelog entry added][changelog], if necessary -1. Reviewed and any concerns are addressed +1. Reviewed by UX/FE/BE and any concerns are addressed 1. Merged by a project maintainer 1. Added to the release blog article, if relevant 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant 1. Community questions answered 1. Answers to questions radiated (in docs/wiki/support etc.) +1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-or-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions If you add a dependency in GitLab (such as an operating system package) please consider updating the following and note the applicability of each in your @@ -186,6 +185,12 @@ merge request: 1. Test suite https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh 1. Omnibus package creator https://gitlab.com/gitlab-org/omnibus-gitlab +[definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html +[testing]: ../testing_guide/index.md + --- [Return to Contributing documentation](index.md) + +[changelog]: ../changelog.md "Generate a changelog entry" +[doc-guidelines]: ../documentation/index.md "Documentation guidelines" diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md new file mode 100644 index 00000000000..6f1ba5d62a5 --- /dev/null +++ b/doc/development/contributing/style_guides.md @@ -0,0 +1,39 @@ +# Style guides + +1. [Ruby](https://github.com/bbatsov/ruby-style-guide). + Important sections include [Source Code Layout][rss-source] and + [Naming][rss-naming]. Use: + - multi-line method chaining style **Option A**: dot `.` on the second line + - string literal quoting style **Option A**: single quoted by default +1. [Rails](https://github.com/bbatsov/rails-style-guide) +1. [Newlines styleguide][newlines-styleguide] +1. [Testing][testing] +1. [JavaScript styleguide][js-styleguide] +1. [SCSS styleguide][scss-styleguide] +1. [Shell commands](../shell_commands.md) created by GitLab + contributors to enhance security +1. [Database Migrations](../migration_style_guide.md) +1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) +1. [Documentation styleguide](../documentation/styleguide.md) +1. Interface text should be written subjectively instead of objectively. It + should be the GitLab core team addressing a person. It should be written in + present time and never use past tense (has been/was). For example instead + of _prohibited this user from being saved due to the following errors:_ the + text should be _sorry, we could not create your account because:_ +1. Code should be written in [US English][us-english] + +This is also the style used by linting tools such as +[RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com). + +--- + +[Return to Contributing documentation](index.md) + +[rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout +[rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming +[doc-guidelines]: ../documentation/index.md "Documentation guidelines" +[js-styleguide]: ../fe_guide/style_guide_js.md "JavaScript styleguide" +[scss-styleguide]: ../fe_guide/style_guide_scss.md "SCSS styleguide" +[newlines-styleguide]: ../newlines_styleguide.md "Newlines styleguide" +[testing]: ../testing_guide/index.md +[us-english]: https://en.wikipedia.org/wiki/American_English diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 9c31265e417..b2c804b2ff0 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -33,7 +33,7 @@ If your test DB is giving you problems, it is safe to nuke it because it doesn't - `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR - `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down` - `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration - - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Setup a migration + - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration diff --git a/doc/development/database_merge_request_checklist.md b/doc/development/database_merge_request_checklist.md index 75c395b61ef..48864c81592 100644 --- a/doc/development/database_merge_request_checklist.md +++ b/doc/development/database_merge_request_checklist.md @@ -1,15 +1,15 @@ # Merge Request Checklist When creating a merge request that performs database related changes (schema -changes, adjusting queries to optimise performance, etc) you should use the -merge request template called "Database Changes". This template contains a +changes, adjusting queries to optimize performance, etc) you should use the +merge request template called "Database changes". This template contains a checklist of steps to follow to make sure the changes are up to snuff. To use the checklist, create a new merge request and click on the "Choose a -template" dropdown, then click "Database Changes". +template" dropdown, then click "Database changes". An example of this checklist can be found at -https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12463. +<https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12463>. The source code of the checklist can be found in at -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Database%20Changes.md +<https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Database%20changes.md> diff --git a/doc/development/db_dump.md b/doc/development/db_dump.md index e4ff72aa349..97762a62a80 100644 --- a/doc/development/db_dump.md +++ b/doc/development/db_dump.md @@ -13,7 +13,7 @@ large database imports. ``` # On STAGING echo "postgresql['checkpoint_segments'] = 64" | sudo tee -a /etc/gitlab/gitlab.rb -sudo touch /etc/gitlab/skip-auto-migrations +sudo touch /etc/gitlab/skip-auto-reconfigure sudo gitlab-ctl reconfigure sudo gitlab-ctl stop unicorn sudo gitlab-ctl stop sidekiq diff --git a/doc/development/diffs.md b/doc/development/diffs.md index 5e8e8cc7541..43fc125c21d 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -2,13 +2,10 @@ Currently we rely on different sources to present diffs, these include: -- Rugged gem - Gitaly service - Database (through `merge_request_diff_files`) - Redis (cached highlighted diffs) -We're constantly moving Rugged calls to Gitaly and the progress can be followed through [Gitaly repo](https://gitlab.com/gitlab-org/gitaly). - ## Architecture overview ### Merge request diffs @@ -19,20 +16,21 @@ we fetch the comparison information using `Gitlab::Git::Compare`, which fetches The diffs fetching process _limits_ single file diff sizes and the overall size of the whole diff through a series of constant values. Raw diff files are then persisted on `merge_request_diff_files` table. -Even though diffs higher than 10kb are collapsed (`Gitlab::Git::Diff::COLLAPSE_LIMIT`), we still keep them on Postgres. However, diff files over _safety limits_ -(see the [Diff limits section](#diff-limits)) are _not_ persisted. +Even though diffs larger than 10% of the value of `ApplicationSettings#diff_max_patch_bytes` are collapsed, +we still keep them on Postgres. However, diff files larger than defined _safety limits_ +(see the [Diff limits section](#diff-limits)) are _not_ persisted in the database. In order to present diffs information on the Merge Request diffs page, we: 1. Fetch all diff files from database `merge_request_diff_files` -2. Fetch the _old_ and _new_ file blobs in batch to: - 1. Highlight old and new file content - 2. Know which viewer it should use for each file (text, image, deleted, etc) - 3. Know if the file content changed - 4. Know if it was stored externally - 5. Know if it had storage errors -3. If the diff file is cacheable (text-based), it's cached on Redis -using `Gitlab::Diff::FileCollection::MergeRequestDiff` +1. Fetch the _old_ and _new_ file blobs in batch to: + - Highlight old and new file content + - Know which viewer it should use for each file (text, image, deleted, etc) + - Know if the file content changed + - Know if it was stored externally + - Know if it had storage errors +1. If the diff file is cacheable (text-based), it's cached on Redis + using `Gitlab::Diff::FileCollection::MergeRequestDiff` ### Note diffs @@ -41,9 +39,9 @@ on `NoteDiffFile` (which is associated with the actual `DiffNote`). So instead of hitting the repository every time we need the diff of the file, we: 1. Check whether we have the `NoteDiffFile#diff` persisted and use it -2. Otherwise, if it's a current MR revision, use the persisted -`MergeRequestDiffFile#diff` -3. In the last scenario, go the the repository and fetch the diff +1. Otherwise, if it's a current MR revision, use the persisted + `MergeRequestDiffFile#diff` +1. In the last scenario, go the repository and fetch the diff ## Diff limits @@ -102,23 +100,20 @@ Gitaly will only return the safe amount of data to be persisted on `merge_reques Limits that act onto each diff file of a collection. Files number, lines number and files size are considered. -```ruby -Gitlab::Git::Diff::COLLAPSE_LIMIT = 10.kilobytes -``` +#### Expandable patches (collapsed) -File diff will be collapsed (but be expandable) if it is larger than 10 kilobytes. +Diff patches are collapsed when surpassing 10% of the value set in `ApplicationSettings#diff_max_patch_bytes`. +That is, it's equivalent to 10kb if the maximum allowed value is 100kb. +The diff will still be persisted and expandable if the patch size doesn't +surpass `ApplicationSettings#diff_max_patch_bytes`. *Note:* Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly). Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits. -```ruby -Gitlab::Git::Diff::SIZE_LIMIT = 100.kilobytes -``` - -File diff will not be rendered if it's larger than 100 kilobytes. +#### Not expandable patches (too large) -*Note:* This limit is currently hardcoded and applied on Gitaly and the RPC returns `Diff.TooLarge` when this limit is surpassed. -Although we're still also applying it on GitLab, we should remove the redundancy from GitLab once we're confident with the Gitaly integration. +The patch not be rendered if it's larger than `ApplicationSettings#diff_max_patch_bytes`. +Users will see a `This source diff could not be displayed because it is too large` message. ```ruby Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index d6ae4cb39f0..b7990e1b558 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -4,9 +4,9 @@ description: Learn how to contribute to GitLab Documentation. # GitLab Documentation guidelines - - **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. - - **[Technical Articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). - - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs). +- **General Documentation**: written by the [developers responsible by creating features](#contributing-to-docs). Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. +- **[Technical Articles](#technical-articles)**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). +- **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs). ## Contributing to docs @@ -41,15 +41,17 @@ how to structure GitLab docs. ## Markdown and styles -Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. +[GitLab docs](https://gitlab.com/gitlab-com/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown) +as markdown engine. Check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) +for a complete Kramdown reference. -All the docs follow the [documentation style guidelines](styleguide.md). +Follow the [documentation style guidelines](styleguide.md) strictly. ## Documentation directory structure The documentation is structured based on the GitLab UI structure itself, separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), -[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). +[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. @@ -61,11 +63,11 @@ in small iterations. Please don't create new docs in these folders. ### Documentation files - When you create a new directory, always start with an `index.md` file. -Do not use another file name and **do not** create `README.md` files + Do not use another file name and **do not** create `README.md` files. - **Do not** use special chars and spaces, or capital letters in file names, -directory names, branch names, and anything that generates a path. -- Max screenshot size: 100KB -- We do not support videos (yet) + directory names, branch names, and anything that generates a path. +- Max screenshot size: 100KB. +- We do not support videos (yet). ### Location and naming documents @@ -83,24 +85,21 @@ and cross-link between any related content. The table below shows what kind of documentation goes where. -| Directory | What belongs here | -| --------- | -------------- | -| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | -| `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | -| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | +| Directory | What belongs here | +|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | +| `doc/api/` | API related documentation. | +| `doc/development/` | Documentation related to the development of GitLab. Any styleguides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | +| `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | +| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | --- **General rules & best practices:** -1. The correct naming and location of a new document, is a combination - of the relative URL of the document in question and the GitLab Map design - that is used for UX purposes ([source][graffle], [image][gitlab-map]). 1. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (`-`). For example, a proper naming would be `import_projects_from_github.md`. The same rule @@ -134,13 +133,13 @@ merge request. Changing a document's location is not to be taken lightly. Remember that the documentation is available to all installations under `help/` and not only to -GitLab.com or http://docs.gitlab.com. Make sure this is discussed with the +GitLab.com or <http://docs.gitlab.com>. Make sure this is discussed with the Documentation team beforehand. If you indeed need to change a document's location, do NOT remove the old document, but rather replace all of its contents with a new line: -``` +```md This document was moved to [another location](path/to/new_doc.md). ``` @@ -154,7 +153,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to 1. Copy `doc/workflow/lfs/lfs_administration.md` to `doc/administration/lfs.md` 1. Replace the contents of `doc/workflow/lfs/lfs_administration.md` with: - ``` + ```md This document was moved to [another location](../../administration/lfs.md). ``` @@ -162,7 +161,7 @@ For example, if you were to move `doc/workflow/lfs/lfs_administration.md` to A quick way to find them is to use `git grep`. First go to the root directory where you cloned the `gitlab-ce` repository and then do: - ``` + ```sh git grep -n "workflow/lfs/lfs_administration" git grep -n "lfs/lfs_administration" ``` @@ -198,6 +197,11 @@ redirect_to: '../path/to/file/README.md' It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`. +NOTE: **Note:** +This redirection method will not provide a redirect fallback on GitLab `/help`. When using +it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that +land on the doc via `/help`. + ### Redirections for pages with Disqus comments If the documentation page being relocated already has any Disqus comments, @@ -223,33 +227,14 @@ redirect_from: 'https://docs.gitlab.com/my-old-location/README.html' Note: it is necessary to include the file name in the `redirect_from` URL, even if it's `index.html` or `README.html`. -## Testing - -We treat documentation as code, thus have implemented some testing. -Currently, the following tests are in place: - -1. `docs lint`: Check that all internal (relative) links work correctly and - that all cURL examples in API docs use the full switches. It's recommended - to [check locally](#previewing-locally) before pushing to GitLab by executing the command - `bundle exec nanoc check internal_links` on your local - [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory. -1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only): - When you submit a merge request to GitLab Community Edition (CE), - there is this additional job that runs against Enterprise Edition (EE) - and checks if your changes can apply cleanly to the EE codebase. - If that job fails, read the instructions in the job log for what to do next. - As CE is merged into EE once a day, it's important to avoid merge conflicts. - Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is - essential to avoid them. - ## Branch naming If your contribution contains **only** documentation changes, you can speed up the CI process by following some branch naming conventions. You have three choices: -| Branch name | Valid example | -| ----------- | ------------- | +| Branch name | Valid example | +|:----------------------|:-----------------------------| | Starting with `docs/` | `docs/update-api-issues` | | Starting with `docs-` | `docs-update-api-issues` | | Ending in `-docs` | `123-update-api-issues-docs` | @@ -257,15 +242,6 @@ choices: If your branch name matches any of the above, it will run only the docs tests. If it doesn't, the whole test suite will run (including docs). -## Danger bot - -GitLab uses [danger bot](https://github.com/danger/danger) for some elements in -code review. For docs changes in merge requests, the following actions are taken: - -1. Whenever a change under `/doc` is made, the bot leaves a comment for the - author to mention `@gl-docsteam`, so that the docs can be properly - reviewed. - ## Merge requests for GitLab documentation Before getting started, make sure you read the introductory section @@ -278,7 +254,6 @@ for GitLab Team members. - Label the MR `Documentation` - Assign the correct milestone (see note below) - NOTE: **Note:** If the release version you want to add the documentation to has already been frozen or released, use the label `Pick into X.Y` to get it merged into @@ -299,112 +274,15 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m - Create the EE-equivalent branch ending with `-ee`, e.g., `git checkout -b docs-example-ee` - Once all the jobs are passing in CE and EE, and you've addressed the -feedback from your own team, assign the CE MR to a technical writer for review + feedback from your own team, assign the CE MR to a technical writer for review - When both MRs are ready, the EE merge request will be merged first, and the -CE-equivalent will be merged next. + CE-equivalent will be merged next. - Note that the review will occur only in the CE MR, as the EE MR -contains the same commits as the CE MR. + contains the same commits as the CE MR. - If you have a few more changes that apply to the EE-version only, you can submit -a couple more commits to the EE branch, but ask the reviewer to review the EE merge request -additionally to the CE MR. If there are many EE-only changes though, start a new MR -to EE only. - -## Previewing the changes live - -NOTE: **Note:** -To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development). - -The live preview is currently enabled for the following projects: - -- https://gitlab.com/gitlab-org/gitlab-ce -- https://gitlab.com/gitlab-org/gitlab-ee -- https://gitlab.com/gitlab-org/gitlab-runner - -If your branch contains only documentation changes, you can use -[special branch names](#branch-naming) to avoid long running pipelines. - -For [docs-only changes](#branch-naming), the review app is run automatically. -For all other branches, you can use the manual `review-docs-deploy-manual` job -in your merge request. You will need at least Maintainer permissions to be able -to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will -reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start. - - - -NOTE: **Note:** -You will need to push a branch to those repositories, it doesn't work for forks. - -The `review-docs-deploy*` job will: - -1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs) - project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`, - where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for - CE, etc. -1. Trigger a cross project pipeline and build the docs site with your changes - -After a few minutes, the Review App will be deployed and you will be able to -preview the changes. The docs URL can be found in two places: - -- In the merge request widget -- In the output of the `review-docs-deploy*` job, which also includes the - triggered pipeline so that you can investigate whether something went wrong - -In case the Review App URL returns 404, follow these steps to debug: - -1. **Did you follow the URL from the merge request widget?** If yes, then check if - the link is the same as the one in the job output. -1. **Did you follow the URL from the job output?** If yes, then it means that - either the site is not yet deployed or something went wrong with the remote - pipeline. Give it a few minutes and it should appear online, otherwise you - can check the status of the remote pipeline from the link in the job output. - If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. - -TIP: **Tip:** -Someone that has no merge rights to the CE/EE projects (think of forks from -contributors) will not be able to run the manual job. In that case, you can -ask someone from the GitLab team who has the permissions to do that for you. - -NOTE: **Note:** -Make sure that you always delete the branch of the merge request you were -working on. If you don't, the remote docs branch won't be removed either, -and the server where the Review Apps are hosted will eventually be out of -disk space. - -### Technical aspects - -If you want to know the hot details, here's what's really happening: - -1. You manually run the `review-docs-deploy` job in a CE/EE merge request. -1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs) - script with the `deploy` flag, which in turn: - 1. Takes your branch name and applies the following: - - The slug of the branch name is used to avoid special characters since - ultimately this will be used by NGINX. - - The `preview-` prefix is added to avoid conflicts if there's a remote branch - with the same name that you created in the merge request. - - The final branch name is truncated to 42 characters to avoid filesystem - limitations with long branch names (> 63 chars). - 1. The remote branch is then created if it doesn't exist (meaning you can - re-run the manual job as many times as you want and this step will be skipped). - 1. A new cross-project pipeline is triggered in the docs project. - 1. The preview URL is shown both at the job output and in the merge request - widget. You also get the link to the remote pipeline. -1. In the docs project, the pipeline is created and it - [skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) - to lower the build time. -1. Once the docs site is built, the HTML files are uploaded as artifacts. -1. A specific Runner tied only to the docs project, runs the Review App job - that downloads the artifacts and uses `rsync` to transfer the files over - to a location where NGINX serves them. - -The following GitLab features are used among others: - -- [Manual actions](../../ci/yaml/README.md#manual-actions) -- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html) -- [Review Apps](../../ci/review_apps/index.md) -- [Artifacts](../../ci/yaml/README.md#artifacts) -- [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) + a couple more commits to the EE branch, but ask the reviewer to review the EE merge request + additionally to the CE MR. If there are many EE-only changes though, start a new MR + to EE only. ## GitLab `/help` @@ -413,8 +291,8 @@ Every GitLab instance includes the documentation, which is available from `/help The documentation available online on docs.gitlab.com is continuously deployed every hour from the `master` branch of CE, EE, Omnibus, and Runner. Therefore, -once a merge request gets merged, it will be available online on the same day, -but they will be shipped (and available on `/help`) within the milestone assigned +once a merge request gets merged, it will be available online on the same day. +However, they will be shipped (and available on `/help`) within the milestone assigned to the MR. For instance, let's say your merge request has a milestone set to 11.3, which @@ -511,7 +389,7 @@ They should be placed in a new directory named `/article-title/index.md` under a - **User guides**: technical content to guide regular users from point A to point B - **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B - **Technical Overviews**: technical content describing features, solutions, and third-party integrations -- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives +- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach specific objectives #### Understanding guides, tutorials, and technical overviews @@ -543,7 +421,6 @@ with the following information: For example: - ```yaml --- author: John Doe @@ -558,5 +435,250 @@ date: 2017-02-01 Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team. +## Previewing the changes live + +NOTE: **Note:** +To preview your changes to documentation locally, follow this +[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). + +The live preview is currently enabled for the following projects: + +- <https://gitlab.com/gitlab-org/gitlab-ce> +- <https://gitlab.com/gitlab-org/gitlab-ee> +- <https://gitlab.com/gitlab-org/gitlab-runner> + +If your branch contains only documentation changes, you can use +[special branch names](#branch-naming) to avoid long running pipelines. + +For [docs-only changes](#branch-naming), the review app is run automatically. +For all other branches, you can use the manual `review-docs-deploy-manual` job +in your merge request. You will need at least Maintainer permissions to be able +to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will +reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start. + + + +NOTE: **Note:** +You will need to push a branch to those repositories, it doesn't work for forks. + +The `review-docs-deploy*` job will: + +1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs) + project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`, + where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for + CE, etc. +1. Trigger a cross project pipeline and build the docs site with your changes + +After a few minutes, the Review App will be deployed and you will be able to +preview the changes. The docs URL can be found in two places: + +- In the merge request widget +- In the output of the `review-docs-deploy*` job, which also includes the + triggered pipeline so that you can investigate whether something went wrong + +TIP: **Tip:** +Someone that has no merge rights to the CE/EE projects (think of forks from +contributors) will not be able to run the manual job. In that case, you can +ask someone from the GitLab team who has the permissions to do that for you. + +NOTE: **Note:** +Make sure that you always delete the branch of the merge request you were +working on. If you don't, the remote docs branch won't be removed either, +and the server where the Review Apps are hosted will eventually be out of +disk space. + +### Troubleshooting review apps + +In case the review app URL returns 404, follow these steps to debug: + +1. **Did you follow the URL from the merge request widget?** If yes, then check if + the link is the same as the one in the job output. +1. **Did you follow the URL from the job output?** If yes, then it means that + either the site is not yet deployed or something went wrong with the remote + pipeline. Give it a few minutes and it should appear online, otherwise you + can check the status of the remote pipeline from the link in the job output. + If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. + +### Technical aspects + +If you want to know the in-depth details, here's what's really happening: + +1. You manually run the `review-docs-deploy` job in a CE/EE merge request. +1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs) + script with the `deploy` flag, which in turn: + 1. Takes your branch name and applies the following: + - The slug of the branch name is used to avoid special characters since + ultimately this will be used by NGINX. + - The `preview-` prefix is added to avoid conflicts if there's a remote branch + with the same name that you created in the merge request. + - The final branch name is truncated to 42 characters to avoid filesystem + limitations with long branch names (> 63 chars). + 1. The remote branch is then created if it doesn't exist (meaning you can + re-run the manual job as many times as you want and this step will be skipped). + 1. A new cross-project pipeline is triggered in the docs project. + 1. The preview URL is shown both at the job output and in the merge request + widget. You also get the link to the remote pipeline. +1. In the docs project, the pipeline is created and it + [skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) + to lower the build time. +1. Once the docs site is built, the HTML files are uploaded as artifacts. +1. A specific Runner tied only to the docs project, runs the Review App job + that downloads the artifacts and uses `rsync` to transfer the files over + to a location where NGINX serves them. + +The following GitLab features are used among others: + +- [Manual actions](../../ci/yaml/README.md#manual-actions) +- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html) +- [Review Apps](../../ci/review_apps/index.md) +- [Artifacts](../../ci/yaml/README.md#artifacts) +- [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) + +## Testing + +We treat documentation as code, thus have implemented some testing. +Currently, the following tests are in place: + +1. `docs lint`: Check that all internal (relative) links work correctly and + that all cURL examples in API docs use the full switches. It's recommended + to [check locally](#previewing-locally) before pushing to GitLab by executing the command + `bundle exec nanoc check internal_links` on your local + [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory. +1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only): + When you submit a merge request to GitLab Community Edition (CE), + there is this additional job that runs against Enterprise Edition (EE) + and checks if your changes can apply cleanly to the EE codebase. + If that job fails, read the instructions in the job log for what to do next. + As CE is merged into EE once a day, it's important to avoid merge conflicts. + Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is + essential to avoid them. + +### Linting + +To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content +added to documentation, consider locally installing and running documentation linters. This will +help you catch common issues before raising merge requests for review of documentation. + +The following are some suggested linters you can install locally and sample configuration: + +- [`proselint`](#proselint) +- [`markdownlint`](#markdownlint) + +NOTE: **Note:** +This list does not limit what other linters you can add to your local documentation writing toolchain. + +#### `proselint` + +`proselint` checks for common problems with English prose. It provides a + [plethora of checks](http://proselint.com/checks/) that are helpful for technical writing. + +`proselint` can be used [on the command line](http://proselint.com/utility/), either on a single + Markdown file or on all Markdown files in a project. For example, to run `proselint` on all + documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), run the + following commands from within the `gitlab-ce` project: + +```sh +cd doc +proselint **/*.md +``` + +`proselint` can also be run from within editors using plugins. For example, the following plugins + are available: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-proselint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=PatrykPeszko.vscode-proselint) +- [Others](https://github.com/amperser/proselint#plugins-for-other-software) + +##### Sample `proselint` configuration + +All of the checks are good to use. However, excluding the `typography.symbols` and `misc.phrasal_adjectives` checks will reduce +noise. The following sample `proselint` configuration disables these checks: + +```json +{ + "checks": { + "typography.symbols": false, + "misc.phrasal_adjectives": false + } +} +``` + +A file with `proselint` configuration must be placed in a +[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`. + +#### `markdownlint` + +`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases)) + are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices + must be made when selecting Markdown syntax for GitLab documentation and this tool helps + catch deviations from those guidelines. + +`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--), + either on a single Markdown file or on all Markdown files in a project. For example, to run + `markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), + run the following commands from within the `gitlab-ce` project: + +```sh +cd doc +markdownlint **/*.md +``` + +`markdownlint` can also be run from within editors using plugins. For example, the following plugins + are available: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Others](https://github.com/DavidAnson/markdownlint#related) + +##### Sample `markdownlint` configuration + +The following sample `markdownlint` configuration modifies the available default rules to: + +- Adhere to the [style guidelines](styleguide.md). +- Apply conventions found in the GitLab documentation. +- Allow the flexibility of using some inline HTML. + +```json +{ + "default": true, + "header-style": { "style": "atx" }, + "ul-style": { "style": "dash" }, + "line-length": false, + "no-trailing-punctuation": false, + "ol-prefix": { "style": "one" }, + "blanks-around-fences": false, + "no-inline-html": { + "allowed_elements": [ + "table", + "tbody", + "tr", + "td", + "ul", + "ol", + "li", + "br", + "img", + "a", + "strong", + "i", + "div" + ] + }, + "hr-style": { "style": "---" }, + "fenced-code-language": false +} +``` + +For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be +placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For +example, `~/.markdownlintrc`. + +## Danger bot + +GitLab uses [danger bot](https://github.com/danger/danger) for some elements in +code review. For docs changes in merge requests, whenever a change under `/doc` +is made, the bot leaves a comment for the author to mention `@gl-docsteam`, so +that the docs can be properly reviewed. + [gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png [graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 1002836096a..607ad21d459 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -21,21 +21,21 @@ Before getting started, read through the following docs: Every document should include the following content in the following sequence: - **Feature name**: defines an intuitive name for the feature that clearly -states what it is and is consistent with any relevant UI text. + states what it is and is consistent with any relevant UI text. - **Feature overview** and description: describe what it is, what it does, and in what context it should be used. - **Use cases**: describes real use case scenarios for that feature. - **Requirements**: describes what software and/or configuration is required to be able to -use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. -For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. -Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. -(Another doc page, a third party application's site, etc.) + use the feature and, if applicable, prerequisite knowledge for being able to follow/implement the tutorial. + For example, familiarity with GitLab CI/CD, an account on a third-party service, dependencies installed, etc. + Link each one to its most relevant resource; i.e., where the reader can go to begin to fullfil that requirement. + (Another doc page, a third party application's site, etc.) - **Instructions**: clearly describes the steps to use the feature, leaving no gaps. - **Troubleshooting** guide (recommended but not required): if you know beforehand what issues -one might have when setting it up, or when something is changed, or on upgrading, it's -important to describe those too. Think of things that may go wrong and include them in the -docs. This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. Answering them beforehand only makes your -document better and more approachable. + one might have when setting it up, or when something is changed, or on upgrading, it's + important to describe those too. Think of things that may go wrong and include them in the + docs. This is important to minimize requests for support, and to avoid doc comments with + questions that you know someone might ask. Answering them beforehand only makes your + document better and more approachable. For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). @@ -55,10 +55,11 @@ You should answer this question: what can you do with this feature/change? Use c are examples of how this feature or change can be used in real life. Examples: -- CE and EE: [Issues](../user/project/issues/index.md#use-cases) -- CE and EE: [Merge Requests](../user/project/merge_requests/index.md#overview) -- EE-only: [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html#overview) -- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.md#overview) + +- CE and EE: [Issues](../../user/project/issues/index.md#use-cases) +- CE and EE: [Merge Requests](../../user/project/merge_requests/index.md) +- EE-only: [Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) +- EE-only: [Jenkins integration](https://docs.gitlab.com/ee/integration/jenkins.html) Note that if you don't have anything to add between the doc title (`<h1>`) and the header `## Overview`, you can omit the header, but keep the content of the @@ -72,14 +73,14 @@ and for every **major** feature present in Community Edition. Your new document will be discoverable by the user only if: - Crosslinked from the higher-level index (e.g., Issue Boards docs -should be linked from Issues; Prometheus docs should be linked from -Monitoring; CI/CD tutorials should be linked from CI/CD examples). + should be linked from Issues; Prometheus docs should be linked from + Monitoring; CI/CD tutorials should be linked from CI/CD examples). - When referencing other GitLab products and features, link to their -respective docs; when referencing third-party products or technologies, -link out to their external sites, documentation, and resources. + respective docs; when referencing third-party products or technologies, + link out to their external sites, documentation, and resources. - The headings are clear. E.g., "App testing" is a bad heading, "Testing -an application with GitLab CI/CD" is much better. Think of something -someone will search for and use these keywords in the headings. + an application with GitLab CI/CD" is much better. Think of something + someone will search for and use these keywords in the headings. ## Documentation template for new docs @@ -133,7 +134,7 @@ is simple and the document is short. - Be clear, concise, and stick to the goal of the doc: explain how to use that feature. - Use inclusive language and avoid jargons, as well as uncommon and -fancy words. The docs should be clear and very easy to understand. +fancy words. The docs should be clear and easy to understand. - Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). - Always provide internal and external reference links. - Always link the doc from its higher-level index. @@ -141,9 +142,49 @@ fancy words. The docs should be clear and very easy to understand. <!-- ## Troubleshooting Add a troubleshooting guide when possible/applicable. --> -``` + +--- Notes: -- (1): Apply the [tier badges](styleguide.md#product-badges) accordingly -- (2): Apply the correct format for the [GitLab version introducing the feature](styleguide.md#gitlab-versions-and-tiers) +- (1): Apply the [tier badges](https://docs.gitlab.com/ee/development/documentation/styleguide.html#product-badges) accordingly +- (2): Apply the correct format for the [GitLab version introducing the feature](https://docs.gitlab.com/ee/development/documentation/styleguide.html#gitlab-versions-and-tiers) +``` + +## Help and feedback section + +The "help and feedback" section (introduced by [!319](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/319)) displayed at the end of each document +can be omitted from the doc by adding a key into the its frontmatter: + +```yaml +--- +feedback: false +--- +``` + +The default is to leave it there. If you want to omit it from a document, +you must check with a technical writer before doing so. + +### Disqus + +We also have integrated the docs site with Disqus (introduced by +[!151](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/151)), +allowing our users to post comments. + +To omit only the comments from the feedback section, use the following +key on the frontmatter: + +```yaml +--- +comments: false +--- +``` + +We are only hiding comments in main index pages, such as [the main documentation index](../../README.md), since its content is too broad to comment on. Before omitting Disqus, +you must check with a technical writer. + +Note that once `feedback: false` is added to the frontmatter, it will automatically omit +Disqus, therefore, don't add both keys to the same document. + +The click events in the feedback section are tracked with Google Tag Manager. The +conversions can be viewed on Google Analytics by navigating to **Behavior > Events > Top events > docs**. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 8083f219d4a..8309ba9a72c 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -10,15 +10,15 @@ GitLab documentation. Check the Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +For help adhering to the guidelines, see [linting](index.md#linting). + ## Files - [Directory structure](index.md#location-and-naming-documents): place the docs in the correct location. - [Documentation files](index.md#documentation-files): name the files accordingly. -- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the -documentation. -NOTE: **Note:** +DANGER: **Attention:** **Do not** use capital letters, spaces, or special chars in file names, branch names, directory names, headings, or in anything that generates a path. @@ -26,65 +26,144 @@ NOTE: **Note:** **Do not** create new `README.md` files, name them `index.md` instead. There's a test that will fail if it spots a new `README.md` file. -## Text +### Markdown + +The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) +in October, 2018. + +The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) +gem will support all [GFM markup](../../user/markdown.md) in the future. For now, +use regular markdown markup, following the rules on this style guide. For a complete +Kramdown reference, check the [GiLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in +[`/help`](#gitlab-help). + +## Content -- Split up long lines (wrap text), this makes it much easier to review and edit. Only - double line breaks are shown as a full line break in [GitLab markdown][gfm]. - 80-100 characters is a good line length. - Make sure that the documentation is added in the correct - [directory](index.md#documentation-directory-structure) and that - there's a link to it somewhere useful. + [directory](index.md#documentation-directory-structure), linked from its + higher-level index, and linked from other related pages. - Do not duplicate information. - Be brief and clear. -- Unless there's a logical reason not to, add documents in alphabetical order. +- Unless there's a logical reason not to, structure the document in alphabetical order +(headings, tables, and lists). - Write in US English. -- Use [single spaces][] instead of double spaces. -- Jump a line between different markups (e.g., after every paragraph, header, list, etc) - Capitalize "G" and "L" in GitLab. -- Use sentence case for titles, headings, labels, menu items, and buttons. - Use title case when referring to [features](https://about.gitlab.com/features/) or [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies (e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that -some features are also objects (e.g. "Merge Requests" and "merge requests"). +some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z."). -## Formatting +## Text + +- Split up long lines (wrap text), this makes it much easier to review and edit. Only + double line breaks are shown as a full line break by creating new paragraphs. + 80-100 characters is the recommended line length. +- Use sentence case for titles, headings, labels, menu items, and buttons. +- Jump a line between different markups (e.g., after every paragraph, header, list, etc). Example: -- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). -- Use undescore (`_`) for text in italics (`_italic_`). -- Put an empty line between different markups. For example: ```md ## Header Paragraph. - - List item - - List item + - List item 1 + - List item 2 ``` -### Punctuation +## Emphasis + +- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). +- Use undescore (`_`) for text in italics (`_italic_`). +- Use greater than (`>`) for blockquotes. + +## Punctuation + +Check the general punctuation rules for the GitLab documentation on the table below. +Check specific punctuation rules for [list items](#list-items) below. + +| Rule | Example | +| ---- | ------- | +| Always end full sentences with a period. | _For a complete overview, read through this document._| +| Always add a space after a period when beginning a new sentence | _For a complete overview, check this doc. For other references, check out this guide._ | +| Do not use double spaces. | --- | +| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- | +| Use serial commas ("Oxford commas") before the final 'and/or' in a list. | _You can create new issues, merge requests, and milestones._ | +| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ | +| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ | -For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). +## List items -### Ordered and unordered lists +- Always start list items with a capital letter. +- Always leave a blank line before and after a list. +- Begin a line with spaces (not tabs) to denote a subitem. +- To nest subitems, indent them with two spaces. +- To nest code blocks, indent them with four spaces. +- Only use ordered lists when their items describe a sequence of steps to follow. -- Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Use the number one (`1`) for ordered lists. +**Markup:** + +- Use dashes (`- `) for unordered lists instead of asterisks (`* `). +- Use the number one (`1`) for each item in an ordered list. +When rendered, the list items will appear with sequential numbering. + +**Punctuation:** + +- Do not add commas (`,`) or semicolons (`;`) to the end of a list item. +- Only add periods to the end of a list item if the item consists of a complete sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/resources/writing/grammar/grammar-guides/sentence) is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_. +- Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period. - Separate list items from explanatory text with a colon (`:`). For example: + ```md The list is as follows: - - First item: This explains the first item. - - Second item: This explains the second item. + - First item: this explains the first item. + - Second item: this explains the second item. ``` -- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). + +**Examples:** + +Do: + +- First list item +- Second list item +- Third list item + +Don't: + +- First list item +- Second list item +- Third list item. + +Do: + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence. + +Don't: + +- Let's say this is a complete sentence. +- Let's say this is also a complete sentence. +- Not a complete sentence + +## Quotes + +Valid for markdown content only, not for frontmatter entries: + +- Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes". +- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote". + +For other punctuation rules, please refer to the +[GitLab UX guide](https://design.gitlab.com/content/punctuation/). ## Headings - Add **only one H1** in each document, by adding `#` at the beginning of it (when using markdown). The `h1` will be the document `<title>`. -- Start with an h2 (`##`), and respect the order h2 > h3 > h4 > h5 > h6. - Never skip the hierarchy level, such as h2 > h4 +- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`. + Never skip the hierarchy level, such as `h2` > `h4` - Avoid putting numbers in headings. Numbers shift, hence documentation anchor links shift too, which eventually leads to dead links. If you think it is compelling to add numbers in headings, make sure to at least discuss it with @@ -94,21 +173,19 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl - Avoid adding things that show ephemeral statuses. For example, if a feature is considered beta or experimental, put this info in a note, not in the heading. - When introducing a new document, be careful for the headings to be - grammatically and syntactically correct. Mention one or all - of the following GitLab members for a review: `@axil` or `@marcia`. + grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/categories/) + for review. This is to ensure that no document with wrong heading is going live without an audit, thus preventing dead links and redirection issues when corrected. - Leave exactly one new line after a heading. +- Do not use links in headings. +- Add the corresponding [product badge](#product-badges) according to the tier the feature belongs. ## Links -- Use the regular inline link markdown markup `[Text](https://example.com)`. - It's easier to read, review, and maintain. -- If there's a link that repeats several times through the same document, - you can use `[Text][identifier]` and at the bottom of the section or the - document add: `[identifier]: https://example.com`, in which case, we do - encourage you to also add an alternative text: `[identifier]: https://example.com "Alternative text"` that appears when hovering your mouse on a link. +- Use inline link markdown markup `[Text](https://example.com)`. + It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. - To link to internal documentation, use relative links, not full URLs. Use `../` to navigate tp high-level directories, and always add the file name `file.md` at the end of the link with the `.md` extension, not `.html`. @@ -126,11 +203,12 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl To indicate the steps of navigation through the UI: + - Use the exact word as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char `>` as separator +- Use bold text for navigation items and the char "greater than" (`>`) as separator (e.g., `Navigate to your project's **Settings > CI/CD**` ). - If there are any expandable menus, make sure to mention that the user -needs to expand the tab to find the settings you're referring to. +needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`). ## Images @@ -139,7 +217,7 @@ needs to expand the tab to find the settings you're referring to. names with the name of the document that they will be included in. For example, if there is a document called `twitter.md`, then a valid image name could be `twitter_login_screen.png`. -- Images should have a specific, non-generic name that will differentiate them. +- Images should have a specific, non-generic name that will differentiate and describe them properly. - Keep all file names in lower case. - Consider using PNG images instead of JPEG. - Compress all images with <https://tinypng.com/> or similar tool. @@ -162,13 +240,39 @@ Inside the document: - If a heading is placed right after an image, always add three dashes (`---`) between the image and the heading. +## Code blocks + +- Always wrap code added to a sentence in inline code blocks (``` ` ```). +E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: master`. +File names, commands, entries, and anything that refers to code should be added to code blocks. +To make things easier for the user, always add a full code block for things that can be +useful to copy and paste, as they can easily do it with the button on code blocks. +- For regular code blocks, always use a highlighting class corresponding to the +language for better readability. Examples: + + ```md + ```ruby + Ruby code + ``` + + ```js + JavaScript code + ``` + + ```md + Markdown code + ``` + ``` + +- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks). + ## Alert boxes Whenever you want to call the attention to a particular sentence, use the following markup for highlighting. _Note that the alert boxes only work for one paragraph only. Multiple paragraphs, -lists, headers, etc will not render correctly._ +lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._ ### Note @@ -232,6 +336,31 @@ which renders in docs.gitlab.com to: If the text spans across multiple lines it's OK to split the line. +For multiple paragraphs, use the symbol `>` before every line: + +```md +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list +> +> ### This is an `h3` +``` + +Which renders to: + +> This is the first paragraph. +> +> This is the second paragraph. +> +> - This is a list item +> - Second item in the list +> +> ### This is an `h3` +>{:.no_toc} + ## Specific sections and terms To mention and/or reference specific terms in GitLab, please follow the styles @@ -251,7 +380,7 @@ below. (in that order) that introduced it. The above quote would be then transformed to: ```md - > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) in GitLab 8.3. + > [Introduced](<link-to-issue>) in GitLab 8.3. ``` - If the feature is only available in GitLab Enterprise Edition, don't forget to mention @@ -259,10 +388,22 @@ below. the feature is available in: ```md - > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/1242) - in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. + > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. ``` +#### Early versions of EE + +If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)): + +- Declare it as "Introduced in GitLab Enterprise Edition X.Y". +- Note which tier the feature is available in. + +For example: + +```md +> [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +``` + ### Product badges When a feature is available in EE-only tiers, add the corresponding tier according to the @@ -276,18 +417,18 @@ feature availability: To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the keyword "only": +- For GitLab Core: `**[CORE ONLY]**`. - For GitLab Starter: `**[STARTER ONLY]**`. - For GitLab Premium: `**[PREMIUM ONLY]**`. - For GitLab Ultimate: `**[ULTIMATE ONLY]**`. -- For GitLab Core: `**[CORE ONLY]**`. The tier should be ideally added to headers, so that the full badge will be displayed. -But it can be also mentioned from paragraphs, list items, and table cells. For these cases, -the tier mention will be represented by an orange question mark. +However, it can be also mentioned from paragraphs, list items, and table cells. For these cases, +the tier mention will be represented by an orange question mark that will show the tiers on hover. E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**. The absence of tiers' mentions mean that the feature is available in GitLab Core, -GitLab.com Free, and higher tiers. +GitLab.com Free, and all higher tiers. #### How it works @@ -303,7 +444,7 @@ avoid duplication, link to the special document that can be found in [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will read like: -``` +```md Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) for the changes to take effect. ``` @@ -334,8 +475,8 @@ prefer to document it in the CE docs to avoid duplication. Configuration settings include: -- Settings that touch configuration files in `config/`. -- NGINX settings and settings in `lib/support/` in general. +1. Settings that touch configuration files in `config/`. +1. NGINX settings and settings in `lib/support/` in general. When there is a list of steps to perform, usually that entails editing the configuration file and reconfiguring/restarting GitLab. In such case, follow @@ -372,13 +513,13 @@ the style below as a guide: In this case: -- before each step list the installation method is declared in bold -- three dashes (`---`) are used to create a horizontal line and separate the +- Before each step list the installation method is declared in bold +- Three dashes (`---`) are used to create a horizontal line and separate the two methods -- the code blocks are indented one or more spaces under the list item to render +- The code blocks are indented one or more spaces under the list item to render correctly -- different highlighting languages are used for each config in the code block -- the [references](#references) guide is used for reconfigure/restart +- Different highlighting languages are used for each config in the code block +- The [references](#references) guide is used for reconfigure/restart ### Fake tokens @@ -389,19 +530,19 @@ low. You can use the following fake tokens as examples. -| **Token type** | **Token value** | -| --------------------- | --------------------------------- | -| Private user token | `9koXpg98eAheJpvBs5tK` | -| Personal access token | `n671WNGecHugsdEDPsyo` | +| **Token type** | **Token value** | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `9koXpg98eAheJpvBs5tK` | +| Personal access token | `n671WNGecHugsdEDPsyo` | | Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | | Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | -| Secret CI variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | -| Trigger token | `be20d8dcc028677c931e04f3871a9b` | -| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | -| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | -| Request profile token | `7VgpS4Ax5utVD2esNstz` | +| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | ### API @@ -424,16 +565,16 @@ on this document. Further explanation is given below. Use the following table headers to describe the methods. Attributes should always be in code blocks using backticks (``` ` ```). -``` +```md | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|:----------|:-----|:---------|:------------| ``` Rendered example: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user` | string | yes | The GitLab username | +| Attribute | Type | Required | Description | +|:----------|:-------|:---------|:--------------------| +| `user` | string | yes | The GitLab username | #### cURL commands @@ -445,12 +586,12 @@ Rendered example: - Prefer to use examples using the personal access token and don't pass data of username and password. -| Methods | Description | -| ------- | ----------- | +| Methods | Description | +|:-------------------------------------------|:------------------------------------------------------| | `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed | -| `-X POST` | Use this method when creating new objects | -| `-X PUT` | Use this method when updating existing objects | -| `-X DELETE` | Use this method when removing existing objects | +| `-X POST` | Use this method when creating new objects | +| `-X PUT` | Use this method when updating existing objects | +| `-X DELETE` | Use this method when removing existing objects | #### cURL Examples diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 52bc059a925..75ce8640e87 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -7,16 +7,16 @@ description: Learn the process of shipping documentation for GitLab. At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process. - Product Managers (PMs): in the issue for all new and updated features, -PMs include specific documentation requirements that the developer who is -writing or updating the docs must meet, along with feature descriptions -and use cases. They call out any specific areas where collaborating with -a technical writer is recommended, and usually act as the first reviewer -of the docs. + PMs include specific documentation requirements that the developer who is + writing or updating the docs must meet, along with feature descriptions + and use cases. They call out any specific areas where collaborating with + a technical writer is recommended, and usually act as the first reviewer + of the docs. - Developers: author documentation and merge it on time (up to a week after -the feature freeze). + the feature freeze). - Technical Writers: review each issue to ensure PM's requirements are complete, -help developers with any questions throughout the process, and act as the final -reviewer of all new and updated docs content before it's merged. + help developers with any questions throughout the process, and act as the final + reviewer of all new and updated docs content before it's merged. ## Requirements @@ -112,17 +112,17 @@ and the missed-deliverable due date (the 14th of each month) are both respected. The developer should add to the feature MR the documentation containing: - The [documentation blurb](structure.md#documentation-blurb): copy the -feature name, overview/description, and use cases from the feature issue + feature name, overview/description, and use cases from the feature issue - Instructions: write how to use the feature, step by step, with no gaps. - [Crosslink for discoverability](structure.md#discoverability): link with -internal docs and external resources (if applicable) + internal docs and external resources (if applicable) - Index: link the new doc or the new heading from the higher-level index -for [discoverability](#discoverability) + for [discoverability](#discoverability) - [Screenshots](styleguide.md#images): when necessary, add screenshots for: - Illustrating a step of the process - Indicating the location of a navigation menu - Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign -the correct milestone + the correct milestone - Assign the PM for review - When done, mention the `@gl\-docsteam` in the MR asking for review - **Due date**: feature freeze date and time @@ -133,10 +133,10 @@ If the docs aren't being shipped within the feature MR: - Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template) - Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>` -(product label == CI/CD, Pages, Prometheus, etc) + (product label == CI/CD, Pages, Prometheus, etc) - Add the correct milestone - Create a new MR for shipping the docs changes and follow the same -process [described above](#documentation-shipped-in-the-feature-mr) + process [described above](#documentation-shipped-in-the-feature-mr) - Use the MR description template called "Documentation" - Add the same labels and milestone as you did for the issue - Assign the PM for review @@ -162,9 +162,9 @@ The **due date** for **merging** `missed-deliverable` MRs is on the - **Planning** - Once an issue contains a Documentation label and the current milestone, a -technical writer reviews the Product Manager's documentation requirements + technical writer reviews the Product Manager's documentation requirements. - Once the documentation requirements are approved, the technical writer can -work with the developer to discuss any documentation questions and plans/outlines, as needed. + work with the developer to discuss any documentation questions and plans/outlines, as needed. - **Review** - A technical writer must review the documentation for: - Clarity @@ -183,4 +183,3 @@ work with the developer to discuss any documentation questions and plans/outline - Describe the difference between new features and feature updates - Creating a new doc vs updating an existing doc --> - diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index f9e6efa2c30..790b1bf951b 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -119,10 +119,20 @@ This also applies to views. ### EE features based on CE features -For features that build on existing CE features, write a module in the -`EE` namespace and `prepend` it in the CE class. This makes conflicts -less likely to happen during CE to EE merges because only one line is -added to the CE class - the `prepend` line. +For features that build on existing CE features, write a module in the `EE` +namespace and `prepend` it in the CE class, on the last line of the file that +the class resides in. This makes conflicts less likely to happen during CE to EE +merges because only one line is added to the CE class - the `prepend` line. For +example, to prepend a module into the `User` class you would use the following +approach: + +```ruby +class User < ActiveRecord::Base + # ... lots of code here ... +end + +User.prepend(EE::User) +``` Since the module would require an `EE` namespace, the file should also be put in an `ee/` sub-directory. For example, we want to extend the user model @@ -171,7 +181,7 @@ There are a few gotchas with it: class Base def execute return unless enabled? - + # ... # ... end @@ -185,12 +195,12 @@ There are a few gotchas with it: class Base def execute return unless enabled? - + do_something end - + private - + def do_something # ... # ... @@ -204,14 +214,14 @@ There are a few gotchas with it: ```ruby module EE::Base extend ::Gitlab::Utils::Override - + override :do_something def do_something # Follow the above pattern to call super and extend it end end ``` - + This would require updating CE first, or make sure this is back ported to CE. When prepending, place them in the `ee/` specific sub-directory, and @@ -231,7 +241,6 @@ the existing file: ```ruby class ApplicationController < ActionController::Base - prepend EE::ApplicationController # ... def after_sign_out_path_for(resource) @@ -240,6 +249,8 @@ class ApplicationController < ActionController::Base # ... end + +ApplicationController.prepend(EE::ApplicationController) ``` And create a new file in the `ee/` sub-directory with the altered @@ -332,6 +343,21 @@ full implementation details. [ce-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12373 [ee-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2199 +### Code in `config/routes` + +When we add `draw :admin` in `config/routes.rb`, the application will try to +load the file located in `config/routes/admin.rb`, and also try to load the +file located in `ee/config/routes/admin.rb`. + +In EE, it should at least load one file, at most two files. If it cannot find +any files, an error will be raised. In CE, since we don't know if there will +be an EE route, it will not raise any errors even if it cannot find anything. + +This means if we want to extend a particular CE route file, just add the same +file located in `ee/config/routes`. If we want to add an EE only route, we +could still put `draw :ee_only` in both CE and EE, and add +`ee/config/routes/ee_only.rb` in EE, similar to `render_if_exists`. + ### Code in `app/controllers/` In controllers, the most common type of conflict is with `before_action` that @@ -393,7 +419,7 @@ view. For instance the approval code in the project's settings page. **Mitigations** Blocks of code that are EE-specific should be moved to partials. This -avoids conflicts with big chunks of HAML code that that are not fun to +avoids conflicts with big chunks of HAML code that are not fun to resolve when you add the indentation to the equation. EE-specific views should be placed in `ee/app/views/`, using extra @@ -485,7 +511,7 @@ module EE params do requires :id, type: String, desc: 'The ID of a project' end - resource :projects, requirements: ::API::API::PROJECT_ENDPOINT_REQUIREMENTS do + resource :projects, requirements: ::API::API::NAMESPACE_OR_PROJECT_REQUIREMENTS do # ... end end @@ -518,8 +544,6 @@ module API end end - prepend EE::API::MergeRequests - params :optional_params do # CE specific params go here... @@ -527,6 +551,8 @@ module API end end end + +API::MergeRequests.prepend(EE::API::MergeRequests) ``` And then we could override it in EE module: @@ -567,10 +593,10 @@ module API authorize_read_builds! end end - - prepend EE::API::JobArtifacts end end + +API::JobArtifacts.prepend(EE::API::JobArtifacts) ``` And then we can follow regular object-oriented practices to override it: @@ -611,8 +637,6 @@ module API end end - prepend EE::API::MergeRequests - put ':id/merge_requests/:merge_request_iid/merge' do merge_request = find_project_merge_request(params[:merge_request_iid]) @@ -624,6 +648,8 @@ module API end end end + +API::MergeRequests.prepend(EE::API::MergeRequests) ``` Note that `update_merge_request_ee` doesn't do anything in CE, but @@ -661,27 +687,37 @@ or not we really need to extend it from EE. For now we're not using it much. Sometimes we need to use different arguments for a particular API route, and we can't easily extend it with an EE module because Grape has different context in -different blocks. In order to overcome this, we could use class methods from the -API class. +different blocks. In order to overcome this, we need to move the data to a class +method that resides in a separate module or class. This allows us to extend that +module or class before its data is used, without having to place a `prepend` in +the middle of CE code. For example, in one place we need to pass an extra argument to `at_least_one_of` so that the API could consider an EE-only argument as the -least argument. This is not quite beautiful but it's working: +least argument. We would approach this as follows: ```ruby +# api/merge_requests/parameters.rb module API class MergeRequests < Grape::API - def self.update_params_at_least_one_of - %i[ - assignee_id - description - ] + module Parameters + def self.update_params_at_least_one_of + %i[ + assignee_id + description + ] + end end + end +end - prepend EE::API::MergeRequests +API::MergeRequests::Parameters.prepend(EE::API::MergeRequests::Parameters) +# api/merge_requests.rb +module API + class MergeRequests < Grape::API params do - at_least_one_of(*::API::MergeRequests.update_params_at_least_one_of) + at_least_one_of(*Parameters.update_params_at_least_one_of) end end end @@ -693,16 +729,18 @@ And then we could easily extend that argument in the EE class method: module EE module API module MergeRequests - extend ActiveSupport::Concern + module Parameters + extend ActiveSupport::Concern - class_methods do - extend ::Gitlab::Utils::Override + class_methods do + extend ::Gitlab::Utils::Override - override :update_params_at_least_one_of - def update_params_at_least_one_of - super.push(*%i[ - squash - ]) + override :update_params_at_least_one_of + def update_params_at_least_one_of + super.push(*%i[ + squash + ]) + end end end end @@ -713,6 +751,78 @@ end It could be annoying if we need this for a lot of routes, but it might be the simplest solution right now. +This approach can also be used when models define validations that depend on +class methods. For example: + +```ruby +# app/models/identity.rb +class Identity < ActiveRecord::Base + def self.uniqueness_scope + [:provider] + end + + prepend EE::Identity + + validates :extern_uid, + allow_blank: true, + uniqueness: { scope: uniqueness_scope, case_sensitive: false } +end + +# ee/app/models/ee/identity.rb +module EE + module Identity + extend ActiveSupport::Concern + + class_methods do + extend ::Gitlab::Utils::Override + + def uniqueness_scope + [*super, :saml_provider_id] + end + end + end +end +``` + +Instead of taking this approach, we would refactor our code into the following: + +```ruby +# ee/app/models/ee/identity/uniqueness_scopes.rb +module EE + module Identity + module UniquenessScopes + extend ActiveSupport::Concern + + class_methods do + extend ::Gitlab::Utils::Override + + def uniqueness_scope + [*super, :saml_provider_id] + end + end + end + end +end + +# app/models/identity/uniqueness_scopes.rb +class Identity < ActiveRecord::Base + module UniquenessScopes + def self.uniqueness_scope + [:provider] + end + end +end + +Identity::UniquenessScopes.prepend(EE::Identity::UniquenessScopes) + +# app/models/identity.rb +class Identity < ActiveRecord::Base + validates :extern_uid, + allow_blank: true, + uniqueness: { scope: Identity::UniquenessScopes.scopes, case_sensitive: false } +end +``` + ### Code in `spec/` When you're testing EE-only features, avoid adding examples to the diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md index ee0c2d534ff..0e9126ee667 100644 --- a/doc/development/fe_guide/components.md +++ b/doc/development/fe_guide/components.md @@ -6,7 +6,7 @@ ## Dropdowns -See also the [corresponding UX guide](../ux_guide/components.md#dropdowns). +See also the [corresponding UX guide](https://design.gitlab.com/#/components/dropdowns). ### How to style a bootstrap dropdown 1. Use the HTML structure provided by the [docs][bootstrap-dropdowns] @@ -40,7 +40,7 @@ See also the [corresponding UX guide](../ux_guide/components.md#dropdowns). ## Modals -See also the [corresponding UX guide](../ux_guide/components.md#modals). +See also the [corresponding UX guide](https://design.gitlab.com/#/components/modals). We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue) diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index 112ff3419d9..ce96a9fc8ae 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.md @@ -123,7 +123,7 @@ droplab.init().addData([{ ``` Alternatively, you can specify a specific dropdown to add this data to but passing -the data as the second argument and and the `id` of the trigger element as the first argument. +the data as the second argument and the `id` of the trigger element as the first argument. ```html <a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a> diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md new file mode 100644 index 00000000000..f55f01720fd --- /dev/null +++ b/doc/development/fe_guide/graphql.md @@ -0,0 +1,83 @@ +# GraphQL + +We use [Apollo] and [Vue Apollo][vue-apollo] for working with GraphQL +on the frontend. + +In order to use GraphQL, you need to enable the `graphql` feature flag, +read more about [Feature Flags][feature-flags]. + +## Apollo Client + +To save duplicated clients getting created in different apps, we have a +[default client][defualt-client] that should be used. This setups the +Apollo client with the correct URL and also sets the CSRF headers. + +## GraphQL Queries + +To save query compilation at runtime, webpack can directly import `.graphql` +files. This allows webpack to preprocess the query at compile time instead +of the client doing compilation of queries. + +## Usage in Vue + +To use Vue Apollo, import the [Vue Apollo][vue-apollo] plugin as well +as the default client. This should be created at the same point +the Vue application is mounted. + +```javascript +import Vue from 'vue'; +import VueApollo from 'vue-apollo'; +import defaultClient from '~/lib/graphql'; +Vue.use(VueApollo); + +const apolloProvider = new VueApollo({ + defaultClient, +}); + +new Vue({ + ..., + apolloProvider, + ... +}); +``` + +Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs]. + +### Testing + +With [Vue test utils][vue-test-utils] it is easy to quickly test components that +fetch GraphQL queries. The simplest way is to use `shallowMount` and then set +the data on the component + +```javascript +it('tests apollo component', () => { + const vm = shallowMount(App); + + vm.setData({ + ...mock data + }); +}); +``` + +## Usage outside of Vue + +It is also possible to use GraphQL outside of Vue by directly importing +and using the default client with queries. + +```javascript +import defaultClient from '~/lib/graphql'; +import query from './query.graphql'; + +defaultClient.query(query) + .then(result => console.log(result)); +``` + +Read more about the [Apollo] client in the [Apollo documentation][apollo-client-docs]. + +[Apollo]: https://www.apollographql.com/ +[vue-apollo]: https://github.com/Akryum/vue-apollo/ +[vue-apollo-docs]: https://akryum.github.io/vue-apollo/ +[feature-flags]: ../feature_flags.md +[default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js +[apollo-client-docs]: https://www.apollographql.com/docs/tutorial/client.html +[vue-test-utils]: https://vue-test-utils.vuejs.org/ diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 3d8da6accc1..533e2001300 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -3,7 +3,7 @@ We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository. This repository is published on [npm][npm] and managed as a dependency via yarn. You can browse all available Icons and Illustrations [here][svg-preview]. -To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`. +To upgrade to a new version run `yarn upgrade @gitlab/svgs`. ## Icons @@ -111,6 +111,6 @@ export default { </template> ``` -[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs +[npm]: https://www.npmjs.com/package/@gitlab/svgs [gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs [svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 11b9a2e6a64..cca3ad6fae6 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -54,6 +54,9 @@ Vuex specific design patterns and practices. ## [Axios](axios.md) Axios specific practices and gotchas. +## [GraphQL](graphql.md) +How to use GraphQL + ## [Icons and Illustrations](icons.md) How we use SVG for our Icons and Illustrations. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 656ddd868cd..1e0529262ad 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -1,11 +1,13 @@ # Style guides and linting + See the relevant style guides for our guidelines and for information on linting: ## JavaScript + We defer to [Airbnb][airbnb-js-style-guide] on most style-related conventions and enforce them with eslint. -See [our current .eslintrc][eslintrc] for specific rules and patterns. +See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc.yml) for specific rules and patterns. ### Common @@ -21,10 +23,10 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable */ - + // better /* eslint-disable some-rule, some-other-rule */ - + // best // nothing :) ``` @@ -34,14 +36,14 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable no-new */ - + import Foo from 'foo'; - + new Foo(); - + // better import Foo from 'foo'; - + // eslint-disable-next-line no-new new Foo(); ``` @@ -58,11 +60,11 @@ followed by any global declarations, then a blank newline prior to any imports o /* global Foo */ /* eslint-disable no-new */ import Bar from './bar'; - + // good /* eslint-disable no-new */ /* global Foo */ - + import Bar from './bar'; ``` @@ -73,7 +75,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad /* globals Flash, Cookies, jQuery */ - + // good /* global Flash */ /* global Cookies */ @@ -85,7 +87,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad fn(p1, p2, p3, p4) {} - + // good fn(options) {} ``` @@ -191,28 +193,28 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad const values = {foo: 1}; - + function impureFunction(items) { const bar = 1; - + items.foo = items.a * bar + 2; - + return items.a; } - + const c = impureFunction(values); - + // good var values = {foo: 1}; - + function pureFunction (foo) { var bar = 1; - + foo = foo * bar + 2; - + return foo; } - + var c = pureFunction(values.foo); ``` @@ -231,10 +233,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod document.addEventListener('click', this.handleCallback) }, handleCallback() { - + } } - + // Good export class Foo { constructor() { @@ -253,12 +255,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript const users = [ { name: 'Foo' }, { name: 'Bar' } ]; - + // bad users.forEach((user, index) => { user.id = index; }); - + // good const usersWithId = users.map((user, index) => { return Object.assign({}, user, { id: index }); @@ -272,10 +274,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad +'10' // 10 - + // good Number('10') // 10 - + // better parseInt('10', 10); ``` @@ -289,7 +291,7 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod <button class="add-user"> Add User </button> - + // good <button class="js-add-user"> Add User @@ -299,10 +301,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ### Vue.js #### `eslint-vue-plugin` + We default to [eslint-vue-plugin][eslint-plugin-vue], with the `plugin:vue/recommended`. Please check this [rules][eslint-plugin-vue-rules] for more documentation. #### Basic Rules + 1. The service has it's own file 1. The store has it's own file 1. Use a function in the bundle file to instantiate the Vue component: @@ -314,7 +318,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. new Component({}) } } - + // good document.addEventListener('DOMContentLoaded', () => new Vue({ el: '#element', @@ -336,7 +340,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. } } } - + // good class Store { constructor() { @@ -354,14 +358,14 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad import cardBoard from 'cardBoard.vue' - + components: { cardBoard, }; - + // good import CardBoard from 'cardBoard.vue' - + components: { CardBoard, }; @@ -373,13 +377,13 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad <component class="btn"> - + // good <component css-class="btn"> - + // bad <component myProp="prop" /> - + // good <component my-prop="prop" /> ``` @@ -387,6 +391,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 #### Alignment + 1. Follow these alignment styles for the template method: 1. With more than one attribute, all attributes should be on a new line: @@ -395,31 +400,31 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. // bad <component v-if="bar" param="baz" /> - + <button class="btn">Click me</button> - + // good <component v-if="bar" param="baz" /> - + <button class="btn"> Click me </button> ``` - + 1. The tag can be inline if there is only one attribute: ```javascript // good <component bar="bar" /> - + // good <component bar="bar" /> - + // bad <component bar="bar" /> @@ -434,7 +439,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. template: ` <button :class='style'>Button</button> ` - + // good template: ` <button :class="style">Button</button> @@ -447,7 +452,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad props: ['foo'] - + // good props: { foo: { @@ -467,7 +472,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. type: String, } } - + // good props: { foo: { @@ -490,7 +495,7 @@ On those a default key should not be provided. required: false, } } - + // good props: { foo: { @@ -499,7 +504,7 @@ On those a default key should not be provided. default: 'bar' } } - + // good props: { foo: { @@ -534,7 +539,7 @@ On those a default key should not be provided. ```javascript // bad <component v-on:click="eventHandler"/> - + // good <component @click="eventHandler"/> ``` @@ -544,7 +549,7 @@ On those a default key should not be provided. ```javascript // bad <component v-bind:class="btn"/> - + // good <component :class="btsn"/> ``` @@ -556,7 +561,7 @@ On those a default key should not be provided. ```javascript // bad <component></component> - + // good <component /> ``` @@ -650,7 +655,7 @@ Useful links: title="Some tooltip text"> Text </span> - + // good <span v-tooltip @@ -666,10 +671,10 @@ Useful links: ```javascript // bad <span data-original-title="tooltip text">Foo</span> - + // good <span title="tooltip text">Foo</span> - + $('span').tooltip('_fixTitle'); ``` diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 48eb6d0a7d6..b09243598d5 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -183,9 +183,11 @@ Don't use ID selectors in CSS. ``` ### Variables + Before adding a new variable for a color or a size, guarantee: -1. There isn't already one -2. There isn't a similar one we can use instead. + +- There isn't already one +- There isn't a similar one we can use instead. ## Linting diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index f6cbd11042c..ccfd465531a 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -221,6 +221,14 @@ const vm = mountComponent(Component, data); The main return value of a Vue component is the rendered output. In order to test the component we need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that: +## Vue.js Expert Role +One should apply to be a Vue.js expert by opening an MR when the Merge Request's they create and review show: +- Deep understanding of Vue and Vuex reactivy +- Vue and Vuex code are structured according to both official and our guidelines +- Full understanding of testing a Vue and Vuex application +- Vuex code follows the [documented pattern](./vuex.md#actions-pattern-request-and-receive-namespaces) +- Knowledge about the existing Vue and Vuex applications and existing reusable components + [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index f582f5da323..0f57835fb87 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -114,19 +114,21 @@ When a request is made we often want to show a loading state to the user. Instead of creating an action to toggle the loading state and dispatch it in the component, create: + 1. An action `requestSomething`, to toggle the loading state 1. An action `receiveSomethingSuccess`, to handle the success callback 1. An action `receiveSomethingError`, to handle the error callback 1. An action `fetchSomething` to make the request. 1. In case your application does more than a `GET` request you can use these as examples: - 1. `PUT`: `createSomething` - 2. `POST`: `updateSomething` - 3. `DELETE`: `deleteSomething` + - `PUT`: `createSomething` + - `POST`: `updateSomething` + - `DELETE`: `deleteSomething` The component MUST only dispatch the `fetchNamespace` action. Actions namespaced with `request` or `receive` should not be called from the component The `fetch` action will be responsible to dispatch `requestNamespace`, `receiveNamespaceSuccess` and `receiveNamespaceError` By following this pattern we guarantee: + 1. All applications follow the same pattern, making it easier for anyone to maintain the code 1. All data in the application follows the same lifecycle pattern 1. Actions are contained and human friendly @@ -297,12 +299,12 @@ export default { ```javascript // component.vue - + // bad created() { this.$store.commit('mutation'); } - + // good created() { this.$store.dispatch('action'); diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 417298205f5..1019a1fd0e2 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -33,7 +33,7 @@ You can follow the progress on that [in the issue on our issue tracker](https:// In general, it's better to have a group- or user-based gate, and you should prefer it over the use of percentage gates. This would make debugging easier, as you -filter for example logs and errors based on actors too. Futhermore, this allows +filter for example logs and errors based on actors too. Furthermore, this allows for enabling for the `gitlab-org` group first, while the rest of the users aren't impacted. @@ -69,6 +69,37 @@ For more information about rolling out changes using feature flags, refer to the [Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md) guide. +### Frontend + +For frontend code you can use the method `push_frontend_feature_flag`, which is +available to all controllers that inherit from `ApplicationController`. Using +this method you can expose the state of a feature flag as follows: + +```ruby +before_action do + push_frontend_feature_flag(:vim_bindings) +end + +def index + # ... +end + +def edit + # ... +end +``` + +You can then check for the state of the feature flag in JavaScript as follows: + +```javascript +if ( gon.features.vimBindings ) { + // ... +} +``` + +The name of the feature flag in JavaScript will always be camelCased, meaning +that checking for `gon.features.vim_bindings` would not work. + ### Specs In the test environment `Feature.enabled?` is stubbed to always respond to `true`, @@ -81,3 +112,8 @@ feature flag. You can stub a feature flag as follows: ```ruby stub_feature_flags(my_feature_flag: false) ``` + +## Enabling a feature flag + +Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md). + diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 4f9ca1920a5..32beafad307 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -1,15 +1,11 @@ # GitLab Developers Guide to Working with Gitaly [Gitaly](https://gitlab.com/gitlab-org/gitaly) is a high-level Git RPC service used by GitLab CE/EE, -Workhorse and GitLab-Shell. All Rugged operations in GitLab CE/EE are currently being phased out to -be replaced by Gitaly API calls. - -Visit the [Gitaly Migration Board](https://gitlab.com/gitlab-org/gitaly/boards/331341) for current -status of the migration. +Workhorse and GitLab-Shell. ## Developing new Git features -Starting with Gitlab 10.8, all new Git features should be developed in +Starting with GitLab 10.8, all new Git features should be developed in Gitaly. > This is a new process that is not clearly defined yet. If you want @@ -52,57 +48,6 @@ comfortable writing Go code. There is documentation for this approach in [the Gitaly repo](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/ruby_endpoint.md). -## Modifying existing Git features - -If you modify existing Git features in `lib/gitlab/git` you need to make -sure the changes also work in Gitaly. Because we are still in the -migration process there are a number of subtle pitfalls. Features that -have been migrated have dual implementations (Gitaly and local). The -Gitaly implementation may or may not use a vendored (and therefore -possibly outdated) copy of the local implementation in `lib/gitlab/git`. - -To avoid unexpected problems and conflicts, all changes to -`lib/gitlab/git` need to be approved by a member of the Gitaly team. - -For the time being, while the Gitaly migration is still in progress, -there should be no Enterprise Edition-only Git code in -`lib/gitlab/git`. Also no mixins. - -## Feature Flags - -Gitaly makes heavy use of [feature flags](feature_flags.md). - -Each Rugged-to-Gitaly migration goes through a [series of phases](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/MIGRATION_PROCESS.md): - -* **Opt-In**: by default the Rugged implementation is used. - * Production instances can choose to enable the Gitaly endpoint by enabling the feature flag. - * For testing purposes, you may wish to enable all feature flags by default. This can be done by exporting the following - environment variable: `GITALY_FEATURE_DEFAULT_ON=1`. - * On developer instances (ie, when `Rails.env.development?` is true), the Gitaly endpoint - is enabled by default, but can be _disabled_ using feature flags. -* **Opt-Out**: by default, the Gitaly endpoint is used, but the feature can be explicitly disabled using the feature flag. -* **Mandatory**: The migration is complete and cannot be disabled. The old codepath is removed. - -### Enabling and Disabling Feature - -In the Rails console, type: - -```ruby -Feature.enable(:gitaly_feature_name) -Feature.disable(:gitaly_feature_name) -``` - -Where `gitaly_feature_name` is the name of the Gitaly feature. This can be determined by finding the appropriate -`gitaly_migrate` code block, for example: - -```ruby -gitaly_migrate(:tag_names) do -... -end -``` - -Since Gitaly features are always prefixed with `gitaly_`, the name of the feature flag in this case would be `gitaly_tag_names`. - ## Gitaly-Related Test Failures If your test-suite is failing with Gitaly issues, as a first step, try running: diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 0d558583bb8..863ac049db6 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -99,8 +99,8 @@ This worker will wrap up the import process by performing some housekeeping Advancing stages is done in one of two ways: -1. Scheduling the worker for the next stage directly. -2. Scheduling a job for `Gitlab::GithubImport::AdvanceStageWorker` which will +- Scheduling the worker for the next stage directly. +- Scheduling a job for `Gitlab::GithubImport::AdvanceStageWorker` which will advance the stage when all work of the current stage has been completed. The first approach should only be used by workers that perform all their work in @@ -131,7 +131,7 @@ our import as failed because of this. To prevent this from happening we periodically refresh the expiration time of the import process. This works by storing the JID of the import job in the database, then refreshing this JID's TTL at various stages throughout the import -process. This is done by calling `Project#refresh_import_jid_expiration`. By +process. This is done by calling `ProjectImportState#refresh_jid_expiration`. By refreshing this TTL we can ensure our import does not get marked as failed so long we're still performing work. @@ -147,7 +147,7 @@ We handle this by doing the following: 1. Once we hit the rate limit all jobs will automatically reschedule themselves in such a way that they are not executed until the rate limit has been reset. -2. We cache the mapping of GitHub users to GitLab users in Redis. +1. We cache the mapping of GitHub users to GitLab users in Redis. More information on user caching can be found below. @@ -157,21 +157,21 @@ When mapping GitHub users to GitLab users we need to (in the worst case) perform: 1. One API call to get the user's Email address. -2. Two database queries to see if a corresponding GitLab user exists. One query +1. Two database queries to see if a corresponding GitLab user exists. One query will try to find the user based on the GitHub user ID, while the second query is used to find the user using their GitHub Email address. Because this process is quite expensive we cache the result of these lookups in Redis. For every user looked up we store three keys: -1. A Redis key mapping GitHub usernames to their Email addresses. -2. A Redis key mapping a GitHub Email addresses to a GitLab user ID. -3. A Redis key mapping a GitHub user ID to GitLab user ID. +- A Redis key mapping GitHub usernames to their Email addresses. +- A Redis key mapping a GitHub Email addresses to a GitLab user ID. +- A Redis key mapping a GitHub user ID to GitLab user ID. There are two types of lookups we cache: -1. A positive lookup, meaning we found a GitLab user ID. -2. A negative lookup, meaning we didn't find a GitLab user ID. Caching this +- A positive lookup, meaning we found a GitLab user ID. +- A negative lookup, meaning we didn't find a GitLab user ID. Caching this prevents us from performing the same work for users that we know don't exist in our GitLab database. diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 84dea7ce9aa..a5a34d82bec 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -92,7 +92,7 @@ describe API::Labels do end ``` -## Avoid using `allow_any_instance_of` in RSpec +## Avoid using `expect_any_instance_of` or `allow_any_instance_of` in RSpec ### Why @@ -102,7 +102,7 @@ end error like this: ``` - 1.1) Failure/Error: allow_any_instance_of(ApplicationSetting).to receive_messages(messages) + 1.1) Failure/Error: expect_any_instance_of(ApplicationSetting).to receive_messages(messages) Using `any_instance` to stub a method (elasticsearch_indexing) that has been defined on a prepended module (EE::ApplicationSetting) is not supported. ``` @@ -112,7 +112,7 @@ Instead of writing: ```ruby # Don't do this: -allow_any_instance_of(Project).to receive(:add_import_job) +expect_any_instance_of(Project).to receive(:add_import_job) ``` We could write: diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index 7290a175501..c44690a4c5d 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -50,3 +50,5 @@ able to proofread and instructions on becoming a proofreader yourself. ## Release Translations are typically included in the next major or minor release. + +See [Merging translations from Crowdin](merging_translations.md) diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md new file mode 100644 index 00000000000..d172aa6da21 --- /dev/null +++ b/doc/development/i18n/merging_translations.md @@ -0,0 +1,60 @@ +# Merging translations from Crowdin + +Crowdin automatically syncs the `gitlab.pot` file presenting newly +added translations to the community of translators. + +At the same time, it creates a merge request to merge all newly added +& approved translations. Find the [merge reqeust created by +`gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) +to see new and merged merge requests. They are created in EE and need +to be ported to CE manually. + +## Validation + +By default Crowdin commits translations with `[skip ci]` in the commit +message. This is done to avoid a bunch of pipelines being run. Before +merging translations, make sure to trigger a pipeline to validate +translations, we have static analysis validating things Crowdin +doesn't do. Create a [new pipeline](https://gitlab.com/gitlab-org/gitlab-ee/pipelines/new) for the +`master-i18n` branch. + +If there are validation errors, the easiest solution is to disapprove +the offending string in Crowdin, leaving a comment with what is +required to fix the offense. There is an +[issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/49208) +suggesting to automate this process. Disapproving will exclude the +invalid translation, the merge request will be updated within a few +minutes. + +It might be handy to pause the integration on the Crowdin side for a +little while so translations don't keep coming. This can be done by +clicking `Pause sync` on the [Crowdin integration settings +page](https://translate.gitlab.com/project/gitlab-ee/settings#integration). + +When all failures are resolved, the translations need to be double +checked once more [as discussed in this +issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/37850). + +## Merging translations + +When all translations are found good and pipelines pass the +translations can be merged into the master branch. After that is done, +create a new merge request cherry-picking the translations from EE to +CE. When merging the translations, make sure to check the `Remove +source branch` checkbox, so Crowdin recreates the `master-i18n` from +master after the new translation was merged. + +We are discussing automating this entire process +[here](https://gitlab.com/gitlab-org/gitlab-ce/issues/39309). + +## Recreate the merge request + +Crowdin creates a new merge request as soon as the old one is closed +or merged. But it won't recreate the `master-i18n` branch every +time. To force Crowdin to recreate the branch, close any [open merge +request](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) +and delete the +[`master-18n`](https://gitlab.com/gitlab-org/gitlab-ee/branches/all?utf8=%E2%9C%93&search=master-i18n). + +This might be needed when the merge request contains failures that +have been fixed on master. diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 6e57ffbae27..fd4df64999b 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -5,7 +5,14 @@ are very appreciative of the work done by translators and proofreaders! ## Proofreaders +- Albanian + - Proofreaders needed. +- Arabic + - Proofreaders needed. - Bulgarian + - Lyubomir Vasilev - [Crowdin](https://crowdin.com/profile/lyubomirv) +- Catalan + - Proofreaders needed. - Chinese Simplified - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) - Chinese Traditional @@ -14,14 +21,31 @@ are very appreciative of the work done by translators and proofreaders! - Yi-Jyun Pan - [GitLab](https://gitlab.com/pan93412), [Crowdin](https://crowdin.com/profile/pan93412) - Chinese Traditional, Hong Kong - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) +- Czech + - Proofreaders needed. +- Danish + - Proofreaders needed. - Dutch - - Emily Hendle - [GitLab](https://gitlab.com/pundachan), [Crowdin](https://crowdin.com/profile/pandachan) + - Emily Hendle - [GitLab](https://gitlab.com/pundachan), [Crowdin](https://crowdin.com/profile/pandachan) - Esperanto +- Lyubomir Vasilev - [Crowdin](https://crowdin.com/profile/lyubomirv) +- Estonian + - Proofreaders needed. +- Filipino + - Proofreaders needed. - French - Davy Defaud - [GitLab](https://gitlab.com/DevDef), [Crowdin](https://crowdin.com/profile/DevDef) +- Galician + - Antón Méixome - [Crowdin](https://crowdin.com/profile/meixome) + - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt) - German + - Michael Hahnle - [GitLab](https://gitlab.com/mhah), [Crowdin](https://crowdin.com/profile/mhah) +- Greek + - Proofreaders needed. - Hebrew - Yaron Shahrabani - [GitLab](https://gitlab.com/yarons), [Crowdin](https://crowdin.com/profile/YaronSh) +- Hungarian + - Proofreaders needed. - Indonesian - Ahmad Naufal Mukhtar - [GitLab](https://gitlab.com/anaufalm), [Crowdin](https://crowdin.com/profile/anaufalm) - Italian @@ -32,18 +56,39 @@ are very appreciative of the work done by translators and proofreaders! - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) + - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie) +- Mongolian + - Proofreaders needed. +- Norwegian Bokmal + - Proofreaders needed. - Polish - Filip Mech - [GitLab](https://gitlab.com/mehenz), [Crowdin](https://crowdin.com/profile/mehenz) +- Portuguese + - Proofreaders needed. - Portuguese, Brazilian - Paulo George Gomes Bezerra - [GitLab](https://gitlab.com/paulobezerra), [Crowdin](https://crowdin.com/profile/paulogomes.rep) - André Gama - [GitLab](https://gitlab.com/andregamma), [Crowdin](https://crowdin.com/profile/ToeOficial) +- Romanian + - Proofreaders needed. - Russian - Nikita Grylov - [GitLab](https://gitlab.com/nixel2007), [Crowdin](https://crowdin.com/profile/nixel2007) - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin) + - NickVolynkin - [Crowdin](https://crowdin.com/profile/NickVolynkin) +- Serbian (Cyrillic) + - Proofreaders needed. +- Serbian (Latin) + - Proofreaders needed. +- Slovak + - Proofreaders needed. - Spanish + - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt) +- Turkish + - Proofreaders needed. - Ukrainian - Volodymyr Sobotovych - [GitLab](https://gitlab.com/wheleph), [Crowdin](https://crowdin.com/profile/wheleph) - Andrew Vityuk - [GitLab](https://gitlab.com/3_1_3_u), [Crowdin](https://crowdin.com/profile/andruwa13) +- Welsh + - Proofreaders needed. ## Become a proofreader @@ -75,6 +120,8 @@ are very appreciative of the work done by translators and proofreaders! have previously translated. 1. Your request to become a proofreader will be considered on the merits of - your previous translations. + your previous translations by [GitLab team members](https://about.gitlab.com/team/) + or [Core team members](https://about.gitlab.com/core-team/) who are fluent in + the language or current proofreaders. [proofreader-src]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/i18n/proofreader.md diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index a14c0752366..bef166f2aec 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -69,7 +69,7 @@ The easiest way to check if a method has been instrumented is to check its source location. For example: ```ruby -method = Rugged::TagCollection.instance_method(:[]) +method = Banzai::Renderer.method(:render) method.source_location ``` @@ -82,7 +82,7 @@ method (along with its source location), this is easier than running the above Ruby code. In case of the above snippet you'd run the following: ``` -$ Rugged::TagCollection#[] +$ Banzai::Renderer.render ``` This will print out something along the lines of: @@ -117,11 +117,11 @@ The block is executed and the execution time is stored as a set of fields in the currently running transaction. If no transaction is present the block is yielded without measuring anything. -3 values are measured for a block: +Three values are measured for a block: -1. The real time elapsed, stored in NAME_real_time. -2. The CPU time elapsed, stored in NAME_cpu_time. -3. The call count, stored in NAME_call_count. +- The real time elapsed, stored in NAME_real_time. +- The CPU time elapsed, stored in NAME_cpu_time. +- The call count, stored in NAME_call_count. Both the real and CPU timings are measured in milliseconds. diff --git a/doc/development/logging.md b/doc/development/logging.md new file mode 100644 index 00000000000..5c1d96b9e0c --- /dev/null +++ b/doc/development/logging.md @@ -0,0 +1,144 @@ +# GitLab Developers Guide to Logging + +[GitLab Logs](../administration/logs.md) play a critical role for both +administrators and GitLab team members to diagnose problems in the field. + +## Don't use `Rails.logger` + +Currently `Rails.logger` calls all get saved into `production.log`, which contains +a mix of Rails' logs and other calls developers have inserted in the code base. +For example: + +``` +Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200 +Processing by Projects::TreeController#show as HTML + Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"} + + ... + + Namespaces"."created_at" DESC, "namespaces"."id" DESC LIMIT 1 [["id", 26]] + CACHE (0.0ms) SELECT "members".* FROM "members" WHERE "members"."source_type" = 'Project' AND "members"."type" IN ('ProjectMember') AND "members"."source_id" = $1 AND "members"."source_type" = $2 AND "members"."user_id" = 1 ORDER BY "members"."created_at" DESC, "members"."id" DESC LIMIT 1 [["source_id", 18], ["source_type", "Project"]] + CACHE (0.0ms) SELECT "members".* FROM "members" WHERE "members"."source_type" = 'Project' AND "members". + (1.4ms) SELECT COUNT(*) FROM "merge_requests" WHERE "merge_requests"."target_project_id" = $1 AND ("merge_requests"."state" IN ('opened','reopened')) [["target_project_id", 18]] + Rendered layouts/nav/_project.html.haml (28.0ms) + Rendered layouts/_collapse_button.html.haml (0.2ms) + Rendered layouts/_flash.html.haml (0.1ms) + Rendered layouts/_page.html.haml (32.9ms) +Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms) +``` + +These logs suffer from a number of problems: + +1. They often lack timestamps or other contextual information (e.g. project ID, user) +2. They may span multiple lines, which make them hard to find via Elasticsearch. +3. They lack a common structure, which make them hard to parse by log +forwarders, such as Logstash or Fluentd. This also makes them hard to +search. + +Note that currently on GitLab.com, any messages in `production.log` will +NOT get indexed by Elasticsearch due to the sheer volume and noise. They +do end up in Google Stackdriver, but it is still harder to search for +logs there. See the [GitLab.com logging +documentation](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md) +for more details. + +## Use structured (JSON) logging + +Structured logging solves these problems. Consider the example from an API request: + +```json +{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30} +``` + +In a single line, we've included all the information that a user needs +to understand what happened: the timestamp, HTTP method and path, user +ID, etc. + +### How to use JSON logging + +Suppose you want to log the events that happen in a project +importer. You want to log issues created, merge requests, etc. as the +importer progresses. Here's what to do: + +1. Look at [the list of GitLab Logs](../administration/logs.md) to see +if your log message might belong with one of the existing log files. +1. If there isn't a good place, consider creating a new filename, but +check with a maintainer if it makes sense to do so. A log file should +make it easy for people to search pertinent logs in one place. For +example, `geo.log` contains all logs pertaining to GitLab Geo. +To create a new file: + 1. Choose a filename (e.g. `importer_json.log`). + 1. Create a new subclass of `Gitlab::JsonLogger`: + + ```ruby + module Gitlab + module Import + class Logger < ::Gitlab::JsonLogger + def self.file_name_noext + 'importer' + end + end + end + end + ``` + + 1. In your class where you want to log, you might initialize the logger as an instance variable: + + ```ruby + attr_accessor :logger + + def initialize + @logger = Gitlab::Import::Logger.build + end + ``` + + Note that it's useful to memoize this because creating a new logger + each time you log will open a file, adding unnecessary overhead. + +1. Now insert log messages into your code. When adding logs, + make sure to include all the context as key-value pairs: + + ```ruby + # BAD + logger.info("Unable to create project #{project.id}") + ``` + + ```ruby + # GOOD + logger.info(message: "Unable to create project", project_id: project.id) + ``` + +1. Be sure to create a common base structure of your log messages. For example, + all messages might have `current_user_id` and `project_id` to make it easier + to search for activities by user for a given time. + +1. Do NOT mix and match types. Elasticsearch won't be able to index your + logs properly if you [mix integer and string + types](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html#_avoiding_type_gotchas): + + ```ruby + # BAD + logger.info(message: "Import error", error: 1) + logger.info(message: "Import error", error: "I/O failure") + ``` + + ```ruby + # GOOD + logger.info(message: "Import error", error_code: 1, error: "I/O failure") + ``` + +## Additional steps with new log files + +1. Consider log retention settings. By default, Omnibus will rotate any +logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at +most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). +On GitLab.com, that setting is only 6 compressed files. These settings should suffice +for most users, but you may need to tweak them in [omnibus-gitlab](https://gitlab.com/gitlab-org/omnibus-gitlab). + +1. If you add a new file, submit an issue to the [production +tracker](https://gitlab.com/gitlab-com/gl-infra/production/issues) or +a merge request to the [gitlab_fluentd](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd) +project. See [this example](https://gitlab.com/gitlab-cookbooks/gitlab_fluentd/merge_requests/51/diffs). + +1. Be sure to update the [GitLab CE/EE documentation](../administration/logs.md) and the [GitLab.com +runbooks](https://gitlab.com/gitlab-com/runbooks/blob/master/howto/logging.md). diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 12badbe39b2..ee01c89e0ed 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -168,6 +168,7 @@ user objects for every username we can remove the need for running the same query for every mention of `@alice`. Caching data per transaction can be done using -[RequestStore](https://github.com/steveklabnik/request_store). Caching data in -Redis can be done using [Rails' caching +[RequestStore](https://github.com/steveklabnik/request_store) (use +`Gitlab::SafeRequestStore` to avoid having to remember to check +`RequestStore.active?`). Caching data in Redis can be done using [Rails' caching system](http://guides.rubyonrails.org/caching_with_rails.html). diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 6f31e5b82e5..a99267bfbba 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -134,9 +134,9 @@ should be more than enough. When removing an index make sure to use the method `remove_concurrent_index` instead of the regular `remove_index` method. The `remove_concurrent_index` method automatically drops concurrent indexes when using PostgreSQL, removing the -need for downtime. To use this method you must disable transactions by calling -the method `disable_ddl_transaction!` in the body of your migration class like -so: +need for downtime. To use this method you must disable single-transaction mode +by calling the method `disable_ddl_transaction!` in the body of your migration +class like so: ```ruby class MyMigration < ActiveRecord::Migration @@ -187,12 +187,7 @@ end When adding a foreign-key constraint to either an existing or new column remember to also add a index on the column. -This is _required_ if the foreign-key constraint specifies -`ON DELETE CASCADE` or `ON DELETE SET NULL` behavior. On a cascading -delete, the [corresponding record needs to be retrieved using an -index](https://www.cybertec-postgresql.com/en/postgresql-indexes-and-foreign-keys/) -(otherwise, we'd need to scan the whole table) for subsequent update or -deletion. +This is _required_ for all foreign-keys. Here's an example where we add a new column with a foreign key constraint. Note it includes `index: true` to create an index for it. diff --git a/doc/development/module_with_instance_variables.md b/doc/development/module_with_instance_variables.md index 48a1b7f847e..7bdfa04fc57 100644 --- a/doc/development/module_with_instance_variables.md +++ b/doc/development/module_with_instance_variables.md @@ -60,7 +60,7 @@ as long as it's contained in the same module; that is, no other modules or objects are touching them, then it would be an acceptable use. We especially allow the case where a single instance variable is used with -`||=` to setup the value. This would look like: +`||=` to set up the value. This would look like: ``` ruby module M diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 244dfb3756f..5ccd5357314 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -2,7 +2,7 @@ ## Monitoring -We have a performance dashboard available in one of our [grafana instances](https://performance.gprd.gitlab.com/dashboard/db/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://sitespeed.io) every 6 hours. These changes are displayed after a set number of pages are aggregated. +We have a performance dashboard available in one of our [grafana instances](https://dashboards.gitlab.net/d/1EBTz3Dmz/sitespeed-page-summary?orgId=1). This dashboard automatically aggregates metric data from [sitespeed.io](https://sitespeed.io) every 6 hours. These changes are displayed after a set number of pages are aggregated. These pages can be found inside a text file in the gitlab-build-images [repository](https://gitlab.com/gitlab-org/gitlab-build-images) called [gitlab.txt](https://gitlab.com/gitlab-org/gitlab-build-images/blob/master/scripts/gitlab.txt) Any frontend engineer can contribute to this dashboard. They can contribute by adding or removing urls of pages from this text file. Please have a [frontend monitoring expert](https://about.gitlab.com/team) review your changes before assigning to a maintainer of the `gitlab-build-images` project. The changes will go live on the next scheduled run after the changes are merged into `master`. diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index a9223ac6b0f..082acbedcd2 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -1,30 +1,247 @@ # Overview of Frontend Testing -## Types of tests in our codebase +Tests relevant for frontend development can be found at two places: + +- `spec/javascripts/` which are run by Karma and contain + - [frontend unit tests](#frontend-unit-tests) + - [frontend component tests](#frontend-component-tests) + - [frontend integration tests](#frontend-integration-tests) +- `spec/features/` which are run by RSpec and contain + - [feature tests](#feature-tests) + +In addition there were feature tests in `features/` run by Spinach in the past. +These have been removed from our codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-ce/issues/23036)). + +See also: -* **RSpec** - * **[Ruby unit tests](#ruby-unit-tests-spec-rb)** for models, controllers, helpers, etc. (`/spec/**/*.rb`) - * **[Full feature tests](#full-feature-tests-spec-features-rb)** (`/spec/features/**/*.rb`) -* **[Karma](#karma-tests-spec-javascripts-js)** (`/spec/javascripts/**/*.js`) -* <s>Spinach</s> — These have been removed from our codebase in May 2018. (`/features/`) +- [old testing guide](../../testing_guide/frontend_testing.html) +- [notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components) -## RSpec: Ruby unit tests `/spec/**/*.rb` +## Frontend unit tests -These tests are meant to unit test the ruby models, controllers and helpers. +Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user. -### When do we write/update these tests? +### When to use unit tests -Whenever we create or modify any Ruby models, controllers or helpers we add/update corresponding tests. +<details> + <summary>exported functions and classes</summary> + Anything that is exported can be reused at various places in a way you have no control over. + Therefore it is necessary to document the expected behavior of the public interface with tests. +</details> ---- +<details> + <summary>Vuex actions</summary> + Any Vuex action needs to work in a consistent way independent of the component it is triggered from. +</details> -## RSpec: Full feature tests `/spec/features/**/*.rb` +<details> + <summary>Vuex mutations</summary> + For complex Vuex mutations it helps to identify the source of a problem by separating the tests from other parts of the Vuex store. +</details> -Full feature tests will load a full app environment and allow us to test things like rendering DOM, interacting with links and buttons, testing the outcome of those interactions through multiple pages if necessary. These are also called end-to-end tests but should not be confused with QA end-to-end tests (`package-and-qa` manual pipeline job). +### When *not* to use unit tests -### When do we write/update these tests? +<details> + <summary>non-exported functions or classes</summary> + Anything that is not exported from a module can be considered private or an implementation detail and doesn't need to be tested. +</details> -When we add a new feature, we write at least two tests covering the success and the failure scenarios. +<details> + <summary>constants</summary> + Testing the value of a constant would mean to copy it. + This results in extra effort without additional confidence that the value is correct. +</details> + +<details> + <summary>Vue components</summary> + Computed properties, methods, and lifecycle hooks can be considered an implementation detail of components and don't need to be tested. + They are implicitly covered by component tests. + The <a href="https://vue-test-utils.vuejs.org/guides/#getting-started">official Vue guidelines</a> suggest the same. +</details> + +### What to mock in unit tests + +<details> + <summary>state of the class under test</summary> + Modifying the state of the class under test directly rather than using methods of the class avoids side-effects in test setup. +</details> + +<details> + <summary>other exported classes</summary> + Every class needs to be tested in isolation to prevent test scenarios from growing exponentially. +</details> + +<details> + <summary>single DOM elements if passed as parameters</summary> + For tests that only operate on single DOM elements rather than a whole page, creating these elements is cheaper than loading a whole HTML fixture. +</details> + +<details> + <summary>all server requests</summary> + When running frontend unit tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations</summary> + Background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +### What *not* to mock in unit tests + +<details> + <summary>non-exported functions or classes</summary> + Everything that is not exported can be considered private to the module and will be implicitly tested via the exported classes / functions. +</details> + +<details> + <summary>methods of the class under test</summary> + By mocking methods of the class under test, the mocks will be tested and not the real methods. +</details> + +<details> + <summary>utility functions (pure functions, or those that only modify parameters)</summary> + If a function has no side effects because it has no state, it is safe to not mock it in tests. +</details> + +<details> + <summary>full HTML pages</summary> + Loading the HTML of a full page slows down tests, so it should be avoided in unit tests. +</details> + +## Frontend component tests + +Component tests cover the state of a single component that is perceivable by a user depending on external signals such as user input, events fired from other components, or application state. + +### When to use component tests + +- Vue components + +### When *not* to use component tests + +<details> + <summary>Vue applications</summary> + Vue applications may contain many components. + Testing them on a component level requires too much effort. + Therefore they are tested on frontend integration level. +</details> + +<details> + <summary>HAML templates</summary> + HAML templates contain only Markup and no frontend-side logic. + Therefore they are not complete components. +</details> + +### What to mock in component tests + +<details> + <summary>DOM</summary> + Operating on the real DOM is significantly slower than on the virtual DOM. +</details> + +<details> + <summary>properties and state of the component under test</summary> + Similarly to testing classes, modifying the properties directly (rather than relying on methods of the component) avoids side-effects. +</details> + +<details> + <summary>Vuex store</summary> + To avoid side effects and keep component tests simple, Vuex stores are replaced with mocks. +</details> + +<details> + <summary>all server requests</summary> + Similar to unit tests, when running component tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations</summary> + Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +<details> + <summary>child components</summary> + Every component is tested individually, so child components are mocked. + See also <a href="https://vue-test-utils.vuejs.org/api/#shallowmount">shallowMount()</a> +</details> + +### What *not* to mock in component tests + +<details> + <summary>methods or computed properties of the component under test</summary> + By mocking part of the component under test, the mocks will be tested and not the real component. +</details> + +<details> + <summary>functions and classes independent from Vue</summary> + All plain JavaScript code is already covered by unit tests and needs not to be mocked in component tests. +</details> + +## Frontend integration tests + +Integration tests cover the interaction between all components on a single page. +Their abstraction level is comparable to how a user would interact with the UI. + +### When to use integration tests + +<details> + <summary>page bundles (<code>index.js</code> files in <code>app/assets/javascripts/pages/</code>)</summary> + Testing the page bundles ensures the corresponding frontend components integrate well. +</details> + +<details> + <summary>Vue applications outside of page bundles</summary> + Testing Vue applications as a whole ensures the corresponding frontend components integrate well. +</details> + +### What to mock in integration tests + +<details> + <summary>HAML views (use fixtures instead)</summary> + Rendering HAML views requires a Rails environment including a running database which we cannot rely on in frontend tests. +</details> + +<details> + <summary>all server requests</summary> + Similar to unit and component tests, when running component tests, the backend may not be reachable. + Therefore all outgoing requests need to be mocked. +</details> + +<details> + <summary>asynchronous background operations that are not perceivable on the page</summary> + Background operations that affect the page need to be tested on this level. + All other background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects. +</details> + +### What *not* to mock in integration tests + +<details> + <summary>DOM</summary> + Testing on the real DOM ensures our components work in the environment they are meant for. + Part of this will be delegated to <a href="https://gitlab.com/gitlab-org/quality/team-tasks/issues/45">cross-browser testing</a>. +</details> + +<details> + <summary>properties or state of components</summary> + On this level, all tests can only perform actions a user would do. + For example to change the state of a component, a click event would be fired. +</details> + +<details> + <summary>Vuex stores</summary> + When testing the frontend code of a page as a whole, the interaction between Vue components and Vuex stores is covered as well. +</details> + +## Feature tests + +In contrast to [frontend integration tests](#frontend-integration-tests), feature tests make requests against the real backend instead of using fixtures. +This also implies that database queries are executed which makes this category significantly slower. + +### When to use feature tests + +- use cases that require a backend and cannot be tested using fixtures +- behavior that is not part of a page bundle but defined globally ### Relevant notes @@ -48,33 +265,9 @@ wait_for_requests expect(page).not_to have_selector('.card') ``` ---- - -## Karma tests `/spec/javascripts/**/*.js` - -These are the more frontend-focused, at the moment. They're **faster** than `rspec` and make for very quick testing of frontend components. - -### When do we write/update these tests? - -When we add/update a method/action/mutation to Vue or Vuex, we write karma tests to ensure the logic we wrote doesn't break. We should, however, refrain from writing tests that double-test Vue's internal features. - -### Relevant notes - -Karma tests are run against a virtual DOM. +## Test helpers -To populate the DOM, we can use fixtures to fake the generation of HTML instead of having Rails do that. - -Be sure to check the [best practices for karma tests](../../testing_guide/frontend_testing.html#best-practices). - -### Vue and Vuex - -Test as much as possible without double-testing Vue's internal features, as mentioned above. - -Make sure to test computedProperties, mutations, actions. Run the action and test that the proper mutations are committed. - -Also check these [notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components). - -#### Vuex Helper: `testAction` +### Vuex Helper: `testAction` We have a helper available to make testing actions easier, as per [official documentation](https://vuex.vuejs.org/en/testing.html): @@ -97,7 +290,7 @@ testAction( Check an example in [spec/javascripts/ide/stores/actions_spec.jsspec/javascripts/ide/stores/actions_spec.js](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/javascripts/ide/stores/actions_spec.js). -#### Vue Helper: `mountComponent` +### Vue Helper: `mountComponent` To make mounting a Vue component easier and more readable, we have a few helpers available in `spec/helpers/vue_mount_component_helper`. @@ -133,6 +326,7 @@ afterEach(() => { vm.$destroy(); }); ``` + ## Testing with older browsers Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps: @@ -140,20 +334,21 @@ Some regressions only affect a specific browser version. We can install and test ### Browserstack -[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. +[Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. You can use it directly through the [live app](https://www.browserstack.com/live) or you can install the [chrome extension](https://chrome.google.com/webstore/detail/browserstack/nkihdmlheodkdfojglpcjjmioefjahjb) for easy access. You can find the credentials on 1Password, under `frontendteam@gitlab.com`. ### Firefox #### macOS + You can download any older version of Firefox from the releases FTP server, https://ftp.mozilla.org/pub/firefox/releases/ 1. From the website, select a version, in this case `50.0.1`. -2. Go to the mac folder. -3. Select your preferred language, you will find the dmg package inside, download it. -4. Drag and drop the application to any other folder but the `Applications` folder. -5. Rename the application to something like `Firefox_Old`. -6. Move the application to the `Applications` folder. -7. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version. -8. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version. +1. Go to the mac folder. +1. Select your preferred language, you will find the dmg package inside, download it. +1. Drag and drop the application to any other folder but the `Applications` folder. +1. Rename the application to something like `Firefox_Old`. +1. Move the application to the `Applications` folder. +1. Open up a terminal and run `/Applications/Firefox_Old.app/Contents/MacOS/firefox-bin -profilemanager` to create a new profile specific to that Firefox version. +1. Once the profile has been created, quit the app, and run it again like normal. You now have a working older Firefox version. diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 78931defa24..bfcca9cec7b 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -19,6 +19,10 @@ Guidance on topics related to development. Learn about all the dependencies that make up our frontend, including some of our own custom built libraries. +## [Modules](modules/index.md) + +Learn about all the internal JavaScript modules that make up our frontend. + ## [Style guides](style/index.md) Style guides to keep our code consistent. diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md new file mode 100644 index 00000000000..6c03958b463 --- /dev/null +++ b/doc/development/new_fe_guide/modules/dirty_submit.md @@ -0,0 +1,23 @@ +# Dirty Submit + +> [Introduced][ce-21115] in GitLab 11.3. +> [dirty_submit][dirty-submit] + +## Summary + +Prevent submitting forms with no changes. + +Currently handles `input`, `textarea` and `select` elements. + +## Usage + +```js +import dirtySubmitFactory from './dirty_submit/dirty_submit_form'; + +new DirtySubmitForm(document.querySelector('form')); +// or +new DirtySubmitForm(document.querySelectorAll('form')); +``` + +[ce-21115]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115 +[dirty-submit]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/
\ No newline at end of file diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md new file mode 100644 index 00000000000..0a7f2dbd819 --- /dev/null +++ b/doc/development/new_fe_guide/modules/index.md @@ -0,0 +1,5 @@ +# Modules + +* [DirtySubmit](dirty_submit.md) + + Disable form submits until there are unsaved changes.
\ No newline at end of file diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md index 6395af6f815..baaea67d38b 100644 --- a/doc/development/new_fe_guide/style/prettier.md +++ b/doc/development/new_fe_guide/style/prettier.md @@ -47,13 +47,13 @@ The source of these Yarn scripts can be found in `/scripts/frontend/prettier.js` ### Scripts during Conversion period ``` -node ./scripts/frontend/prettier.js check ./vendor/ +node ./scripts/frontend/prettier.js check-all ./vendor/ ``` This will go over all files in a specific folder check it. ``` -node ./scripts/frontend/prettier.js save ./vendor/ +node ./scripts/frontend/prettier.js save-all ./vendor/ ``` This will go over all files in a specific folder and save it. diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index 5d00e1f7a0c..e9c6481635b 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -1,32 +1,49 @@ -# Ordering Table Columns +# Ordering Table Columns in PostgreSQL Similar to C structures the space of a table is influenced by the order of columns. This is because the size of columns is aligned depending on the type of -the column. Take the following column order for example: +the following column. Let's consider an example: -* id (integer, 4 bytes) -* name (text, variable) -* user_id (integer, 4 bytes) +- `id` (integer, 4 bytes) +- `name` (text, variable) +- `user_id` (integer, 4 bytes) -Integers are aligned to the word size. This means that on a 64 bit platform the -actual size of each column would be: 8 bytes, variable, 8 bytes. This means that -each row will require at least 16 bytes for the two integers, and a variable -amount for the text field. If a table has a few rows this is not an issue, but -once you start storing millions of rows you can save space by using a different -order. For the above example a more ideal column order would be the following: +The first column is a 4-byte integer. The next is text of variable length. The +`text` data type requires 1-word alignment, and on 64-bit platform, 1 word is 8 +bytes. To meet the alignment requirements, four zeros are to be added right +after the first column, so `id` occupies 4 bytes, then 4 bytes of alignment +padding, and only next `name` is being stored. Therefore, in this case, 8 bytes +will be spent for storing a 4-byte integer. -* id (integer, 4 bytes) -* user_id (integer, 4 bytes) -* name (text, variable) +The space between rows is also subject to alignment padding. The `user_id` +column takes only 4 bytes, and on 64-bit platform, 4 zeroes will be added for +alignment padding, to allow storing the next row beginning with the "clear" word. -In this setup the `id` and `user_id` columns can be packed together, which means -we only need 8 bytes to store _both_ of them. This in turn each row will require -8 bytes less of space. +As a result, the actual size of each column would be (ommiting variable length +data and 24-byte tuple header): 8 bytes, variable, 8 bytes. This means that +each row will require at least 16 bytes for the two 4-byte integers. If a table +has a few rows this is not an issue. However, once you start storing millions of +rows you can save space by using a different order. For the above example, the +ideal column order would be the following: + +- `id` (integer, 4 bytes) +- `user_id` (integer, 4 bytes) +- `name` (text, variable) + +or + +- `name` (text, variable) +- `id` (integer, 4 bytes) +- `user_id` (integer, 4 bytes) + +In these examples, the `id` and `user_id` columns are packed together, which +means we only need 8 bytes to store _both_ of them. This in turn means each row +will require 8 bytes less space. For GitLab we require that columns of new tables are ordered based to use the least amount of space. An easy way of doing this is to order them based on the -type size in descending order with variable sizes (string and text columns for -example) at the end. +type size in descending order with variable sizes (`text`, `varchar`, arrays, +`json`, `jsonb`, and so on) at the end. ## Type Sizes @@ -36,7 +53,7 @@ of information we will list the sizes of common types here so it's easier to look them up. Here "word" refers to the word size, which is 4 bytes for a 32 bits platform and 8 bytes for a 64 bits platform. -| Type | Size | Aligned To | +| Type | Size | Alignment needed | |:-----------------|:-------------------------------------|:-----------| | smallint | 2 bytes | 1 word | | integer | 4 bytes | 1 word | @@ -58,7 +75,7 @@ always be at the end of a table. ## Real Example -Let's use the "events" table as an example, which currently has the following +Let's use the `events` table as an example, which currently has the following layout: | Column | Type | Size | @@ -89,8 +106,8 @@ divided into fixed size chunks as follows: | 8 bytes | updated_at | | 8 bytes | action, author_id | -This means that excluding the variable sized data we need at least 48 bytes per -row. +This means that excluding the variable sized data and tuple header, we need at +least 8 * 6 = 48 bytes per row. We can optimise this by using the following column order instead: @@ -120,8 +137,8 @@ This would produce the following chunks: | variable | title | | variable | data | -Here we only need 40 bytes per row excluding the variable sized data. 8 bytes -being saved may not sound like much, but for tables as large as the "events" -table it does begin to matter. For example, when storing 80 000 000 rows this -translates to a space saving of at least 610 MB: all by just changing the order -of a few columns. +Here we only need 40 bytes per row excluding the variable sized data and 24-byte +tuple header. 8 bytes being saved may not sound like much, but for tables as +large as the `events` table it does begin to matter. For example, when storing +80 000 000 rows this translates to a space saving of at least 610 MB, all by +just changing the order of a few columns. diff --git a/doc/development/performance.md b/doc/development/performance.md index 05caffb150a..4cc2fdc9a58 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -9,17 +9,17 @@ The process of solving performance problems is roughly as follows: 1. Make sure there's an issue open somewhere (e.g., on the GitLab CE issue tracker), create one if there isn't. See [#15607][#15607] for an example. -2. Measure the performance of the code in a production environment such as +1. Measure the performance of the code in a production environment such as GitLab.com (see the [Tooling](#tooling) section below). Performance should be measured over a period of _at least_ 24 hours. -3. Add your findings based on the measurement period (screenshots of graphs, +1. Add your findings based on the measurement period (screenshots of graphs, timings, etc) to the issue mentioned in step 1. -4. Solve the problem. -5. Create a merge request, assign the "Performance" label and assign it to +1. Solve the problem. +1. Create a merge request, assign the "Performance" label and assign it to [@yorickpeterse][yorickpeterse] for reviewing. -6. Once a change has been deployed make sure to _again_ measure for at least 24 +1. Once a change has been deployed make sure to _again_ measure for at least 24 hours to see if your changes have any impact on the production environment. -7. Repeat until you're done. +1. Repeat until you're done. When providing timings make sure to provide: @@ -34,13 +34,14 @@ graphs/dashboards. ## Tooling -GitLab provides built-in tools to aid the process of improving performance: +GitLab provides built-in tools to help improve performance and availability: * [Profiling](profiling.md) * [Sherlock](profiling.md#sherlock) * [GitLab Performance Monitoring](../administration/monitoring/performance/index.md) * [Request Profiling](../administration/monitoring/performance/request_profiling.md) * [QueryRecoder](query_recorder.md) for preventing `N+1` regressions +* [Chaos endpoints](chaos_endpoints.md) for testing failure scenarios. Intended mainly for testing availability. GitLab employees can use GitLab.com's performance monitoring systems located at <https://dashboards.gitlab.net>, this requires you to log in using your @@ -93,14 +94,14 @@ result of this should be used instead of the `Benchmark` module. In short: -1. Don't trust benchmarks you find on the internet. -2. Never make claims based on just benchmarks, always measure in production to +- Don't trust benchmarks you find on the internet. +- Never make claims based on just benchmarks, always measure in production to confirm your findings. -3. X being N times faster than Y is meaningless if you don't know what impact it +- X being N times faster than Y is meaningless if you don't know what impact it will actually have on your production environment. -4. A production environment is the _only_ benchmark that always tells the truth +- A production environment is the _only_ benchmark that always tells the truth (unless your performance monitoring systems are not set up correctly). -5. If you must write a benchmark use the benchmark-ips Gem instead of Ruby's +- If you must write a benchmark use the benchmark-ips Gem instead of Ruby's `Benchmark` module. ## Profiling @@ -364,8 +365,7 @@ Depending on the size of the String and how frequently it would be allocated there's no guarantee it will. Strings will be frozen by default in Ruby 3.0. To prepare our code base for -this eventuality, it's a good practice to add the following header to all -Ruby files: +this eventuality, we will be adding the following header to all Ruby files: ```ruby # frozen_string_literal: true @@ -379,6 +379,9 @@ test = +"hello" test += " world" ``` +When adding new Ruby files, please check that you can add the above header, +as omitting it may lead to style check failures. + ## Anti-Patterns This is a collection of [anti-patterns][anti-pattern] that should be avoided diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md index cfc91539bee..5986efa9974 100644 --- a/doc/development/post_deployment_migrations.md +++ b/doc/development/post_deployment_migrations.md @@ -57,13 +57,13 @@ depends on this column being present while it's running. Normally you'd follow these steps in such a case: 1. Stop the GitLab instance -2. Run the migration removing the column -3. Start the GitLab instance again +1. Run the migration removing the column +1. Start the GitLab instance again Using post deployment migrations we can instead follow these steps: 1. Deploy a new version of GitLab while ignoring post deployment migrations -2. Re-run `rake db:migrate` but without the environment variable set +1. Re-run `rake db:migrate` but without the environment variable set Here we don't need any downtime as the migration takes place _after_ a new version (which doesn't depend on the column anymore) has been deployed. diff --git a/doc/development/query_count_limits.md b/doc/development/query_count_limits.md index 310e3faf61b..b3ecaf30d8a 100644 --- a/doc/development/query_count_limits.md +++ b/doc/development/query_count_limits.md @@ -8,8 +8,8 @@ in test environments we'll raise an error when this threshold is exceeded. When a test fails because it executes more than 100 SQL queries there are two solutions to this problem: -1. Reduce the number of SQL queries that are executed. -2. Whitelist the controller or API endpoint. +- Reduce the number of SQL queries that are executed. +- Whitelist the controller or API endpoint. You should only resort to whitelisting when an existing controller or endpoint is to blame as in this case reducing the number of SQL queries can take a lot of diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index fc51b74da1d..2ad748d4802 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -1,6 +1,6 @@ # Rake tasks for developers -## Setup db with developer seeds +## Set up db with developer seeds Note that if your db user does not have advanced privileges you must create the db manually before running this command. diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index 905aa26a40b..b65fbc9d958 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -151,3 +151,40 @@ most cases this will translate to a feature (with a feature flag) being shipped in RC1, followed by the feature flag being removed in RC2. This in turn means the feature will be stable by the time we publish a stable package around the 22nd of the month. + +## Implicit feature flags + +The [`Project#feature_available?`][project-fa], +[`Namespace#feature_available?`][namespace-fa] (EE), and +[`License.feature_available?`][license-fa] (EE) methods all implicitly check for +a feature flag by the same name as the provided argument. + +For example if a feature is license-gated, there's no need to add an additional +explicit feature flag check since the flag will be checked as part of the +`License.feature_available?` call. Similarly, there's no need to "clean up" a +feature flag once the feature has reached general availability. + +You'd still want to use an explicit `Feature.enabled?` check if your new feature +isn't gated by a License or Plan. + +[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 +[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 +[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 + +### Undefined feature flags default to "on" + +An important side-effect of the [implicit feature +flags][#implicit-feature-flags] mentioned above is that unless the feature is +explicitly disabled or limited to a percentage of users, the feature flag check +will default to `true`. + +As an example, if you were to ship the backend half of a feature behind a flag, +you'd want to explicitly disable that flag until the frontend half is also ready +to be shipped. You can do this via ChatOps: + +``` +/chatops run feature set some_feature 0 +``` + +Note that you can do this at any time, even before the merge request using the +flag has been merged! diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 76ff51446ba..8e268224c98 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -17,8 +17,8 @@ would be `process_something`. If you're not sure what queue a worker uses, you can find it using `SomeWorker.queue`. There is almost never a reason to manually override the queue name using `sidekiq_options queue: :some_queue`. -You must always add any new queues to `app/workers/all_queues.yml` otherwise -your worker will not run. +You must always add any new queues to `app/workers/all_queues.yml` or `ee/app/workers/all_queues.yml` +otherwise your worker will not run. ## Queue Namespaces diff --git a/doc/development/swapping_tables.md b/doc/development/swapping_tables.md index 6b990ece72c..29cd6a43aff 100644 --- a/doc/development/swapping_tables.md +++ b/doc/development/swapping_tables.md @@ -8,8 +8,8 @@ Let's say you want to swap the table "events" with "events_for_migration". In this case you need to follow 3 steps: 1. Rename "events" to "events_temporary" -2. Rename "events_for_migration" to "events" -3. Rename "events_temporary" to "events_for_migration" +1. Rename "events_for_migration" to "events" +1. Rename "events_temporary" to "events_for_migration" Rails allows you to do this using the `rename_table` method: diff --git a/doc/development/switching_to_rails5.md b/doc/development/switching_to_rails5.md new file mode 100644 index 00000000000..c9a4ce1a1d1 --- /dev/null +++ b/doc/development/switching_to_rails5.md @@ -0,0 +1,27 @@ +# Switching to Rails 5 + +GitLab switched recently to Rails 5. This is a big change (especially for backend development) and it introduces couple of temporary inconveniences. + +## After the switch, I found a broken feature. What do I do? + +Many fixes and tweaks were done to make our codebase compatible with Rails 5, but it's possible that not all issues were found. If you find an bug, please create an issue and assign it the ~rails5 label. + +## It takes much longer to run CI pipelines that build GitLab. Why? + +We are temporarily running CI pipelines with Rails 4 and 5 so that we ensure we remain compatible with Rails 4 in case we must revert back to Rails 4 from Rails 5 (this can double the duration of CI pipelines). + +We might revert back to Rails 4 if we found a major issue we were unable to quickly fix. + +Once we are sure we can stay with Rails 5, we will stop running CI pipelines with Rails 4. + +## Can I skip running Rails 4 tests? + +If you are sure that your merge request doesn't introduce any incompatibility, you can just include `norails4` anywhere in your branch name and Rails 4 tests will be skipped. + +## CI is failing on my test with Rails 4. How can I debug it? + +You can run specs locally with Rails 4 using the following command: + +```sh +BUNDLE_GEMFILE=Gemfile.rails4 RAILS5=0 bundle exec rspec ... +``` diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index acbfa1850b4..72abda26e3d 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -209,6 +209,130 @@ it 'is overdue' do end ``` +### Pristine test environments + +The code exercised by a single GitLab test may access and modify many items of +data. Without careful preparation before a test runs, and cleanup afterward, +data can be changed by a test in such a way that it affects the behaviour of +following tests. This should be avoided at all costs! Fortunately, the existing +test framework handles most cases already. + +When the test environment does get polluted, a common outcome is +[flaky tests](flaky_tests.md). Pollution will often manifest as an order +dependency: running spec A followed by spec B will reliably fail, but running +spec B followed by spec A will reliably succeed. In these cases, you can use +`rspec --bisect` (or a manual pairwise bisect of spec files) to determine which +spec is at fault. Fixing the problem requires some understanding of how the test +suite ensures the environment is pristine. Read on to discover more about each +data store! + +#### SQL database + +This is managed for us by the `database_cleaner` gem. Each spec is surrounded in +a transaction, which is rolled back once the test completes. Certain specs will +instead issue `DELETE FROM` queries against every table after completion; this +allows the created rows to be viewed from multiple database connections, which +is important for specs that run in a browser, or migration specs, among others. + +One consequence of using these strategies, instead of the well-known +`TRUNCATE TABLES` approach, is that primary keys and other sequences are **not** +reset across specs. So if you create a project in spec A, then create a project +in spec B, the first will have `id=1`, while the second will have `id=2`. + +This means that specs should **never** rely on the value of an ID, or any other +sequence-generated column. To avoid accidental conflicts, specs should also +avoid manually specifying any values in these kinds of columns. Instead, leave +them unspecified, and look up the value after the row is created. + +#### Redis + +GitLab stores two main categories of data in Redis: cached items, and sidekiq +jobs. + +In most specs, the Rails cache is actually an in-memory store. This is replaced +between specs, so calls to `Rails.cache.read` and `Rails.cache.write` are safe. +However, if a spec makes direct Redis calls, it should mark itself with the +`:clean_gitlab_redis_cache`, `:clean_gitlab_redis_shared_state` or +`:clean_gitlab_redis_queues` traits as appropriate. + +Sidekiq jobs are typically not run in specs, but this behaviour can be altered +in each spec through the use of `Sidekiq::Testing.inline!` blocks. Any spec that +causes Sidekiq jobs to be pushed to Redis should use the `:sidekiq` trait, to +ensure that they are removed once the spec completes. + +#### Filesystem + +Filesystem data can be roughly split into "repositories", and "everything else". +Repositories are stored in `tmp/tests/repositories`. This directory is emptied +before a test run starts, and after the test run ends. It is not emptied between +specs, so created repositories accumulate within this directory over the +lifetime of the process. Deleting them is expensive, but this could lead to +pollution unless carefully managed. + +To avoid this, [hashed storage](../../administration/repository_storage_types.md) +is enabled in the test suite. This means that repositories are given a unique +path that depends on their project's ID. Since the project IDs are not reset +between specs, this guarantees that each spec gets its own repository on disk, +and prevents changes from being visible between specs. + +If a spec manually specifies a project ID, or inspects the state of the +`tmp/tests/repositories/` directory directly, then it should clean up the +directory both before and after it runs. In general, these patterns should be +completely avoided. + +Other classes of file linked to database objects, such as uploads, are generally +managed in the same way. With hashed storage enabled in the specs, they are +written to disk in locations determined by ID, so conflicts should not occur. + +Some specs disable hashed storage by passing the `:legacy_storage` trait to the +`projects` factory. Specs that do this must **never** override the `path` of the +project, or any of its groups. The default path includes the project ID, so will +not conflict; but if two specs create a `:legacy_storage` project with the same +path, they will use the same repository on disk and lead to test environment +pollution. + +Other files must be managed manually by the spec. If you run code that creates a +`tmp/test-file.csv` file, for instance, the spec must ensure that the file is +removed as part of cleanup. + +#### Persistent in-memory application state + +All the specs in a given `rspec` run share the same Ruby process, which means +they can affect each other by modifying Ruby objects that are accessible between +specs. In practice, this means global variables, and constants (which includes +Ruby classes, modules, etc). + +Global variables should generally not be modified. If absolutely necessary, a +block like this can be used to ensure the change is rolled back afterwards: + +```ruby +around(:each) do |example| + old_value = $0 + + begin + $0 = "new-value" + example.run + ensure + $0 = old_value + end +end +``` + +If a spec needs to modify a constant, it should use the `stub_const` helper to +ensure the change is rolled back. + +If you need to modify the contents of the `ENV` constant, you can use the +`stub_env` helper method instead. + +While most Ruby **instances** are not shared between specs, **classes** +and **modules** generally are. Class and module instance variables, accessors, +class variables, and other stateful idioms, should be treated in the same way as +global variables - don't modify them unless you have to! In particular, prefer +using expectations, or dependency injection along with stubs, to avoid the need +for modifications. If you have no other choice, an `around` block similar to the +example for global variables, above, can be used, but this should be avoided if +at all possible. + ### Table-based / Parameterized tests This style of testing is used to exercise one piece of code with a comprehensive @@ -270,7 +394,7 @@ This is especially useful whenever it's showing 500 internal server error. ### Shared contexts -All shared contexts should be be placed under `spec/support/shared_contexts/`. +All shared contexts should be placed under `spec/support/shared_contexts/`. Shared contexts can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. @@ -280,7 +404,7 @@ Each file should include only one context and have a descriptive name, e.g. ### Shared examples -All shared examples should be be placed under `spec/support/shared_examples/`. +All shared examples should be placed under `spec/support/shared_examples/`. Shared examples can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. @@ -292,7 +416,7 @@ Each file should include only one context and have a descriptive name, e.g. Helpers are usually modules that provide some methods to hide the complexity of specific RSpec examples. You can define helpers in RSpec files if they're not -intended to be shared with other specs. Otherwise, they should be be placed +intended to be shared with other specs. Otherwise, they should be placed under `spec/support/helpers/`. Helpers can be placed in subfolder if they apply to a certain type of specs only (e.g. features, requests etc.) but shouldn't be if they apply to multiple type of specs. @@ -346,7 +470,38 @@ GitLab uses [factory_bot] as a test fixture replacement. ### Fixtures -All fixtures should be be placed under `spec/fixtures/`. +All fixtures should be placed under `spec/fixtures/`. + +### Repositories + +Testing some functionality, e.g., merging a merge request, requires a git +repository with a certain state to be present in the test environment. GitLab +maintains the [gitlab-test](https://gitlab.com/gitlab-org/gitlab-test) +repository for certain common cases - you can ensure a copy of the repository is +used with the `:repository` trait for project factories: + +```ruby +let(:project) { create(:project, :repository) } +``` + +Where you can, consider using the `:custom_repo` trait instead of `:repository`. +This allows you to specify exactly what files will appear in the `master` branch +of the project's repository. For example: + +```ruby +let(:project) do + create( + :project, :custom_repo, + files: { + 'README.md' => 'Content here', + 'foo/bar/baz.txt' => 'More content here' + } + ) +end +``` + +This will create a repository containing two files, with default permissions and +the specified content. ### Config diff --git a/doc/development/testing_guide/end_to_end_tests.md b/doc/development/testing_guide/end_to_end_tests.md index 21ec926414d..e9f236c6b3a 100644 --- a/doc/development/testing_guide/end_to_end_tests.md +++ b/doc/development/testing_guide/end_to_end_tests.md @@ -1,32 +1,37 @@ -# End-to-End Testing +# End-to-end Testing -## What is End-to-End testing? +## What is end-to-end testing? -End-to-End testing is a strategy used to check whether your application works -as expected across entire software stack and architecture, including -integration of all microservices and components that are supposed to work +End-to-end testing is a strategy used to check whether your application works +as expected across the entire software stack and architecture, including +integration of all micro-services and components that are supposed to work together. ## How do we test GitLab? We use [Omnibus GitLab][omnibus-gitlab] to build GitLab packages and then we -test these packages using [GitLab QA][gitlab-qa] project, which is entirely -black-box, click-driven testing framework. +test these packages using the [GitLab QA orchestrator][gitlab-qa] tool, which is +a black-box testing framework for the API and the UI. ### Testing nightly builds We run scheduled pipeline each night to test nightly builds created by Omnibus. -You can find these nightly pipelines at [GitLab QA pipelines page][gitlab-qa-pipelines]. +You can find these nightly pipelines at [gitlab-org/quality/nightly/pipelines][quality-nightly-pipelines]. + +### Testing staging + +We run scheduled pipeline each night to test staging. +You can find these nightly pipelines at [gitlab-org/quality/staging/pipelines][quality-staging-pipelines]. ### Testing code in merge requests It is possible to run end-to-end tests (eventually being run within a [GitLab QA pipeline][gitlab-qa-pipelines]) for a merge request by triggering -the `package-and-qa` manual action, that should be present in a merge request -widget. +the `package-and-qa` manual action in the `test` stage, that should be present +in a merge request widget (unless the merge request is from a fork). Manual action that starts end-to-end tests is also available in merge requests -in Omnibus GitLab project. +in [Omnibus GitLab][omnibus-gitlab]. Below you can read more about how to use it and how does it work. @@ -35,46 +40,56 @@ Below you can read more about how to use it and how does it work. Currently, we are using _multi-project pipeline_-like approach to run QA pipelines. -1. Developer triggers a manual action, that can be found in CE and EE merge +1. Developer triggers a manual action, that can be found in CE / EE merge requests. This starts a chain of pipelines in multiple projects. -1. The script being executed triggers a pipeline in GitLab Omnibus and waits -for the resulting status. We call this a _status attribution_. +1. The script being executed triggers a pipeline in [Omnibus GitLab][omnibus-gitlab] +and waits for the resulting status. We call this a _status attribution_. -1. GitLab packages are being built in Omnibus pipeline. Packages are going to be -pushed to Container Registry. +1. GitLab packages are being built in the [Omnibus GitLab][omnibus-gitlab] +pipeline. Packages are then pushed to its Container Registry. 1. When packages are ready, and available in the registry, a final step in the -pipeline, that is now running in Omnibus, triggers a new pipeline in the GitLab -QA project. It also waits for a resulting status. +[Omnibus GitLab][omnibus-gitlab] pipeline, triggers a new +[GitLab QA pipeline][gitlab-qa-pipelines]. It also waits for a resulting status. 1. GitLab QA pulls images from the registry, spins-up containers and runs tests against a test environment that has been just orchestrated by the `gitlab-qa` tool. -1. The result of the GitLab QA pipeline is being propagated upstream, through -Omnibus, back to CE / EE merge request. +1. The result of the [GitLab QA pipeline][gitlab-qa-pipelines] is being +propagated upstream, through Omnibus, back to the CE / EE merge request. #### How do I write tests? In order to write new tests, you first need to learn more about GitLab QA -architecture. See the [documentation about it][gitlab-qa-architecture] in -GitLab QA project. +architecture. See the [documentation about it][gitlab-qa-architecture]. -Once you decided where to put test environment orchestration scenarios and -instance specs, take a look at the [relevant documentation][instance-qa-readme] -and examples in [the `qa/` directory][instance-qa-examples]. +Once you decided where to put [test environment orchestration scenarios] and +[instance-level scenarios], take a look at the [GitLab QA README][instance-qa-readme], +the [GitLab QA orchestrator README][gitlab-qa-readme], and [the already existing +instance-level scenarios][instance-level scenarios]. ## Where can I ask for help? You can ask question in the `#quality` channel on Slack (GitLab internal) or you can find an issue you would like to work on in -[the issue tracker][gitlab-qa-issues] and start a new discussion there. +[the `gitlab-ce` issue tracker][gitlab-ce-issues], +[the `gitlab-ee` issue tracker][gitlab-ce-issues], or +[the `gitlab-qa` issue tracker][gitlab-qa-issues]. [omnibus-gitlab]: https://gitlab.com/gitlab-org/omnibus-gitlab [gitlab-qa]: https://gitlab.com/gitlab-org/gitlab-qa +[gitlab-qa-readme]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md [gitlab-qa-pipelines]: https://gitlab.com/gitlab-org/gitlab-qa/pipelines +[quality-nightly-pipelines]: https://gitlab.com/gitlab-org/quality/nightly/pipelines +[quality-staging-pipelines]: https://gitlab.com/gitlab-org/quality/staging/pipelines [gitlab-qa-architecture]: https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/architecture.md -[gitlab-qa-issues]: https://gitlab.com/gitlab-org/gitlab-qa/issues +[gitlab-qa-issues]: https://gitlab.com/gitlab-org/gitlab-qa/issues?label_name%5B%5D=new+scenario +[gitlab-ce-issues]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name[]=QA&label_name[]=test +[gitlab-ee-issues]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name[]=QA&label_name[]=test +[test environment orchestration scenarios]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/lib/gitlab/qa/scenario +[instance-level scenarios]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/specs/features +[Page objects documentation]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/page/README.md [instance-qa-readme]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/README.md [instance-qa-examples]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 38ea2f1dde1..a6ed9e85a41 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -1,81 +1,104 @@ -# Review apps +# Review Apps -We currently have review apps available as a manual job in EE pipelines. Here is -[the first implementation](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6259). - -That said, [the Quality team is working](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665) -on making Review Apps automatically deployed by each pipeline, both in CE and EE. +Review Apps are automatically deployed by each pipeline, both in +[CE](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22010) and +[EE](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665). ## How does it work? -1. On every EE [pipeline][gitlab-pipeline] during the `test` stage, you can - start the [`review` job][review-job] -1. The `review` job [triggers a pipeline][cng-pipeline] in the - [`CNG-mirror`][cng-mirror] [^1] project -1. The `CNG-mirror` pipeline creates the Docker images of each component (e.g. `gitlab-rails-ee`, - `gitlab-shell`, `gitaly` etc.) based on the commit from the - [GitLab pipeline][gitlab-pipeline] and store them in its - [registry][cng-mirror-registry] -1. Once all images are built, the review app is deployed using - [the official GitLab Helm chart][helm-chart] [^2] to the - [`review-apps-ee` Kubernetes cluster on GCP][review-apps-ee] - - The actual scripts used to deploy the review app can be found at - [`scripts/review_apps/review-apps.sh`][review-apps.sh] - - These scripts are basically - [our official Auto DevOps scripts][Auto-DevOps.gitlab-ci.yml] where the - default CNG images are overriden with the images built and stored in the - [`CNG-mirror` project's registry][cng-mirror-registry] -1. Once the `review` job succeeds, you should be able to use your review app - thanks to the direct link to it from the MR widget. The default username is - `root` and its password can be found in the 1Password secure note named - **gitlab-{ce,ee} review app's root password**. +1. On every [pipeline][gitlab-pipeline] during the `test` stage, the + [`review-deploy`][review-deploy-job] job is automatically started. +1. The `review-deploy` job: + 1. Waits for the `gitlab:assets:compile` job to finish since the + [`CNG-mirror`][cng-mirror] pipeline triggerred in the following step + depends on it. + 1. [Triggers a pipeline][cng-pipeline] in the [`CNG-mirror`][cng-mirror] + project. + - We use the `CNG-mirror` project so that the `CNG`, (**C**loud + **N**ative **G**itLab), project's registry is not overloaded with a + lot of transient Docker images. + - The `CNG-mirror` pipeline creates the Docker images of each component + (e.g. `gitlab-rails-ee`, `gitlab-shell`, `gitaly` etc.) based on the + commit from the [GitLab pipeline][gitlab-pipeline] and store them in + its [registry][cng-mirror-registry]. + 1. Once all images are built by [`CNG-mirror`][cng-mirror], the Review App + is deployed using [the official GitLab Helm chart][helm-chart] to the + [`review-apps-ce`][review-apps-ce] / [`review-apps-ee`][review-apps-ee] + Kubernetes cluster on GCP. + - The actual scripts used to deploy the Review App can be found at + [`scripts/review_apps/review-apps.sh`][review-apps.sh]. + - These scripts are basically + [our official Auto DevOps scripts][Auto-DevOps.gitlab-ci.yml] where the + default CNG images are overridden with the images built and stored in the + [`CNG-mirror` project's registry][cng-mirror-registry]. + - Since we're using [the official GitLab Helm chart][helm-chart], this means + you get a dedicated environment for your branch that's very close to what + it would look in production. +1. Once the `review-deploy` job succeeds, you should be able to use your Review + App thanks to the direct link to it from the MR widget. The default username + is `root` and its password can be found in the 1Password secure note named + **gitlab-{ce,ee} Review App's root password** (note that there's currently + [a bug where the default password seems to be overridden][password-bug]). **Additional notes:** -- The Kubernetes cluster is connected to the `gitlab-ee` project using [GitLab's - Kubernetes integration][gitlab-k8s-integration]. This basically allows to have - a link to the review app directly from the merge request widget. -- The manual `stop_review` in the `post-cleanup` stage can be used to stop a - review app manually, and is also started by GitLab once a branch is deleted -- [TBD] Review apps are cleaned up regularly using a pipeline schedule that runs - the [`scripts/review_apps/automated_cleanup.rb`][automated_cleanup.rb] script +- The Kubernetes cluster is connected to the `gitlab-{ce,ee}` projects using + [GitLab's Kubernetes integration][gitlab-k8s-integration]. This basically + allows to have a link to the Review App directly from the merge request + widget. +- If the Review App deployment fails, you can simply retry it (there's no need + to run the [`review-stop`][gitlab-ci-yml] job first). +- The manual [`review-stop`][gitlab-ci-yml] in the `test` stage can be used to + stop a Review App manually, and is also started by GitLab once a branch is + deleted. +- Review Apps are cleaned up regularly using a pipeline schedule that runs + the [`schedule:review-cleanup`][gitlab-ci-yml] job. + +## QA runs + +On every [pipeline][gitlab-pipeline] during the `test` stage, the +`review-qa-smoke` job is automatically started: it runs the smoke QA suite. +You can also manually start the `review-qa-all`: it runs the full QA suite. -[^1]: We use the `CNG-mirror` project so that the `CNG`, (**C**loud **N**ative **G**itLab), project's registry is - not overloaded with a lot of transient Docker images. -[^2]: Since we're using [the official GitLab Helm chart][helm-chart], this means - you get the a dedicated environment for your branch that's very close to what it - would look in production +Note that both jobs first wait for the `review-deploy` job to be finished. ## Frequently Asked Questions -**Will it be too much to trigger CNG image builds on every test run? This could create thousands of unused docker images.** +**Isn't it too much to trigger CNG image builds on every test run? This creates +thousands of unused Docker images.** - > We have to start somewhere and improve later. If we see this getting out of hand, we will revisit. + > We have to start somewhere and improve later. Also, we're using the + CNG-mirror project to store these Docker images so that we can just wipe out + the registry at some point, and use a new fresh, empty one. -**How big is the Kubernetes cluster?** +**How big are the Kubernetes clusters (`review-apps-ce` and `review-apps-ee`)?** - > The cluster is currently setup with a single pool of preemptible - nodes, with a minimum of 1 node and a maximum of 30 nodes. + > The clusters are currently set up with a single pool of preemptible nodes, + with a minimum of 1 node and a maximum of 100 nodes. **What are the machine running on the cluster?** > We're currently using `n1-standard-4` (4 vCPUs, 15 GB memory) machines. -**How do we secure this from abuse? Apps are open to the world so we need to find a way to limit it to only us.** +**How do we secure this from abuse? Apps are open to the world so we need to +find a way to limit it to only us.** - > This won't work for forks. We will add a root password to 1password shared vault. + > This isn't enabled for forks. -[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ee/pipelines/29302122 -[review-job]: https://gitlab.com/gitlab-org/gitlab-ee/-/jobs/94294136 +[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ce/pipelines/35850709 +[review-deploy-job]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/118076368 [cng-mirror]: https://gitlab.com/gitlab-org/build/CNG-mirror -[cng-pipeline]: https://gitlab.com/gitlab-org/build/CNG-mirror/pipelines/29307727 +[cng-pipeline]: https://gitlab.com/gitlab-org/build/CNG-mirror/pipelines/35883435 [cng-mirror-registry]: https://gitlab.com/gitlab-org/build/CNG-mirror/container_registry [helm-chart]: https://gitlab.com/charts/gitlab/ +[review-apps-ce]: https://console.cloud.google.com/kubernetes/clusters/details/us-central1-a/review-apps-ce?project=gitlab-review-apps [review-apps-ee]: https://console.cloud.google.com/kubernetes/clusters/details/us-central1-b/review-apps-ee?project=gitlab-review-apps [review-apps.sh]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/review-apps.sh [automated_cleanup.rb]: https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/review_apps/automated_cleanup.rb -[Auto-DevOps.gitlab-ci.yml]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml +[Auto-DevOps.gitlab-ci.yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml +[gitlab-ci-yml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml [gitlab-k8s-integration]: https://docs.gitlab.com/ee/user/project/clusters/index.html +[password-bug]: https://gitlab.com/gitlab-org/gitlab-ce/issues/53621 --- diff --git a/doc/development/testing_guide/smoke.md b/doc/development/testing_guide/smoke.md index 3f2843cba6e..3360031c220 100644 --- a/doc/development/testing_guide/smoke.md +++ b/doc/development/testing_guide/smoke.md @@ -1,8 +1,9 @@ # Smoke Tests -It is imperative in any testing suite that we have Smoke Tests. In short, smoke tests are will run quick sanity -end-to-end functional tests from GitLab QA and are designed to run against the specified environment to ensure that -basic functionality is working. +It is imperative in any testing suite that we have Smoke Tests. In short, smoke +tests will run quick sanity end-to-end functional tests from GitLab QA and are +designed to run against the specified environment to ensure that basic +functionality is working. Currently, our suite consists of this basic functionality coverage: @@ -11,6 +12,8 @@ Currently, our suite consists of this basic functionality coverage: - Issue Creation - Merge Request Creation +Smoke tests have the `:smoke` RSpec metadata. + --- [Return to Testing documentation](index.md) diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 32ed22ca3ed..a8671fc3aa3 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -34,7 +34,11 @@ records should use stubs/doubles as much as possible. Formal definition: https://en.wikipedia.org/wiki/Integration_testing -These kind of tests ensure that individual parts of the application work well together, without the overhead of the actual app environment (i.e. the browser). These tests should assert at the request/response level: status code, headers, body. They're useful to test permissions, redirections, what view is rendered etc. +These kind of tests ensure that individual parts of the application work well +together, without the overhead of the actual app environment (i.e. the browser). +These tests should assert at the request/response level: status code, headers, +body. +They're useful to test permissions, redirections, what view is rendered etc. | Code path | Tests path | Testing engine | Notes | | --------- | ---------- | -------------- | ----- | @@ -67,20 +71,40 @@ run JavaScript tests, so you can either run unit tests (e.g. test a single JavaScript method), or integration tests (e.g. test a component that is composed of multiple components). -## System tests or feature tests +## White-box tests at the system level (formerly known as System / Feature tests) -Formal definition: https://en.wikipedia.org/wiki/System_testing. +Formal definitions: -These kind of tests ensure the application works as expected from a user point -of view (aka black-box testing). These tests should test a happy path for a -given page or set of pages, and a test case should be added for any regression +- https://en.wikipedia.org/wiki/System_testing +- https://en.wikipedia.org/wiki/White-box_testing + +These kind of tests ensure the GitLab *Rails* application (i.e. +`gitlab-ce`/`gitlab-ee`) works as expected from a *browser* point of view. + +Note that: + +- knowledge of the internals of the application are still required +- data needed for the tests are usually created directly using RSpec factories +- expectations are often set on the database or objects state + +These tests should only be used when: + +- the functionality/component being tested is small +- the internal state of the objects/database *needs* to be tested +- it cannot be tested at a lower level + +For instance, to test the breadcrumbs on a given page, writing a system test +makes sense since it's a small component, which cannot be tested at the unit or +controller level. + +Only test the happy path, but make sure to add a test case for any regression that couldn't have been caught at lower levels with better tests (i.e. if a regression is found, regression tests should be added at the lowest-level possible). | Tests path | Testing engine | Notes | | ---------- | -------------- | ----- | -| `spec/features/` | [Capybara] + [RSpec] | If your spec has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. | +| `spec/features/` | [Capybara] + [RSpec] | If your test has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. | ### Consider **not** writing a system test! @@ -89,7 +113,7 @@ we have enough Unit & Integration tests), we shouldn't need to duplicate their thorough testing at the System test level. It's very easy to add tests, but a lot harder to remove or improve tests, so one -should take care of not introducing too many (slow and duplicated) specs. +should take care of not introducing too many (slow and duplicated) tests. The reasons why we should follow these best practices are as follows: @@ -107,29 +131,33 @@ The reasons why we should follow these best practices are as follows: [Poltergeist]: https://github.com/teamcapybara/capybara#poltergeist [RackTest]: https://github.com/teamcapybara/capybara#racktest -## Black-box tests or end-to-end tests +## Black-box tests at the system level, aka end-to-end tests + +Formal definitions: + +- https://en.wikipedia.org/wiki/System_testing +- https://en.wikipedia.org/wiki/Black-box_testing GitLab consists of [multiple pieces] such as [GitLab Shell], [GitLab Workhorse], [Gitaly], [GitLab Pages], [GitLab Runner], and GitLab Rails. All theses pieces are configured and packaged by [GitLab Omnibus]. -[GitLab QA] is a tool that allows to test that all these pieces integrate well -together by building a Docker image for a given version of GitLab Rails and -running feature tests (i.e. using Capybara) against it. +The QA framework and instance-level scenarios are [part of GitLab Rails] so that +they're always in-sync with the codebase (especially the views). -The actual test scenarios and steps are [part of GitLab Rails] so that they're -always in-sync with the codebase. +Note that: -### Smoke tests - -Smoke tests are quick tests that may be run at any time (especially after the pre-deployment migrations). +- knowledge of the internals of the application are not required +- data needed for the tests can only be created using the GUI or the API +- expectations can only be made against the browser page and API responses -Much like feature tests - these tests run against the UI and ensure that basic functionality is working. +Every new feature should come with a [test plan]. -> See [Smoke Tests](smoke.md) for more information. +| Tests path | Testing engine | Notes | +| ---------- | -------------- | ----- | +| `qa/qa/specs/features/` | [Capybara] + [RSpec] + Custom QA framework | Tests should be placed under their corresponding [Product category] | -Read a separate document about [end-to-end tests](end_to_end_tests.md) to -learn more. +> See [end-to-end tests](end_to_end_tests.md) for more information. [multiple pieces]: ../architecture.md#components [GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell @@ -138,8 +166,29 @@ learn more. [GitLab Pages]: https://gitlab.com/gitlab-org/gitlab-pages [GitLab Runner]: https://gitlab.com/gitlab-org/gitlab-runner [GitLab Omnibus]: https://gitlab.com/gitlab-org/omnibus-gitlab -[GitLab QA]: https://gitlab.com/gitlab-org/gitlab-qa [part of GitLab Rails]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa +[test plan]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab/issue_templates/Test%20plan.md +[Product category]: https://about.gitlab.com/handbook/product/categories/ + +### Smoke tests + +Smoke tests are quick tests that may be run at any time (especially after the +pre-deployment migrations). + +These tests run against the UI and ensure that basic functionality is working. + +> See [Smoke Tests](smoke.md) for more information. + +### GitLab QA orchestrator + +[GitLab QA orchestrator] is a tool that allows to test that all these pieces +integrate well together by building a Docker image for a given version of GitLab +Rails and running end-to-end tests (i.e. using Capybara) against it. + +Learn more in the [GitLab QA orchestrator README][gitlab-qa-readme]. + +[GitLab QA orchestrator]: https://gitlab.com/gitlab-org/gitlab-qa +[gitlab-qa-readme]: https://gitlab.com/gitlab-org/gitlab-qa/tree/master/README.md ## EE-specific tests diff --git a/doc/development/ui_guide.md b/doc/development/ui_guide.md index df6ac452300..1e84bf608f4 100644 --- a/doc/development/ui_guide.md +++ b/doc/development/ui_guide.md @@ -1,107 +1,5 @@ -# UI Guide for building GitLab +--- +redirect_to: 'https://design.gitlab.com/' +--- -## GitLab UI development kit - -We created a page inside GitLab where you can check commonly used html and css elements. - -When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples -you can use during GitLab development. - -## Design repository - -All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design) -repository and maintained by GitLab UX designers. - -## Navigation - -GitLab's layout contains 2 sections: the left sidebar and the content. The left sidebar contains a static navigation menu. -This menu will be visible regardless of what page you visit. -The content section contains a header and the content itself. The header describes the current GitLab page and what navigation is -available to the user in this area. Depending on the area (project, group, profile setting) the header name and navigation may change. For example, when the user visits one of the -project pages the header will contain the project's name and navigation for that project. When the user visits a group page it will contain the group's name and navigation related to this group. - -You can see a visual representation of the navigation in GitLab in the GitLab Product Map, which is located in the [Design Repository][gitlab-map-graffle] -along with [PDF][gitlab-map-pdf] and [PNG][gitlab-map-png] exports. - - -### Adding new tab to header navigation - -We try to keep the amount of tabs in the header navigation between 5 and 10 so that it fits on a typical laptop screen. We also try not to confuse the user with too many options. Ideally each -tab should represent separate functionality. Everything related to the issue -tracker should be under the 'Issues' tab while everything related to the wiki should -be under 'Wiki' tab and so on and so forth. -When adding a new tab to the header don't use more than 2 words for text in the link. -We want to keep links short and easy to remember and fit all of them in the small screen. - -## Mobile screen size - -We want GitLab to work well on small mobile screens as well. Size limitations make it is impossible to fit everything on a mobile screen. In this case it is OK to hide -part of the UI for smaller resolutions in favor of a better user experience. -However core functionality like browsing files, creating issues, writing comments, should -be available on all resolutions. - -## Icons - -* `trash` icon for button or link that does destructive action like removing -information from database or file system -* `x` icon for closing/hiding UI element. For example close modal window -* `pencil` icon for edit button or link -* `eye` icon for subscribe action -* `rss` for rss/atom feed -* `plus` for link or dropdown that lead to page where you create new object (For example new issue page) - -### SVGs - -When exporting SVGs, be sure to follow the following guidelines: - -1. Convert all strokes to outlines. -2. Use pathfinder tools to combine overlapping paths and create compound paths. -3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. -4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. - -You can open your svg in a text editor to ensure that it is clean. -Incorrect files will look like this: - -```xml -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<svg width="16px" height="17px" viewBox="0 0 16 17" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> - <!-- Generator: Sketch 3.7.2 (28276) - http://www.bohemiancoding.com/sketch --> - <title>Group</title> - <desc>Created with Sketch.</desc> - <defs></defs> - <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> - <g id="Group" fill="#7E7C7C"> - <path d="M15.1111,1 L0.8891,1 C0.3981,1 0.0001,1.446 0.0001,1.996 L0.0001,15.945 C0.0001,16.495 0.3981,16.941 0.8891,16.941 L15.1111,16.941 C15.6021,16.941 16.0001,16.495 16.0001,15.945 L16.0001,1.996 C16.0001,1.446 15.6021,1 15.1111,1 L15.1111,1 L15.1111,1 Z M14.0001,6.0002 L14.0001,14.949 L2.0001,14.949 L2.0001,6.0002 L14.0001,6.0002 Z M14.0001,4.0002 L14.0001,2.993 L2.0001,2.993 L2.0001,4.0002 L14.0001,4.0002 Z" id="Combined-Shape"></path> - <polygon id="Fill-11" points="3 2.0002 5 2.0002 5 0.0002 3 0.0002"></polygon> - <polygon id="Fill-16" points="11 2.0002 13 2.0002 13 0.0002 11 0.0002"></polygon> - <path d="M5.37709616,11.5511984 L6.92309616,12.7821984 C7.35112915,13.123019 7.97359761,13.0565604 8.32002627,12.6330535 L10.7740263,9.63305349 C11.1237073,9.20557058 11.0606364,8.57555475 10.6331535,8.22587373 C10.2056706,7.87619272 9.57565475,7.93926361 9.22597373,8.36674651 L6.77197373,11.3667465 L8.16890384,11.2176016 L6.62290384,9.98660159 C6.19085236,9.6425813 5.56172188,9.71394467 5.21770159,10.1459962 C4.8736813,10.5780476 4.94504467,11.2071781 5.37709616,11.5511984 L5.37709616,11.5511984 Z" id="Stroke-21"></path> - </g> - </g> -</svg> -``` - -Correct file will look like this: - -```xml -<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> -``` - - -## Buttons - -* Button should contain icon or text. Exceptions should be approved by UX designer. -* Use red button for destructive actions (not revertable). For example removing issue. -* Use green or blue button for primary action. Primary button should be only one. -Do not use both green and blue button in one form. -* For all other cases use default white button. -* Text button should have only first word capitalized. So should be "Create issue" instead of "Create Issue" - -## Counts - -* Always use the [`number_with_delimiter`][number_with_delimiter] helper to - display counts in the UI. - -[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter -[gitlab-map-graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/master/production/resources/gitlab-map.graffle -[gitlab-map-pdf]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.pdf -[gitlab-map-png]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 0d074a3ef05..e5466ae8914 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -171,8 +171,8 @@ class Commit extend Gitlab::Cache::RequestCache def author - User.find_by_any_email(author_email.downcase) + User.find_by_any_email(author_email) end - request_cache(:author) { author_email.downcase } + request_cache(:author) { author_email } end ``` diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md index 797390a6845..583ff19bc69 100644 --- a/doc/development/ux_guide/animation.md +++ b/doc/development/ux_guide/animation.md @@ -1,65 +1,5 @@ -# Animation +--- +redirect_to: 'https://design.gitlab.com/foundations/motion' +--- -Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. - -## Timings - -The longer distance an object travel, the timing should be longer for the animation. However, when in doubt, we should avoid large, full screen animations. - -Subtle animations, or objects leaving the screen should take **100-200 milliseconds**. Objects entering the screen, or motion we want to use to direct user attention can take between **200-400 milliseconds**. We should avoid animations of longer than 400 milliseconds as they will make the experience appear sluggish. If a specific animation feels like it will need more than 400 milliseconds, revisit the animation to see if there is a simpler, easier, shorter animation to implement. - -## Easing - -Easing specifies the rate of change of a parameter over time (see [easings.net](http://easings.net/)). Adding an easing curve will make the motion feel more natural. Being consistent with the easing curves will make the whole experience feel more cohesive and connected. - -* When an object is entering the screen, or transforming the scale, position, or shape, use the **easeOutQuint** curve (`cubic-bezier(0.23, 1, 0.32, 1)`) -* When an object is leaving the screen, or transforming the opacity or color, no easing curve is needed. It shouldn't _slow down_ as it is exiting the screen, as that draws attention on the leaving object, where we don't want it. Adding easing to opacity and color transitions will make the motion appear less smooth. Therefore, for these cases, motion should just be **linear**. - -## Types of animations - -### Hover - -Interactive elements (links, buttons, etc.) should have a hover state. A subtle animation for this transition adds a polished feel. We should target a `100ms - 150ms linear` transition for a color hover effect. - -View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here. - - - -### Dropdowns - -The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with an opacity animation `200ms linear` on the second half of the motion achieves this affect. - -View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here. - - - -### Quick update - -When information is updating in place, a quick, subtle animation is needed. The previous content should cut out, and the new content should have a quick, `200ms linear` fade in. - - - -### Skeleton loading - -Skeleton loading is explained in the [component section](components.html#skeleton-loading) of the UX guide. It includes a horizontally pulsating animation that shows motion as if it's growing. It's timing is a slower `linear 1s`. - - - -### Moving transitions - -When elements move on screen, there should be a quick animation so it is clear to users what moved where. The timing of this animation differs based on the amount of movement and change. Consider animations between `200ms` and `400ms`. - -#### Shifting elements on reorder -An example of a moving transition is when elements have to move out of the way when you drag an element. - -View the [interactive example](http://codepen.io/awhildy/full/ALyKPE/) here. - - - -#### Autoscroll the page - -Another example of a moving transition is when you have to autoscroll the page to keep an active element visible. - -View the [interactive example](http://codepen.io/awhildy/full/PbxgVo/) here. - - +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com). diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md index e215026bcca..1e84bf608f4 100644 --- a/doc/development/ux_guide/basics.md +++ b/doc/development/ux_guide/basics.md @@ -1,82 +1,5 @@ -# Basics - -## Contents -* [Responsive](#responsive) -* [Typography](#typography) -* [Icons](#icons) -* [Color](#color) -* [Cursors](#cursors) - ---- - -## Responsive -GitLab is a responsive experience that works well across all screen sizes, from mobile devices to large monitors. In order to provide a great user experience, the core functionality (browsing files, creating issues, writing comments, etc.) must be available at all resolutions. However, due to size limitations, some secondary functionality may be hidden on smaller screens. Please keep this functionality limited to rare actions that aren't expected to be needed on small devices. - ---- - -## Typography -### Primary typeface -GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support both the bold and regular weight. - - - - -### Monospace typeface -This is the typeface used for code blocks and references to commits, branches, and tags (`.commit-sha` or `.ref-name`). GitLab uses the OS default font. -- **Menlo** (Mac) -- **Consolas** (Windows) -- **Liberation Mono** (Linux) - - - ---- - -## Icons - -GitLab has a strong, unique personality. When you look at any screen, you should know immediately that it is GitLab. -Iconography is a powerful visual cue to the user and is a great way for us to reflect our particular sense of style. - -- **Standard size:** 16px * 16px -- **Border thickness:** 2px -- **Border radius:** 3px - - - -> TODO: List all icons, proper usage, hover, and active states. - --- - -## Color - -| | State | Action | -| :------: | :------- | :------- | -|  | Primary and active (such as the current tab) | Organizational, managing, and retry commands| -|  | Opened | Create new objects | -|  | Warning | Non destructive action | -|  | Closed | Delete and other destructive commands | -|  | Neutral | Neutral secondary commands | - -### Text colors - -||| -| :---: | :--- | -|  | Used for primary body text, such as issue description and comment | -|  | Used for secondary body text, such as username and date | - -> TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. - +redirect_to: 'https://design.gitlab.com/' --- -## Cursors -The mouse cursor is key in helping users understand how to interact with elements on the screen. - -| | | -| :------: | :------- | -|  | Default cursor | -|  | Pointer cursor: used to indicate that you can click on an element to invoke a command or navigate, such as links and buttons | -|  | Move cursor: used to indicate that you can move an element around on the screen | -|  | Pan cursor (opened): indicates that you can grab and move the entire canvas, affecting what is seen in the view port. | -|  | Pan cursor (closed): indicates that you are actively panning the canvas. | -|  | I-beam cursor: indicates that this is either text that you can select and copy, or a text field that you can click into to enter text. | - - +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index 4a3b3125f59..1e84bf608f4 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -1,387 +1,5 @@ -# Components - -## Contents -* [Tooltips](#tooltips) -* [Anchor links](#anchor-links) -* [Buttons](#buttons) -* [Dropdowns](#dropdowns) -* [Counts](#counts) -* [Lists](#lists) -* [Tables](#tables) -* [Blocks](#blocks) -* [Panels](#panels) -* [Modals](#modals) -* [Alerts](#alerts) -* [Forms](#forms) -* [Search box](#search-box) -* [File holders](#file-holders) -* [Data formats](#data-formats) - ---- - -## Tooltips -Tooltips identify elements or provide additional, useful information about the referring elements. Tooltips are different from ALT-attributes, which are intended primarily for static images. Tooltips are summoned by: - -* Hovering over an element with a cursor -* Focusing on an element with a keyboard (usually the tab key) -* Upon touch - -### Usage -A tooltip should be used: -* When there isn’t enough space to show the information -* When it isn’t critical for the user to see the information -* For icons that don’t have a label - -Tooltips shouldn’t repeat information that is shown near the referring element. However, they can show the same data in a different format (e.g. date or timestamps). - - - -### Placement -By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport, the tooltip should be moved to the side as needed. - - - ---- - -## Popovers - -Popovers provide additional, useful, unique information about the referring elements and can provide one or multiple actionable elements. They inform the user of additional information within the context of their original view, but without forcing the user to act upon it like a modal. Popovers are different from tooltips, which do not provide rich markup and actionable items. A popover can contain a header section with a different background color. - -Popovers are summoned: - -* Upon hover or touch on an element - -### Usage -A popover should be used: -* When you don't want to let the user lose context, but still want to provide additional useful unique information about referring elements -* When it isn’t critical for the user to act upon the information -* When you want to give a user a summary of extended information and the option to switch context if they want to dive in deeper. - -### Styling - -A popover can contain a header section with a different background color if that improves readability and separation of content within. - - - -This example shows two sections, where each section includes an actionable element. The first section shows a summary of the content shown when clicking the "read more" link. With this information the user can decide to dive deeper or start their GitLab Enterprise Edition trial immediately. - -### Placement -By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport or it blocks related content, the tooltip should be moved to the side or above as needed. - - - -In this example we let the user know more about the setting they are deciding over, without loosing context. If they want to know even more they can do so, but with the expectation of opening that content in a new view. - ---- - -## Anchor links - -Anchor links are used for navigational actions and lone, secondary commands (such as 'Reset filters' on the Issues List) when deemed appropriate by the UX team. - -### States - -#### Rest - -Primary links are blue in their rest state. Secondary links (such as the time stamp on comments) are a neutral gray color in rest. Details on the main GitLab navigation links can be found on the [features](features.md#navigation) page. - -#### Hover - -On hover, an underline should be added and the color should change. Both the primary and secondary link should become the darker blue color on hover. - -#### Focus - -The focus state should match the hover state. - - - ---- - -## Buttons - -Buttons communicate the command that will occur when the user clicks on them. - -### Types - -#### Primary -Primary buttons communicate the main call to action. There should only be one call to action in any given experience. Visually, primary buttons are conveyed with a full background fill - - - -#### Secondary -Secondary buttons are for alternative commands. They should be conveyed by a button with a stroke, and no background fill. - - - -### Icon and text treatment -Text should be in sentence case, where only the first word is capitalized. "Create issue" is correct, not "Create Issue". Buttons should only contain an icon or a text, not both. - -> TODO: Rationalize this. Ensure that we still believe this. - -### Colors -The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button. - -### Secondary states - -Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed. - -| Values | Info | Success | Warning | Danger | -| :------ | :------: | :------: | :------: | :------: | -| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  |  | -| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  |  | -| Background: `$color-dark` <br> Border: `$border-color-dark` |  |  |  |  | - -Since secondary buttons only have a border on their resting state, their hover and focus states add a background color, which gets darkened on active. - -| Values | Success Secondary | Close | Spam | -| :------ | :------: | :------: | :------: | -| Font: `$border-color-light` <br> Border: `$border-color-light` |  |  |  | -| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  | -| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  | - -### Placement - -When there are a group of buttons in a dialog or a form, we need to be consistent with the placement. - -#### Dismissive actions on the left -The dismissive action returns the user to the previous state. - -> Example: Cancel - -#### Affirmative actions on the right -Affirmative actions continue to progress towards the user goal that triggered the dialog or form. - -> Example: Submit, Ok, Delete - ---- - - -## Dropdowns - -Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.) - -> TODO: Will update this section when the new filters UI is implemented. - - - -### Max size - -The max height for dropdowns should target **10-15** single line items, or **7-10** multi-line items. If the height of the dropdown is too large, the list becomes very hard to parse and it is easy to visually lose track of the item you are looking for. Usability also suffers as more mouse movement is required, and you have a larger area in which you hijack the scroll away from the page level. While it may initially seem counterintuitive to not show as many items as you can, it is actually quicker and easier to process the information when it is cropped at a reasonable height. - ---- - -## Counts - -A count element is used in navigation contexts where it is helpful to indicate the count, or number of items, in a list. Always use the [`number_with_delimiter`][number_with_delimiter] helper to display counts in the UI. - - - -[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter - ---- - -## Lists - -Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of an important list in the GitLab UI. - -### Types - -Simple list using .content-list - - - -List with avatar, title and description using .content-list - - - -List with hover effect .content-list - - - -List inside panel - - - ---- - -## Tables - -When the information is too complex for a list, with multiple columns of information, a table can be used. For example, the [pipelines page](https://gitlab.com/gitlab-org/gitlab-ce/pipelines) uses a table. - - - ---- - -## Blocks - -Blocks are a way to group related information. - -### Types - -#### Content blocks - -Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a button border. - - - -#### Row content blocks - -A background color can be added to this blocks. For example, items in the [issue list](https://gitlab.com/gitlab-org/gitlab-ce/issues) have a green background if they were created recently. Below is an example of a gray content block with side padding using `.row-content-block`. - - - -#### Cover blocks -Cover blocks are generally used to create a heading element for a page, such as a new project, or a user profile page. Below is a cover block (`.cover-block`) for the profile page with an avatar, name and description. - - - ---- - -## Skeleton loading - -Skeleton loading is a way to convey to the user what kind of content is currently being loaded. It's a paradigm with which content can independently and asynchronously be loaded, while still adhering to the structure and look of the completely loaded view. - -### Requirements - -* A skeleton should represent an organism in a recognisable way -* Atom elements within organisms (for reference see this article on [atomic design methodology](http://atomicdesign.bradfrost.com/chapter-2/)) may be represented in a maximum of 3 repetitions, if applicable. -* Skeletons should only be presented in grayscale using the HEX colors: `#fafafa` or `#ffffff` (except for shadows) -* Animate the grey atoms in a pulsating way to show motion, as if "loading". The pulse animation transitions colors horizontally from left to right, starting with `#f2f2f2` to `#fafafa`. - - - -### Usage - -Skeleton loading can replace any existing UI elements for the period in which they are loaded and should aim for maintaining a similar structure visually. - ---- - -## Modals - -Modals are only used for having a conversation and confirmation with the user. The user is not able to access the features on the main page until closing the modal. - -### Usage - -* When the action is irreversible, modals provide the details and confirm with the user before they take an advanced action. -* When the action will affect privacy or authorization, modals provide advanced information and confirm with the user. - -### Style - -* Modals contain the header, body, and actions. - * **Header(1):** The header title is a question instead of a descriptive phrase. - * **Body(2):** The content in body should never be ambiguous and unclear. It provides specific information. - * **Actions(3):** Contains an affirmative action, a dismissive action, and an extra action. The order of actions from left to right: Dismissive action → Extra action → Affirmative action -* Confirmations regarding labels should keep labeling styling. -* References to commits, branches, and tags should be **monospaced**. - - - -### Placement - -* Modals should always be the center of the screen horizontally and be positioned **72px** from the top. - -| Modal with 2 actions | Modal with 3 actions | Special confirmation | -| --------------------- | --------------------- | -------------------- | -|  |  |  | - -> TODO: Special case for modal. - ---- - -## Panels - -> TODO: Catalog how we are currently using panels and rationalize how they relate to alerts - - - ---- - -## Alerts - -> TODO: Catalog how we are currently using alerts - - - --- - -## Forms - -There are two options shown below regarding the positioning of labels in forms. Both are options to consider based on context and available size. However, it is important to have a consistent treatment of labels in the same form. - -### Types - -#### Labels stack vertically - -Form (`form`) with label rendered above input. - - - -#### Labels side-by-side - -Horizontal form (`form.horizontal-form`) with label rendered inline with input. - - - +redirect_to: 'https://design.gitlab.com/' --- -## Search box - -Search boxes across GitLab have a consistent rest, active and text entered state. When text isn't entered in the box, there should be a magnifying glass right aligned with the input field. When text is entered, the magnifying glass should become a x, allowing users to clear their text. - - - -If needed, we indicate the scope of the search in the search box. - - - ---- - -## File holders -A file holder (`.file-holder`) is used to show the contents of a file inline on a page of GitLab. - - - ---- - -## Data formats - -### Dates - -#### Exact - -Format for exacts dates should be ‘Mon DD, YYYY’, such as the examples below. - - - -#### Relative - -This format relates how long since an action has occurred. The exact date can be shown as a tooltip on hover. - - - -### References - -Referencing GitLab items depends on a symbol for each type of item. Typing that symbol will invoke a dropdown that allows you to search for and autocomplete the item you were looking for. References are shown as [links](#links) in context, and hovering on them shows the full title or name of the item. - - - -#### `%` Milestones - - - -#### `#` Issues - - - -#### `!` Merge Requests - - - -#### `~` Labels - - - -#### `@` People - - - -> TODO: Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this. +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index d5afa544372..1e84bf608f4 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -1,198 +1,5 @@ -# Copy
-
-The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding.
-
-The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab.
-
-Portions of this page are inspired by work found in the [Material Design guidelines][material design].
-
->**Note:**
-We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align.
-
-## Contents
-* [Brevity](#brevity)
-* [Capitalization and punctuation](#capitalization-and-punctuation)
-* [Terminology](#terminology)
-
----
-
-## Brevity
-Users will skim content, rather than read text carefully.
-When familiar with a web app, users rely on muscle memory, and may read even less when moving quickly.
-A good experience should quickly orient a user, regardless of their experience, to the purpose of the current screen. This should happen without the user having to consciously read long strings of text.
-In general, text is burdensome and adds cognitive load. This is especially pronounced in a powerful productivity tool such as GitLab.
-We should _not_ rely on words as a crutch to explain the purpose of a screen.
-The current navigation and composition of the elements on the screen should get the user 95% there, with the remaining 5% being specific elements such as text.
-This means that, as a rule, copy should be very short. A long message or label is a red flag hinting at design that needs improvement.
-
->**Example:**
-Use `Add` instead of `Add issue` as a button label.
-Preferably use context and placement of controls to make it obvious what clicking on them will do.
-
----
-
-## Capitalization and punctuation
-
-### Case
-Use sentence case for titles, headings, labels, menu items, and buttons. Use title case when referring to [features][features] or [products][products]. Note that some features are also objects (e.g. “Merge Requests” and “merge requests”).
-
-| :white_check_mark: Do | :no_entry_sign: Don’t |
-| --- | --- |
-| Add issues to the Issue Board feature in GitLab Hosted | Add Issues To The Issue Board Feature In GitLab Hosted |
-
-### Avoid periods
-Avoid using periods in solitary sentences in these elements:
-
-* Labels
-* Hover text
-* Bulleted lists
-* Modal body text
-
-Periods should be used for:
-
-* Lists or modals with multiple sentences
-* Any sentence followed by a link
-
-| :white_check_mark: **Do** place periods after sentences followed by a link | :no_entry_sign: **Don’t** place periods after a link if it‘s not followed by a sentence |
-| --- | --- |
-| Mention someone to notify them. [Learn more](#) | Mention someone to notify them. [Learn more](#). |
-
-| :white_check_mark: **Do** skip periods after solo sentences of body text | :no_entry_sign: **Don’t** place periods after body text if there is only a single sentence |
-| --- | --- |
-| To see the available commands, enter `/gitlab help` | To see the available commands, enter `/gitlab help`. |
-
-### Use contractions
-Don’t make a sentence harder to understand just to follow this rule. For example, “do not” can give more emphasis than “don’t” when needed.
-
-| :white_check_mark: Do | :no_entry_sign: Don’t |
-| --- | --- |
-| it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t | it is, cannot, would not, it’ll, should’ve |
-
-### Use numerals for numbers
-Use “1, 2, 3” instead of “one, two, three” for numbers. One exception is when mixing uses of numbers, such as “Enter two 3s.”
-
-| :white_check_mark: Do | :no_entry_sign: Don’t |
-| --- | --- |
-| 3 new commits | Three new commits |
-
-### Punctuation
-Omit punctuation after phrases and labels to create a cleaner and more readable interface. Use punctuation to add clarity or be grammatically correct.
-
-| Punctuation mark | Copy and paste | HTML entity | Unicode | Mac shortcut | Windows shortcut | Description |
-|---|---|---|---|---|---|---|
-| Period | **.** | | | | | Omit for single sentences in affordances like labels, hover text, bulleted lists, and modal body text.<br><br>Use in lists or modals with multiple sentences, and any sentence followed by a link or inline code.<br><br>Place inside quotation marks unless you’re telling the reader what to enter and it’s ambiguous whether to include the period. |
-| Comma | **,** | | | | | Place inside quotation marks.<br><br>Use a [serial comma][serial comma] in lists of three or more terms. |
-| Exclamation point | **!** | | | | | Avoid exclamation points as they tend to come across as shouting. Some exceptions include greetings or congratulatory messages. |
-| Colon | **:** | `:` | `\u003A` | | | Omit from labels, for example, in the labels for fields in a form. |
-| Apostrophe | **’** | `’` | `\u2019` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use for contractions (I’m, you’re, ’89) and to show possession.<br><br>To show possession, add an *’s* to all singular common nouns and names, even if they already end in an *s*: “Look into this worker process’s log.” For singular proper names ending in *s*, use only an apostrophe: “James’ commits.” For plurals of a single letter, add an *’s*: “Dot your i’s and cross your t’s.”<br><br>Omit for decades or acronyms: “the 1990s”, “MRs.” |
-| Quotation marks | **“**<br><br>**”**<br><br>**‘**<br><br>**’** | `“`<br><br>`”`<br><br>`‘`<br><br>`’` | `\u201C`<br><br>`\u201D`<br><br>`\u2018`<br><br>`\u2019` | <kbd>⌥ Option</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>]</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 7</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 8</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 5</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use proper quotation marks (also known as smart quotes, curly quotes, or typographer’s quotes) for quotes. Single quotation marks are used for quotes inside of quotes.<br><br>The right single quotation mark symbol is also used for apostrophes.<br><br>Don’t use primes, straight quotes, or free-standing accents for quotation marks. |
-| Primes | **′**<br><br>**″** | `′`<br><br>`″` | `\u2032`<br><br>`\u2033` | | <kbd>Alt</kbd>+<kbd>8 2 4 2</kbd><br><br><kbd>Alt</kbd>+<kbd>8 2 4 3</kbd> | Use prime (′) only in abbreviations for feet, arcminutes, and minutes: 3° 15′<br><br>Use double-prime (″) only in abbreviations for inches, arcseconds, and seconds: 3° 15′ 35″<br><br>Don’t use quotation marks, straight quotes, or free-standing accents for primes. |
-| Straight quotes and accents | **"**<br><br>**'**<br><br>**`**<br><br>**´** | `"`<br><br>`'`<br><br>```<br><br>`´` | `\u0022`<br><br>`\u0027`<br><br>`\u0060`<br><br>`\u00B4` | | | Don’t use straight quotes or free-standing accents for primes or quotation marks.<br><br>Proper typography never uses straight quotes. They are left over from the age of typewriters and their only modern use is for code. |
-| Ellipsis | **…** | `…` | | <kbd>⌥ Option</kbd>+<kbd>;</kbd> | <kbd>Alt</kbd>+<kbd>0 1 3 3</kbd> | Use to indicate an action in progress (“Downloading…”) or incomplete or truncated text. No space before the ellipsis.<br><br>Omit from menu items or buttons that open a modal or start some other process. |
-| Chevrons | **«**<br><br>**»**<br><br>**‹**<br><br>**›**<br><br>**<**<br><br>**>** | `«`<br><br>`»`<br><br>`‹`<br><br>`›`<br><br>`<`<br><br>`>` | `\u00AB`<br><br>`\u00BB`<br><br>`\u2039`<br><br>`\u203A`<br><br>`\u003C`<br><br>`\u003E`<br><br> | | | Omit from links or buttons that open another page or move to the next or previous step in a process. Also known as angle brackets, angular quote brackets, or guillemets. |
-| Em dash | **—** | `—` | `\u2014` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 1</kbd> | Avoid using dashes to separate text. If you must use dashes for this purpose — like this — use an em dash surrounded by spaces. |
-| En dash | **–** | `–` | `\u2013` | <kbd>⌥ Option</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 0</kbd> | Use an en dash without spaces instead of a hyphen to indicate a range of values, such as numbers, times, and dates: “3–5 kg”, “8:00 AM–12:30 PM”, “10–17 Jan” |
-| Hyphen | **-** | | | | | Use to represent negative numbers, or to avoid ambiguity in adjective-noun or noun-participle pairs. Example: “anti-inflammatory”; “5-mile walk.”<br><br>Omit in commonly understood terms and adverbs that end in *ly*: “frontend”, “greatly improved performance.”<br><br>Omit in the term “open source.” |
-| Parentheses | **( )** | | | | | Use only to define acronyms or jargon: “Secure web connections are based on a technology called SSL (the secure sockets layer).”<br><br>Avoid other uses and instead rewrite the text, or use dashes or commas to set off the information. If parentheses are required: If the parenthetical is a complete, independent sentence, place the period inside the parentheses; if not, the period goes outside. |
-
-When using the <kbd>Alt</kbd> keystrokes in Windows, use the numeric keypad, not the row of numbers above the alphabet, and be sure Num Lock is turned on.
-
----
-
-## Terminology
-Only use the terms below.
-
-When using verbs or adjectives:
-* If the context clearly refers to the object, use them alone. Example: `Edit` or `Closed`
-* If the context isn’t clear enough, use them with the object. Example: `Edit issue` or `Closed issues`
-
-### Search
-
-| Term | Use |
-| ---- | --- |
-| Search | When using all metadata to add criteria that match/don't match. Search can also affect ordering, by ranking best results. |
-| Filter | When taking a single criteria that removes items within a list that match/don't match. Filters do not affect ordering. |
-| Sort | Orders a list based on a single or grouped criteria |
-
-### Projects and Groups
-
-| Term | Use | :no_entry_sign: Don't |
-| ---- | --- | ----- |
-| Members | When discussing the people who are a part of a project or a group. | Don't use `users`. |
-
-### Issues
-
-#### Adjectives (states)
-
-| Term | :no_entry_sign: Don’t |
-| ---- | --- |
-| Open | Don’t use `Pending` or `Created` |
-| Closed | Don’t use `Archived` |
-| Deleted | Don’t use `Removed` or `Trashed` |
-
-#### Verbs (actions)
-
-| Term | Use | :no_entry_sign: Don’t |
-| ---- | --- | --- |
-| New | Although it’s not a verb, `New` is a common standard and used for entering the creation mode of a non-existent issue | Don’t use `Create`, `Open`, or `Add` |
-| Create | Only to indicate when or who created an issue ||
-| Add | Associate an existing issue with an item or a list of items | Don’t use `New` or `Create` |
-| View | Open the detail page of an issue | Don’t use `Open` or `See` |
-| Edit | Enter the editing mode of an issue | Don’t use `Change`, `Modify` or `Update` |
-| Submit | Finalize the *creation* process of an issue | Don’t use `Add`, `Create`, `New`, `Open`, `Save` or `Save changes` |
-| Save | Finalize the *editing* process of an issue | Don’t use `Edit`, `Modify`, `Update`, `Submit`, or `Save changes` |
-| Cancel | Cancel the *creation* or *editing* process of an issue | Don’t use `Back`, `Close`, or `Discard` |
-| Close | Close an open issue | Don’t use `Archive` |
-| Re-open | Re-open a closed issue | Don’t use `Open` |
-| Delete | Permanently remove an issue from the system | Don’t use `Remove` |
-| Remove | Remove the association an issue with an item or a list of items | Don’t use `Delete` |
-
-### Merge requests
-
-#### Adjectives (states)
-
-| Term |
-| ---- |
-| Open |
-| Merged |
-
-#### Verbs (actions)
-
-| Term | Use | :no_entry_sign: Don’t |
-| ---- | --- | --- |
-| Add | Add a merge request | Do not use `create` or `new` |
-| View | View an open or merged merge request ||
-| Edit | Edit an open or merged merge request| Do not use `update` |
-| Approve | Approve an open merge request ||
-| Remove approval, unapproved | Remove approval of an open merge request | Do not use `unapprove` as that is not an English word|
-| Merge | Merge an open merge request ||
-
-### Comments & Discussions
-
-#### Comment
-A **comment** is a written piece of text that users of GitLab can create. Comments have the meta data of author and timestamp. Comments can be added in a variety of contexts, such as issues, merge requests, and discussions.
-
-#### Discussion
-A **discussion** is a group of 1 or more comments. A discussion can include subdiscussions. Some discussions have the special capability of being able to be **resolved**. Both the comments in the discussion and the discussion itself can be resolved.
-
-## Modals
-
-- Destruction buttons should be clear and always say what they are destroying.
- E.g., `Delete page` instead of just `Delete`.
-- If the copy describes another action the user can take instead of the
- destructive one, provide a way for them to do that as a secondary button.
-- Avoid the word `cancel` or `canceled` in the descriptive copy. It can be
- confusing when you then see the `Cancel` button.
-
-see also: guidelines for [modal components](components.md#modals)
-
----
-
-Portions of this page are modifications based on work created and shared by the [Android Open Source Project][android project] and used according to terms described in the [Creative Commons 2.5 Attribution License][creative commons].
-
-[material design]: https://material.io/guidelines/
-[features]: https://about.gitlab.com/features/ "GitLab features page"
-[products]: https://about.gitlab.com/pricing/ "GitLab products page"
-[serial comma]: https://en.wikipedia.org/wiki/Serial_comma "“Serial comma” in Wikipedia"
-[android project]: http://source.android.com/
-[creative commons]: http://creativecommons.org/licenses/by/2.5/
+--- +redirect_to: 'https://design.gitlab.com/' +--- + +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md index 9472995c68c..1e84bf608f4 100644 --- a/doc/development/ux_guide/features.md +++ b/doc/development/ux_guide/features.md @@ -1,57 +1,5 @@ -# Features - -## Contents -* [Navigation](#navigation) -* [Filtering](#filtering) -* [Search results](#search-results) -* [Conversations](#conversations) -* [Empty states](#empty-states) - --- - -## Navigation - -### Global navigation - -The global navigation is accessible via the menu button on the top left of the screen, and can be pinned to keep it open. It contains a consistent list of pages that allow you to view content that is across GitLab. For example, you can view your todos, issues and merge requests across projects and groups. - - - - -### Contextual navigation - -The navigation in the header is contextual to each page. These options change depending on if you are looking at a project, group, or settings page. There should be no more than 10 items on a level in the contextual navigation, allowing it to comfortably fit on a typical laptop screen. There can be up to too levels of navigation. Each sub nav group should be a self-contained group of functionality. For example, everything related to the issue tracker should be under the 'Issue' tab, while everything relating to the wiki will be grouped under the 'Wiki' tab. The names used for each section should be short and easy to remember, ideally 1-2 words in length. - - - -### Information architecture - -The [GitLab Product Map](https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png) shows a visual representation of the information architecture for GitLab. - +redirect_to: 'https://design.gitlab.com/' --- -## Filtering - -Today, lists are filtered by a series of dropdowns. Some of these dropdowns allow multiselect (labels), while others allow you to filter to one option (milestones). However, we are currently implementing a [new model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747) for this, and will update the guide when it is ready. - - - ---- - -## Search results - -### Global search - -[Global search](https://gitlab.com/search?group_id=&project_id=13083&repository_ref=&scope=issues&search=mobile) allows you to search across items in a project, or even across multiple projects. You can switch tabs to filter on type of object, or filter by group. - -### List search - -There are several core lists in the GitLab experience, such as the Issue list and the Merge Request list. You are also able to [filter and search these lists](https://gitlab.com/gitlab-org/gitlab-ce/issues?utf8=%E2%9C%93&search=mobile). This UI will be updated with the [new filtering model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747). - ---- - -## Empty states - -Empty states need to be considered in the design of features. They are vital to helping onboard new users, making the experience feel more approachable and understandable. Empty states should feel inviting and provide just enough information to get people started. There should be a single call to action and a clear explanation of what to use the feature for. - - +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/illustrations.md b/doc/development/ux_guide/illustrations.md index 7e16c300921..ed072b6515f 100644 --- a/doc/development/ux_guide/illustrations.md +++ b/doc/development/ux_guide/illustrations.md @@ -1,86 +1,5 @@ -# Illustrations - -The illustrations should always align with topics and goals in specific context. - -## Principles - -#### Be simple. -- For clarity, we use simple and specific elements to create our illustrations. - -#### Be optimistic. -- We are an open-minded, optimistic, and friendly team. We should reflect those values in our illustrations to connect with our brand experience. - -#### Be gentle. -- Our illustrations assist users in understanding context and guide users in the right direction. Illustrations are supportive, so they should be obvious but not aggressive. - - -## Style - -#### Shapes -- All illustrations are geometric rather than organic. -- The illustrations are made by circles, rectangles, squares, and triangles. - -<img src="img/illustrations-geometric.png" width=224px alt="Example for geometric" /> - -#### Stroke -- Standard border thickness: **4px** -- Depending on the situation, border thickness can be changed to **3px**. For example, when the illustration size is small, an illustration with 4px border thickness would look tight. In this case, the border thickness can be changed to 3px. -- We use **rounded caps** and **rounded corner**. - -| Do | Don't | -| -------- | -------- | -| <img src="img/illustrations-caps-do.png" width= 133px alt="Do: caps and corner" /> | <img src="img/illustrations-caps-don't.png" width= 133px alt="Don't: caps and corner"/> | - -#### Radius -- Standard corner radius: **10px** -- Depending on the situation, corner radius can be changed to **5px**. For example, when the illustration size is small, an illustration with 10px corner radius would be over-rounded. In this case, the corner radius can be changed to 5px. - -<img src="img/illustrations-border-radius.png" width= 464px alt="Example for border radius"/> - -#### Size -Depends on the situation, the illustration size can be the 3 types below: - -**Large** -* Use case: Empty states, error pages(e.g. 404, 403) -* For vertical layout, the illustration should not larger than **430*300 px**. -* For horizontal layout, the illustration should not larger than **430*380 px**. - -| Vertical layout | Horizontal layout | -| --------------- | ----------------- | -| <img src="img/illustration-size-large-vertical.png" /> | <img src="img/illustration-size-large-horizontal.png" /> - -**Medium** -* Use case: Banner -* The illustration should not larger than **240*160 px** -* The illustration should keep simple and clear. We recommend not including too many elements in the medium size illustration. - -<img src="img/illustration-size-medium.png" width=983px /> - -**Small** -* Use case: Graphics for explanatory text, graphics for status. -* The illustration should not larger than **160*90 px**. -* The illustration should keep simple and clear. We recommend not including too many elements in the small size illustration. - -<img src="img/illustration-size-small.png" width=983px /> - -**Illustration on mobile** -- Keep the proportions in original ratio. - -#### Colors palette - -For consistency, we recommend choosing colors from our color palette. - -| Orange | Purple | Grey | -| -------- | -------- | -------- | -| <img src="img/illustrations-color-orange.png" width= 160px alt="Orange" /> | <img src="img/illustrations-color-purple.png" width= 160px alt="Purple" /> | <img src="img/illustrations-color-grey.png" width= 160px alt="Grey" /> | -| #FC6D26 | #6B4FBB | #EEEEEE | - -#### Don't -- Don't include the typography in the illustration. -- Don't include tanuki in the illustration. If necessary, we recommend having tanuki monochromatic. - +--- +redirect_to: 'https://design.gitlab.com/foundations/illustration/' --- -| Orange | Purple | -| -------- | -------- | -| <img src="img/illustrations-palette-oragne.png" width= 160px alt="Palette - Orange" /> | <img src="img/illustrations-palette-purple.png" width= 160px alt="Palette - Purple" /> | +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md index c59e7b72a1a..1e84bf608f4 100644 --- a/doc/development/ux_guide/index.md +++ b/doc/development/ux_guide/index.md @@ -1,70 +1,5 @@ -> We are in the process of transferring UX documentation to the [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com) project. Any updates to these docs should be made in that project. If documentation does not yet exist within [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com), [create an issue](https://gitlab.com/gitlab-org/design.gitlab.com/issues) and merge request to add your new changes. - -# GitLab UX Guide - -The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions. - -## Design - ---- - -### [Principles](principles.md) -These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created. - ---- - -### [Basics](basics.md) -The basic ingredients of our experience establish our personality and feel. This section includes details about typography, iconography, and color. - --- - -### [Animation](animation.md) -Guidance on the timing, curving and motion for GitLab. - ---- - -### [Illustrations](illustrations.md) -Guidelines for principals and styles related to illustrations for GitLab. - ---- - -### [Copy](copy.md) -Conventions on text and messaging within labels, buttons, and other components. - ---- - -### [Components](components.md) -Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc. - ---- - -### [Surfaces](surfaces.md) -The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc. - ---- - -### [Features](features.md) -The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. - ---- - -## Research - ---- - -### [Users](users.md) -How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc. - ---- - -## Other - ---- - -### [Tips for designers](tips.md) -Tips for exporting assets, and other guidance. - +redirect_to: 'https://design.gitlab.com/' --- -### [Resources](resources.md) -Resources for GitLab UX +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md index 1a297cba2cc..1e84bf608f4 100644 --- a/doc/development/ux_guide/principles.md +++ b/doc/development/ux_guide/principles.md @@ -1,17 +1,5 @@ -# Principles +--- +redirect_to: 'https://design.gitlab.com/' +--- -These are the guiding principles that we should strive for to establish a solid foundation for the GitLab experience. - -## Professional and productive -GitLab is a tool to support what people do, day in, day out. We need to respect the importance of their work, and avoid gimicky details. - -## Minimal and efficient -While work can get complicated, GitLab is about bringing a sharp focus, helping our customers know what matters now. - -## Immediately recognizable -When you look at any screen, you should know immediately that it is GitLab. Our personality is strong and consistent across product and marketing experiences. - -## Human and quirky -We need to build empathy with our users, understanding their state of mind, and connect with them at a human level. Quirkiness is part of our DNA, and we should embrace it in the right moments and contexts. - -> TODO: Ensure these principles align well with the goals of the Marketing team +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md index db57258237f..baec235a8dd 100644 --- a/doc/development/ux_guide/resources.md +++ b/doc/development/ux_guide/resources.md @@ -1,17 +1,5 @@ -# Resources +--- +redirect_to: 'https://design.gitlab.com/resources/design-resources' +--- -## GitLab UI development kit - -We created a page inside GitLab where you can check commonly used html and css elements. - -When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples -you can use during GitLab development. - -## Design repository - -All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design) -repository and maintained by GitLab UX designers. - -## [brand.ai](https://brand.ai/git-lab/primary-brand) - -We are in the process of capturing our UI paradigms on brand.ai, see https://brand.ai/git-lab/primary-brand +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md index 881d6aa4cd6..1e84bf608f4 100644 --- a/doc/development/ux_guide/surfaces.md +++ b/doc/development/ux_guide/surfaces.md @@ -1,47 +1,5 @@ -# Surfaces - -## Contents -* [Header](#header) -* [Global menu](#global-menu) -* [Side pane](#side-pane) -* [Content area](#content-area) - ---- - - - -## Global menu - -This menu is to navigate to pages that contain content global to GitLab. - ---- - -## Header - -The header contains 3 main elements: Project switching and searching, user account avatar and settings, and a contextual menu that changes based on the current page. - - - --- - -## Side pane - -The side pane holds supporting information and meta data for the information in the content area. - +redirect_to: 'https://design.gitlab.com/' --- -## Content area - -The main content of the page. The content area can include other surfaces. - -### Item title bar - -The item title bar contains the top level information to identify the item, such as the name, id and status. - - - -### Item system information - -The system information block contains relevant system controlled information. - - +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md index 8348de4f8a2..1e84bf608f4 100644 --- a/doc/development/ux_guide/tips.md +++ b/doc/development/ux_guide/tips.md @@ -1,44 +1,5 @@ -# Tips - -## Contents -* [SVGs](#svgs) - +--- +redirect_to: 'https://design.gitlab.com/' --- -## SVGs - -When exporting SVGs, be sure to follow the following guidelines: - -1. Convert all strokes to outlines. -2. Use pathfinder tools to combine overlapping paths and create compound paths. -3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. -4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. - -You can open your svg in a text editor to ensure that it is clean. -Incorrect files will look like this: - -```xml -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<svg width="16px" height="17px" viewBox="0 0 16 17" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> - <!-- Generator: Sketch 3.7.2 (28276) - http://www.bohemiancoding.com/sketch --> - <title>Group</title> - <desc>Created with Sketch.</desc> - <defs></defs> - <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> - <g id="Group" fill="#7E7C7C"> - <path d="M15.1111,1 L0.8891,1 C0.3981,1 0.0001,1.446 0.0001,1.996 L0.0001,15.945 C0.0001,16.495 0.3981,16.941 0.8891,16.941 L15.1111,16.941 C15.6021,16.941 16.0001,16.495 16.0001,15.945 L16.0001,1.996 C16.0001,1.446 15.6021,1 15.1111,1 L15.1111,1 L15.1111,1 Z M14.0001,6.0002 L14.0001,14.949 L2.0001,14.949 L2.0001,6.0002 L14.0001,6.0002 Z M14.0001,4.0002 L14.0001,2.993 L2.0001,2.993 L2.0001,4.0002 L14.0001,4.0002 Z" id="Combined-Shape"></path> - <polygon id="Fill-11" points="3 2.0002 5 2.0002 5 0.0002 3 0.0002"></polygon> - <polygon id="Fill-16" points="11 2.0002 13 2.0002 13 0.0002 11 0.0002"></polygon> - <path d="M5.37709616,11.5511984 L6.92309616,12.7821984 C7.35112915,13.123019 7.97359761,13.0565604 8.32002627,12.6330535 L10.7740263,9.63305349 C11.1237073,9.20557058 11.0606364,8.57555475 10.6331535,8.22587373 C10.2056706,7.87619272 9.57565475,7.93926361 9.22597373,8.36674651 L6.77197373,11.3667465 L8.16890384,11.2176016 L6.62290384,9.98660159 C6.19085236,9.6425813 5.56172188,9.71394467 5.21770159,10.1459962 C4.8736813,10.5780476 4.94504467,11.2071781 5.37709616,11.5511984 L5.37709616,11.5511984 Z" id="Stroke-21"></path> - </g> - </g> -</svg> -``` - -Correct file will look like this: - -```xml -<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> -``` - -> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md index 6afb33cfc36..11bac11257c 100644 --- a/doc/development/ux_guide/users.md +++ b/doc/development/ux_guide/users.md @@ -1,310 +1,5 @@ -# UX Personas - -* [Nazim Ramesh](#nazim-ramesh) - - Small to medium size organizations using GitLab CE -* [Matthieu Poirier](#matthieu-poirier) - - Responsible for managing and maintaining GitLab installation - - Any size organization - - Using CE or EE -* [James Mackey](#james-mackey) - - Medium to large size organizations using CE or EE - - Small organizations using EE -* [Karolina Plaskaty](#karolina-plaskaty) - - Using GitLab.com for personal/hobby projects - - Would like to use GitLab at work - - Working within a medium to large size organization - ---- - -## Nazim Ramesh -- Small to medium size organizations using GitLab CE - - - -### Demographics - -**Age** - -32 years old - -**Location** - -Germany - -**Education** - -Bachelor of Science in Computer Science - -**Occupation** - -Full-stack web developer - -**Programming experience** - -Over 10 years - -**Frequently used programming languages** - -JavaScript, SQL, PHP - -**Hobbies / interests** - -Functional programming, open source, gaming, web development, and web security. - -### Motivations -Nazim works for a software development company which currently hires around 80 people. When Nazim first joined the company, the engineering team were using Subversion (SVN) as their primary form of source control. However, Nazim felt SVN was not flexible enough to work with many feature branches and noticed that developers with less experience of source control struggled with the central-repository nature of SVN. Armed with a wish list of features, Nazim began comparing source control tools. A search for "self-hosted Git server repository management" returned GitLab. In his own words, Nazim explains why he wanted the engineering team to start using GitLab: - ->"I wanted them to switch away from SVN. I needed a server application to manage repositories. The common tools that were around just didn't meet the requirements. Most of them were too simple or plain...GitLab provided all the required features. Also, costs had to be low since we don't have a big budget for those things...the Community Edition was perfect in this regard." - -In his role as a full-stack web developer, Nazim could recommend products that he would like the engineering team to use, but final approval lay with his line manager, Mike, VP of Engineering. Nazim recalls that he was met with reluctance from his colleagues when he raised moving to Git and using GitLab. - ->"The biggest challenge...why should we change anything at all from the status quo? We needed to switch from SVN to Git. They knew they needed to learn Git and a Git workflow...using Git was scary to my colleagues...they thought it was more complex than SVN to use." - -Undeterred, Nazim decided to migrate a couple of projects across to GitLab. - ->"Old SVN users couldn't see the benefits of Git at first. It took a month or two to convince them." - -Slowly, by showing his colleagues how easy it was to use Git, the majority of the team's projects were migrated to GitLab. - -The engineering team have been using GitLab CE for around 2 years now. Nazim credits himself as being entirely responsible for his company's decision to move to GitLab. - -### Frustrations -#### Adoption to GitLab has been slow -Not only has the engineering team had to get to grips with Git, they've also had to adapt to using GitLab. Due to lack of training and existing skills in other tools, the full feature set of GitLab CE is not being utilized. Nazim sold GitLab to his manager as an ‘all in one' tool which would replace multiple tools used within the company, thus saving costs. Nazim hasn't had the time to integrate the legacy tools to GitLab and he's struggling to convince his peers to change their habits. - -#### Missing Features -Nazim's company want GitLab to be able to do everything. There isn't a large budget for software, so they're selective about what tools are implemented. It needs to add real value to the company. In order for GitLab to be widely adopted and to meet the requirements of different roles within the company, it needs a host of features. When an individual within Nazim's company wants to know if GitLab has a specific feature or does a particular thing, Nazim is the person to ask. He becomes the point of contact to investigate, build or sometimes just raise the feature request. Nazim gets frustrated when GitLab isn't able to do what he or his colleagues need it to do. - -#### Regressions and bugs -Nazim often has to calm down his colleagues, when a release contains regressions or new bugs. As he puts it "every new version adds something awesome, but breaks something". He feels that "old issues for minor annoyances get quickly buried in the mass of open issues and linger for a very long time. More generally, I have the feeling that GitLab focus on adding new functionalities, but overlook a bunch of annoying minor regressions or introduced bugs." Due to limited resource and expertise within the team, not only is it difficult to remain up-to-date with the frequent release cycle, it's also counterproductive to fix workflows every month. - -#### Uses too much RAM and CPU ->"Memory usages mean that if we host it from a cloud-based host like AWS, we spend almost as much on the instance as what we would pay GitHub" - - -#### UI/UX -GitLab's interface initially attracted Nazim when he was comparing version control software. He thought it would help his less technical colleagues to adapt to using Git and perhaps, GitLab could be rolled out to other areas of the business, beyond engineering. However, using GitLab's interface daily has left him frustrated at the lack of personalization/control over his user experience. He's also regularly lost in a maze of navigation. Whilst he acknowledges that GitLab listens to its users and that the interface is improving, he becomes annoyed when the changes are too progressive. "Too frequent UI changes. Most of them tend to turn out great after a few cycles of fixes, but the frequency is still far too high for me to feel comfortable to always stay on the current release." - -### Goals -* To convince his colleagues to fully adopt GitLab CE, thus improving workflow and collaboration. -* To use a feature-rich version control platform that covers all stages of the development lifecycle, in order to reduce dependencies on other tools. -* To use an intuitive and stable product, so he can spend more time on his core job responsibilities and less time bug-fixing, guiding colleagues, etc. - ---- -## Matthieu Poirier -- Responsible for managing and maintaining GitLab installation -- Any size organization -- Using CE or EE - - - -### Demographics - -**Age** - -42 years old - -**Location** - -France - -**Education** - -Masters Degree in Computer Science - -**Occupation** - -DevOps Engineer - -**Programming experience** - -Over 10 years - -**Frequently used programming languages** - -JavaScript, SQL, PHP and Node.js - -**Hobbies / interests** - -Functional programming, data analysis, building apps, and tools. - -### Motivations -Matthieu works in DevOps for a web services company which currently hires 90 staff. When Matthieu first joined the company, he was responsible for managing a custom built in-house bug tracking tool and release management system. Over time, as the company grew, his colleagues requested more features and tools to help them in their day-to-day work. To meet their needs, Matthieu was forced to "hack together" a solution. In his own words, Matthieu explains that it became: - ->"...a huge pain managing access to all the individual pieces. In addition, they didn't have any integration with each other, nobody ended up using them and we couldn't do any workflows with merge requests and the like. I was sick of managing all those separate parts and wanted to move to a single platform that would handle it all." - - -He further explains that he wanted to introduce "better, easier, more formal code reviews" and to start using continuous integration and deployment. - -Matthieu tried to find a platform which would consolidate the company's existing toolset, and centralize code, documentation, and issues. He discovered GitHub, but the price was an issue: - ->"We needed to host our code on-site and wanted GitHub Enterprise functionality without the GitHub Enterprise costs." - - -Not only was GitLab cheaper than GitHub, it was also more cost-effective than maintaining multiple tools. Subsequently, Matthieu found it easy to sell the merits of GitLab to his manager. - -Matthieu describes GitLab as: - ->"the only tool that offers the real feeling of having everything you need in one place." - - -He credits himself as being entirely responsible for moving his company to GitLab. - -### Frustrations -#### Updating to the latest release -Matthieu introduced his company to GitLab. He is responsible for maintaining and managing the company's installation in addition to his day job. He feels updates are too frequent and he doesn't always have sufficient time to update GitLab. As a result, he's not up to date with releases. - -Matthieu tried to set up automatic updates, however, as he isn't a Systems Administrator, he wasn't confident in his set-up. He feels he should be able to "upgrade without users even noticing" but hasn't figured out how to do this yet. Matthieu would like the "update process to be triggered from the Admin Panel, perhaps accompanied with a changelog and the option to skip updates." - -Matthieu is looking for confirmation that his update procedure is "secure and efficient" so more tutorials related to this topic would be useful to him. - -#### Configuration -Matthieu dislikes using the combination of gitlab.rb and the UI for changing settings. He explains that it "would be nice to be able to configure more from the Admin UI rather than just the config files." - -#### Creating a backup -Matthieu explains that the "backup solution is not well integrated into the UI", for example, he "cannot see if backups succeeded" or whether they have been rolled back to via the UI. - -#### Onboarding -It's Matthieu's responsibility to get teams across his organization up and running with GitLab. He explains that whilst many teams might be leveraging GitLab, they are: - ->"..not aware of GitLab's powerful CI or our omnibus install of Mattermost...It would be nice to have a tutorial type walkthrough available when a new user logs in on how to get started with all these features. AutoDevOps may solve some of this, but GitLab has many powerful features wrapped up into it and some [teams] may just think that it is only a Git repo similar to GitHub." - - -He states that there has been: "a sluggishness of others to adapt" and it's "a low-effort adaptation at that." - -### Goals -* To save time. One of the reasons Matthieu moved his company to GitLab was to reduce the effort it took him to manage and configure multiple tools, thus saving him time. He has to balance his day job in addition to managing the company's GitLab installation and onboarding new teams to GitLab. -* To use a platform which is easy to manage. Matthieu isn't a Systems Administrator, and when updating GitLab, creating backups, etc. He would prefer to work within GitLab's UI. Explanations / guided instructions when configuring settings in GitLab's interface would really help Matthieu. He needs reassurance that what he is about to change is - -1. the right setting -2. will provide him with the desired result he wants. - -* Matthieu needs to educate his colleagues about GitLab. Matthieu's colleagues won't adopt GitLab as they're unaware of its capabilities and the positive impact it could have on their work. Matthieu needs support in getting this message across to them. - --- - -## James Mackey -- Medium to large size organizations using CE or EE -- Small organizations using EE - - - -### Demographics - -**Age** - -36 years old - -**Location** - -US - -**Education** - -Masters degree in Computer Science - -**Occupation** - -Full-stack web developer - -**Programming experience** - -Over 10 years - -**Frequently used programming languages** - -JavaScript, SQL, Node.js, Java, PHP, Python - -**Hobbies / interests** - -DevOps, open source, web development, science, automation, and electronics. - -### Motivations -James works for a research company which currently hires around 800 staff. He began using GitLab.com back in 2013 for his own open source, hobby projects and loved "the simplicity of installation, administration and use". After using GitLab for over a year, he began to wonder about using it at work. James explains: - ->"We first installed the CE edition...on a staging server for a PoC and asked a beta team to use it, specifically for the Merge Request features. Soon other teams began asking us to be beta users too because the team that was already using GitLab was really enjoying it." - - -James and his colleagues also reviewed competitor products including GitHub Enterprise, but they found it "less innovative and with considerable costs...GitLab had the features we wanted at a much lower cost per head than GitHub". - -The company James works for provides employees with a discretionary budget to spend how they want on software, so James and his team decided to upgrade to EE. - -James feels partially responsible for his organization's decision to start using GitLab. - ->"It's still up to the teams themselves [to decide] which tools to use. We just had a great experience moving our daily development to GitLab, so other teams have followed the path or are thinking about switching." - - -### Frustrations -#### Third Party Integration -Some of GitLab EE's features are too basic, in particular, issues boards which do not have the level of reporting that James and his team need. Subsequently, they still need to use GitLab EE in conjunction with other tools, such as JIRA. Whilst James feels it isn't essential for GitLab to meet all his needs (his company are happy for him to use, and pay for, multiple tools), he sometimes isn't sure what is/isn't possible with plugins and what level of custom development he and his team will need to do. - -#### UX/UI -James and his team use CI quite heavily for several projects. Whilst they've welcomed improvements to the builds and pipelines interface, they still have some difficulty following build process on the different tabs under Pipelines. Some confusion has arisen from not knowing where to find different pieces of information or how to get to the next stages logs from the current stage's log output screen. They feel more intuitive linking and flow may alleviate the problem. Generally, they feel GitLab's navigation needs to reviewed and optimized. - -#### Permissions ->"There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for Gitlab CI/build pipelines." - - -### Goals -* To be able to integrate third-party tools easily with GitLab EE and to create custom integrations and patches where needed. -* To use GitLab EE primarily for code hosting, merge requests, continuous integration and issue management. James and his team want to be able to understand and use these particular features easily. -* To able to share one instance of GitLab EE with multiple teams across the business. Advanced user management, the ability to separate permissions on different parts of the source code, etc are important to James. - +redirect_to: 'https://design.gitlab.com/getting-started/personas/' --- -## Karolina Plaskaty -- Using GitLab.com for personal/hobby projects -- Would like to use GitLab at work -- Working within a medium to large size organization - - - -### Demographics - -**Age** - -26 years old - -**Location** - -UK - -**Education** - -Self taught - -**Occupation** - -Junior web-developer - -**Programming experience** - -6 years - -**Frequently used programming languages** - -JavaScript and SQL - -**Hobbies / interests** - -Web development, mobile development, UX, open source, gaming, and travel. - -### Motivations -Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab's values and the fact that it isn't a "behemoth of a company". She explains that "displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose Gitlab personally and to recommend it at work." She's also an avid reader of GitLab's blog. - -Karolina works for a software development company which currently hires around 500 people. Karolina would love to use GitLab at work but the company has used GitHub Enterprise for a number of years. She describes management at her company as "old fashioned" and explains that it's "less of a technical issue and more of a cultural issue" to convince upper management to move to GitLab. Karolina is also relatively new to the company so she's apprehensive about pushing too hard to change version control platforms. - -### Frustrations -#### Unable to use GitLab at work -Karolina wants to use GitLab at work but isn't sure how to approach the subject with management. In her current role, she doesn't feel that she has the authority to request GitLab. - -#### Performance -GitLab.com is frequently slow and unavailable. Karolina has also heard that GitLab is a "memory hog" which has deterred her from running GitLab on her own machine for just hobby / personal projects. - -#### UX/UI -Karolina has an interest in UX and therefore has strong opinions about how GitLab should look and feel. She feels the interface is cluttered, "it has too many links/buttons" and the navigation "feels a bit weird sometimes. I get lost if I don't pay attention." As Karolina also enjoys contributing to open-source projects, it's important to her that GitLab is well designed for public repositories, she doesn't feel that GitLab currently achieves this. - -### Goals -* To develop her programming experience and to learn from other developers. -* To contribute to both her own and other open source projects. -* To use a fast and intuitive version control platform.
\ No newline at end of file +The content of this document was moved into the [GitLab Design System](https://design.gitlab.com/). diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index b668c9de6a0..3630a28fae9 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -300,7 +300,7 @@ The same applies to `rename_column_using_background_migration`: 1. Create a migration using the helper, which will schedule background migrations to spread the writes over a longer period of time. -2. In the next monthly release, create a clean-up migration to steal from the +1. In the next monthly release, create a clean-up migration to steal from the Sidekiq queues, migrate any missing rows, and cleanup the rename. This migration should skip the steps after stealing from the Sidekiq queues if the column has already been renamed. diff --git a/doc/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md index 1a44123aa81..17c210c43e0 100644 --- a/doc/gitlab-basics/add-image.md +++ b/doc/gitlab-basics/add-image.md @@ -5,7 +5,7 @@ in Windows, or...), put the image file into the GitLab project. You can find the project as a regular folder in your files. Go to your [shell](command-line-commands.md), and move into the folder of your -Gitlab project. This usually means running the following command until you get +GitLab project. This usually means running the following command until you get to the desired destination: ``` diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index b6ebe374de3..881629c3bfd 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -12,7 +12,7 @@  -3. Paste your **public** key that you generated in the first step in the 'Key' +1. Paste your **public** key that you generated in the first step in the 'Key' box.  diff --git a/doc/img/devops-stages.png b/doc/img/devops-stages.png Binary files differnew file mode 100644 index 00000000000..a971e81a419 --- /dev/null +++ b/doc/img/devops-stages.png diff --git a/doc/img/devops_lifecycle.png b/doc/img/devops_lifecycle.png Binary files differdeleted file mode 100644 index 0b15e9619a5..00000000000 --- a/doc/img/devops_lifecycle.png +++ /dev/null diff --git a/doc/install/README.md b/doc/install/README.md index 27df03c6ac6..92116305775 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -34,11 +34,11 @@ the hardware requirements. - [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md) - [Install GitLab on Google Kubernetes Engine (GKE)](https://about.gitlab.com/2017/01/23/video-tutorial-idea-to-production-on-google-container-engine-gke/): video tutorial on the full process of installing GitLab on Google Kubernetes Engine (GKE), pushing an application to GitLab, building the app with GitLab CI/CD, and deploying to production. -- [Install on AWS](https://about.gitlab.com/aws/) -- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) - - Quickly test any version of GitLab on DigitalOcean using Docker Machine. +- [Install on AWS](aws/index.md): Install GitLab on AWS using the community AMIs that GitLab provides. - [Getting started with GitLab and DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): requirements, installation process, updates. - [Demo: Cloud Native Development with GitLab](https://about.gitlab.com/2017/04/18/cloud-native-demo/): video demonstration on how to install GitLab on Kubernetes, build a project, create Review Apps, store Docker images in Container Registry, deploy to production on Kubernetes, and monitor with Prometheus. +- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) - + Quickly test any version of GitLab on DigitalOcean using Docker Machine. ## Database diff --git a/doc/install/aws/img/add_tags.png b/doc/install/aws/img/add_tags.png Binary files differnew file mode 100644 index 00000000000..3572cd5daa1 --- /dev/null +++ b/doc/install/aws/img/add_tags.png diff --git a/doc/install/aws/img/associate_subnet_gateway.png b/doc/install/aws/img/associate_subnet_gateway.png Binary files differnew file mode 100644 index 00000000000..1edca974fca --- /dev/null +++ b/doc/install/aws/img/associate_subnet_gateway.png diff --git a/doc/install/aws/img/associate_subnet_gateway_2.png b/doc/install/aws/img/associate_subnet_gateway_2.png Binary files differnew file mode 100644 index 00000000000..76e101d32a3 --- /dev/null +++ b/doc/install/aws/img/associate_subnet_gateway_2.png diff --git a/doc/install/aws/img/aws_diagram.png b/doc/install/aws/img/aws_diagram.png Binary files differnew file mode 100644 index 00000000000..bcd5c69bbeb --- /dev/null +++ b/doc/install/aws/img/aws_diagram.png diff --git a/doc/install/aws/img/choose_ami.png b/doc/install/aws/img/choose_ami.png Binary files differnew file mode 100644 index 00000000000..034ac92691d --- /dev/null +++ b/doc/install/aws/img/choose_ami.png diff --git a/doc/install/aws/img/create_gateway.png b/doc/install/aws/img/create_gateway.png Binary files differnew file mode 100644 index 00000000000..9408520e050 --- /dev/null +++ b/doc/install/aws/img/create_gateway.png diff --git a/doc/install/aws/img/create_route_table.png b/doc/install/aws/img/create_route_table.png Binary files differnew file mode 100644 index 00000000000..ea72c57257e --- /dev/null +++ b/doc/install/aws/img/create_route_table.png diff --git a/doc/install/aws/img/create_security_group.png b/doc/install/aws/img/create_security_group.png Binary files differnew file mode 100644 index 00000000000..9a0dfccfe37 --- /dev/null +++ b/doc/install/aws/img/create_security_group.png diff --git a/doc/install/aws/img/create_subnet.png b/doc/install/aws/img/create_subnet.png Binary files differnew file mode 100644 index 00000000000..26f5ab1b625 --- /dev/null +++ b/doc/install/aws/img/create_subnet.png diff --git a/doc/install/aws/img/create_vpc.png b/doc/install/aws/img/create_vpc.png Binary files differnew file mode 100644 index 00000000000..a678f7013fd --- /dev/null +++ b/doc/install/aws/img/create_vpc.png diff --git a/doc/install/aws/img/ec_az.png b/doc/install/aws/img/ec_az.png Binary files differnew file mode 100644 index 00000000000..22a8291c593 --- /dev/null +++ b/doc/install/aws/img/ec_az.png diff --git a/doc/install/aws/img/ec_subnet.png b/doc/install/aws/img/ec_subnet.png Binary files differnew file mode 100644 index 00000000000..c44fb4485e3 --- /dev/null +++ b/doc/install/aws/img/ec_subnet.png diff --git a/doc/install/aws/img/policies.png b/doc/install/aws/img/policies.png Binary files differnew file mode 100644 index 00000000000..e99497a52a2 --- /dev/null +++ b/doc/install/aws/img/policies.png diff --git a/doc/install/aws/img/rds_subnet_group.png b/doc/install/aws/img/rds_subnet_group.png Binary files differnew file mode 100644 index 00000000000..7c6157e38e0 --- /dev/null +++ b/doc/install/aws/img/rds_subnet_group.png diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md new file mode 100644 index 00000000000..ce61ace60a0 --- /dev/null +++ b/doc/install/aws/index.md @@ -0,0 +1,655 @@ +# Installing GitLab on Amazon Web Services (AWS) + +To install GitLab on AWS, you can use the Amazon Machine Images (AMIs) that GitLab +provides with [each release](https://about.gitlab.com/releases/). + +This page offers a walkthrough of a common HA (Highly Available) configuration +for GitLab on AWS. You should customize it to accommodate your needs. + +## Introduction + +GitLab on AWS can leverage many of the services that are already +configurable with GitLab High Availability (HA). These services offer a great deal of +flexibility and can be adapted to the needs of most companies, while enabling the +automation of both vertical and horizontal scaling. + +In this guide, we'll go through a basic HA setup where we'll start by +configuring our Virtual Private Cloud and subnets to later integrate +services such as RDS for our database server and ElastiCache as a Redis +cluster to finally manage them within an auto scaling group with custom +scaling policies. + +## Requirements + +In addition to having a basic familiarity with [AWS](https://docs.aws.amazon.com/) and [Amazon EC2](https://docs.aws.amazon.com/ec2/), you will need: + +- [An AWS account](https://console.aws.amazon.com/console/home) +- [To create or upload an SSH key](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) + to connect to the instance via SSH +- A domain name for the GitLab instance + +## Architecture + +Below is a diagram of the recommended architecture. + + + +## AWS costs + +Here's a list of the AWS services we will use, with links to pricing information: + +- **EC2**: GitLab will deployed on shared hardware which means + [on-demand pricing](https://aws.amazon.com/ec2/pricing/on-demand) + will apply. If you want to run it on a dedicated or reserved instance, + consult the [EC2 pricing page](https://aws.amazon.com/ec2/pricing/) for more + information on the cost. +- **EBS**: We will also use an EBS volume to store the Git data. See the + [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). +- **S3**: We will use S3 to store backups, artifacts, LFS objects, etc. See the + [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/). +- **ALB**: An Application Load Balancer will be used to route requests to the + GitLab instance. See the [Amazon ELB pricing](https://aws.amazon.com/elasticloadbalancing/pricing/). +- **RDS**: An Amazon Relational Database Service using PostgreSQL will be used + to provide a High Availability database configuration. See the + [Amazon RDS pricing](https://aws.amazon.com/rds/postgresql/pricing/). +- **ElastiCache**: An in-memory cache environment will be used to provide a + High Availability Redis configuration. See the + [Amazon ElastiCache pricing](https://aws.amazon.com/elasticache/pricing/). + +## Creating an IAM EC2 instance role and profile +To minimize the permissions of the user, we'll create a new [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) +role with limited access: + +1. Navigate to the IAM dashboard https://console.aws.amazon.com/iam/home and + click **Create role**. +1. Create a new role by selecting **AWS service > EC2**, then click + **Next: Permissions**. +1. Choose **AmazonEC2FullAccess** and **AmazonS3FullAccess**, then click **Next: Review**. +1. Give the role the name `GitLabAdmin` and click **Create role**. + +## Configuring the network + +We'll start by creating a VPC for our GitLab cloud infrastructure, then +we can create subnets to have public and private instances in at least +two [Availability Zones (AZs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html). Public subnets will require a Route Table keep and an associated +Internet Gateway. + +### Creating the Virtual Private Cloud (VPC) + +We'll now create a VPC, a virtual networking environment that you'll control: + +1. Navigate to https://console.aws.amazon.com/vpc/home. +1. Select **Your VPCs** from the left menu and then click **Create VPC**. + At the "Name tag" enter `gitlab-vpc` and at the "IPv4 CIDR block" enter + `10.0.0.0/16`. If you don't require dedicated hardware, you can leave + "Tenancy" as default. Click **Yes, Create** when ready. + +  + +### Subnets + +Now, let's create some subnets in different Availability Zones. Make sure +that each subnet is associated to the VPC we just created and +that CIDR blocks don't overlap. This will also +allow us to enable multi AZ for redundancy. + +We will create private and public subnets to match load balancers and +RDS instances as well: + +1. Select **Subnets** from the left menu. +1. Click **Create subnet**. Give it a descriptive name tag based on the IP, + for example `gitlab-public-10.0.0.0`, select the VPC we created previously, + and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`: + +  + +1. Follow the same steps to create all subnets: + + | Name tag | Type |Availability Zone | CIDR block | + | -------- | ---- | ---------------- | ---------- | + | gitlab-public-10.0.0.0 | public | us-west-2a | 10.0.0.0 | + | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 | + | gitlab-public-10.0.2.0 | public | us-west-2b | 10.0.2.0 | + | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 | + +### Route Table + +Up to now all our subnets are private. We need to create a Route Table +to associate an Internet Gateway. On the same VPC dashboard: + +1. Select **Route Tables** from the left menu. +1. Click **Create Route Table**. +1. At the "Name tag" enter `gitlab-public` and choose `gitlab-vpc` under "VPC". +1. Hit **Yes, Create**. + +### Internet Gateway + +Now, still on the same dashboard, go to Internet Gateways and +create a new one: + +1. Select **Internet Gateways** from the left menu. +1. Click **Create internet gateway**, give it the name `gitlab-gateway` and + click **Create**. +1. Select it from the table, and then under the **Actions** dropdown choose + "Attach to VPC". + +  + +1. Choose `gitlab-vpc` from the list and hit **Attach**. + +### Configuring subnets + +We now need to add a new target which will be our Internet Gateway and have +it receive traffic from any destination. + +1. Select **Route Tables** from the left menu and select the `gitlab-public` + route to show the options at the bottom. +1. Select the **Routes** tab, hit **Edit > Add another route** and set `0.0.0.0/0` + as destination. In the target, select the `gitlab-gateway` we created previously. + Hit **Save** once done. + +  + +Next, we must associate the **public** subnets to the route table: + +1. Select the **Subnet Associations** tab and hit **Edit**. +1. Check only the public subnet and hit **Save**. + +  + +--- + +Now that we're done with the network, let's create a security group. + +## Creating a security group + +The security group is basically the firewall: + +1. Select **Security Groups** from the left menu. +1. Click **Create Security Group** and fill in the details. Give it a name, + add a description, and choose the VPC we created previously +1. Select the security group from the list and at the bottom select the + Inbound Rules tab. You will need to open the SSH, HTTP, and HTTPS ports. Set + the source to `0.0.0.0/0`. + +  + + TIP: **Tip:** + Based on best practices, you should allow SSH traffic from only a known + host or CIDR block. In that case, change the SSH source to be custom and give + it the IP you want to SSH from. + +1. When done, click **Save**. + +## PostgreSQL with RDS + +For our database server we will use Amazon RDS which offers Multi AZ +for redundancy. Let's start by creating a subnet group and then we'll +create the actual RDS instance. + +### RDS Subnet Group + +1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu. +1. Give it a name (`gitlab-rds-group`), a description, and choose the VPC from + the VPC dropdown. +1. Click "Add all the subnets related to this VPC" and + remove the public ones, we only want the **private subnets**. + In the end, you should see `10.0.1.0/24` and `10.0.3.0/24` (as + we defined them in the [subnets section](#subnets)). + Click **Create** when ready. + +  + +### Creating the database + +Now, it's time to create the database: + +1. Select **Instances** from the left menu and click **Create database**. +1. Select PostgreSQL and click **Next**. +1. Since this is a production server, let's choose "Production". Click **Next**. +1. Let's see the instance specifications: + 1. Leave the license model as is (`postgresql-license`). + 1. For the version, select the latest of the 9.6 series (check the + [database requirements](../../install/requirements.md#postgresql-requirements)) + if there are any updates on this). + 1. For the size, let's select a `t2.medium` instance. + 1. Multi-AZ-deployment is recommended as redundancy, so choose "Create + replica in different zone". Read more at + [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). + 1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can + choose a General Purpose (SSD) to reduce the costs). Read more about it at + [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). + +1. The rest of the settings on this page request a DB isntance identifier, username + and a master password. We've chosen to use `gitlab-db-ha`, `gitlab` and a + very secure password respectively. Keep these in hand for later. +1. Click **Next** to proceed to the advanced settings. +1. Make sure to choose our gitlab VPC, our subnet group, set public accessibility to + **No**, and to leave it to create a new security group. The only additional + change which will be helpful is the database name for which we can use + `gitlabhq_production`. At the very bottom, there's an option to enable + auto updates to minor versions. You may want to turn it off. +1. When done, click **Create database**. + +### Installing the `pg_trgm` extension for PostgreSQL + +Once the database is created, connect to your new RDS instance to verify access +and to install a required extension. + +You can find the host or endpoint by selecting the instance you just created and +after the details drop down you'll find it labeled as 'Endpoint'. Do not to +include the colon and port number: + +```sh +sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production +``` + +At the psql prompt create the extension and then quit the session: + +```sh +psql (9.4.7) +Type "help" for help. + +gitlab=# CREATE EXTENSION pg_trgm; +gitlab=# \q +``` + +--- + +Now that the database is created, let's move on setting up Redis with ElasticCache. + +## Redis with ElastiCache + +ElastiCache is an in-memory hosted caching solution. Redis maintains its own +persistence and is used for certain types of the GitLab application. + +To set up Redis: + +1. Navigate to the ElastiCache dashboard from your AWS console. +1. Go to **Subnet Groups** in the left menu, and create a new subnet group. + Make sure to select our VPC and its [private subnets](#subnets). Click + **Create** when ready. + +  + +1. Select **Redis** on the left menu and click **Create** to create a new + Redis cluster. Depending on your load, you can choose whether to enable + cluster mode or not. Even without cluster mode on, you still get the + chance to deploy Redis in multi availability zones. In this guide, we chose + not to enable it. +1. In the settings section: + 1. Give the cluster a name (`gitlab-redis`) and a description. + 1. For the version, select the latest of `3.2` series (e.g., `3.2.10`). + 1. Select the node type and the number of replicas. +1. In the advanced settings section: + 1. Select the multi-AZ auto-failover option. + 1. Select the subnet group we created previously. + 1. Manually select the preferred availability zones, and under "Replica 2" + choose a different zone than the other two. + +  + +1. In the security settings, edit the security groups and choose the + `gitlab-security-group` we had previously created. +1. Leave the rest of the settings to their default values or edit to your liking. +1. When done, click **Create**. + +## RDS and Redis Security Group + +Let's navigate to our EC2 security groups and add a small change for our EC2 +instances to be able to connect to RDS. First, copy the security group name we +defined, namely `gitlab-security-group`, select the RDS security group and edit the +inbound rules. Choose the rule type to be PostgreSQL and paste the name under +source. + +Similar to the above, jump to the `gitlab-security-group` group +and add a custom TCP rule for port `6379` accessible within itself. + +## Load Balancer + +On the EC2 dashboard, look for Load Balancer on the left column: + +1. Click the **Create Load Balancer** button. + 1. Choose the Application Load Balancer. + 1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing". + 1. In the "Listeners" section, make sure it has HTTP and HTTPS. + 1. In the "Availability Zones" section, select the `gitlab-vpc` we have created + and associate the **public subnets**. +1. Click **Configure Security Settings** to go to the next section to + select the TLS certificate. When done, go to the next step. +1. In the "Security Groups" section, create a new one by giving it a name + (`gitlab-loadbalancer-sec-group`) and allow both HTTP ad HTTPS traffic + from anywhere (`0.0.0.0/0, ::/0`). +1. In the next step, configure the routing and select an existing target group + (`gitlab-public`). The Load Balancer Health will allow us to indicate where to + ping and what makes up a healthy or unhealthy instance. +1. Leave the "Register Targets" section as is, and finally review the settings + and create the ELB. + +After the Load Balancer is up and running, you can revisit your Security +Groups to refine the access only through the ELB and any other requirement +you might have. + +## Deploying GitLab inside an auto scaling group + +We'll use AWS's wizard to deploy GitLab and then SSH into the instance to +configure the PostgreSQL and Redis connections. + +The Auto Scaling Group option is available through the EC2 dashboard on the left +sidebar. + +1. Click **Create Auto Scaling group**. +1. Create a new launch configuration. + +### Choose the AMI + +Choose the AMI: + +1. Go to the Community AMIs and search for `GitLab EE <version>` + where `<version>` the latest version as seen on the + [releases page](https://about.gitlab.com/releases/). + +  + +### Choose an instance type + +You should choose an instance type based on your workload. Consult +[the hardware requirements](../requirements.md#hardware-requirements) to choose +one that fits your needs (at least `c4.xlarge`, which is enough to accommodate 100 users): + +1. Choose the your instance type. +1. Click **Next: Configure Instance Details**. + +### Configure details + +In this step we'll configure some details: + +1. Enter a name (`gitlab-autoscaling`). +1. Select the IAM role we created. +1. Optionally, enable CloudWatch and the EBS-optimized instance settings. +1. In the "Advanced Details" section, set the IP address type to + "Do not assign a public IP address to any instances." +1. Click **Next: Add Storage**. + +### Add storage + +The root volume is 8GB by default and should be enough given that we won't store +any data there. Let's create a new EBS volume that will host the Git data. Its +size depends on your needs and you can always migrate to a bigger volume later. +You will be able to [set up that volume](#setting-up-the-ebs-volume) +after the instance is created. + +### Configure security group + +As a last step, configure the security group: + +1. Select the existing load balancer security group we have [created](#load-balancer). +1. Select **Review**. + +### Review and launch + +Now is a good time to review all the previous settings. When ready, click +**Create launch configuration** and select the SSH key pair with which you will +connect to the instance. + +### Create Auto Scaling Group + +We are now able to start creating our Auto Scaling Group: + +1. Give it a group name. +1. Set the group size to 2 as we want to always start with two instances. +1. Assign it our network VPC and add the **private subnets**. +1. In the "Advanced Details" section, choose to receive traffic from ELBs + and select our ELB. +1. Choose the ELB health check. +1. Click **Next: Configure scaling policies**. + +This is the really great part of Auto Scaling; we get to choose when AWS +launches new instances and when it removes them. For this group we'll +scale between 2 and 4 instances where one instance will be added if CPU +utilization is greater than 60% and one instance is removed if it falls +to less than 45%. + + + +Finally, configure notifications and tags as you see fit, and create the +auto scaling group. + +You'll notice that after we save the configuration, AWS starts launching our two +instances in different AZs and without a public IP which is exactly what +we intended. + +## After deployment + +After a few minutes, the instances should be up and accessible via the internet. +Let's connect to the primary and configure some things before logging in. + +### Configuring GitLab to connect with postgres and Redis + +While connected to your server, let's connect to the RDS instance to verify +access and to install a required extension: + +```sh +sudo /opt/gitlab/embedded/bin/psql -U gitlab -h <rds-endpoint> -d gitlabhq_production +``` + +Edit the `gitlab.rb` file at `/etc/gitlab/gitlab.rb` +find the `external_url 'http://gitlab.example.com'` option and change it +to the domain you will be using or the public IP address of the current +instance to test the configuration. + +For a more detailed description about configuring GitLab, see [Configuring GitLab for HA](../../administration/high_availability/gitlab.md) + +Now look for the GitLab database settings and uncomment as necessary. In +our current case we'll specify the database adapter, encoding, host, name, +username, and password: + +```ruby +# Disable the built-in Postgres +postgresql['enable'] = false + +# Fill in the connection details +gitlab_rails['db_adapter'] = "postgresql" +gitlab_rails['db_encoding'] = "unicode" +gitlab_rails['db_database'] = "gitlabhq_production" +gitlab_rails['db_username'] = "gitlab" +gitlab_rails['db_password'] = "mypassword" +gitlab_rails['db_host'] = "<rds-endpoint>" +``` + +Next, we need to configure the Redis section by adding the host and +uncommenting the port: + +```ruby +# Disable the built-in Redis +redis['enable'] = false + +# Fill in the connection details +gitlab_rails['redis_host'] = "<redis-endpoint>" +gitlab_rails['redis_port'] = 6379 +``` + +Finally, reconfigure GitLab for the change to take effect: + + +```sh +sudo gitlab-ctl reconfigure +``` + +You might also find it useful to run a check and a service status to make sure +everything has been setup correctly: + +```sh +sudo gitlab-rake gitlab:check +sudo gitlab-ctl status +``` + +If everything looks good, you should be able to reach GitLab in your browser. + +### Setting up the EBS volume + +The EBS volume will host the Git repositories data: + +1. First, format the `/dev/xvdb` volume and then mount it under the directory + where the data will be stored. For example, `/mnt/gitlab-data/`. +1. Tell GitLab to store its data in the new directory by editing + `/etc/gitlab/gitlab.rb` with your editor: + + ```ruby + git_data_dirs({ + "default" => { "path" => "/mnt/gitlab-data" } + }) + ``` + + where `/mnt/gitlab-data` the location where you will store the Git data. + +1. Save the file and reconfigure GitLab: + + ```sh + sudo gitlab-ctl reconfigure + ``` + +TIP: **Tip:** +If you wish to add more than one data volumes to store the Git repositories, +read the [repository storage paths docs](../../administration/repository_storage_paths.md). + +### Setting up Gitaly + +Gitaly is a service that provides high-level RPC access to Git repositories. +It should be enabled and configured in a separate EC2 instance on the +[private VPC](#subnets) we configured previously. + +Follow the [documentation to set up Gitaly](../../administration/gitaly/index.md). + +### Using Amazon S3 object storage + +GitLab stores many objects outside the Git repository, many of which can be +uploaded to S3. That way, you can offload the root disk volume of these objects +which would otherwise take much space. + +In particular, you can store in S3: + +- [The Git LFS objects](../../workflow/lfs/lfs_administration.md#s3-for-omnibus-installations) ((Omnibus GitLab installations)) +- [The Container Registry images](../../administration/container_registry.md#container-registry-storage-driver) (Omnibus GitLab installations) +- [The GitLab CI/CD job artifacts](../../administration/job_artifacts.md#using-object-storage) (Omnibus GitLab installations) + +### Setting up a domain name + +After you SSH into the instance, configure the domain name: + +1. Open `/etc/gitlab/gitlab.rb` with your preferred editor. +1. Edit the `external_url` value: + + ```ruby + external_url 'http://example.com' + ``` + +1. Reconfigure GitLab: + + ```sh + sudo gitlab-ctl reconfigure + ``` + +You should now be able to reach GitLab at the URL you defined. To use HTTPS +(recommended), see the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). + +### Logging in for the first time + +If you followed the previous section, you should be now able to visit GitLab +in your browser. The very first time, you will be asked to set up a password +for the `root` user which has admin privileges on the GitLab instance. + +After you set it up, login with username `root` and the newly created password. + +## Health check and monitoring with Prometheus + +Apart from Amazon's Cloudwatch which you can enable on various services, +GitLab provides its own integrated monitoring solution based on Prometheus. +For more information on how to set it up, visit the +[GitLab Prometheus documentation](../../administration/monitoring/prometheus/index.md) + +GitLab also has various [health check endpoints](../..//user/admin_area/monitoring/health_check.md) +that you can ping and get reports. + +## GitLab Runners + +If you want to take advantage of [GitLab CI/CD](../../ci/README.md), you have to +set up at least one [GitLab Runner](https://docs.gitlab.com/runner/). + +Read more on configuring an +[autoscaling GitLab Runner on AWS](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/). + +## Backup and restore + +GitLab provides [a tool to backup](../../raketasks/backup_restore.md#creating-a-backup-of-the-gitlab-system) +and restore its Git data, database, attachments, LFS objects, etc. + +Some important things to know: + +- The backup/restore tool **does not** store some configuration files, like secrets; you'll + need to [configure this yourself](../../raketasks/backup_restore.md#storing-configuration-files). +- By default, the backup files are stored locally, but you can + [backup GitLab using S3](../../raketasks/backup_restore.md#using-amazon-s3). +- You can [exclude specific directories form the backup](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). + +### Backing up GitLab + +To back up GitLab: + +1. SSH into your instance. +1. Take a backup: + + ```sh + sudo gitlab-rake gitlab:backup:create + ``` + +### Restoring GitLab from a backup + +To restore GitLab, first review the [restore documentation](../../raketasks/backup_restore.md#restore), +and primarily the restore prerequisites. Then, follow the steps under the +[Omnibus installations section](../../raketasks/backup_restore.md#restore-for-omnibus-installations). + +## Updating GitLab + +GitLab releases a new version every month on the 22nd. Whenever a new version is +released, you can update your GitLab instance: + +1. SSH into your instance +1. Take a backup: + + ```sh + sudo gitlab-rake gitlab:backup:create + ``` + +1. Update the repositories and install GitLab: + + ```sh + sudo apt update + sudo apt install gitlab-ee + ``` + +After a few minutes, the new version should be up and running. + +## Conclusion + +In this guide, we went mostly through scaling and some redundancy options, +your mileage may vary. + +Keep in mind that all Highly Available solutions come with a trade-off between +cost/complexity and uptime. The more uptime you want, the more complex the solution. +And the more complex the solution, the more work is involved in setting up and +maintaining it. + +Have a read through these other resources and feel free to +[open an issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/new) +to request additional material: + +- [GitLab High Availability](https://docs.gitlab.com/ee/administration/high_availability/): + GitLab supports several different types of clustering and high-availability. +- [Geo replication](https://docs.gitlab.com/ee/administration/geo/replication/): + Geo is the solution for widely distributed development teams. +- [Omnibus GitLab](https://docs.gitlab.com/omnibus/) - Everything you need to know + about administering your GitLab instance. +- [Upload a license](https://docs.gitlab.com/ee/user/admin_area/license.html): + Activate all GitLab Enterprise Edition functionality with a license. +- [Pricing](https://about.gitlab.com/pricing): Pricing for the different tiers. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 570bd18c172..19a6e46f969 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -37,7 +37,7 @@ Once you have an Azure account, you can get started. Login to Azure using  -The Dashboard gives you a quick overview of Azure resources, and from here you you can build VMs, +The Dashboard gives you a quick overview of Azure resources, and from here you can build VMs, create SQL Databases, author websites, and perform lots of other cloud tasks. ## Create New VM @@ -74,7 +74,7 @@ The first items we need to configure are the basic settings of the underlying vi > **Note:** if you're unsure which authentication type to use, select **Password** 1. If you chose **SSH public key** - enter your `SSH public key` into the field provided - _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to setup SSH + _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to set up SSH public keys)_ 1. If you chose **Password** - enter the password you wish to use _(this is the password that you will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_ @@ -154,7 +154,7 @@ on the Azure Dashboard (you may need to refresh the page): The new VM can also be accessed by clicking the `All resources` or `Virtual machines` icons in the Azure Portal sidebar navigation menu. -## Setup a domain name +## Set up a domain name The VM will have a public IP address (static by default), but Azure allows us to assign a friendly DNS name to the VM, so let's go ahead and do that. @@ -296,7 +296,7 @@ homepage for the project:  If you scroll further down the project's home page, you'll see some basic instructions on how to -setup a local clone of your new repository and push and pull from it: +set up a local clone of your new repository and push and pull from it:  @@ -347,7 +347,7 @@ If you're running [SSH] from the command-line (terminal), then type in the follo connect to your VM, substituting `username` and `your-azure-domain-name.com` for the correct values. Again, remember that your Azure VM domain name will be the one you -[setup previously in the tutorial](#set-up-a-domain-name). If you didn't setup a domain name for +[set up previously in the tutorial](#set-up-a-domain-name). If you didn't set up a domain name for your VM, you can use the IP address in its place in the following command: ```bash @@ -401,7 +401,7 @@ is now showing **"up-to-date"**: Naturally, we believe that GitLab is a great git repository tool. However, GitLab is a whole lot more than that too. GitLab unifies issues, code review, CI and CD into a single UI, helping you to move faster from idea to production, and in this tutorial we showed you how quick and easy it is to -setup and run your own instance of GitLab on Azure, Microsoft's cloud service. +set up and run your own instance of GitLab on Azure, Microsoft's cloud service. Azure is a great way to experiment with GitLab, and if you decide (as we hope) that GitLab is for you, you can continue to use Azure as your secure, scalable cloud provider or of course run GitLab @@ -424,7 +424,7 @@ Check out our other [Technical Articles][GitLab-Technical-Articles] or browse th - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM] - [SSH], [PuTTY] and [Using SSH in PuTTY][Using-SSH-In-Putty] -[Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Setup a GitLab Instance on Microsoft Azure" +[Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Set up a GitLab Instance on Microsoft Azure" [GitLab-Docs]: https://docs.gitlab.com/ce/README.html "GitLab Documentation" [GitLab-Technical-Articles]: https://docs.gitlab.com/ce/articles/index.html "GitLab Technical Articles" [GitLab-Docs-SSH]: https://docs.gitlab.com/ce/ssh/README.html "GitLab Documentation: SSH" diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md index 4cf18f53239..e89846107b6 100644 --- a/doc/install/database_mysql.md +++ b/doc/install/database_mysql.md @@ -1,15 +1,20 @@ # Database MySQL -> **Note:** -> - We do not recommend using MySQL due to various issues. For example, case - [(in)sensitivity](https://dev.mysql.com/doc/refman/5.0/en/case-sensitivity.html) - and [problems](https://bugs.mysql.com/bug.php?id=65830) that - [suggested](https://bugs.mysql.com/bug.php?id=50909) - [fixes](https://bugs.mysql.com/bug.php?id=65830) [have](https://bugs.mysql.com/bug.php?id=63164). +NOTE: **Note:** +We do not recommend using MySQL due to various issues. +For example, there have been bugs with case +[(in)sensitivity](https://dev.mysql.com/doc/refman/5.7/en/case-sensitivity.html). + +Bugs relating to case sensitivity: + +- <https://bugs.mysql.com/bug.php?id=65830> +- <https://bugs.mysql.com/bug.php?id=50909> +- <https://bugs.mysql.com/bug.php?id=65830> +- <https://bugs.mysql.com/bug.php?id=63164> ## Initial database setup -``` +```sh # Install the database packages sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev @@ -79,19 +84,20 @@ After installation or upgrade, remember to [convert any new tables](#tables-and- --- -GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have setup your database before GitLab 8.16. +GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have set up your database before GitLab 8.16. Follow the below instructions to ensure you use the most up to date requirements for your GitLab MySQL Database. **We are about to do the following:** + - Ensure you can enable `utf8mb4` encoding and `utf8mb4_general_ci` collation for your GitLab DB, tables and data. -- Convert your GitLab tables and data from `utf8`/`utf8_general_ci` to `utf8mb4`/`utf8mb4_general_ci` +- Convert your GitLab tables and data from `utf8`/`utf8_general_ci` to `utf8mb4`/`utf8mb4_general_ci`. ### Check for utf8mb4 support #### Check for InnoDB File-Per-Table Tablespaces -We need to check, enable and maybe convert your existing GitLab DB tables to the [InnoDB File-Per-Table Tablespaces](http://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) as a prerequisite for supporting **utfb8mb4 with long indexes** required by recent GitLab databases. +We need to check, enable and maybe convert your existing GitLab DB tables to the [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) as a prerequisite for supporting **utfb8mb4 with long indexes** required by recent GitLab databases. # Login to MySQL mysql -u root -p @@ -128,9 +134,10 @@ We need to check, enable and maybe convert your existing GitLab DB tables to the > You need **MySQL 5.5.3 or later** to perform this update. -Whatever the results of your checks above, we now need to check if your GitLab database has been created using [InnoDB File-Per-Table Tablespaces](http://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) (i.e. `innodb_file_per_table` was set to **1** at initial setup time). +Whatever the results of your checks above, we now need to check if your GitLab database has been created using [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) (i.e. `innodb_file_per_table` was set to **1** at initial setup time). -> Note: This setting is [enabled by default](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table) since MySQL 5.6.6. +NOTE: **Note:** +This setting is [enabled by default](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table) since MySQL 5.6.6. # Run this command with root privileges, replace the data dir if different: sudo ls -lh /var/lib/mysql/gitlabhq_production/*.ibd | wc -l @@ -138,26 +145,25 @@ Whatever the results of your checks above, we now need to check if your GitLab d # Run this command with root privileges, replace the data dir if different: sudo ls -lh /var/lib/mysql/gitlabhq_production/*.frm | wc -l - - **Case 1: a result > 0 for both commands** -Congrats, your GitLab database uses the right InnoDB tablespace format. +Congratulations, your GitLab database uses the right InnoDB tablespace format. However, you must still ensure that any **future tables** created by GitLab will still use the right format: - If `SELECT @@innodb_file_per_table` returned **1** previously, your server is running correctly. - > It's however a requirement to check *now* that this setting is indeed persisted in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file! + > It's however a requirement to check *now* that this setting is indeed persisted in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file! - If `SELECT @@innodb_file_per_table` returned **0** previously, your server is not running correctly. - > [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [my.cnf](https://dev.mysql.com/doc/refman/5.7/en/tablespace-enabling.html) file + > [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file. Now, if you have a **different result** returned by the 2 commands above, it means you have a **mix of tables format** uses in your GitLab database. This can happen if your MySQL server had different values for `innodb_file_per_table` in its life and you updated GitLab at different moments with those inconsistent values. So keep reading. - **Case 2: a result equals to "0" OR not the same result for both commands** -Unfortunately, none or only some of your GitLab database tables use the GitLab requirement of [InnoDB File-Per-Table Tablespaces](http://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html). +Unfortunately, none or only some of your GitLab database tables use the GitLab requirement of [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html). Let's enable what we need on the running server: @@ -172,7 +178,7 @@ Let's enable what we need on the running server: # You can now quit the database session mysql> \q -> Now, **persist** [innodb_file_per_table](https://dev.mysql.com/doc/refman/5.6/en/tablespace-enabling.html) and [innodb_file_format](https://dev.mysql.com/doc/refman/5.6/en/innodb-file-format-enabling.html) in your `my.cnf` file. +> Now, **persist** [innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format-enabling.html) in your `my.cnf` file. Ensure at this stage that your GitLab instance is indeed **stopped**. @@ -184,7 +190,7 @@ Now, let's convert all the GitLab database tables to the new tablespace format: # Type the MySQL root password mysql > use gitlabhq_production; - # Safety check: you should still have those values set as follow: + # Safety check: you should still have those values set as follows: mysql> SELECT @@innodb_file_per_table, @@innodb_file_format; +-------------------------+----------------------+ | @@innodb_file_per_table | @@innodb_file_format | @@ -203,7 +209,7 @@ Now, let's convert all the GitLab database tables to the new tablespace format: #### Check for proper InnoDB File Format, Row Format, Large Prefix and tables conversion -We need to check, enable and probably convert your existing GitLab DB tables to use the [Barracuda InnoDB file format](https://dev.mysql.com/doc/refman/5.6/en/innodb-file-format.html), the [DYNAMIC row format](https://dev.mysql.com/doc/refman/5.6/en/glossary.html#glos_dynamic_row_format) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) as a second prerequisite for supporting **utfb8mb4 with long indexes** used by recent GitLab databases. +We need to check, enable and probably convert your existing GitLab DB tables to use the [Barracuda InnoDB file format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format.html), the [DYNAMIC row format](https://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_dynamic_row_format) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) as a second prerequisite for supporting **utfb8mb4 with long indexes** used by recent GitLab databases. # Login to MySQL mysql -u root -p @@ -229,7 +235,7 @@ We need to check, enable and probably convert your existing GitLab DB tables to | utf8 | utf8_general_ci | +--------------------------+----------------------+ -> Now, ensure that [innodb_file_format](https://dev.mysql.com/doc/refman/5.6/en/tablespace-enabling.html) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) are **persisted** in your `my.cnf` file. +> Now, ensure that [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) are **persisted** in your `my.cnf` file. #### Tables and data conversion to utf8mb4 @@ -257,7 +263,7 @@ Now that you have a persistent MySQL setup, you can safely upgrade tables after Ensure your GitLab database configuration file uses a proper connection encoding and collation: -```sudo -u git -H editor config/database.yml``` +`sudo -u git -H editor config/database.yml` production: adapter: mysql2 @@ -266,19 +272,19 @@ Ensure your GitLab database configuration file uses a proper connection encoding [Restart your GitLab instance](../administration/restart_gitlab.md). - ## MySQL strings limits After installation or upgrade, remember to run the `add_limits_mysql` Rake task: **Omnibus GitLab installations** -``` + +```sh sudo gitlab-rake add_limits_mysql ``` **Installations from source** -``` +```sh bundle exec rake add_limits_mysql RAILS_ENV=production ``` @@ -291,8 +297,7 @@ GitLab database to `longtext` columns, which can persist values of up to 4GB (sometimes less if the value contains multibyte characters). Details can be found in the [PostgreSQL][postgres-text-type] and -[MySQL][mysql-text-types] manuals. +[MySQL](https://dev.mysql.com/doc/refman/5.7/en/string-type-overview.html) manuals. [postgres-text-type]: http://www.postgresql.org/docs/9.2/static/datatype-character.html -[mysql-text-types]: http://dev.mysql.com/doc/refman/5.7/en/string-type-overview.html [ce-38152]: https://gitlab.com/gitlab-org/gitlab-ce/issues/38152 diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 8efc0530b8a..d67695d75b4 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,7 +1,8 @@ # Digital Ocean and Docker Machine test environment -## Warning. This guide is for quickly testing different versions of GitLab and -## not recommended for ease of future upgrades or keeping the data you create. +CAUTION: **Caution:** +This guide is for quickly testing different versions of GitLab and not recommended for ease of +future upgrades or keeping the data you create. ## Initial setup @@ -12,92 +13,88 @@ locally on either macOS or Linux. #### Install Docker Toolbox -1. [https://www.docker.com/products/docker-toolbox](https://www.docker.com/products/docker-toolbox) +- <https://www.docker.com/products/docker-toolbox> ### On Linux #### Install Docker Engine -1. [https://docs.docker.com/engine/installation/linux](https://docs.docker.com/engine/installation/linux/) +- <https://docs.docker.com/engine/installation/linux/> #### Install Docker Machine -1. [https://docs.docker.com/machine/install-machine](https://docs.docker.com/machine/install-machine/) +- <https://docs.docker.com/machine/install-machine/> -_The rest of the steps are identical for macOS and Linux_ +NOTE: **Note:** +The rest of the steps are identical for macOS and Linux. ### Create new docker host -1. Login to Digital Ocean -1. Generate a new API token at https://cloud.digitalocean.com/settings/api/tokens +1. Login to Digital Ocean. +1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. + This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. -This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. + NOTE: **Note:** + 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. -**Note: 4GB is the minimum requirement for a Docker host that will run more then one GitLab instance** + - RAM: 4GB + - Name: `gitlab-test-env-do` + - Driver: `digitalocean` -+ RAM: 4GB -+ Name: `gitlab-test-env-do` -+ Driver: `digitalocean` +1. Set the DO token: + ```sh + export DOTOKEN=<your generated token> + ``` -**Set the DO token** - Replace the string below with your generated token +1. Create the machine: -``` -export DOTOKEN=cf3dfd0662933203005c4a73396214b7879d70aabc6352573fe178d340a80248 -``` - -**Create the machine** - -``` -docker-machine create \ - --driver digitalocean \ - --digitalocean-access-token=$DOTOKEN \ - --digitalocean-size "4gb" \ - gitlab-test-env-do -``` - -+ Resource: https://docs.docker.com/machine/drivers/digital-ocean/ + ```sh + docker-machine create \ + --driver digitalocean \ + --digitalocean-access-token=$DOTOKEN \ + --digitalocean-size "4gb" \ + gitlab-test-env-do + ``` +Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. ### Creating GitLab test instance - #### Connect your shell to the new machine - In this example we'll create a GitLab EE 8.10.8 instance. - First connect the docker client to the docker host you created previously. -``` +```sh eval "$(docker-machine env gitlab-test-env-do)" ``` You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` docker host - #### Create new GitLab container -+ HTTP port: `8888` -+ SSH port: `2222` - + Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG ` -+ Hostname: IP of docker host -+ Container name: `gitlab-test-8.10` -+ GitLab version: **EE** `8.10.8-ee.0` +- HTTP port: `8888` +- SSH port: `2222` + - Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG` +- Hostname: IP of docker host +- Container name: `gitlab-test-8.10` +- GitLab version: **EE** `8.10.8-ee.0` -##### Setup container settings +##### Set up container settings -``` +```sh export SSH_PORT=2222 export HTTP_PORT=8888 export VERSION=8.10.8-ee.0 export NAME=gitlab-test-8.10 ``` -##### Create container -``` +##### Create container + +```sh docker run --detach \ --env GITLAB_OMNIBUS_CONFIG="external_url 'http://$(docker-machine ip gitlab-test-env-do):$HTTP_PORT'; gitlab_rails['gitlab_shell_ssh_port'] = $SSH_PORT;" \ --hostname $(docker-machine ip gitlab-test-env-do) \ @@ -110,23 +107,20 @@ gitlab/gitlab-ee:$VERSION ##### Retrieve the docker host IP -``` +```sh docker-machine ip gitlab-test-env-do # example output: 192.168.151.134 ``` - -+ Browse to: http://192.168.151.134:8888/ - +Browse to: <http://192.168.151.134:8888/>. ##### Execute interactive shell/edit configuration - -``` +```sh docker exec -it $NAME /bin/bash ``` -``` +```sh # example commands root@192:/# vi /etc/gitlab/gitlab.rb root@192:/# gitlab-ctl reconfigure @@ -134,6 +128,6 @@ root@192:/# gitlab-ctl reconfigure #### Resources -+ [https://docs.gitlab.com/omnibus/docker/](https://docs.gitlab.com/omnibus/docker/) -+ [https://docs.docker.com/machine/get-started/](https://docs.docker.com/machine/get-started/) -+ [https://docs.docker.com/machine/reference/ip/](https://docs.docker.com/machine/reference/ip/)+ +- <https://docs.gitlab.com/omnibus/docker/>. +- <https://docs.docker.com/machine/get-started/>. +- <https://docs.docker.com/machine/reference/ip/>. diff --git a/doc/install/installation.md b/doc/install/installation.md index 85431a80a81..06293b8caf5 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -12,7 +12,7 @@ Since installations from source don't have Runit, Sidekiq can't be terminated an ## Select Version to Install -Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-3-stable`). +Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-5-stable`). You can select the branch in the version dropdown in the top left corner of GitLab (below the menu bar). If the highest number stable branch is unclear please check the [GitLab Blog](https://about.gitlab.com/blog/) for installation guide links by version. @@ -79,7 +79,7 @@ Make sure you have the right version of Git installed # Install Git sudo apt-get install -y git-core - # Make sure Git is version 2.9.5 or higher + # Make sure Git is version 2.18.0 or higher git --version Is the system packaged Git too old? Remove it and compile from source. @@ -103,7 +103,7 @@ Is the system packaged Git too old? Remove it and compile from source. # When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git -**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://github.com/gitlabhq/gitlabhq/issues/4866#issuecomment-32726573) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: +**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-ce/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: sudo apt-get install -y postfix @@ -132,9 +132,9 @@ Remove the old Ruby 1.8 if present: Download Ruby and compile it: mkdir /tmp/ruby && cd /tmp/ruby - curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz - echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz - cd ruby-2.4.4 + curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.gz + echo 'f919a9fbcdb7abecd887157b49833663c5c15fda ruby-2.5.3.tar.gz' | shasum -c - && tar xzf ruby-2.5.3.tar.gz + cd ruby-2.5.3 ./configure --disable-install-rdoc make @@ -300,9 +300,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-3-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-5-stable gitlab -**Note:** You can change `11-3-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `11-5-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -460,11 +460,11 @@ GitLab-Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is o ### Install Gitaly # Fetch Gitaly source with Git and compile with Go - sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly]" RAILS_ENV=production + sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production You can specify a different Git repository by providing it as an extra parameter: - sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,https://example.com/gitaly.git]" RAILS_ENV=production + sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories,https://example.com/gitaly.git]" RAILS_ENV=production Next, make sure gitaly configured: @@ -515,7 +515,7 @@ Make GitLab start on boot: sudo update-rc.d gitlab defaults 21 -### Setup Logrotate +### Set up Logrotate sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 09f5aaa04a7..5749eb0a9ec 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -31,7 +31,7 @@ to deploy. TIP: **Tip:** For production deployments, we strongly recommend using the -[detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/README.md) +[detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/index.md) utilizing [external Postgres, Redis, and object storage](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) services. ### Requirements @@ -93,7 +93,7 @@ You can access the GitLab instance by visiting the domain name beginning with above, the URL would be `https://gitlab.example.com`. If you manually created the secret for initial root password, you -can use that to sign in as `root` user. If not, Gitlab automatically +can use that to sign in as `root` user. If not, GitLab automatically created a random password for `root` user. This can be extracted by the following command (replace `<name>` by name of the release - which is `gitlab` if you used the command above): @@ -112,8 +112,7 @@ If your SMTP server requires authentication make sure to read the section on pro your password in the [secrets documentation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md#smtp-password). You can disable authentication settings with `--set global.smtp.authentication=""`. -If your Kubernetes cluster is on GKE, be aware that SMTP ports [25, 465, and 587 -are blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports). +If your Kubernetes cluster is on GKE, be aware that SMTP port [25 is blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports). ### Deploying the Community Edition diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md index 2aab225fcdb..3c2f883f29d 100644 --- a/doc/install/kubernetes/gitlab_runner_chart.md +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -1,6 +1,6 @@ # GitLab Runner Helm Chart > **Note:** -These charts have been tested on Google Kubernetes Engine and Azure Container Service. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/gitlab-runner/issues). +These charts have been tested on Google Kubernetes Engine and Azure Container Service. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/gitlab-org/gitlab-runner/issues). The `gitlab-runner` Helm chart deploys a GitLab Runner instance into your Kubernetes cluster. @@ -84,7 +84,7 @@ rbac: ## # serviceAccountName: default -## Configuration for the Pods that that the runner launches for each new job +## Configuration for the Pods that the runner launches for each new job ## runners: ## Default container image to use for builds when none is specified @@ -132,7 +132,7 @@ runners: If your cluster has RBAC enabled, you can choose to either have the chart create its own service account or provide one. -To have the chart create the service account for you, set `rbac.create` to true. +To have the chart create the service account for you, set `rbac.create` to true. ### Controlling maximum Runner concurrency diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 70bc3ff770f..4c88b6f97fc 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -80,7 +80,7 @@ This will download the VirtualBox image and fire up the VM with some preconfigur values as you can see in the Vagrantfile. As you may have noticed, you need plenty of RAM (5GB in our example), so make sure you have enough. -Now that OpenShift is setup, let's see how the web console looks like. +Now that OpenShift is set up, let's see how the web console looks like. ### Explore the OpenShift web console @@ -505,7 +505,7 @@ PaaS and managing your applications with the ease of containers. [RedHat]: https://www.redhat.com/en "RedHat website" [openshift]: https://www.openshift.org "OpenShift Origin website" [vm]: https://www.openshift.org/vm/ "OpenShift All-in-one VM" -[vm-new]: https://atlas.hashicorp.com/openshift/boxes/origin-all-in-one "Official OpenShift Vagrant box on Atlas" +[vm-new]: https://app.vagrantup.com/openshift/boxes/origin-all-in-one "Official OpenShift Vagrant box on Vagrant Cloud" [template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/docker/openshift-template.json "OpenShift template for GitLab" [openshift.com]: https://openshift.com "OpenShift Online" [kubernetes]: http://kubernetes.io/ "Kubernetes website" diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 2f5d4142d04..5f129fd3bd1 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -124,5 +124,5 @@ To disable the relative URL: 1. Follow the same as above starting from 2. and set up the GitLab URL to one that doesn't contain a relative path. -[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to setup relative URL in Omnibus GitLab" +[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab" [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab" diff --git a/doc/install/requirements.md b/doc/install/requirements.md index df59ce9837c..1b7e0d1d0ab 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -36,7 +36,7 @@ Please consider using a virtual machine to run GitLab. GitLab requires Ruby (MRI) 2.3. Support for Ruby versions below 2.3 (2.1, 2.2) will stop with GitLab 8.13. You will have to use the standard MRI implementation of Ruby. -We love [JRuby](http://jruby.org/) and [Rubinius](http://rubini.us/) but GitLab +We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab needs several Gems that have native extensions. ## Hardware requirements @@ -103,8 +103,8 @@ features of GitLab work with MySQL/MariaDB: 1. MySQL support for subgroups was [dropped with GitLab 9.3][post]. See [issue #30472][30472] for more information. -1. Geo **[STARTER ONLY]** does [not support MySQL](https://docs.gitlab.com/ee/gitlab-geo/database.html#mysql-replication). This means no supported Disaster Recovery solution if using MySQL. -1. [Zero downtime migrations][../update/README.md#upgrading-without-downtime] do not work with MySQL. +1. Geo does [not support MySQL](https://docs.gitlab.com/ee/administration/geo/replication/database.html#mysql-replication). This means no supported Disaster Recovery solution if using MySQL. **[PREMIUM ONLY]** +1. [Zero downtime migrations](../update/README.md#upgrading-without-downtime) do not work with MySQL. 1. GitLab [optimizes the loading of dashboard events](https://gitlab.com/gitlab-org/gitlab-ce/issues/31806) using [PostgreSQL LATERAL JOINs](https://blog.heapanalytics.com/postgresqls-powerful-new-join-type-lateral/). 1. In general, SQL optimized for PostgreSQL may run much slower in MySQL due to differences in query planners. For example, subqueries that work well in PostgreSQL @@ -197,7 +197,13 @@ use the CI features. ## Supported web browsers -We support the current and the previous major release of Firefox, Chrome/Chromium, Safari and Microsoft browsers (Microsoft Edge and Internet Explorer 11). +We support the current and the previous major release of: + +- Firefox +- Chrome/Chromium +- Safari +- Microsoft Edge +- Internet Explorer 11 Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version. diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a6436b5f926..200fe6f5206 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -20,17 +20,17 @@ To use Akismet: 1. Go to the URL: https://akismet.com/account/ -2. Sign-in or create a new account. +1. Sign-in or create a new account. -3. Click on **Show** to reveal the API key. +1. Click on **Show** to reveal the API key. -4. Go to Applications Settings on Admin Area (`admin/application_settings`) +1. Go to Applications Settings on Admin Area (`admin/application_settings`) -5. Check the **Enable Akismet** checkbox +1. Check the **Enable Akismet** checkbox -6. Fill in the API key from step 3. +1. Fill in the API key from step 3. -7. Save the configuration. +1. Save the configuration.  @@ -42,9 +42,9 @@ To use Akismet: As a way to better recognize between spam and ham, you can train the Akismet filter whenever there is a false positive or false negative. -When an entry is recognized as spam, it is rejected and added to the Spam Logs. +When an entry is recognized as spam, it is rejected and added to the Spam Logs. From here you can review if they are really spam. If one of them is not really -spam, you can use the **Submit as ham** button to tell Akismet that it falsely +spam, you can use the **Submit as ham** button to tell Akismet that it falsely recognized an entry as spam.  diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md index a75836a915a..bccaeec3706 100644 --- a/doc/integration/auth0.md +++ b/doc/integration/auth0.md @@ -3,7 +3,7 @@ To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an application. -1. Sign in to the [Auth0 Console](https://manage.auth0.com). If you need to +1. Sign in to the [Auth0 Console](https://auth0.com/auth/login). If you need to create an account, you can do so at the same link. 1. Select "New App/API". diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index bf587b5b296..a69db1d1a6e 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -54,6 +54,7 @@ you to use. ``` Account: Email, Read + Projects: Read Repositories: Read Pull Requests: Read Issues: Read diff --git a/doc/integration/github.md b/doc/integration/github.md index 680712f9e01..b8156b2b593 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,28 +1,32 @@ -# Integrate your server with GitHub +# Integrate your GitLab instance with GitHub -Import projects from GitHub and login to your GitLab instance with your GitHub account. +You can integrate your GitLab instance with GitHub.com as well as GitHub Enterprise to enable users to import projects from GitHub and/or to login to your GitLab instance with your GitHub account. -To enable the GitHub OmniAuth provider you must register your application with GitHub. -GitHub will generate an application ID and secret key for you to use. +## Enabling GitHub OAuth -1. Sign in to GitHub. +To enable GitHub OmniAuth provider, you must use GitHub's credentials for your GitLab instance. +To get the credentials (a pair of Client ID and Client Secret), you must register an application as an OAuth App on GitHub. -1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. +1. Sign in to GitHub. -1. Select "OAuth applications" in the left menu. +1. Navigate to your individual user or organization settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. -1. If you already have applications listed, switch to the "Developer applications" tab. + - For individual accounts, select **Developer settings** from the left menu, then select **OAuth Apps**. + - For organization accounts, directly select **OAuth Apps** from the left menu. -1. Select "Register new application". +1. Select **Register an application** (if you don't have any OAuth App) or **New OAuth App** (if you already have OAuth Apps). +  1. Provide the required details. - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' + - Homepage URL: the URL to your GitLab installation. e.g., `https://gitlab.company.com` - Application description: Fill this in if you wish. - - Authorization callback URL is 'http(s)://${YOUR_DOMAIN}'. Please make sure the port is included if your Gitlab instance is not configured on default port. -1. Select "Register application". + - Authorization callback URL: `http(s)://${YOUR_DOMAIN}`. Please make sure the port is included if your GitLab instance is not configured on default port. +  + +1. Select **Register application**. -1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). +1. You should now see a pair of **Client ID** and **Client Secret** near the top right of the page (see screenshot). Keep this page open as you continue configuration.  @@ -97,9 +101,9 @@ GitHub will generate an application ID and secret key for you to use. __Replace `https://github.example.com/` with your GitHub URL.__ -1. Change 'YOUR_APP_ID' to the client ID from the GitHub application page from step 7. +1. Change `YOUR_APP_ID` to the Client ID from the GitHub application page from step 6. -1. Change 'YOUR_APP_SECRET' to the client secret from the GitHub application page from step 7. +1. Change `YOUR_APP_SECRET` to the Client Secret from the GitHub application page from step 6. 1. Save the configuration file. @@ -154,7 +158,7 @@ You will also need to disable Git SSL verification on the server hosting GitLab. $ git config --global http.sslVerify false ``` -For the changes to take effect, [reconfigure Gitlab] if you installed +For the changes to take effect, [reconfigure GitLab] if you installed via Omnibus, or [restart GitLab] if you installed from source. [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index 05a91d9bef9..c19320471e3 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -2,7 +2,7 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). -If correctly setup, emails that require an action will be marked in Gmail. +If correctly set up, emails that require an action will be marked in Gmail.  diff --git a/doc/integration/google.md b/doc/integration/google.md index 73e2f5826ff..b91d40d4bd4 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -35,7 +35,7 @@ In Google's side: 1. You should now be able to see a Client ID and Client secret. Note them down or keep this page open as you will need them later. -1. From the **Dashboard** select **ENABLE APIS AND SERVICES > Compute > Google+ API > Enable** +1. From the **Dashboard** select **ENABLE APIS AND SERVICES > Social > Google+ API > Enable** 1. To enable projects to access [Google Kubernetes Engine](../user/project/clusters/index.md), you must also enable these APIs: - Google Kubernetes Engine API diff --git a/doc/integration/img/github_app.png b/doc/integration/img/github_app.png Binary files differindex d6c289a1de1..4a1523d41ac 100644 --- a/doc/integration/img/github_app.png +++ b/doc/integration/img/github_app.png diff --git a/doc/integration/img/github_app_entry.png b/doc/integration/img/github_app_entry.png Binary files differnew file mode 100644 index 00000000000..9e151f8cdff --- /dev/null +++ b/doc/integration/img/github_app_entry.png diff --git a/doc/integration/img/github_register_app.png b/doc/integration/img/github_register_app.png Binary files differnew file mode 100644 index 00000000000..edd3f660f4e --- /dev/null +++ b/doc/integration/img/github_register_app.png diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 932cd479d56..8fdadb008ec 100644 --- a/doc/integration/recaptcha.md +++ b/doc/integration/recaptcha.md @@ -8,19 +8,13 @@ to confirm that a real user, not a bot, is attempting to create an account. To use reCAPTCHA, first you must create a site and private key. -1. Go to the URL: https://www.google.com/recaptcha/admin - -2. Fill out the form necessary to obtain reCAPTCHA keys. - -3. Login to your GitLab server, with administrator credentials. - -4. Go to Applications Settings on Admin Area (`admin/application_settings`) - -5. Fill all recaptcha fields with keys from previous steps - -6. Check the `Enable reCAPTCHA` checkbox - -7. Save the configuration. +1. Go to the URL: <https://www.google.com/recaptcha/admin>. +1. Fill out the form necessary to obtain reCAPTCHA keys. +1. Login to your GitLab server, with administrator credentials. +1. Go to Applications Settings on Admin Area (`admin/application_settings`). +1. Fill all recaptcha fields with keys from previous steps. +1. Check the `Enable reCAPTCHA` checkbox. +1. Save the configuration. ## Enabling reCAPTCHA for user logins via passwords diff --git a/doc/integration/saml.md b/doc/integration/saml.md index e2eea57d694..a7470d27b4b 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -339,6 +339,23 @@ args: { } ``` +### `uid_attribute` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/43806) in GitLab 10.7. + +By default, the `uid` is set as the `name_id` in the SAML response. If you'd like to designate a unique attribute for the `uid`, you can set the `uid_attribute`. In the example below, the value of `uid` attribute in the SAML response is set as the `uid_attribute`. + +```yaml +args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent', + uid_attribute: 'uid' +} +``` + ## Troubleshooting ### 500 error after login diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 41fa63ae6f2..616f3a76b2c 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -4,92 +4,95 @@ This documentation is for enabling shibboleth with omnibus-gitlab package. In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled Nginx provided in the omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. - -To enable the Shibboleth OmniAuth provider you must: - -1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. -Check https://wiki.shibboleth.net/ for more info. - -1. You can find Apache config in gitlab-recipes (https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache) - -Following changes are needed to enable shibboleth: - -protect omniauth-shibboleth callback URL: -``` - <Location /users/auth/shibboleth/callback> - AuthType shibboleth - ShibRequestSetting requireSession 1 - ShibUseHeaders On - require valid-user - </Location> - - Alias /shibboleth-sp /usr/share/shibboleth - <Location /shibboleth-sp> - Satisfy any - </Location> - - <Location /Shibboleth.sso> - SetHandler shib - </Location> -``` -exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibboleth.sso" and "RewriteCond %{REQUEST_URI} !/shibboleth-sp", config should look like this: -``` - # Apache equivalent of Nginx try files - RewriteEngine on - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_URI} !/Shibboleth.sso - RewriteCond %{REQUEST_URI} !/shibboleth-sp - RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] - RequestHeader set X_FORWARDED_PROTO 'https' -``` - -1. Edit /etc/gitlab/gitlab.rb configuration file to enable OmniAuth and add -Shibboleth as an OmniAuth provider. User attributes will be sent from the -Apache reverse proxy to GitLab as headers with the names from the Shibboleth -attribute mapping. Therefore the values of the `args` hash -should be in the form of `"HTTP_ATTRIBUTE"`. The keys in the hash are arguments -to the [OmniAuth::Strategies::Shibboleth class](https://github.com/toyokazu/omniauth-shibboleth/blob/master/lib/omniauth/strategies/shibboleth.rb) -and are documented by the [omniauth-shibboleth gem](https://github.com/toyokazu/omniauth-shibboleth) -(take care to note the version of the gem packaged with GitLab). If some of -your users appear to be authenticated by Shibboleth and Apache, but GitLab -rejects their account with a URI that contains "e-mail is invalid" then your -Shibboleth Identity Provider or Attribute Authority may be asserting multiple -e-mail addresses. In this instance, you might consider setting the -`multi_values` argument to `first`. - -File should look like this: -``` -external_url 'https://gitlab.example.com' -gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' - -# disable Nginx -nginx['enable'] = false - -gitlab_rails['omniauth_allow_single_sign_on'] = true -gitlab_rails['omniauth_block_auto_created_users'] = false -gitlab_rails['omniauth_enabled'] = true -gitlab_rails['omniauth_providers'] = [ - { - "name" => "'shibboleth"', - "label" => "Text for Login Button", - "args" => { - "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", - "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", - "uid_field" => 'HTTP_EPPN', - "name_field" => 'HTTP_CN', - "info_fields" => { "email" => 'HTTP_MAIL'} - } - } -] - -``` - -1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you +To enable the Shibboleth OmniAuth provider you must configure Apache shibboleth module. +Installation and configuration of module it self is out of scope of this document. +Check <https://wiki.shibboleth.net/> for more info. + +You can find Apache config in gitlab-recipes (<https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache>). + +The following changes are needed to enable Shibboleth: + +1. Protect omniauth-shibboleth callback URL: + + ``` + <Location /users/auth/shibboleth/callback> + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibUseHeaders On + require valid-user + </Location> + + Alias /shibboleth-sp /usr/share/shibboleth + <Location /shibboleth-sp> + Satisfy any + </Location> + + <Location /Shibboleth.sso> + SetHandler shib + </Location> + ``` + +1. Exclude shibboleth URLs from rewriting. Add `RewriteCond %{REQUEST_URI} !/Shibboleth.sso` and `RewriteCond %{REQUEST_URI} !/shibboleth-sp`. Config should look like this: + + ``` + # Apache equivalent of Nginx try files + RewriteEngine on + RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_URI} !/Shibboleth.sso + RewriteCond %{REQUEST_URI} !/shibboleth-sp + RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] + RequestHeader set X_FORWARDED_PROTO 'https' + ``` + +1. Edit `/etc/gitlab/gitlab.rb` configuration file to enable OmniAuth and add + Shibboleth as an OmniAuth provider. User attributes will be sent from the + Apache reverse proxy to GitLab as headers with the names from the Shibboleth + attribute mapping. Therefore the values of the `args` hash + should be in the form of `"HTTP_ATTRIBUTE"`. The keys in the hash are arguments + to the [OmniAuth::Strategies::Shibboleth class](https://github.com/toyokazu/omniauth-shibboleth/blob/master/lib/omniauth/strategies/shibboleth.rb) + and are documented by the [omniauth-shibboleth gem](https://github.com/toyokazu/omniauth-shibboleth) + (take care to note the version of the gem packaged with GitLab). If some of + your users appear to be authenticated by Shibboleth and Apache, but GitLab + rejects their account with a URI that contains "e-mail is invalid" then your + Shibboleth Identity Provider or Attribute Authority may be asserting multiple + e-mail addresses. In this instance, you might consider setting the + `multi_values` argument to `first`. + + The file should look like this: + + ``` + external_url 'https://gitlab.example.com' + gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' + + # disable Nginx + nginx['enable'] = false + + gitlab_rails['omniauth_allow_single_sign_on'] = true + gitlab_rails['omniauth_block_auto_created_users'] = false + gitlab_rails['omniauth_enabled'] = true + gitlab_rails['omniauth_providers'] = [ + { + "name" => "'shibboleth"', + "label" => "Text for Login Button", + "args" => { + "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", + "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", + "uid_field" => 'HTTP_EPPN', + "name_field" => 'HTTP_CN', + "info_fields" => { "email" => 'HTTP_MAIL'} + } + } + ] + + ``` + +1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you installed GitLab via Omnibus or from source respectively. -On the sign in page there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (Depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. +On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. ## Apache 2.4 / GitLab 8.6 update + The order of the first 2 Location directives is important. If they are reversed, you will not get a shibboleth session! @@ -135,6 +138,3 @@ you will not get a shibboleth session! RequestHeader set X_FORWARDED_PROTO 'https' RequestHeader set X-Forwarded-Ssl on ``` - -[reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure -[restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index fc7b97b3cc2..03ba2ae8817 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -75,7 +75,8 @@ Please see the table below for some examples: | Latest stable version | Your version | Recommended upgrade path | Note | | -------------- | ------------ | ------------------------ | ---------------- | | 9.4.5 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.4.5` | `8.17.7` is the last version in version `8` | -| 10.1.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.8` -> `10.1.4` | `8.17.7` is the last version in version `8`, `9.5.8` is the last version in version `9` | +| 10.1.4 | 8.13.4 | `8.13.4 -> 8.17.7 -> 9.5.10 -> 10.1.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9` | +| 11.3.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9`, `10.8.7` is the last version in version `10` | More information about the release procedures can be found in our [release-tools documentation][rel]. You may also want to read our diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 1d29f6d4e43..a63656fafef 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -9,37 +9,39 @@ You can only restore a backup to **exactly the same version and type (CE/EE)** of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. -## Backup +## Requirements -GitLab provides a simple command line interface to backup your whole installation, -and is flexible enough to fit your needs. +In order to be able to backup and restore, you need two essential tools +installed on your system. -### Requirements +### Rsync -* rsync +If you installed GitLab: -If you're using GitLab with the Omnibus package, you're all set. If you -installed GitLab from source, make sure you have rsync installed. +- Using the Omnibus package, you're all set. +- From source, make sure `rsync` is installed: -If you're using Ubuntu, you could run: + ```sh + # Debian/Ubuntu + sudo apt-get install rsync -``` -sudo apt-get install -y rsync -``` + # RHEL/CentOS + sudo yum install rsync + ``` -* tar +### Tar Backup and restore tasks use `tar` under the hood to create and extract archives. Ensure you have version 1.30 or above of `tar` available in your system. To check the version, run: -``` +```sh tar --version ``` -### Backup timestamp +## Backup timestamp ->**Note:** +NOTE: **Note:** In GitLab 9.2 the timestamp format was changed from `EPOCH_YYYY_MM_DD` to `EPOCH_YYYY_MM_DD_GitLab_version`, for example `1493107454_2018_04_25` would become `1493107454_2018_04_25_10.6.4-ce`. @@ -54,31 +56,48 @@ available. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, then the timestamp is `1493107454_2018_04_25_10.6.4-ce`. -### Creating a backup of the GitLab system +## Creating a backup of the GitLab system + +GitLab provides a simple command line interface to backup your whole instance. +It backs up your: + +- Database +- Attachments +- Git repositories data +- CI/CD job output logs +- CI/CD job artifacts +- LFS objects +- Container Registry images +- GitLab Pages content + +CAUTION: **Warning:** +GitLab does not back up any configuration files, SSL certificates, or system files. +You are highly advised to [read about storing configuration files](#storing-configuration-files). Use this command if you've installed GitLab with the Omnibus package: -``` +```sh sudo gitlab-rake gitlab:backup:create ``` Use this if you've installed GitLab from source: -``` +```sh sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` If you are running GitLab within a Docker container, you can run the backup from the host: -``` +```sh docker exec -t <container name> gitlab-rake gitlab:backup:create ``` -If you are using the gitlab-omnibus helm chart on a Kubernetes cluster, you can -run the backup task on the gitlab application pod using kubectl +If you are using the [GitLab helm chart](https://gitlab.com/charts/gitlab) on a +Kubernetes cluster, you can run the backup task using `backup-utility` script on +the gitlab task runner pod via `kubectl`. Refer to [backing up a GitLab installation](https://gitlab.com/charts/gitlab/blob/master/doc/backup-restore/backup.md#backing-up-a-gitlab-installation) for more details: -``` -kubectl exec -it <gitlab-gitlab pod> gitlab-rake gitlab:backup:create +```sh +kubectl exec -it <gitlab task-runner pod> backup-utility ``` Example output: @@ -110,9 +129,50 @@ Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` +## Storing configuration files + +A backup performed by the [raketask GitLab provides](#creating-a-backup-of-the-gitlab-system) +does **not** store your configuration files. The primary reason for this is that your +database contains encrypted information for two-factor authentication, the CI/CD +'secure variables', etc. Storing encrypted information along with its key in the +same place defeats the purpose of using encryption in the first place. + +CAUTION: **Warning:** +The secrets file is essential to preserve your database encryption key. + +At the very **minimum**, you must backup: + +For Omnibus: + +- `/etc/gitlab/gitlab-secrets.json` +- `/etc/gitlab/gitlab.rb` + +For installation from source: + +- `/home/git/gitlab/config/secrets.yml` +- `/home/git/gitlab/config/gitlab.yml` + +For [Docker installations](https://docs.gitlab.com/omnibus/docker/), you must +back up the volume where the configuration files are stored. If you have created +the GitLab container according to the documentation, it should be under +`/srv/gitlab/config`. + +You may also want to back up any TLS keys and certificates, and your +[SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + +If you use Omnibus GitLab, see some additional information +[to backup your configuration](https://docs.gitlab.com/omnibus/settings/backups.html). + +In the unlikely event that the secrets file is lost, see the +[troubleshooting section](#when-the-secrets-file-is-lost). + +## Backup options + +The command line tool GitLab provides to backup your instance can take more options. + ### Backup strategy option -> **Note:** Introduced as an option in GitLab 8.17. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8728) in GitLab 8.17. The default backup strategy is to essentially stream data from the respective data locations to the backup using the Linux command `tar` and `gzip`. This works @@ -129,8 +189,11 @@ so the problem doesn't compound, but it could be a considerable change for large installations. This is why the `copy` strategy is not the default in 8.17. To use the `copy` strategy instead of the default streaming strategy, specify -`STRATEGY=copy` in the Rake task command. For example, -`sudo gitlab-rake gitlab:backup:create STRATEGY=copy`. +`STRATEGY=copy` in the Rake task command. For example: + +```sh +sudo gitlab-rake gitlab:backup:create STRATEGY=copy +``` ### Excluding specific directories from the backup @@ -151,11 +214,15 @@ Use a comma to specify several options at the same time: All wikis will be backed up as part of the `repositories` group. Non-existent wikis will be skipped during a backup. -``` -# use this command if you've installed GitLab with the Omnibus package +For Omnibus GitLab packages: + +```sh sudo gitlab-rake gitlab:backup:create SKIP=db,uploads +``` + +For installations from source: -# if you've installed GitLab from source +```sh sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=production ``` @@ -208,7 +275,7 @@ This example can be used for a bucket in Amsterdam (AMS3). 1. [Reconfigure GitLab] for the changes to take effect -CAUTION: **Warning:** +NOTE: **Note:** If you see `400 Bad Request` by using Digital Ocean Spaces, the cause may be the usage of backup encryption. Remove or comment the line that contains `gitlab_rails['backup_encryption']` since Digital Ocean Spaces @@ -370,33 +437,43 @@ backups will be copied to, and will be created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, just use `.` instead. -For omnibus packages: -```ruby -gitlab_rails['backup_upload_connection'] = { - :provider => 'Local', - :local_root => '/mnt/backups' -} +For Omnibus GitLab packages: -# The directory inside the mounted folder to copy backups to -# Use '.' to store them in the root directory -gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' -``` +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['backup_upload_connection'] = { + :provider => 'Local', + :local_root => '/mnt/backups' + } + + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +--- For installations from source: -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: Local - local_root: '/mnt/backups' - # The directory inside the mounted folder to copy backups to - # Use '.' to store them in the root directory - remote_directory: 'gitlab_backups' -``` +1. Edit `home/git/gitlab/config/gitlab.yml`: + + ```yaml + backup: + upload: + # Fog storage connection settings, see http://fog.io/storage/ . + connection: + provider: Local + local_root: '/mnt/backups' + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + remote_directory: 'gitlab_backups' + ``` + +1. [Restart GitLab] for the changes to take effect. ### Backup archive permissions @@ -405,45 +482,56 @@ will have owner/group git:git and 0600 permissions by default. This is meant to avoid other system users reading GitLab's data. If you need the backup archives to have different permissions you can use the 'archive_permissions' setting. -``` -# In /etc/gitlab/gitlab.rb, for omnibus packages -gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable -``` +For Omnibus GitLab packages: -``` -# In gitlab.yml, for installations from source: - backup: - archive_permissions: 0644 # Makes the backup archives world-readable -``` +1. Edit `/etc/gitlab/gitlab.rb`: -### Storing configuration files + ```ruby + gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable + ``` -Please be informed that a backup does not store your configuration -files. One reason for this is that your database contains encrypted -information for two-factor authentication. Storing encrypted -information along with its key in the same place defeats the purpose -of using encryption in the first place! +1. [Reconfigure GitLab] for the changes to take effect. -If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). -If you have a cookbook installation there should be a copy of your configuration in Chef. -If you installed from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). +--- -At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and -`/etc/gitlab/gitlab-secrets.json` (Omnibus), or -`/home/git/gitlab/config/secrets.yml` (source) to preserve your database -encryption key. +For installations from source: + +1. Edit `/home/git/gitlab/config/gitlab.yml`: + + ```yaml + backup: + archive_permissions: 0644 # Makes the backup archives world-readable + ``` + +1. [Restart GitLab] for the changes to take effect. ### Configuring cron to make daily backups ->**Note:** +NOTE: **Note:** The following cron jobs do not [backup your GitLab configuration files](#storing-configuration-files) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -**For Omnibus installations** +For Omnibus GitLab packages: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + ## Limit backup lifetime to 7 days - 604800 seconds + gitlab_rails['backup_keep_time'] = 604800 + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +Note that the `backup_keep_time` configuration option only manages local +files. GitLab does not automatically prune old files stored in a third-party +object storage (e.g., AWS S3) because the user may not have permission to list +and delete files. We recommend that you configure the appropriate retention +policy for your object storage. For example, you can configure [the S3 backup +policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: -``` +```sh sudo su - crontab -e ``` @@ -455,26 +543,24 @@ There, add the following line to schedule the backup for everyday at 2 AM: ``` You may also want to set a limited lifetime for backups to prevent regular -backups using all your disk space. To do this add the following lines to -`/etc/gitlab/gitlab.rb` and reconfigure: +backups using all your disk space. -``` -# limit backup lifetime to 7 days - 604800 seconds -gitlab_rails['backup_keep_time'] = 604800 -``` +--- -Note that the `backup_keep_time` configuration option only manages local -files. GitLab does not automatically prune old files stored in a third-party -object storage (e.g., AWS S3) because the user may not have permission to list -and delete files. We recommend that you configure the appropriate retention -policy for your object storage. For example, you can configure [the S3 backup -policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). +For installations from source: + +1. Edit `home/git/gitlab/config/gitlab.yml`: -**For installation from source** + ```yaml + backup: + ## Limit backup lifetime to 7 days - 604800 seconds + keep_time: 604800 + ``` -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups +1. [Restart GitLab] for the changes to take effect. + + +```sh sudo -u git crontab -e # Edit the crontab for the git user ``` @@ -518,12 +604,14 @@ If you fail to restore this encryption key file along with the application data backup, users with two-factor authentication enabled and GitLab Runners will lose access to your GitLab server. +You may also want to restore any TLS keys, certificates, or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + Depending on your case, you might want to run the restore command with one or more of the following options: - `BACKUP=timestamp_of_backup` - Required if more than one backup exists. Read what the [backup timestamp is about](#backup-timestamp). -- `force=yes` - Does not ask if the authorized_keys file should get regenerated and assumes 'yes' for warning that database tables will be removed. +- `force=yes` - Does not ask if the authorized_keys file should get regenerated and assumes 'yes' for warning that database tables will be removed, enabling the "Write to authorized_keys file" setting, and updating LDAP providers. If you are restoring into directories that are mountpoints you will need to make sure these directories are empty before attempting a restore. Otherwise GitLab @@ -580,7 +668,7 @@ Restart GitLab: sudo service gitlab restart ``` -### Restore for Omnibus installations +### Restore for Omnibus GitLab installations This procedure assumes that: @@ -591,10 +679,11 @@ This procedure assumes that: First make sure your backup tar file is in the backup directory described in the `gitlab.rb` configuration `gitlab_rails['backup_path']`. The default is -`/var/opt/gitlab/backups`. +`/var/opt/gitlab/backups`. It needs to be owned by the `git` user. ```shell sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/ +sudo chown git.git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar ``` Stop the processes that are connected to the database. Leave the rest of GitLab @@ -628,10 +717,10 @@ If there is a GitLab version mismatch between your backup tar file and the insta version of GitLab, the restore command will abort with an error. Install the [correct GitLab version](https://packages.gitlab.com/gitlab/) and try again. -### Restore for Docker image and gitlab-omnibus helm chart +### Restore for Docker image and GitLab helm chart installations -For GitLab installations using docker image or the gitlab-omnibus helm chart on -a Kubernetes cluster, restore task expects the restore directories to be empty. +For GitLab installations using the Docker image or the GitLab helm chart on +a Kubernetes cluster, the restore task expects the restore directories to be empty. However, with docker and Kubernetes volume mounts, some system level directories may be created at the volume roots, like `lost+found` directory found in Linux operating systems. These directories are usually owned by `root`, which can @@ -642,19 +731,14 @@ directories are empty. For both these installation types, the backup tarball has to be available in the backup location (default location is `/var/opt/gitlab/backups`). -For docker installations, the restore task can be run from host using the -command +For docker installations, the restore task can be run from host: -``` +```sh docker exec -it <name of container> gitlab-rake gitlab:backup:restore ``` -Similarly, for gitlab-omnibus helm chart, the restore task can be run on the -gitlab application pod using kubectl - -``` -kubectl exec -it <gitlab-gitlab pod> gitlab-rake gitlab:backup:restore -``` +The GitLab helm chart uses a different process, documented in +[restoring a GitLab helm chart installation](https://gitlab.com/charts/gitlab/blob/master/doc/backup-restore/restore.md). ## Alternative backup strategies @@ -710,5 +794,53 @@ Those objects have no influence on the database backup/restore but they give thi For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). +### When the secrets file is lost + +If you have failed to [back up the secrets file](#storing-configuration-files), +then users with 2FA enabled will not be able to log into GitLab. In that case, +you need to [disable 2FA for everyone](../security/two_factor_authentication.md#disabling-2fa-for-everyone). + +In the case of CI/CD, if your project has secure variables set, you might experience +some weird behavior, like stuck jobs or 500 errors. In that case, you can try +deleting the `ci_variables` table from the database. + +CAUTION: **Warning:** +Use the following commands at your own risk, and make sure you've taken a +backup beforehand. + +1. Enter the Rails console: + + For Omnibus GitLab packages: + + ```sh + sudo gitlab-rails dbconsole + ``` + + For installations from source: + + ```sh + sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production + ``` + +1. Check the `ci_variables` table: + + ```sql + SELECT * FROM public."ci_variables"; + ``` + + Those are the variables that you need to delete. + +1. Drop the table: + + ```sql + DELETE FROM ci_variables; + ``` + +1. You may need to reconfigure or restart GitLab for the changes to take + effect. + +You should now be able to visit your project, and the jobs will start +running again. + [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md index 97e9b36d1a6..bb316df5b9a 100644 --- a/doc/raketasks/import.md +++ b/doc/raketasks/import.md @@ -6,6 +6,7 @@ - The groups will be created as needed, including subgroups - The owner of the group will be the first admin - Existing projects will be skipped +- Projects in hashed storage may be skipped (see [Importing bare repositories from hashed storage](#importing-bare-repositories-from-hashed-storage)) - The existing Git repos will be moved from disk (removed from the original path) ## How to use @@ -26,7 +27,6 @@ sudo -u git mkdir /var/opt/gitlab/git-data/repository-import-<date>/new_group If we copy the repos to `/var/opt/gitlab/git-data/repository-import-<date>`, and repo A needs to be under the groups G1 and G2, it will have to be created under those folders: `/var/opt/gitlab/git-data/repository-import-<date>/G1/G2/A.git`. - ``` sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repository-import-<date>/new_group/ @@ -70,3 +70,73 @@ Processing /var/opt/gitlab/git-data/repository-import-1/group/xyz.git * Skipping repo /var/opt/gitlab/git-data/repository-import-1/@shared/a/b/abcd.git [...] ``` + +## Importing bare repositories from hashed storage + +### Background + +Projects in legacy storage have a directory structure that mirrors their full +project path in GitLab, including their namespace structure. This information is +leveraged by the bare repository importer to import projects into their proper +locations. Each project and its parent namespaces are meaningfully named. + +However, the directory structure of projects in hashed storage do not contain +this information. This is beneficial for a variety of reasons, especially +improved performance and data integrity. See +[Repository Storage Types](../administration/repository_storage_types.md) for +more details. + +### Which repositories are importable? + +#### GitLab 10.3 or earlier + +Importing bare repositories from hashed storage is unsupported. + +#### GitLab 10.4 and later + +To support importing bare repositories from hashed storage, GitLab 10.4 and +later stores the full project path with each repository, in a special section of +the git repository's config file. This section is formatted as follows: + +``` +[gitlab] + fullpath = gitlab-org/gitlab-ce +``` + +However, existing repositories were not migrated to include this path. + +Bare repositories are importable if the following events occurred to the +repository in GitLab 10.4 and later: + +- Created +- Migrated to hashed storage +- Renamed +- Transferred to another namespace +- Ancestor renamed +- Ancestor transferred to another namespace + +Bare repositories are **not** importable by GitLab 10.4 and later when all the following are true about the repository: + +- It was created in GitLab 10.3 or earlier. +- It was not renamed, transferred, or migrated to hashed storage in GitLab 10.4 and later. +- Its ancestor namespaces were not renamed or transferred in GitLab 10.4 and later. + +There is an [open issue to add a migration to make all bare repositories +importable](https://gitlab.com/gitlab-org/gitlab-ce/issues/41776). + +Until then, you may wish to manually migrate repositories yourself. You can use +[Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session) +to do so. In a Rails console session, run the following to migrate a project: + +``` +project = Project.find_by_full_path('gitlab-org/gitlab-ce') +project.write_repository_config +``` + +In a Rails console session, run the following to migrate all of a namespace's +projects (this may take a while if there are 1000s of projects in a namespace): + +``` +namespace = Namespace.find_by_full_path('gitlab-org') +namespace.send(:write_projects_repository_config) +``` diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 3efb19c1526..dcdc9f42c22 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -10,7 +10,7 @@ Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering and tracking. **Note:** Starting with 11.2, Rack Attack is disabled by default. To continue -using this feature, please enable it in your `gitlab.rb` by setting +using this feature, please enable it in your `gitlab.rb` by setting `gitlab_rails['rack_attack_git_basic_auth'] = true`. By default, user sign-in, user sign-up (if enabled), and user password reset is @@ -35,13 +35,13 @@ For more information on how to use these options check out gitlab_rails['rack_attack_git_basic_auth'] = { 'enabled' => true, 'ip_whitelist' => ["127.0.0.1"], - 'maxretry' => 10, - 'findtime' => 60, - 'bantime' => 3600 + 'maxretry' => 10, # Limit the number of Git HTTP authentication attempts per IP + 'findtime' => 60, # Reset the auth attempt counter per IP after 60 seconds + 'bantime' => 3600 # Ban an IP for one hour (3600s) after too many auth attempts } ``` -3. Reconfigure GitLab: +1. Reconfigure GitLab: ``` sudo gitlab-ctl reconfigure @@ -55,9 +55,9 @@ The following settings can be configured: - `maxretry`: The maximum amount of times a request can be made in the specified time. - `findtime`: The maximum amount of time failed requests can count against an IP - before it's blacklisted. -- `bantime`: The total amount of time that a blacklisted IP will be blocked in - seconds. + before it's blacklisted (in seconds). +- `bantime`: The total amount of time that a blacklisted IP will be blocked (in + seconds). **Installations from source** @@ -98,26 +98,26 @@ In case you want to remove a blocked IP, follow these steps: grep "Rack_Attack" /var/log/gitlab/gitlab-rails/production.log ``` -2. Since the blacklist is stored in Redis, you need to open up `redis-cli`: +1. Since the blacklist is stored in Redis, you need to open up `redis-cli`: ```sh /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket ``` -3. You can remove the block using the following syntax, replacing `<ip>` with +1. You can remove the block using the following syntax, replacing `<ip>` with the actual IP that is blacklisted: ``` del cache:gitlab:rack::attack:allow2ban:ban:<ip> ``` -4. Confirm that the key with the IP no longer shows up: +1. Confirm that the key with the IP no longer shows up: ``` keys *rack::attack* ``` -5. Optionally, add the IP to the whitelist to prevent it from being blacklisted +1. Optionally, add the IP to the whitelist to prevent it from being blacklisted again (see [settings](#settings)). ## Troubleshooting @@ -129,11 +129,11 @@ the load balancer. In that case, you will need to: 1. [Configure `nginx[real_ip_trusted_addresses]`](https://docs.gitlab.com/omnibus/settings/nginx.html#configuring-gitlab-trusted_proxies-and-the-nginx-real_ip-module). This will keep users' IPs from being listed as the load balancer IPs. -2. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings). -3. Reconfigure GitLab: +1. Whitelist the load balancer's IP address(es) in the Rack Attack [settings](#settings). +1. Reconfigure GitLab: ``` sudo gitlab-ctl reconfigure ``` -4. [Remove the block via Redis.](#remove-blocked-ips-from-rack-attack-via-redis) +1. [Remove the block via Redis.](#remove-blocked-ips-from-rack-attack-via-redis) diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index f02f7b807cf..b770f2544d2 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -11,10 +11,10 @@ You can read more about it here: ## Enforcing 2FA for all users Users on GitLab, can enable it without any admin's intervention. If you want to -enforce everyone to setup 2FA, you can choose from two different ways: +enforce everyone to set up 2FA, you can choose from two different ways: - 1. Enforce on next login - 2. Suggest on next login, but allow a grace period before enforcing. +- Enforce on next login. +- Suggest on next login, but allow a grace period before enforcing. In the Admin area under **Settings** (`/admin/application_settings`), look for the "Sign-in Restrictions" area, where you can configure both. diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 48c79cd4769..8c07e11dcb1 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,6 +1,6 @@ # User email confirmation at sign-up -Gitlab admin can enable email confirmation on sign-up, if you want to confirm all +GitLab admin can enable email confirmation on sign-up, if you want to confirm all user emails before they are able to sign-in. In the Admin area under **Settings** (`/admin/application_settings`), go to section diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 5db042326f3..d9ae3c08172 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -8,163 +8,224 @@ you need a secure communication channel for sharing information. The SSH protocol provides this security and allows you to authenticate to the GitLab remote server without supplying your username or password each time. -For a more detailed explanation of how the SSH protocol works, we advise you to -read [this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). +For a more detailed explanation of how the SSH protocol works, read +[this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). -## Locating an existing SSH key pair +## Requirements -Before generating a new SSH key pair check if your system already has one -at the default location by opening a shell, or Command Prompt on Windows, -and running the following command: +The only requirement is to have the OpenSSH client installed on your system. This +comes pre-installed on GNU/Linux and macOS, but not on Windows. -**Windows Command Prompt:** +Depending on your Windows version, there are different methods to work with +SSH keys. -```bash -type %userprofile%\.ssh\id_rsa.pub -``` +### Installing the SSH client for Windows 10 -**Git Bash on Windows / GNU/Linux / macOS / PowerShell:** +Starting with Windows 10, you can +[install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +where you can run Linux distributions directly on Windows, without the overhead +of a virtual machine. Once installed and set up, you'll have the Git and SSH +clients at your disposal. -```bash -cat ~/.ssh/id_rsa.pub -``` +### Installing the SSH client for Windows 8.1 and Windows 7 + +The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 +is [Git for Windows](https://gitforwindows.org). It provides a BASH +emulation (Git Bash) used for running Git from the command line and the +`ssh-keygen` command that is useful to create SSH keys as you'll learn below. + +NOTE: **Alternative tools:** +Although not explored in this page, you can use some alternative tools. +[Cygwin](https://www.cygwin.com) is a large collection of GNU and open source +tools which provide functionality similar to a Unix distribution. +[PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) +provides a graphical user interface to [create SSH keys](https://tartarus.org/~simon/putty-snapshots/htmldoc/Chapter8.html#pubkey-puttygen). + +## Types of SSH keys and which to choose + +GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on +the signing algorithm, and some of them have advantages over the others. For +more information, you can read this +[nice article on ArchWiki](https://wiki.archlinux.org/index.php/SSH_keys#Choosing_the_authentication_key_type). +We'll focus on ED25519 and RSA and here. + +NOTE: **Note:** +As an admin, you can restrict +[which keys should be permitted and their minimum length](../security/ssh_keys_restrictions.md). +By default, all keys are permitted, which is also the case for +[GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints). -If you see a string starting with `ssh-rsa` you already have an SSH key pair -and you can skip the generate portion of the next section and skip to the copy -to clipboard step. -If you don't see the string or would like to generate a SSH key pair with a -custom name continue onto the next step. +## ED25519 SSH keys -Note that Public SSH key may also be named as follows: +Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/), +you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they +are more secure and have better performance over the other types. -- `id_dsa.pub` -- `id_ecdsa.pub` -- `id_ed25519.pub` +They were introduced in OpenSSH 6.5, so any modern OS should include the +option to create them. If for any reason your OS or the GitLab instance you +interact with doesn't support this, you can fallback to RSA. + +## RSA SSH keys + +RSA keys are the most common ones and therefore the most compatible with +servers that may have an old OpenSSH version. Use them if the GitLab server +doesn't work with ED25519 keys. + +The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a +stronger RSA key pair, specify the `-b` flag with a higher bit value than the +default. + +The old, default password encoding for SSH private keys is +[insecure](https://latacora.singles/2018/08/03/the-default-openssh.html); +it's only a single round of an MD5 hash. Since OpenSSH version 6.5, you should +use the `-o` option to `ssh-keygen` to encode your private key in a new, more +secure format. + +If you already have an RSA SSH key pair to use with GitLab, consider upgrading it +to use the more secure password encryption format by using the following command +on the private key: + +```bash +ssh-keygen -o -f ~/.ssh/id_rsa +``` ## Generating a new SSH key pair -1. To generate a new SSH key pair, use the following command: +Before creating an SSH key pair, make sure to read about the +[different types of keys](#types-of-ssh-keys-and-which-to-choose) to understand +their differences. + +To create a new SSH key pair: - **Git Bash on Windows / GNU/Linux / macOS:** +1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows. +1. Generate a new ED25519 SSH key pair: ```bash - ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096 + ssh-keygen -t ed25519 -C "email@example.com" ``` - (Note: the `-o` option was introduced in 2014; if this command does not work for you, simply remove the `-o` option and try again) + Or, if you want to use RSA: - **Windows:** + ```bash + ssh-keygen -o -t rsa -b 4096 -C "email@example.com" + ``` - Alternatively on Windows you can download - [PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - and follow [this documentation article][winputty] to generate a SSH key pair. + The `-C` flag adds a comment in the key in case you have multiple of them + and want to tell which is which. It is optional. 1. Next, you will be prompted to input a file path to save your SSH key pair to. + If you don't already have an SSH key pair, use the suggested path by pressing + <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client + to automatically use the SSH key pair with no additional configuration. - If you don't already have an SSH key pair use the suggested path by pressing - enter. Using the suggested path will normally allow your SSH client - to automatically use the SSH key pair with no additional configuration. + If you already have an SSH key pair with the suggested file path, you will need + to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths) + this SSH key pair will be used for in your `~/.ssh/config` file. - If you already have a SSH key pair with the suggested file path, you will need - to input a new file path and declare what host this SSH key pair will be used - for in your `.ssh/config` file, see [**Working with non-default SSH key pair paths**](#working-with-non-default-ssh-key-pair-paths) - for more information. +1. Once the path is decided, you will be prompted to input a password to + secure your new SSH key pair. It's a best practice to use a password, + but it's not required and you can skip creating it by pressing + <kbd>Enter</kbd> twice. -1. Once you have input a file path you will be prompted to input a password to - secure your SSH key pair. It is a best practice to use a password for an SSH - key pair, but it is not required and you can skip creating a password by - pressing enter. + If, in any case, you want to add or change the password of your SSH key pair, + you can use the `-p`flag: - NOTE: **Note:** - If you want to change the password of your SSH key pair, you can use - `ssh-keygen -p -o -f <keyname>`. - The `-o` option was added in 2014, so if this command does not work for you, - simply remove the `-o` option and try again. + ``` + ssh-keygen -p -o -f <keyname> + ``` -## Adding a SSH key to your GitLab account +Now, it's time to add the newly created public key to your GitLab account. -1. The next step is to copy the public SSH key as we will need it afterwards. +## Adding an SSH key to your GitLab account - To copy your public SSH key to the clipboard, use the appropriate code below: +1. Copy your **public** SSH key to the clipboard by using one of the commands below + depending on your Operating System: **macOS:** ```bash - pbcopy < ~/.ssh/id_rsa.pub + pbcopy < ~/.ssh/id_ed25519.pub ``` - **GNU/Linux (requires the xclip package):** + **WSL / GNU/Linux (requires the xclip package):** ```bash - xclip -sel clip < ~/.ssh/id_rsa.pub + xclip -sel clip < ~/.ssh/id_ed25519.pub ``` - **Windows Command Line:** + **Git Bash on Windows:** ```bash - type %userprofile%\.ssh\id_rsa.pub | clip + cat ~/.ssh/id_ed25519.pub | clip ``` - **Git Bash on Windows / Windows PowerShell:** + You can also open the key in a graphical editor and copy it from there, + but be careful not to accidentally change anything. - ```bash - cat ~/.ssh/id_rsa.pub | clip - ``` - -1. The final step is to add your public SSH key to GitLab. + NOTE: **Note:** + If you opted to create an RSA key, the name might differ. - Navigate to the 'SSH Keys' tab in your 'Profile Settings'. - Paste your key in the 'Key' section and give it a relevant 'Title'. - Use an identifiable title like 'Work Laptop - Windows 7' or - 'Home MacBook Pro 15'. +1. Add your public SSH key to your GitLab account by clicking your avatar + in the upper right corner and selecting **Settings**. From there on, + navigate to **SSH Keys** and paste your public key in the "Key" section. + If you created the key with a comment, this will appear under "Title". + If not, give your key an identifiable title like _Work Laptop_ or + _Home Workstation_, and click **Add key**. + NOTE: **Note:** If you manually copied your public SSH key make sure you copied the entire - key starting with `ssh-rsa` and ending with your email. + key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email. + +## Testing that everything is set up correctly + +To test whether your SSH key was added correctly, run the following command in +your terminal (replacing `gitlab.com` with your GitLab's instance domain): -1. Optionally you can test your setup by running `ssh -T git@example.com` - (replacing `example.com` with your GitLab domain) and verifying that you - receive a `Welcome to GitLab` message. +```bash +ssh -T git@gitlab.com +``` + +You should receive a _Welcome to GitLab, `@username`!_ message. + +If the welcome message doesn't appear, run SSH's verbose mode by replacing `-T` +with `-vvvT` to understand where the error is. ## Working with non-default SSH key pair paths If you used a non-default file path for your GitLab SSH key pair, you must configure your SSH client to find your GitLab private SSH key -for connections to your GitLab server (perhaps `gitlab.com`). +for connections to GitLab. -For your current terminal session you can do so using the following commands +Open a terminal and use the following commands (replacing `other_id_rsa` with your private SSH key): -**Git Bash on Windows / GNU/Linux / macOS:** - ```bash eval $(ssh-agent -s) ssh-add ~/.ssh/other_id_rsa ``` -To retain these settings you'll need to save them to a configuration file. -For OpenSSH clients this is configured in the `~/.ssh/config` file for some -operating systems. +To retain these settings, you'll need to save them to a configuration file. +For OpenSSH clients this is configured in the `~/.ssh/config` file. In this +file you can set up configurations for multiple hosts, like GitLab.com, your +own GitLab instance, GitHub, Bitbucket, etc. + Below are two example host configurations using their own SSH key: -``` -# GitLab.com server +```conf +# GitLab.com Host gitlab.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename-01 + Preferredauthentications publickey + IdentityFile ~/.ssh/gitlab_com_rsa -# Private GitLab server +# Private GitLab instance Host gitlab.company.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename + Preferredauthentications publickey + IdentityFile ~/.ssh/example_com_rsa ``` -Due to the wide variety of SSH clients and their very large number of -configuration options, further explanation of these topics is beyond the scope -of this document. - -Public SSH keys need to be unique, as they will bind to your account. -Your SSH key is the only identifier you'll have when pushing code via SSH. -That's why it needs to uniquely map to a single user. +Public SSH keys need to be unique to GitLab, as they will bind to your account. +Your SSH key is the only identifier you'll have when pushing code via SSH, +that's why it needs to uniquely map to a single user. ## Deploy keys @@ -240,8 +301,6 @@ not implicitly give any access just by setting them up. How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration -[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen - ## SSH on the GitLab server GitLab integrates with the system-installed SSH daemon, designating a user diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index a8aa11265d0..766a23c419d 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -23,7 +23,7 @@ This page gathers all the resources for the topic **Authentication** within GitL - [How to Configure LDAP with GitLab CE](../../administration/auth/how_to_configure_ldap_gitlab_ce/index.md) - [How to Configure LDAP with GitLab EE](https://docs.gitlab.com/ee/articles/how_to_configure_ldap_gitlab_ee/) - [Feature Highlight: LDAP Integration](https://about.gitlab.com/2014/07/10/feature-highlight-ldap-sync/) - - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/ldap/debugging_ldap.html) + - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/support-engineering/ldap/debugging_ldap.html) - **Integrations:** - [OmniAuth](../../integration/omniauth.md) - [Authentiq OmniAuth Provider](../../administration/auth/authentiq.md#authentiq-omniauth-provider) @@ -36,14 +36,13 @@ This page gathers all the resources for the topic **Authentication** within GitL ## API - [OAuth 2 Tokens](../../api/README.md#oauth-2-tokens) -- [Private Tokens](../../api/README.md#private-tokens) +- [Personal access tokens](../../api/README.md#personal-access-tokens) - [Impersonation tokens](../../api/README.md#impersonation-tokens) - [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) ## Third-party resources -- [Kanboard Plugin GitLab Authentication](https://kanboard.net/plugin/gitlab-auth) -- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) -- [Setup Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) +- [Kanboard Plugin GitLab Authentication](https://github.com/kanboard/plugin-gitlab-auth) +- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [How to customize GitLab to support OpenID authentication](http://eric.van-der-vlist.com/blog/2013/11/23/how-to-customize-gitlab-to-support-openid-authentication/) - [Openshift - Configuring Authentication and User Agent](https://docs.openshift.org/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index e778f1d83df..63e7497cbbc 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -2,40 +2,54 @@ > [Introduced][ce-37115] in GitLab 10.0. Generally available on GitLab 11.0. -Auto DevOps automatically detects, builds, tests, deploys, and monitors your -applications. +Auto DevOps provides pre-defined CI/CD configuration which allows you to automatically detect, build, test, +deploy, and monitor your applications. Leveraging CI/CD best practices and tools, Auto DevOps aims +to simplify the setup and execution of a mature & modern software development lifecycle. ## Overview +NOTE: **Enabled by default:** +Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for all +projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically +disabled on the first pipeline failure. Your project will continue to use an alternative +[CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab +administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops) +in the admin area. + With Auto DevOps, the software development process becomes easier to set up as every project can have a complete workflow from verification to monitoring -without needing to configure anything. Just push your code and GitLab takes +with minimal configuration. Just push your code and GitLab takes care of everything else. This makes it easier to start new projects and brings consistency to how applications are set up throughout a company. ## Quick start If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) -for using Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes -Engine. +for how to use Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes +Engine (GKE). + +If you are using a self-hosted instance of GitLab, you will need to configure the +[Google OAuth2 OmniAuth Provider](../../integration/google.md) before +you can configure a cluster on GKE. Once this is set up, you can follow the steps on the +[quick start guide](quick_start_guide.md) to get started. ## Comparison to application platforms and PaaS -Auto DevOps provides functionality described by others as an application -platform or as a Platform as a Service (PaaS). It takes inspiration from the +Auto DevOps provides functionality that is often included in an application +platform or a Platform as a Service (PaaS). It takes inspiration from the innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it -in a couple of ways: +in multiple ways: -1. Auto DevOps works with any Kubernetes cluster, you're not limited to running - on GitLab's infrastructure (note that many features also work without Kubernetes). +1. Auto DevOps works with any Kubernetes cluster; you're not limited to running + on GitLab's infrastructure. (Note that many features also work without Kubernetes.) 1. There is no additional cost (no markup on the infrastructure costs), and you can use a self-hosted Kubernetes cluster or Containers as a Service on any - public cloud (for example [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). + public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). 1. Auto DevOps has more features including security testing, performance testing, and code quality testing. -1. It offers an incremental graduation path. If you need advanced customizations +1. Auto DevOps offers an incremental graduation path. If you need advanced customizations, you can start modifying the templates without having to start over on a - completely different platform. + completely different platform. Review the [customizing](#customizing) section for more information. ## Features @@ -71,11 +85,6 @@ For an overview on the creation of Auto DevOps, read the blog post [From 2/3 of ## Requirements -TIP: **Tip:** -For self-hosted installations, the easiest way to make use of Auto DevOps is to -install GitLab inside a Kubernetes cluster using the [GitLab Omnibus Helm Chart] -which automatically installs and configures everything you need! - To make full use of Auto DevOps, you will need: 1. **GitLab Runner** (needed for all stages) - Your Runner needs to be @@ -101,10 +110,6 @@ To make full use of Auto DevOps, you will need: Kubernetes cluster using the [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) Helm chart. - 1. **Wildcard TLS termination** - You can deploy the - [`kube-lego`](https://github.com/kubernetes/charts/tree/master/stable/kube-lego) - Helm chart to your Kubernetes cluster to automatically issue certificates - for your domains using Let's Encrypt. 1. **Prometheus** (needed for Auto Monitoring) - To enable Auto Monitoring, you will need Prometheus installed somewhere (inside or outside your cluster) and configured to scrape your Kubernetes cluster. To get response metrics @@ -148,18 +153,13 @@ Auto DevOps base domain to `1.2.3.4.nip.io`. Once set up, all requests will hit the load balancer, which in turn will route them to the Kubernetes pods that run your application(s). -NOTE: **Note:** -If GitLab is installed using the [GitLab Omnibus Helm Chart], there are two -options: provide a static IP, or have one assigned. For more information see the -relevant docs on the [network prerequisites](../../install/kubernetes/gitlab_omnibus.md#networking-prerequisites). - ## Using multiple Kubernetes clusters **[PREMIUM]** When using Auto DevOps, you may want to deploy different environments to different Kubernetes clusters. This is possible due to the 1:1 connection that [exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters). -In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml) +In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) (used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know: - `review/` (every environment starting with `review/`) @@ -203,23 +203,38 @@ and verifying that your app is deployed as a review app in the Kubernetes cluster with the `review/*` environment scope. Similarly, you can check the other environments. -## Enabling Auto DevOps +## Enabling/Disabling Auto DevOps -If you haven't done already, read the [requirements](#requirements) to make -full use of Auto DevOps. If this is your fist time, we recommend you follow the +When first using Auto Devops, review the [requirements](#requirements) to ensure all necessary components to make +full use of Auto DevOps are available. If this is your fist time, we recommend you follow the [quick start guide](quick_start_guide.md). -To enable Auto DevOps to your project: +GitLab.com users can enable/disable Auto DevOps at the project-level only. Self-managed users +can enable/disable Auto DevOps at either the project-level or instance-level. + +### Enabling/disabling Auto DevOps at the instance-level (Administrators only) + +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Toggle the checkbox labeled **Default to Auto DevOps pipeline for all projects**. +1. If enabling, optionally set up the Auto DevOps [base domain](#auto-devops-base-domain) which will be used for Auto Deploy and Auto Review Apps. +1. Click **Save changes** for the changes to take effect. + +NOTE: **Note:** +Even when disabled at the instance level, project maintainers are still able to enable +Auto DevOps at the project level. + +### Enabling/disabling Auto DevOps at the project-level + +If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it. -1. Check that your project doesn't have a `.gitlab-ci.yml`, or remove it otherwise -1. Go to your project's **Settings > CI/CD > Auto DevOps** -1. Select "Enable Auto DevOps" -1. Optionally, but recommended, add in the [base domain](#auto-devops-base-domain) - that will be used by Kubernetes to [deploy your application](#auto-deploy) - and choose the [deployment strategy](#deployment-strategy) -1. Hit **Save changes** for the changes to take effect +1. Go to your project's **Settings > CI/CD > Auto DevOps**. +1. Toggle the **Default to Auto DevOps pipeline** checkbox (checked to enable, unchecked to disable) +1. When enabling, it's optional but recommended to add in the [base domain](#auto-devops-base-domain) + that will be used by Auto DevOps to [deploy your application](#auto-deploy) + and choose the [deployment strategy](#deployment-strategy). +1. Click **Save changes** for the changes to take effect. -Once saved, an Auto DevOps pipeline will be triggered on the default branch. +When the feature has been enabled, an Auto DevOps pipeline is triggered on the default branch. NOTE: **Note:** For GitLab versions 10.0 - 10.2, when enabling Auto DevOps, a pipeline needs to be @@ -228,22 +243,10 @@ manually triggered either by pushing a new commit to the repository or by visiti a new pipeline for your default branch, generally `master`. NOTE: **Note:** -If you are a GitLab Administrator, you can enable Auto DevOps instance wide -in **Admin Area > Settings > Continuous Integration and Deployment**. Doing that, -all the projects that haven't explicitly set an option will have Auto DevOps -enabled by default. - -NOTE: **Note:** There is also a feature flag to enable Auto DevOps to a percentage of projects which can be enabled from the console with `Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)`. -NOTE: **Enabled by default:** -Starting with GitLab 11.3, the Auto DevOps pipeline will be enabled by default for all -projects. If it's not explicitly enabled for the project, Auto DevOps will be automatically -disabled on the first pipeline failure. Your project will continue to use an alternative -[CI/CD configuration file](../../ci/yaml/README.md) if one is found. - ### Deployment strategy > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/38542) in GitLab 11.0. @@ -253,14 +256,19 @@ project's **Settings > CI/CD > Auto DevOps**. The available options are: -- **Continuous deployment to production** - enables [Auto Deploy](#auto-deploy) - by setting the [`STAGING_ENABLED`](#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_ENABLED`](#incremental-rollout-to-production) variables - to false. -- **Automatic deployment to staging, manual deployment to production** - sets the +- **Continuous deployment to production**: Enables [Auto Deploy](#auto-deploy) + with `master` branch directly deployed to production. +- **Continuous deployment to production using timed incremental rollout**: Sets the + [`INCREMENTAL_ROLLOUT_MODE`](#timed-incremental-rollout-to-production) variable + to `timed`, and production deployment will be executed with a 5 minute delay between + each increment in rollout. +- **Automatic deployment to staging, manual deployment to production**: Sets the [`STAGING_ENABLED`](#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_ENABLED`](#incremental-rollout-to-production) variables - to true, and the user is responsible for manually deploying to staging and production. + [`INCREMENTAL_ROLLOUT_MODE`](#incremental-rollout-to-production) variables + to `1` and `manual`. This means: + + - `master` branch is directly deployed to staging. + - Manual actions are provided for incremental rollout to production. ## Stages of Auto DevOps @@ -306,8 +314,7 @@ static analysis and other code checks on the current code. The report is created, and is uploaded as an artifact which you can later download and check out. -In GitLab Starter, differences between the source and -target branches are also +Any differences between the source and target branches are also [shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html). ### Auto SAST **[ULTIMATE]** @@ -320,9 +327,12 @@ analysis on the current code and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/sast.html). +NOTE: **Note:** +The Auto SAST stage will be skipped on licenses other than Ultimate. + ### Auto Dependency Scanning **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 10.7. @@ -336,6 +346,9 @@ check out. Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/dependency_scanning.html). +NOTE: **Note:** +The Auto Dependency Scanning stage will be skipped on licenses other than Ultimate. + ### Auto License Management **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 11.0. @@ -349,6 +362,9 @@ check out. Any licenses are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/license_management.html). +NOTE: **Note:** +The Auto License Management stage will be skipped on licenses other than Ultimate. + ### Auto Container Scanning > Introduced in GitLab 10.4. @@ -359,9 +375,12 @@ Docker image and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/container_scanning.html). +NOTE: **Note:** +The Auto Container Scanning stage will be skipped on licenses other than Ultimate. + ### Auto Review Apps NOTE: **Note:** @@ -381,6 +400,9 @@ branch's code so developers, designers, QA, product managers, and other reviewers can actually see and interact with code changes as part of the review process. Auto Review Apps create a Review App for each branch. +Auto Review Apps will deploy your app to your Kubernetes cluster only. When no cluster +is available, no deployment will occur. + The Review App will have a unique URL based on the project name, the branch name, and a unique number, combined with the Auto DevOps base domain. For example, `user-project-branch-1234.example.com`. A link to the Review App shows @@ -398,9 +420,12 @@ to perform an analysis on the current code and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/dast.html). +NOTE: **Note:** +The Auto DAST stage will be skipped on licenses other than Ultimate. + ### Auto Browser Performance Testing **[PREMIUM]** > Introduced in [GitLab Premium][ee] 10.4. @@ -413,8 +438,8 @@ Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://h /direction ``` -In GitLab Premium, performance differences between the source -and target branches are [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). +Any performance differences between the source and target branches are also +[shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). ### Auto Deploy @@ -454,6 +479,39 @@ no longer be valid as soon as the deployment job finishes. This means that Kubernetes can run the application, but in case it should be restarted or executed somewhere else, it cannot be accessed again. +#### Migrations + +> [Introduced][ce-21955] in GitLab 11.4 + +Database initialization and migrations for PostgreSQL can be configured to run +within the application pod by setting the project variables `DB_INITIALIZE` and +`DB_MIGRATE` respectively. + +If present, `DB_INITIALIZE` will be run as a shell command within an +application pod as a helm post-install hook. As some applications will +not run without a successful database initialization step, GitLab will +deploy the first release without the application deployment and only the +database initialization step. After the database initialization completes, +GitLab will deploy a second release with the application deployment as +normal. + +Note that a post-install hook means that if any deploy succeeds, +`DB_INITIALIZE` will not be processed thereafter. + +If present, `DB_MIGRATE` will be run as a shell command within an application pod as +a helm pre-upgrade hook. + +For example, in a Rails application: + +* `DB_INITIALIZE` can be set to `cd /app && RAILS_ENV=production + bin/setup` +* `DB_MIGRATE` can be set to `cd /app && RAILS_ENV=production bin/update` + +NOTE: **Note:** +The `/app` path is the directory of your project inside the docker image +as [configured by +Herokuish](https://github.com/gliderlabs/herokuish#paths) + > [Introduced][ce-19507] in GitLab 11.0. For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md###gitlab-deploy-token) @@ -482,10 +540,7 @@ The metrics include: - **Response Metrics:** latency, throughput, error rate - **System Metrics:** CPU utilization, memory utilization -If GitLab has been deployed using the [GitLab Omnibus Helm Chart], no -configuration is required. - -If you have installed GitLab using a different method, you need to: +In order to make use of monitoring you need to: 1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version @@ -540,7 +595,7 @@ repo or by specifying a project variable: file in it, Auto DevOps will detect the chart and use it instead of the [default one](https://gitlab.com/charts/auto-deploy-app). This can be a great way to control exactly how your application is deployed. -- **Project variable** - Create a [project variable](../../ci/variables/README.md#secret-variables) +- **Project variable** - Create a [project variable](../../ci/variables/README.md#variables) `AUTO_DEVOPS_CHART` with the URL of a custom chart to use. ### Customizing `.gitlab-ci.yml` @@ -598,9 +653,11 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `BUILDPACK_URL` | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` | | `SAST_CONFIDENCE_LEVEL` | The minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High; defaults to `3`.| | `DEP_SCAN_DISABLE_REMOTE_CHECKS` | Whether remote Dependency Scanning checks are disabled; defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).| +| `DB_INITIALIZE` | From GitLab 11.4, this variable can be used to specify the command to run to initialize the application's PostgreSQL database. It runs inside the application pod. | +| `DB_MIGRATE` | From GitLab 11.4, this variable can be used to specify the command to run to migrate the application's PostgreSQL database. It runs inside the application pod. | | `STAGING_ENABLED` | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | | `CANARY_ENABLED` | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | -| `INCREMENTAL_ROLLOUT_ENABLED`| From GitLab 10.8, this variable can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. | +| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment.<br/>Set to: <ul><li>`manual`, for manual deployment jobs.</li><li>`timed`, for automatic rollout deployments with a 5 minute delay each one.</li></ul> | | `TEST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `test` job. If the variable is present, the job will not be created. | | `CODE_QUALITY_DISABLED` | From GitLab 11.0, this variable can be used to disable the `codequality` job. If the variable is present, the job will not be created. | | `SAST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `sast` job. If the variable is present, the job will not be created. | @@ -612,7 +669,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac TIP: **Tip:** Set up the replica variables using a -[project variable](../../ci/variables/README.md#secret-variables) +[project variable](../../ci/variables/README.md#variables) and scale your application by just redeploying it! CAUTION: **Caution:** @@ -690,7 +747,7 @@ staging environment and deploy to production manually. For this scenario, the `STAGING_ENABLED` environment variable was introduced. If `STAGING_ENABLED` is defined in your project (e.g., set `STAGING_ENABLED` to -`1` as a secret variable), then the application will be automatically deployed +`1` as a CI/CD variable), then the application will be automatically deployed to a `staging` environment, and a `production_manual` job will be created for you when you're ready to manually deploy to production. @@ -703,7 +760,7 @@ A [canary environment](https://docs.gitlab.com/ee/user/project/canary_deployment before any changes are deployed to production. If `CANARY_ENABLED` is defined in your project (e.g., set `CANARY_ENABLED` to -`1` as a secret variable) then two manual jobs will be created: +`1` as a CI/CD variable) then two manual jobs will be created: - `canary` which will deploy the application to the canary environment - `production_manual` which is to be used by you when you're ready to manually @@ -721,9 +778,8 @@ to use an incremental rollout to replace just a few pods with the latest code. This will allow you to first check how the app is behaving, and later manually increasing the rollout up to 100%. -If `INCREMENTAL_ROLLOUT_ENABLED` is defined in your project (e.g., set -`INCREMENTAL_ROLLOUT_ENABLED` to `1` as a secret variable), then instead of the -standard `production` job, 4 different +If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead +of the standard `production` job, 4 different [manual jobs](../../ci/pipelines.md#manual-actions-from-the-pipeline-graph) will be created: @@ -747,21 +803,45 @@ environment page. Below, you can see how the pipeline will look if the rollout or staging variables are defined. -- **Without `INCREMENTAL_ROLLOUT_ENABLED` and without `STAGING_ENABLED`** +Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: + + + +Without `INCREMENTAL_ROLLOUT_MODE` and with `STAGING_ENABLED`: + + + +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and without `STAGING_ENABLED`: -  + -- **Without `INCREMENTAL_ROLLOUT_ENABLED` and with `STAGING_ENABLED`** +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED` -  + -- **With `INCREMENTAL_ROLLOUT_ENABLED` and without `STAGING_ENABLED`** +CAUTION: **Caution:** +Before GitLab 11.4 this feature was enabled by the presence of the +`INCREMENTAL_ROLLOUT_ENABLED` environment variable. +This configuration is deprecated and will be removed in the future. + +#### Timed incremental rollout to production **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7545) in GitLab 11.4. + +TIP: **Tip:** +You can also set this inside your [project's settings](#deployment-strategy). -  +This configuration based on +[incremental rollout to production](#incremental-rollout-to-production). -- **With `INCREMENTAL_ROLLOUT_ENABLED` and with `STAGING_ENABLED`** +Everything behaves the same way, except: -  +- It's enabled by setting the `INCREMENTAL_ROLLOUT_MODE` variable to `timed`. +- Instead of the standard `production` job, the following jobs with a 5 minute delay between each are created: + 1. `timed rollout 10%` + 1. `timed rollout 25%` + 1. `timed rollout 50%` + 1. `timed rollout 100%` ## Currently supported languages @@ -849,7 +929,7 @@ curl --data "value=true" --header "PRIVATE-TOKEN: personal_access_token" https:/ [review-app]: ../../ci/review_apps/index.md [container-registry]: ../../user/project/container_registry.md [postgresql]: https://www.postgresql.org/ -[Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml -[GitLab Omnibus Helm Chart]: ../../install/kubernetes/gitlab_omnibus.md +[Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml [ee]: https://about.gitlab.com/pricing/ +[ce-21955]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21955 [ce-19507]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19507 diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 7ca441a2f74..6326aadcdf2 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -15,7 +15,7 @@ need to ensure your own [Runners are configured](../../ci/runners/README.md) and Before creating and connecting your Kubernetes cluster to your GitLab project, you need a Google Cloud Platform account. If you don't already have one, -sign up at https://console.cloud.google.com. You'll need to either sign in with an existing +sign up at <https://console.cloud.google.com>. You'll need to either sign in with an existing Google account (for example, one that you use to access Gmail, Drive, etc.) or create a new one. 1. Follow the steps as outlined in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin) @@ -83,6 +83,9 @@ under which this application will be deployed.  1. Once ready, click **Create Kubernetes cluster**. + +NOTE: **Note:** +Do not select `f1-micro` from the **Machine type** dropdown. `f1-micro` machines cannot support a full GitLab installation. After a couple of minutes, the cluster will be created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). @@ -205,7 +208,7 @@ applications. In the rightmost column for the production environment, you can ma application is running. Right below, there is the -[Deploy Board](https://docs.gitlab.com/ee/user/project/deploy_boards.md). +[Deploy Board](https://docs.gitlab.com/ee/user/project/deploy_boards.html). The squares represent pods in your Kubernetes cluster that are associated with the given environment. Hovering above each square you can see the state of a deployment and clicking a square will take you to the pod's logs page. @@ -264,8 +267,8 @@ Let's fix that: to stage the changes. 1. Write a commit message and click **Commit**. -Now, if you go back to the merge request you should not only see the test passing, -but also the application deployed as a [review app](index.md#auto-review-apps). You +Now, if you go back to the merge request you should not only see the test passing, but +also the application deployed as a [review app](index.md#auto-review-apps). You can visit it by following the URL in the merge request. The changes that we previously made should be there. diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index 58d86f7d387..d7e1979217e 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -22,7 +22,7 @@ an extensive selection of dependency managed libraries and applications. If you are sure you don't need access to any additional development libraries or don't have approximately 15gb of available disk space for Xcode and Homebrew -use one of the the aforementioned methods. +use one of the aforementioned methods. ### Installing Xcode diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 8555c5e91ea..d1729d70158 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -78,5 +78,20 @@ git push In case you're running an older version of Git (< 2.9), consider upgrading to >= 2.9 (see [Broken pipe when pushing to Git repository][Broken-Pipe]). +## Timeout during git push/pull + +If pulling/pushing from/to your repository ends up taking more than 50 seconds, +a timeout will be issued with a log of the number of operations performed +and their respective timings, like the example below: + +``` +remote: Running checks for branch: master +remote: Scanning for LFS objects... (153ms) +remote: Calculating new repository size... (cancelled after 729ms) +``` + +This could be used to further investigate what operation is performing poorly +and provide GitLab with more information on how to improve the service. + [SSH troubleshooting]: ../../ssh/README.md#troubleshooting "SSH Troubleshooting" [Broken-Pipe]: https://stackoverflow.com/questions/19120120/broken-pipe-when-pushing-to-git-repository/36971469#36971469 "StackOverflow: 'Broken pipe when pushing to Git repository'" diff --git a/doc/university/README.md b/doc/university/README.md index 203981b85ec..3e7d02770e4 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -11,7 +11,7 @@ and [Blog Articles](https://about.gitlab.com/blog/). Would you like to contribute to GitLab University? Then please take a look at our contribution [process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md) for more information. -## Gitlab University Curriculum +## GitLab University Curriculum The curriculum is composed of GitLab videos, screencasts, presentations, projects and external GitLab content hosted on other services and has been organized into the following sections. @@ -104,7 +104,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [Due Dates and Milestones for GitLab Issues](https://about.gitlab.com/2016/08/05/feature-highlight-set-dates-for-issues/) 1. [How to Use GitLab Labels](https://about.gitlab.com/2016/08/17/using-gitlab-labels/) 1. [Applying GitLab Labels Automatically](https://about.gitlab.com/2016/08/19/applying-gitlab-labels-automatically/) -1. [GitLab Issue Board - Product Page](https://about.gitlab.com/solutions/issueboard/) +1. [GitLab Issue Board - Product Page](https://about.gitlab.com/product/issueboard/) 1. [An Overview of GitLab Issue Board](https://about.gitlab.com/2016/08/22/announcing-the-gitlab-issue-board/) 1. [Designing GitLab Issue Board](https://about.gitlab.com/2016/08/31/designing-issue-boards/) 1. [From Idea to Production with GitLab - Video](https://www.youtube.com/watch?v=25pHyknRgEo&index=14&list=PLFGfElNsQthbQu_IWlNOxul0TbS_2JH-e) @@ -125,7 +125,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) 1. [IBM: Continuous Delivery vs Continuous Deployment - Video](https://www.youtube.com/watch?v=igwFj8PPSnw) 1. [Amazon: Transition to Continuous Delivery - Video](https://www.youtube.com/watch?v=esEFaY0FDKc) -2. [TechBeacon: Doing continuous delivery? Focus first on reducing release cycle times](https://techbeacon.com/doing-continuous-delivery-focus-first-reducing-release-cycle-times) +1. [TechBeacon: Doing continuous delivery? Focus first on reducing release cycle times](https://techbeacon.com/doing-continuous-delivery-focus-first-reducing-release-cycle-times) 1. See **[Integrations](#39-integrations)** for integrations with other CI services. #### 2.4. Workflow @@ -140,7 +140,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [GitLab Compared to Other Tools](https://about.gitlab.com/comparison/) 1. [Comparing GitLab Terminology](https://about.gitlab.com/2016/01/27/comparing-terms-gitlab-github-bitbucket/) -1. [GitLab Compared to Atlassian (Recording 2016-03-03) ](https://youtu.be/Nbzp1t45ERo) +1. [GitLab Compared to Atlassian (Recording 2016-03-03)](https://youtu.be/Nbzp1t45ERo) 1. [GitLab Position FAQ](https://about.gitlab.com/handbook/positioning-faq) 1. [Customer review of GitLab with points on why they prefer GitLab](https://www.enovate.co.uk/web-design-blog/2015/11/25/gitlab-review/) @@ -189,7 +189,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project #### 3.8 Cycle Analytics 1. [GitLab Cycle Analytics Overview](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) -1. [GitLab Cycle Analytics - Product Page](https://about.gitlab.com/solutions/cycle-analytics/) +1. [GitLab Cycle Analytics - Product Page](https://about.gitlab.com/product/cycle-analytics/) #### 3.9. Integrations @@ -205,7 +205,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project ### 4. External Articles -1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](http://www.wsj.com/articles/SB10001424053111903480904576512250915629460) +1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](https://www.wsj.com/articles/SB10001424053111903480904576512250915629460) 1. [2014 Blog post by Chris Dixon - Software eats software development](http://cdixon.org/2014/04/13/software-eats-software-development/) 1. [2015 Venture Beat article - Actually, Open Source is Eating the World](http://venturebeat.com/2015/12/06/its-actually-open-source-software-thats-eating-the-world/) @@ -213,7 +213,8 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project ### 5. Resources for GitLab Team Members -*Some content can only be accessed by GitLab team members* +NOTE: **Note:** +Some content can only be accessed by GitLab team members 1. [Support Path](support/README.md) 1. [Sales Path (redirect to sales handbook)](https://about.gitlab.com/handbook/sales-onboarding/) diff --git a/doc/university/bookclub/booklist.md b/doc/university/bookclub/booklist.md index 26c3851276b..d5662be6fa6 100644 --- a/doc/university/bookclub/booklist.md +++ b/doc/university/bookclub/booklist.md @@ -10,108 +10,108 @@ List of books and resources, that may be worth reading. 1. **The Humble Programmer** - Edsger W. Dijkstra, 1972 ([paper](http://dl.acm.org/citation.cfm?id=361591)) + Edsger W. Dijkstra, 1972 ([paper](https://dl.acm.org/citation.cfm?id=361591)) ## Programming 1. **Design Patterns: Elements of Reusable Object-Oriented Software** - Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides, 1994 ([amazon](http://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612)) + Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides, 1994 ([amazon](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612)) 1. **Clean Code: A Handbook of Agile Software Craftsmanship** - Robert C. "Uncle Bob" Martin, 2008 ([amazon](http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)) + Robert C. "Uncle Bob" Martin, 2008 ([amazon](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)) 1. **Code Complete: A Practical Handbook of Software Construction**, 2nd Edition - Steve McConnell, 2004 ([amazon](http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670)) + Steve McConnell, 2004 ([amazon](https://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670)) 1. **The Pragmatic Programmer: From Journeyman to Master** - Andrew Hunt, David Thomas, 1999 ([amazon](http://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X)) + Andrew Hunt, David Thomas, 1999 ([amazon](https://www.amazon.com/Pragmatic-Programmer-Journeyman-Master/dp/020161622X)) 1. **Working Effectively with Legacy Code** - Michael Feathers, 2004 ([amazon](http://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052)) + Michael Feathers, 2004 ([amazon](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052)) 1. **Eloquent Ruby** - Russ Olsen, 2011 ([amazon](http://www.amazon.com/Eloquent-Ruby-Addison-Wesley-Professional/dp/0321584104)) + Russ Olsen, 2011 ([amazon](https://www.amazon.com/Eloquent-Ruby-Addison-Wesley-Professional/dp/0321584104)) 1. **Domain-Driven Design: Tackling Complexity in the Heart of Software** - Eric Evans, 2003 ([amazon](http://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)) + Eric Evans, 2003 ([amazon](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)) 1. **How to Solve It: A New Aspect of Mathematical Method** - Polya G. 1957 ([amazon](http://www.amazon.com/How-Solve-Mathematical-Princeton-Science/dp/069116407X)) + Polya G. 1957 ([amazon](https://www.amazon.com/How-Solve-Mathematical-Princeton-Science/dp/069116407X)) 1. **Software Creativity 2.0** - Robert L. Glass, 2006 ([amazon](http://www.amazon.com/Software-Creativity-2-0-Robert-Glass/dp/0977213315)) + Robert L. Glass, 2006 ([amazon](https://www.amazon.com/Software-Creativity-2-0-Robert-Glass/dp/0977213315)) 1. **Object-Oriented Software Construction** - Bertrand Meyer, 1997 ([amazon](http://www.amazon.com/Object-Oriented-Software-Construction-Book-CD-ROM/dp/0136291554)) + Bertrand Meyer, 1997 ([amazon](https://www.amazon.com/Object-Oriented-Software-Construction-Book-CD-ROM/dp/0136291554)) 1. **Refactoring: Improving the Design of Existing Code** - Martin Fowler, Kent Beck, 1999 ([amazon](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672)) + Martin Fowler, Kent Beck, 1999 ([amazon](https://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672)) 1. **Test Driven Development: By Example** - Kent Beck, 2002 ([amazon](http://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530)) + Kent Beck, 2002 ([amazon](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530)) 1. **Algorithms in C++: Fundamentals, Data Structure, Sorting, Searching** - Robert Sedgewick, 1990 ([amazon](http://www.amazon.com/Algorithms-Parts-1-4-Fundamentals-Structure/dp/0201350882)) + Robert Sedgewick, 1990 ([amazon](https://www.amazon.com/Algorithms-Parts-1-4-Fundamentals-Structure/dp/0201350882)) 1. **Effective C++** - Scott Mayers, 1996 ([amazon](http://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876)) + Scott Mayers, 1996 ([amazon](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876)) 1. **Extreme Programming Explained: Embrace Change** - Kent Beck, 1999 ([amazon](http://www.amazon.com/Extreme-Programming-Explained-Embrace-Change/dp/0321278658)) + Kent Beck, 1999 ([amazon](https://www.amazon.com/Extreme-Programming-Explained-Embrace-Change/dp/0321278658)) 1. **The Art of Computer Programming** - Donald E. Knuth, 1997 ([amazon](http://www.amazon.com/Computer-Programming-Volumes-1-4A-Boxed/dp/0321751043)) + Donald E. Knuth, 1997 ([amazon](https://www.amazon.com/Computer-Programming-Volumes-1-4A-Boxed/dp/0321751043)) 1. **Writing Efficient Programs** - Jon Louis Bentley, 1982 ([amazon](http://www.amazon.com/Writing-Efficient-Programs-Prentice-Hall-Software/dp/013970244X)) + Jon Louis Bentley, 1982 ([amazon](https://www.amazon.com/Writing-Efficient-Programs-Prentice-Hall-Software/dp/013970244X)) 1. **The Mythical Man-Month: Essays on Software Engineering** - Frederick Phillips Brooks, 1975 ([amazon](http://www.amazon.com/Mythical-Man-Month-Essays-Software-Engineering/dp/0201006502)) + Frederick Phillips Brooks, 1975 ([amazon](https://www.amazon.com/Mythical-Man-Month-Essays-Software-Engineering/dp/0201006502)) 1. **Peopleware: Productive Projects and Teams** 3rd Edition - Tom DeMarco, Tim Lister, 2013 ([amazon](http://www.amazon.com/Peopleware-Productive-Projects-Teams-3rd/dp/0321934113)) + Tom DeMarco, Tim Lister, 2013 ([amazon](https://www.amazon.com/Peopleware-Productive-Projects-Teams-3rd/dp/0321934113)) 1. **Principles Of Software Engineering Management** - Tom Gilb, 1988 ([amazon](http://www.amazon.com/Principles-Software-Engineering-Management-Gilb/dp/0201192462)) + Tom Gilb, 1988 ([amazon](https://www.amazon.com/Principles-Software-Engineering-Management-Gilb/dp/0201192462)) ## Other 1. **Thinking, Fast and Slow** - Daniel Kahneman, 2013 ([amazon](http://www.amazon.com/Thinking-Fast-Slow-Daniel-Kahneman/dp/0374533555)) + Daniel Kahneman, 2013 ([amazon](https://www.amazon.com/Thinking-Fast-Slow-Daniel-Kahneman/dp/0374533555)) 1. **The Social Animal** 11th Edition - Elliot Aronson, 2011 ([amazon](http://www.amazon.com/Social-Animal-Elliot-Aronson/dp/1429233419)) + Elliot Aronson, 2011 ([amazon](https://www.amazon.com/Social-Animal-Elliot-Aronson/dp/1429233419)) 1. **Influence: Science and Practice** 5th Edition - Robert B. Cialdini, 2008 ([amazon](http://www.amazon.com/Influence-Practice-Robert-B-Cialdini/dp/0205609996)) + Robert B. Cialdini, 2008 ([amazon](https://www.amazon.com/Influence-Practice-Robert-B-Cialdini/dp/0205609996)) 1. **Getting to Yes: Negotiating Agreement Without Giving In** - Roger Fisher, William L. Ury, Bruce Patton, 2011 ([amazon](http://www.amazon.com/Getting-Yes-Negotiating-Agreement-Without/dp/0143118757)) + Roger Fisher, William L. Ury, Bruce Patton, 2011 ([amazon](https://www.amazon.com/Getting-Yes-Negotiating-Agreement-Without/dp/0143118757)) 1. **How to Win Friends & Influence People** - Dale Carnegie, 1981 ([amazon](http://www.amazon.com/How-Win-Friends-Influence-People/dp/0671027034)) + Dale Carnegie, 1981 ([amazon](https://www.amazon.com/How-Win-Friends-Influence-People/dp/0671027034)) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 89516dba60b..7c7e44d29e7 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -303,7 +303,7 @@ A [tool](https://docs.gitlab.com/ee/integration/external-issue-tracker.html) use ### Jenkins -An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins-ci.org/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). +An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins.io/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). ### Jira @@ -395,7 +395,7 @@ Allow you to [organize issues](../../user/project/milestones/index.md) and merge ### Mirror Repositories -A project that is setup to automatically have its branches, tags, and commits [updated from an upstream repository](https://docs.gitlab.com/ee/workflow/repository_mirroring.html). This is useful when a repository you're interested in is located on a different server, and you want to be able to browse its content and activity using the familiar GitLab interface. +A project that is set up to automatically have its branches, tags, and commits [updated from an upstream repository](https://docs.gitlab.com/ee/workflow/repository_mirroring.html). This is useful when a repository you're interested in is located on a different server, and you want to be able to browse its content and activity using the familiar GitLab interface. ### MIT License @@ -673,7 +673,7 @@ Version control is a system that records changes to a file or set of files over ### Virtual Private Cloud (VPC) -A [VPC](https://docs.gitlab.com/ce/university/glossary/README.html#virtual-private-cloud-vpc) is an on demand configurable pool of shared computing resources allocated within a public cloud environment, providing some isolation between the different users using the resources. GitLab users need to create a new Amazon VPC in order to [setup High Availability](https://docs.gitlab.com/ce/university/high-availability/aws/). +A [VPC](https://docs.gitlab.com/ce/university/glossary/README.html#virtual-private-cloud-vpc) is an on demand configurable pool of shared computing resources allocated within a public cloud environment, providing some isolation between the different users using the resources. GitLab users need to create a new Amazon VPC in order to [set up High Availability](https://docs.gitlab.com/ce/university/high-availability/aws/). ### Virtual private server (VPS) @@ -689,7 +689,7 @@ A [model](http://www.umsl.edu/~hugheyd/is6840/waterfall.html) of building softwa ### Webhooks -A way for for an app to [provide](https://docs.gitlab.com/ce/user/project/integrations/webhooks.html) other applications with real-time information (e.g., send a message to a slack channel when a commit is pushed.) Read about setting up [custom git hooks](https://gitlab.com/help/administration/custom_hooks.md) for when webhooks are insufficient. +A way for an app to [provide](https://docs.gitlab.com/ce/user/project/integrations/webhooks.html) other applications with real-time information (e.g., send a message to a slack channel when a commit is pushed.) Read about setting up [custom git hooks](https://gitlab.com/help/administration/custom_hooks.md) for when webhooks are insufficient. ### Wiki diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 1bff1488746..b21cf27c1d3 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -9,7 +9,7 @@ in [significantly degraded performance](https://gitlab.com/gitlab-org/gitlab-ee/ GitLab on AWS can leverage many of the services that are already configurable with High Availability. These services have a lot of -flexibility and are able to adopt to most companies, best of all is the +flexibility and are able to adapt to most companies, best of all is the ability to automate both vertical and horizontal scaling. In this article we'll go through a basic HA setup where we'll start by @@ -55,9 +55,9 @@ and from the Actions dropdown choose Edit DNS Hostnames and select Yes. ### Subnet Now let's create some subnets in different Availability Zones. Make sure -that each subnet is associated the the VPC we just created, that it has +that each subnet is associated to the VPC we just created, that it has a distinct VPC and lastly that CIDR blocks don't overlap. This will also -allow us to enable multi AZ for redundancy. +allow us to enable multi-AZ for redundancy. We will create private and public subnets to match load balancers and RDS instances as well. @@ -98,7 +98,7 @@ traffic from any destination.  -Before leaving this screen select the next tab to the rgiht which is +Before leaving this screen select the next tab to the right which is Subnet Associations and add our public subnets. If you followed our naming convention they should be easy to find. @@ -106,8 +106,8 @@ naming convention they should be easy to find. ## Database with RDS -For our database server we will use Amazon RDS which offers Multi AZ -for redundancy. Lets start by creating a subnet group and then we'll +For our database server we will use Amazon RDS which offers Multi-AZ +for redundancy. Let's start by creating a subnet group and then we'll create the actual RDS instance. ### Subnet Group @@ -122,7 +122,7 @@ the VPC ID dropdown and at the bottom we can add our private subnets. Select the RDS service from the Database section and create a new PostgreSQL instance. After choosing between a Production or Development instance we'll start with the actual configuration. On the -image bellow we have the settings for this article but note the +image below we have the settings for this article but note the following two options which are of particular interest for HA: 1. Multi-AZ-Deployment is recommended as redundancy. Read more at @@ -133,7 +133,7 @@ IOPS (SSD) is best suited for HA. Read more about it at  -The rest of the setting on this page request a DB identifier, username +The rest of the setting on this page request a DB identifier, username, and a master password. We've chosen to use `gitlab-ha`, `gitlab` and a very secure password respectively. Keep these in hand for later. @@ -152,7 +152,7 @@ EC is an in-memory hosted caching solution. Redis maintains its own persistence and is used for certain types of application. Let's choose the ElastiCache service in the Database section from our -AWS console. Now lets create a cache subnet group which will be very +AWS console. Now let's create a cache subnet group which will be very similar to the RDS subnet group. Make sure to select our VPC and its private subnets. @@ -160,7 +160,7 @@ private subnets. Now press the Launch a Cache Cluster and choose Redis for our DB engine. You'll be able to configure details such as replication, -Multi AZ and node types. The second section will allow us to choose our +Multi-AZ and node types. The second section will allow us to choose our subnet and security group and  @@ -274,7 +274,7 @@ username, and password. gitlab_rails['db_password'] = "mypassword" gitlab_rails['db_host'] = "<rds-endpoint>" -Next we only need to configure the Redis section by adding the host and +Next, we only need to configure the Redis section by adding the host and uncommenting the port. @@ -285,8 +285,8 @@ to make the EFS integration easier to manage. gitlab_rails['redis_host'] = "<redis-endpoint>" gitlab_rails['redis_port'] = 6379 -Finally run reconfigure, you might find it useful to run a check and -a service status to make sure everything has been setup correctly. +Finally, run reconfigure. You might find it useful to run a check and +a service status to make sure everything has been set up correctly. sudo gitlab-ctl reconfigure sudo gitlab-rake gitlab:check @@ -321,10 +321,10 @@ The Load Balancer Health will allow us to indicate where to ping and what makes up a healthy or unhealthy instance. We won't add the instance on the next session because we'll destroy it -momentarily as we'll be using the image we where creating. We will keep +momentarily as we'll be using the image we were creating. We will keep the Enable Cross-Zone and Enable Connection Draining active. -After we finish creating the Load Balancer we can re visit our Security +After we finish creating the Load Balancer we can revisit our Security Groups to improve access only through the ELB and any other requirement you might have. @@ -363,7 +363,7 @@ After this is launched we are able to start creating our Auto Scaling Group. Start by giving it a name and assigning it our VPC and private subnets. We also want to always start with two instances and if you scroll down to Advanced Details we can choose to receive traffic from ELBs. -Lets enable that option and select our ELB. We also want to use the ELB's +Let's enable that option and select our ELB. We also want to use the ELB's health check.  @@ -388,9 +388,9 @@ we where aiming for. After you're done with the policies section have some fun trying to break instances. You should be able to see how the Auto Scaling Group and the -EC2 screen start bringing them up again. +EC2 screen starts bringing them up again. -High Availability is a very big area, we went mostly through scaling and +High Availability is a vast area, we went mostly through scaling and some redundancy options but it might also imply Geographic replication. There is a lot of ground yet to cover so have a read through these other resources and feel free to open an issue to request additional material. diff --git a/doc/university/support/README.md b/doc/university/support/README.md index 0cbae71d1f5..805af253367 100644 --- a/doc/university/support/README.md +++ b/doc/university/support/README.md @@ -37,7 +37,7 @@ Continue to look over remaining portions of the [University Overview](../README. Get your development machine ready to familiarize yourself with the codebase, the components, and to be prepared to reproduce issues that our users encounter - Install the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) - - [Setup OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap) + - [Set up OpenLDAP as part of this](https://gitlab.com/gitlab-org/gitlab-development-kit#openldap) #### Become comfortable with the Installation processes that we support diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md index 9b8a8db58e2..701533358c8 100644 --- a/doc/university/training/end-user/README.md +++ b/doc/university/training/end-user/README.md @@ -78,9 +78,9 @@ Workshop Time! ```bash git config --global user.name "Your Name" git config --global user.email you@example.com -``` +``` -- If you don't use the global flag you can setup a different author for +- If you don't use the global flag you can set up a different author for each project - Check settings with: @@ -107,14 +107,14 @@ cd ~/development -or- mkdir ~/workspace -cd ~/workspace +cd ~/workspace ``` --- ## Git Basics ---- +--- ### Git Workflow @@ -136,7 +136,7 @@ cd ~/workspace issue tracking, Merge Requests, and other features. - The hosted version of GitLab is gitlab.com ---- +--- ### New Project @@ -150,12 +150,12 @@ cd ~/workspace ### Git and GitLab basics 1. Edit `edit_this_file.rb` in `training-examples` -2. See it listed as a changed file (working area) -3. View the differences -4. Stage the file -5. Commit -6. Push the commit to the remote -7. View the git log +1. See it listed as a changed file (working area) +1. View the differences +1. Stage the file +1. Commit +1. Push the commit to the remote +1. View the git log --- @@ -169,14 +169,14 @@ git push origin master git log ``` ---- +--- ### Feature Branching 1. Create a new feature branch called `squash_some_bugs` -2. Edit `bugs.rb` and remove all the bugs. -3. Commit -4. Push +1. Edit `bugs.rb` and remove all the bugs. +1. Commit +1. Push --- @@ -250,16 +250,17 @@ git push origin squash_some_bugs --- ### Example Plan + 1. Checkout a new branch and edit conflicts.rb. Add 'Line4' and 'Line5'. -2. Commit and push -3. Checkout master and edit conflicts.rb. Add 'Line6' and 'Line7' below 'Line3'. -4. Commit and push to master -5. Create a merge request and watch it fail -6. Rebase our new branch with master -7. Fix conflicts on the conflicts.rb file. -8. Stage the file and continue rebasing -9. Force push the changes -10. Finally continue with the Merge Request +1. Commit and push +1. Checkout master and edit conflicts.rb. Add 'Line6' and 'Line7' below 'Line3'. +1. Commit and push to master +1. Create a merge request and watch it fail +1. Rebase our new branch with master +1. Fix conflicts on the conflicts.rb file. +1. Stage the file and continue rebasing +1. Force push the changes +1. Finally continue with the Merge Request --- @@ -362,15 +363,15 @@ Don't reset after pushing ### Reset Workflow 1. Edit file again 'edit_this_file.rb' -2. Check status -3. Add and commit with wrong message -4. Check log -5. Amend commit -6. Check log -7. Soft reset -8. Check log -9. Pull for updates -10. Push changes +1. Check status +1. Add and commit with wrong message +1. Check log +1. Amend commit +1. Check log +1. Soft reset +1. Check log +1. Pull for updates +1. Push changes ---- @@ -389,9 +390,9 @@ Don't reset after pushing ### Note -git revert vs git reset -Reset removes the commit while revert removes the changes but leaves the commit -Revert is safer considering we can revert a revert +git revert vs git reset +Reset removes the commit while revert removes the changes but leaves the commit +Revert is safer considering we can revert a revert # Changed file diff --git a/doc/university/training/topics/additional_resources.md b/doc/university/training/topics/additional_resources.md index d01634df744..4871372d105 100644 --- a/doc/university/training/topics/additional_resources.md +++ b/doc/university/training/topics/additional_resources.md @@ -4,9 +4,9 @@ comments: false # Additional Resources -1. GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) -2. GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) -3. Pro git book [http://git-scm.com/book](http://git-scm.com/book) -4. Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) -5. Code School tutorial [http://try.github.io/](http://try.github.io/) -6. Contact Us at `subscribers@gitlab.com` +1. GitLab Documentation: <http://docs.gitlab.com>. +1. GUI Clients: <http://git-scm.com/downloads/guis>. +1. Pro Git book: <http://git-scm.com/book>. +1. Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>. +1. Code School tutorial: <http://try.github.io/>. +1. Contact us at `subscribers@gitlab.com`. diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md index 01e93e4dcb0..4848d0412c1 100644 --- a/doc/university/training/topics/bisect.md +++ b/doc/university/training/topics/bisect.md @@ -2,7 +2,7 @@ comments: false --- -# Bisect +# Bisect ---------- @@ -17,11 +17,11 @@ comments: false ## Bisect 1. Start the bisect process -2. Enter the bad revision (usually latest commit) -3. Enter a known good revision (commit/branch) -4. Run code to see if bug still exists -5. Tell bisect the result -6. Repeat the previous 2 items until you find the offending commit +1. Enter the bad revision (usually latest commit) +1. Enter a known good revision (commit/branch) +1. Run code to see if bug still exists +1. Tell bisect the result +1. Repeat the previous 2 items until you find the offending commit ---------- diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index 1441e4b89b2..66cb08feacb 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.md @@ -35,11 +35,10 @@ comments: false ## Instantiate workflow with clone -1. Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git -2. Create a '`Workspace`' directory in your home directory. -3. Clone the '`training-examples`' project +1. Create a project in your user namespace. + - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. +1. Create a '`Workspace`' directory in your home directory. +1. Clone the '`training-examples`' project. ---------- diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index 3e39ea5cc9a..6ba6f9eb69d 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.md @@ -46,11 +46,11 @@ Git log lists commit history. It allows searching and filtering. ## Git Log Workflow 1. Change to workspace directory -2. Clone the multi runner projects -3. Change to project dir -4. Search by author -5. Search by date -6. Combine +1. Clone the multi runner projects +1. Change to project dir +1. Search by author +1. Search by date +1. Combine ---------- diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md index 9a1ce550868..071baddf508 100644 --- a/doc/university/training/topics/merge_conflicts.md +++ b/doc/university/training/topics/merge_conflicts.md @@ -16,15 +16,15 @@ comments: false ## Merge conflicts 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. -2. Commit and push -3. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. -4. Commit and push to master -5. Create a merge request and watch it fail -6. Rebase our new branch with master -7. Fix conflicts on the `conflicts.rb` file. -8. Stage the file and continue rebasing -9. Force push the changes -10. Finally continue with the Merge Request +1. Commit and push. +1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. +1. Commit and push to master. +1. Create a merge request and watch it fail. +1. Rebase our new branch with master. +1. Fix conflicts on the `conflicts.rb` file. +1. Stage the file and continue rebasing. +1. Force push the changes. +1. Finally continue with the Merge Request. ---------- diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index 11cb557651f..44304634f36 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.md @@ -41,15 +41,15 @@ comments: false ## Reset Workflow 1. Edit file again 'edit_this_file.rb' -2. Check status -3. Add and commit with wrong message -4. Check log -5. Amend commit -6. Check log -7. Soft reset -8. Check log -9. Pull for updates -10. Push changes +1. Check status +1. Add and commit with wrong message +1. Check log +1. Amend commit +1. Check log +1. Soft reset +1. Check log +1. Pull for updates +1. Push changes ---------- diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md index 315ced1a196..42eedea14e5 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -66,12 +66,12 @@ stashes. ## Git Stash 1. Modify a file -2. Stage file -3. Stash it -4. View our stash list -5. Confirm no pending changes through status -5. Apply with pop -6. View list to confirm changes +1. Stage file +1. Stash it +1. View our stash list +1. Confirm no pending changes through status +1. Apply with pop +1. View list to confirm changes ---------- diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md index 6333ceedbd7..14c39457838 100644 --- a/doc/university/training/topics/tags.md +++ b/doc/university/training/topics/tags.md @@ -22,7 +22,7 @@ comments: false **Additional resources** -[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) +<https://git-scm.com/book/en/Git-Basics-Tagging> ---------- diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index dccb6cbf071..ca3f777f403 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -6,91 +6,90 @@ comments: false --- -# Agenda +## Agenda -1. Brief history of Git -1. GitLab walkthrough -1. Configure your environment -1. Workshop +1. Brief history of Git. +1. GitLab walkthrough. +1. Configure your environment. +1. Workshop. --- -# Git introduction +## Git introduction -https://git-scm.com/about +<https://git-scm.com/about> -- Distributed version control - - Does not rely on connection to a central server - - Many copies of the complete history -- Powerful branching and merging -- Adapts to nearly any workflow -- Fast, reliable and stable file format +- Distributed version control. + - Does not rely on connection to a central server. + - Many copies of the complete history. +- Powerful branching and merging. +- Adapts to nearly any workflow. +- Fast, reliable and stable file format. --- -# Help! +## Help! Use the tools at your disposal when you get stuck. -- Use '`git help <command>`' command -- Use Google -- Read documentation at https://git-scm.com +- Use '`git help <command>`' command. +- Use Google. +- Read documentation at <https://git-scm.com>. --- -# GitLab Walkthrough +## GitLab Walkthrough  --- -# Configure your environment +## Configure your environment - Windows: Install 'Git for Windows' -> https://git-for-windows.github.io +> <https://git-for-windows.github.io> - Mac: Type '`git`' in the Terminal application. > If it's not installed, it will prompt you to install it. -- Debian: '`sudo apt-get install git-all`' -or Red Hat '`sudo yum install git-all`' +- Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' --- -# Git Workshop +## Git Workshop -## Overview +### Overview -1. Configure Git -1. Configure SSH Key -1. Create a project -1. Committing -1. Feature branching -1. Merge requests -1. Feedback and Collaboration +1. Configure Git. +1. Configure SSH Key. +1. Create a project. +1. Committing. +1. Feature branching. +1. Merge requests. +1. Feedback and Collaboration. --- -# Configure Git +## Configure Git -One-time configuration of the Git client +One-time configuration of the Git client: -```bash +```sh git config --global user.name "Your Name" git config --global user.email you@example.com ``` --- -# Configure SSH Key +## Configure SSH Key -```bash +```sh ssh-keygen -t rsa -b 4096 -C "you@computer-name" ``` -```bash +```sh # You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. Generating public/private rsa key pair. Enter file in which to save the key (/Users/you/.ssh/id_rsa): @@ -102,31 +101,30 @@ The key fingerprint is: 39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name ``` -Copy your public key and add it to your GitLab profile +Copy your public key and add it to your GitLab profile: -```bash +```sh cat ~/.ssh/id_rsa.pub ``` -```bash +```sh ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com ``` --- -# Create a project +## Create a project -- Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git +- Create a project in your user namespace. + - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. - Create a '`development`' or '`workspace`' directory in your home directory. -- Clone the '`training-examples`' project +- Clone the '`training-examples`' project. --- -# Commands +## Commands (project) -``` +```sh mkdir ~/development cd ~/development @@ -141,37 +139,37 @@ cd training-examples --- -# Git concepts +## Git concepts -**Untracked files** +### Untracked files New files that Git has not been told to track previously. -**Working area** +### Working area Files that have been modified but are not committed. -**Staging area** +### Staging area Modified files that have been marked to go in the next commit. --- -# Committing +## Committing -1. Edit '`edit_this_file.rb`' in '`training-examples`' -1. See it listed as a changed file (working area) -1. View the differences -1. Stage the file -1. Commit -1. Push the commit to the remote -1. View the git log +1. Edit '`edit_this_file.rb`' in '`training-examples`'. +1. See it listed as a changed file (working area). +1. View the differences. +1. Stage the file. +1. Commit. +1. Push the commit to the remote. +1. View the git log. --- -# Commands +## Commands (committing) -``` +```sh # Edit `edit_this_file.rb` git status git diff @@ -183,29 +181,29 @@ git log --- -# Feature branching +## Feature branching -- Efficient parallel workflow for teams -- Develop each feature in a branch -- Keeps changes isolated -- Consider a 1-to-1 link to issues -- Push branches to the server frequently - - Hint: This is a cheap backup for your work-in-progress code +- Efficient parallel workflow for teams. +- Develop each feature in a branch. +- Keeps changes isolated. +- Consider a 1-to-1 link to issues. +- Push branches to the server frequently. + - Hint: This is a cheap backup for your work-in-progress code. --- -# Feature branching +## Feature branching steps -1. Create a new feature branch called 'squash_some_bugs' +1. Create a new feature branch called 'squash_some_bugs'. 1. Edit '`bugs.rb`' and remove all the bugs. -1. Commit -1. Push +1. Commit. +1. Push. --- -# Commands +## Commands (feature branching) -``` +```sh git checkout -b squash_some_bugs # Edit `bugs.rb` git status @@ -216,51 +214,50 @@ git push origin squash_some_bugs --- -# Merge requests +## Merge requests -- When you want feedback create a merge request -- Target is the ‘default’ branch (usually master) -- Assign or mention the person you would like to review -- Add 'WIP' to the title if it's a work in progress -- When accepting, always delete the branch -- Anyone can comment, not just the assignee -- Push corrections to the same branch +- When you want feedback create a merge request. +- Target is the ‘default’ branch (usually master). +- Assign or mention the person you would like to review. +- Add 'WIP' to the title if it's a work in progress. +- When accepting, always delete the branch. +- Anyone can comment, not just the assignee. +- Push corrections to the same branch. --- -# Merge requests +## Merge requests steps -**Create your first merge request** +Create your first merge request: -1. Use the blue button in the activity feed -1. View the diff (changes) and leave a comment -1. Push a new commit to the same branch -1. Review the changes again and notice the update +1. Use the blue button in the activity feed. +1. View the diff (changes) and leave a comment. +1. Push a new commit to the same branch. +1. Review the changes again and notice the update. --- -# Feedback and Collaboration +## Feedback and Collaboration -- Merge requests are a time for feedback and collaboration -- Giving feedback is hard -- Be as kind as possible -- Receiving feedback is hard -- Be as receptive as possible -- Feedback is about the best code, not the person. You are not your code +- Merge requests are a time for feedback and collaboration. +- Giving feedback is hard. +- Be as kind as possible. +- Receiving feedback is hard. +- Be as receptive as possible. +- Feedback is about the best code, not the person. You are not your code. --- -# Feedback and Collaboration +## Feedback and Collaboration resources Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: -[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) +<https://github.com/thoughtbot/guides/tree/master/code-review>. -See GitLab merge requests for examples: -[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) +See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>. --- -# Explore GitLab projects +## Explore GitLab projects  @@ -274,31 +271,29 @@ See GitLab merge requests for examples: --- -# Tags +## Tags -- Useful for marking deployments and releases -- Annotated tags are an unchangeable part of Git history -- Soft/lightweight tags can be set and removed at will -- Many projects combine an annotated release tag with a stable branch -- Consider setting deployment/release tags automatically +- Useful for marking deployments and releases. +- Annotated tags are an unchangeable part of Git history. +- Soft/lightweight tags can be set and removed at will. +- Many projects combine an annotated release tag with a stable branch. +- Consider setting deployment/release tags automatically. --- -# Tags - -- Create a lightweight tag -- Create an annotated tag -- Push the tags to the remote repository +## Tags steps -**Additional resources** +1. Create a lightweight tag. +1. Create an annotated tag. +1. Push the tags to the remote repository. -[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) +Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>. --- -# Commands +## Commands (tags) -``` +```sh git checkout master # Lightweight tag @@ -313,31 +308,31 @@ git push origin --tags --- -# Merge conflicts +## Merge conflicts -- Happen often -- Learning to fix conflicts is hard -- Practice makes perfect +- Happen often. +- Learning to fix conflicts is hard. +- Practice makes perfect. - Force push after fixing conflicts. Be careful! --- -# Merge conflicts +## Merge conflicts steps 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. -1. Commit and push +1. Commit and push. 1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. -1. Commit and push to master -1. Create a merge request +1. Commit and push to master. +1. Create a merge request. --- -# Merge conflicts +## Merge conflicts commands After creating a merge request you should notice that conflicts exist. Resolve the conflicts locally by rebasing. -``` +```sh git rebase master # Fix conflicts by editing the files. @@ -350,7 +345,7 @@ git push origin <branch> -f --- -# Rebase with squash +## Rebase with squash You may end up with a commit log that looks like this: @@ -368,11 +363,11 @@ Squash these in to meaningful commits using an interactive rebase. --- -# Rebase with squash +## Rebase with squash commands Squash the commits on the same branch we used for the merge conflicts step. -``` +```sh git rebase -i master ``` @@ -380,17 +375,17 @@ In the editor, leave the first commit as 'pick' and set others to 'fixup'. --- -# Questions? +## Questions?  Thank you for your hard work! -**Additional Resources** +## Additional Resources -GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) -GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) -Pro git book [http://git-scm.com/book](http://git-scm.com/book) -Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) -Code School tutorial [http://try.github.io/](http://try.github.io/) -Contact Us at `subscribers@gitlab.com` +- GitLab Documentation: <http://docs.gitlab.com/>. +- GUI Clients: <http://git-scm.com/downloads/guis>. +- Pro Git book: <http://git-scm.com/book>. +- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>. +- Code School tutorial: <http://try.github.io/>. +- Contact us at `subscribers@gitlab.com`. diff --git a/doc/update/11.2-to-11-3.md b/doc/update/11.2-to-11.3.md index d77f879ee57..f2b8efc3e6e 100644 --- a/doc/update/11.2-to-11-3.md +++ b/doc/update/11.2-to-11.3.md @@ -235,7 +235,7 @@ There might be configuration options available for [`gitlab.yml`][yaml]. View th ```sh cd /home/git/gitlab -git diff origin/11-1-stable:config/gitlab.yml.example origin/11-3-stable:config/gitlab.yml.example +git diff origin/11-2-stable:config/gitlab.yml.example origin/11-3-stable:config/gitlab.yml.example ``` #### Nginx configuration @@ -246,10 +246,10 @@ Ensure you're still up-to-date with the latest NGINX configuration changes: cd /home/git/gitlab # For HTTPS configurations -git diff origin/11-1-stable:lib/support/nginx/gitlab-ssl origin/11-3-stable:lib/support/nginx/gitlab-ssl +git diff origin/11-2-stable:lib/support/nginx/gitlab-ssl origin/11-3-stable:lib/support/nginx/gitlab-ssl # For HTTP configurations -git diff origin/11-1-stable:lib/support/nginx/gitlab origin/11-3-stable:lib/support/nginx/gitlab +git diff origin/11-2-stable:lib/support/nginx/gitlab origin/11-3-stable:lib/support/nginx/gitlab ``` If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx @@ -283,7 +283,7 @@ There might be new configuration options available for [`gitlab.default.example` ```sh cd /home/git/gitlab -git diff origin/11-1-stable:lib/support/init.d/gitlab.default.example origin/11-3-stable:lib/support/init.d/gitlab.default.example +git diff origin/11-2-stable:lib/support/init.d/gitlab.default.example origin/11-3-stable:lib/support/init.d/gitlab.default.example ``` Ensure you're still up-to-date with the latest init script changes: diff --git a/doc/update/11.3-to-11.4.md b/doc/update/11.3-to-11.4.md new file mode 100644 index 00000000000..fddec45e57a --- /dev/null +++ b/doc/update/11.3-to-11.4.md @@ -0,0 +1,378 @@ +--- +comments: false +--- + +# From 11.3 to 11.4 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-4-stable`. You can select the branch in the version +dropdown at the top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz +echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz +cd ruby-2.4.5 + +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v6.0.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v6.0.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go +1.9.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz +echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.10.3.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all --prune +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +sudo -u git -H git checkout -- locale +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-4-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-4-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### New Gitaly configuration options required + +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. + +```shell +echo ' +[gitaly-ruby] +dir = "/home/git/gitaly/ruby" + +[gitlab-shell] +dir = "/home/git/gitlab-shell" +' | sudo -u git tee -a /home/git/gitaly/config.toml +``` + +#### Check Gitaly configuration + +Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly +configuration file may contain syntax errors. The block name +`[[storages]]`, which may occur more than once in your `config.toml` +file, should be `[[storage]]` instead. + +```shell +sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml +``` + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 10. Update gitlab-pages + +#### Only needed if you use GitLab Pages. + +Install and compile gitlab-pages. GitLab-Pages uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-pages + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` + +### 11. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 12. Update configuration files + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/11-3-stable:config/gitlab.yml.example origin/11-4-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/11-3-stable:lib/support/nginx/gitlab-ssl origin/11-4-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-3-stable:lib/support/nginx/gitlab origin/11-4-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/11-3-stable:lib/support/init.d/gitlab.default.example origin/11-4-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 14. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 15. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (11.3) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.2 to 11.3](11.2-to-11.3.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/11.4-to-11.5.md b/doc/update/11.4-to-11.5.md new file mode 100644 index 00000000000..44105348d14 --- /dev/null +++ b/doc/update/11.4-to-11.5.md @@ -0,0 +1,390 @@ +--- +comments: false +--- + +# From 11.4 to 11.5 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-5-stable`. You can select the branch in the version +dropdown at the top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz +echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz +cd ruby-2.4.5 + +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v6.0.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v6.0.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go +1.9.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz +echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.10.5.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all --prune +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +sudo -u git -H git checkout -- locale +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-5-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-5-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### Check Gitaly configuration + +Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly +configuration file may contain syntax errors. The block name +`[[storages]]`, which may occur more than once in your `config.toml` +file, should be `[[storage]]` instead. + +```shell +sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml +``` + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 10. Update gitlab-pages + +#### Only needed if you use GitLab Pages. + +Install and compile gitlab-pages. GitLab-Pages uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-pages + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` + +### 11. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 12. Update configuration files + +#### New `unicorn.rb` configuration + +Note: we have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. + +- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/unicorn.rb.example but with your settings. + - In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: + +```ruby +require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" + +before_exec do |server| + # Signal application hooks that we're about to restart + Gitlab::Cluster::LifecycleEvents.do_master_restart +end + +before_fork do |server, worker| + # Signal application hooks that we're about to fork + Gitlab::Cluster::LifecycleEvents.do_before_fork +end + +after_fork do |server, worker| + # Signal application hooks of worker start + Gitlab::Cluster::LifecycleEvents.do_worker_start +end +``` + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/11-4-stable:config/gitlab.yml.example origin/11-5-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/11-4-stable:lib/support/nginx/gitlab-ssl origin/11-5-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-4-stable:lib/support/nginx/gitlab origin/11-5-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/11-4-stable:lib/support/init.d/gitlab.default.example origin/11-5-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 14. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 15. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (11.4) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.3 to 11.4](11.3-to-11.4.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/4.2-to-5.0.md b/doc/update/4.2-to-5.0.md index 311664b2bc1..d292327efbd 100644 --- a/doc/update/4.2-to-5.0.md +++ b/doc/update/4.2-to-5.0.md @@ -32,7 +32,7 @@ cd /home/git/ sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git /home/git/gitlab-shell ``` -## 3. setup gitlab-shell +## 3. set up gitlab-shell ```bash # chmod all repos and files under git diff --git a/doc/update/6.x-or-7.x-to-7.14.md b/doc/update/6.x-or-7.x-to-7.14.md index 41d0e78b7d8..61854b91aa2 100644 --- a/doc/update/6.x-or-7.x-to-7.14.md +++ b/doc/update/6.x-or-7.x-to-7.14.md @@ -20,7 +20,7 @@ database migrations for GitLab 7.2. ## Stash changes -If you [deleted the vendors folder during your original installation](https://github.com/gitlabhq/gitlabhq/issues/4883#issuecomment-31108431), [you will get an error](https://gitlab.com/gitlab-org/gitlab-ce/issues/1494) when you attempt to rebuild the assets in step 7. To avoid this, stash the changes in your GitLab working copy before starting: +If you deleted the vendors folder during your original installation, [you will get an error](https://gitlab.com/gitlab-org/gitlab-ce/issues/1494) when you attempt to rebuild the assets in step 7. To avoid this, stash the changes in your GitLab working copy before starting: git stash diff --git a/doc/update/7.5-to-7.6.md b/doc/update/7.5-to-7.6.md index f0dfb177b79..0d45a9528b9 100644 --- a/doc/update/7.5-to-7.6.md +++ b/doc/update/7.5-to-7.6.md @@ -82,7 +82,7 @@ git diff origin/7-5-stable:config/gitlab.yml.example origin/7-6-stable:config/gi * HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.6-to-7.7.md b/doc/update/7.6-to-7.7.md index 85de6b0c546..5e0b2ca7bcd 100644 --- a/doc/update/7.6-to-7.7.md +++ b/doc/update/7.6-to-7.7.md @@ -82,7 +82,7 @@ git diff origin/7-6-stable:config/gitlab.yml.example origin/7-7-stable:config/gi * HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.7-to-7.8.md b/doc/update/7.7-to-7.8.md index 7cee5f79a13..f5b1ebf0a9c 100644 --- a/doc/update/7.7-to-7.8.md +++ b/doc/update/7.7-to-7.8.md @@ -83,7 +83,7 @@ git diff origin/7-7-stable:config/gitlab.yml.example origin/7-8-stable:config/gi * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.8-to-7.9.md b/doc/update/7.8-to-7.9.md index 5a8b689dbc1..0db7698936b 100644 --- a/doc/update/7.8-to-7.9.md +++ b/doc/update/7.8-to-7.9.md @@ -85,7 +85,7 @@ git diff origin/7-8-stable:config/gitlab.yml.example origin/7-9-stable:config/gi * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/7.9-to-7.10.md b/doc/update/7.9-to-7.10.md index 99df51dbb99..782fb0736e6 100644 --- a/doc/update/7.9-to-7.10.md +++ b/doc/update/7.9-to-7.10.md @@ -81,7 +81,7 @@ git diff origin/7-9-stable:config/gitlab.yml.example origin/7-10-stable:config/g * HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. * A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. -#### Setup time zone (optional) +#### Set up time zone (optional) Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 74ce52859fa..3c73bc573a6 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -269,7 +269,7 @@ sudo systemctl daemon-reload ### 9. Install libs, migrations, etc. GitLab 9.0.11 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on on the `re2` regular expression library. To install this dependency: +a dependency on the `re2` regular expression library. To install this dependency: ```bash sudo apt-get install libre2-dev diff --git a/doc/update/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md index 3a806d2f8c8..7c9dacc9b90 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -269,7 +269,7 @@ sudo systemctl daemon-reload ### 9. Install libs, migrations, etc. GitLab 9.1.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on on the `re2` regular expression library. To install this dependency: +a dependency on the `re2` regular expression library. To install this dependency: ```bash sudo apt-get install libre2-dev diff --git a/doc/update/9.1-to-9.2.md b/doc/update/9.1-to-9.2.md index 2fff6544797..b815242ab4e 100644 --- a/doc/update/9.1-to-9.2.md +++ b/doc/update/9.1-to-9.2.md @@ -227,7 +227,7 @@ sudo systemctl daemon-reload ### 10. Install libs, migrations, etc. GitLab 9.2.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on on the `re2` regular expression library. To install this dependency: +a dependency on the `re2` regular expression library. To install this dependency: ```bash sudo apt-get install libre2-dev diff --git a/doc/update/9.2-to-9.3.md b/doc/update/9.2-to-9.3.md index 1b36cf53f4c..a58b12cb81c 100644 --- a/doc/update/9.2-to-9.3.md +++ b/doc/update/9.2-to-9.3.md @@ -263,7 +263,7 @@ sudo systemctl daemon-reload ### 12. Install libs, migrations, etc. GitLab 9.3.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on on the `re2` regular expression library. To install this dependency: +a dependency on the `re2` regular expression library. To install this dependency: ```bash sudo apt-get install libre2-dev diff --git a/doc/update/9.3-to-9.4.md b/doc/update/9.3-to-9.4.md index 210b6eb607d..0c87468334b 100644 --- a/doc/update/9.3-to-9.4.md +++ b/doc/update/9.3-to-9.4.md @@ -276,7 +276,7 @@ sudo systemctl daemon-reload ### 12. Install libs, migrations, etc. GitLab 9.4 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on on the `re2` regular expression library. To install this dependency: +a dependency on the `re2` regular expression library. To install this dependency: ```bash sudo apt-get install libre2-dev diff --git a/doc/update/README.md b/doc/update/README.md index 2c1fbc15719..d4fc0cc91bf 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -38,11 +38,12 @@ Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or patch version of GitLab without having to take your GitLab instance offline. However, for this to work there are the following requirements: -1. You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to +- You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to 9.3. -2. You have to use [post-deployment - migrations](../development/post_deployment_migrations.md). -3. You are using PostgreSQL. If you are using MySQL please look at the release +- You have to use [post-deployment + migrations](../development/post_deployment_migrations.md) (included in + zero downtime update steps below). +- You are using PostgreSQL. If you are using MySQL please look at the release post to see if downtime is required. Most of the time you can safely upgrade from a patch release to the next minor diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index a4f17746b69..2e8380aa5d8 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -83,7 +83,7 @@ sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workh ```bash cd /home/git/gitlab -sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly]" RAILS_ENV=production +sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,/home/git/repositories]" RAILS_ENV=production ``` ### 6. Update gitlab-shell to the corresponding version diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md new file mode 100644 index 00000000000..5afbf9f2934 --- /dev/null +++ b/doc/user/admin_area/custom_project_templates.md @@ -0,0 +1,25 @@ +# Custom instance-level project templates **[PREMIUM ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in [GitLab Premium](https://about.gitlab.com/pricing) 11.2. + +When you create a new project, creating it based on custom project templates is +a convenient option to bootstrap from an existing project boilerplate. +The administration setting to configure a GitLab group that serves as template +source can be found under **Admin > Settings > Custom project templates**. + +Within this section, you can configure the group where all the custom project +templates are sourced. Every project directly under the group namespace will be +available to the user if they have access to them. For example, every public +project in the group will be available to every logged user. However, +private projects will be available only if the user has view [permissions](../permissions.md) +in the project: + +- Project Owner, Maintainer, Developer, Reporter or Guest +- Is a member of the Group: Owner, Maintainer, Developer, Reporter or Guest + +Projects below subgroups of the template group are **not** supported. + +Repository and database information that are copied over to each new project are +identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). + +If you would like to set project templates at a group level, please see [Custom group-level project templates](../group/custom_project_templates.md).
\ No newline at end of file diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md new file mode 100644 index 00000000000..9205860ef1f --- /dev/null +++ b/doc/user/admin_area/diff_limits.md @@ -0,0 +1,21 @@ +# Diff limits administration + +NOTE: **Note:** +Merge requests and branch comparison views will be affected. + +CAUTION: **Caution:** +These settings are currently under experimental state. They'll +increase the resource consumption of your instance and should +be edited mindfully. + +1. Access **Admin area > Settings > General** +1. Expand **Diff limits** + +### Maximum diff patch size + +This is the content size each diff file (patch) is allowed to reach before +it's collapsed, without the possibility of being expanded. A link redirecting +to the blob view will be presented for the patches that surpass this limit. + +Patches surpassing 10% of this content size will be automatically collapsed, +but expandable (a link to expand the diff will be presented). diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 6025a5bbcda..d4853a5842e 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -49,3 +49,19 @@ and the default value is `30 days`. On GitLab.com they This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts-expire_in). To disable the expiration, set it to `0`. The default unit is in seconds. + +## Archive jobs **[CORE ONLY]** + +Archiving jobs is useful for reducing the CI/CD footprint on the system by +removing some of the capabilities of the jobs (metadata needed to run the job), +but persisting the traces and artifacts for auditing purposes. + +To set the duration for which the jobs will be considered as old and expired: + +1. Go to **Admin area > Settings > CI/CD > Continuous Integration and Deployment**. +1. Change the value of "Archive jobs". +1. Hit **Save changes** for the changes to take effect. + +Once that time passes, the jobs will be archived and no longer able to be +retried. Make it empty to never expire jobs. It has to be no less than 1 day, +for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. diff --git a/doc/user/admin_area/settings/email.md b/doc/user/admin_area/settings/email.md index 7c9e5bf882e..50c318a4969 100644 --- a/doc/user/admin_area/settings/email.md +++ b/doc/user/admin_area/settings/email.md @@ -3,3 +3,20 @@ ## Custom logo The logo in the header of some emails can be customized, see the [logo customization section](../../../customization/branded_page_and_email_header.md). + +## Custom hostname for private commit emails + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22560) in GitLab 11.5. + +This configuration option sets the email hostname for [private commit emails](../../profile/index.md#private-commit-email), +and it's, by default, set to `users.noreply.YOUR_CONFIGURED_HOSTNAME`. + +In order to change this option: + +1. Go to **Admin area > Settings** (`/admin/application_settings`). +1. Under the **Email** section, change the **Custom hostname (for private commit emails)** field. +1. Hit **Save** for the changes to take effect. + +NOTE: **Note**: Once the hostname gets configured, every private commit email using the previous hostname, will not get +recognized by GitLab. This can directly conflict with certain [Push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html) such as +`Check whether author is a GitLab user` and `Check whether committer is the current authenticated user`. diff --git a/doc/user/admin_area/settings/img/import_sources.png b/doc/user/admin_area/settings/img/import_sources.png Binary files differnew file mode 100644 index 00000000000..4257f02448f --- /dev/null +++ b/doc/user/admin_area/settings/img/import_sources.png diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 9801a0a14ed..d3ecfd42903 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -4,7 +4,7 @@ You can block email addresses of specific domains, or whitelist only some specific domains via the **Application Settings** in the Admin area. >**Note**: These restrictions are only applied during sign-up. An admin is -able to add add a user through the admin panel with a disallowed domain. Also +able to add a user through the admin panel with a disallowed domain. Also note that the users can change their email addresses after signup to disallowed domains. diff --git a/doc/user/admin_area/settings/terms.md b/doc/user/admin_area/settings/terms.md index aa817c9a209..e2290bf0598 100644 --- a/doc/user/admin_area/settings/terms.md +++ b/doc/user/admin_area/settings/terms.md @@ -35,17 +35,17 @@ continue their registration afterwards. ## Accepting terms -When this feature was enabled, the users that have not accepted the +When this feature is enabled, the users that have not accepted the terms of service will be presented with a screen where they can either accept or decline the terms.  -When the user accepts the terms, they will be directed to where they +If the user accepts the terms, they will be directed to where they were going. After a sign-in or sign-up this will most likely be the dashboard. -When the user was already logged in when the feature was turned on, +If the user was already logged in when the feature was turned on, they will be asked to accept the terms on their next interaction. -When a user declines the terms, they will be signed out. +If a user declines the terms, they will be signed out. diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 35a9d7adb28..bd0155dc712 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -42,7 +42,11 @@ not send any project names, usernames, or any other specific data. The information from the usage ping is not anonymous, it is linked to the hostname of the instance. -You can view the exact JSON payload in the administration panel. +You can view the exact JSON payload in the administration panel. To view the payload: + +1. Go to the **Admin area** (spanner symbol on the top bar). +1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**. +1. Expand **Usage statistics** and click on the **Preview payload** button. ### Deactivate the usage ping diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 3d38588a9ed..6a1e8004f87 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,5 +1,12 @@ # Visibility and access controls +## Import sources + +Choose from which hosting sites the users can +[import their projects](../../project/import/index.md). + + + ## Enabled Git access protocols > [Introduced][ce-4696] in GitLab 8.10. diff --git a/doc/user/discussions/img/index_notes_filters.png b/doc/user/discussions/img/index_notes_filters.png Binary files differnew file mode 100644 index 00000000000..977a3770c05 --- /dev/null +++ b/doc/user/discussions/img/index_notes_filters.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1b3fb9db4ec..0f89d261ff6 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -273,6 +273,26 @@ edit existing comments. Non-team members are restricted from adding or editing c Additionally locked issues can not be reopened. +## Filtering notes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. + +For issues with many comments like activity notes and user comments, sometimes +finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues. + +From a merge request's **Discussion** tab, or from an issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options: + +- **Show all activity**: displays all user comments and system notes +(issue updates, mentions from other issues, changes to the description, etc). +- **Show comments only**: only displays user comments in the list. +- **Show history only**: only displays activity notes. + + + +Once you select one of the filters in a given issue or MR, GitLab will save +your preference, so that it will persist when you visit the same page again +from any device you're logged into. + [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 [ce-7527]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7527 @@ -281,7 +301,7 @@ Additionally locked issues can not be reopened. [ce-14053]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14053 [ce-14061]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14061 [ce-14531]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14531 -[ce-31847]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31847 +[ce-31847]: https://gitlab.com/gitlab-org/gitlab-ce/issues/31847 [resolve-discussion-button]: img/resolve_discussion_button.png [resolve-comment-button]: img/resolve_comment_button.png [discussion-view]: img/discussion_view.png diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 0b9395914f9..e14e716a5eb 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -221,7 +221,7 @@ and the following environment variables: ## Cron jobs -Periodically executed jobs by Sidekiq, to self-heal Gitlab, do external +Periodically executed jobs by Sidekiq, to self-heal GitLab, do external synchronizations, run scheduled pipelines, etc.: | Setting | GitLab.com | Default | diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md new file mode 100644 index 00000000000..eaf0273050b --- /dev/null +++ b/doc/user/group/custom_project_templates.md @@ -0,0 +1,23 @@ +# Custom group-level project templates **[PREMIUM ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6. + +When you create a new project, creating it based on custom project templates is +a convenient option to bootstrap from an existing project boilerplate. +The group-level setting to configure a GitLab group that serves as template +source can be found under **Group > Settings > General > Custom project templates**. + +Within this section, you can configure the group where all the custom project +templates are sourced. Every project directly under the group namespace will be +available to the user if they have access to them. For example, every public +project in the group will be available to every logged in user. However, +private projects will be available only if the user has view [permissions](../permissions.md) +in the project. That is, users with Owner, Maintainer, Developer, Reporter or Guest roles for projects, +or for groups to which the project belongs. + +Projects of nested subgroups of a selected template source cannot be used. + +Repository and database information that are copied over to each new project are +identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). + +If you would like to set project templates at an instance level, please see [Custom instance-level project templates](../admin_area/custom_project_templates.md).
\ No newline at end of file diff --git a/doc/user/group/img/access_requests_management.png b/doc/user/group/img/access_requests_management.png Binary files differindex 36deaa89a70..7de6a1c0a5e 100644 --- a/doc/user/group/img/access_requests_management.png +++ b/doc/user/group/img/access_requests_management.png diff --git a/doc/user/group/img/add_new_members.png b/doc/user/group/img/add_new_members.png Binary files differindex 99b8e52ea13..4431c9fbe0b 100644 --- a/doc/user/group/img/add_new_members.png +++ b/doc/user/group/img/add_new_members.png diff --git a/doc/user/group/img/create_new_group_info.png b/doc/user/group/img/create_new_group_info.png Binary files differindex 1ac26fb08d9..c2e6ed43c5b 100644 --- a/doc/user/group/img/create_new_group_info.png +++ b/doc/user/group/img/create_new_group_info.png diff --git a/doc/user/group/img/create_new_project_from_group.png b/doc/user/group/img/create_new_project_from_group.png Binary files differindex 553cd0759aa..b6286ac7800 100644 --- a/doc/user/group/img/create_new_project_from_group.png +++ b/doc/user/group/img/create_new_project_from_group.png diff --git a/doc/user/group/img/group_settings.png b/doc/user/group/img/group_settings.png Binary files differindex 1705bf4ce8e..f3a75f1bde8 100644 --- a/doc/user/group/img/group_settings.png +++ b/doc/user/group/img/group_settings.png diff --git a/doc/user/group/img/request_access_button.png b/doc/user/group/img/request_access_button.png Binary files differindex 54b490a3bb2..4d73990ec7e 100644 --- a/doc/user/group/img/request_access_button.png +++ b/doc/user/group/img/request_access_button.png diff --git a/doc/user/group/img/select_group_dropdown.png b/doc/user/group/img/select_group_dropdown.png Binary files differindex 79eca5d94d5..8c03ffffbde 100644 --- a/doc/user/group/img/select_group_dropdown.png +++ b/doc/user/group/img/select_group_dropdown.png diff --git a/doc/user/group/img/withdraw_access_request_button.png b/doc/user/group/img/withdraw_access_request_button.png Binary files differindex 4365f7fa788..a5fe78eb090 100644 --- a/doc/user/group/img/withdraw_access_request_button.png +++ b/doc/user/group/img/withdraw_access_request_button.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index b14377a72b6..36b9318c0e0 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -252,12 +252,23 @@ level of members in group. Learn more about [Member Lock](https://docs.gitlab.com/ee/user/group/index.html#member-lock). +#### Group-level file templates **[PREMIUM]** + +Group-level file templates allow you to share a set of templates for common file +types with every project in a group. + +Learn more about [Group-level file templates](https://docs.gitlab.com/ee/user/group/index.html#group-level-file-templates-premium). + +#### Group-level project templates **[PREMIUM]** + +Define project templates at a group-level by setting a group as a template source. +[Learn more about group-level project templates](custom_project_templates.md). + ### Advanced settings - **Projects**: view all projects within that group, add members to each project, access each project's settings, and remove any project from the same screen. - **Webhooks**: configure [webhooks](../project/integrations/webhooks.md) to your group. -- **Push rules**: configure [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html#push-rules) to your group. **[STARTER]** - **Audit Events**: view [Audit Events](https://docs.gitlab.com/ee/administration/audit_events.html#audit-events) for the group. **[STARTER ONLY]** - **Pipelines quota**: keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index b55946a788f..8db36c4a0e8 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,9 +1,8 @@ # Subgroups -> **Notes:** -> - [Introduced][ce-2772] in GitLab 9.0. -> - Not available when using MySQL as external database (support removed in -> GitLab 9.3 [due to performance reasons][issue]). +NOTE: **Note:** +[Introduced][ce-2772] in GitLab 9.0. Not available when using MySQL as external +database (support removed in GitLab 9.3 [due to performance reasons][issue]). With subgroups (aka nested groups or hierarchical groups) you can have up to 20 levels of nested groups, which among other things can help you to: @@ -79,14 +78,14 @@ structure. ## Creating a subgroup -> **Notes:** -> - You need to be an Owner of a group in order to be able to create -> a subgroup. For more information check the [permissions table][permissions]. -> - For a list of words that are not allowed to be used as group names see the -> [reserved names][reserved]. -> - Users can always create subgroups if they are explicitly added as an Owner to -> a parent group even if group creation is disabled by an administrator in their -> settings. +NOTE: **Note:** +You need to be an Owner of a group in order to be able to create a subgroup. For +more information check the [permissions table][permissions]. +For a list of words that are not allowed to be used as group names see the +[reserved names][reserved]. +Users can always create subgroups if they are explicitly added as an Owner to +a parent group even if group creation is disabled by an administrator in their +settings. To create a subgroup: @@ -136,12 +135,15 @@ From the image above, we can deduct the following things: ### Overriding the ancestor group membership ->**Note:** +NOTE: **Note:** You need to be an Owner of a group in order to be able to add members to it. +NOTE: **Note:** +A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. +Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. + To override a user's membership of an ancestor group (the first group they were -added to), simply add the user in the new subgroup again, but with different -permissions. +added to), add the user to the new subgroup again with a higher set of permissions. For example, if User0 was first added to group `group-1/group-1-1` with Developer permissions, then they will inherit those permissions in every other subgroup diff --git a/doc/user/img/color_inline_colorchip_render_gfm.png b/doc/user/img/color_inline_colorchip_render_gfm.png Binary files differnew file mode 100644 index 00000000000..6a8a674d6e0 --- /dev/null +++ b/doc/user/img/color_inline_colorchip_render_gfm.png diff --git a/doc/user/img/math_inline_sup_render_gfm.png b/doc/user/img/math_inline_sup_render_gfm.png Binary files differnew file mode 100644 index 00000000000..bf1464457bc --- /dev/null +++ b/doc/user/img/math_inline_sup_render_gfm.png diff --git a/doc/user/img/mermaid_diagram_render_gfm.png b/doc/user/img/mermaid_diagram_render_gfm.png Binary files differnew file mode 100644 index 00000000000..3b3eb3a738a --- /dev/null +++ b/doc/user/img/mermaid_diagram_render_gfm.png diff --git a/doc/user/img/task_list_ordered_render_gfm.png b/doc/user/img/task_list_ordered_render_gfm.png Binary files differnew file mode 100644 index 00000000000..fdff8a9886c --- /dev/null +++ b/doc/user/img/task_list_ordered_render_gfm.png diff --git a/doc/user/img/unordered_check_list_render_gfm.png b/doc/user/img/unordered_check_list_render_gfm.png Binary files differnew file mode 100644 index 00000000000..2e3fb7cbb79 --- /dev/null +++ b/doc/user/img/unordered_check_list_render_gfm.png diff --git a/doc/user/index.md b/doc/user/index.md index 649c0b664a5..08995032cb1 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -96,7 +96,7 @@ directly from GitLab. No third-party integrations needed. - [GitLab Auto Deploy](../ci/autodeploy/index.md): Deploy your application out-of-the-box with GitLab Auto Deploy. - [Review Apps](../ci/review_apps/index.md): Live-preview the changes introduced by a merge request with Review Apps. - [GitLab Pages](project/pages/index.md): Publish your static site directly from -GitLab with Gitlab Pages. You can build, test, and deploy any Static Site Generator with Pages. +GitLab with GitLab Pages. You can build, test, and deploy any Static Site Generator with Pages. - [GitLab Container Registry](project/container_registry.md): Build and deploy Docker images with Container Registry. diff --git a/doc/user/instance_statistics/convdev.md b/doc/user/instance_statistics/convdev.md index d2795e092fc..52b99b69a02 100644 --- a/doc/user/instance_statistics/convdev.md +++ b/doc/user/instance_statistics/convdev.md @@ -2,20 +2,21 @@ > [Introduced][ce-30469] in GitLab 9.3. -Conversational Development Index (ConvDev) gives you an overview of your entire -instance's feature usage, from idea to production. It looks at your usage in the -past 30 days, averaged over the number of active users in that time period. It also -provides a lead score per feature, which is calculated based on GitLab's analysis -of top performing instances, based on [usage ping data][ping] that GitLab has +The Conversational Development Index (ConvDev Index) gives you an overview of your entire +instance's adoption of [Concurrent DevOps](https://about.gitlab.com/concurrent-devops/) +from planning to monitoring. It displays the usage of these GitLab features over +the last 30 days, averaged over the number of active users in that time period. It also +provides a Lead score per feature, which is calculated based on GitLab's analysis +of top-performing instances based on [usage ping data][ping] that GitLab has collected. Your score is compared to the lead score, expressed as a percentage. -The overall index score is an average over all your feature scores. +Your overall index score is an average of all your feature score percentages.  The page also provides helpful links to articles and GitLab docs, to help you improve your scores. -Your GitLab instance's usage ping must be activated in order to use this feature. +Your GitLab instance's [usage ping][ping] must be activated in order to use this feature. Usage ping data is aggregated on GitLab's servers for analysis. Your usage information is **not sent** to any other GitLab instances. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index fb132f0613b..debebd4c081 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,36 +1,52 @@ -# Markdown +# GitLab Markdown -## GitLab Flavored Markdown (GFM) - -> **Note:** -> Not all of the GitLab-specific extensions to Markdown that are described in -> this document currently work on our documentation website. -> -> For the best result, we encourage you to check this document out as rendered -> by GitLab: [markdown.md] +This markdown guide is **valid for GitLab's system markdown entries and files**. +It is not valid for the [GitLab documentation website](https://docs.gitlab.com) +nor [GitLab's main website](https://about.gitlab.com), as they both use +[Kramdown](https://kramdown.gettalong.org) as their markdown engine. +The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). +Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference._ -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ - -_Where there are significant differences, we will try to call them out in this document._ +## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). You can use GFM in the following areas: -- comments -- issues -- merge requests -- milestones -- snippets (the snippet must be named with a `.md` extension) -- wiki pages -- markdown documents inside the repository +- Comments +- Issues +- Merge requests +- Milestones +- Snippets (the snippet must be named with a `.md` extension) +- Wiki pages +- Markdown documents inside repositories You can also use other rich text files in GitLab. You might have to install a -dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. + +> **Notes:** +> +> For the best result, we encourage you to check this document out as [rendered +> by GitLab itself](markdown.md). +> +> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown +processing of all new issues, merge requests, comments, and other Markdown content +in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the +repositories are also processed with CommonMark. Older content in issues/comments +are still processed using the [Redcarpet Ruby library][redcarpet]. +> +> The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) +in October 2018. +> +> _Where there are significant differences, we will try to call them out in this document._ ### Transitioning to CommonMark -You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. +You may have Markdown documents in your repository that were written using some +of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a +slightly stricter syntax, these documents may now display a little strangely +since we've transitioned to CommonMark. Numbered lists with nested lists in +particular can be displayed incorrectly. It is usually quite easy to fix. In the case of a nested list such as this: @@ -50,11 +66,18 @@ simply add a space to each nested item: In the documentation below, we try to highlight some of the differences. -If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: +If you have a need to view a document using RedCarpet, you can add the token +`legacy_render=1` to the end of the url, like this: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 -If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. +If you have a large volume of Markdown files, it can be tedious to determine +if they will be displayed correctly or not. You can use the +[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) +tool (not an officially supported product) to generate a list of files and +differences between how RedCarpet and CommonMark render the files. It can give +you a great idea if anything needs to be changed - many times nothing will need +to changed. ### Newlines @@ -63,7 +86,8 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newline GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. -A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: <!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> @@ -85,7 +109,9 @@ Sugar is sweet > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words -It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words: +It is not reasonable to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. +Therefore, GFM ignores multiple underscores in words: perform_complicated_task @@ -112,8 +138,8 @@ GFM will autolink almost any URL you copy and paste into your text: * https://www.google.com * https://google.com/ * ftp://ftp.us.debian.org/debian/ -* smb://foo/bar/baz -* irc://irc.freenode.net/gitlab +* <a href="smb://foo/bar/baz">smb://foo/bar/baz</a> +* <a href="irc://irc.freenode.net/gitlab">irc://irc.freenode.net/gitlab</a> * http://localhost:3000 ### Multiline Blockquote @@ -124,7 +150,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multili On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, GFM supports multiline blockquotes fenced by <code>>>></code>: -```no-highlight +``` >>> If you paste a message from somewhere else @@ -138,17 +164,13 @@ you can quote that without having to manually prepend `>` to every line! >>> ``` ->>> -If you paste a message from somewhere else - -that - -spans - -multiple lines, - -you can quote that without having to manually prepend `>` to every line! ->>> +<blockquote dir="auto"> +<p>If you paste a message from somewhere else</p> +<p>that</p> +<p>spans</p> +<p>multiple lines,</p> +<p>you can quote that without having to manually prepend <code>></code> to every line!</p> +</blockquote> ### Code and Syntax Highlighting @@ -162,7 +184,7 @@ Blocks of code are either fenced by lines with three back-ticks <code>```</code> or are indented with four spaces. Only the fenced code blocks support syntax highlighting: -```no-highlight +``` Inline `code` has `back-ticks around` it. ``` @@ -252,32 +274,34 @@ However the wrapping tags cannot be mixed as such: > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji - Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +``` +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - :zap: You can use emoji anywhere GFM is supported. :v: +:zap: You can use emoji anywhere GFM is supported. :v: - You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - 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 one of the supported codes. +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 one of the supported codes. - Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) 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: - Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. - On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. - Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +``` -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px">. Well we have a gift for you: -:zap: You can use emoji anywhere GFM is supported. :v: +<img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px"> -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px">. People will <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px"> you for that. -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 one of the supported codes. +If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px">. All you need to do is to look up one of the supported codes. -Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) 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. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px"> Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. @@ -285,8 +309,6 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. - - ### Special GitLab References GFM recognizes special references. @@ -348,7 +370,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-li You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: -```no-highlight +``` - [x] Completed task - [ ] Incomplete task - [ ] Sub-task 1 @@ -356,25 +378,18 @@ You can add task lists to issues, merge requests and comments. To create a task - [ ] Sub-task 3 ``` -- [x] Completed task -- [ ] Incomplete task - - [ ] Sub-task 1 - - [x] Sub-task 2 - - [ ] Sub-task 3 + Tasks formatted as ordered lists are supported as well: -```no-highlight +``` 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 1. [x] Sub-task 2 ``` -1. [x] Completed task -1. [ ] Incomplete task - 1. [ ] Sub-task 1 - 1. [x] Sub-task 2 + Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes. @@ -393,7 +408,10 @@ The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`. Here's a sample video: - +<div class="video-container"> + <video src="img/markdown_video.mp4" width="400" controls="true" data-setup="{}" data-title="Sample Video"></video> + <p><a href="img/markdown_video.mp4" target="_blank" rel="noopener noreferrer" title="Download 'Sample Video'">Sample Video</a></p> +</div> ### Math @@ -417,12 +435,11 @@ Example: Becomes: -This math is inline $`a^2+b^2=c^2`$. +This math is inline . This is on a separate line -```math -a^2+b^2=c^2 -``` + +<img src="./img/math_inline_sup_render_gfm.png" > _Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ @@ -450,17 +467,9 @@ Examples: `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` -Become: +Becomes: -`#F00` -`#F00A` -`#FF0000` -`#FF0000AA` -`RGB(0,255,0)` -`RGB(0%,100%,0%)` -`RGBA(0,255,0,0.7)` -`HSL(540,70%,50%)` -`HSLA(540,70%,50%,0.7)` + #### Supported formats: @@ -492,13 +501,7 @@ Example: Becomes: -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` +<img src="./img/mermaid_diagram_render_gfm.png" width="200px" height="400px"> For details see the [Mermaid official page][mermaid]. @@ -506,7 +509,7 @@ For details see the [Mermaid official page][mermaid]. ### Headers -```no-highlight +``` # H1 ## H2 ### H3 @@ -564,7 +567,7 @@ Note that the Emoji processing happens before the header IDs are generated, so t Examples: -```no-highlight +``` Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. @@ -574,7 +577,7 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Become: +Becomes: Emphasis, aka italics, with *asterisks* or _underscores_. @@ -588,7 +591,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ Examples: -```no-highlight +``` 1. First ordered list item 2. Another item * Unordered sub-list. @@ -601,7 +604,7 @@ Examples: + Or pluses ``` -Become: +Becomes: 1. First ordered list item 2. Another item @@ -619,7 +622,7 @@ each subsequent paragraph should be indented to the same level as the start of t Example: -```no-highlight +``` 1. First ordered list item Second paragraph of first item. @@ -640,7 +643,7 @@ the paragraph will appear outside the list, instead of properly indented under t Example: -```no-highlight +``` 1. First ordered list item Paragraph of first item. @@ -700,7 +703,7 @@ Examples: [logo]: img/markdown_logo.png -Become: +Becomes: Here's our logo: @@ -718,7 +721,7 @@ Reference-style: Examples: -```no-highlight +``` > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -727,7 +730,7 @@ Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` -Become: +Becomes: > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -744,7 +747,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd Examples: -```no-highlight +``` <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> @@ -754,7 +757,7 @@ Examples: </dl> ``` -Become: +Becomes: <dl> <dt>Definition list</dt> @@ -779,7 +782,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. </details> </p> -**Note:** Markdown inside these tags is supported, as long as you have a blank link after the `</summary>` tag and before the `</details>` tag, as shown in the example. _Redcarpet does not support Markdown inside these tags. You can work around this by using HTML, for example you can use `<pre><code>` tags instead of [code fences](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting)._ +**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example. _Redcarpet does not support Markdown inside these tags. You can work around this by using HTML, for example you can use `<pre><code>` tags instead of [code fences](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting)._ ```html <details> @@ -812,7 +815,7 @@ ___ Underscores ``` -Become: +Becomes: Three or more... @@ -850,7 +853,7 @@ This line is *on its own line*, because the previous line ends with two spaces. spaces. ``` -Become: +Becomes: Here's a line for us to start with. @@ -1019,7 +1022,7 @@ A link starting with a `/` is relative to the wiki root. [rouge]: http://rouge.jneen.net/ "Rouge website" [redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website" [katex]: https://github.com/Khan/KaTeX "KaTeX website" -[katex-subset]: https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX "Macros supported by KaTeX" +[katex-subset]: https://katex.org/docs/supported.html "Macros supported by KaTeX" [asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual" [commonmarker]: https://github.com/gjtorikian/commonmarker [commonmark-spec]: https://spec.commonmark.org/current/ diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 8369cff2386..c4a2d5f66e5 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -42,6 +42,8 @@ The following table depicts the various user permission levels in a project. | See a job log | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | Download and browse job artifacts | ✓ [^3] | ✓ | ✓ | ✓ | ✓ | | View wiki pages | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| View license management reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| View Security reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | Pull project code | [^1] | ✓ | ✓ | ✓ | ✓ | | Download project | [^1] | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | @@ -57,6 +59,7 @@ The following table depicts the various user permission levels in a project. | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | Manage related issues **[STARTER]** | | ✓ | ✓ | ✓ | ✓ | | Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | +| Create issue from vulnerability **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | | Lock merge request discussions | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | @@ -73,6 +76,9 @@ The following table depicts the various user permission levels in a project. | Update a container registry | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ | | Create/edit/delete project milestones | | | ✓ | ✓ | ✓ | +| View approved/blacklisted licenses **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Use security dashboard **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Dismiss vulnerability **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | @@ -89,7 +95,9 @@ The following table depicts the various user permission levels in a project. | Manage GitLab Pages | | | | ✓ | ✓ | | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | Remove GitLab Pages | | | | | ✓ | +| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core-only) | ✓ | ✓ | ✓ | ✓ | ✓ | | Manage clusters | | | | ✓ | ✓ | +| Manage license policy **[ULTIMATE]** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | @@ -98,7 +106,7 @@ The following table depicts the various user permission levels in a project. | Remove pages | | | | | ✓ | | Force push to protected branches [^4] | | | | | | | Remove protected branches [^4] | | | | | | -| View project Audit Events | | | | ✓ | ✓ | +| View project Audit Events | | | | ✓ | ✓ | ## Project features permissions @@ -110,6 +118,7 @@ which visibility level you select on project settings. - Disabled: disabled for everyone - Only team members: only team members will see even if your project is public or internal - Everyone with access: everyone can see depending on your project visibility level +- Everyone: enabled for everyone (only available for GitLab Pages) ### Protected branches @@ -198,7 +207,7 @@ They will, like usual users, receive a role in the project or group with all the abilities that are mentioned in the table above. They cannot however create groups or projects, and they have the same access as logged out users in all other cases. - + An administrator can flag a user as external [through the API](../api/users.md) or by checking the checkbox on the admin panel. As an administrator, navigate to **Admin > Users** to create a new user or edit an existing one. There, you @@ -209,7 +218,7 @@ by an administrator under **Admin > Application Settings**. ### Default internal users -The "Internal users" field allows specifying an e-mail address regex pattern to identify default internal users. +The "Internal users" field allows specifying an e-mail address regex pattern to identify default internal users. New users whose email address matches the regex pattern will be set to internal by default rather than an external collaborator. @@ -242,6 +251,7 @@ which visibility level you select on project settings. - Disabled: disabled for everyone - Only team members: only team members will see even if your project is public or internal - Everyone with access: everyone can see depending on your project visibility level +- Everyone: enabled for everyone (only available for GitLab Pages) ## GitLab CI/CD permissions diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 8838efb18fe..76f7e869ff7 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -2,18 +2,18 @@ Two-factor Authentication (2FA) provides an additional level of security to your GitLab account. Once enabled, in addition to supplying your username and -password to login, you'll be prompted for a code generated by an application on -your phone. +password to login, you'll be prompted for a code generated by your one time password +authenticator. For example, a password manager on one of your devices. By enabling 2FA, the only way someone other than you can log into your account -is to know your username and password *and* have access to your phone. +is to know your username and password *and* have access to your one time password secret. ## Overview > **Note:** When you enable 2FA, don't forget to back up your recovery codes. -In addition to a phone application, GitLab supports U2F (universal 2nd factor) devices as +In addition to one time authenticators (TOTP), GitLab supports U2F (universal 2nd factor) devices as the second factor of authentication. Once enabled, in addition to supplying your username and password to login, you'll be prompted to activate your U2F device (usually by pressing a button on it), and it will perform secure authentication on your behalf. @@ -24,10 +24,10 @@ from other browsers. ## Enabling 2FA -There are two ways to enable two-factor authentication: via a mobile application +There are two ways to enable two-factor authentication: via a one time password authenticator or a U2F device. -### Enable 2FA via mobile application +### Enable 2FA via one time password authenticator **In GitLab:** @@ -69,7 +69,7 @@ of recovery codes. 1. Go to **Account**. 1. Click **Enable Two-Factor Authentication**. 1. Plug in your U2F device. -1. Click on **Setup New U2F Device**. +1. Click on **Set up New U2F Device**. 1. A light will start blinking on your device. Activate it by pressing its button. You will see a message indicating that your device was successfully set up. @@ -82,10 +82,12 @@ Click on **Register U2F Device** to complete the process. > **Note:** Recovery codes are not generated for U2F devices. -Should you ever lose access to your phone, you can use one of the ten provided -backup codes to login to your account. We suggest copying or printing them for -storage in a safe place. **Each code can be used only once** to log in to your -account. +Should you ever lose access to your one time password authenticator, you can use one of the ten provided +backup codes to login to your account. We suggest copying them, printing them, or downloading them using +the **Download codes** button for storage in a safe place. + +CAUTION: **Caution:** +Each code can be used only once to log in to your account. If you lose the recovery codes or just want to generate new ones, you can do so [using SSH](#generate-new-recovery-codes-using-ssh). @@ -98,7 +100,7 @@ be presented with a second prompt, depending on which type of 2FA you've enabled ### Log in via mobile application -Enter the pin from your phone's application or a recovery code to log in. +Enter the pin from your one time password authenticator's application or a recovery code to log in.  @@ -156,7 +158,7 @@ authentication. If an SSH key is added to your GitLab account, you can generate a new set of recovery codes with SSH. 1. Run `ssh git@gitlab.example.com 2fa_recovery_codes`. -2. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. +1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. ``` bash $ ssh git@gitlab.example.com 2fa_recovery_codes @@ -183,7 +185,7 @@ a new set of recovery codes with SSH. so you do not lose access to your account again. ``` -3. Go to the GitLab sign-in page and enter your username/email and password. +1. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 8604ea27f99..2f989a26725 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -31,6 +31,7 @@ From there, you can: - Update your personal information - Set a [custom status](#current-status) for your profile +- Manage your [commit email](#commit-email) for your profile - Manage [2FA](account/two_factor_authentication.md) - Change your username and [delete your account](account/delete_account.md) - Manage applications that can @@ -96,13 +97,13 @@ You and GitLab admins can see your the abovementioned information on your profil > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/14078) in GitLab 11.3. -Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. +Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. To enable private contributions: 1. Navigate to your personal [profile settings](#profile-settings). -2. Check the "Private contributions" option. -3. Hit **Update profile settings**. +1. Check the "Private contributions" option. +1. Hit **Update profile settings**. ## Current status @@ -115,6 +116,13 @@ Please be aware that your status is publicly visible even if your [profile is pr To set your current status: +1. Open the user menu in the top-right corner of the navigation bar. +1. Hit **Set status**, or **Edit status** if you have already set a status. +1. Set the emoji and/or status message to your liking. +1. Hit **Set status**. Alternatively, you can also hit **Remove status** to remove your user status entirely. + +or + 1. Navigate to your personal [profile settings](#profile-settings). 1. In the text field below `Your status`, enter your status message. 1. Select an emoji from the dropdown if you like. @@ -125,6 +133,45 @@ They may however contain emoji codes such as `I'm on vacation :palm_tree:`. You can also set your current status [using the API](../../api/users.md#user-status). +## Commit email + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21598) in GitLab 11.4. + +A commit email, is the email that will be displayed in every Git-related action done through the +GitLab interface. + +You are able to select from the list of your own verified emails which email you want to use as the commit email. + +To change it: + +1. Open the user menu in the top-right corner of the navigation bar. +1. Hit **Commit email** selection box. +1. Select any of the verified emails. +1. Hit **Update profile settings**. + +### Private commit email + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22560) in GitLab 11.5. + +GitLab provides the user with an automatically generated private commit email option, +which allows the user to not make their email information public. + +To enable this option: + +1. Open the user menu in the top-right corner of the navigation bar. +1. Hit **Commit email** selection box. +1. Select **Use a private email** option. +1. Hit **Update profile settings**. + +Once this option is enabled, every Git-related action will be performed using the private commit email. + +In order to stay fully annonymous, you can also copy this private commit email +and configure it on your local machine using the following command: + +``` +git config --global user.email "YOUR_PRIVATE_COMMIT_EMAIL" +``` + ## Troubleshooting ### Why do I keep getting signed out? diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 25d6c34409c..7d55048c994 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -45,16 +45,14 @@ the following table. | Scope | Description | | ----- | ----------- | |`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). | -| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. | -| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). | +| `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. | +| `read_registry` | Allows to read (pull) [container registry] images if a project is private and authorization is required ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3). | | `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). | -| `read_repository` | Allows read-access to the repository through git clone. | +| `read_repository` | Allows read-access (pull) to the repository through git clone. | [2fa]: ../account/two_factor_authentication.md [api]: ../../api/README.md [ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749 -[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951 -[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845 [ce-14838]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838 [container registry]: ../project/container_registry.md [users]: ../../api/users.md diff --git a/doc/user/project/clusters/eks_and_gitlab/img/new_project.png b/doc/user/project/clusters/eks_and_gitlab/img/new_project.png Binary files differdeleted file mode 100644 index 02afc099f10..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/new_project.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png b/doc/user/project/clusters/eks_and_gitlab/img/rbac.png Binary files differnew file mode 100644 index 00000000000..517e4f7ca44 --- /dev/null +++ b/doc/user/project/clusters/eks_and_gitlab/img/rbac.png diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 10f0cdb333e..fa2ed21f980 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -1,72 +1,171 @@ ---- -author: Joshua Lambert -author_gitlab: joshlambert -level: intermediate -article_type: tutorial -date: 2018-06-05 ---- - # Connecting and deploying to an Amazon EKS cluster -## Introduction +In this tutorial, we will show how to integrate an +[Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin +deploying applications. -In this tutorial, we will show how easy it is to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab, and begin deploying applications. +## Introduction For an end-to-end walkthrough we will: -1. Start with a new project based on the sample Ruby on Rails template -1. Integrate an EKS cluster -1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application + +1. Start with a new project based on the sample Ruby on Rails template. +1. Integrate an EKS cluster. +1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application. You will need: -1. An account on GitLab, like [GitLab.com](https://gitlab.com) -1. An Amazon EKS cluster -1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) -If you don't have an Amazon EKS cluster, one can be created by following [the EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). +1. An account on GitLab, like [GitLab.com](https://gitlab.com). +1. An Amazon EKS cluster (with worker nodes properly configured). +1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). -## Creating a new project +If you don't have an Amazon EKS cluster, one can be created by following the +[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). -On GitLab, create a new project by clicking on the `+` icon in the top navigation bar, and selecting `New project`. +## Creating a new project - +On GitLab, create a new project by clicking on the `+` icon in the top navigation +bar and selecting **New project**. -On the new project screen, click on the `Create from template` tab, and select `Use template` for the Ruby on Rails sample project. +On the new project screen, click on the **Create from template** tab, and select +"Use template" for the Ruby on Rails sample project. -Give the project a name, and then select `Create project`. +Give the project a name, and then select **Create project**.  -## Connecting the EKS cluster +## Configuring and connecting the EKS cluster + +From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, +then click **Add an existing Kubernetes cluster**. + +A few details from the EKS cluster will be required to connect it to GitLab: + +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: + + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D + ``` + +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: + + 2.1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 2.2. Apply the service account to your cluster: + + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` + + Output: -From the left side bar, hover over `Operations` and select `Kubernetes`, then click on `Add Kubernetes cluster`, and finally `Add an existing Kubernetes cluster`. + ```bash + serviceaccount "eks-admin" created + ``` -A few details from the EKS cluster will be required to connect it to GitLab. + 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: -1. A valid Kubernetes certificate and token are needed to authenticate to the EKS cluster. A pair is created by default, which can be used. Open a shell and use `kubectl` to retrieve them: - * List the secrets with `kubectl get secrets`, and one should named similar to `default-token-xxxxx`. Copy that token name for use below. - * Get the certificate with `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D` - * Retrieve the token with `kubectl get secret <secret name> -o jsonpath="{['data']['token']}" | base64 -D`. -1. The API server endpoint is also required, so GitLab can connect to the cluster. This is displayed on the AWS EKS console, when viewing the EKS cluster details. + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` + + 2.4. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "eks-admin" created + ``` + + 2.5. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + +1. The API server endpoint is also required, so GitLab can connect to the cluster. + This is displayed on the AWS EKS console, when viewing the EKS cluster details. You now have all the information needed to connect the EKS cluster: -* Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. -* Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. -* API URL: Paste in the API server endpoint retrieved above. -* CA Certificate: Paste the certificate data from the earlier step, as-is. -* Paste the token value. Note on some versions of Kubernetes a trailing `%` is output, do not include it. -* Project namespace: This can be left blank to accept the default namespace, based on the project name. + +- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. +- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. +- API URL: Paste in the API server endpoint retrieved above. +- CA Certificate: Paste the certificate data from the earlier step, as-is. +- Paste the admin token value. +- Project namespace: This can be left blank to accept the default namespace, based on the project name.  -Click on `Add Kubernetes cluster`, the cluster is now connected to GitLab. At this point, [Kubernetes deployment variables](../#deployment-variables) will automatically be available during CI jobs, making it easy to interact with the cluster. +Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. +At this point, [Kubernetes deployment variables](../#deployment-variables) will +automatically be available during CI/CD jobs, making it easy to interact with the cluster. If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. -## Disable Role-Based Access Control (RBAC) +## Disable Role-Based Access Control (RBAC) (optional) + +When connecting a cluster via GitLab integration, you may specify whether the +cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" +checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +when interacting with it. If so, you must disable RBAC on your cluster for the +integration to work properly. -Presently, Auto DevOps and one-click app installs do not support [Kubernetes role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). Support is [being worked on](https://gitlab.com/groups/gitlab-org/-/epics/136), but in the interim RBAC must be disabled to utilize for these features. + -> **Note**: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](https://docs.gitlab.com/ee/user/project/clusters/#security-implications), and may not be desirable. +NOTE: **Note**: Disabling RBAC means that any application running in the cluster, +or user who can authenticate to the cluster, has full API access. This is a +[security concern](../index.md#security-implications), and may not be desirable. To effectively disable RBAC, global permissions can be applied granting full access: @@ -80,56 +179,100 @@ kubectl create clusterrolebinding permissive-binding \ ## Deploy services to the cluster -GitLab supports one-click deployment of helpful services to the cluster, many of which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a list of applications is now available to deploy. +GitLab supports one-click deployment of helpful services to the cluster, many of +which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a +list of applications is now available to deploy. -First install Helm Tiller, a package manager for Kubernetes. This enables deployment of the other applications. +First, install Helm Tiller, a package manager for Kubernetes. This enables +deployment of the other applications.  ### Deploying NGINX Ingress (optional) -Next, if you would like the deployed app to be reachable on the internet, deploy the Ingress. Note that this will also cause an [Elastic Load Balancer](https://aws.amazon.com/documentation/elastic-load-balancing/) to be created, which will incur additional AWS costs. +Next, if you would like the deployed app to be reachable on the internet, deploy +the Ingress. Note that this will also cause an +[Elastic Load Balancer](https://aws.amazon.com/documentation/elastic-load-balancing/) +to be created, which will incur additional AWS costs. -Once installed, you may see a `?` for `Ingress IP Address`. This is because the created ELB is available at a DNS name, not an IP address. To get the DNS name, run: `kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"`. Note, you may see a trailing `%` on some Kubernetes versions, do not include it. +Once installed, you may see a `?` for "Ingress IP Address". This is because the +created ELB is available at a DNS name, not an IP address. To get the DNS name, +run: -The Ingress is now available at this address, and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS CNAME record should be created for the desired domain name. For example `*.myekscluster.com` would point to the Ingress hostname obtained earlier. +```sh +kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}" +``` + +Note that you may see a trailing `%` on some Kubernetes versions, **do not include it**. + +The Ingress is now available at this address and will route incoming requests to +the proper service based on the DNS name in the request. To support this, a +wildcard DNS CNAME record should be created for the desired domain name. For example, +`*.myekscluster.com` would point to the Ingress hostname obtained earlier.  ### Deploying the GitLab Runner (optional) -If the project is on GitLab.com, free shared runners are available and you do not have to deploy one. If a project specific runner is desired, or there are no shared runners, it is easy to deploy one. +If the project is on GitLab.com, free shared Runners are available and you do +not have to deploy one. If a project specific Runner is desired, or there are no +shared Runners, it is easy to deploy one. -Simply click on the `Install` button for the GitLab Runner. It is important to note that the runner deployed is set as **privileged**, which means it essentially has root access to the underlying machine. This is required to build docker images, and so is on by default. +Simply click on the **Install** button for the GitLab Runner. It is important to +note that the Runner deployed is set as **privileged**, which means it essentially +has root access to the underlying machine. This is required to build docker images, +and so is on by default. ### Deploying Prometheus (optional) -GitLab is able to monitor applications automatically, utilizing [Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and memory metrics are automatically collected, and response metrics are retrieved from NGINX Ingress as well. +GitLab is able to monitor applications automatically, utilizing +[Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and +memory metrics are automatically collected, and response metrics are retrieved +from NGINX Ingress as well. -To enable monitoring, simply install Prometheus into the cluster with the `Install` button. +To enable monitoring, simply install Prometheus into the cluster with the +**Install** button. ## Create a default Storage Class -Amazon EKS does not have a default Storage Class out of the box, which means requests for persistent volumes will not be automatically fulfilled. As part of Auto DevOps, the deployed Postgres instance requests persistent storage, and without a default storage class it will fail to start. +Amazon EKS doesn't have a default Storage Class out of the box, which means +requests for persistent volumes will not be automatically fulfilled. As part +of Auto DevOps, the deployed Postgres instance requests persistent storage, +and without a default storage class it will fail to start. -If a default Storage Class does not already exist and is desired, follow Amazon's [short guide](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) to create one. +If a default Storage Class doesn't already exist and is desired, follow Amazon's +[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) +to create one. -Alternatively, disable Postgres by setting the project variable [`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. +Alternatively, disable Postgres by setting the project variable +[`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. ## Deploy the app to EKS -With RBAC disabled and services deployed, [Auto DevOps](https://docs.gitlab.com/ee/topics/autodevops/) can now be leveraged to build, test, and deploy the app. To enable, click on `Settings` in the left sidebar, then `CI/CD`. You will see a section for `Auto DevOps`, expand it. Click on the radio button to `Enable Auto DevOps`. +With RBAC disabled and services deployed, +[Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged +to build, test, and deploy the app. -If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field. Otherwise, the deployed app will not be externally available outside of the cluster. To save, click `Save changes`. +[Enable Auto DevOps](../../../../topics/autodevops/index.md##enablingdisabling-auto-devops-at-the-project-level) +if not already enabled. If a wildcard DNS entry was created resolving to the +Load Balancer, enter it in the `domain` field under the Auto DevOps settings. +Otherwise, the deployed app will not be externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, and deploy the app. +A new pipeline will automatically be created, which will begin to build, test, +and deploy the app. -After the pipeline has finished, your app will be running in EKS and available to users. Click on `CI/CD` tab in the left navigation bar, and choose `Environments`. +After the pipeline has finished, your app will be running in EKS and available +to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. +You will see a list of the environments and their deploy status, as well as +options to browse to the app, view monitoring metrics, and even access a shell +on the running pod. + +## Learn more -To learn more about Auto DevOps, review our [documentation](../../../../topics/autodevops/). +To learn more on automatically deploying your applications, +read about [Auto DevOps](../../../../topics/autodevops/index.md). diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 41768998a59..79b36e5263e 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -49,8 +49,8 @@ new Kubernetes cluster to your project: NOTE: **Note:** You need Maintainer [permissions] and above to access the Kubernetes page. -1. Click on **Add Kubernetes cluster**. -1. Click on **Create with Google Kubernetes Engine**. +1. Click **Add Kubernetes cluster**. +1. Click **Create with Google Kubernetes Engine**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. From there on, choose your cluster's settings: @@ -78,8 +78,8 @@ To add an existing Kubernetes cluster to your project: NOTE: **Note:** You need Maintainer [permissions] and above to access the Kubernetes page. -1. Click on **Add Kubernetes cluster**. -1. Click on **Add an existing Kubernetes cluster** and fill in the details: +1. Click **Add Kubernetes cluster**. +1. Click **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. @@ -92,13 +92,47 @@ To add an existing Kubernetes cluster to your project: the `ca.crt` contents here. - **Token** - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. If you don't have a service token yet, - you can follow the - [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) - to create one. You can also view or create service tokens in the - [Kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) - (under **Config > Secrets**). **The account that will issue the service token - must have admin privileges on the cluster.** + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + + 1. Create a `gitlab` service account in the `default` namespace: + + ```bash + kubectl create -f - <<EOF + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab + namespace: default + EOF + ``` + 1. Create a cluster role binding to give the `gitlab` service account + `cluster-admin` privileges: + + ```bash + kubectl create -f - <<EOF + kind: ClusterRoleBinding + apiVersion: rbac.authorization.k8s.io/v1 + metadata: + name: gitlab-cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab + namespace: default + roleRef: + kind: ClusterRole + name: cluster-admin + apiGroup: rbac.authorization.k8s.io + EOF + ``` + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. - **Project namespace** (optional) - You don't have to fill it in; by leaving it blank, GitLab will create one for you. Also: - Each project should have a unique namespace. @@ -113,6 +147,14 @@ To add an existing Kubernetes cluster to your project: After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). +To determine the: + +- API URL, run `kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'`. +- Token: + 1. List the secrets by running: `kubectl get secrets`. Note the name of the secret you need the token for. + 1. Get the token for the appropriate secret by running: `kubectl get secret <SECRET_NAME> -o jsonpath="{['data']['token']}" | base64 -D`. +- CA certificate, run `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D`. + ## Security implications CAUTION: **Important:** @@ -124,84 +166,64 @@ functionalities needed to successfully build and deploy a containerized application. Bare in mind that the same credentials are used for all the applications running on the cluster. -When GitLab creates the cluster, it enables and uses the legacy -[Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/). -The newer [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) -authorization is [experimental](#role-based-access-control-rbac). - -### Role-based access control (RBAC) **[CORE ONLY]** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21401) in GitLab 11.4. - -CAUTION: **Warning:** -The RBAC authorization is experimental. To enable it you need access to the -server where GitLab is installed. - -The support for RBAC-enabled clusters is hidden behind a feature flag. Once -the feature flag is enabled, GitLab will create the necessary service accounts -and privileges in order to install and run [GitLab managed applications](#installing-applications). - -To enable the feature flag: - -1. SSH into the server where GitLab is installed. -1. Enter the Rails console: - - **For Omnibus GitLab** - - ```sh - sudo gitlab-rails console - ``` - - **For installations from source** - - ```sh - sudo -u git -H bundle exec rails console - ``` - -1. Enable the RBAC authorization: - - ```ruby - Feature.enable('rbac_clusters') - ``` - -If you are creating a [new GKE cluster via -GitLab](#adding-and-creating-a-new-gke-cluster-via-gitlab), you will be -asked if you would like to create an RBAC-enabled cluster. Enabling this -setting will create a `gitlab` service account which will be used by -GitLab to manage the newly created cluster. To enable this, this service -account will have the `cluster-admin` privilege. - -If you are [adding an existing Kubernetes -cluster](#adding-an-existing-kubernetes-cluster), you will be asked if -the cluster you are adding is a RBAC-enabled cluster. Ensure the -token of the account has administrator privileges for the cluster. - -In both cases above, when you install Helm Tiller into your cluster, an -RBAC-enabled cluster will create a `tiller` service account, with `cluster-admin` -privileges in the `gitlab-managed-apps` namespace. This service account will be -added to the installed Helm Tiller and will be used by Helm to install and run -[GitLab managed applications](#installing-applications). - -The table below summarizes which resources will be created in a -RBAC-enabled cluster : - -| Name | Kind | Details | Created when | -| --- | --- | --- | --- | -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | - - -Helm Tiller will also create additional service accounts and other RBAC -resources for each installed application. Consult the documentation for the -Helm charts for each application for details. - -NOTE: **Note:** -Auto DevOps will not successfully complete in a cluster that only has RBAC -authorization enabled. RBAC support for Auto DevOps is planned in a -[future release](https://gitlab.com/gitlab-org/gitlab-ce/issues/44597). +## Access controls + +When creating a cluster in GitLab, you will be asked if you would like to create an +[Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/) cluster, or +a [Role-based access control (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/) one. + +Whether ABAC or RBAC is enabled, GitLab will create the necessary +service accounts and privileges in order to install and run +[GitLab managed applications](#installing-applications): + +- If GitLab is creating the cluster, a `gitlab` service account with + `cluster-admin` privileges will be created in the `default` namespace, + which will be used by GitLab to manage the newly created cluster. + +- A project service account with [`edit` + privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + will be created in the project namespace (also created by GitLab), which will + be used in [deployment jobs](#deployment-variables). + + NOTE: **Note:** + Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716) in GitLab 11.5. + +- When you install Helm Tiller into your cluster, the `tiller` service account + will be created with `cluster-admin` privileges in the `gitlab-managed-apps` + namespace. This service account will be added to the installed Helm Tiller and will + be used by Helm to install and run [GitLab managed applications](#installing-applications). + Helm Tiller will also create additional service accounts and other resources for each + installed application. Consult the documentation of the Helm charts for each application + for details. + +If you are [adding an existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster), +ensure the token of the account has administrator privileges for the cluster. + +The following sections summarize which resources will be created on ABAC/RBAC clusters. + +### Attribute-based access control (ABAC) + +| Name | Kind | Details | Created when | +| --- | --- | --- | --- | +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | + +### Role-based access control (RBAC) + +| Name | Kind | Details | Created when | +| --- | --- | --- | --- | +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | +| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating/Adding a new GKE Cluster | ### Security of GitLab Runners @@ -228,7 +250,7 @@ added directly to your configured cluster. Those applications are needed for [Review Apps](../../../ci/review_apps/index.md) and [deployments](../../../ci/environments.md). NOTE: **Note:** -The applications will be installed in a dedicated namespace called +With the exception of Knative, the applications will be installed in a dedicated namespace called `gitlab-managed-apps`. In case you have added an existing Kubernetes cluster with Tiller already installed, you should be careful as GitLab cannot detect it. By installing it via the applications will result into having it @@ -238,16 +260,23 @@ twice, which can lead to confusion during deployments. | ----------- | :------------: | ----------- | --------------- | | [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 is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a | | [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] or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | +| [Cert Manager](http://docs.cert-manager.io/en/latest/) | 11.6+ | Cert Manager is a native Kubernetes certificate management controller that helps with issuing certificates. Installing Cert Manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up to date. The email address used by Let's Encrypt registration will be taken from the GitLab user that installed Cert Manager on the cluster. | [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) | | [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | [stable/prometheus](https://github.com/helm/charts/tree/master/stable/prometheus) | | [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/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | -| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use [this](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) custom Jupyter image that installs additional useful packages on top of the base Jupyter. **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | [jupyter/jupyterhub](https://jupyterhub.github.io/helm-chart/) | +| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use [this](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) custom Jupyter image that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/amit1rrr/rubix). More information on creating executable runbooks can be found at [Nurtch Documentation](http://docs.nurtch.com/en/latest). **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | [jupyter/jupyterhub](https://jupyterhub.github.io/helm-chart/) | +| [Knative](https://cloud.google.com/knative) | 11.5+ | Knative provides a platform to create, deploy, and manage serverless workloads from a Kubernetes cluster. It is used in conjunction with, and includes [Istio](https://istio.io) to provide an external IP address for all programs hosted by Knative. You will be prompted to enter a wildcard domain where your applications will be exposed. Configure your DNS server to use the external IP address for that domain. For any application created and installed, they will be accessible as `<program_name>.<kubernetes_namespace>.<domain_name>`. This will require your kubernetes cluster to have [RBAC enabled](#role-based-access-control-rbac). | [knative/knative](https://storage.googleapis.com/triggermesh-charts) + +NOTE: **Note:** +As of GitLab 11.6 Helm Tiller will be upgraded to the latest version supported +by GitLab before installing any of the above applications. ## 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](#installing-applications). +With the following procedure, a load balancer must be installed in your cluster +to obtain the external IP address. You can use either +[Ingress](#installing-applications), or Knative's own load balancer +([Istio](https://istio.io)) if using [Knative](#installing-applications). In order to publish your web application, you first need to find the external IP address associated to your load balancer. @@ -256,21 +285,24 @@ address associated to your load balancer. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17052) in GitLab 10.6. -If you installed the Ingress [via the **Applications**](#installing-applications), +If you [installed Ingress or Knative](#installing-applications), you should see the Ingress IP address on this same page within a few minutes. If you don't see this, GitLab might not be able to determine the IP address of your ingress application in which case you should manually determine it. ### Manually determining the IP address -If the cluster is on GKE, click on the **Google Kubernetes Engine** link in the +If the cluster is on GKE, click the **Google Kubernetes Engine** link in the **Advanced settings**, or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click on **Connect** and execute +and select the proper project and cluster. Then click **Connect** and execute 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. +The output of the following examples will show the external IP address of your +cluster. This information can then be used to set up DNS entries and forwarding +rules that allow external access to your deployed applications. If you installed the Ingress [via the **Applications**](#installing-applications), run the following command: @@ -279,20 +311,23 @@ run the following command: kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' ``` -Otherwise, you can list the IP addresses of all load balancers: +For Istio/Knative, the command will be different: ```bash -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' +``` + +Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: + +```bash +kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}". ``` -> **Note**: Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: -> ```bash -> kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}". -> ``` +Otherwise, you can list the IP addresses of all load balancers: -The output is the external IP address of your cluster. This information can then -be used to set up DNS entries and forwarding rules that allow external access to -your deployed applications. +```bash +kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +``` ### Using a static IP @@ -302,7 +337,7 @@ your apps will not be able to be reached, and you'd have to change the DNS record again. In order to avoid that, you should change it into a static reserved IP. -[Read how to promote an ephemeral external IP address in GKE.](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip) +Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). ### Pointing your DNS at the cluster IP @@ -393,18 +428,22 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token. | +| `KUBE_TOKEN` | The Kubernetes token of the [project service account](#access-controls). | | `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. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. | +NOTE: **NOTE:** +Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main +service account of the cluster integration. + ## Enabling or disabling the Kubernetes cluster integration After you have successfully added your cluster information, you can enable the Kubernetes cluster integration: -1. Click the "Enabled/Disabled" switch +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. @@ -421,7 +460,7 @@ 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 Kubernetes cluster integration from your project, simply click on the +To remove the Kubernetes cluster integration from your project, simply click the **Remove integration** button. You will then be able to follow the procedure and add a Kubernetes cluster again. @@ -484,7 +523,13 @@ the deployment variables above, ensuring any pods you create are labelled with ## Read more -- [Connecting and deploying to an Amazon EKS cluster](eks_and_gitlab/index.md) +### Integrating Amazon EKS cluster with GitLab + +- Learn how to [connect and deploy to an Amazon EKS cluster](eks_and_gitlab/index.md). + +### Serverless + +- [Run serverless workloads on Kubernetes with Knative.](serverless/index.md) [permissions]: ../../permissions.md [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png Binary files differnew file mode 100644 index 00000000000..64f95ed45f0 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png diff --git a/doc/user/project/clusters/runbooks/img/demo-runbook.png b/doc/user/project/clusters/runbooks/img/demo-runbook.png Binary files differnew file mode 100644 index 00000000000..25c9df4126d --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/demo-runbook.png diff --git a/doc/user/project/clusters/runbooks/img/gitlab-variables.png b/doc/user/project/clusters/runbooks/img/gitlab-variables.png Binary files differnew file mode 100644 index 00000000000..f76ed21145f --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/gitlab-variables.png diff --git a/doc/user/project/clusters/runbooks/img/helm-install.png b/doc/user/project/clusters/runbooks/img/helm-install.png Binary files differnew file mode 100644 index 00000000000..e39094bcbf7 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/helm-install.png diff --git a/doc/user/project/clusters/runbooks/img/ingress-install.png b/doc/user/project/clusters/runbooks/img/ingress-install.png Binary files differnew file mode 100644 index 00000000000..093c61f2d0e --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/ingress-install.png diff --git a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png Binary files differnew file mode 100644 index 00000000000..2115ec9745b --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png diff --git a/doc/user/project/clusters/runbooks/img/postgres-query.png b/doc/user/project/clusters/runbooks/img/postgres-query.png Binary files differnew file mode 100644 index 00000000000..3880438c97a --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/postgres-query.png diff --git a/doc/user/project/clusters/runbooks/img/sample-runbook.png b/doc/user/project/clusters/runbooks/img/sample-runbook.png Binary files differnew file mode 100644 index 00000000000..c12ce8990a4 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/sample-runbook.png diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md new file mode 100644 index 00000000000..e1b8dc07b50 --- /dev/null +++ b/doc/user/project/clusters/runbooks/index.md @@ -0,0 +1,137 @@ +# Runbooks + +Runbooks are a collection of documented procedures that explain how to +carry out a particular process, be it starting, stopping, debugging, +or troubleshooting a particular system. + +## Overview + +Historically, runbooks took the form of a decision tree or a detailed +step-by-step guide depending on the condition or system. + +Modern implementations have introduced the concept of an "executable +runbooks", where, along with a well-defined process, operators can execute +pre-written code blocks or database queries against a given environment. + +## Nurtch Executable Runbooks + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. + +The JupyterHub app offered via GitLab’s Kubernetes integration now ships +with Nurtch’s Rubix library, providing a simple way to create DevOps +runbooks. A sample runbook is provided, showcasing common operations. + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) +for an overview of how this is acomplished in GitLab!** + +## Requirements + +To create an executable runbook, you will need: + +1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). +1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install + all the other applications. It is installed in its own pod inside the cluster which + can run the helm CLI in a safe environment. +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based + virtual hosting. It acts as a web proxy for your applications. +1. **JupyterHub** - JupyterHub is a multi-user service for managing notebooks across + a team. Jupyter Notebooks provide a web-based interactive programming environment + used for data analysis, visualization, and machine learning. + +## Nurtch + +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is +an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. +Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified +down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +for more information. + +## Configure an executable runbook with GitLab + +Follow this step-by-step guide to configure an executable runbook in GitLab using +the components outlined above and the preloaded demo runbook. + +### 1. Add a Kubernetes cluster + +Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab) +to add a Kubernetes cluster to your project. + +### 2. Install Helm Tiller, Ingress, and JupyterHub + +Once the cluster has been provisioned in GKE, click the **Install** button next to the **Helm Tiller** app. + + + +Once Tiller has been installed successfully, click the **Install** button next to the **Ingress** app. + + + +Once Ingress has been installed successfully, click the **Install** button next to the **JupyterHub** app. + + + +### 3. Login to JupyterHub and start the server + +Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click +**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This +will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**. + + + +Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. +The server will take a couple of seconds to start. + +### 4. Configure access + +In order for the runbook to access your GitLab project, you will need to enter a +[GitLab Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) +as well as your Project ID in the **Setup** section of the demo runbook. + +Double-click the **DevOps-Runbook-Demo** folder located on the left panel. + + + +Double-click the "Nurtch-DevOps-Demo.ipynb" runbook. + + + +The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find +entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows: + +```sql +PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' +PROJECT_ID = '1234567' +``` + +Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your +access token. In this example our variable name is `PRIVATE_TOKEN`. + +```sql +VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value +``` + +### 5. Configure an operation + +For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query +a postgres database. The first 4 lines of the section define the variables that are required for this query to function. + +```sql +%env DB_USER={project.variables.get('DB_USER').value} +%env DB_PASSWORD={project.variables.get('DB_PASSWORD').value} +%env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value} +%env DB_NAME={project.variables.get('DB_NAME').value} +``` + +Create the matching variables in your project's **Settings >> CI/CD >> Variables** + + + +Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be +displayed in-line as follows: + + + +You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file diff --git a/doc/user/project/clusters/serverless/img/deploy-stage.png b/doc/user/project/clusters/serverless/img/deploy-stage.png Binary files differnew file mode 100644 index 00000000000..dc2f8af9c63 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/deploy-stage.png diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differnew file mode 100644 index 00000000000..2e7655c6041 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/dns-entry.png diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png Binary files differnew file mode 100644 index 00000000000..dd576a9df35 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/install-knative.png diff --git a/doc/user/project/clusters/serverless/img/knative-app.png b/doc/user/project/clusters/serverless/img/knative-app.png Binary files differnew file mode 100644 index 00000000000..54301e1786f --- /dev/null +++ b/doc/user/project/clusters/serverless/img/knative-app.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md new file mode 100644 index 00000000000..bdbc4f7f09d --- /dev/null +++ b/doc/user/project/clusters/serverless/index.md @@ -0,0 +1,137 @@ +# Serverless + +> Introduced in GitLab 11.5. + +Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). + +## Overview + +Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, container-based applications. Knative brings some significant benefits out of the box through its main components: + +- [Build:](https://github.com/knative/build) Source-to-container build orchestration +- [Eventing:](https://github.com/knative/eventing) Management and delivery of events +- [Serving:](https://github.com/knative/serving) Request-driven compute that can scale to zero + +For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). + +## Requirements + +To run Knative on Gitlab, you will need: + +1. **Kubernetes:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). + GitLab recommends +1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install + all the other applications. +1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an + external IP address for all the applications served by Knative. You will be prompted to enter a + wildcard domain where your applications will be served. Configure your DNS server to use the + external IP address for that domain. +1. **Serverless `gitlab-ci.yml` Template:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) + to build the application and the [TriggerMesh CLI](https://github.com/triggermesh/tm), to simplify the + deployment of knative services and functions. + + Add the following `.gitlab-ci.yml` to the root of your repository (you may skip this step if using the sample + [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned below). + + ```yaml + stages: + - build + - deploy + + build: + stage: build + image: + name: gcr.io/kaniko-project/executor:debug + entrypoint: [""] + only: + - master + script: + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE + + deploy: + stage: deploy + image: gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 + only: + - master + environment: production + script: + - echo "$CI_REGISTRY_IMAGE" + - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait + ``` + +1. **Dockerfile:** Knative requires a Dockerfile in order to build your application. It should be included + at the root of your project's repo and expose port 8080. + +## Installing Knative via GitLab's Kubernetes integration + +NOTE: **Note:** +Minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. RBAC must be enabled. + +You may download the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + +1. [Add a Kubernetes cluster](https://docs.gitlab.com/ce/user/project/clusters/) and install Helm. + +1. Once Helm has been successfully installed, on the Knative app section, enter the domain to be used with + your application and click "Install". + +  + +1. After the Knative installation has finished, retrieve the Istio Ingress IP address by running the following command: + + ```bash + kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + + Output: + + ```bash + 35.161.143.124 my-machine-name:~ my-user$ + ``` + +1. The ingress is now available at this address and will route incoming requests to the proper service based on the DNS + name in the request. To support this, a wildcard DNS A record should be created for the desired domain name. For example, + if your Knative base domain is `knative.example.com` then you need to create an A record with domain `*.knative.example.com` + pointing the ip address of the ingress. + +  + +## Deploy the application with Knative + +With all the pieces in place, you can simply create a new CI pipeline to deploy the Knative application. Navigate to +**CI/CD >> Pipelines** and click the **Run Pipeline** button at the upper-right part of the screen. Then, on the +Pipelines page, click **Create pipeline**. + +## Obtain the URL for the Knative deployment + +Once all the stages of the pipeline finish, click the **deploy** stage. + + + +The output will look like this: + +```bash +Running with gitlab-runner 11.5.0~beta.844.g96d88322 (96d88322) + on docker-auto-scale 72989761 +Using Docker executor with image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Pulling docker image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Using docker image sha256:6b3f6590a9b30bd7aafb9573f047d930c70066e43955b4beb18a1eee175f6de1 for gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Running on runner-72989761-project-4342902-concurrent-0 via runner-72989761-stg-srm-1541795796-27929c96... +Cloning repository... +Cloning into '/builds/danielgruesso/knative'... +Checking out 8671ad20 as master... +Skipping Git submodules setup +$ echo "$CI_REGISTRY_IMAGE" +registry.staging.gitlab.com/danielgruesso/knative +$ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait +Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details +Waiting for ready state....... +Service domain: knative.knative-4342902.knative.info +Job succeeded +``` + +The second to last line, labeled **Service domain** contains the URL for the deployment. Copy and paste the domain into your +browser to see the app live. + +
\ No newline at end of file diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index df850d4f68d..cac64fc0cb6 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -27,7 +27,7 @@ to enable it. 1. First, ask your system administrator to enable GitLab Container Registry following the [administration documentation](../../administration/container_registry.md). If you are using GitLab.com, this is enabled by default so you can start using - the Registry immediately. Currently there is a soft (10GB) size restriction for + the Registry immediately. Currently there is a soft (10GB) size restriction for registry on GitLab.com, as part of the [repository size limit](repository/index.html#repository-size). 1. Go to your [project's General settings](settings/index.md#sharing-and-permissions) and enable the **Container Registry** feature on your project. For new @@ -119,12 +119,17 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do > Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7 If a project is private, credentials will need to be provided for authorization. -The preferred way to do this, is either by using a [personal access tokens][pat] or a [project deploy token][pdt]. +There are two ways to do this: + +- By using a [personal access token](../profile/personal_access_tokens.md). +- By using a [deploy token](../project/deploy_tokens/index.md). + The minimal scope needed for both of them is `read_registry`. -Example of using a personal access token: -``` -docker login registry.example.com -u <your_username> -p <your_access_token> +Example of using a token: + +```sh +docker login registry.example.com -u <username> -p <token> ``` ## Troubleshooting the GitLab Container Registry @@ -134,12 +139,12 @@ docker login registry.example.com -u <your_username> -p <your_access_token> 1. Check to make sure that the system clock on your Docker client and GitLab server have been synchronized (e.g. via NTP). -2. If you are using an S3-backed Registry, double check that the IAM +1. If you are using an S3-backed Registry, double check that the IAM permissions and the S3 credentials (including region) are correct. See [the sample IAM policy](https://docs.docker.com/registry/storage-drivers/s3/) for more details. -3. Check the Registry logs (e.g. `/var/log/gitlab/registry/current`) and the GitLab production logs +1. Check the Registry logs (e.g. `/var/log/gitlab/registry/current`) and the GitLab production logs for errors (e.g. `/var/log/gitlab/gitlab-rails/production.log`). You may be able to find clues there. @@ -216,7 +221,7 @@ needs to trust the mitmproxy SSL certificates for this to work. The following installation instructions assume you are running Ubuntu: -1. Install mitmproxy (see http://docs.mitmproxy.org/en/stable/install.html) +1. [Install mitmproxy](https://docs.mitmproxy.org/stable/overview-installation/). 1. Run `mitmproxy --port 9000` to generate its certificates. Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit. 1. Install the certificate from `~/.mitmproxy` to your system: @@ -245,7 +250,7 @@ This will run mitmproxy on port `9000`. In another window, run: curl --proxy http://localhost:9000 https://httpbin.org/status/200 ``` -If everything is setup correctly, you will see information on the mitmproxy window and +If everything is set up correctly, you will see information on the mitmproxy window and no errors from the curl commands. #### Running the Docker daemon with a proxy @@ -293,4 +298,4 @@ Once the right permissions were set, the error will go away. [docker-docs]: https://docs.docker.com/engine/userguide/intro/ [pat]: ../profile/personal_access_tokens.md [pdt]: ../project/deploy_tokens/index.md -[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
\ No newline at end of file +[reconfigure]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 0b9b49f326f..7688508c6ac 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -9,12 +9,12 @@ at midnight UTC and that they can be only managed by [maintainers](https://docs. ## Creating a Deploy Token -You can create as many deploy tokens as you like from the settings of your project: +You can create as many deploy tokens as you like from the settings of your project: 1. Log in to your GitLab account. 1. Go to the project you want to create Deploy Tokens for. -1. Go to **Settings** > **Repository** -1. Click on "Expand" on **Deploy Tokens** section +1. Go to **Settings** > **Repository**. +1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name and optionally an expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Click on **Create deploy token**. @@ -46,39 +46,46 @@ the following table. To download a repository using a Deploy Token, you just need to: 1. Create a Deploy Token with `read_repository` as a scope. -2. Take note of your `username` and `token` -3. `git clone` the project using the Deploy Token: +1. Take note of your `username` and `token`. +1. `git clone` the project using the Deploy Token: + ```sh + git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git + ``` -```bash -git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git -``` - -Just replace `<username>` and `<deploy_token>` with the proper values +Replace `<username>` and `<deploy_token>` with the proper values. -### Read container registry images +### Read Container Registry images To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. -2. Take note of your `username` and `token` -3. Log in to GitLab’s Container Registry using the deploy token: +1. Take note of your `username` and `token`. +1. Log in to GitLab’s Container Registry using the deploy token: -``` +```sh docker login registry.example.com -u <username> -p <deploy_token> ``` -Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply +Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply pull images from your Container Registry. ### GitLab Deploy Token > [Introduced][ce-18414] in GitLab 10.8. -There's a special case when it comes to Deploy Tokens, if a user creates one -named `gitlab-deploy-token`, the username and token of the Deploy Token will be -automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and -`CI_DEPLOY_PASSWORD`, respectively. +There's a special case when it comes to Deploy Tokens. If a user creates one +named `gitlab-deploy-token`, the username and token of the Deploy Token will be +automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and +`CI_DEPLOY_PASSWORD`, respectively. With the GitLab Deploy Token, the +`read_registry` scope is implied. + +After you create the token, you can login to the Container Registry using +those variables: + +```sh +docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY +``` [ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894 [ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845 diff --git a/doc/user/project/img/issue_board.png b/doc/user/project/img/issue_board.png Binary files differindex 925b969eebe..b46b995d8bb 100644 --- a/doc/user/project/img/issue_board.png +++ b/doc/user/project/img/issue_board.png diff --git a/doc/user/project/img/issue_board_milestone_lists.png b/doc/user/project/img/issue_board_milestone_lists.png Binary files differnew file mode 100644 index 00000000000..91926f58f87 --- /dev/null +++ b/doc/user/project/img/issue_board_milestone_lists.png diff --git a/doc/user/project/img/issue_board_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png Binary files differnew file mode 100644 index 00000000000..2288d767d8c --- /dev/null +++ b/doc/user/project/img/issue_board_summed_weights.png diff --git a/doc/user/project/img/issue_boards_core.png b/doc/user/project/img/issue_boards_core.png Binary files differnew file mode 100644 index 00000000000..8bc187482ad --- /dev/null +++ b/doc/user/project/img/issue_boards_core.png diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png Binary files differnew file mode 100644 index 00000000000..4e238ea6983 --- /dev/null +++ b/doc/user/project/img/issue_boards_premium.png diff --git a/doc/user/project/img/koding_build-in-progress.png b/doc/user/project/img/koding_build-in-progress.png Binary files differdeleted file mode 100644 index 118b97c07e1..00000000000 --- a/doc/user/project/img/koding_build-in-progress.png +++ /dev/null diff --git a/doc/user/project/img/koding_build-logs.png b/doc/user/project/img/koding_build-logs.png Binary files differdeleted file mode 100644 index b30c8375b20..00000000000 --- a/doc/user/project/img/koding_build-logs.png +++ /dev/null diff --git a/doc/user/project/img/koding_build-success.png b/doc/user/project/img/koding_build-success.png Binary files differdeleted file mode 100644 index 0f3b954abf5..00000000000 --- a/doc/user/project/img/koding_build-success.png +++ /dev/null diff --git a/doc/user/project/img/koding_commit-koding.yml.png b/doc/user/project/img/koding_commit-koding.yml.png Binary files differdeleted file mode 100644 index d921c73dc73..00000000000 --- a/doc/user/project/img/koding_commit-koding.yml.png +++ /dev/null diff --git a/doc/user/project/img/koding_different-stack-on-mr-try.png b/doc/user/project/img/koding_different-stack-on-mr-try.png Binary files differdeleted file mode 100644 index 10c7c51d2e6..00000000000 --- a/doc/user/project/img/koding_different-stack-on-mr-try.png +++ /dev/null diff --git a/doc/user/project/img/koding_edit-on-ide.png b/doc/user/project/img/koding_edit-on-ide.png Binary files differdeleted file mode 100644 index 25ca7694fe0..00000000000 --- a/doc/user/project/img/koding_edit-on-ide.png +++ /dev/null diff --git a/doc/user/project/img/koding_enable-koding.png b/doc/user/project/img/koding_enable-koding.png Binary files differdeleted file mode 100644 index 7e6c1735df2..00000000000 --- a/doc/user/project/img/koding_enable-koding.png +++ /dev/null diff --git a/doc/user/project/img/koding_landing.png b/doc/user/project/img/koding_landing.png Binary files differdeleted file mode 100644 index ac880376e09..00000000000 --- a/doc/user/project/img/koding_landing.png +++ /dev/null diff --git a/doc/user/project/img/koding_open-gitlab-from-koding.png b/doc/user/project/img/koding_open-gitlab-from-koding.png Binary files differdeleted file mode 100644 index 4235a72b36f..00000000000 --- a/doc/user/project/img/koding_open-gitlab-from-koding.png +++ /dev/null diff --git a/doc/user/project/img/koding_run-in-ide.png b/doc/user/project/img/koding_run-in-ide.png Binary files differdeleted file mode 100644 index fb5825a4010..00000000000 --- a/doc/user/project/img/koding_run-in-ide.png +++ /dev/null diff --git a/doc/user/project/img/koding_run-mr-in-ide.png b/doc/user/project/img/koding_run-mr-in-ide.png Binary files differdeleted file mode 100644 index cb1112c4034..00000000000 --- a/doc/user/project/img/koding_run-mr-in-ide.png +++ /dev/null diff --git a/doc/user/project/img/koding_set-up-ide.png b/doc/user/project/img/koding_set-up-ide.png Binary files differdeleted file mode 100644 index 033d41729a2..00000000000 --- a/doc/user/project/img/koding_set-up-ide.png +++ /dev/null diff --git a/doc/user/project/img/koding_stack-import.png b/doc/user/project/img/koding_stack-import.png Binary files differdeleted file mode 100644 index 483bfad7d6a..00000000000 --- a/doc/user/project/img/koding_stack-import.png +++ /dev/null diff --git a/doc/user/project/img/koding_start-build.png b/doc/user/project/img/koding_start-build.png Binary files differdeleted file mode 100644 index c09a6d669f0..00000000000 --- a/doc/user/project/img/koding_start-build.png +++ /dev/null diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index f23623ed485..89a9f7da852 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,6 +1,6 @@ # Migrating from ClearCase -[ClearCase](https://www-03.ibm.com/software/products/en/clearcase/) is a set of +[ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system similar to Git. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index fcd6192e82f..42da2210fab 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,6 +17,7 @@ the [GitHub rake task](../../../administration/raketasks/github_import.md) to im GitHub without the constraints of a Sidekiq worker. The following aspects of a project are imported: + * Repository description (GitLab.com & 7.7+) * Git repository data (GitLab.com & 7.7+) * Issues (GitLab.com & 7.7+) @@ -65,9 +66,9 @@ developer documentation. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: -1. A GitLab account that has logged in using the GitHub icon +- A GitLab account that has logged in using the GitHub icon \- or - -2. A GitLab account with an email address that matches the [public email address](https://help.github.com/articles/setting-your-commit-email-address-on-github/) of the GitHub user +- A GitLab account with an email address that matches the [public email address](https://help.github.com/articles/setting-your-commit-email-address-on-github/) of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. @@ -77,10 +78,10 @@ If you are using a self-hosted GitLab instance, this process requires that you h [GitHub integration][gh-import]. 1. From the top navigation bar, click **+** and select **New project**. -2. Select the **Import project** tab and then select **GitHub**. -3. Select the first button to **List your GitHub repositories**. You are redirected to a page on github.com to authorize the GitLab application. -4. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. -5. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). +1. Select the **Import project** tab and then select **GitHub**. +1. Select the first button to **List your GitHub repositories**. You are redirected to a page on github.com to authorize the GitLab application. +1. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token @@ -92,12 +93,12 @@ integration enabled, that should be the preferred method to import your reposito If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: 1. Go to https://github.com/settings/tokens/new -2. Enter a token description. -3. Select the repo scope. -4. Click **Generate token**. -5. Copy the token hash. -6. Go back to GitLab and provide the token to the GitHub importer. -7. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. +1. Enter a token description. +1. Select the repo scope. +1. Click **Generate token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the GitHub importer. +1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. Once done, you'll be taken to the importer page to select the repositories to import. ### Selecting which repositories to import @@ -107,10 +108,10 @@ your GitHub repositories are listed. 1. By default, the proposed repository namespaces match the names as they exist in GitHub, but based on your permissions, you can choose to edit these names before you proceed to import any of them. -2. Select the **Import** button next to any number of repositories, or select **Import all repositories**. -3. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will +1. Select the **Import** button next to any number of repositories, or select **Import all repositories**. +1. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will update in realtime or you can return to it later. -4. Once a repository has been imported, click its GitLab path to open its GitLab URL. +1. Once a repository has been imported, click its GitLab path to open its GitLab URL. ## Mirroring and pipeline status sharing diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 4ea35a30bbf..2f5efbe84d9 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -1,6 +1,7 @@ # Migrating projects to a GitLab instance -1. [From Bitbucket.org](bitbucket.md) +1. [From Bitbucket Cloud (aka bitbucket.org)](bitbucket.md) +1. [From Bitbucket Server (aka Stash)](bitbucket_server.md) 1. [From ClearCase](clearcase.md) 1. [From CVS](cvs.md) 1. [From FogBugz](fogbugz.md) diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 24bf6541a9d..baf410d9c9e 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -29,7 +29,7 @@ Below is a valid example of a manifest file: ```xml <manifest> - <remote review="https://android-review.googlesource.com/" /> + <remote review="https://android.googlesource.com/" /> <project path="build/make" name="platform/build" /> <project path="build/blueprint" name="platform/build/blueprint" /> @@ -38,10 +38,10 @@ Below is a valid example of a manifest file: As a result, the following projects will be created: -| GitLab | Import URL | -|---|---| -| https://gitlab.com/YOUR_GROUP/build/make | https://android-review.googlesource.com/platform/build | -| https://gitlab.com/YOUR_GROUP/build/blueprint | https://android-review.googlesource.com/platform/build/blueprint | +| GitLab | Import URL | +|:------------------------------------------------|:------------------------------------------------------------| +| `https://gitlab.com/YOUR_GROUP/build/make` | <https://android.googlesource.com/platform/build> | +| `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> | ## Importing the repositories diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index 16bc5121027..a5923986292 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -29,7 +29,7 @@ directly in a filesystem level. 1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). -1. Download SubGit from https://subgit.com/download/. +1. Download SubGit from <https://subgit.com/download/>. 1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` command will be available at `/opt/subgit-VERSION/bin/subgit`. @@ -71,7 +71,7 @@ edit $GIT_REPO_PATH/subgit/config ``` For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation.html) website. +[SubGit's documentation](https://subgit.com/documentation/) website. ### Initial translation @@ -97,7 +97,7 @@ subgit import $GIT_REPO_PATH ### SubGit licensing Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing.html). Registration is free for open +[registration](https://subgit.com/pricing/). Registration is free for open source, academic and startup projects. We're currently working on deeper GitLab/SubGit integration. You may track our @@ -179,5 +179,6 @@ git push --tags origin ``` ## Contribute to this guide + We welcome all contributions that would expand this guide with instructions on how to migrate from SVN and other version control systems. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 671804035cc..040e80d529d 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -16,8 +16,9 @@ Once you have configured and enabled Bugzilla you'll see the Bugzilla link on th ## Referencing issues in Bugzilla Issues in Bugzilla can be referenced in two alternative ways: -1. `#<ID>` where `<ID>` is a number (example `#143`). -2. `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is + +- `#<ID>` where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md new file mode 100644 index 00000000000..cb98105e0c0 --- /dev/null +++ b/doc/user/project/integrations/discord_notifications.md @@ -0,0 +1,29 @@ +# Discord Notifications service + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22684) in GitLab 11.6. + +The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. + +To send GitLab event notifications to a Discord channel, create a webhook in Discord and configure it in GitLab. + +## Create webhook + +1. Open the Discord channel you want to receive GitLab event notifications. +1. From the channel menu, select **Edit channel**. +1. Click on **Webhooks** menu item. +1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Note the URL from the **WEBHOOK URL** field. +1. Click the **Save** button. + +## Configure created webhook in GitLab + +With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. + +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings. That is, **Project > Settings > Integrations**. +1. Select the **Discord Notifications** project service to configure it. +1. Check the **Active** checkbox to turn on the service. +1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. +1. Paste the webhook URL that you copied from the create Discord webhook step. +1. Configure the remaining options and click the **Save changes** button. + +The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 47525617d95..20a71da927c 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -15,7 +15,7 @@ See also [the Hangouts Chat documentation for configuring incoming webhooks](htt ## On GitLab -When you have the **Webhook URL** for your Hangouts Chat room webhook, you can setup the GitLab service. +When you have the **Webhook URL** for your Hangouts Chat room webhook, you can set up the GitLab service. 1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings, i.e. **Project > Settings > Integrations**. 1. Select the **Hangouts Chat** project service to configure it. diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png Binary files differnew file mode 100644 index 00000000000..2c64f7bc44f --- /dev/null +++ b/doc/user/project/integrations/img/jira_api_token.png diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differnew file mode 100644 index 00000000000..20655ba3c0e --- /dev/null +++ b/doc/user/project/integrations/img/jira_api_token_menu.png diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differindex c75c11888a8..869d562ed5b 100644 --- a/doc/user/project/integrations/img/jira_service_page.png +++ b/doc/user/project/integrations/img/jira_service_page.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b3821cf8391..bc4bba40e59 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,123 +1,84 @@ -# GitLab JIRA integration +# GitLab Jira integration -GitLab can be configured to interact with [JIRA], a project management platform. +GitLab Issues are a powerful tool for discussing ideas and planning and tracking work. +However, many organizations have been using Jira for these purposes and have +extensive data and business processes built into it. -Once your GitLab project is connected to JIRA, you can reference and close the -issues in JIRA directly from GitLab. +While you can always migrate content and process from Jira to GitLab Issues, +you can also opt to continue using Jira and use it together with GitLab through +our integration. -For a use case, check out this article of [How and why to integrate GitLab with -JIRA](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-jira/how-to/2017/04/25). +Once you integrate your GitLab project with your Jira instance, you can automatically +detect and cross-reference activity between the GitLab project and any of your projects +in Jira. This includes the ability to close or transition Jira issues when the work +is completed in GitLab. -## Configuration - -Each GitLab project can be configured to connect to a different JIRA instance. That -means one GitLab project maps to _all_ JIRA projects in that JIRA instance once -the configuration is set up. Therefore, you don't have to explicitly associate -one GitLab project to any JIRA project. Once the configuration is set up, any JIRA -projects in the JIRA instance are already mapped to the GitLab project. - -If you have one JIRA instance you can pre-fill the settings page with a default -template, see the [Services Templates][services-templates] docs. - -Configuration happens via user name and password. Connecting to a JIRA server -via CAS is not possible. - -In order to enable the JIRA service in GitLab, you need to first configure the -project in JIRA and then enter the correct values in GitLab. - -### Configuring JIRA - -We need to create a user in JIRA which will have access to all projects that -need to integrate with GitLab. Login to your JIRA instance as admin and under -Administration go to User Management and create a new user. - -As an example, we'll create a user named `gitlab` and add it to `JIRA-developers` -group. - -**It is important that the user `GitLab` has write-access to projects in JIRA** - -We have split this stage in steps so it is easier to follow. - ---- - -1. Login to your JIRA instance as an administrator and under **Administration** - go to **User Management** to create a new user. - -  - - --- +Here's how the integration responds when you take the following actions in GitLab: -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in JIRA. Enter the user's name and a _valid_ e-mail address - since JIRA sends a verification e-mail to set-up the password. - _**Note:** JIRA creates the username automatically by using the e-mail - prefix. You can change it later if you want._ +- **Mention a Jira issue ID** in a commit message or MR (merge request). + - GitLab hyperlinks to the Jira issue. + - The Jira issue adds an issue link to the commit/MR in GitLab. + - The Jira issue adds a comment reflecting the comment made in GitLab, the comment author, and a link to the commit/MR in GitLab. +- **Mention that a commit or MR 'closes', 'resolves', or 'fixes' a Jira issue ID**. When the commit is made on master or the change is merged to master: + - GitLab's merge request page displays a note that it "Closed" the Jira issue, with a link to the issue. (Note: Before the merge, an MR will display that it "Closes" the Jira issue.) + - The Jira issue shows the activity and the Jira issue is closed, or otherwise transitioned. -  +You can also use [Jira's Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-298976812.html) +directly from GitLab, as covered in the article +[How and why to integrate GitLab with Jira](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-Jira/how-to/2017/04/25). - --- - -1. Now, let's create a `gitlab-developers` group which will have write access - to projects in JIRA. Go to the **Groups** tab and select **Create group**. - -  - - --- - - Give it an optional description and hit **Create group**. - -  - - --- +## Configuration -1. Give the newly-created group write access by going to - **Application access ➔ View configuration** and adding the `gitlab-developers` - group to JIRA Core. +Each GitLab project can be configured to connect to an entire Jira instance. That +means one GitLab project can interact with _all_ Jira projects in that instance, once +configured. Therefore, you will not have to explicitly associate +a GitLab project with any single Jira project. -  +If you have one Jira instance, you can pre-fill the settings page with a default +template. See the [Services Templates][services-templates] docs. - --- +Configuration happens via user name and password. Connecting to a Jira server +via CAS is not possible. -1. Add the `gitlab` user to the `gitlab-developers` group by going to - **Users ➔ GitLab user ➔ Add group** and selecting the `gitlab-developers` - group from the dropdown menu. Notice that the group says _Access_ which is - what we aim for. +In order to enable the Jira service in GitLab, you need to first configure the +project in Jira and then enter the correct values in GitLab. -  +### Configuring Jira - --- +When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step: +* [Setting up an user in JIRA server](jira_server_configuration.md) -The JIRA configuration is over. Write down the new JIRA username and its -password as they will be needed when configuring GitLab in the next section. +When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step: +* [Setting up an user in JIRA cloud](jira_cloud_configuration.md) ### Configuring GitLab > **Notes:** -> - The currently supported JIRA versions are `v6.x` and `v7.x.`. GitLab 7.8 or +> - The currently supported Jira versions are `v6.x` and `v7.x.`. GitLab 7.8 or > higher is required. -> - GitLab 8.14 introduced a new way to integrate with JIRA which greatly simplified +> - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified > the configuration options you have to enter. If you are using an older version, > [follow this documentation][jira-repo-old-docs]. > - In order to support Oracle's Access Manager, GitLab will send additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. -To enable JIRA integration in a project, navigate to the +To enable Jira integration in a project, navigate to the [Integrations page](project_services.md#accessing-the-project-services), click -the **JIRA** service, and fill in the required details on the page as described +the **Jira** service, and fill in the required details on the page as described in the table below. | Field | Description | | ----- | ----------- | -| `Web URL` | The base URL to the JIRA instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `JIRA API URL` | The base URL to the JIRA instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | -| `Username` | The user name created in [configuring JIRA step](#configuring-jira). Using the email address will cause `401 unauthorized`. | -| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | +| `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://Jira.example.com`. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | +| `Username/Email` | Created when [configuring Jira step](#configuring-jira). Use `username` for **JIRA server** or `email` for **JIRA cloud**. | +| `Password/API token` |Created in [configuring Jira step](#configuring-jira). Use `password` for **JIRA server** or `API token` for **JIRA cloud**. | +| `Transition ID` | This is the ID of a transition that moves issues to the desired state. It is possible to insert transition ids separated by `,` or `;` which means the issue will be moved to each state after another using the given order. **Closing Jira issues via commits or Merge Requests won't work if you don't set the ID correctly.** | -### Getting a transition ID +### Obtaining a transition ID -In the most recent JIRA UI, you can no longer see transition IDs in the workflow +In the most recent Jira user interface, you can no longer see transition IDs in the workflow administration UI. You can get the ID you need in either of the following ways: 1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` @@ -129,25 +90,23 @@ Note that the transition ID may vary between workflows (e.g., bug vs. story), even if the status you are changing to is the same. After saving the configuration, your GitLab project will be able to interact -with all JIRA projects in your JIRA instance and you'll see the JIRA link on the GitLab project pages that takes you to the appropriate JIRA project. +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. - + ---- +## Jira issues -## JIRA issues - -By now you should have [configured JIRA](#configuring-jira) and enabled the -[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly -you should be able to reference and close JIRA issues by just mentioning their +By now you should have [configured Jira](#configuring-jira) and enabled the +[Jira service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. -### Referencing JIRA Issues +### Referencing Jira Issues -When GitLab project has JIRA issue tracker configured and enabled, mentioning -JIRA issue in GitLab will automatically add a comment in JIRA issue with the +When GitLab project has Jira issue tracker configured and enabled, mentioning +Jira issue in GitLab will automatically add a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in JIRA issue in the +referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the format: ``` @@ -156,21 +115,19 @@ ENTITY_TITLE ``` * `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where JIRA issue was mentioned. +* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. * `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. * `PROJECT_NAME` GitLab project name. * `ENTITY_TITLE` Merge request title or commit message first line. - - ---- + -### Closing JIRA Issues +### Closing Jira Issues -JIRA issues can be closed directly from GitLab by using trigger words in +Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the JIRA issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned JIRA issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned Jira issue and immediately close it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -180,66 +137,66 @@ the same goal: - `Closes PROJECT-1` - `Fixes PROJECT-1` -where `PROJECT-1` is the issue ID of the JIRA project. +where `PROJECT-1` is the issue ID of the Jira project. > **Notes:** > - Only commits and merges into the project's default branch (usually **master**) will > close an issue in Jira. You can change your projects default branch under > [project settings](img/jira_project_settings.png). -> - The JIRA issue will not be transitioned if it has a resolution. +> - The Jira issue will not be transitioned if it has a resolution. -### JIRA issue closing example +### Jira issue closing example Let's consider the following example: -1. For the project named `PROJECT` in JIRA, we implemented a new feature +1. For the project named `PROJECT` in Jira, we implemented a new feature and created a merge request in GitLab. -1. This feature was requested in JIRA issue `PROJECT-7` and the merge request +1. This feature was requested in Jira issue `PROJECT-7` and the merge request in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the JIRA issue will be automatically closed +1. Once the merge request is merged, the Jira issue will be automatically closed with a comment and an associated link to the commit that resolved the issue. ---- - -In the following screenshot you can see what the link references to the JIRA +In the following screenshot you can see what the link references to the Jira issue look like. - - ---- + -Once this merge request is merged, the JIRA issue will be automatically closed +Once this merge request is merged, the Jira issue will be automatically closed with a link to the commit that resolved the issue. - + ---- - - + ## Troubleshooting -If things don't work as expected that's usually because you have configured -incorrectly the JIRA-GitLab integration. +If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. + +### GitLab is unable to comment on a Jira issue + +Make sure that the Jira user you set up for the integration has the +correct access permission to post comments on a Jira issue and also to transition +the issue, if you'd like GitLab to also be able to do so. +Jira issue references and update comments will not work if the GitLab issue tracker is disabled. -### GitLab is unable to comment on a ticket +### GitLab is unable to close a Jira issue -Make sure that the user you set up for GitLab to communicate with JIRA has the -correct access permission to post comments on a ticket and to also transition -the ticket, if you'd like GitLab to also take care of closing them. -JIRA issue references and update comments will not work if the GitLab issue tracker is disabled. +Make sure the `Transition ID` you set within the Jira settings matches the one +your project needs to close an issue. -### GitLab is unable to close a ticket +Make sure that the Jira issue is not already marked as resolved; that is, +the Jira issue resolution field is not set. (It should not be struck through in +Jira lists.) -Make sure the `Transition ID` you set within the JIRA settings matches the one -your project needs to close a ticket. +### CAPTCHA -Make sure that the JIRA issue is not already marked as resolved, in other words that -the JIRA issue resolution field is not set. (It should not be struck through in -JIRA lists.) +CAPTCHA may be triggered after several consecutive failed login attempts +which may lead to a `401 unauthorized` error when testing your Jira integration. +If CAPTCHA has been triggered, you will not be able to use Jira's REST API to +authenticate with the Jira site. You will need to log in to your Jira instance +and complete the CAPTCHA. [services-templates]: services_templates.md [jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/doc/project_services/jira.md -[jira]: https://www.atlassian.com/software/jira diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md new file mode 100644 index 00000000000..cae66526175 --- /dev/null +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -0,0 +1,18 @@ +# Creating an API token in JIRA cloud + +An API token is needed when integrating with JIRA Cloud, follow the steps +below to create one: + +1. Log in to https://id.atlassian.com with your email. +1. **Click API tokens**, then **Create API token**. + + + + + +1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). + +NOTE: **Note** +It is important that the user associated with this email has 'write' access to projects in JIRA. + +The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md new file mode 100644 index 00000000000..20036183187 --- /dev/null +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -0,0 +1,53 @@ +# Creating a username and password for JIRA server + +We need to create a user in Jira which will have access to all projects that +need to integrate with GitLab. Login to your Jira instance as admin and under +*Administration*, go to *User Management* and create a new user. + +As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` +group. + +NOTE: **Note** +It is important that the user `gitlab` has 'write' access to projects in Jira. + +We have split this stage in steps so it is easier to follow. + +1. Log in to your Jira instance as an administrator and under **Administration** + go to **User Management** to create a new user. + +  + +1. The next step is to create a new user (e.g., `gitlab`) who has write access + to projects in Jira. Enter the user's name and a _valid_ e-mail address + since Jira sends a verification e-mail to set up the password. + _**Note:** Jira creates the username automatically by using the e-mail + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create + an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password._ + +  + +1. Create a `gitlab-developers` group which will have write access + to projects in Jira. Go to the **Groups** tab and select **Create group**. + +  + + Give it an optional description and click **Create group**. + +  + +1. To give the newly-created group 'write' access, go to + **Application access > View configuration** and add the `gitlab-developers` + group to Jira Core. + +  + +1. Add the `gitlab` user to the `gitlab-developers` group by going to + **Users > GitLab user > Add group** and selecting the `gitlab-developers` + group from the dropdown menu. Notice that the group says _Access_, which is + intended as part of this process. + +  + +The Jira configuration is complete. Write down the new Jira username and its +password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 3e77823a6aa..ed4367c1135 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,9 +4,9 @@ To enable Mattermost integration you must create an incoming webhook integration: -1. Sign in to your Mattermost instance -1. Visit incoming webhooks, that will be something like: https://mattermost.example/your_team_name/integrations/incoming_webhooks/add -1. Choose a display name, description and channel, those can be overridden on GitLab +1. Sign in to your Mattermost instance. +1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable @@ -38,7 +38,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to setup on Mattermost, it will be something like: http://mattermost.example/hooks/5xo… | +| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: http://mattermost.example/hooks/5xo… | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 488f61c77a3..e031dcad2c3 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -102,7 +102,7 @@ in a new slash command.  -1. After you setup all the values, copy the token (we will use it below) and +1. After you set up all the values, copy the token (we will use it below) and click **Done**.  diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 140c6738a49..ca32689910c 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -25,7 +25,7 @@ At the end fill in your Microsoft Teams details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to setup on Microsoft Teams. | +| **Webhook** | The incoming webhook URL which you have to set up on Microsoft Teams. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | After you are all done, click **Save changes** for the changes to take effect. diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 6aefe5dbded..8b1908c46fe 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -2,7 +2,7 @@ **NB: This service is only listed if you are in a development environment!** -To setup the mock CI service server, respond to the following endpoints +To set up the mock CI service server, respond to the following endpoints - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success_with_warnings'|'skipped'|'not_found'] }` diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index efb0381d7aa..be45ce46dfd 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -30,6 +30,7 @@ Click on the service links to see further configuration instructions and details | [Bugzilla](bugzilla.md) | Bugzilla issue tracker | | Campfire | Simple web-based real-time group chat | | Custom Issue Tracker | Custom issue tracker | +| [Discord Notifications](discord_notifications.md) | Receive event notifications in Discord | | Drone CI | Continuous Integration platform built on Docker, written in Go | | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index f687027e8c8..7d0e567cae7 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -8,7 +8,7 @@ within the GitLab interface.  -There are two ways to setup Prometheus integration, depending on where your apps are running: +There are two ways to set up 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). @@ -56,7 +56,7 @@ The [NGINX Ingress](../clusters/index.md#installing-applications) that is deploy 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. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) 1. Each metric must be have a label to indicate the environment 1. GitLab must have network connectivity to the Prometheus server @@ -65,7 +65,7 @@ Integration with Prometheus requires the following: 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. Set up one of the [supported monitoring targets](prometheus_library/index.md) 1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) #### Configuration in GitLab diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index bf6c0dc0e7e..66f1b587070 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -27,4 +27,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label 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). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index cd398f7c0fd..abb0c01ad18 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -21,4 +21,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label 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). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md new file mode 100644 index 00000000000..9b9b4f6c8ca --- /dev/null +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -0,0 +1,33 @@ +# Prometheus Metrics library + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0. + +GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). + +## Exporters + +Currently supported exporters are: + +- [Kubernetes](kubernetes.md) +- [NGINX](nginx.md) +- [NGINX Ingress Controller](nginx_ingress.md) +- [HAProxy](haproxy.md) +- [Amazon Cloud Watch](cloudwatch.md) + +We have tried to surface the most important metrics for each exporter, and will +be continuing to add support for additional exporters in future releases. If you +would like to add support for other official exporters, contributions are welcome. + +## Identifying Environments + +GitLab retrieves performance data from the configured Prometheus server, and +attempts to identifying the presence of known metrics. Once identified, GitLab +then needs to be able to map the data to a particular environment. + +In order to isolate and only display relevant metrics for a given environment, +GitLab needs a method to detect which labels are associated. To do that, +GitLab uses the defined queries and fills in the environment specific variables. +Typically this involves looking for the +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-variables-environment-variables), +but may also include other information such as the project's Kubernetes namespace. +Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index ec16902fcc8..37a5388d2fc 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -1,19 +1 @@ -# Prometheus Metrics library - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0 - -GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). Currently supported exporters are: -* [Kubernetes](kubernetes.md) -* [NGINX](nginx.md) -* [NGINX Ingress Controller](nginx_ingress.md) -* [HAProxy](haproxy.md) -* [Amazon Cloud Watch](cloudwatch.md) - -We have tried to surface the most important metrics for each exporter, and will be continuing to add support for additional exporters in future releases. If you would like to add support for other official exporters, [contributions](#adding-to-the-library) are welcome. - -## Identifying Environments - -GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. - -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, -GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the [$CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#prometheus-metrics-library). +This document was moved to [another location](index.md). diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 557487e1a75..c4fea178ab5 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -27,4 +27,4 @@ If you are using NGINX as your Kubernetes ingress, GitLab will [automatically de ## Specifying the Environment label 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). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index a1db79538a4..40ac855c74f 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,8 +1,8 @@ # Monitoring NGINX Ingress Controller -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438) in GitLab 9.5 +> [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) and above 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-nginx/blob/master/Changelog.md#09-beta1) and above of the ingress. ## Requirements @@ -38,7 +38,7 @@ When used in conjunction with the GitLab deployed Prometheus service, response m ### 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. +Version 0.9.0 and above of [NGINX ingress](https://github.com/kubernetes/ingress-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. Next, the ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index de2cf6d4647..76a2617125e 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -18,15 +18,16 @@ in the table below.  -2. To disable the internal issue tracking system in a project, navigate to the General page, expand [Permissions](../settings/index.md#sharing-and-permissions), and slide the Issues switch invalid. +1. To disable the internal issue tracking system in a project, navigate to the General page, expand [Permissions](../settings/index.md#sharing-and-permissions), and slide the Issues switch invalid.  ## Referencing issues in Redmine Issues in Redmine can be referenced in two alternative ways: -1. `#<ID>` where `<ID>` is a number (example `#143`) -2. `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is + +- `#<ID>` where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 5b04d7d88b8..a0bf31c526f 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,8 +1,10 @@ # Services templates A GitLab administrator can add a service template that sets a default for each -project. After a service template is enabled, it will be applied to new -projects only and its details will be pre-filled on the project's Service page. +project. After a service template is enabled, it will be applied to **all** +projects that don't have it already enabled and its details will be pre-filled +on the project's Service page. By disabling the template, it will be disabled +for new projects only. ## Enable a service template diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e22f8e976be..4d1d95da6f0 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -7,7 +7,7 @@ > - the `project.http_url` key is deprecated in favor of the `project.git_http_url` key > > **Note:** -> Starting from GitLab 11.1, the logs of web hooks are automatically removed after +> Starting from GitLab 11.1, the logs of webhooks are automatically removed after > one month. > > **Note:** @@ -73,8 +73,8 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -> **Note:** When more than 20 commits are pushed at once, the `commits` web hook - attribute will only contain the first 20 for performance reasons. Loading +> **Note:** When more than 20 commits are pushed at once, the `commits` webhook + attribute will only contain the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being present in the `commits` attribute, the `total_commits_count` attribute will contain the actual total. @@ -338,10 +338,10 @@ payload will also include information about the target of the comment. For examp a comment on an issue will include the specific issue information under the `issue` key. Valid target types: -1. `commit` -2. `merge_request` -3. `issue` -4. `snippet` +- `commit` +- `merge_request` +- `issue` +- `snippet` #### Comment on commit @@ -943,7 +943,13 @@ X-Gitlab-Event: Pipeline Hook ], "created_at": "2016-08-12 15:23:28 UTC", "finished_at": "2016-08-12 15:26:29 UTC", - "duration": 63 + "duration": 63, + "variables": [ + { + "key": "NESTOR_PROD_ENVIRONMENT", + "value": "us-west-1" + } + ] }, "user":{ "name": "Administrator", @@ -1151,10 +1157,11 @@ its description: ``` It will appear in the webhook body as the below (assuming that GitLab is -installed at gitlab.example.com): +installed at gitlab.example.com, and the project is at +example-group/example-project): ```markdown - + ``` This will not rewrite URLs that already are pointing to HTTP, HTTPS, or @@ -1170,7 +1177,7 @@ You can trigger the webhook manually. Sample data from the project will be used. ## Troubleshoot webhooks -Gitlab stores each perform of the webhook. +GitLab stores each perform of the webhook. You can find records for last 2 days in "Recent Deliveries" section on the edit page of each webhook.  @@ -1184,7 +1191,7 @@ From this page, you can repeat delivery with the same data by clicking `Resend R > **Note:** If URL or secret token of the webhook were updated, data will be delivered to the new address. -### Receiving duplicate or multiple web hook requests triggered by one event +### Receiving duplicate or multiple webhook requests triggered by one event When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 7c6d547d626..9e2434c02ec 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -2,13 +2,44 @@ > [Introduced][ce-5554] in [GitLab 8.11](https://about.gitlab.com/2016/08/22/gitlab-8-11-released/#issue-board). +## Overview + The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban] or a [Scrum] board. - +It provides perfect pairing between issue tracking and project management, +keeping everything in the same place, so that you don't need to jump +between different platforms to organize your workflow. -## Overview +With GitLab Issue Boards, you organize your issues in lists that correspond to +their assigned labels, visualizing issues designed as cards throughout that lists. + +You define your process and GitLab organizes it for you. You add your labels +then create the corresponding list to pull in your existing issues. When +you're ready, you can drag and drop your issue cards from one step to the next. + + + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of +Issue Boards** (version introduced in GitLab 8.11 - August 2016). + +### Advanced features of Issue Boards + +With [GitLab Starter](https://about.gitlab.com/pricing/), you can create +[multiple issue boards](#multiple-issue-boards) for a given project. **[STARTER]** + +With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple +issue boards for your groups, and add lists for [assignees](#assignee-lists) and +[milestones](#milestone-lists). **[PREMIUM]** + +Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards) +below. + + + +## How it works The Issue Board builds on GitLab's existing [issue tracking functionality](issues/index.md#issue-tracker) and @@ -28,15 +59,12 @@ and deploy from one single platform. Issue Boards help you to visualize and manage the entire process _in_ GitLab. With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), available -only in [GitLab Enterprise Edition](#features-per-tier), +only in [different tiers of GitLab Enterprise Edition](#gitlab-enterprise-features-for-issue-boards), you go even further, as you can not only keep yourself and your project organized from a broader perspective with one Issue Board per project, but also allow your team members to organize their own workflow by creating multiple Issue Boards within the same project. -For a visual overview, see our [Issue Board feature page](https://about.gitlab.com/features/issueboard/) -on about.gitlab.com or our [video introduction to Issue Boards](https://www.youtube.com/watch?v=UWsJ8tkHAa8). - ## Use cases There are many ways to use GitLab Issue Boards tailored to your own preferred workflow. @@ -111,11 +139,6 @@ to improve their workflow with multiple boards. Create lists for each of your team members and quickly drag-and-drop issues onto each team member. -## Permissions - -[Developers and up](../permissions.md) can use all the functionality of the -Issue Board, that is, create or delete lists and drag issues from one list to another. - ## Issue Board terminology - **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards. @@ -126,6 +149,142 @@ Issue Board, that is, create or delete lists and drag issues from one list to an - **Closed** (default): shows all closed issues. Always appears as the rightmost list. - **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list. +## Permissions + +[Developers and up](../permissions.md) can use all the functionality of the +Issue Board, that is, create or delete lists and drag issues from one list to another. + +## GitLab Enterprise features for Issue Boards + +GitLab Issue Boards are available on GitLab Core and GitLab.com Free, but some +advanced functionalities are only present in higher tiers: GitLab.com Bronze, +Silver, or Gold, or GitLab self-managed Starter, Premium, and Ultimate, as described +on the following sections. + +For a collection of [features per tier](#summary-of-features-per-tier), check the summary below. + +### Multiple Issue Boards **[STARTER]** + +> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee). + +Multiple Issue Boards, as the name suggests, allow for more than one Issue Board +for a given project or group. This is great for large projects with more than one team +or in situations where a repository is used to host the code of multiple +products. + +Clicking on the current board name in the upper left corner will reveal a +menu from where you can create another Issue Board and rename or delete the +existing one. + +When you're revisiting an issue board in a project or group with multiple boards, +GitLab will automatically load the last board you visited. + +NOTE: **Note:** +The Multiple Issue Boards feature is available for +**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**. + + + +### Configurable Issue Boards **[STARTER]** + +> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration). + +An Issue Board can be associated with a GitLab [Milestone](milestones/index.md#milestones), +[Labels](labels.md), Assignee and Weight +which will automatically filter the Board issues according to these fields. +This allows you to create unique boards according to your team's need. + + + +You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter +through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board. + + + +If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope". + + + +### Focus mode **[STARTER]** + +> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). + +Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. + + + +### Sum of Issue Weights **[STARTER]** + +The top of each list indicates the sum of issue weights for the issues that +belong to that list. This is useful when using boards for capacity allocation, +especially in combination with [assignee lists](#assignee-lists). + + + +### Group Issue Boards **[PREMIUM]** + +> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards). + +Accessible at the group navigation level, a group issue board offers the same features as a project-level board, +but it can display issues from all projects in that +group and its descendant subgroups. Similarly, you can only filter by group labels for these +boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only +group-level objects are available. + +NOTE: **Note:** +Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and +one group issue board per group was made available in GitLab 10.6 Core. + + + +### Assignee lists **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium. + +Like a regular list that shows all issues that have the list label, you can add +an assignee list that shows all issues assigned to the given user. +You can have a board with both label lists and assignee lists. To add an +assignee list: + +1. Click **Add list**. +1. Select the **Assignee list** tab. +1. Search and click on the user you want to add as an assignee. + +Now that the assignee list is added, you can assign or unassign issues to that user +by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list. +To remove an assignee list, just as with a label list, click the trash icon. + + + +### Milestone lists **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium. + +As of 11.2, you're also able to create lists of a milestone. As the name states, +these are lists that filter issues by the assigned milestone, giving you more +freedom and visibility on the Issue Board. To do so: + +1. Click **Add list**. +1. Select the **Milestone** tab. +1. Search and click on the milestone. + +Similar to the assignee lists, you're now able to [drag issues](#dragging-issues-between-lists) +to and/or from a milestone list to manipulate the milestone of the dragged issues. +As on another list types, click on the trash icon to remove it. + + + +### Summary of features per tier + +Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: + +| Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | +|----------|--------------------------------|------------------------------|---------------------------|----------------| +| Core / Free | 1 | 1 | No | No | +| Starter / Bronze | Multiple | 1 | Yes | No | +| Premium / Silver | Multiple | Multiple | Yes | Yes | +| Ultimate / Gold | Multiple | Multiple | Yes | Yes | + ## Actions you can take on an Issue Board - [Create a new list](#creating-a-new-list). @@ -142,7 +301,7 @@ Issue Board, that is, create or delete lists and drag issues from one list to an If you are not able to perform one or more of the things above, make sure you have the right [permissions](#permissions). -## First time using the Issue Board +### First time using the Issue Board The first time you navigate to your Issue Board, you will be presented with a default list (**Done**) and a welcoming message that gives @@ -157,7 +316,7 @@ which means the system has no way of populating them automatically. That's of course if the predefined labels don't already exist. If any of them does exist, the list will be created and filled with the issues that have that label. -## Creating a new list +### Creating a new list Create a new list by clicking on the **Add list** button at the upper right corner of the Issue Board. @@ -172,7 +331,7 @@ To create a list for a label that doesn't yet exist, simply create the label by choosing **Create new label**. The label will be created on-the-fly and it will be immediately added to the dropdown. You can now choose it to create a list. -## Deleting a list +### Deleting a list To delete a list from the Issue Board use the small trash icon that is present in the list's heading. A confirmation dialog will appear for you to confirm. @@ -180,7 +339,7 @@ in the list's heading. A confirmation dialog will appear for you to confirm. Deleting a list doesn't have any effect in issues and labels, it's just the list view that is removed. You can always add it back later if you need. -## Adding issues to a list +### Adding issues to a list You can add issues to a list by clicking the **Add issues** button that is present in the upper right corner of the Issue Board. This will open up a modal @@ -192,7 +351,7 @@ the list by filtering by author, assignee, milestone and label.  -## Removing an issue from a list +### Removing an issue from a list Removing an issue from a list can be done by clicking on the issue card and then clicking the **Remove from board** button in the sidebar. Under the hood, the @@ -201,7 +360,7 @@ board itself.  -## Issue ordering in a list +### Issue ordering in a list When visiting a board, issues appear ordered in any list. You are able to change that order simply by dragging and dropping the issues. The changed order will be saved @@ -224,7 +383,7 @@ a given board inside your GitLab instance, any time those two issues are subsequ loaded in any board in the same instance (could be a different project board or a different group board, for example), that ordering will be maintained. -## Filtering issues +### Filtering issues You should be able to use the filters on top of your Issue Board to show only the results you want. This is similar to the filtering used in the issue tracker @@ -232,7 +391,7 @@ since the metadata from the issues and labels are re-used in the Issue Board. You can filter by author, assignee, milestone and label. -## Creating workflows +### Creating workflows By reordering your lists, you can create workflows. As lists in Issue Boards are based on labels, it works out of the box with your existing issues. So if you've @@ -267,89 +426,7 @@ to another list the label changes and a system not is recorded.  -## Multiple Issue Boards **[STARTER]** - -> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee). - -Multiple Issue Boards, as the name suggests, allow for more than one Issue Board -for a given project or group. This is great for large projects with more than one team -or in situations where a repository is used to host the code of multiple -products. - -Clicking on the current board name in the upper left corner will reveal a -menu from where you can create another Issue Board and rename or delete the -existing one. - -NOTE: **Note:** -The Multiple Issue Boards feature is available for -**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**. - - - -## Configurable Issue Boards **[STARTER]** - -> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration). - -An Issue Board can be associated with GitLab [Milestone](milestones/index.md#milestones), -[Labels](labels.md), Assignee and Weight -which will automatically filter the Board issues according to these fields. -This allows you to create unique boards according to your team's need. - - - -You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter -through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board. - - - -If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope". - - - -## Focus mode **[STARTER]** - -> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep). - -Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board. - - - -## Group Issue Boards **[PREMIUM]** - -> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards). - -Accessible at the group navigation level, a group issue board offers the same features as a project-level board, -but it can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -NOTE: **Note:** -Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and -one group issue board per group was made available in GitLab 10.6 Core. - - - -## Assignee lists **[PREMIUM]** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium. - -Like a regular list that shows all issues that have the list label, you can add -an assignee list that shows all issues assigned to the given user. -You can have a board with both label lists and assignee lists. To add an -assignee list: - -1. Click **Add list**. -1. Select the **Assignee list** tab. -1. Search and click on the user you want to add as an assignee. - -Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list. -To remove an assignee list, just as with a label list, click the trash icon. - - - -## Dragging issues between lists +### Dragging issues between lists When dragging issues between lists, different behavior occurs depending on the source list and the target list. @@ -360,17 +437,6 @@ When dragging issues between lists, different behavior occurs depending on the s | From label `A` list | `A` removed | Issue closed | `A` removed<br/>`B` added | `Bob` assigned | | From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned<br/>`Bob` assigned | -## Features per tier - -Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: - -| Tier | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists | -|----------|--------------------------------|------------------------------|---------------------------|----------------| -| Core | 1 | 1 | No | No | -| Starter | Multiple | 1 | Yes | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | - ## Tips A few things to remember: diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index b6570c777ae..afb7d9ada5f 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -27,10 +27,11 @@ used: Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's source code that can match references to: -1. a local issue (`#123`), -2. a cross-project issue (`group/project#123`) -3. a link to an issue -(`https://gitlab.example.com/group/project/issues/123`). + +- A local issue (`#123`). +- A cross-project issue (`group/project#123`). +- A link to an issue + (`https://gitlab.example.com/group/project/issues/123`). --- diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 1688edc1ee2..c33d1365001 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -58,3 +58,21 @@ body becomes the issue description. [Markdown] and [quick actions] are supported.  + +## New issue via URL with prefilled fields + +You can link directly to the new issue page for a given project, with prefilled +field values using query string parameters in a URL. This is useful for embedding +a URL in an external HTML page, and also certain scenarios where you want the user to +create an issue with certain fields prefilled. + +The title, description, and description template fields can be prefilled using +this method. The description and description template fields cannot be pre-entered +in the same URL (since a description template just populates the description field). + +Follow these examples to form your new issue URL with prefilled fields. + +- For a new issue in the GitLab Community Edition project with a pre-entered title +and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` +- For a new issue in the GitLab Community Edition project with a pre-entered title +and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png Binary files differindex df9d6f64985..c75c35a382e 100644 --- a/doc/user/project/issues/img/issue_board.png +++ b/doc/user/project/issues/img/issue_board.png diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index 46f25417fde..d78721f8658 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -69,7 +69,7 @@ Learn more on the [Time Tracking documentation](../../../workflow/time_tracking. #### 6. Due date When you work on a tight schedule, and it's important to -have a way to setup a deadline for implementations and for solving +have a way to set up a deadline for implementations and for solving problems. This can be facilitated by the [due date](due_dates.md)). Due dates can be changed as many times as needed. @@ -118,9 +118,12 @@ is the `project-name`, and `xxx` is the issue number. #### 13. @mentions -- Mentions: you can either `@mention` a user or a group present in your -GitLab instance and they will be notified via todos and email, unless that -person has disabled all notifications in their profile settings. +- You can either `@mention` a user or a group present in your + GitLab instance and they will be notified via todos and email, unless that + person has disabled all notifications in their profile settings. +- Mentions for yourself (the current logged in user),will be distinctly highlighted + in a different color, allowing you to easily see which comments involve you, + helping you focus on them quickly. To change your [notification settings](../../../workflow/notifications.md) navigate to **Profile Settings** > **Notifications** > **Global notification level** diff --git a/doc/user/project/koding.md b/doc/user/project/koding.md deleted file mode 100644 index 2c886d7916a..00000000000 --- a/doc/user/project/koding.md +++ /dev/null @@ -1,131 +0,0 @@ -# Koding integration - -> **Notes:** -> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed -> in a future version.** -> - [Introduced][ce-5909] in GitLab 8.11. - -This document will guide you through using Koding integration on GitLab in -detail. For configuring and installing please follow the -[administrator guide](../../administration/integration/koding.md). - -You can use Koding integration to run and develop your projects on GitLab. This -will allow you and the users to test your project without leaving the browser. -Koding handles projects as stacks which are basic recipes to define your -environment for your project. With this integration you can automatically -create a proper stack template for your projects. Currently auto-generated -stack templates are designed to work with AWS which requires a valid AWS -credential to be able to use these stacks. You can find more information about -stacks and the other providers that you can use on Koding following the -[Koding documentation][koding-docs]. - -## Enable Integration - -You can enable Koding integration by providing the running Koding instance URL -in Application Settings under **Admin area > Settings** (`/admin/application_settings`). - - - -Once enabled you will see `Koding` link on your sidebar which leads you to -Koding Landing page. - - - -You can navigate to running Koding instance from here. For more information and -details about configuring the integration, please follow the -[administrator guide](../../administration/integration/koding.md). - -## Set up Koding on Projects - -Once it's enabled, you will see some integration buttons on Project pages, -Merge Requests etc. To get started working on a specific project you first need -to create a `.koding.yml` file under your project root. You can easily do that -by using `Set Up Koding` button which will be visible on every project's -landing page; - - - -Once you click this will open a New File page on GitLab with auto-generated -`.koding.yml` content based on your server and repository configuration. - - - - -## Run a project on Koding - -If there is `.koding.yml` exists in your project root, you will see -`Run in IDE (Koding)` button in your project landing page. You can initiate the -process from here. - - - -This will open Koding defined in the settings in a new window and will start -importing the project's stack file. - - - -You should see the details of your repository imported into your Koding -instance. Once it's completed it will lead you to the Stack Editor and from -there you can start using your new stack integrated with your project on your -GitLab instance. For details about what's next you can follow -[this guide](https://www.koding.com/docs/creating-an-aws-stack) from step 8. - -Once stack initialized you will see the `README.md` content from your project -in `Stack Build` wizard, this wizard will let you build the stack and import -your project into it. **Once it's completed it will automatically open the -related vm instead of importing from scratch**. - - - -This will take time depending on the required environment. - - - -It usually takes ~4 min. to make it ready with a `t2.nano` instance on given -AWS region. (`t2.nano` is default vm type on auto-generated stack template -which can be manually changed). - - - -You can check out the `Build Logs` from this success modal as well. - - - -You can now `Start Coding`! - - - -## Try a Merge Request on IDE - -It's also possible to try a change on IDE before merging it. This flow only -enabled if the target project has `.koding.yml` in it's target branch. You -should see the alternative version of `Run in IDE (Koding)` button in merge -request pages as well; - - - -This will again take you to Koding with proper arguments passed, which will -allow Koding to modify the stack template provided by target branch. You can -see the difference; - - - -The flow for the branch stack is also same with the regular project flow. - -## Open GitLab from Koding - -Since stacks generated with import flow defined in previous steps, they have -information about the repository they are belonging to. By using this -information you can access to related GitLab page from stacks on your sidebar -on Koding. - - - -## Other links - -- [YouTube video on GitLab + Koding workflow][youtube] -- [Koding documentation][koding-docs] - -[ce-5909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5909 -[youtube]: https://youtu.be/3wei5yv_Ye8 -[koding-docs]: https://www.koding.com/docs diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 3ae6dbe585e..9c045dfcce4 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -19,6 +19,7 @@ A permission level of `Developer` or higher is required to create labels. ### New project label To create a **project label**, navigate to **Issues > Labels** in the project. +This page only shows project labels in this project and group labels of this project's parent group. Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label. @@ -33,6 +34,7 @@ GitLab will add the following default labels to the project: ### New group label 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. +This page only shows group labels in this group. Group labels appear in every label list page of the group's child projects. @@ -95,7 +97,7 @@ From the group issue list page and the group merge request list page, you can [f ## Subscribing to labels -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. +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 the label has been assigned to an issue or merge request.  diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 22ef11e4049..06b3779668b 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -12,9 +12,11 @@ to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal will appear where you can choose to -cherry-pick the changes directly into the selected branch or you can opt to -create a new merge request with the cherry-pick changes +After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +where you can choose to either: + +- Cherry-pick the changes directly into the selected branch. +- Create a new merge request with the cherry-picked changes. ## Cherry-picking a Commit diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differnew file mode 100644 index 00000000000..856ede41527 --- /dev/null +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png diff --git a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png Binary files differnew file mode 100644 index 00000000000..40913718385 --- /dev/null +++ b/doc/user/project/merge_requests/img/filter_wip_merge_requests.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differindex ac766c99935..1cdac5ef573 100644 --- a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png +++ b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differnew file mode 100644 index 00000000000..183d9cb910b --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/img/merge_request_widget.png b/doc/user/project/merge_requests/img/merge_request_widget.png Binary files differindex 6c2317b29b5..58562fcb034 100644 --- a/doc/user/project/merge_requests/img/merge_request_widget.png +++ b/doc/user/project/merge_requests/img/merge_request_widget.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 43ca498d006..5b54b6ecdd5 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -9,7 +9,7 @@ collaborate with other people on the same project. A Merge Request (**MR**) is the basis of GitLab as a code collaboration and version control platform. -Is it simple as the name implies: a _request_ to _merge_ one branch into another. +It is as simple as the name implies: a _request_ to _merge_ one branch into another. With GitLab merge requests, you can: @@ -141,6 +141,15 @@ you hide discussions that are no longer relevant. [Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) +## Commenting on any file line in merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/13950) in GitLab 11.5. + +GitLab provides a way of leaving comments in any part of the file being changed +in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. + + + ## Resolve conflicts When a merge request has conflicts, GitLab may provide the option to resolve @@ -166,9 +175,26 @@ administrator to do so.  +### Adding patches when creating a merge request via e-mail + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22723) in GitLab 11.5. + +You can add commits to the merge request being created by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` will be considered patches and they will be processed +ordered by name. + +The combined size of the patches can be 2MB. + +If the source branch from the subject does not exist, it will be +created from the repository's HEAD or the specified target branch to +apply the patches. The target branch can be specified using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches will be applied on top of it. + ## 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). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5. 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. @@ -205,9 +231,10 @@ have been marked as a **Work In Progress**. ## Merge request diff file navigation -The diff view has a persistent dropdown for file navigation. As you scroll through -diffs with a large number of files and/or many changes in those files, you can -easily jump to any changed file through the dropdown navigation. +When reviewing changes in the **Changes** tab the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list.  @@ -232,10 +259,67 @@ all your changes will be available to preview by anyone with the Review Apps lin [Read more about Review Apps.](../../../ci/review_apps/index.md) +## Pipeline status in merge requests + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +you will be able to see: + +- Both pre and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If there's an [environment](../../../ci/environments.md) and the application is +successfully deployed to it, the deployed environment and the link to the +Review App will be shown as well. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the master branch and then triggers a deployment to the staging +environment. + +Deployments that are ongoing will be shown, as well as the deploying/deployed state +for environments. If it's the first time the branch is deployed, the link +will return a `404` error until done. During the deployment, the stop button will +be disabled. If the pipeline fails to deploy, the deployment info will be hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines.md). + ## Bulk editing merge requests Find out about [bulk editing merge requests](../../project/bulk_editing.md). +## Troubleshooting + +Sometimes things don't go as expected in a merge request, here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur for one of two reasons: + +* Sidekiq doesn't pick up the changes fast enough +* Because of the bug described in [#41545](https://gitlab.com/gitlab-org/gitlab-ce/issues/41545) + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status will update automatically. + +#### Bug + +Merge Request pipeline statuses can't be retrieved when the following occurs: + +1. A Merge Requst is created +1. The Merge Request is closed +1. Changes are made in the project +1. The Merge Request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +Merge Request again. + ## Tips Here are some tips that will help you be more efficient with merge requests in diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index ecbc8534eea..ccef2853e3f 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,15 +1,31 @@ -# Merge conflict resolution +# Merge request conflict resolution -> [Introduced][ce-5479] in GitLab 8.11. +Merge conflicts occur when two branches have different changes that cannot be +merged automatically. -When a merge request has conflicts, GitLab may provide the option to resolve -those conflicts in the GitLab UI. (See -[conflicts available for resolution](#conflicts-available-for-resolution) for -more information on when this is available.) If this is an option, you will see -a **resolve these conflicts** link in the merge request widget: +Git is able to automatically merge changes between branches in most cases, but +there are situations where Git will require your assistance to resolve the +conflicts manually. Typically, this is necessary when people change the same +parts of the same files. + +GitLab will prevent merge requests from being merged until all conflicts are +resolved. Conflicts can be resolved locally, or in many cases within GitLab +(see [conflicts available for resolution](#conflicts-available-for-resolution) +for information on when this is available).  +NOTE: **Note:** +GitLab resolves conflicts by creating a merge commit in the source branch that +is not automatically merged into the target branch. This allows the merge +commit to be reviewed and tested before the changes are merged, preventing +unintended changes entering the target branch without review or breaking the +build. + +## Resolve conflicts: interactive mode + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5479) in GitLab 8.11. + Clicking this will show a list of files with conflicts, with conflict sections highlighted: @@ -21,9 +37,9 @@ request into the source branch, resolving the conflicts using the options chosen. If the source branch is `feature` and the target branch is `master`, this is similar to performing `git checkout feature; git merge master` locally. -## Merge conflict editor +## Resolve conflicts: inline editor -> Introduced in GitLab 8.13. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6374) in GitLab 8.13. The merge conflict resolution editor allows for more complex merge conflicts, which require the user to manually modify a file in order to resolve a conflict, @@ -50,5 +66,3 @@ Additionally, GitLab does not detect conflicts in renames away from a path. For example, this will not create a conflict: on branch `a`, doing `git mv file1 file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be present in the branch after the merge request is merged. - -[ce-5479]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5479 diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index 8cf8a59dbfe..b9102798a49 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -12,6 +12,12 @@ The **Revert** button will only be available for merge requests created since GitLab 8.5. However, you can still revert a merge request by reverting the merge commit from the list of Commits page. +NOTE: **Note:** +The **Revert** button will only be shown for projects that use the +merge method "Merge Commit", which can be set under the project's +**Settings > General > Merge request**. [Fast-forward commits](fast_forward_merge.md) +can not be reverted via the MR view. + After the Merge Request has been merged, a **Revert** button will be available to revert the changes introduced by that merge request. 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 f01da06fa6e..66ac7740157 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,7 @@ have been marked a **Work In Progress**.  To mark a merge request a Work In Progress, simply start its title with `[WIP]` -or `WIP:`. As an alternative, you're also able to do it by sending a commit +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.  @@ -15,4 +15,11 @@ with its title starting with `wip` or `WIP` to the merge request's source branch To allow a Work In Progress merge request to be accepted again when it's ready, simply remove the `WIP` prefix. - + + +## Filtering merge requests with WIP Status + +To filter merge requests with the `WIP` status, you can type `wip` +and select the value for your filter from the merge request search input. + + diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 632253db94c..ac58a0b5c18 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -6,6 +6,26 @@ Milestones in GitLab are a way to track issues and merge requests created to ach Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. +## Milestones as Agile sprints + +Milestones can be used as Agile sprints. +Set the milestone start date and due date to represent +the start and end of your Agile sprint. +Set the milestone title to the name of your Agile sprint, +such as `November 2018 sprint`. +Add an issue to your Agile sprint by associating +the milestone to the issue. + +## Milestones as releases + +Milestones can be used as releases. +Set the milestone due date to represent the release date of your release. +(And leave the milestone start date blank.) +Set the milestone title to the version of your release, +such as `Version 9.4`. +Add an issue to your release by associating +the milestone to the issue. + ## Project milestones and group milestones - **Project milestones** can be assigned to issues or merge requests in that project only. @@ -68,7 +88,8 @@ From [project issue boards](../issue_board.md), you can filter by both group mil When filtering by milestone, in addition to choosing a specific project milestone or group milestone, you can choose a special milestone filter. -- **No Milestone**: Show issues or merge requests with no assigned milestone. +- **None**: Show issues or merge requests with no assigned milestone. +- **Any**: Show issues or merge requests that have an 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. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 23d5b34504c..9a53036b4d1 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -60,7 +60,7 @@ Let's consider the following scenario: hosted in private repositories and you have multiple CI jobs that make use of these repositories. -2. You invite a new [external user][ext]. CI jobs created by that user do not +1. You invite a new [external user][ext]. CI jobs created by that user do not have access to internal repositories, because the user also doesn't have the access from within GitLab. You as an employee have to grant explicit access for this user. This allows us to prevent from accidental data leakage. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index e1eede8bbed..247e8d2a6a0 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,5 +1,5 @@ --- -last_updated: 2018-08-16 +last_updated: 2018-11-19 author: Marcia Ramos author_gitlab: marcia level: beginner @@ -11,7 +11,7 @@ date: 2017-02-22 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`. +These steps assume you've already [set your site up](getting_started_part_two.md) 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 @@ -183,7 +183,7 @@ you can use the following setup: - In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232` - In GitLab, add the domain to GitLab Pages - In Cloudflare, create a DNS `TXT` record to verify your domain -- In Cloudflare, create a DNS `CNAME` record poiting `www` to `domain.com` +- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com` ## SSL/TLS Certificates @@ -212,7 +212,7 @@ security measure, necessary just for big companies, like banks and shoppings sit 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/)._ +> _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](https://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) diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differnew file mode 100644 index 00000000000..daaf760ec08 --- /dev/null +++ b/doc/user/project/pages/img/icons/click.png diff --git a/doc/user/project/pages/img/icons/cogs.png b/doc/user/project/pages/img/icons/cogs.png Binary files differnew file mode 100644 index 00000000000..a12da1b5e8c --- /dev/null +++ b/doc/user/project/pages/img/icons/cogs.png diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png Binary files differnew file mode 100644 index 00000000000..e2c9577e7ce --- /dev/null +++ b/doc/user/project/pages/img/icons/fork.png diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png Binary files differnew file mode 100644 index 00000000000..3b8f8f6863e --- /dev/null +++ b/doc/user/project/pages/img/icons/free.png diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png Binary files differnew file mode 100644 index 00000000000..1c1f0b4457b --- /dev/null +++ b/doc/user/project/pages/img/icons/lock.png diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png Binary files differnew file mode 100644 index 00000000000..7b99d430eef --- /dev/null +++ b/doc/user/project/pages/img/icons/monitor.png diff --git a/doc/user/project/pages/img/icons/terminal.png b/doc/user/project/pages/img/icons/terminal.png Binary files differnew file mode 100644 index 00000000000..ab5ae11310c --- /dev/null +++ b/doc/user/project/pages/img/icons/terminal.png diff --git a/doc/user/project/pages/img/ssgs_pages.png b/doc/user/project/pages/img/ssgs_pages.png Binary files differnew file mode 100644 index 00000000000..608881c8e31 --- /dev/null +++ b/doc/user/project/pages/img/ssgs_pages.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 4f0774dba5c..7de9ae0caea 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -4,71 +4,180 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no add # GitLab Pages -With GitLab Pages it's easy to publish your project website. GitLab Pages is a hosting service for static websites, at no additional cost. - -## Getting Started - -[Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch) -to get you started quickly, or, -alternatively, start from an existing project as follows: - -1. [Fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project) an [example project](https://gitlab.com/pages): +**GitLab Pages is a feature that allows you to publish static websites +directly from a repository in GitLab.** + +You can use it either for personal or business websites, such as +portfolios, documentation, manifestos, and business presentations, +and attribute any license to your content. + +<table class="borderless-table center fixed-table"> + <tr> + <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td> + <td style="width: 4%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Use any static website generator or plain HTML</em></td> + <td></td> + <td><em>Create websites for your projects, groups, or user account</em></td> + <td></td> + <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td> + <td></td> + <td><em>Connect your custom domain(s) and TLS certificates</em></td> + </tr> +</table> + +Pages is available for free for all GitLab.com users as well as for self-managed +instances (GitLab Core, Starter, Premium, and Ultimate). + +## Overview + +<div class="row"> +<div class="col-md-9"> +<p style="margin-top: 18px;"> +To publish a website with Pages, you can use any Static Site Generator (SSG), +such as Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also +publish any website written directly in plain HTML, CSS, and JavaScript.</p> +<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about +<a href="https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p> +</div> +<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> +</div> + +### Availability + +If you're using GitLab.com, your website will be publicly available to the internet. +If you're using self-managed instances (Core, Starter, Premium, or Ultimate), +your websites will be published on your own server, according to the +[Pages admin settings](../../../administration/pages/index.md) chosen by your sysdamin, +who can opt for making them public or internal to your server. + +### How it works + +To use GitLab Pages, first you need to create a project in GitLab to upload your website's +files to. These projects can be either public, internal, or private, at your own choice. +GitLab will always deploy your website from a very specific folder called `public` in your +repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md) +becomes available automatically. + +To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), +that will build your site and publish it to the GitLab Pages server. The sequence of +scripts that GitLab CI/CD runs to accomplish this task is created from a file named +`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. + +You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain), +`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll +need admin access to your domain's registrar (or control panel) to set it up with Pages. + +Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your +site under the HTTPS protocol. + +## Getting started + +To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch) +or quickly start from copying an existing example project, as follows: + +1. Choose an [example project](https://gitlab.com/pages) to [fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project): by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch. -2. Change a file to trigger a GitLab CI/CD pipeline: GitLab CI/CD will build and deploy your site to GitLab Pages. -3. Visit your project's **Settings > Pages** to see your **website link**, and click on it. Bam! Your website is live! :) - - _Further steps (optional):_ - -4. Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from) +1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click +**Run pipeline** so that GitLab CI/CD will build and deploy your site to the server. +1. Once the pipeline has finished successfully, find the link to visit your website from your + project's **Settings > Pages**. + +<table class="borderless-table center fixed-table middle width-80"> + <tr> + <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td> + <td style="width: 10%"> + <strong> + <i class="fa fa-angle-double-right" aria-hidden="true"></i> + </strong> + </td> + <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td> + </tr> + <tr> + <td><em>Fork an example project</em></td> + <td></td> + <td><em>Deploy your website</em></td> + <td></td> + <td><em>Visit your website's URL</em></td> + </tr> +</table> + +Your website is then visible on your domain, and you can modify your files +as you wish. For every modification pushed to your repository, GitLab CI/CD will run +a new pipeline to publish your changes to the server. + +You can also take some optional further steps: + +- Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from) (_You don't need the relationship unless you intent to contribute back to the example project you forked from_). -5. Make it a [user/group website](getting_started_part_one.md#user-and-group-websites) +- Make it a [user/group website](getting_started_part_one.md#user-and-group-websites) -**Watch a video with the steps above: https://www.youtube.com/watch?v=TWqh9MtT4Bg** +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps above!** _Advanced options:_ - [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages) - Apply [SSL/TLS certification](getting_started_part_three.md#ssl-tls-certificates) to your custom domain -## How Does It Work? - -With GitLab Pages you can create [static websites](getting_started_part_one.md#what-you-need-to-know-before-getting-started) -for your GitLab projects, groups, or user accounts. - -It supports plain static content, such as HTML, and **all** [static site generators (SSGs)](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/), such as Jekyll, Middleman, Hexo, Hugo, and Pelican. - -Connect as many custom domains as you like and bring your own TLS certificate -to secure them. - -Your files live in a project [repository](../repository/index.md) on GitLab. -[GitLab CI](../../../ci/README.md) picks up those files and makes them available at, typically, -`https://<username>.gitlab.io/<projectname>`. Please read through the docs on -[GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain) for more info. - ## Explore GitLab Pages -Read the following tutorials to know more about: +To learn more about GitLab Pages, read the following tutorials: - [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 +- [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) -_Blog posts series about Static Site Generators (SSGs):_ +### GitLab Pages with Static Site Generators (SSGs) + +To understand more about SSGs, their advantages, and how to get the most from them +with Pages, read through this series: - [SSGs part 1: Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) - [SSGs part 2: Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) - [SSGs part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -_Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_ +### GitLab Pages with SSL/TLS certificates + +If you're using GitLab Pages default domain (`.gitlab.io`), your website will be +automatically secure and available under HTTPS. If you're using your own domain, you can +optionally secure it with SSL/TLS certificates. You can read the following +tutorials to learn how to use these third-party certificates with GitLab Pages: - [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) +- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps) ## Advanced use +There are quite some great examples of GitLab Pages websites built for some +specific reasons. These examples can teach you some advanced techniques +to use and adapt to your own needs: + - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/) - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) @@ -80,10 +189,9 @@ _Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_ Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with the [admin guide](../../../administration/pages/index.md). -**Watch the video: https://www.youtube.com/watch?v=dD8c7WNcc6s** +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!** ## More information about GitLab Pages -- For an overview, visit the [feature webpage](https://about.gitlab.com/features/pages/) - Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/2016/12/24/were-bringing-gitlab-pages-to-community-edition/) - Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index fe4d15adfa1..ed049e2e648 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -441,6 +441,48 @@ The rest of the guide still applies. See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain). +## GitLab Pages access control **[CORE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. + +NOTE: **Note:** +GitLab Pages access control is not activated on GitLab.com. You can check its +progress on the +[infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5576). + +You can enable Pages access control on your project, so that only +[members of your project](../../permissions.md#project-members-permissions) +(at least Guest) can access your website: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Toggle the **Pages** button to enable the access control. + + NOTE: **Note:** + If you don't see the toggle button, that means that it's not enabled. + Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). + +1. The Pages access control dropdown allows you to set who can view pages hosted + with GitLab Pages, depending on your project's visibility: + + - If your project is private: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is internal: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is public: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + +1. Click **Save changes**. + +--- + +The next time someone tries to access your website and the access control is +enabled, they will be presented with a page to sign into GitLab and verify they +can access the website. + ## Limitations When using Pages under the general domain of a GitLab instance (`*.example.io`), diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index fc3970e2014..a8b47558c99 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -151,6 +151,20 @@ For example: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/browse?job=coverage ``` +There is also a URL to specific files, including html files that +are shown in [GitLab Pages](../../../administration/pages/index.md): + +``` +https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name> +``` + +For example, when a job `coverage` creates the artifact `htmlcov/index.html`, +you can access it at: + +``` +https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage +``` + The latest builds are also exposed in the UI in various places. Specifically, look for the download button in: diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index 9daacc37994..051277dfe02 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -83,12 +83,12 @@ The next time a pipeline is scheduled, your credentials will be used.  -> **Note:** -When the owner of the schedule doesn't have the ability to create pipelines -anymore, due to e.g., being blocked or removed from the project, or lacking -the permission to run on protected branches or tags. When this happened, the -schedule is deactivated. Another user can take ownership and activate it, so -the schedule can be run again. +NOTE: **Note:** +If the owner of a pipeline schedule doesn't have the ability to create pipelines +on the target branch, the schedule will stop creating new pipelines. This can +happen if, for example, the owner is blocked or removed from the project, or +the target branch or tag is protected. In this case, someone with sufficient +privileges must take ownership of the schedule. ## Advanced admin configuration diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 9ad9155258f..85a03d125dd 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -1,48 +1,85 @@ # GitLab quick actions -Quick actions are textual shortcuts for common actions on issues, merge requests -or commits that are usually done by clicking buttons or dropdowns in GitLab's UI. -You can enter these commands while creating a new issue or merge request, and -in comments. Each command should be on a separate line in order to be properly -detected and executed. The commands are removed from the issue, merge request or -comment body before it is saved and will not be visible to anyone else. - -Below is a list of all of the available commands and descriptions about what they -do. - -| Command | Action | -|:---------------------------|:-------------| -| `/close` | Close the issue or merge request | -| `/reopen` | Reopen the issue or merge request | -| `/merge` | Merge (when pipeline succeeds) | -| `/title <New title>` | Change title | -| `/assign @username` | Assign | -| `/unassign` | Remove assignee | -| `/milestone %milestone` | Set milestone | -| `/remove_milestone` | Remove milestone | -| `/label ~foo ~"bar baz"` | Add label(s) | -| `/unlabel ~foo ~"bar baz"` | Remove all or specific label(s) | -| `/relabel ~foo ~"bar baz"` | Replace all label(s) | -| `/todo` | Add a todo | -| `/done` | Mark todo as done | -| `/subscribe` | Subscribe | -| `/unsubscribe` | Unsubscribe | -| <code>/due <in 2 days | this Friday | December 31st></code> | Set due date | -| `/remove_due_date` | Remove due date | -| `/wip` | Toggle the Work In Progress status | -| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | -| `/remove_estimate` | Remove estimated time | -| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | -| `/remove_time_spent` | Remove time spent | -| `/target_branch <Branch Name>` | Set target branch for current merge request | -| `/award :emoji:` | Toggle award for :emoji: | -| `/board_move ~column` | Move issue to column on the board | -| `/duplicate #issue` | Closes this issue and marks it as a duplicate of another issue | -| `/move path/to/project` | Moves issue to another project | -| `/tag v1.2.3 <message>` | Tags a commit with a given tag name and optional message | -| `/tableflip` | Append the comment with `(╯°□°)╯︵ ┻━┻` | -| `/shrug` | Append the comment with `¯\＿(ツ)＿/¯` | -| <code>/copy_metadata #issue | !merge_request</code> | Copy labels and milestone from other issue or merge request | -| `/confidential` | Makes the issue confidential | -| `/lock` | Lock the discussion | -| `/unlock` | Unlock the discussion | +Quick actions are textual shortcuts for common actions on issues, epics, merge requests, +and commits that are usually done by clicking buttons or dropdowns in GitLab's UI. +You can enter these commands while creating a new issue or merge request, or +in comments of issues, epics, merge requests, and commits. Each command should be +on a separate line in order to be properly detected and executed. Once executed, +the commands are removed from the text body and not visible to anyone else. + +## Quick actions for issues and merge requests + +The following quick actions are applicable to both issues and merge requests threads, +discussions, and descriptions: + +| Command | Action | Issue | Merge request | +|:---------------------------|:------------------------------ |:------|:--------------| +| `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | ✓ | ✓ | +| `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | ✓ | ✓ | +| `/todo` | Add a todo | ✓ | ✓ | +| `/done` | Mark todo as done | ✓ | ✓ | +| `/subscribe` | Subscribe | ✓ | ✓ | +| `/unsubscribe` | Unsubscribe | ✓ | ✓ | +| `/close` | Close | ✓ | ✓ | +| `/reopen` | Reopen | ✓ | ✓ | +| `/title <New title>` | Change title | ✓ | ✓ | +| `/award :emoji:` | Toggle emoji award | ✓ | ✓ | +| `/assign me` | Assign yourself | ✓ | ✓ | +| `/assign @user` | Assign one user | ✓ | ✓ | +| `/assign @user1 @user2` | Assign multiple users **[STARTER]** | ✓ | | +| `/unassign` | Remove assignee(s) | ✓ | ✓ | +| `/reassign @user1 @user2` | Change assignee | ✓ | ✓ | +| `/milestone %milestone` | Set milestone | ✓ | ✓ | +| `/remove_milestone` | Remove milestone | ✓ | ✓ | +| `/label ~label1 ~label2` | Add label(s) | ✓ | ✓ | +| `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓ | ✓ | +| `/relabel ~label1 ~label2` | Replace label | ✓ | ✓ | +| <code>/copy_metadata #issue | !merge_request</code> | Copy labels and milestone from other issue or merge request | ✓ | ✓ | +| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | ✓ | ✓ | +| `/remove_estimate` | Remove time estimate | ✓ | ✓ | +| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/remove_time_spent` | Remove time spent | ✓ | ✓ | +| `/lock` | Lock the discussion | ✓ | ✓ | +| `/unlock` | Unlock the discussion | ✓ | ✓ | +| <code>/due <in 2 days | this Friday | December 31st></code>| Set due date | ✓ | | +| `/remove_due_date` | Remove due date | ✓ | | +| `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | +| `/clear_weight` | Clears weight **[STARTER]** | ✓ | | +| `/epic <group&epic | Epic URL>` | Add to epic **[ULTIMATE]** | ✓ | | +| `/remove_epic` | Removes from epic **[ULTIMATE]** | ✓ | | +| `/confidential` | Make confidential | ✓ | | +| `/duplicate #issue` | Mark this issue as a duplicate of another issue | ✓ | +| `/move path/to/project` | Move this issue to another project | ✓ | | +| `/target_branch <Local branch Name>` | Set target branch | | ✓ | +| `/wip` | Toggle the Work In Progress status | | ✓ | +| `/merge` | Merge (when pipeline succeeds) | | ✓ | +| `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | ✓ | | + + +## Quick actions for commit messages + +The following quick actions are applicable for commit messages: + +| Command | Action | +|:------------------------|:------------------------------------------| +| `/tag v1.2.3 <message>` | Tags this commit with an optional message | + +## Quick actions for Epics **[ULTIMATE]** + +The following quick actions are applicable for epics threads and description: + +| Command | Action | +|:---------------------------|:----------------------------------------| +| `/tableflip <Comment>` | Append the comment with `(╯°□°)╯︵ ┻━┻` | +| `/shrug <Comment>` | Append the comment with `¯\＿(ツ)＿/¯` | +| `/todo` | Add a todo | +| `/done` | Mark todo as done | +| `/subscribe` | Subscribe | +| `/unsubscribe` | Unsubscribe | +| `/close` | Close | +| `/reopen` | Reopen | +| `/title <New title>` | Change title | +| `/award :emoji:` | Toggle emoji award | +| `/label ~label1 ~label2` | Add label(s) | +| `/unlabel ~label1 ~label2` | Remove all or specific label(s) | +| `/relabel ~label1 ~label2` | Replace label | diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box.png b/doc/user/project/repository/branches/img/branch_filter_search_box.png Binary files differnew file mode 100644 index 00000000000..c4364ef39f4 --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 19417d91fec..783081cec26 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,6 +6,7 @@ Read through GiLab's branching documentation: - [Default branch](#default-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) +- [Branch filter search box](#branch-filter-search-box) See also: @@ -29,16 +30,30 @@ to learn more. ## Delete merged branches -> [Introduced][ce-6449] in GitLab 8.14. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14.  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected][protected] will be deleted as part of +have been merged and [are not protected](../../protected_branches.md) will be deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted automatically when a merge request was merged. -[ce-6449]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449 "Add button to delete all merged branches" -[protected]: ../../protected_branches.md + +## Branch filter search box + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5. + + + +This feature allows you to search and select branches quickly. Search results appear in the following order: + +- Branches with names that matched search terms exactly. +- Other branches with names that include search terms, sorted alphabetically. + +Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following: + +- `^feature` will only match branch names that begin with 'feature'. +- `feature$` will only match branch names that end with 'feature'. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 4f076ee01b8..c6239c8e41c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -57,7 +57,7 @@ started: gpg --full-gen-key ``` -_NOTE: In some cases like Gpg4win on Windows and other Mac OS versions the command here may be ` gpg --gen-key`_ + _NOTE: In some cases like Gpg4win on Windows and other Mac OS versions the command here may be ` gpg --gen-key`_ This will spawn a series of questions. diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 1c3915a5fdd..1710bba2fd0 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -53,6 +53,46 @@ To get started with the command line, please read through the Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository. +### Supported markup languages and extensions + +GitLab supports a number of markup languages (sometimes called [lightweight +markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) +that you can use for the content of your files in a repository. They are mostly +used for documentation purposes. + +Just pick the right extension for your files and GitLab will render them +according to the markup language. + +| Markup language | Extensions | +| --------------- | ---------- | +| Plain text | `txt` | +| [Markdown](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` | +| [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` | +| [Asciidoc](https://asciidoctor.org/docs/what-is-asciidoc/) | `adoc`, `ad`, `asciidoc` | +| [Textile](https://txstyle.org/) | `textile` | +| [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | +| [Orgmode](https://orgmode.org/) | `org` | +| [creole](http://www.wikicreole.org/) | `creole` | +| [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | + +### Repository README and index files + +When a `README` or `index` file is present in a repository, its contents will be +automatically pre-rendered by GitLab without opening it. + +They can either be plain text or have an extension of a +[supported markup language](#supported-markup-languages-and-extensions): + +Some things to note about precedence: + +1. When both a `README` and an `index` file are present, the `README` will always + take precedence. +1. When more than one file is present with different extensions, they are + ordered alphabetically, with the exception of a file without an extension + which will always be last in precedence. For example, `README.adoc` will take + precedence over `README.md`, and `README.rst` will take precedence over + `README`. + ### Jupyter Notebook files > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2508) in GitLab 9.1 @@ -85,12 +125,13 @@ You can live preview changes submitted to a new branch with With [GitLab Starter](https://about.gitlab.com/pricing/), 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: +To create, delete, and view [branches](branches/index.md) via GitLab's UI: - [Default branches](branches/index.md#default-branch) - [Create a branch](web_editor.md#create-a-new-branch) - [Protected branches](../protected_branches.md#protected-branches) - [Delete merged branches](branches/index.md#delete-merged-branches) +- [Branch filter search box](branches/index.md#branch-filter-search-box) Alternatively, you can use the [command line](../../../gitlab-basics/start-using-git.md#create-a-branch). @@ -158,16 +199,22 @@ Find it under your project's **Repository > Graph**. ## Repository Languages For the default branch of each repository, GitLab will determine what programming languages -were used and display this on the projects pages. +were used and display this on the projects pages. If this information is missing, it will +be added after updating the default branch on the project. This process can take up to 5 +minutes.  -Not all files are detected, among others; documentation, -vendored code, and most markup languages are excluded. +Not all files are detected, among others; documentation, +vendored code, and most markup languages are excluded. This behaviour can be +adjusted by overriding the default. For example, to enable `.proto` files to be +detected, add the following to `.gitattributes` in the root of your repository. + +> *.proto linguist-detectable=true ## Compare -Select branches to compare and view the changes inline: +Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:  diff --git a/doc/user/project/settings/img/sharing_and_permissions_settings.png b/doc/user/project/settings/img/sharing_and_permissions_settings.png Binary files differindex f5e3e32f95c..6cb89c6ea1d 100644 --- a/doc/user/project/settings/img/sharing_and_permissions_settings.png +++ b/doc/user/project/settings/img/sharing_and_permissions_settings.png diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 084d1161633..d6754372816 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -18,6 +18,8 @@ Adjust your project's name, description, avatar, [default branch](../repository/  +The project description also partially supports [standard markdown](../../markdown.md#standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. + ### Sharing and permissions Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../container_registry.md) for your projects: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 9429b1268f0..e6b1f6b6aae 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -22,6 +22,27 @@ searching. The file finder is launched using the keyboard shortcut `Command-p`, `Control-p`, or `t` (when editor is not in focus). Type the filename or file path fragments to start seeing results. +## Syntax highligting + +As expected from an IDE, syntax highlighting for many languages within +the Web IDE will make your direct editing even easier. + +The Web IDE currently provides: + +- Basic syntax colorization for a variety of programming, scripting and markup +languages such as XML, PHP, C#, C++, Markdown, Java, VB, Batch, Python, Ruby +and Objective-C. +- IntelliSense and validation support (displaying errors and warnings, providing +smart completions, formatting, and outlining) for some languages. For example: +TypeScript, JavaScript, CSS, LESS, SCSS, JSON and HTML. + +Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), +you can find a more complete list of supported languages in the +[Monaco languages](https://github.com/Microsoft/monaco-languages) repository. + +NOTE: **Note:** +Single file editing is based on the [Ace Editor](https://ace.c9.io). + ## Stage and commit changes After making your changes, click the Commit button in the bottom left to diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 52610378ad5..45c306f5988 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -68,7 +68,6 @@ Currently the following names are reserved as top level groups: - import - invites - jwt -- koding - notification_settings - oauth - profile diff --git a/doc/user/search/img/dashboard_links.png b/doc/user/search/img/dashboard_links.png Binary files differnew file mode 100644 index 00000000000..2c472c7e464 --- /dev/null +++ b/doc/user/search/img/dashboard_links.png diff --git a/doc/user/search/img/issues_assigned_to_you.png b/doc/user/search/img/issues_assigned_to_you.png Binary files differindex 36c670eedd5..d2fff5e9a67 100644 --- a/doc/user/search/img/issues_assigned_to_you.png +++ b/doc/user/search/img/issues_assigned_to_you.png diff --git a/doc/user/search/img/issues_filter_none_any.png b/doc/user/search/img/issues_filter_none_any.png Binary files differnew file mode 100644 index 00000000000..9682fc55315 --- /dev/null +++ b/doc/user/search/img/issues_filter_none_any.png diff --git a/doc/user/search/img/left_menu_bar.png b/doc/user/search/img/left_menu_bar.png Binary files differdeleted file mode 100644 index d68a71cba8e..00000000000 --- a/doc/user/search/img/left_menu_bar.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 4f1b96b775c..78c1294346b 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -2,27 +2,27 @@ ## Issues and merge requests -To search through issues and merge requests in multiple projects, you can use the left-sidebar. +To search through issues and merge requests in multiple projects, you can use the **Issues** or **Merge Requests** links +in the top-right part of your screen. -Click the menu bar, then **Issues** or **Merge Requests**, which work in the same way, -therefore, the following notes are valid for both. +Both of them work in the same way, therefore, the following notes are valid for both. The number displayed on their right represents the number of issues and merge requests assigned to you. - + When you click **Issues**, you'll see the opened issues assigned to you straight away:  -You can filter them by **Author**, **Assignee**, **Milestone**, and **Labels**, -searching through **Open**, **Closed**, and **All** issues. +You can search through **Open**, **Closed**, or **All** issues. -Of course, you can combine all filters together. +You can also filter the results using the search and filter field. This works in the same way as the ones found in the +per project pages described below. ### Issues and MRs assigned to you or created by you -You'll find a shortcut to issues and merge requests create by you or assigned to you +You'll also find shortcuts to issues and merge requests created by you or assigned to you on the search field on the top-right of your screen:  @@ -40,6 +40,16 @@ The same process is valid for merge requests. Navigate to your project's **Merge and click **Search or filter results...**. Merge requests can be filtered by author, assignee, milestone, and label. +### Filtering by **None** / **Any** + +Some filter fields like milestone and assignee, allow you to filter by **None** or **Any**. + + + +Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee. + +Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. + ### Searching for specific terms You can filter issues and merge requests by specific terms included in titles or descriptions. diff --git a/doc/workflow/img/repository_mirroring_force_update.png b/doc/workflow/img/repository_mirroring_force_update.png Binary files differnew file mode 100644 index 00000000000..8ba715d1ba3 --- /dev/null +++ b/doc/workflow/img/repository_mirroring_force_update.png diff --git a/doc/workflow/img/repository_mirroring_pull_settings_lower.png b/doc/workflow/img/repository_mirroring_pull_settings_lower.png Binary files differnew file mode 100644 index 00000000000..a3e0b74ddf8 --- /dev/null +++ b/doc/workflow/img/repository_mirroring_pull_settings_lower.png diff --git a/doc/workflow/img/repository_mirroring_pull_settings_upper.png b/doc/workflow/img/repository_mirroring_pull_settings_upper.png Binary files differnew file mode 100644 index 00000000000..c60354fdca7 --- /dev/null +++ b/doc/workflow/img/repository_mirroring_pull_settings_upper.png diff --git a/doc/workflow/img/repository_mirroring_push_settings.png b/doc/workflow/img/repository_mirroring_push_settings.png Binary files differnew file mode 100644 index 00000000000..21a6aca4526 --- /dev/null +++ b/doc/workflow/img/repository_mirroring_push_settings.png diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md index 444d1483fcc..ec5943fd51b 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -54,7 +54,7 @@ to offload local hard disk R/W operations, and free up disk space significantly. GitLab is tightly integrated with `Fog`, so you can refer to its [documentation](http://fog.io/about/provider_documentation.html) to check which storage services can be integrated with GitLab. You can also use external object storage in a private local network. For example, -[Minio](https://www.minio.io/) is a standalone object storage service, is easy to setup, and works well with GitLab instances. +[Minio](https://www.minio.io/) is a standalone object storage service, is easy to set up, and works well with GitLab instances. GitLab provides two different options for the uploading mechanism: "Direct upload" and "Background upload". diff --git a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md index 9adbafee255..d02e921fa84 100644 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -78,10 +78,10 @@ git clone git@gitlab.example.com:group/project.git ``` If you already cloned the repository and you want to get the latest LFS object -that are on the remote repository, eg. from branch `master`: +that are on the remote repository, eg. for a branch from origin: ```bash -git lfs fetch master +git lfs fetch origin master ``` ## File Locking diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 731c9209224..020aa73f809 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -10,31 +10,32 @@ You can find notification settings under the user profile. Notification settings are divided into three groups: -* Global Settings -* Group Settings -* Project Settings +- Global settings +- Group settings +- Project settings Each of these settings have levels of notification: -* Disabled - turns off notifications -* Participating - receive notifications from related resources -* Watch - receive notifications from projects or groups user is a member of -* Global - notifications as set at the global settings -* Custom - user will receive notifications when mentioned, is participant and custom selected events. +- Watch: Receive notifications for any activity. +- On Mention: Receive notifications when `@mentioned` in comments. +- Participate: Receive notifications for threads you have participated in. +- Disabled: Turns off notifications. +- Custom: Receive notifications for custom selected events. +- Global: For groups and projects, notifications as per global settings. -#### Global Settings +### Global Settings -Global Settings are at the bottom of the hierarchy. +Global settings are at the bottom of the hierarchy. Any setting set here will be overridden by a setting at the group or a project level. Group or Project settings can use `global` notification setting which will then use anything that is set at Global Settings. -#### Group Settings +### Group Settings  -Group Settings are taking precedence over Global Settings but are on a level below Project or Subgroup Settings: +Group settings are taking precedence over Global Settings but are on a level below Project or Subgroup settings: ``` Group < Subgroup < Project @@ -46,11 +47,11 @@ Organization like this is suitable for users that belong to different groups but same need for being notified for every group they are member of. These settings can be configured on group page under the name of the group. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. -#### Project Settings +### Project Settings  -Project Settings are at the top level and any setting placed at this level will take precedence of any +Project settings are at the top level and any setting placed at this level will take precedence of any other setting. This is suitable for users that have different needs for notifications per project basis. These settings can be configured on project page under the name of the project. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. @@ -63,6 +64,8 @@ Below is the table of events users can be notified of: |------------------------------|-------------------------------------------------------------------|------------------------------| | New SSH key added | User | Security email, always sent. | | New email added | User | Security email, always sent. | +| Email changed | User | Security email, always sent. | +| Password changed | User | Security email, always sent. | | New user created | User | Sent on user creation, except for omniauth (LDAP)| | User added to project | User | Sent when user is added to project | | Project access level changed | User | Sent when user project access level is changed | @@ -73,11 +76,12 @@ Below is the table of events users can be notified of: ### Issue / Merge request events In most of the below cases, the notification will be sent to: + - Participants: - the author and assignee of the issue/merge request - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - - anyone mentioned by `@username` in any of the comments on the issue/merge request + - anyone mentioned by `@username` in any of the comments on the issue/merge request ...with notification level "Participating" or higher - Watchers: users with notification level "Watch" - Subscribers: anyone who manually subscribed to the issue/merge request @@ -90,12 +94,16 @@ In most of the below cases, the notification will be sent to: | Reassign issue | The above, plus the old assignee | | Reopen issue | | | Due issue | Participants and Custom notification level with this event selected | +| Change milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone issue | Subscribers, participants mentioned, and Custom notification level with this event selected | | New merge request | | | Push to merge request | Participants and Custom notification level with this event selected | | Reassign merge request | The above, plus the old assignee | | Close merge request | | | Reopen merge request | | | Merge merge request | | +| Change milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | +| Remove milestone merge request | Subscribers, participants mentioned, and Custom notification level with this event selected | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | | Failed pipeline | The author of the pipeline | | Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set | @@ -129,16 +137,19 @@ Notification emails include headers that provide extra content about the notific | X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc | #### X-GitLab-NotificationReason + This header holds the reason for the notification to have been sent out, where reason can be `mentioned`, `assigned`, `own_activity`, etc. Only one reason is sent out according to its priority: + - `own_activity` - `assigned` - `mentioned` -The reason in this header will also be shown in the footer of the notification email. For example an email with the +The reason in this header will also be shown in the footer of the notification email. For example an email with the reason `assigned` will have this sentence in the footer: `"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"` -**Note: Only reasons listed above have been implemented so far** -Further implementation is [being discussed here](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062) +NOTE: **Note:** +Only reasons listed above have been implemented so far. +Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062). diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md index 8c4e6ea8eab..e259e6fe50c 100644 --- a/doc/workflow/repository_mirroring.md +++ b/doc/workflow/repository_mirroring.md @@ -1,351 +1,399 @@ # Repository mirroring -Repository mirroring is a way to mirror repositories from external sources. -It can be used to mirror all branches, tags, and commits that you have -in your repository. +Repository mirroring allows for mirroring of repositories to and from external sources. It can be +used to mirror branches, tags, and commits between repositories. -Your mirror at GitLab will be updated automatically. You can -also manually trigger an update at most once every 5 minutes. +A repository mirror at GitLab will be updated automatically. You can also manually trigger an update +at most once every 5 minutes. ## Overview -Repository mirroring is very useful when, for some reason, you must use a -project from another source. +Repository mirroring is useful when you want to use a repository outside of GitLab. -There are two kinds of repository mirroring features supported by GitLab: -**push** and **pull**, the latter being only available in GitLab Enterprise Edition. -The **push** method mirrors the repository in GitLab to another location. +There are two kinds of repository mirroring supported by GitLab: -Once the mirror repository is updated, all new branches, -tags, and commits will be visible in the project's activity feed. -Users with at least [developer access][perms] to the project can also force an -immediate update with the click of a button. This button will not be available if -the mirror is already being updated or 5 minutes still haven't passed since its last update. +- Push: for mirroring a GitLab repository to another location. +- Pull: for mirroring a repository from another location to GitLab. **[STARTER]** -A few things/limitations to consider: +When the mirror repository is updated, all new branches, tags, and commits will be visible in the +project's activity feed. -- The repository must be accessible over `http://`, `https://`, `ssh://` or `git://`. -- If your HTTP repository is not publicly accessible, add authentication - information to the URL, like: `https://username@gitlab.company.com/group/project.git`. - In some cases, you might need to use a personal access token instead of a - password, e.g., you want to mirror to GitHub and have 2FA enabled. -- The import will time out after 15 minutes. For repositories that take longer - use a clone/push combination. -- The Git LFS objects will not be synced. You'll need to push/pull them - manually. +Users with at least [developer access](../user/permissions.md) to the project can also force an +immediate update, unless: + +- The mirror is already being updated. +- 5 minutes haven't elapsed since its last update. ## Use cases -- You migrated to GitLab but still need to keep your project in another source. - In that case, you can simply set it up to mirror to GitLab (pull) and all the - essential history of commits, tags and branches will be available in your - GitLab instance. -- You have old projects in another source that you don't use actively anymore, - but don't want to remove for archiving purposes. In that case, you can create - a push mirror so that your active GitLab repository can push its changes to the - old location. +The following are some possible use cases for repository mirroring: -## Pulling from a remote repository **[STARTER]** +- You migrated to GitLab but still need to keep your project in another source. In that case, you + can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + and branches will be available in your GitLab instance. **[STARTER]** +- You have old projects in another source that you don't use actively anymore, but don't want to + remove for archiving purposes. In that case, you can create a push mirror so that your active + GitLab repository can push its changes to the old location. ->[Introduced][ee-51] in GitLab Enterprise Edition 8.2. +## Pushing to a remote repository **[CORE]** -You can set up a repository to automatically have its branches, tags, and commits -updated from an upstream repository. This is useful when a repository you're -interested in is located on a different server, and you want to be able to -browse its content and its activity using the familiar GitLab interface. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise +> Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. -When creating a new project, you can enable repository mirroring when you choose -to import the repository from "Any repo by URL". Enter the full URL of the Git -repository to pull from and click on the **Mirror repository** checkbox. +For an existing project, you can set up push mirroring as follows: - +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter a repository URL. +1. Select **Push** from the **Mirror direction** dropdown. +1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. Check the **Only mirror protected branches** box, if necessary. +1. Click the **Mirror repository** button to save the configuration. -For an existing project, you can set up mirror pulling by visiting your project's -**Settings ➔ Repository** and searching for the "Pull from a remote repository" -section. Check the "Mirror repository" box and hit **Save changes** at the bottom. -You have a few options to choose from one being the user who will be the author -of all events in the activity feed that are the result of an update. This user -needs to have at least [master access][perms] to the project. Another option is -whether you want to trigger builds for mirror updates. + - +When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the +mirror diverging. All changes will end up in the mirrored repository whenever: -Since the repository on GitLab functions as a mirror of the upstream repository, -you are advised not to push commits directly to the repository on GitLab. -Instead, any commits should be pushed to the upstream repository, and will end -up in the GitLab repository automatically within a certain period of time -or when a [forced update](#forcing-an-update) is initiated. +- Commits are pushed to GitLab. +- A [forced update](#forcing-an-update) is initiated. -If you do manually update a branch in the GitLab repository, the branch will -become diverged from upstream, and GitLab will no longer automatically update -this branch to prevent any changes from being lost. +Changes pushed to files in the repository are automatically pushed to the remote mirror at least: - +- Within five minutes of being received. +- Within one minute if **Only mirror protected branches** is enabled. -### Trigger update using API **[STARTER]** +In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories** +section. ->[Introduced][ee-3453] in GitLab Enterprise Edition 10.3. +### Push only protected branches **[CORE]** -Pull mirroring uses polling to detect new branches and commits added upstream, -often many minutes afterwards. If you notify GitLab by [API][pull-api], updates -will be pulled immediately. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8. -Read the [Pull Mirror Trigger API docs][pull-api]. +You can choose to only push your protected branches from GitLab to your remote repository. -### Pull only protected branches **[STARTER]** +To use this option, check the **Only mirror protected branches** box when creating a repository +mirror. ->[Introduced][ee-3326] in GitLab Enterprise Edition 10.3. +## Setting up a push mirror from GitLab to GitHub **[CORE]** -You can choose to only pull the protected branches from your remote repository to GitLab. +To set up a mirror from GitLab to GitHub, you need to follow these steps: -To use this option go to your project's repository settings page under pull mirror. +1. Create a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `public_repo` box checked. +1. Fill in the **Git repository URL** field, with the personal access token instead of a password. + For example: `https://<GitHubUsername>:<GitHubPersonalAccessToken>@github.com/group/project.git`. +1. Click the **Mirror repository** button. +1. Wait, or click the update button. -### Overwrite diverged branches **[STARTER]** +## Pulling from a remote repository **[STARTER]** ->[Introduced][ee-4559] in GitLab Enterprise Edition 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. -You can choose to always update your local branch with the remote version even -if your local version has diverged from the remote. +You can set up a repository to automatically have its branches, tags, and commits updated from an +upstream repository. -To use this option go to your project's repository settings page under pull mirror. +This is useful when a repository you're interested in is located on a different server, and you want +to be able to browse its content and its activity using the familiar GitLab interface. -### Hard failure **[STARTER]** +To configure mirror pulling for an existing project: ->[Introduced][ee-3117] in GitLab Enterprise Edition 10.2. +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** + section. +1. Enter a repository URL. +1. Select **Pull** from the **Mirror direction** dropdown. +1. Select an authentication method from the **Authentication method** dropdown, if necessary. +1. If necessary, check the following boxes: + - **Overwrite diverged branches**. + - **Trigger pipelines for mirror updates**. + - **Only mirror protected branches**. +1. Click the **Mirror repository** button to save the configuration. -Once a mirror gets retried 14 times in a row, it will get marked as hard failed, -this will become visible in either the project main dashboard or in the -pull mirror settings page. + - +--- - + -When a project is hard failed, it will no longer get picked up for mirroring. -A user can resume the project mirroring again by either [forcing an update](#forcing-an-update) -or by changing the import URL in repository settings. +Because GitLab is now set to pull changes from the upstream repository, you should not push commits +directly to the repository on GitLab. Instead, any commits should be pushed to the upstream repository. +Changes pushed to the upstream repository will be pulled into the GitLab repository, either: -### SSH authentication **[STARTER]** +- Automatically within a certain period of time. +- When a [forced update](#forcing-an-update) is initiated. -> [Introduced][ee-2551] in GitLab Starter 9.5 +CAUTION: **Caution:** +If you do manually update a branch in the GitLab repository, the branch will become diverged from +upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost. -If you're mirroring over SSH (i.e., an `ssh://` URL), you can authenticate using -password-based authentication, just as over HTTPS, but you can also use public -key authentication. This is often more secure than password authentication, -especially when the source repository supports [Deploy Keys][deploy-key]. +### How it works -To get started, navigate to **Settings ➔ Repository ➔ Pull from a remote repository**, -enable mirroring (if not already enabled) and enter an `ssh://` URL. +Once you activate the pull mirroring feature, the mirror will be inserted into a queue. A scheduler +will start every minute and schedule a fixed number of mirrors for update, based on the configured maximum capacity. -> **NOTE**: SCP-style URLs, e.g., `git@example.com:group/project.git`, are not -supported at this time. +If the mirror updates successfully, it will be enqueued once again with a small backoff period. -Entering the URL adds two features to the page - `Fingerprints` and -`SSH public key authentication`: +If the mirror fails (for example, a branch diverged from upstream), the project's backoff period is +increased each time it fails, up to a maximum amount of time. - +### SSH authentication -SSH authentication is mutual. You have to prove to the server that you're -allowed to access the repository, but the server also has to prove to *you* that -it's who it claims to be. You provide your credentials as a password or public -key. The server that the source repository resides on provides its credentials -as a "host key", the fingerprint of which needs to be verified manually. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Push mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Pull mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 -Press the `Detect host keys` button. GitLab will fetch the host keys from the -server, and display the fingerprints to you: +SSH authentication is mutual: - +- You have to prove to the server that you're allowed to access the repository. +- The server also has to prove to *you* that it's who it claims to be. -You now need to verify that the fingerprints are those you expect. GitLab.com -and other code hosting sites publish their fingerprints in the open for you -to check: +You provide your credentials as a password or public key. The server that the +other repository resides on provides its credentials as a "host key", the +fingerprint of which needs to be verified manually. -* [AWS CodeCommit](http://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) -* [Bitbucket](https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints) -* [GitHub](https://help.github.com/articles/github-s-ssh-key-fingerprints/) -* [GitLab.com](https://about.gitlab.com/gitlab-com/settings/#ssh-host-keys-fingerprints) -* [Launchpad](https://help.launchpad.net/SSHFingerprints) -* [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) -* [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) +If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: -Other providers will vary. If you're running on-premises GitLab, or otherwise -have access to the source server, you can securely gather the key fingerprints: +- Password-based authentication, just as over HTTPS. +- Public key authentication. This is often more secure than password authentication, + especially when the other repository supports [Deploy Keys](../ssh/README.md#deploy-keys). -``` -$ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - -256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com (ECDSA) -256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com (ED25519) -2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) -``` +To get started: -(You may need to exclude `-E md5` for some older versions of SSH). +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter an `ssh://` URL for mirroring. -If you're an SSH expert and already have a `known_hosts` file you'd like to use -unaltered, then you can skip these steps. Just press the "Show advanced" button -and paste in the file contents: +NOTE: **Note:** +SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time. - +Entering the URL adds two buttons to the page: -Once you've **carefully verified** that all the fingerprints match your trusted -source, you can press `Save changes`. This will record the host keys, along with -the person who verified them (you!) and the date: +- **Detect host keys**. +- **Input host keys manually**. - +If you click the: -When pulling changes from the source repository, GitLab will now check that at -least one of the stored host keys matches before connecting. This can prevent -malicious code from being injected into your mirror, or your password being -stolen! +- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints. +- **Input host keys manually** button, a field is displayed where you can paste in host keys. -To use SSH public key authentication, you'll also need to choose that option -from the authentication methods dropdown. GitLab will generate a 4096-bit RSA -key and display the public component of that key to you: +Assuming you used the former, you now need to verify that the fingerprints are +those you expect. GitLab.com and other code hosting sites publish their +fingerprints in the open for you to check: - +- [AWS CodeCommit](http://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints) +- [Bitbucket](https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints) +- [GitHub](https://help.github.com/articles/github-s-ssh-key-fingerprints/) +- [GitLab.com](https://about.gitlab.com/gitlab-com/settings/#ssh-host-keys-fingerprints) +- [Launchpad](https://help.launchpad.net/SSHFingerprints) +- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/) +- [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/) -You then need to add the public SSH key to the source repository configuration. -If the source is hosted on GitLab, you should add it as a [Deploy Key][deploy-key]. -Other sources may require you to add the key to your user's `authorized_keys` -file - just paste the entire `ssh-rsa AAA.... user@host` block into the file on -its own line and save it. +Other providers will vary. If you're running self-managed GitLab, or otherwise +have access to the server for the other repository, you can securely gather the +key fingerprints: -Once the public key is set up on the source repository, press `Save changes` and your -mirror will begin working. +```sh +$ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f - +256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com (ECDSA) +256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com (ED25519) +2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA) +``` -If you need to change the key at any time, you can press the `Regenerate key` -button to do so. You'll have to update the source repository with the new key -to keep the mirror running. +NOTE: **Note:** +You may need to exclude `-E md5` for some older versions of SSH. -### How it works +When mirroring the repository, GitLab will now check that at least one of the +stored host keys matches before connecting. This can prevent malicious code from +being injected into your mirror, or your password being stolen. -Once you activate the pull mirroring feature, the mirror will be inserted into -a queue. A scheduler will start every minute and schedule a fixed amount of -mirrors for update, based on the configured maximum capacity. +### SSH public key authentication -If the mirror successfully updates it will be enqueued once again with a small -backoff period. +To use SSH public key authentication, you'll also need to choose that option +from the **Authentication method** dropdown. GitLab will generate a 4096-bit RSA +key and display the public component of that key to you. -If the mirror fails (eg: branch diverged from upstream), the project's backoff -period will be penalized each time it fails up to a maximum amount of time. +You then need to add the public SSH key to the other repository's configuration: -## Pushing to a remote repository +- If the other repository is hosted on GitLab, you should add the public SSH key + as a [Deploy Key](../ssh/README.md#deploy-keys). +- If the other repository is hosted elsewhere, you may need to add the key to + your user's `authorized_keys` file. Paste the entire public SSH key into the + file on its own line and save it. ->[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in -GitLab Enterprise Edition 8.7. [Moved to GitLab Community Edition][ce-18715] in 10.8. +If you need to change the key at any time, you can remove and re-add the mirror +to generate a new key. You'll have to update the other repository with the new +key to keep the mirror running. -For an existing project, you can set up push mirror from your project's -**Settings ➔ Repository** and searching for the "Push to a remote repository" -section. Check the "Remote mirror repository" box and fill in the Git URL of -the repository to push to. Click **Save changes** for the changes to take -effect. +### Overwrite diverged branches **[STARTER]** - +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. -When push mirroring is enabled, you are advised not to push commits directly -to the mirrored repository to prevent the mirror diverging. -All changes will end up in the mirrored repository whenever commits -are pushed to GitLab, or when a [forced update](#forcing-an-update) is -initiated. +You can choose to always update your local branches with remote versions, even if they have +diverged from the remote. -Pushes into GitLab are automatically pushed to the remote mirror at least once -every 5 minutes after they are received or once every minute if **push only -protected branches** is enabled. +CAUTION: **Caution:** +For mirrored branches, enabling this option results in the loss of local changes. -In case of a diverged branch, you will see an error indicated at the **Mirror -repository** settings. +To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. - +### Only mirror protected branches **[STARTER]** -### Push only protected branches +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. ->[Introduced][ee-3350] in GitLab Enterprise Edition 10.3. [Moved to GitLab Community Edition][ce-18715] in 10.8. +You can choose to pull mirror only the protected branches from your remote repository to GitLab. +Non-protected branches are not mirrored and can diverge. -You can choose to only push your protected branches from GitLab to your remote repository. +To use this option, check the **Only mirror protected branches** box when creating a repository mirror. -To use this option go to your project's repository settings page under push mirror. +### Hard failure **[STARTER]** -## Setting up a push mirror from GitLab to GitHub +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. -To set up a mirror from GitLab to GitHub, you need to follow these steps: +Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard +failed. This will become visible in either the: -1. Create a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the "public_repo" box checked: +- Project's main dashboard. +- Pull mirror settings page. -  +When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the +project mirroring again by [Forcing an update](#forcing-an-update). -1. Fill in the "Git repository URL" with the personal access token replacing the password `https://GitHubUsername:GitHubPersonalAccessToken@github.com/group/project.git`: +### Trigger update using API **[STARTER]** -  +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in +[GitLab Starter](https://about.gitlab.com/pricing/) 10.3. -1. Save -1. And either wait or trigger the "Update Now" button: +Pull mirroring uses polling to detect new branches and commits added upstream, often minutes +afterwards. If you notify GitLab by [API](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project), +updates will be pulled immediately. + +For more information, see [Start the pull mirroring process for a Project](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project). + +## Forcing an update **[CORE]** + +While mirrors are scheduled to update automatically, you can always force an update by using the +update button which is available on the **Mirroring repositories** section of the **Repository Settings** page. + + + +## Bidirectional mirroring **[STARTER]** + +CAUTION: **Caution:** +Bidirectional mirroring may cause conflicts. + +If you configure a GitLab repository to both pull from, and push to, the same remote source, there +is no guarantee that either repository will update correctly. If you set up a repository for +bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve +them and how they will be resolved. + +Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can +be prevented by: + +- [Pulling only protected branches](#pull-only-protected-branches). +- [Pushing only protected branches](#push-only-protected-branches). + +You should [protect the branches](../user/project/protected_branches.md) you wish to mirror on both +remotes to prevent conflicts caused by rewriting history. + +Bidirectional mirroring also creates a race condition where commits made close together to the same +branch causes conflicts. The race condition can be mitigated by reducing the mirroring delay by using +a [Push event webhook](../user/project/integrations/webhooks.md#push-events) to trigger an immediate +pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring +protected branches. + +### Preventing conflicts using a `pre-receive` hook + +> **Warning:** The solution proposed will negatively impact the performance of +> Git push operations because they will be proxied to the upstream Git +> repository. + +A server-side `pre-receive` hook can be used to prevent the race condition +described above by only accepting the push after first pushing the commit to +the upstream Git repository. In this configuration one Git repository acts as +the authoritative upstream, and the other as downstream. The `pre-receive` hook +will be installed on the downstream repository. + +Read about [configuring custom Git hooks](../administration/custom_hooks.md) on the GitLab server. + +A sample `pre-receive` hook is provided below. + +```bash +#!/usr/bin/env bash + +# --- Assume only one push mirror target +# Push mirroring remotes are named `remote_mirror_<id>`, this finds the first remote and uses that. +TARGET_REPO=$(git remote | grep -m 1 remote_mirror) + +proxy_push() +{ + # --- Arguments + OLDREV=$(git rev-parse $1) + NEWREV=$(git rev-parse $2) + REFNAME="$3" + + # --- Pattern of branches to proxy pushes + whitelisted=$(expr "$branch" : "\(master\)") + + case "$refname" in + refs/heads/*) + branch=$(expr "$refname" : "refs/heads/\(.*\)") + + if [ "$whitelisted" = "$branch" ]; then + error="$(git push --quiet $TARGET_REPO $NEWREV:$REFNAME 2>&1)" + fail=$? + + if [ "$fail" != "0" ]; then + echo >&2 "" + echo >&2 " Error: updates were rejected by upstream server" + echo >&2 " This is usually caused by another repository pushing changes" + echo >&2 " to the same ref. You may want to first integrate remote changes" + echo >&2 "" + return + fi + fi + ;; + esac +} + +# Allow dual mode: run from the command line just like the update hook, or +# if no arguments are given then run as a hook script +if [ -n "$1" -a -n "$2" -a -n "$3" ]; then + # Output to the terminal in command line mode - if someone wanted to + # resend an email; they could redirect the output to sendmail + # themselves + PAGER= proxy_push $2 $3 $1 +else + # Push is proxied upstream one ref at a time. Because of this it is possible + # for some refs to succeed, and others to fail. This will result in a failed + # push. + while read oldrev newrev refname + do + proxy_push $oldrev $newrev $refname + done +fi +``` -  +### Mirroring with Perforce Helix via Git Fusion **[STARTER]** -## Forcing an update +CAUTION: **Warning:** +Bidirectional mirroring should not be used as a permanent configuration. Refer to +[Migrating from Perforce Helix](../user/project/import/perforce.md) for alternative migration approaches. -While mirrors are scheduled to update automatically, you can always force an update -by using the **Update now** button which is exposed in various places: +[Git Fusion](https://www.perforce.com/video-tutorials/git-fusion-overview) provides a Git interface +to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally +mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. -- in the commits page -- in the branches page -- in the tags page -- in the **Mirror repository** settings page +If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix +will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored +due to the performance limitations of Git Fusion. -## Bidirectional mirroring +When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion +settings are recommended: -CAUTION: **Warning:** -There is no bidirectional support without conflicts. If you -configure a repository to pull and push to a second remote, there is no -guarantee that it will update correctly on both remotes. If you configure -a repository for bidirectional mirroring, you should consider when conflicts -occur who and how they will be resolved. - -Rewriting any mirrored commit on either remote will cause conflicts and -mirroring to fail. This can be prevented by [only pulling protected branches]( -#pull-only-protected-branches) and [only pushing protected branches]( -#push-only-protected-branches). You should protect the branches you wish to -mirror on both remotes to prevent conflicts caused by rewriting history. - -Bidirectional mirroring also creates a race condition where commits to the same -branch in close proximity will cause conflicts. The race condition can be -mitigated by reducing the mirroring delay by using a Push event webhook to -trigger an immediate pull to GitLab. Push mirroring from GitLab is rate limited -to once per minute when only push mirroring protected branches. - -It may be possible to implement a locking mechanism using the server-side -`pre-receive` hook to prevent the race condition. Read about [configuring -custom Git hooks][hooks] on the GitLab server. - -### Mirroring with Perforce via GitFusion +- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed + by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user. +- `unknown_git` user will be used as the commit author if the GitLab user does not exist in + Perforce Helix. -CAUTION: **Warning:** -Bidirectional mirroring should not be used as a permanent -configuration. There is no bidirectional mirroring without conflicts. -Refer to [Migrating from Perforce Helix][perforce] for alternative migration -approaches. - -GitFusion provides a Git interface to Perforce which can be used by GitLab to -bidirectionally mirror projects with GitLab. This may be useful in some -situations when migrating from Perforce to GitLab where overlapping Perforce -workspaces cannot be migrated simultaneously to GitLab. - -If using mirroring with Perforce you should only mirror protected branches. -Perforce will reject any pushes that rewrite history. It is recommended that -only the fewest number of branches are mirrored due to the performance -limitations of GitFusion. - -[ee-51]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51 -[ee-2551]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551 -[ee-3117]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117 -[ee-3326]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326 -[ee-3350]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350 -[ee-3453]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453 -[ee-4559]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559 -[ce-18715]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715 -[perms]: ../user/permissions.md -[hooks]: ../administration/custom_hooks.md -[deploy-key]: ../ssh/README.md#deploy-keys -[webhook]: ../user/project/integrations/webhooks.md#push-events -[pull-api]: ../api/projects.md#start-the-pull-mirroring-process-for-a-project -[perforce]: ../user/project/import/perforce.md +Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/perforce/doc.current/manuals/git-fusion/Content/Git-Fusion/section_vss_bdw_w3.html#section_zdp_zz1_3l). diff --git a/doc/workflow/repository_mirroring/repository_mirroring_detect_host_keys.png b/doc/workflow/repository_mirroring/repository_mirroring_detect_host_keys.png Binary files differdeleted file mode 100644 index 2377a4a6516..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_detect_host_keys.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch.png b/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch.png Binary files differdeleted file mode 100644 index 45c9bce0889..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png b/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png Binary files differdeleted file mode 100644 index 786bd23eee6..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_diverged_branch_push.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png b/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png Binary files differdeleted file mode 100644 index 139de42d8db..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_github_edit_personal_access_token.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png Binary files differdeleted file mode 100644 index ccbc1d92329..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png b/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png Binary files differdeleted file mode 100644 index b16b3d2828e..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_main.png b/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_main.png Binary files differdeleted file mode 100644 index d8af5ce129e..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_main.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_settings.png b/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_settings.png Binary files differdeleted file mode 100644 index a10102e97ac..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_hard_failed_settings.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_new_project.png b/doc/workflow/repository_mirroring/repository_mirroring_new_project.png Binary files differdeleted file mode 100644 index 43bf304838f..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_new_project.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_pull_advanced_host_keys.png b/doc/workflow/repository_mirroring/repository_mirroring_pull_advanced_host_keys.png Binary files differdeleted file mode 100644 index 1f1b3e1d5fb..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_pull_advanced_host_keys.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_pull_settings.png b/doc/workflow/repository_mirroring/repository_mirroring_pull_settings.png Binary files differdeleted file mode 100644 index b8dfddb3d02..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_pull_settings.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_pull_settings_for_ssh.png b/doc/workflow/repository_mirroring/repository_mirroring_pull_settings_for_ssh.png Binary files differdeleted file mode 100644 index 8f1de1d3003..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_pull_settings_for_ssh.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png b/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png Binary files differdeleted file mode 100644 index f8199aa7c0f..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_push_settings.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_ssh_host_keys_verified.png b/doc/workflow/repository_mirroring/repository_mirroring_ssh_host_keys_verified.png Binary files differdeleted file mode 100644 index 930d10a0822..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_ssh_host_keys_verified.png +++ /dev/null diff --git a/doc/workflow/repository_mirroring/repository_mirroring_ssh_public_key_authentication.png b/doc/workflow/repository_mirroring/repository_mirroring_ssh_public_key_authentication.png Binary files differdeleted file mode 100644 index adc1eedac44..00000000000 --- a/doc/workflow/repository_mirroring/repository_mirroring_ssh_public_key_authentication.png +++ /dev/null diff --git a/doc/workflow/shortcuts.md b/doc/workflow/shortcuts.md index b2f1cbec204..7359e1c6119 100644 --- a/doc/workflow/shortcuts.md +++ b/doc/workflow/shortcuts.md @@ -93,4 +93,5 @@ You can see GitLab's keyboard shortcuts by using 'shift + ?' | Keyboard Shortcut | Description | | ----------------- | ----------- | -| <kbd>⌘</kbd> + <kbd>p</kbd> | Go to file | +| <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>p</kbd> | Go to file | +| <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message) | diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md index bfe87bb2ceb..8a75687e4f5 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -62,12 +62,13 @@ To remove all the time spent at once, use `/remove_time_spent`. ## Configuration The following time units are available: +* months (mo) * weeks (w) * days (d) * hours (h) * minutes (m) -Default conversion rates are 1w = 5d and 1d = 8h. +Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. [landing]: https://about.gitlab.com/features/time-tracking [quick actions]: ../user/project/quick_actions.md |
