diff options
| author | Rémy Coutable <remy@rymai.me> | 2019-02-01 19:05:59 +0300 |
|---|---|---|
| committer | Rémy Coutable <remy@rymai.me> | 2019-02-01 19:05:59 +0300 |
| commit | dd89d8365d08728883cc1d557b83fd1f1f038615 (patch) | |
| tree | 8caf0bfbba64377e62602e948a39b3fcf7bc9c8d /doc | |
| parent | edc51a2fdc6fed4d94381d846910f5a980000e67 (diff) | |
| parent | 1de1608a28d03f86c131961c046a7afbbf5b6e51 (diff) | |
Merge branch 'master' into 'patch-29'
# Conflicts:
# doc/api/merge_requests.md
Diffstat (limited to 'doc')
613 files changed, 17314 insertions, 7749 deletions
diff --git a/doc/README.md b/doc/README.md index 03371226041..1a0359f9e2a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,137 +3,232 @@ 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. -<img class="image-noshadow" src="img/devops_lifecycle.png" alt="DevOps Lifecycle"> +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. +GitLab is like a top-of-the-line kitchen for making software. As the executive +chef, you decide what software you want serve. Using your recipe, GitLab handles +all the prep work, cooking, and delivery, so you can turn around orders faster +than ever. + +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. | -- 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. +<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> -#### Migrate and import your projects from other platforms +### Manage + +GitLab provides statistics and insight into ways you can maximize the value of GitLab in your organization. + +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. -- [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 **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 +#### Projects and Groups -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. +| 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 +<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> -- [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) - -#### 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 +236,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 +254,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, 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 (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/README.md b/doc/administration/auth/README.md index 373d4239f71..54be7b616cc 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -10,7 +10,7 @@ providers. - [LDAP](ldap.md) Includes Active Directory, Apple Open Directory, Open LDAP, and 389 Server - [OmniAuth](../../integration/omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, Crowd, Azure and Authentiq ID + Bitbucket, Facebook, Shibboleth, Crowd, Azure, Authentiq ID, and JWT - [CAS](../../integration/cas.md) Configure GitLab to sign in using CAS - [SAML](../../integration/saml.md) Configure GitLab as a SAML 2.0 Service Provider - [Okta](okta.md) Configure GitLab to sign in using Okta 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/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 621d4f77d5e..0d03b481881 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -255,7 +255,7 @@ After configuring LDAP, basic authentication will be available. Users can then l Users that are removed from the LDAP base group (e.g `OU=GitLab INT,DC=GitLab,DC=org`) will be **blocked** in GitLab. [More information](../ldap.md#security) on LDAP security. -If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab will ignore everything after the first '@' in the LDAP username used on login. Example: The username `jon.doe@example.com` is converted to `jon.doe` when authenticating with the LDAP server. Disable this setting if you use `userPrincipalName` as the `uid`. +If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab will ignore everything after the first '@' in the LDAP username used on login. Example: The username `` jon.doe@example.com `` is converted to `jon.doe` when authenticating with the LDAP server. Disable this setting if you use `userPrincipalName` as the `uid`. ## LDAP extended features on GitLab EE diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 8b00f52ffc1..497298503ad 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -26,15 +26,15 @@ JWT will provide you with a secret key for you to use. ```ruby gitlab_rails['omniauth_providers'] = [ { name: 'jwt', - app_secret: 'YOUR_APP_SECRET', args: { - algorithm: 'HS256', - uid_claim: 'email', - required_claims: ["name", "email"], - info_maps: { name: "name", email: "email" }, - auth_url: 'https://example.com/', - valid_within: nil, - } + secret: 'YOUR_APP_SECRET', + algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512' + uid_claim: 'email', + required_claims: ['name', 'email'], + info_maps: { name: 'name', email: 'email' }, + auth_url: 'https://example.com/', + valid_within: 3600 # 1 hour + } } ] ``` @@ -43,15 +43,15 @@ JWT will provide you with a secret key for you to use. ``` - { name: 'jwt', - app_secret: 'YOUR_APP_SECRET', args: { - algorithm: 'HS256', - uid_claim: 'email', - required_claims: ["name", "email"], - info_map: { name: "name", email: "email" }, - auth_url: 'https://example.com/', - valid_within: null, - } + secret: 'YOUR_APP_SECRET', + algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512' + uid_claim: 'email', + required_claims: ['name', 'email'], + info_map: { name: 'name', email: 'email' }, + auth_url: 'https://example.com/', + valid_within: 3600 # 1 hour + } } ``` @@ -60,7 +60,7 @@ JWT will provide you with a secret key for you to use. 1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL. 1. Save the configuration file. -1. [Reconfigure GitLab][] or [restart GitLab][] for the changes to take effect if you +1. [Reconfigure][] or [restart 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 JWT icon below the regular sign in form. @@ -68,5 +68,5 @@ Click the icon to begin the authentication process. JWT will ask the user to sign in and authorize the GitLab application. If everything goes well, the user will be redirected to GitLab and will be signed in. -[reconfigure GitLab]: ../restart_gitlab.md#omnibus-gitlab-reconfigure +[reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../restart_gitlab.md#installations-from-source diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 54ded25291a..0ac73c55580 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -335,7 +335,7 @@ group, you can use the following syntax: ``` Find more information about this "LDAP_MATCHING_RULE_IN_CHAIN" filter at -https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx. Support for +<https://docs.microsoft.com/en-us/windows/desktop/ADSI/search-filter-syntax>. Support for nested members in the user filter should not be confused with [group sync nested groups support (EE only)](https://docs.gitlab.com/ee/administration/auth/ldap-ee.html#supported-ldap-group-types-attributes). 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..db0b3e1270c 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -11,7 +11,7 @@ With the Container Registry integrated into GitLab, every project can have its own space to store its Docker images. You can read more about the Container Registry at -https://docs.docker.com/registry/introduction/. +<https://docs.docker.com/registry/introduction/>. ## Enable the Container Registry @@ -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. @@ -375,7 +378,7 @@ Read more about the individual driver's config options in the > **Warning** GitLab will not backup Docker images that are not stored on the filesystem. Remember to enable backups with your object storage provider if desired. -> +> > **Important** Enabling storage driver other than `filesystem` would mean that your Docker client needs to be able to access the storage backend directly. So you must use an address that resolves and is accessible outside GitLab server. @@ -601,6 +604,52 @@ Registry out of the box, it is possible to make it work if you follow [Docker's documentation][docker-insecure-self-signed]. You may find some additional information in [issue 18239][ce-18239]. +## Troubleshooting + +When using AWS S3 with the GitLab registry, an error may occur when pushing +large images. Look in the Registry log for the following error: + +``` +level=error msg="response completed with error" err.code=unknown err.detail="unexpected EOF" err.message="unknown error" +``` + +To resolve the error specify a `chunksize` value in the Registry configuration. +Start with a value between `25000000` (25MB) and `50000000` (50MB). + +**For Omnibus installations** + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + registry['storage'] = { + 's3' => { + 'accesskey' => 'AKIAKIAKI', + 'secretkey' => 'secret123', + 'bucket' => 'gitlab-registry-bucket-AKIAKIAKI', + 'chunksize' => 25000000 + } + } + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**For installations from source** + +1. Edit `config/gitlab.yml`: + + ```yaml + storage: + s3: + accesskey: 'AKIAKIAKI' + secretkey: 'secret123' + bucket: 'gitlab-registry-bucket-AKIAKIAKI' + chunksize: 25000000 + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + [ce-18239]: https://gitlab.com/gitlab-org/gitlab-ce/issues/18239 [docker-insecure-self-signed]: https://docs.docker.com/registry/insecure/#use-self-signed-certificates [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index c58ced7d520..60ad4bf4e8f 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -60,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/git_protocol.md b/doc/administration/git_protocol.md new file mode 100644 index 00000000000..11b2adeeeb8 --- /dev/null +++ b/doc/administration/git_protocol.md @@ -0,0 +1,110 @@ +--- +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. +> [Temporarily disabled](https://gitlab.com/gitlab-org/gitlab-ce/issues/55769) in GitLab 11.5.8, 11.6.6, 11.7.1, and 11.8+ + +NOTE: **Note:** +Git protocol v2 support has been [temporarily disabled](https://gitlab.com/gitlab-org/gitlab-ce/issues/55769), +as a feature used to hide certain internal references does not function when it +is enabled, and this has a security impact. Once this problem has been resolved, +protocol v2 support will be re-enabled. + +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 e1b2a0a24eb..abef7a6cd33 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,7 +23,7 @@ gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` To change a Gitaly setting in installations from source you can edit -`/home/git/gitaly/config.toml`. Changes will be applied when you run +`/home/git/gitaly/config.toml`. Changes will be applied when you run `service gitlab restart`. ```toml @@ -47,15 +45,28 @@ 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. + +### Network architecture + +- gitlab-rails shards repositories into "repository storages" +- gitlab-rails/config/gitlab.yml contains a map from storage names to + (Gitaly address, Gitaly token) pairs +- the `storage name` -\> `(Gitaly address, Gitaly token)` map in + gitlab.yml is the single source of truth for the Gitaly network + topology +- a (Gitaly address, Gitaly token) corresponds to a Gitaly server +- a Gitaly server hosts one or more storages +- Gitaly addresses must be specified in such a way that they resolve + correctly for ALL Gitaly clients +- Gitaly clients are: unicorn, sidekiq, gitlab-workhorse, + gitlab-shell, and Gitaly itself +- special case: a Gitaly server must be able to make RPC calls **to + itself** via its own (Gitaly address, Gitaly token) pair as + specified in gitlab-rails/config/gitlab.yml +- Gitaly servers must not be exposed to the public internet Gitaly network traffic is unencrypted so you should use a firewall to restrict access to your Gitaly server. @@ -99,13 +110,13 @@ documentation on configuring Gitaly authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication) . -Gitaly must trigger some callbacks to GitLab via GitLab Shell. As a result, +Gitaly must trigger some callbacks to GitLab via GitLab Shell. As a result, the GitLab Shell secret must be the same between the other GitLab servers and the Gitaly server. The easiest way to accomplish this is to copy `/etc/gitlab/gitlab-secrets.json` from an existing GitLab server to the Gitaly server. Without this shared secret, -Git operations in GitLab will result in an API error. +Git operations in GitLab will result in an API error. -> **NOTE:** In most or all cases the storage paths below end in `/repositories` which is +> **NOTE:** In most or all cases the storage paths below end in `/repositories` which is different than `path` in `git_data_dirs` of Omnibus installations. Check the directory layout on your Gitaly server to be sure. @@ -141,6 +152,11 @@ gitaly['storage'] = [ { 'name' => 'default', 'path' => '/mnt/gitlab/default/repositories' }, { 'name' => 'storage1', 'path' => '/mnt/gitlab/storage1/repositories' }, ] + +# To use tls for gitaly you need to add +gitaly['tls_listen_addr'] = "0.0.0.0:9999" +gitaly['certificate_path'] = "path/to/cert.pem" +gitaly['key_path'] = "path/to/key.pem" ``` Source installations: @@ -148,6 +164,11 @@ Source installations: ```toml # /home/git/gitaly/config.toml listen_addr = '0.0.0.0:8075' +tls_listen_addr = '0.0.0.0:9999' + +[tls] +certificate_path = /path/to/cert.pem +key_path = /path/to/key.pem [auth] token = 'abc123secret' @@ -213,6 +234,72 @@ Gitaly logs on your Gitaly server (`sudo gitlab-ctl tail gitaly` or coming in. One sure way to trigger a Gitaly request is to clone a repository from your GitLab server over HTTP. +## TLS support + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22602) in GitLab 11.7. + +Gitaly supports TLS credentials for GRPC authentication. To be able to communicate +with a gitaly instance that listens for secure connections you will need to use `tls://` url +scheme in the `gitaly_address` of the corresponding storage entry in the gitlab configuration. + +The admin needs to bring their own certificate as we do not provide that automatically. +The certificate to be used needs to be installed on all gitaly nodes and on all client nodes that communicate with it following procedures described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) + +### Example TLS configuration + +### Omnibus installations: + +#### On client nodes: + +```ruby +# /etc/gitlab/gitlab.rb +git_data_dirs({ + 'default' => { 'path' => '/mnt/gitlab/default', 'gitaly_address' => 'tls://gitaly.internal:9999' }, + 'storage1' => { 'path' => '/mnt/gitlab/storage1', 'gitaly_address' => 'tls://gitaly.internal:9999' }, +}) + +gitlab_rails['gitaly_token'] = 'abc123secret' +``` + +#### On gitaly server nodes: + +```ruby +gitaly['tls_listen_addr'] = "0.0.0.0:9999" +gitaly['certificate_path'] = "path/to/cert.pem" +gitaly['key_path'] = "path/to/key.pem" +``` + +### Source installations: + +#### On client nodes: + +```yaml +# /home/git/gitlab/config/gitlab.yml +gitlab: + repositories: + storages: + default: + path: /mnt/gitlab/default/repositories + gitaly_address: tls://gitaly.internal:9999 + storage1: + path: /mnt/gitlab/storage1/repositories + gitaly_address: tls://gitaly.internal:9999 + + gitaly: + token: 'abc123secret' +``` + +#### On gitaly server nodes: + +```toml +# /home/git/gitaly/config.toml +tls_listen_addr = '0.0.0.0:9999' + +[tls] +certificate_path = '/path/to/cert.pem' +key_path = '/path/to/key.pem' +``` + ## Disabling or enabling the Gitaly service in a cluster environment If you are running Gitaly [as a remote @@ -245,3 +332,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/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 040c9ecae55..74b0e2c8184 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -37,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 @@ -54,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 @@ -63,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. diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index b5d1ff698c6..987a0b9f350 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 @@ -82,7 +82,7 @@ When a **Master** fails to respond, it's the application's responsibility for a new **Master**). To get a better understanding on how to correctly set up Sentinel, please read -the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as +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. @@ -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. @@ -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. @@ -545,10 +545,10 @@ discussed in [Redis setup overview](#redis-setup-overview) and Here is a list and description of each **machine** and the assigned **IP**: -* `10.0.0.1`: Redis Master + Sentinel 1 -* `10.0.0.2`: Redis Slave 1 + Sentinel 2 -* `10.0.0.3`: Redis Slave 2 + Sentinel 3 -* `10.0.0.4`: GitLab application +- `10.0.0.1`: Redis Master + Sentinel 1 +- `10.0.0.2`: Redis Slave 1 + Sentinel 2 +- `10.0.0.3`: Redis Slave 2 + Sentinel 3 +- `10.0.0.4`: GitLab application Please note that after the initial configuration, if a failover is initiated by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master** @@ -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 5823c575251..14e2784c419 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -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 @@ -214,10 +214,10 @@ For this example, **Sentinel 1** will be configured in the same machine as the Here is a list and description of each **machine** and the assigned **IP**: -* `10.0.0.1`: Redis Master + Sentinel 1 -* `10.0.0.2`: Redis Slave 1 + Sentinel 2 -* `10.0.0.3`: Redis Slave 2 + Sentinel 3 -* `10.0.0.4`: GitLab application +- `10.0.0.1`: Redis Master + Sentinel 1 +- `10.0.0.2`: Redis Slave 1 + Sentinel 2 +- `10.0.0.3`: Redis Slave 2 + Sentinel 3 +- `10.0.0.4`: GitLab application Please note that after the initial configuration, if a failover is initiated by the Sentinel nodes, the Redis nodes will be reconfigured and the **Master** @@ -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/housekeeping.md b/doc/administration/housekeeping.md index bb621b788f1..058346df56d 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -17,19 +17,18 @@ The housekeeping function will run a `repack` or `gc` depending on the For example in the following scenario a `git repack -d` will be executed: -+ Project: pushes since gc counter (`pushes_since_gc`) = `10` -+ Git GC period = `200` -+ Full repack period = `50` +- Project: pushes since gc counter (`pushes_since_gc`) = `10` +- Git GC period = `200` +- Full repack period = `50` When the `pushes_since_gc` value is 50 a `repack -A -d --pack-kept-objects` will run, similarly when the `pushes_since_gc` value is 200 a `git gc` will be run. -+ `git gc` ([man page][man-gc]) runs a number of housekeeping tasks, -such as compressing filerevisions (to reduce disk space and increase performance) -and removing unreachable objects which may have been created from prior invocations of -`git add`. - -+ `git repack` ([man page][man-repack]) re-organize existing packs into a single, more efficient pack. +- `git gc` ([man page][man-gc]) runs a number of housekeeping tasks, + such as compressing filerevisions (to reduce disk space and increase performance) + and removing unreachable objects which may have been created from prior invocations of + `git add`. +- `git repack` ([man page][man-repack]) re-organize existing packs into a single, more efficient pack. You can find this option under your **[Project] > Edit Project**. @@ -39,4 +38,4 @@ You can find this option under your **[Project] > Edit Project**. [ce-2371]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2371 "Housekeeping merge request" [man-gc]: https://www.kernel.org/pub/software/scm/git/docs/git-gc.html "git gc man page" -[man-repack]: https://www.kernel.org/pub/software/scm/git/docs/git-repack.html
\ No newline at end of file +[man-repack]: https://www.kernel.org/pub/software/scm/git/docs/git-repack.html diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 27a3710632d..05873e01a08 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -13,43 +13,45 @@ GitLab has several features based on receiving incoming emails: ## Requirements -Handling incoming emails requires an [IMAP]-enabled email account. GitLab -requires one of the following three strategies: +Handling incoming emails requires an [IMAP](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol)-enabled +email account. GitLab requires one of the following three strategies: -- Email sub-addressing -- Dedicated email address +- Email sub-addressing (recommended) - Catch-all mailbox +- Dedicated email address (supports Reply by Email only) Let's walk through each of these options. -**If your provider or server supports email sub-addressing, we recommend using it. -Most features (other than reply by email) only work with sub-addressing.** - -[IMAP]: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol - ### Email sub-addressing [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is -a feature where any email to `user+some_arbitrary_tag@example.com` will end up -in the mailbox for `user@example.com`, and is supported by providers such as -Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the -[Postfix mail server] which you can run on-premises. - -[Postfix mail server]: reply_by_email_postfix_setup.md +a mail server feature where any email to `user+arbitrary_tag@example.com` will end up +in the mailbox for `user@example.com` . It is supported by providers such as +Gmail, Google Apps, Yahoo! Mail, Outlook.com, and iCloud, as well as the +[Postfix mail server](reply_by_email_postfix_setup.md), which you can run on-premises. + +TIP: **Tip:** +If your provider or server supports email sub-addressing, we recommend using it. +A dedicated email address only supports Reply by Email functionality. +A catch-all mailbox supports the same features as sub-addressing as of GitLab 11.7, +but sub-addressing is still preferred because only one email address is used, +leaving a catch-all available for other purposes beyond GitLab. -### Dedicated email address +### Catch-all mailbox -This solution is really simple to set up: you just have to create an email -address dedicated to receive your users' replies to GitLab notifications. +A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain +receives all emails addressed to the domain that do not match any addresses that +exist on the mail server. -### Catch-all mailbox +As of GitLab 11.7, catch-all mailboxes support the same features as +email sub-addressing, but email sub-addressing remains our recommendation so that you +can reserve your catch-all mailbox for other purposes. -A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will -"catch all" the emails addressed to the domain that do not exist in the mail -server. +### Dedicated email address -GitLab can be set up to allow users to comment on issues and merge requests by -replying to notification emails. +This solution is relatively simple to set up: you just need to create an email +address dedicated to receive your users' replies to GitLab notifications. However, +this method only supports replies, and not the other features of [incoming email](#incoming-email). ## Set it up @@ -160,14 +162,16 @@ for a real-world example of this exploit. gitlab_rails['incoming_email_idle_timeout'] = 60 ``` - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes - mailbox incoming@exchange.example.com + Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the + catch-all mailbox incoming@exchange.example.com ```ruby gitlab_rails['incoming_email_enabled'] = true - # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here - gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com" + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + # Exchange does not support sub-addressing, so a catch-all mailbox must be used. + gitlab_rails['incoming_email_address'] = "incoming-%{key}@exchange.example.com" # Email account username # Typically this is the userPrincipalName (UPN) @@ -279,15 +283,17 @@ for a real-world example of this exploit. idle_timeout: 60 ``` - Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes - mailbox incoming@exchange.example.com + Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes the + catch-all mailbox incoming@exchange.example.com ```yaml incoming_email: enabled: true - # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here - address: "incoming@exchange.example.com" + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + # Exchange does not support sub-addressing, so a catch-all mailbox must be used. + address: "incoming-%{key}@exchange.example.com" # Email account username # Typically this is the userPrincipalName (UPN) diff --git a/doc/administration/index.md b/doc/administration/index.md index 8e6fa9563c7..0b673d61139 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -41,13 +41,14 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Polling](polling.md): Configure how often the GitLab UI polls for updates. - [GitLab Pages configuration](pages/index.md): Enable and configure GitLab Pages. - [GitLab Pages configuration for GitLab source installations](pages/source.md): Enable and configure GitLab Pages on -[source installations](../install/installation.md#installation-from-source). + [source installations](../install/installation.md#installation-from-source). - [Environment variables](environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab. - [Plugins](plugins.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. - [Enforcing Terms of Service](../user/admin_area/settings/terms.md) - [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. +- [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI. #### Customizing GitLab's appearance @@ -80,7 +81,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate with [Mattermost](https://about.mattermost.com/), an open source, private cloud workplace for web messaging. - [PlantUML](integration/plantuml.md): Create simple diagrams in AsciiDoc and Markdown documents -created in snippets, wikis, and repos. + created in snippets, wikis, and repos. - [Web terminals](integration/terminal.md): Provide terminal access to your applications deployed to Kubernetes from within GitLab's CI/CD [environments](../ci/environments.md#web-terminals). ## User settings and permissions @@ -88,13 +89,14 @@ created in snippets, wikis, and repos. - [Libravatar](../customization/libravatar.md): Use Libravatar instead of Gravatar for user avatars. - [Sign-up restrictions](../user/admin_area/settings/sign_up_restrictions.md): block email addresses of specific domains, or whitelist only specific domains. - [Access restrictions](../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS). -- [Authentication/Authorization](../topics/authentication/index.md#gitlab-administrators): Enforce 2FA, configure external authentication with LDAP, SAML, CAS and additional Omniauth providers. +- [Authentication and Authorization](auth/README.md): Configure external authentication with LDAP, SAML, CAS and additional providers. See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA). - [Incoming email](incoming_email.md): Configure incoming emails to allow users to [reply by email], create [issues by email] and [merge requests by email], and to enable [Service Desk]. - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a basic Postfix mail server with IMAP authentication on Ubuntu for incoming emails. +- [Abuse reports](../user/admin_area/abuse_reports.md): View and resolve abuse reports from your users. [reply by email]: reply_by_email.md [issues by email]: ../user/project/issues/create_new_issue.md#new-issue-via-email @@ -130,6 +132,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/terminal.md b/doc/administration/integration/terminal.md index fa58d0ef15f..40e03093743 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -14,20 +14,33 @@ A detailed overview of the architecture of web terminals and how they work can be found in [this document](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/terminal.md). In brief: -* GitLab relies on the user to provide their own Kubernetes credentials, and to +- GitLab relies on the user to provide their own Kubernetes credentials, and to appropriately label the pods they create when deploying. -* When a user navigates to the terminal page for an environment, they are served +- When a user navigates to the terminal page for an environment, they are served a JavaScript application that opens a WebSocket connection back to GitLab. -* The WebSocket is handled in [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse), +- The WebSocket is handled in [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse), rather than the Rails application server. -* Workhorse queries Rails for connection details and user permissions; Rails - queries Kubernetes for them in the background, using [Sidekiq](../troubleshooting/sidekiq.md) -* Workhorse acts as a proxy server between the user's browser and the Kubernetes +- Workhorse queries Rails for connection details and user permissions. Rails + queries Kubernetes for them in the background using [Sidekiq](../troubleshooting/sidekiq.md). +- Workhorse acts as a proxy server between the user's browser and the Kubernetes API, passing WebSocket frames between the two. -* Workhorse regularly polls Rails, terminating the WebSocket connection if the +- Workhorse regularly polls Rails, terminating the WebSocket connection if the user no longer has permission to access the terminal, or if the connection details have changed. +## Security + +GitLab and [GitLab Runner](https://docs.gitlab.com/runner/) take some +precautions to keep interactive web terminal data encrypted between them, and +everything protected with authorization guards. This is described in more +detail below. + +- Interactive web terminals are completely disabled unless [`[session_server]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) is configured. +- Every time the runner starts, it will generate an `x509` certificate that will be used for a `wss` (Web Socket Secure) connection. +- For every created job, a random URL is generated which is discarded at the end of the job. This URL is used to establish a web socket connection. The URL for the session is in the format `(IP|HOST):PORT/session/$SOME_HASH`, where the `IP/HOST` and `PORT` are the configured [`listen_address`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). +- Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection. +- The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly. + ## Enabling and disabling terminal support As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of @@ -40,10 +53,10 @@ However, if you run a [load balancer](../high_availability/load_balancer.md) in front of GitLab, you may need to make some changes to your configuration. These guides document the necessary steps for a selection of popular reverse proxies: -* [Apache](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) -* [NGINX](https://www.nginx.com/blog/websocket-nginx/) -* [HAProxy](http://blog.haproxy.com/2012/11/07/websockets-load-balancing-with-haproxy/) -* [Varnish](https://www.varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) +- [Apache](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) +- [NGINX](https://www.nginx.com/blog/websocket-nginx/) +- [HAProxy](http://blog.haproxy.com/2012/11/07/websockets-load-balancing-with-haproxy/) +- [Varnish](https://www.varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) Workhorse won't let WebSocket requests through to non-WebSocket endpoints, so it's safe to enable support for these headers globally. If you'd rather had a @@ -60,8 +73,8 @@ the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse proxy in the chain. For most users, this will be the NGINX server bundled with Omnibus GitLab, in which case, you need to: -* Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file -* Ensure the whole block is uncommented, and then comment out or remove the +- Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file +- Ensure the whole block is uncommented, and then comment out or remove the `Connection` and `Upgrade` lines. For your own load balancer, just reverse the configuration changes recommended diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 35f25e55414..160da47c780 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -17,7 +17,7 @@ The default pattern can be located in [gitlab.yml.example] under the "Automatic issue closing" section. > **Tip:** -You are advised to use http://rubular.com to test the issue closing pattern. +You are advised to use <http://rubular.com> to test the issue closing pattern. Because Rubular doesn't understand `%{issue_ref}`, you can replace this by `#\d+` when testing your patterns, which matches only local issue references like `#123`. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 2feac1fd3b0..25ae535d1ec 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 @@ -167,12 +165,6 @@ _The artifacts are stored by default in gitlab-rake gitlab:artifacts:migrate ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. - --- **In installations from source:** @@ -203,12 +195,6 @@ _The artifacts are stored by default in sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production ``` - Currently this has to be executed manually and it will allow you to - migrate the existing artifacts to the object storage, but all new - artifacts will still be stored on the local disk. In the future - you will be given an option to define a default storage artifacts for all - new files. - ## Expiring artifacts If an expiry date is used for the artifacts, they are marked for deletion diff --git a/doc/administration/logs.md b/doc/administration/logs.md index a8cdd20581d..698f4caab3a 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -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`. @@ -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 @@ -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/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 7947b0fedc4..1f431f8bd62 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -33,7 +33,7 @@ Test Connection to ensure the configuration is correct. - **Name**: InfluxDB - **Default**: Checked - **Type**: InfluxDB 0.9.x (Even if you're using InfluxDB 0.10.x) -- **Url**: https://localhost:8086 (Or the remote URL if you've installed InfluxDB +- **Url**: `https://localhost:8086` (Or the remote URL if you've installed InfluxDB on a separate server) - **Access**: proxy - **Database**: gitlab 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..9f3dd7f08ca 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..726882fbb87 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` + +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: + - 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 c6fd7ef7360..c9a2778b3a4 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -45,6 +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 | +| 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 index 44018e966e0..0397452e650 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -44,12 +44,10 @@ 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 | +From experience with multiple customers, this task should take under 10 +seconds to indicate good filesystem performance. + +NOTE: **Note:** +This test is naive and only evaluates write performance. It's possible to +receive good results on this test but still have poor performance due to read +speed and various other factors.
\ No newline at end of file diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md index bad61151bda..0e2079cb093 100644 --- a/doc/administration/operations/unicorn.md +++ b/doc/administration/operations/unicorn.md @@ -60,7 +60,17 @@ Unicorn master then automatically replaces the worker process. This is a robust way to handle memory leaks: Unicorn is designed to handle workers that 'crash' so no user requests will be dropped. The unicorn-worker-killer gem is designed to only terminate a worker process _in -between requests_, so no user requests are affected. +between requests_, so no user requests are affected. You can set the minimum and +maximum memory threshold (in bytes) for the Unicorn worker killer by +setting the following values `/etc/gitlab/gitlab.rb`: + +```ruby +unicorn['worker_memory_limit_min'] = "400 * 1 << 20" +unicorn['worker_memory_limit_max'] = "650 * 1 << 20" +``` + +Otherwise, you can set the `GITLAB_UNICORN_MEMORY_MIN` and `GITLAB_UNICORN_MEMORY_MIN` +[environment variables](../environment_variables.md). This is what a Unicorn worker memory restart looks like in unicorn_stderr.log. You see that worker 4 (PID 125918) is inspecting itself and decides to exit. diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 2952a98626a..10ae8c7dedf 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -242,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 @@ -303,6 +332,42 @@ The maximum size of the unpacked archive per project can be configured in the Admin area under the Application settings in the **Maximum size of pages (MB)**. The default is 100MB. +## Running GitLab Pages in a separate server + +You may want to run GitLab Pages daemon on a separate server in order to decrease the load on your main application server. +Follow the steps below to configure GitLab Pages in a separate server. + +1. Suppose you have the main GitLab application server named `app1`. Prepare +new Linux server (let's call it `app2`), create NFS share there and configure access to +this share from `app1`. Let's use the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` +as the shared folder on `app2` and mount it to `/mnt/pages` on `app1`. + +1. On `app2` install GitLab omnibus and modify `/etc/gitlab/gitlab.rb` this way: + + ```shell + external_url 'http://<ip-address-of-the-server>' + pages_external_url "http://<your-pages-domain>" + postgresql['enable'] = false + redis['enable'] = false + prometheus['enable'] = false + unicorn['enable'] = false + sidekiq['enable'] = false + gitlab_workhorse['enable'] = false + gitaly['enable'] = false + alertmanager['enable'] = false + node_exporter['enable'] = false + ``` +1. Run `sudo gitlab-ctl reconfigure`. +1. On `app1` apply the following changes to `/etc/gitlab/gitlab.rb`: + + ```shell + gitlab_pages['enable'] = false + pages_external_url "http://<your-pages-domain>" + gitlab_rails['pages_path'] = "/mnt/pages" + ``` + +1. Run `sudo gitlab-ctl reconfigure`. + ## Backup Pages are part of the [regular backup][backup] so there is nothing to configure. 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/check.md b/doc/administration/raketasks/check.md index 0ca1d77f1d0..d8f80965c21 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -52,9 +52,9 @@ and these checks will verify them against current files. Currently, integrity checks are supported for the following types of file: -* CI artifacts (Available from version 10.7.0) -* LFS objects (Available from version 10.6.0) -* User uploads (Available from version 10.6.0) +- CI artifacts (Available from version 10.7.0) +- LFS objects (Available from version 10.6.0) +- User uploads (Available from version 10.6.0) **Omnibus Installation** diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 29af07d12dc..0d863594fc7 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -53,6 +53,7 @@ Git: /usr/bin/git Runs the following rake tasks: - `gitlab:gitlab_shell:check` +- `gitlab:gitaly:check` - `gitlab:sidekiq:check` - `gitlab:app:check` @@ -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_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index d1a03219542..d57fc67c83e 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 @@ -333,6 +333,6 @@ If all the tests were successful, Postfix is all set up and ready to receive ema --- -_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._ +_This document was adapted from <https://help.ubuntu.com/community/PostfixBasicSetupHowto>, by contributors to the Ubuntu documentation wiki._ [incoming email]: incoming_email.md diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 715bc0cd08c..8b725e50f58 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -31,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 c03f23a8931..7f25423171f 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -11,6 +11,25 @@ storage load between several mount points. > - The paths are defined in key-value pairs. The key is an arbitrary name you > can pick to name the file path. > - The target directories and any of its subpaths must not be a symlink. +> - No target directory may be a sub-directory of another; no nesting. + +Example: this is OK: + +``` +default: + path: /mnt/git-storage-1 +storage2: + path: /mnt/git-storage-2 +``` + +This is not OK because it nests storage paths: + +``` +default: + path: /mnt/git-storage-1 +storage2: + path: /mnt/git-storage-1/git-storage-2 # <- NOT OK because of nesting +``` ## Configure GitLab diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index bd758c49eba..51e1518d73f 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -7,8 +7,8 @@ Legacy Storage is the storage behavior prior to version 10.0. For historical reasons, GitLab replicated the same mapping structure from the projects URLs: -* Project's repository: `#{namespace}/#{project_name}.git` -* Project's wiki: `#{namespace}/#{project_name}.wiki.git` +- Project's repository: `#{namespace}/#{project_name}.git` +- Project's wiki: `#{namespace}/#{project_name}.wiki.git` This structure made it simple to migrate from existing solutions to GitLab and easy for Administrators to find where the repository is stored. @@ -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 @@ -97,6 +94,23 @@ need to be performed on these nodes as well. Database changes will propagate wit You must make sure the migration event was already processed or otherwise it may migrate the files back to Hashed state again. +#### Hashed object pools + +For deduplication of public forks and their parent repository, objects are pooled +in an object pool. These object pools are a third repository where shared objects +are stored. + +```ruby +# object pool paths +"@pools/#{hash[0..1]}/#{hash[2..3]}/#{hash}.git" +``` + +The object pool feature is behind the `object_pools` feature flag, and can be +enabled for individual projects by executing +`Feature.enable(:object_pools, Project.find(<id>))`. Note that the project has to +be on hashed storage, should not be a fork itself, and hashed storage should be +enabled for all new projects. + ##### Attachments To rollback single Attachment migration, rename `aa/bb/abcdef1234567890...` folder back to `namespace/project`. diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index 2902af8c782..8f7280d5128 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 @@ -158,7 +158,7 @@ are concerned about affecting others during a production system, you can run a separate Rails process to debug the issue: 1. Log in to your GitLab account. -1. Copy the URL that is causing problems (e.g. https://gitlab.com/ABC). +1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`). 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens). 1. Bring up the GitLab Rails console. For omnibus users, run: @@ -211,5 +211,5 @@ The output in `/tmp/unicorn.txt` may help diagnose the root cause. # More information -* [Debugging Stuck Ruby Processes](https://blog.newrelic.com/2013/04/29/debugging-stuck-ruby-processes-what-to-do-before-you-kill-9/) -* [Cheatsheet of using gdb and ruby processes](gdb-stuck-ruby.txt) +- [Debugging Stuck Ruby Processes](https://blog.newrelic.com/2013/04/29/debugging-stuck-ruby-processes-what-to-do-before-you-kill-9/) +- [Cheatsheet of using gdb and ruby processes](gdb-stuck-ruby.txt) diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index aec9a359ada..476ae8e8a76 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -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 @@ -119,30 +120,7 @@ _The uploads are stored by default in ``` 1. Save the file and [reconfigure GitLab][] for the changes to take effect. -1. Migrate any existing local uploads to the object storage: - - > **Notes:** - > These task complies with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - - ```bash - # gitlab-rake gitlab:uploads:migrate[uploader_class, model_class, mount_point] - - # Avatars - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - gitlab-rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - gitlab-rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - gitlab-rake "gitlab:uploads:migrate[FileUploader, Project]" - gitlab-rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - gitlab-rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - ``` +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). --- @@ -167,34 +145,11 @@ _The uploads are stored by default in ``` 1. Save the file and [restart GitLab][] for the changes to take effect. -1. Migrate any existing local uploads to the object storage: - - > **Notes:** - > - These task comply with the `BATCH` environment variable to process uploads in batch (200 by default). All of the processing will be done in a background worker and requires **no downtime**. - > - To migrate in production use `RAILS_ENV=production` environment variable. - - ```bash - # sudo -u git -H bundle exec rake gitlab:uploads:migrate - - # Avatars - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Project, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, Group, :avatar]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AvatarUploader, User, :avatar]" - - # Attachments - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Note, :attachment]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :logo]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[AttachmentUploader, Appearance, :header_logo]" - - # Markdown - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, Project]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[PersonalFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[NamespaceFileUploader, Snippet]" - sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeRequest]" - - ``` +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). [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 a351db99bbd..692f63a400c 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -5,76 +5,91 @@ under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. -## Resources +## API Resources -Documentation for various API resources can be found separately in the -following locations: +The following API resources are available: -- [Award Emoji](award_emoji.md) +- [Applications](applications.md) +- [Avatar](avatar.md) +- [Award emoji](award_emoji.md) - [Branches](branches.md) -- [Broadcast Messages](broadcast_messages.md) -- [Project-level Variables](project_level_variables.md) -- [Group-level Variables](group_level_variables.md) -- [Code Snippets](snippets.md) +- [Broadcast messages](broadcast_messages.md) +- [Code snippets](snippets.md) - [Commits](commits.md) -- [Custom Attributes](custom_attributes.md) +- [Container Registry](container_registry.md) +- [Custom attributes](custom_attributes.md) +- [Deploy keys](deploy_keys.md), and [deploy keys for multiple projects](deploy_key_multiple_projects.md) - [Deployments](deployments.md) -- [Deploy Keys](deploy_keys.md) -- [Dockerfile templates](templates/dockerfiles.md) +- [Discussions](discussions.md) (threaded comments) - [Environments](environments.md) - [Events](events.md) - [Feature flags](features.md) -- [Gitignore templates](templates/gitignores.md) -- [GitLab CI Config templates](templates/gitlab_ci_ymls.md) -- [Groups](groups.md) -- [Group Access Requests](access_requests.md) -- [Group Badges](group_badges.md) -- [Group Members](members.md) +- Group-related resources, including: + - [Groups](groups.md) + - [Group access requests](access_requests.md) + - [Group badges](group_badges.md) + - [Group issue boards](group_boards.md) + - [Group-level variables](group_level_variables.md) + - [Group members](members.md) + - [Group milestones](group_milestones.md) - [Issues](issues.md) -- [Issue Boards](boards.md) -- [Group Issue Boards](group_boards.md) +- [Issue boards](boards.md) - [Jobs](jobs.md) - [Keys](keys.md) - [Labels](labels.md) - [Markdown](markdown.md) -- [Merge Requests](merge_requests.md) -- [Project milestones](milestones.md) -- [Group milestones](group_milestones.md) +- [Merge requests](merge_requests.md) - [Namespaces](namespaces.md) - [Notes](notes.md) (comments) -- [Discussions](discussions.md) (threaded comments) -- [Resource Label Events](resource_label_events.md) - [Notification settings](notification_settings.md) -- [Open source license templates](templates/licenses.md) -- [Pages Domains](pages_domains.md) +- [Pages domains](pages_domains.md) - [Pipelines](pipelines.md) -- [Pipeline Triggers](pipeline_triggers.md) -- [Pipeline Schedules](pipeline_schedules.md) -- [Projects](projects.md) including setting Webhooks -- [Project Access Requests](access_requests.md) -- [Project Badges](project_badges.md) -- [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) +- [Pipeline schedules](pipeline_schedules.md) +- [Pipeline triggers](pipeline_triggers.md) and [triggering pipelines](../ci/triggers/README.md) +- Project-related resources, including: + - [Projects](projects.md) including setting Webhooks + - [Project access requests](access_requests.md) + - [Project badges](project_badges.md) + - [Project clusters](project_clusters.md) + - [Project-level variables](project_level_variables.md) + - [Project import/export](project_import_export.md) + - [Project members](members.md) + - [Project milestones](milestones.md) + - [Project snippets](project_snippets.md) + - [Project templates](project_templates.md) (see also [Templates API Resources](#templates-api-resources)) +- [Protected branches](protected_branches.md) +- [Protected tags](protected_tags.md) - [Repositories](repositories.md) -- [Repository Files](repository_files.md) +- [Repository files](repository_files.md) +- [Repository submodules](repository_submodules.md) +- [Resource label events](resource_label_events.md) - [Runners](runners.md) - [Search](search.md) - [Services](services.md) - [Settings](settings.md) - [Sidekiq metrics](sidekiq_metrics.md) -- [System Hooks](system_hooks.md) +- [System hooks](system_hooks.md) - [Tags](tags.md) +- [Releases](releases/index.md) +- Release Assets + - [Links](releases/links.md) - [Todos](todos.md) - [Users](users.md) -- [Validate CI configuration](lint.md) -- [V3 to V4](v3_to_v4.md) +- [Validate CI configuration](lint.md) (linting) - [Version](version.md) - [Wikis](wikis.md) +See also [V3 to V4](v3_to_v4.md). + +### Templates API Resources + +Endpoints are available for: + +- [Dockerfile templates](templates/dockerfiles.md). +- [gitignore templates](templates/gitignores.md). +- [GitLab CI YAML templates](templates/gitlab_ci_ymls.md). +- [Open source license templates](templates/licenses.md). + ## Road to GraphQL Going forward, we will start on moving to @@ -96,14 +111,14 @@ specification. ## Compatibility Guidelines The HTTP API is versioned using a single number, the current one being 4. This -number symbolises the same as the major version number as described by +number symbolizes the same as the major version number as described by [SemVer](https://semver.org/). This mean that backward incompatible changes will require this version number to change. However, the minor version is 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 @@ -184,13 +199,13 @@ You can use a [personal access token][pat] to authenticate with the API by passi Example of using the personal access token in a parameter: ```shell -curl https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK +curl https://gitlab.example.com/api/v4/projects?private_token=<your_access_token> ``` Example of using the personal access token in a header: ```shell -curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects +curl --header "Private-Token: <your_access_token>" https://gitlab.example.com/api/v4/projects ``` Read more about [personal access tokens][pat]. @@ -223,6 +238,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:** @@ -235,6 +286,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`: @@ -270,22 +324,22 @@ Example of a valid API call and a request using cURL with sudo request, providing a username: ``` -GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username +GET /projects?private_token=<your_access_token>&sudo=username ``` ```shell -curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" +curl --header "Private-Token: <your_access_token>" --header "Sudo: username" "https://gitlab.example.com/api/v4/projects" ``` Example of a valid API call and a request using cURL with sudo request, providing an ID: ``` -GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 +GET /projects?private_token=<your_access_token>&sudo=23 ``` ```shell -curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" +curl --header "Private-Token: <your_access_token>" --header "Sudo: 23" "https://gitlab.example.com/api/v4/projects" ``` ## Status codes @@ -334,7 +388,7 @@ resources you can pass the following parameters: In the example below, we list 50 [namespaces](namespaces.md) per page. ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/namespaces?per_page=50 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50 ``` ### Pagination Link header @@ -348,7 +402,7 @@ and we request the second page (`page=2`) of [comments](notes.md) of the issue with ID `8` which belongs to the project with ID `8`: ```bash -curl --head --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2 +curl --head --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/8/issues/8/notes?per_page=3&page=2 ``` The response will then be: @@ -385,6 +439,14 @@ Additional pagination headers are also sent back. | `X-Next-Page` | The index of the next page | | `X-Prev-Page` | The index of the previous page | +CAUTION: **Caution:** +For performance reasons since +[GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23931) +and **behind the `api_kaminari_count_with_limit` +[feature flag](../development/feature_flags.md)**, if the number of resources is +more than 10,000, the `X-Total` and `X-Total-Pages` headers as well as the +`rel="last"` `Link` are not present in the response headers. + ## Namespaced path encoding If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_NAME` is @@ -416,7 +478,7 @@ We can call the API with `array` and `hash` types parameters as shown below: `import_sources` is a parameter of type `array`: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \ +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ -d "import_sources[]=github" \ -d "import_sources[]=bitbucket" \ "https://gitlab.example.com/api/v4/some_endpoint @@ -427,7 +489,7 @@ curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \ `override_params` is a parameter of type `hash`: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" \ +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ --form "namespace=email" \ --form "path=impapi" \ --form "file=@/path/to/somefile.txt" @@ -543,7 +605,7 @@ Content-Type: application/json ## Encoding `+` in ISO 8601 dates If you need to include a `+` in a query parameter, you may need to use `%2B` instead due -a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) that +to a [W3 recommendation](http://www.w3.org/Addressing/URL/4_URI_Recommentations.html) that causes a `+` to be interpreted as a space. For example, in an ISO 8601 date, you may want to pass a time in Mountain Standard Time, such as: diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 4b2014ca843..973c3968d90 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -28,8 +28,8 @@ GET /projects/:id/access_requests | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/access_requests +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/access_requests +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/access_requests ``` Example response: @@ -69,8 +69,8 @@ POST /projects/:id/access_requests | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/access_requests +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/access_requests +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/access_requests ``` Example response: @@ -102,8 +102,8 @@ PUT /projects/:id/access_requests/:user_id/approve | `access_level` | integer | no | A valid access level (defaults: `30`, developer access level) | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests/:user_id/approve?access_level=20 -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/access_requests/:user_id/approve?access_level=20 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/access_requests/:user_id/approve?access_level=20 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/access_requests/:user_id/approve?access_level=20 ``` Example response: @@ -134,6 +134,6 @@ DELETE /projects/:id/access_requests/:user_id | `user_id` | integer | yes | The user ID of the access requester | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests/:user_id -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/access_requests/:user_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/access_requests/:user_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/access_requests/:user_id ``` diff --git a/doc/api/applications.md b/doc/api/applications.md index 6d244594b71..82955f0c1db 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,37 +1,97 @@ # Applications API -> [Introduced][ce-8160] in GitLab 10.5 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8160) in GitLab 10.5. -[ce-8160]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8160 +Applications API operates on OAuth applications for: -## Create a application +- [Using GitLab as an authentication provider](../integration/oauth_provider.md). +- [Allowing access to GitLab resources on a user's behalf](oauth2.md). -Create a application by posting a JSON payload. +NOTE: **Note:** +Only admin users can use the Applications API. -User must be admin to do that. +## Create an application + +Create an application by posting a JSON payload. Returns `200` if the request succeeds. -``` +```text POST /applications ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `name` | string | yes | The name of the application | -| `redirect_uri` | string | yes | The redirect URI of the application | -| `scopes` | string | yes | The scopes of the application | +Parameters: + +| Attribute | Type | Required | Description | +|:---------------|:-------|:---------|:---------------------------------| +| `name` | string | yes | Name of the application. | +| `redirect_uri` | string | yes | Redirect URI of the application. | +| `scopes` | string | yes | Scopes of the application. | + +Example request: -```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" https://gitlab.example.com/api/v4/applications +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" https://gitlab.example.com/api/v4/applications ``` 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. + +```text +GET /applications +``` + +Example request: + +```sh +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/applications +``` + +Example response: + +```json +[ + { + "id":1, + "application_id": "5832fc6e14300a0d962240a8144466eef4ee93ef0d218477e55f11cf12fc3737", + "application_name": "MyApplication", + "callback_url": "http://redirect.uri" + } +] +``` + +NOTE: **Note:** +The `secret` value will not be exposed by this API. + +## Delete an application + +Delete a specific application. + +Returns `204` if the request succeeds. + +```text +DELETE /applications/:id +``` + +Parameters: + +- `id` (required) - The id of the application (not the application_id) + +Example request: + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/applications/:id +``` diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 7faed893066..e55fffba4b2 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,33 +1,41 @@ # Avatar API -> [Introduced][ce-19121] in GitLab 11.0 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19121) in GitLab 11.0. ## Get a single avatar URL -Get a single avatar URL for a given email addres. 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. +Get a single [avatar](../user/profile/index.md#profile-settings) URL for a user with the given email address. -``` +If: + +- No user with the given public email address is found, results from external avatar services are + returned. +- Public visibility is restricted, response will be `403 Forbidden` when unauthenticated. + +NOTE: **Note:** +This endpoint can be accessed without authentication. + +```text GET /avatar?email=admin@example.com ``` -| Attribute | Type | Required | Description | -| --------- | ------- | -------- | --------------------- | -| `email` | string | yes | Public email address of the user | -| `size` | integer | no | Single pixel dimension (since images are squares). Only used for avatar lookups at `Gravatar` or at the configured `Libravatar` server | +Parameters: -```bash -curl https://gitlab.example.com/api/v4/avatar?email=admin@example.com +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `email` | string | yes | Public email address of the user. | +| `size` | integer | no | Single pixel dimension (since images are squares). Only used for avatar lookups at `Gravatar` or at the configured `Libravatar` server. | + +Example request: + +```sh +curl https://gitlab.example.com/api/v4/avatar?email=admin@example.com&size=32 ``` Example response: ```json { - "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon" + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=64&d=identicon" } ``` - -[ce-19121]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19121 diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 3f9542d6653..92936a277ac 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -1,19 +1,26 @@ # Award Emoji API -> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12. +An [awarded emoji](../user/award_emojis.md) tells a thousand words. -An awarded emoji tells a thousand words, and can be awarded on issues, merge -requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called -`awardables`. +Emoji can be awarded on the following (known as "awardables"): + +- [Issues](../user/project/issues/index.md) ([API](issues.md)). +- [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)). +- [Snippets](../user/snippets.md) ([API](snippets.md)). + +Emoji can also [be awarded](../user/award_emojis.html#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md). ## Issues, merge requests, and snippets +See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments. + ### List an awardable's award emoji -Gets a list of all award emoji +Get a list of all award emoji for a specified awardable. -``` +```text GET /projects/:id/issues/:issue_iid/award_emoji GET /projects/:id/merge_requests/:merge_request_iid/award_emoji GET /projects/:id/snippets/:snippet_id/award_emoji @@ -21,16 +28,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji Parameters: -| 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 | -| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | +| Attribute | Type | Required | Description | +|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji +Example request: + +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji ``` -Example Response: +Example response: ```json [ @@ -71,9 +80,9 @@ Example Response: ### Get single award emoji -Gets a single award emoji from an issue, snippet, or merge request. +Get a single award emoji from an issue, snippet, or merge request. -``` +```text GET /projects/:id/issues/:issue_iid/award_emoji/:award_id GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id @@ -81,17 +90,19 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id Parameters: -| 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 | -| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | -| `award_id` | integer | yes | The ID of the award emoji | +| Attribute | Type | Required | Description | +|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `award_id` | integer | yes | ID of the award emoji. | + +Example request: -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1 +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1 ``` -Example Response: +Example response: ```json { @@ -114,9 +125,9 @@ Example Response: ### Award a new emoji -This end point creates an award emoji on the specified resource +Create an award emoji on the specified awardable. -``` +```text POST /projects/:id/issues/:issue_iid/award_emoji POST /projects/:id/merge_requests/:merge_request_iid/award_emoji POST /projects/:id/snippets/:snippet_id/award_emoji @@ -124,14 +135,14 @@ POST /projects/:id/snippets/:snippet_id/award_emoji Parameters: -| 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 | -| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | -| `name` | string | yes | The name of the emoji, without colons | +| Attribute | Type | Required | Description | +|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `name` | string | yes | Name of the emoji without colons. | -```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish ``` Example Response: @@ -157,10 +168,12 @@ Example Response: ### Delete an award emoji -Sometimes its just not meant to be, and you'll have to remove your award. Only available to -admins or the author of the award. +Sometimes it's just not meant to be and you'll have to remove the award. -``` +NOTE: **Note:** +Only available to administrators or the author of the award. + +```text DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id @@ -168,43 +181,47 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id Parameters: -| 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 an issue | -| `award_id` | integer | yes | The ID of an award_emoji | +| Attribute | Type | Required | Description | +|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `award_id` | integer | yes | ID of an award emoji. | -```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344 +```sh +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344 ``` -## Award Emoji on Notes +## Award Emoji on Comments -The endpoints documented above are available for Notes as well. Notes -are a sub-resource of Issues, Merge Requests, or Snippets. The examples below -describe working with Award Emoji on notes for an Issue, but can be -easily adapted for notes on a Merge Request. +Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets. -### List a note's award emoji +NOTE: **Note:** +The examples below describe working with award emoji on comments for an issue, but can be +easily adapted for comments on a merge request. -``` +### List a comment's award emoji + +Get all award emoji for a comment (note). + +```text GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji ``` Parameters: -| 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 an issue | -| `note_id` | integer | yes | The ID of a note | +| Attribute | Type | Required | Description | +|:------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issue_iid` | integer | yes | Internal ID of an issue. | +| `note_id` | integer | yes | ID of a comment (note). | +Example request: -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji ``` -Example Response: +Example response: ```json [ @@ -227,26 +244,30 @@ Example Response: ] ``` -### Get single note's award emoji +### Get an award emoji for a comment -``` +Get a single award emoji for a comment (note). + +```text GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id ``` Parameters: -| 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 an issue | -| `note_id` | integer | yes | The ID of a note | -| `award_id` | integer | yes | The ID of the award emoji | +| Attribute | Type | Required | Description | +|:------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issue_iid` | integer | yes | Internal ID of an issue. | +| `note_id` | integer | yes | ID of a comment (note). | +| `award_id` | integer | yes | ID of the award emoji. | + +Example request: -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2 +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2 ``` -Example Response: +Example response: ```json { @@ -267,26 +288,30 @@ Example Response: } ``` -### Award a new emoji on a note +### Award a new emoji on a comment -``` +Create an award emoji on the specified comment (note). + +```text POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji ``` Parameters: -| 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 an issue | -| `note_id` | integer | yes | The ID of a note | -| `name` | string | yes | The name of the emoji, without colons | +| Attribute | Type | Required | Description | +|:------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issue_iid` | integer | yes | Internal ID of an issue. | +| `note_id` | integer | yes | ID of a comment (note). | +| `name` | string | yes | Name of the emoji without colons. | -```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket +Example request: + +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket ``` -Example Response: +Example response: ```json { @@ -307,26 +332,28 @@ Example Response: } ``` -### Delete an award emoji +### Delete an award emoji from a comment -Sometimes its just not meant to be, and you'll have to remove your award. Only available to -admins or the author of the award. +Sometimes it's just not meant to be and you'll have to remove the award. -``` +NOTE: **Note:** +Only available to administrators or the author of the award. + +```text DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id ``` Parameters: -| 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 an issue | -| `note_id` | integer | yes | The ID of a note | -| `award_id` | integer | yes | The ID of an award_emoji | +| Attribute | Type | Required | Description | +|:------------|:---------------|:---------|:-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `issue_iid` | integer | yes | Internal ID of an issue. | +| `note_id` | integer | yes | ID of a comment (note). | +| `award_id` | integer | yes | ID of an award_emoji. | -```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345 -``` +Example request: -[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575 +```sh +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345 +``` diff --git a/doc/api/boards.md b/doc/api/boards.md index 5f006f4f012..2a2622736c3 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -18,7 +18,7 @@ GET /projects/:id/boards | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards ``` Example response: @@ -87,7 +87,7 @@ GET /projects/:id/boards/:board_id | `board_id` | integer | yes | The ID of a board | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1 ``` Example response: @@ -156,7 +156,7 @@ GET /projects/:id/boards/:board_id/lists | `board_id` | integer | yes | The ID of a board | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1/lists +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1/lists ``` Example response: @@ -208,7 +208,7 @@ GET /projects/:id/boards/:board_id/lists/:list_id | `list_id`| integer | yes | The ID of a board's list | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1 ``` Example response: @@ -240,7 +240,7 @@ POST /projects/:id/boards/:board_id/lists | `label_id` | integer | yes | The ID of a label | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1/lists?label_id=5 +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1/lists?label_id=5 ``` Example response: @@ -273,7 +273,7 @@ PUT /projects/:id/boards/:board_id/lists/:list_id | `position` | integer | yes | The position of the list | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1?position=2 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1?position=2 ``` Example response: @@ -305,5 +305,5 @@ DELETE /projects/:id/boards/:board_id/lists/:list_id | `list_id` | integer | yes | The ID of a board's list | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/boards/1/lists/1 ``` diff --git a/doc/api/branches.md b/doc/api/branches.md index 4abf0639eb0..8d5f333ba77 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -1,22 +1,32 @@ # Branches API +This API operates on [repository branches](../user/project/repository/branches/index.md). + +TIP: **Tip:** +See also [Protected branches API](protected_branches.md). + ## List repository branches Get a list of repository branches from a project, sorted by name alphabetically. -This endpoint can be accessed without authentication if the repository is -publicly accessible. -``` +NOTE: **Note:** +This endpoint can be accessed without authentication if the repository is publicly accessible. + +```text GET /projects/:id/repository/branches ``` -| 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 | -| `search` | string | no | Return list of branches matching the search criteria. | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `search` | string | no | Return list of branches matching the search criteria. | + +Example request: -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches ``` Example response: @@ -53,20 +63,26 @@ Example response: ## Get single repository branch -Get a single project repository branch. This endpoint can be accessed without -authentication if the repository is publicly accessible. +Get a single project repository branch. -``` +NOTE: **Note:** +This endpoint can be accessed without authentication if the repository is publicly accessible. + +```text GET /projects/:id/repository/branches/:branch ``` -| 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 | -| `branch` | string | yes | The name of the branch | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `branch` | string | yes | Name of the branch. | -```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master +Example request: + +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/master ``` Example response: @@ -100,120 +116,34 @@ Example response: ## Protect repository branch ->**Note:** This API endpoint is deprecated in favor of `POST /projects/:id/protected_branches`. - -Protects a single project repository branch. This is an idempotent function, -protecting an already protected repository branch still returns a `200 OK` -status code. - -``` -PUT /projects/:id/repository/branches/:branch/protect -``` - -```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/protect?developers_can_push=true&developers_can_merge=true -``` - -| 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 | -| `branch` | string | yes | The name of the branch | -| `developers_can_push` | boolean | no | Flag if developers can push to the branch | -| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch | - -Example response: - -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "short_id": "7b5c3cc", - "title": "add projects API", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "merged": false, - "protected": true, - "default": true, - "developers_can_push": true, - "developers_can_merge": true, - "can_push": true -} -``` +See [`POST /projects/:id/protected_branches`](protected_branches.md#protect-repository-branches) for +information on protecting repository branches. ## Unprotect repository branch ->**Note:** This API endpoint is deprecated in favor of `DELETE /projects/:id/protected_branches/:name` +See [`DELETE /projects/:id/protected_branches/:name`](protected_branches.md#unprotect-repository-branches) +for information on unprotecting repository branches. -Unprotects a single project repository branch. This is an idempotent function, -unprotecting an already unprotected repository branch still returns a `200 OK` -status code. - -``` -PUT /projects/:id/repository/branches/:branch/unprotect -``` - -```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches/master/unprotect -``` - -| 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 | -| `branch` | string | yes | The name of the branch | +## Create repository branch -Example response: +Create a new branch in the repository. -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "short_id": "7b5c3cc", - "title": "add projects API", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "merged": false, - "protected": false, - "default": true, - "developers_can_push": false, - "developers_can_merge": false, - "can_push": true -} +```text +POST /projects/:id/repository/branches ``` -## Create repository branch +Parameters: -``` -POST /projects/:id/repository/branches -``` +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:-------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `branch` | string | yes | Name of the branch. | +| `ref` | string | yes | Branch name or commit SHA to create branch from. | -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `branch` | string | yes | The name of the branch | -| `ref` | string | yes | The branch name or commit SHA to create branch from | +Example request: -```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=master ``` Example response: @@ -247,36 +177,47 @@ Example response: ## Delete repository branch -``` +Delete a branch from the repository. + +NOTE: **Note:** +In the case of an error, an explanation message is provided. + +```text DELETE /projects/:id/repository/branches/:branch ``` -| 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 | -| `branch` | string | yes | The name of the branch | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `branch` | string | yes | Name of the branch. | -In case of an error, an explaining message is provided. +Example request: -```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch" +```sh +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/branches/newbranch ``` ## Delete merged branches Will delete all branches that are merged into the project's default branch. -Protected branches will not be deleted as part of this operation. +NOTE: **Note:** +[Protected branches](../user/project/protected_branches.md) will not be deleted as part of this operation. -``` +```text DELETE /projects/:id/repository/merged_branches ``` -| 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 | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +Example request: -```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/merged_branches" +```sh +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/merged_branches ``` diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index a8a248a17f4..fe370682308 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -13,7 +13,7 @@ GET /broadcast_messages ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/broadcast_messages +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages ``` Example response: @@ -43,7 +43,7 @@ GET /broadcast_messages/:id | `id` | integer | yes | Broadcast message ID | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/broadcast_messages/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` Example response: @@ -75,7 +75,7 @@ POST /broadcast_messages | `font` | string | no | Foreground color hex code | ```bash -curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/broadcast_messages +curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages ``` Example response: @@ -108,7 +108,7 @@ PUT /broadcast_messages/:id | `font` | string | no | Foreground color hex code | ```bash -curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/broadcast_messages/1 +curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` Example response: @@ -136,5 +136,5 @@ DELETE /broadcast_messages/:id | `id` | integer | yes | Broadcast message ID | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/broadcast_messages/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` diff --git a/doc/api/commits.md b/doc/api/commits.md index 9b7ca4b6e70..14742f034e0 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -20,7 +20,7 @@ GET /projects/:id/repository/commits ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits" ``` Example response: @@ -87,7 +87,7 @@ POST /projects/:id/repository/commits | `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`. Only considered for `move` action. | -| `content` | string | no | File content, required for all except `delete` and `chmod`. Optional for `move` | +| `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. | @@ -127,7 +127,7 @@ PAYLOAD=$(cat << 'JSON' } JSON ) -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data "$PAYLOAD" https://gitlab.example.com/api/v4/projects/1/repository/commits +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data "$PAYLOAD" https://gitlab.example.com/api/v4/projects/1/repository/commits ``` Example response: @@ -173,7 +173,7 @@ Parameters: | `stats` | boolean | no | Include commit stats. Default is true | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master ``` Example response: @@ -229,7 +229,7 @@ Parameters: | `type` | string | no | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`. | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all" ``` Example response: @@ -263,7 +263,7 @@ Parameters: | `branch` | string | yes | The name of the branch | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick" ``` Example response: @@ -288,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: <your_access_token>" --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. @@ -304,7 +345,7 @@ Parameters: | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/diff" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/diff" ``` Example response: @@ -340,7 +381,7 @@ Parameters: | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/comments" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/comments" ``` Example response: @@ -393,7 +434,7 @@ POST /projects/:id/repository/commits/:sha/comments | `line_type` | string | no | The line type. Takes `new` or `old` as arguments | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments ``` Example response: @@ -439,7 +480,7 @@ GET /projects/:id/repository/commits/:sha/statuses | `all` | boolean | no | Return all statuses, not only the latest ones ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses ``` Example response: @@ -515,7 +556,7 @@ POST /projects/:id/statuses/:sha | `coverage` | float | no | The total code coverage ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success" ``` Example response: @@ -562,7 +603,7 @@ GET /projects/:id/repository/commits/:sha/merge_requests ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" ``` Example response: @@ -619,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/container_registry.md b/doc/api/container_registry.md new file mode 100644 index 00000000000..b70854103e8 --- /dev/null +++ b/doc/api/container_registry.md @@ -0,0 +1,200 @@ +# Container Registry API + +This is the API docs of the [GitLab Container Registry](../user/project/container_registry.md). + +## List registry repositories + +Get a list of registry repositories in a project. + +``` +GET /projects/:id/registry/repositories +``` + +| 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. | + + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories" +``` + +Example response: + +```json +[ + { + "id": 1, + "name": "", + "path": "group/project", + "location": "gitlab.example.com:5000/group/project", + "created_at": "2019-01-10T13:38:57.391Z" + }, + { + "id": 2, + "name": "releases", + "path": "group/project/releases", + "location": "gitlab.example.com:5000/group/project/releases", + "created_at": "2019-01-10T13:39:08.229Z" + } +] +``` + +## Delete registry repository + +Get a list of repository commits in a project. + +This operation is executed asynchronously and might take some time to get executed. + +``` +DELETE /projects/:id/registry/repositories/:repository_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. | +| `repository_id` | integer | yes | The ID of registry repository. | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2" +``` + +## List repository tags + +Get a list of tags for given registry repository. + +``` +GET /projects/:id/registry/repositories/:repository_id/tags +``` + +| 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. | +| `repository_id` | integer | yes | The ID of registry repository. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" +``` + +Example response: + +```json +[ + { + "name": "A", + "path": "group/project:A", + "location": "gitlab.example.com:5000/group/project:A" + }, + { + "name": "latest", + "path": "group/project:latest", + "location": "gitlab.example.com:5000/group/project:latest" + } +] +``` + +## Get details of a repository tag + +Get details of a registry repository tag. + +``` +GET /projects/:id/registry/repositories/:repository_id/tags/:tag_name +``` + +| 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. | +| `repository_id` | integer | yes | The ID of registry repository. | +| `tag_name` | string | yes | The name of tag. | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +``` + +Example response: + +```json +{ + "name": "v10.0.0", + "path": "group/project:latest", + "location": "gitlab.example.com:5000/group/project:latest", + "revision": "e9ed9d87c881d8c2fd3a31b41904d01ba0b836e7fd15240d774d811a1c248181", + "short_revision": "e9ed9d87c", + "digest": "sha256:c3490dcf10ffb6530c1303522a1405dfaf7daecd8f38d3e6a1ba19ea1f8a1751", + "created_at": "2019-01-06T16:49:51.272+00:00", + "total_size": 350224384 +} +``` + +## Delete a repository tag + +Delete a registry repository tag. + +``` +DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name +``` + +| 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. | +| `repository_id` | integer | yes | The ID of registry repository. | +| `tag_name` | string | yes | The name of tag. | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" +``` + +## Delete repository tags in bulk + +Delete repository tags in bulk based on given criteria. + +``` +DELETE /projects/:id/registry/repositories/:repository_id/tags +``` + +| 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. | +| `repository_id` | integer | yes | The ID of registry repository. | +| `name_regex` | string | yes | The regex of the name to delete. To delete all tags specify `.*`. | +| `keep_n` | integer | no | The amount of latest tags of given name to keep. | +| `older_than` | string | no | Tags to delete that are older than the given time, written in human readable form `1h`, `1d`, `1month`. | + +This API call performs the following operations: + +1. It orders all tags by creation date. The creation date is the time of the + manifest creation, not the time of tag push. +1. It removes only the tags matching the given `name_regex`. +1. It never removes the tag named `latest`. +1. It keeps N latest matching tags (if `keep_n` is specified). +1. It only removes tags that are older than X amount of time (if `older_than` is specified). +1. It schedules the asynchronous job to be executed in the background. + +These operations are executed asynchronously and it might +take time to get executed. You can run this at most +once an hour for a given container repository. + +NOTE: **Note:** +Due to a [Docker Distribution deficiency](https://gitlab.com/gitlab-org/gitlab-ce/issues/21405), +it doesn't remove tags whose manifest is shared by multiple tags. + +Examples: + +1. Remove tag names that are matching the regex (Git SHA), keep always at least 5, + and remove ones that are older than 2 days: + + ```bash + curl --request DELETE --data 'name_regex=[0-9a-z]{40}' --data 'keep_n=5' --data 'older_than=2d' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +2. Remove all tags, but keep always the latest 5: + + ```bash + curl --request DELETE --data 'name_regex=.*' --data 'keep_n=5' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` + +3. Remove all tags that are older than 1 month: + + ```bash + curl --request DELETE --data 'name_regex=.*' --data 'older_than=1month' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags" + ``` diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 91d1b0e1520..d270b804ad5 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -20,7 +20,7 @@ GET /projects/:id/custom_attributes | `id` | integer | yes | The ID of a resource | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/custom_attributes +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/custom_attributes ``` Example response: @@ -54,7 +54,7 @@ GET /projects/:id/custom_attributes/:key | `key` | string | yes | The key of the custom attribute | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/custom_attributes/location +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/custom_attributes/location ``` Example response: @@ -84,7 +84,7 @@ PUT /projects/:id/custom_attributes/:key | `value` | string | yes | The value of the custom attribute | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "value=Greenland" https://gitlab.example.com/api/v4/users/42/custom_attributes/location +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "value=Greenland" https://gitlab.example.com/api/v4/users/42/custom_attributes/location ``` Example response: @@ -112,5 +112,5 @@ DELETE /projects/:id/custom_attributes/:key | `key` | string | yes | The key of the custom attribute | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/custom_attributes/location +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/custom_attributes/location ``` diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md index 127f9a196de..0c9e3e66cae 100644 --- a/doc/api/deploy_key_multiple_projects.md +++ b/doc/api/deploy_key_multiple_projects.md @@ -7,23 +7,23 @@ First, find the ID of the projects you're interested in, by either listing all projects: ``` -curl --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v4/projects +curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/projects ``` Or finding the ID of a group and then listing all projects in that group: ``` -curl --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v4/groups +curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups # For group 1234: -curl --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v4/groups/1234 +curl --header 'PRIVATE-TOKEN: <your_access_token>' https://gitlab.example.com/api/v4/groups/1234 ``` With those IDs, add the same deploy key to all: ``` for project_id in 321 456 987; do - curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" \ + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys done ``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 698fa22a438..1d7523fcc3d 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -9,7 +9,7 @@ GET /deploy_keys ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/deploy_keys" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_keys" ``` Example response: @@ -44,7 +44,7 @@ GET /projects/:id/deploy_keys | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" ``` Example response: @@ -84,7 +84,7 @@ Parameters: | `key_id` | integer | yes | The ID of the deploy key | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" ``` Example response: @@ -118,7 +118,7 @@ POST /projects/:id/deploy_keys | `can_push` | boolean | no | Can deploy key push to the project's repository | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/" ``` Example response: @@ -148,7 +148,7 @@ PUT /projects/:id/deploy_keys/:key_id | `can_push` | boolean | no | Can deploy key push to the project's repository | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11" ``` Example response: @@ -177,7 +177,7 @@ DELETE /projects/:id/deploy_keys/:key_id | `key_id` | integer | yes | The ID of the deploy key | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/13" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/13" ``` ## Enable a deploy key @@ -185,7 +185,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gi Enables a deploy key for a project so this can be used. Returns the enabled key, with a status code 201 when successful. ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/deploy_keys/13/enable +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/deploy_keys/13/enable ``` | Attribute | Type | Required | Description | diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 1963b0a21de..0a67f134d54 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -15,7 +15,7 @@ GET /projects/:id/deployments | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/deployments" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" ``` Example of response @@ -155,7 +155,7 @@ GET /projects/:id/deployments/:deployment_id | `deployment_id` | integer | yes | The ID of the deployment | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/deployments/1" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1" ``` Example of response diff --git a/doc/api/discussions.md b/doc/api/discussions.md index a1e1ff1419d..79090ea5254 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -97,7 +97,7 @@ GET /projects/:id/issues/:issue_iid/discussions ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions ``` ### Get single issue discussion @@ -117,13 +117,13 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 ``` ### 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 @@ -139,7 +139,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment ``` ### Add note to existing issue discussion @@ -162,7 +162,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment ``` ### Modify existing issue discussion note @@ -184,7 +184,7 @@ Parameters: | `body` | string | yes | The content of a discussion | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment ``` ### Delete an issue discussion note @@ -205,7 +205,7 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636 ``` ## Snippets @@ -303,7 +303,7 @@ GET /projects/:id/snippets/:snippet_id/discussions ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions ``` ### Get single snippet discussion @@ -323,13 +323,13 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 ``` ### 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 @@ -345,7 +345,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment ``` ### Add note to existing snippet discussion @@ -368,7 +368,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment ``` ### Modify existing snippet discussion note @@ -390,7 +390,7 @@ Parameters: | `body` | string | yes | The content of a discussion | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment ``` ### Delete an snippet discussion note @@ -411,7 +411,7 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636 ``` ## Merge requests @@ -562,7 +562,7 @@ Diff comments contain also position: ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions ``` ### Get single merge request discussion @@ -582,13 +582,13 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 ``` ### 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 @@ -617,7 +617,7 @@ Parameters: | `position[y]` | integer | no | Y coordinate (for 'image' diff notes) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment ``` ### Resolve a merge request discussion @@ -638,7 +638,7 @@ Parameters: | `resolved` | boolean | yes | Resolve/unresolve the discussion | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true ``` @@ -662,7 +662,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment ``` ### Modify an existing merge request discussion note @@ -685,13 +685,13 @@ Parameters: | `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment ``` Resolving a note: ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true ``` ### Delete a merge request discussion note @@ -712,7 +712,7 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636 ``` ## Commits @@ -855,7 +855,7 @@ Diff comments contain also position: ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions ``` ### Get single commit discussion @@ -875,13 +875,13 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 ``` ### 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 @@ -910,7 +910,7 @@ Parameters: | `position[y]` | integer | no | Y coordinate (for 'image' diff notes) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment ``` ### Add note to existing commit discussion @@ -933,7 +933,7 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z (requires admin or project/group owner rights) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment ``` ### Modify an existing commit discussion note @@ -955,13 +955,13 @@ Parameters: | `body` | string | no | The content of a note | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment ``` Resolving a note: ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true ``` ### Delete a commit discussion note @@ -982,5 +982,5 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636 ``` diff --git a/doc/api/environments.md b/doc/api/environments.md index 29da4590a59..4a38dd73747 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -13,7 +13,7 @@ GET /projects/:id/environments | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/environments +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/environments ``` Example response: @@ -46,7 +46,7 @@ POST /projects/:id/environments | `external_url` | string | no | Place to link to for this environment | ```bash -curl --data "name=deploy&external_url=https://deploy.example.gitlab.com" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/environments" +curl --data "name=deploy&external_url=https://deploy.example.gitlab.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments" ``` Example response: @@ -78,7 +78,7 @@ PUT /projects/:id/environments/:environments_id | `external_url` | string | no | The new external_url | ```bash -curl --request PUT --data "name=staging&external_url=https://staging.example.gitlab.com" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/environments/1" +curl --request PUT --data "name=staging&external_url=https://staging.example.gitlab.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" ``` Example response: @@ -106,7 +106,7 @@ DELETE /projects/:id/environments/:environment_id | `environment_id` | integer | yes | The ID of the environment | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/environments/1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" ``` ## Stop an environment @@ -123,7 +123,7 @@ POST /projects/:id/environments/:environment_id/stop | `environment_id` | integer | yes | The ID of the environment | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/environments/1/stop" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1/stop" ``` Example response: diff --git a/doc/api/events.md b/doc/api/events.md index ccac5b8bb60..6dca8e52f69 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -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: <your_access_token>" https://gitlab.example.com/api/v4/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` Example response: @@ -143,7 +143,7 @@ Parameters: | `sort` | string | no | Sort events in `asc` or `desc` order by `created_at`. Default is `desc` | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/:id/events +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/:id/events ``` 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: <your_access_token>" 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/features.md b/doc/api/features.md index 6ee1c36ef5b..47f104e1f20 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -14,7 +14,7 @@ GET /features ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features ``` Example response: @@ -60,12 +60,13 @@ POST /features/:name | `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time | | `feature_group` | string | no | A Feature group name | | `user` | string | no | A GitLab username | +| `project` | string | no | A projects path, for example 'gitlab-org/gitlab-ce' | -Note that you can enable or disable a feature for both a `feature_group` and a -`user` with a single API call. +Note that you can enable or disable a feature for a `feature_group`, a `user`, +and a `project` in a single API call. ```bash -curl --data "value=30" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/new_library +curl --data "value=30" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/new_library ``` Example response: diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index 71922318227..ec48bf4940b 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -24,7 +24,7 @@ feature flag. You can enable the feature using the [features api][features-api] For example: ```shell -curl --data "value=100" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/graphql +curl --data "value=100" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/graphql ``` ## Available queries diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index f2353542a5c..f88689d80c6 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -28,7 +28,7 @@ GET /groups/:id/badges | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/badges +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges ``` Example response: @@ -68,7 +68,7 @@ GET /groups/:id/badges/:badge_id | `badge_id` | integer | yes | The badge ID | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id ``` Example response: @@ -99,7 +99,7 @@ POST /groups/:id/badges | `image_url` | string | yes | URL of the badge image | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "link_url=https://gitlab.com/gitlab-org/gitlab-ce/commits/master&image_url=https://shields.io/my/badge1&position=0" https://gitlab.example.com/api/v4/groups/:id/badges +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-ce/commits/master&image_url=https://shields.io/my/badge1&position=0" https://gitlab.example.com/api/v4/groups/:id/badges ``` Example response: @@ -131,7 +131,7 @@ PUT /groups/:id/badges/:badge_id | `image_url` | string | no | URL of the badge image | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id ``` Example response: @@ -161,7 +161,7 @@ DELETE /groups/:id/badges/:badge_id | `badge_id` | integer | yes | The badge ID | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/:badge_id ``` ## Preview a badge from a group @@ -179,7 +179,7 @@ GET /groups/:id/badges/render | `image_url` | string | yes | URL of the badge image | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge ``` Example response: diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 373904e50c4..9b0ac23b41c 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -18,7 +18,7 @@ GET /groups/:id/boards | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards ``` Example response: @@ -75,7 +75,7 @@ GET /groups/:id/boards/:board_id | `board_id` | integer | yes | The ID of a board | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1 ``` Example response: @@ -131,7 +131,7 @@ GET /groups/:id/boards/:board_id/lists | `board_id` | integer | yes | The ID of a board | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards/1/lists +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists ``` Example response: @@ -183,7 +183,7 @@ GET /groups/:id/boards/:board_id/lists/:list_id | `list_id` | integer | yes | The ID of a board's list | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1 ``` Example response: @@ -215,7 +215,7 @@ POST /groups/:id/boards/:board_id/lists | `label_id` | integer | yes | The ID of a label | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards/1/lists?label_id=5 +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists?label_id=5 ``` Example response: @@ -248,7 +248,7 @@ PUT /groups/:id/boards/:board_id/lists/:list_id | `position` | integer | yes | The position of the list | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/group/5/boards/1/lists/1?position=2 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/group/5/boards/1/lists/1?position=2 ``` Example response: @@ -280,5 +280,5 @@ DELETE /groups/:id/boards/:board_id/lists/:list_id | `list_id` | integer | yes | The ID of a board's list | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1/lists/1 ``` diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index 33c6da08018..3551bfa3f8b 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -15,7 +15,7 @@ GET /groups/:id/variables | `id` | integer/string | yes | The ID of a group or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" ``` ```json @@ -45,7 +45,7 @@ GET /groups/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/TEST_VARIABLE_1" ``` ```json @@ -71,7 +71,7 @@ POST /groups/:id/variables | `protected` | boolean | no | Whether the variable is protected | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` ```json @@ -98,7 +98,7 @@ PUT /groups/:id/variables/:key | `protected` | boolean | no | Whether the variable is protected | ``` -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json @@ -123,7 +123,7 @@ DELETE /groups/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" ``` [ce-34519]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34519 diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index e396f4411e6..7be01ce9c6d 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -26,7 +26,7 @@ Parameters: | `search` | string | optional | Return only milestones with a title or description matching the provided string | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/milestones +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/milestones ``` Example Response: diff --git a/doc/api/groups.md b/doc/api/groups.md index be75c363a40..907b443d355 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: @@ -215,7 +220,7 @@ Parameters: | `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4 ``` 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": [ { @@ -351,12 +357,14 @@ Example response: { "group_id": 4, "group_name": "Twitter", + "group_full_path": "twitter", "group_access_level": 30, "expires_at": null }, { "group_id": 3, "group_name": "Gitlab Org", + "group_full_path": "gitlab-org", "group_access_level": 10, "expires_at": "2018-08-14" } @@ -369,7 +377,7 @@ Example response: When adding the parameter `with_projects=false`, projects will not be returned. ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4?with_projects=false +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4?with_projects=false ``` Example response: @@ -386,6 +394,7 @@ Example response: "request_access_enabled": false, "full_name": "Twitter", "full_path": "twitter", + "file_template_project_id": 1, "parent_id": null } ``` @@ -442,9 +451,10 @@ 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" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" ``` @@ -462,6 +472,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/import.md b/doc/api/import.md new file mode 100644 index 00000000000..9f8e0d232c6 --- /dev/null +++ b/doc/api/import.md @@ -0,0 +1,33 @@ +# Import API + +## Import repository from GitHub + +Import your projects from GitHub to GitLab via the API. + +``` +POST /import/github +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `personal_access_token` | string | yes | GitHub personal access token | +| `repo_id` | integer | yes | GitHub repository ID | +| `new_name` | string | no | New repo name | +| `target_namespace` | string | yes | Namespace to import repo into | + + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "personal_access_token=abc123&repo_id=12345&target_namespace=root" https://gitlab.example.com/api/v4/import/github +``` + +Example response: + +```json +{ + "id": 27, + "name": "my-repo", + "full_path": "/root/my-repo", + "full_name": "Administrator / my-repo" +} +``` + diff --git a/doc/api/issues.md b/doc/api/issues.md index cc1d6834a20..6d8683601f6 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. `Any+Milestone` lists all issues that have an assigned 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` | @@ -52,7 +52,7 @@ GET /issues?my_reaction_emoji=star | `updated_before` | datetime | no | Return issues updated on or before the given time | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/issues ``` Example response: @@ -106,6 +106,8 @@ Example response: "created_at" : "2016-01-04T15:31:51.081Z", "iid" : 6, "labels" : [], + "upvotes": 4, + "downvotes": 0, "user_notes_count": 1, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/6", @@ -149,13 +151,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` | @@ -166,7 +168,7 @@ GET /groups/:id/issues?my_reaction_emoji=star ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4/issues +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues ``` Example response: @@ -214,6 +216,8 @@ Example response: "name" : "Dr. Luella Kovacek" }, "labels" : [], + "upvotes": 4, + "downvotes": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -264,12 +268,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` | @@ -279,7 +283,7 @@ GET /projects/:id/issues?my_reaction_emoji=star | `updated_before` | datetime | no | Return issues updated on or before the given time | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues ``` Example response: @@ -327,6 +331,8 @@ Example response: "name" : "Dr. Luella Kovacek" }, "labels" : [], + "upvotes": 4, + "downvotes": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -373,7 +379,7 @@ GET /projects/:id/issues/:issue_iid | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues/41 ``` Example response: @@ -421,6 +427,8 @@ Example response: "name" : "Dr. Luella Kovacek" }, "labels" : [], + "upvotes": 4, + "downvotes": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -476,7 +484,7 @@ POST /projects/:id/issues | `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug ``` Example response: @@ -494,6 +502,8 @@ Example response: "labels" : [ "bug" ], + "upvotes": 4, + "downvotes": 0, "author" : { "name" : "Alexandra Bashirian", "avatar_url" : null, @@ -558,7 +568,7 @@ PUT /projects/:id/issues/:issue_iid ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close ``` Example response: @@ -592,6 +602,8 @@ Example response: "labels" : [ "bug" ], + "upvotes": 4, + "downvotes": 0, "id" : 85, "assignees" : [], "assignee" : null, @@ -635,7 +647,7 @@ DELETE /projects/:id/issues/:issue_iid | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues/85 ``` ## Move an issue @@ -658,7 +670,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: <your_access_token>" --form to_project_id=5 https://gitlab.example.com/api/v4/projects/4/issues/85/move ``` Example response: @@ -676,6 +688,8 @@ Example response: "closed_at": null, "closed_by": null, "labels": [], + "upvotes": 4, + "downvotes": 0, "milestone": null, "assignees": [{ "name": "Miss Monserrate Beier", @@ -740,7 +754,7 @@ POST /projects/:id/issues/:issue_iid/subscribe | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe ``` Example response: @@ -758,6 +772,8 @@ Example response: "closed_at": null, "closed_by": null, "labels": [], + "upvotes": 4, + "downvotes": 0, "milestone": null, "assignees": [{ "name": "Miss Monserrate Beier", @@ -823,7 +839,7 @@ POST /projects/:id/issues/:issue_iid/unsubscribe | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe ``` Example response: @@ -839,6 +855,8 @@ Example response: "created_at": "2016-04-05T21:41:45.217Z", "updated_at": "2016-04-07T13:02:37.905Z", "labels": [], + "upvotes": 4, + "downvotes": 0, "milestone": null, "assignee": { "name": "Edwardo Grady", @@ -882,7 +900,7 @@ POST /projects/:id/issues/:issue_iid/todo | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/todo ``` Example response: @@ -988,7 +1006,7 @@ POST /projects/:id/issues/:issue_iid/time_estimate | `duration` | string | yes | The duration in human format. e.g: 3h30m | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m ``` Example response: @@ -1016,7 +1034,7 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate ``` Example response: @@ -1045,7 +1063,7 @@ POST /projects/:id/issues/:issue_iid/add_spent_time | `duration` | string | yes | The duration in human format. e.g: 3h30m | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h ``` Example response: @@ -1073,7 +1091,7 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time ``` Example response: @@ -1099,7 +1117,7 @@ GET /projects/:id/issues/:issue_iid/time_stats | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats ``` Example response: @@ -1113,6 +1131,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: <your_access_token>" 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. @@ -1127,7 +1232,7 @@ GET /projects/:id/issues/:issue_iid/closed_by | `issue_iid` | integer | yes | The internal ID of a project issue | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by ``` Example response: @@ -1194,7 +1299,7 @@ GET /projects/:id/issues/:issue_iid/participants | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/participants +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/participants ``` Example response: @@ -1239,7 +1344,7 @@ GET /projects/:id/issues/:issue_iid/user_agent_detail | `issue_iid` | integer | yes | The internal ID of a project's issue | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/93/user_agent_detail ``` Example response: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index aa290ff4cf8..085e321b35f 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -8,13 +8,13 @@ Get a list of jobs in a project. GET /projects/:id/jobs ``` -| 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 **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `manual`; showing all jobs if none provided | +| 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 **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | -``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running' +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running' ``` Example of response @@ -140,14 +140,14 @@ Get a list of jobs for a pipeline. GET /projects/:id/pipelines/:pipeline_id/jobs ``` -| 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 | -| `scope` | string **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `manual`; showing all jobs if none provided | +| 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. | +| `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | -``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running' +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running' ``` Example of response @@ -273,13 +273,13 @@ Get a single job of a project GET /projects/:id/jobs/:job_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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | -``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8" +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8" ``` Example of response @@ -348,18 +348,18 @@ Get job artifacts of a project. GET /projects/:id/jobs/:job_id/artifacts ``` -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | Example requests: -``` -curl --location --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" +```sh +curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" ``` -Response: +Possible response status codes: | Status | Description | |-----------|---------------------------------| @@ -383,19 +383,19 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name Parameters -| 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 | -| `ref_name` | string | yes | The ref from a repository (can only be branch or tag name, not HEAD or SHA) | -| `job` | string | yes | The name of the job | +| 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. | +| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | +| `job` | string | yes | The name of the job. | Example requests: -``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" ``` -Example response: +Possible response status codes: | Status | Description | |-----------|---------------------------------| @@ -404,13 +404,13 @@ Example response: [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347 -## Download a single artifact file +## Download a single artifact file by job ID > Introduced in GitLab 10.0 -Download a single artifact file from within the job's artifacts archive. - -Only a single file is going to be extracted from the archive and streamed to a client. +Download a single artifact file from a job with a specified ID from within +the job's artifacts archive. The file is extracted from the archive and +streamed to the client. ``` GET /projects/:id/jobs/:job_id/artifacts/*artifact_path @@ -418,19 +418,54 @@ GET /projects/:id/jobs/:job_id/artifacts/*artifact_path Parameters -| 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 | -| `job_id ` | integer | yes | The unique job identifier | -| `artifact_path` | string | yes | Path to a file inside the artifacts archive | +| 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. | +| `job_id ` | integer | yes | The unique job identifier. | +| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | Example request: +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf" +``` + +Possible response status codes: + +| Status | Description | +|-----------|--------------------------------------| +| 200 | Sends a single artifact file | +| 400 | Invalid path provided | +| 404 | Build not found or no file/artifacts | + +## Download a single artifact file from specific tag or branch + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23538) in GitLab 11.5. + +Download a single artifact file from a specific tag or branch from within the +job's artifacts archive. The file is extracted from the archive and streamed to +the client. + ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf" +GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name ``` -Example response: +Parameters: + +| 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. | +| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | +| `artifact_path` | string | yes | Path to a file inside the artifacts archive. | +| `job` | string | yes | The name of the job. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/raw/some/release/file.pdf?job=pdf" +``` + +Possible response status codes: | Status | Description | |-----------|--------------------------------------| @@ -446,16 +481,16 @@ Get a trace of a specific job of a project GET /projects/:id/jobs/:job_id/trace ``` -| 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 | -| job_id | integer | yes | The ID of a job | +| 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. | +| job_id | integer | yes | The ID of a job. | -``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace" +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace" ``` -Response: +Possible response status codes: | Status | Description | |-----------|-----------------------------------| @@ -470,13 +505,13 @@ Cancel a single job of a project POST /projects/:id/jobs/:job_id/cancel ``` -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | -``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel" ``` Example of response @@ -518,13 +553,13 @@ Retry a single job of a project POST /projects/:id/jobs/:job_id/retry ``` -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | -``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry" ``` Example of response @@ -568,15 +603,15 @@ POST /projects/:id/jobs/:job_id/erase Parameters -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | Example of request -``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/1/erase" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/erase" ``` Example of response @@ -621,15 +656,15 @@ POST /projects/:id/jobs/:job_id/artifacts/keep Parameters -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | Example request: -``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep" ``` Example response: @@ -672,13 +707,13 @@ Triggers a manual action to start a job. POST /projects/:id/jobs/:job_id/play ``` -| 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 | -| `job_id` | integer | yes | The ID of a job | +| 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. | +| `job_id` | integer | yes | The ID of a job. | -``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play" +```sh +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play" ``` Example of response diff --git a/doc/api/labels.md b/doc/api/labels.md index ec93cf50e7a..aec1a2c7592 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -13,7 +13,7 @@ GET /projects/:id/labels | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/labels +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/labels ``` Example response: @@ -95,7 +95,7 @@ POST /projects/:id/labels | `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. | ```bash -curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/labels" +curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels" ``` Example response: @@ -128,7 +128,7 @@ DELETE /projects/:id/labels | `name` | string | yes | The name of the label | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/labels?name=bug" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?name=bug" ``` ## Edit an existing label @@ -151,7 +151,7 @@ PUT /projects/:id/labels ```bash -curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/labels" +curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels" ``` Example response: @@ -186,7 +186,7 @@ POST /projects/:id/labels/:label_id/subscribe | `label_id` | integer or string | yes | The ID or title of a project's label | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe ``` Example response: @@ -221,5 +221,5 @@ POST /projects/:id/labels/:label_id/unsubscribe | `label_id` | integer or string | yes | The ID or title of a project's label | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe ``` diff --git a/doc/api/lint.md b/doc/api/lint.md index bd5a216a99d..a0307f7081d 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -13,14 +13,14 @@ POST /lint | `content` | string | yes | the .gitlab-ci.yaml content| ```bash -curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.1\", \"services\": [\"postgres\"], \"before_script\": [\"gem install bundler\", \"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' +curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' ``` Be sure to copy paste the exact contents of `.gitlab-ci.yml` as YAML is very picky about indentation and spaces. Example responses: -* Valid content: +- Valid content: ```json { @@ -29,7 +29,7 @@ Example responses: } ``` -* Invalid content: +- Invalid content: ```json { @@ -40,7 +40,7 @@ Example responses: } ``` -* Without the content attribute: +- Without the content attribute: ```json { @@ -49,4 +49,3 @@ Example responses: ``` [ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953 - diff --git a/doc/api/members.md b/doc/api/members.md index bb4fae35f52..0593d2c20ea 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -28,8 +28,8 @@ GET /projects/:id/members | `query` | string | no | A query string to search for members | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/members +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/members ``` Example response: @@ -75,8 +75,8 @@ GET /projects/:id/members/all | `query` | string | no | A query string to search for members | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members/all -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members/all +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/members/all +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/members/all ``` Example response: @@ -131,8 +131,8 @@ GET /projects/:id/members/:user_id | `user_id` | integer | yes | The user ID of the member | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members/:user_id -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members/:user_id +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/members/:user_id +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/members/:user_id ``` Example response: @@ -167,8 +167,8 @@ POST /projects/:id/members | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "user_id=1&access_level=30" https://gitlab.example.com/api/v4/groups/:id/members -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "user_id=1&access_level=30" https://gitlab.example.com/api/v4/projects/:id/members +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "user_id=1&access_level=30" https://gitlab.example.com/api/v4/groups/:id/members +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "user_id=1&access_level=30" https://gitlab.example.com/api/v4/projects/:id/members ``` Example response: @@ -203,8 +203,8 @@ PUT /projects/:id/members/:user_id | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40 -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members/:user_id?access_level=40 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/members/:user_id?access_level=40 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/members/:user_id?access_level=40 ``` Example response: @@ -237,8 +237,8 @@ DELETE /projects/:id/members/:user_id | `user_id` | integer | yes | The user ID of the member | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/members/:user_id -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/members/:user_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/:id/members/:user_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/members/:user_id ``` ## Give a group access to a project diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 4d0c2f86190..6a61d7fabe4 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -30,24 +30,24 @@ 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 | +| `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 [ @@ -57,7 +57,18 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "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", @@ -154,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` | | `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests @@ -181,7 +192,18 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "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", @@ -267,23 +289,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 @@ -294,7 +316,18 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "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", @@ -376,6 +409,7 @@ 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 { @@ -384,7 +418,7 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -429,6 +463,7 @@ Parameters: }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, @@ -473,7 +508,8 @@ Parameters: "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "rebase_in_progress": false } ``` @@ -696,7 +732,7 @@ POST /projects/:id/merge_requests "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -741,6 +777,7 @@ POST /projects/:id/merge_requests }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, @@ -823,7 +860,7 @@ Must include at least one non-required attribute from above. "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -868,6 +905,7 @@ Must include at least one non-required attribute from above. }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, @@ -930,17 +968,16 @@ DELETE /projects/:id/merge_requests/:merge_request_iid | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/merge_requests/85 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/merge_requests/85 ``` ## Accept MR Merge changes submitted with MR using this API. +If merge request is unable to be accepted (ie: Work in Progress, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you'll get a `405` and the error message 'Method Not Allowed' -If it has some conflicts and can not be merged - you'll get a `405` and the error message 'Branch cannot be merged' - -If merge request is already merged or closed - you'll get a `406` and the error message 'Method Not Allowed' +If it has some conflicts and can not be merged - you'll get a `406` and the error message 'Branch cannot be merged' If the `sha` parameter is passed and does not match the HEAD of the source - you'll get a `409` and the error message 'SHA does not match HEAD of source branch' @@ -966,7 +1003,7 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -1011,6 +1048,7 @@ Parameters: }, "merge_when_pipeline_succeeds": true, "merge_status": "can_be_merged", + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, @@ -1081,7 +1119,7 @@ Parameters: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -1126,6 +1164,7 @@ Parameters: }, "merge_when_pipeline_succeeds": false, "merge_status": "can_be_merged", + "merge_error": null, "sha": "8888888888888888888888888888888888888888", "merge_commit_sha": null, "user_notes_count": 1, @@ -1174,6 +1213,62 @@ Parameters: } ``` +## 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: <your_access_token>" 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", +} +``` + ## Comments on merge requests Comments are done via the [notes](notes.md) resource. @@ -1192,7 +1287,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | `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/closes_issues +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/76/merge_requests/1/closes_issues ``` Example response when the GitLab issue tracker is used: @@ -1268,7 +1363,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe ``` Example response: @@ -1280,7 +1375,7 @@ Example response: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -1389,7 +1484,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe ``` Example response: @@ -1401,7 +1496,7 @@ Example response: "project_id": 3, "title": "test1", "description": "fixed login page css paddings", - "state": "opened", + "state": "merged", "created_at": "2017-04-29T08:46:00Z", "updated_at": "2017-04-29T08:46:00Z", "target_branch": "master", @@ -1510,7 +1605,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo ``` Example response: @@ -1541,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", @@ -1613,7 +1708,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions | `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/1/merge_requests/1/versions +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions ``` Example response: @@ -1655,7 +1750,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id | `version_id` | integer | yes | The ID of the merge request diff version | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1 ``` Example response: @@ -1722,7 +1817,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | `duration` | string | yes | The duration in human format. e.g: 3h30m | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m ``` Example response: @@ -1750,7 +1845,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate ``` Example response: @@ -1779,7 +1874,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | `duration` | string | yes | The duration in human format. e.g: 3h30m | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h ``` Example response: @@ -1807,7 +1902,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | `merge_request_iid` | integer | yes | The internal ID of a project's merge_request | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time ``` Example response: @@ -1833,7 +1928,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_stats +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_stats ``` Example response: diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 8f1a5c8e19b..fa8f8a0bcf0 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -1,4 +1,4 @@ -# Milestones API +# Project milestones API ## List project milestones @@ -23,7 +23,7 @@ Parameters: | `search` | string | optional | Return only milestones with a title or description matching the provided string | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/milestones +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/milestones ``` Example Response: @@ -45,7 +45,6 @@ Example Response: ] ``` - ## Get single milestone Gets a single project milestone. diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 656bf07bb55..b8bc4c40124 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -19,7 +19,7 @@ GET /namespaces Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces ``` Example response: @@ -71,7 +71,7 @@ GET /namespaces?search=foobar Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces?search=twitter +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces?search=twitter ``` Example response: @@ -105,7 +105,7 @@ GET /namespaces/:id Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces/2 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/2 ``` Example response: @@ -125,7 +125,7 @@ Example response: Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/namespaces/group1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/namespaces/group1 ``` Example response: diff --git a/doc/api/notes.md b/doc/api/notes.md index 44940bdd9e5..dd4e18b14e6 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -66,7 +66,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes ``` ### Get single issue note @@ -84,7 +84,7 @@ Parameters: - `note_id` (required) - The ID of an issue note ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1 ``` ### Create new issue note @@ -98,12 +98,12 @@ 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) ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note ``` ### Modify existing issue note @@ -122,7 +122,7 @@ Parameters: - `body` (required) - The content of a note ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note ``` ### Delete an issue note @@ -142,7 +142,7 @@ Parameters: | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/notes/636 ``` ## Snippets @@ -164,7 +164,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at | `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes ``` ### Get single snippet note @@ -201,7 +201,7 @@ Parameters: ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes/11 ``` ### Create new snippet note @@ -221,7 +221,7 @@ Parameters: - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note ``` ### Modify existing snippet note @@ -240,7 +240,7 @@ Parameters: - `body` (required) - The content of a note ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note ``` ### Delete a snippet note @@ -260,7 +260,7 @@ Parameters: | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/snippets/52/notes/1659 ``` ## Merge Requests @@ -282,7 +282,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda | `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes ``` ### Get single merge request note @@ -323,7 +323,7 @@ Parameters: ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes/1 ``` ### Create new merge request note @@ -359,7 +359,7 @@ Parameters: - `body` (required) - The content of a note ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note ``` ### Delete a merge request note @@ -379,5 +379,5 @@ Parameters: | `note_id` | integer | yes | The ID of a note | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/7/notes/1602 ``` diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 165b9a11c7a..e21e73c7dac 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -43,7 +43,7 @@ GET /notification_settings ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/notification_settings +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings ``` Example response: @@ -64,7 +64,7 @@ PUT /notification_settings ``` ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/notification_settings?level=watch +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/notification_settings?level=watch ``` | Attribute | Type | Required | Description | @@ -105,8 +105,8 @@ GET /projects/:id/notification_settings ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/notification_settings -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/8/notification_settings +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/notification_settings +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/8/notification_settings ``` | Attribute | Type | Required | Description | @@ -131,8 +131,8 @@ PUT /projects/:id/notification_settings ``` ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/notification_settings?level=watch +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/8/notification_settings?level=custom&new_note=true ``` | Attribute | Type | Required | Description | diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 8a1e6b52092..6e156a14b25 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,126 +1,165 @@ # 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 to 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. +If you want GitLab to be an OAuth authentication service provider to sign into +other services, see the [OAuth2 provider](../integration/oauth_provider.md) +documentation. This functionality is based on the +[doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). -This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper). +## Supported OAuth2 flows -## Supported OAuth2 Flows +GitLab currently supports the following authorization flows: -GitLab currently supports following authorization flows: +- **Web application flow:** Most secure and common type of flow, designed for + applications with secure server-side. +- **Implicit grant flow:** This flow is designed for user-agent only apps (e.g., single + page web application running on GitLab Pages). +- **Resource owner password credentials flow:** To be used **only** for securely + hosted, first-party services. -* *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). -* *Resource Owner Password Credentials Flow* - To be used **only** for securely hosted, first-party services. +Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out +how all those flows work and pick the right one for your use case. -Please refer to [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out in details how all those flows work and pick the right one for your use case. +Both **web application** and **implicit grant** flows require `application` to be +registered first via the `/profile/applications` page in your user's account. +During registration, by enabling proper scopes, you can limit the range of +resources which the `application` can access. Upon creation, you'll obtain the +`application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**. -Both *web application* and *implicit* flows require `application` to be registered first via `/profile/applications` page -in your user's account. During registration, by enabling proper scopes you can limit the range of resources which the `application` can access. Upon creation -you'll obtain `application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**. +CAUTION: **Important:** +OAuth specification advises sending the `state` parameter with each request to +`/oauth/authorize`. We highly recommended sending a unique value with each request +and validate it against the one in the redirect request. This is important in +order to prevent [CSRF attacks](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)). +The `state` parameter really should have been a requirement in the standard! ->**Important:** OAuth specification advises sending `state` parameter with each request to `/oauth/authorize`. We highly recommended to send a unique -value with each request and validate it against the one in redirect request. This is important to prevent [CSRF attacks]. The `state` param really should -have been a requirement in the standard! +In the following sections you will find detailed instructions on how to obtain +authorization with each flow. -In the following sections you will find detailed instructions on how to obtain authorization with each flow. +### Web application flow -### Web Application Flow +NOTE: **Note:** +Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.1) for a +detailed flow description. -Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.1) for a detailed flow description +The web application flow is: -#### 1. Requesting authorization code +1. Request authorization code. To do that, you should redirect the user to the + `/oauth/authorize` endpoint with the following GET parameters: -To request the authorization code, you should redirect the user to the `/oauth/authorize` endpoint with following GET parameters: + ``` + https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH + ``` -``` -https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code&state=YOUR_UNIQUE_STATE_HASH -``` + This will ask the user to approve the applications access to their account and + then redirect back to the `REDIRECT_URI` you provided. The redirect will + include the GET `code` parameter, for example: -This will ask the user to approve the applications access to their account and then redirect back to the `REDIRECT_URI` you provided. The redirect will -include the GET `code` parameter, for example: + ``` + http://myapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH + ``` -`http://myapp.com/oauth/redirect?code=1234567890&state=YOUR_UNIQUE_STATE_HASH` + You should then use `code` to request an access token. -You should then use the `code` to request an access token. +1. Once you have the authorization code you can request an `access_token` using the + code. You can do that by using any HTTP client. In the following example, + we are using Ruby's `rest-client`: -#### 2. Requesting access token + ```ruby + parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI' + RestClient.post 'http://gitlab.example.com/oauth/token', parameters + ``` -Once you have the authorization code you can request an `access_token` using the code, to do that you can use any HTTP client. In the following example, -we are using Ruby's `rest-client`: + Example response: -``` -parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=authorization_code&redirect_uri=REDIRECT_URI' -RestClient.post 'http://gitlab.example.com/oauth/token', parameters + ```json + { + "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54", + "token_type": "bearer", + "expires_in": 7200, + "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1" + } + ``` -# The response will be -{ - "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54", - "token_type": "bearer", - "expires_in": 7200, - "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1" -} -``` ->**Note:** -The `redirect_uri` must match the `redirect_uri` used in the original authorization request. +NOTE: **Note:** +The `redirect_uri` must match the `redirect_uri` used in the original +authorization request. You can now make requests to the API with the access token returned. +### Implicit grant flow -### Implicit Grant - -Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.2) for a detailed flow description. +NOTE: **Note:** +Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.2) for a +detailed flow description. -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. +CAUTION: **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 the +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)). ->**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)). - +Unlike the web flow, the client receives an `access token` immediately as a +result of the authorization request. The flow does not use the client secret +or the authorization code because all of the application code and storage is +easily accessible, therefore secrets can leak easily. -#### 1. Requesting access token - -To request the access token, you should redirect the user to the `/oauth/authorize` endpoint using `token` response type: +To request the access token, you should redirect the user to the +`/oauth/authorize` endpoint using `token` response type: ``` https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=token&state=YOUR_UNIQUE_STATE_HASH ``` -This will ask the user to approve the applications access to their account and then redirect back to the `REDIRECT_URI` you provided. The redirect -will include a fragment with `access_token` as well as token details in GET parameters, for example: +This will ask the user to approve the application's access to their account and +then redirect them back to the `REDIRECT_URI` you provided. The redirect +will include a fragment with `access_token` as well as token details in GET +parameters, for example: ``` http://myapp.com/oauth/redirect#access_token=ABCDExyz123&state=YOUR_UNIQUE_STATE_HASH&token_type=bearer&expires_in=3600 ``` -### Resource Owner Password Credentials +### Resource owner password credentials flow -Check [RFC spec](http://tools.ietf.org/html/rfc6749#section-4.3) for a detailed flow description. +NOTE: **Note:** +Check the [RFC spec](https://tools.ietf.org/html/rfc6749#section-4.3) for a +detailed flow description. -> **Deprecation notice:** Starting in GitLab 8.11, the Resource Owner Password Credentials has been *disabled* for users with two-factor authentication -turned on. These users can access the API using [personal access tokens] instead. +NOTE: **Note:** +The Resource Owner Password Credentials is disabled for users with [two-factor +authentication](../user/profile/account/two_factor_authentication.md) turned on. +These users can access the API using [personal access tokens](../user/profile/personal_access_tokens.md) +instead. -In this flow, a token is requested in exchange for the resource owner credentials (username and password). -The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the -client is part of the device operating system or a highly privileged application), and when other authorization grant types are not -available (such as an authorization code). +In this flow, a token is requested in exchange for the resource owner credentials +(username and password). ->**Important:** -Never store the users credentials and only use this grant type when your client is deployed to a trusted environment, in 99% of cases [personal access tokens] -are a better choice. +The credentials should only be used when: -Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used -for a single request and are exchanged for an access token. This grant type can eliminate the need for the client to store the -resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token. +- There is a high degree of trust between the resource owner and the client. For + example, the client is part of the device operating system or a highly + privileged application. +- Other authorization grant types are not available (such as an authorization code). -#### 1. Requesting access token +CAUTION: **Important:** +Never store the user's credentials and only use this grant type when your client +is deployed to a trusted environment, in 99% of cases +[personal access tokens](../user/profile/personal_access_tokens.md) are a better +choice. -POST request to `/oauth/token` with parameters: +Even though this grant type requires direct client access to the resource owner +credentials, the resource owner credentials are used for a single request and +are exchanged for an access token. This grant type can eliminate the need for +the client to store the resource owner credentials for future use, by exchanging +the credentials with a long-lived access token or refresh token. -``` +To request an access token, you must make a POST request to `/oauth/token` with +the following parameters: + +```json { "grant_type" : "password", "username" : "user@example.com", @@ -128,6 +167,13 @@ POST request to `/oauth/token` with parameters: } ``` +Example cURL request: + +```sh +echo 'grant_type=password&username=<your_username>&password=<your_password>' > auth.txt +curl --data "@auth.txt" --request POST https://gitlab.example.com/oauth/token +``` + Then, you'll receive the access token back in the response: ``` @@ -138,7 +184,7 @@ Then, you'll receive the access token back in the response: } ``` -For testing you can use the oauth2 ruby gem: +For testing, you can use the `oauth2` Ruby gem: ``` client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com") @@ -148,7 +194,9 @@ puts access_token.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 +The `access token` allows you to make requests to the API on behalf of a user. +You can pass the token either as GET parameter: + ``` GET https://gitlab.example.com/api/v4/user?access_token=OAUTH-TOKEN ``` @@ -159,5 +207,3 @@ or you can put the token to the Authorization header: curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user ``` -[personal access tokens]: ../user/profile/personal_access_tokens.md -[CSRF attacks]: http://www.oauthsecurity.com/#user-content-authorization-code-flow
\ No newline at end of file diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index da2ffcfe40a..4c41350dcdb 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -13,7 +13,7 @@ GET /pages/domains ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/pages/domains +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/pages/domains ``` ```json @@ -43,7 +43,7 @@ GET /projects/:id/pages/domains | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains ``` ```json @@ -79,7 +79,7 @@ GET /projects/:id/pages/domains/:domain | `domain` | string | yes | The domain | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/www.domain.example ``` ```json @@ -90,7 +90,7 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` ```json @@ -122,11 +122,11 @@ POST /projects/:id/pages/domains | `key` | file/string | no | The certificate key in PEM format. | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain=ssl.domain.example" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains ``` ```json @@ -158,11 +158,11 @@ PUT /projects/:id/pages/domains/:domain | `key` | file/string | no | The certificate key in PEM format. | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=@/path/to/cert.pem" --form "key=@/path/to/key.pem" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certificate=$CERT_PEM" --form "key=$KEY_PEM" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` ```json @@ -192,5 +192,5 @@ DELETE /projects/:id/pages/domains/:domain | `domain` | string | yes | The domain | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/pages/domains/ssl.domain.example ``` diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index e881e61d4ef..736312df116 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -15,7 +15,7 @@ GET /projects/:id/triggers | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers" ``` ```json @@ -46,7 +46,7 @@ GET /projects/:id/triggers/:trigger_id | `trigger_id` | integer | yes | The trigger id | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/5" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5" ``` ```json @@ -75,7 +75,7 @@ POST /projects/:id/triggers | `description` | string | yes | The trigger name | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers" ``` ```json @@ -105,7 +105,7 @@ PUT /projects/:id/triggers/:trigger_id | `description` | string | no | The trigger name | ``` -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10" ``` ```json @@ -134,7 +134,7 @@ POST /projects/:id/triggers/:trigger_id/take_ownership | `trigger_id` | integer | yes | The trigger id | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/10/take_ownership" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/10/take_ownership" ``` ```json @@ -163,5 +163,5 @@ DELETE /projects/:id/triggers/:trigger_id | `trigger_id` | integer | yes | The trigger id | ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers/5" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5" ``` diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 574be52801c..43bbf463c8d 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -22,7 +22,7 @@ GET /projects/:id/pipelines | `sort` | string | no | Sort pipelines in `asc` or `desc` order (default: `desc`) | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines" ``` Example of response @@ -60,7 +60,7 @@ GET /projects/:id/pipelines/:pipeline_id | `pipeline_id` | integer | yes | The ID of a pipeline | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines/46" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46" ``` Example of response @@ -108,7 +108,7 @@ POST /projects/:id/pipeline | `variables` | array | no | An array containing the variables available in the pipeline, matching the structure [{ 'key' => 'UPLOAD_TO_S3', 'value' => 'true' }] | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipeline?ref=master" ``` Example of response @@ -155,7 +155,7 @@ POST /projects/:id/pipelines/:pipeline_id/retry | `pipeline_id` | integer | yes | The ID of a pipeline | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/retry" ``` Response: @@ -202,7 +202,7 @@ POST /projects/:id/pipelines/:pipeline_id/cancel | `pipeline_id` | integer | yes | The ID of a pipeline | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/cancel" ``` Response: @@ -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: <your_access_token>" --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_badges.md b/doc/api/project_badges.md index 94389273e9c..3a7b3d8975e 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -25,7 +25,7 @@ GET /projects/:id/badges | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/badges +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/badges ``` Example response: @@ -65,7 +65,7 @@ GET /projects/:id/badges/:badge_id | `badge_id` | integer | yes | The badge ID | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id ``` Example response: @@ -96,7 +96,7 @@ POST /projects/:id/badges | `image_url` | string | yes | URL of the badge image | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "link_url=https://gitlab.com/gitlab-org/gitlab-ce/commits/master&image_url=https://shields.io/my/badge1&position=0" https://gitlab.example.com/api/v4/projects/:id/badges +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "link_url=https://gitlab.com/gitlab-org/gitlab-ce/commits/master&image_url=https://shields.io/my/badge1&position=0" https://gitlab.example.com/api/v4/projects/:id/badges ``` Example response: @@ -128,7 +128,7 @@ PUT /projects/:id/badges/:badge_id | `image_url` | string | no | URL of the badge image | ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id ``` Example response: @@ -158,7 +158,7 @@ DELETE /projects/:id/badges/:badge_id | `badge_id` | integer | yes | The badge ID | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/badges/:badge_id ``` ## Preview a badge from a project @@ -176,7 +176,7 @@ GET /projects/:id/badges/render | `image_url` | string | yes | URL of the badge image | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/badges/render?link_url=http%3A%2F%2Fexample.com%2Fci_status.svg%3Fproject%3D%25%7Bproject_path%7D%26ref%3D%25%7Bdefault_branch%7D&image_url=https%3A%2F%2Fshields.io%2Fmy%2Fbadge ``` Example response: diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md new file mode 100644 index 00000000000..8efb98fe1fc --- /dev/null +++ b/doc/api/project_clusters.md @@ -0,0 +1,347 @@ +# Project clusters API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23922) +in GitLab 11.7. + +NOTE: **Note:** +User will need at least maintainer access to use these endpoints. + +## List project clusters + +Returns a list of project clusters. + +``` +GET /projects/:id/clusters +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters +``` + +Example response: + +```json +[ + { + "id":18, + "name":"cluster-1", + "created_at":"2019-01-02T20:18:12.563Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"project_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://104.197.68.152", + "namespace":"cluster-1-namespace", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + } + }, + { + "id":19, + "name":"cluster-2", + ... + } +] +``` + +## Get a single project cluster + +Gets a single project cluster. + +```bash +GET /projects/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/18 +``` + +Example response: + +```json +{ + "id":18, + "name":"cluster-1", + "created_at":"2019-01-02T20:18:12.563Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"project_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://104.197.68.152", + "namespace":"cluster-1-namespace", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + }, + "project": + { + "id":26, + "description":"", + "name":"project-with-clusters-api", + "name_with_namespace":"Administrator / project-with-clusters-api", + "path":"project-with-clusters-api", + "path_with_namespace":"root/project-with-clusters-api", + "created_at":"2019-01-02T20:13:32.600Z", + "default_branch":null, + "tag_list":[], + "ssh_url_to_repo":"ssh://gitlab.example.com/root/project-with-clusters-api.git", + "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", + "web_url":"https://gitlab.example.com/root/project-with-clusters-api", + "readme_url":null, + "avatar_url":null, + "star_count":0, + "forks_count":0, + "last_activity_at":"2019-01-02T20:13:32.600Z", + "namespace": + { + "id":1, + "name":"root", + "path":"root", + "kind":"user", + "full_path":"root", + "parent_id":null + } + } +} +``` + +## Add existing cluster to project + +Adds an existing Kubernetes cluster to the project. + +```bash +POST /projects/:id/clusters/user +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `name` | String | yes | The name of the cluster | +| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true | +| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/user \ +-H "Accept: application/json" \ +-H "Content-Type:application/json" \ +-X POST --data '{"name":"cluster-5", "platform_kubernetes_attributes":{"api_url":"https://35.111.51.20","token":"12345","namespace":"cluster-5-namespace","ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----"}}' +``` + +Example response: + +```json +{ + "id":24, + "name":"cluster-5", + "created_at":"2019-01-03T21:53:40.610Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"project_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://35.111.51.20", + "namespace":"cluster-5-namespace", + "authorization_type":"rbac", + "ca_cert":"-----BEGIN CERTIFICATE-----\r\nhFiK1L61owwDQYJKoZIhvcNAQELBQAw\r\nLzEtMCsGA1UEAxMkZDA1YzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM4ZDBj\r\nMB4XDTE4MTIyNzIwMDM1MVoXDTIzMTIyNjIxMDM1MVowLzEtMCsGA1UEAxMkZDA1\r\nYzQ1YjctNzdiMS00NDY0LThjNmEtMTQ0ZDJkZjM.......-----END CERTIFICATE-----" + }, + "project": + { + "id":26, + "description":"", + "name":"project-with-clusters-api", + "name_with_namespace":"Administrator / project-with-clusters-api", + "path":"project-with-clusters-api", + "path_with_namespace":"root/project-with-clusters-api", + "created_at":"2019-01-02T20:13:32.600Z", + "default_branch":null, + "tag_list":[], + "ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git", + "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", + "web_url":"https://gitlab.example.com/root/project-with-clusters-api", + "readme_url":null, + "avatar_url":null, + "star_count":0, + "forks_count":0, + "last_activity_at":"2019-01-02T20:13:32.600Z", + "namespace": + { + "id":1, + "name":"root", + "path":"root", + "kind":"user", + "full_path":"root", + "parent_id":null + } + } +} +``` + +## Edit project cluster + +Updates an existing project cluster. + +```bash +PUT /projects/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | +| `name` | String | no | The name of the cluster | +| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | + +NOTE: **Note:** +`name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added +through the ["Add an existing Kubernetes Cluster"](../user/project/clusters/index.md#adding-an-existing-kubernetes-cluster) option or +through the ["Add existing cluster to project"](#add-existing-cluster-to-project) endpoint. + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/24 \ +-H "Content-Type:application/json" \ +-X PUT --data '{"name":"new-cluster-name","api_url":"https://new-api-url.com"}' +``` + +Example response: + +```json +{ + "id":24, + "name":"new-cluster-name", + "created_at":"2019-01-03T21:53:40.610Z", + "provider_type":"user", + "platform_type":"kubernetes", + "environment_scope":"*", + "cluster_type":"project_type", + "user": + { + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/4249f4df72b..", + "web_url":"https://gitlab.example.com/root" + }, + "platform_kubernetes": + { + "api_url":"https://new-api-url.com", + "namespace":"cluster-5-namespace", + "authorization_type":"rbac", + "ca_cert":null + }, + "project": + { + "id":26, + "description":"", + "name":"project-with-clusters-api", + "name_with_namespace":"Administrator / project-with-clusters-api", + "path":"project-with-clusters-api", + "path_with_namespace":"root/project-with-clusters-api", + "created_at":"2019-01-02T20:13:32.600Z", + "default_branch":null, + "tag_list":[], + "ssh_url_to_repo":"ssh:://gitlab.example.com/root/project-with-clusters-api.git", + "http_url_to_repo":"https://gitlab.example.com/root/project-with-clusters-api.git", + "web_url":"https://gitlab.example.com/root/project-with-clusters-api", + "readme_url":null, + "avatar_url":null, + "star_count":0, + "forks_count":0, + "last_activity_at":"2019-01-02T20:13:32.600Z", + "namespace": + { + "id":1, + "name":"root", + "path":"root", + "kind":"user", + "full_path":"root", + "parent_id":null + } + } +} + +``` + +## Delete project cluster + +Deletes an existing project cluster. + +``` +DELETE /projects/:id/clusters/:cluster_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project owned by the authenticated user | +| `cluster_id` | integer | yes | The ID of the cluster | + +Example request: + +```bash +curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/26/clusters/23' +``` diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 83e405141f1..fc91c5741da 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -30,7 +30,7 @@ POST /projects/:id/export ```console -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export \ +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export \ --data "upload[http_method]=PUT" \ --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd" ``` @@ -54,7 +54,7 @@ GET /projects/:id/export | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```console -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/export +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export ``` Status can be one of `none`, `started`, `after_export_action` or `finished`. The @@ -95,7 +95,7 @@ GET /projects/:id/export/download | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```console -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download +curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download ``` ```console @@ -125,7 +125,7 @@ The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: ```console -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import ``` cURL doesn't support posting a file from a remote server. Importing a project from a remote server can be accomplished through something like the following: @@ -145,7 +145,7 @@ data = { "namespace": "example-group" } headers = { - 'Private-Token': "9koXpg98eAheJpvBs5tK" + 'Private-Token': "<your_access_token>" } requests.post(url, headers=headers, data=data, files=files) @@ -177,7 +177,7 @@ GET /projects/:id/import | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```console -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/import +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/import ``` Status can be one of `none`, `scheduled`, `failed`, `started`, or `finished`. diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 82ac0b09027..438bebe62f5 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -13,7 +13,7 @@ GET /projects/:id/variables | `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" ``` ```json @@ -43,7 +43,7 @@ GET /projects/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables/TEST_VARIABLE_1" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/TEST_VARIABLE_1" ``` ```json @@ -69,7 +69,7 @@ POST /projects/:id/variables | `protected` | boolean | no | Whether the variable is protected | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` ```json @@ -96,7 +96,7 @@ PUT /projects/:id/variables/:key | `protected` | boolean | no | Whether the variable is protected | ``` -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json @@ -121,5 +121,5 @@ DELETE /projects/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1" ``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index cc495c5d091..8f4640fcbd6 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -137,7 +137,7 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail | `snippet_id` | Integer | yes | The ID of a snippet | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/snippets/2/user_agent_detail +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/snippets/2/user_agent_detail ``` Example response: diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index ebdfa975849..ef98205cd68 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -1,19 +1,23 @@ # Project templates API -This API is a project-specific implementation of these endpoints: +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 those endpoints, which will be removed for API version 5. +It deprecates these endpoints, which will be removed for API version 5. -Project-specific templates will be added to this API in time. This includes, but -is not limited to: +In addition to templates common to the entire instance, project-specific +templates are also available from this API endpoint. -- [Issue and Merge Request templates](../user/project/description_templates.html) -- [Group level file templates](https://gitlab.com/gitlab-org/gitlab-ee/issues/5987) **(Premium)** +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 diff --git a/doc/api/projects.md b/doc/api/projects.md index 947e7db9c52..1296b435792 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -7,30 +7,29 @@ This is determined by the `visibility` field in the project. Values for the project visibility level are: -* `private`: +- `private`: Project access must be granted explicitly for each user. -* `internal`: +- `internal`: The project can be cloned by any logged in user. -* `public`: +- `public`: The project can be cloned without any authentication. ## Project merge method There are currently three options for `merge_method` to choose from: -* `merge`: +- `merge`: A merge commit is created for every merge, and merging is allowed as long as there are no conflicts. -* `rebase_merge`: +- `rebase_merge`: A merge commit is created for every merge, but merging is only allowed if fast-forward merge is possible. This way you could make sure that if this merge request would build, after merging to target branch it would also build. -* `ff`: +- `ff`: No merge commits are created and all merges are fast-forwarded, which means that merging is only allowed if the branch could be fast-forwarded. - ## List all projects Get a list of all visible projects across GitLab for the authenticated user. @@ -451,6 +450,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 +508,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, @@ -517,11 +525,13 @@ GET /projects/:id { "group_id": 4, "group_name": "Twitter", + "group_full_path": "twitter", "group_access_level": 30 }, { "group_id": 3, "group_name": "Gitlab Org", + "group_full_path": "gitlab-org", "group_access_level": 10 } ], @@ -572,6 +582,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 +669,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 +707,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 +743,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 | @@ -781,7 +799,7 @@ GET /projects/:id/forks | `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/forks" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/forks" ``` Example responses: @@ -861,7 +879,7 @@ POST /projects/:id/star | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/star" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/star" ``` Example response: @@ -905,6 +923,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, @@ -939,7 +965,7 @@ POST /projects/:id/unstar | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unstar" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unstar" ``` Example response: @@ -983,6 +1009,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, @@ -1013,7 +1047,7 @@ GET /projects/:id/languages ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/languages" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/languages" ``` Example response: @@ -1041,7 +1075,7 @@ POST /projects/:id/archive | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/archive" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/archive" ``` Example response: @@ -1101,6 +1135,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, @@ -1137,7 +1179,7 @@ POST /projects/:id/unarchive | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unarchive" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/unarchive" ``` Example response: @@ -1197,6 +1239,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, @@ -1250,7 +1300,7 @@ The `file=` parameter must point to a file on your filesystem and be preceded by `@`. For example: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "file=@dk.png" https://gitlab.example.com/api/v4/projects/5/uploads +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" https://gitlab.example.com/api/v4/projects/5/uploads ``` Returned object: @@ -1296,7 +1346,7 @@ DELETE /projects/:id/share/:group_id | `group_id` | integer | yes | The ID of the group | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/share/17 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/share/17 ``` ## Hooks @@ -1464,7 +1514,7 @@ GET /projects | `sort` | string | no | Return requests sorted in `asc` or `desc` order | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects?search=test +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects?search=test ``` ## Start the Housekeeping task for a Project diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index ed8837574a0..fa04680d406 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -24,7 +24,7 @@ GET /projects/:id/protected_branches | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches' +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches' ``` Example response: @@ -64,7 +64,7 @@ GET /projects/:id/protected_branches/:name | `name` | string | yes | The name of the branch or wildcard | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master' +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master' ``` Example response: @@ -97,7 +97,7 @@ POST /projects/:id/protected_branches ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30' +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30' ``` | Attribute | Type | Required | Description | @@ -136,7 +136,7 @@ DELETE /projects/:id/protected_branches/:name ``` ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable' +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable' ``` | Attribute | Type | Required | Description | diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index aa750e467f8..3adca61a108 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -25,7 +25,7 @@ GET /projects/:id/protected_tags | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_tags' +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_tags' ``` Example response: @@ -60,7 +60,7 @@ GET /projects/:id/protected_tags/:name | `name` | string | yes | The name of the tag or wildcard | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0' +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_tags/release-1-0' ``` Example response: @@ -87,7 +87,7 @@ POST /projects/:id/protected_tags ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_tags?name=*-stable&create_access_level=30' +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_tags?name=*-stable&create_access_level=30' ``` | Attribute | Type | Required | Description | @@ -119,7 +119,7 @@ DELETE /projects/:id/protected_tags/:name ``` ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable' +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_tags/*-stable' ``` | Attribute | Type | Required | Description | diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md new file mode 100644 index 00000000000..943109a3ea9 --- /dev/null +++ b/doc/api/releases/index.md @@ -0,0 +1,482 @@ +# Releases API + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. +> - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries. +> - For manipulating links as a release asset, see [Release Links API](links.md) + +## List Releases + +Paginated list of Releases, sorted by `created_at`. + +``` +GET /projects/:id/releases +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases" +``` + +Example response: + +```json +[ + { + "tag_name":"v0.2", + "description":"## CHANGELOG\r\n\r\n- Escape label and milestone titles to prevent XSS in GFM autocomplete. !2740\r\n- Prevent private snippets from being embeddable.\r\n- Add subresources removal to member destroy service.", + "name":"Awesome app v0.2 beta", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eEscape label and milestone titles to prevent XSS in GFM autocomplete. !2740\u003c/li\u003e\n\u003cli\u003ePrevent private snippets from being embeddable.\u003c/li\u003e\n\u003cli\u003eAdd subresources removal to member destroy service.\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:56:19.539Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"079e90101242458910cccd35eab0e211dfc359c0", + "short_id":"079e9010", + "title":"Update README.md", + "created_at":"2019-01-03T01:55:38.000Z", + "parent_ids":[ + "f8d3d94cbd347e924aa7b715845e439d00e80ca4" + ], + "message":"Update README.md", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:55:38.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:55:38.000Z" + }, + "assets":{ + "count":6, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.2/awesome-app-v0.2.tar" + } + ], + "links":[ + { + "id":2, + "name":"awesome-v0.2.msi", + "url":"http://192.168.10.15:3000/msi", + "external":true + }, + { + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true + } + ] + } + }, + { + "tag_name":"v0.1", + "description":"## CHANGELOG\r\n\r\n-Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516", + "name":"Awesome app v0.1 alpha", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4", + "short_id":"f8d3d94c", + "title":"Initial commit", + "created_at":"2019-01-03T01:53:28.000Z", + "parent_ids":[ + + ], + "message":"Initial commit", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:53:28.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:53:28.000Z" + }, + "assets":{ + "count":4, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } + } +] +``` + +## Get a Release by a tag name + +Get a Release for the given tag. + +``` +GET /projects/:id/releases/:tag_name +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag where the release will be created from. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +Example response: + +```json +{ + "tag_name":"v0.1", + "description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516", + "name":"Awesome app v0.1 alpha", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4", + "short_id":"f8d3d94c", + "title":"Initial commit", + "created_at":"2019-01-03T01:53:28.000Z", + "parent_ids":[ + + ], + "message":"Initial commit", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:53:28.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:53:28.000Z" + }, + "assets":{ + "count":4, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` + +## Create a release + +Create a Release. You need push access to the repository to create a Release. + +``` +POST /projects/:id/releases +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `name` | string | yes | The release name. | +| `tag_name` | string | yes | The tag where the release will be created from. | +| `description` | string | yes | The description of the release. You can use [markdown](../user/markdown.md). | +| `ref` | string | no | If `tag_name` doesn't exist, the release will be created from `ref`. It can be a commit SHA, another tag name, or a branch name. | +| `assets:links`| array of hash | no | An array of assets links. | +| `assets:links:name`| string | no (if `assets:links` specified, it's required) | The name of the link. | +| `assets:links:url`| string | no (if `assets:links` specified, it's required) | The url of the link. | + +Example request: + +```sh +curl --header 'Content-Type: application/json' --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \ + --data '{ "name": "New release", "tag_name": "v0.3", "description": "Super nice release", "assets": { "links": [{ "name": "hoge", "url": "https://google.com" }] } }' \ + --request POST http://localhost:3000/api/v4/projects/24/releases +``` + +Example response: + +```json +{ + "tag_name":"v0.3", + "description":"Super nice release", + "name":"New release", + "description_html":"\u003cp dir=\"auto\"\u003eSuper nice release\u003c/p\u003e", + "created_at":"2019-01-03T02:22:45.118Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"079e90101242458910cccd35eab0e211dfc359c0", + "short_id":"079e9010", + "title":"Update README.md", + "created_at":"2019-01-03T01:55:38.000Z", + "parent_ids":[ + "f8d3d94cbd347e924aa7b715845e439d00e80ca4" + ], + "message":"Update README.md", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:55:38.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:55:38.000Z" + }, + "assets":{ + "count":5, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.3/awesome-app-v0.3.tar" + } + ], + "links":[ + { + "id":3, + "name":"hoge", + "url":"https://google.com", + "external":true + } + ] + } +} +``` + +## Update a release + +Update a Release. + +``` +PUT /projects/:id/releases/:tag_name +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag where the release will be created from. | +| `name` | string | no | The release name. | +| `description` | string | no | The description of the release. You can use [markdown](../user/markdown.md). | + +Example request: + +```sh +curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +Example response: + +```json +{ + "tag_name":"v0.1", + "description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516", + "name":"new name", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4", + "short_id":"f8d3d94c", + "title":"Initial commit", + "created_at":"2019-01-03T01:53:28.000Z", + "parent_ids":[ + + ], + "message":"Initial commit", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:53:28.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:53:28.000Z" + }, + "assets":{ + "count":4, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` + +## Delete a Release + +Delete a Release. Deleting a Release will not delete the associated tag. + +``` +DELETE /projects/:id/releases/:tag_name +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag where the release will be created from. | + +Example request: + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1" +``` + +Example response: + +```json +{ + "tag_name":"v0.1", + "description":"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching repository code. !8671\r\n- Show error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\r\n- Fix a bug where internal email pattern wasn't respected. !22516", + "name":"new name", + "description_html":"\u003ch2 dir=\"auto\"\u003e\n\u003ca id=\"user-content-changelog\" class=\"anchor\" href=\"#changelog\" aria-hidden=\"true\"\u003e\u003c/a\u003eCHANGELOG\u003c/h2\u003e\n\u003cul dir=\"auto\"\u003e\n\u003cli\u003eRemove limit of 100 when searching repository code. !8671\u003c/li\u003e\n\u003cli\u003eShow error message when attempting to reopen an MR and there is an open MR for the same branch. !16447 (Akos Gyimesi)\u003c/li\u003e\n\u003cli\u003eFix a bug where internal email pattern wasn't respected. !22516\u003c/li\u003e\n\u003c/ul\u003e", + "created_at":"2019-01-03T01:55:18.203Z", + "author":{ + "id":1, + "name":"Administrator", + "username":"root", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon", + "web_url":"http://localhost:3000/root" + }, + "commit":{ + "id":"f8d3d94cbd347e924aa7b715845e439d00e80ca4", + "short_id":"f8d3d94c", + "title":"Initial commit", + "created_at":"2019-01-03T01:53:28.000Z", + "parent_ids":[ + + ], + "message":"Initial commit", + "author_name":"Administrator", + "author_email":"admin@example.com", + "authored_date":"2019-01-03T01:53:28.000Z", + "committer_name":"Administrator", + "committer_email":"admin@example.com", + "committed_date":"2019-01-03T01:53:28.000Z" + }, + "assets":{ + "count":4, + "sources":[ + { + "format":"zip", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.zip" + }, + { + "format":"tar.gz", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.gz" + }, + { + "format":"tar.bz2", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar.bz2" + }, + { + "format":"tar", + "url":"http://localhost:3000/root/awesome-app/-/archive/v0.1/awesome-app-v0.1.tar" + } + ], + "links":[ + + ] + } +} +``` diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md new file mode 100644 index 00000000000..ae99f3bd8b6 --- /dev/null +++ b/doc/api/releases/links.md @@ -0,0 +1,177 @@ +# Release links API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. + +Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md). + +## Get links + +Get assets as links from a Release. + +``` +GET /projects/:id/releases/:tag_name/assets/links +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links" +``` + +Example response: + +```json +[ + { + "id":2, + "name":"awesome-v0.2.msi", + "url":"http://192.168.10.15:3000/msi", + "external":true + }, + { + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true + } +] +``` + +## Get a link + +Get an asset as a link from a Release. + +``` +GET /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Create a link + +Create an asset as a link from a Release. + +``` +POST /projects/:id/releases/:tag_name/assets/links +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `name` | string | yes | The name of the link. | +| `url` | string | yes | The URL of the link. | + +Example request: + +```sh +curl --request POST \ + --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \ + --data name="awesome-v0.2.dmg" \ + --data url="http://192.168.10.15:3000" \ + "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links" +``` + +Example response: + +```json +{ + "id":1, + "name":"awesome-v0.2.dmg", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Update a link + +Update an asset as a link from a Release. + +``` +PUT /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | +| `name` | string | no | The name of the link. | +| `url` | string | no | The URL of the link. | + +NOTE: **NOTE** +You have to specify at least one of `name` or `url` + +Example request: + +```sh +curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"new name", + "url":"http://192.168.10.15:3000", + "external":true +} +``` + +## Delete a link + +Delete an asset as a link from a Release. + +``` +DELETE /projects/:id/releases/:tag_name/assets/links/:link_id +``` + +| Attribute | Type | Required | Description | +| ------------- | -------------- | -------- | --------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `tag_name` | string | yes | The tag associated with the Release. | +| `link_id` | integer | yes | The id of the link. | + +Example request: + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1" +``` + +Example response: + +```json +{ + "id":1, + "name":"new name", + "url":"http://192.168.10.15:3000", + "external":true +} +``` diff --git a/doc/api/repositories.md b/doc/api/repositories.md index f5ac3816fe5..104c64a89ce 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 @@ -207,7 +212,7 @@ Response: ## Merge Base -Get the common ancestor for 2 refs (commit SHAs, branch names or tags). +Get the common ancestor for 2 or more refs (commit SHAs, branch names or tags). ``` GET /projects/:id/repository/merge_base @@ -219,7 +224,7 @@ GET /projects/:id/repository/merge_base | `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" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257dcb821665ab5110318fc58a007bd104ed&refs[]=0031876facac3f2b2702a0e53a26e89939a42209" ``` Example response: diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index c3624f1a535..8c1d982f394 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -4,6 +4,16 @@ **Create, read, update and delete repository files using this API** +The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted +in the following table. + +| Scope | Description | +| ----- | ----------- | +| `read_repository` | Allows read-access to the repository files. | +| `api` | Allows read-write access to the repository files. | + +> `read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23534) in GitLab 11.6. + ## Get file from repository Allows you to receive information about file in repository like name, size, @@ -15,7 +25,7 @@ GET /projects/:id/repository/files/:file_path ``` ```bash -curl --request GET --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master' +curl --request GET --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master' ``` Example response: @@ -50,7 +60,7 @@ HEAD /projects/:id/repository/files/:file_path ``` ```bash -curl --head --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master' +curl --head --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master' ``` Example response: @@ -77,7 +87,7 @@ GET /projects/:id/repository/files/:file_path/raw ``` ```bash -curl --request GET --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master' +curl --request GET --header 'PRIVATE-TOKEN: <your_access_token>' 'https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master' ``` Parameters: @@ -97,7 +107,7 @@ POST /projects/:id/repository/files/:file_path ``` ```bash -curl --request POST --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ +curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' --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' @@ -132,7 +142,7 @@ PUT /projects/:id/repository/files/:file_path ``` ```bash -curl --request PUT --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ +curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' --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' @@ -177,7 +187,7 @@ DELETE /projects/:id/repository/files/:file_path ``` ```bash -curl --request DELETE --header 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' --header "Content-Type: application/json" \ +curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' --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' diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md new file mode 100644 index 00000000000..2c44c4abc93 --- /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: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/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/resource_label_events.md b/doc/api/resource_label_events.md index 33e4821ccf4..e1f9ffa9472 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -65,7 +65,7 @@ GET /projects/:id/issues/:issue_iid/resource_label_events ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events ``` ### Get single issue label event @@ -85,7 +85,7 @@ Parameters: | `resource_label_event_id` | integer | yes | The ID of a label event | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1 ``` ## Merge requests @@ -151,7 +151,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/resource_label_events ``` ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events ``` ### Get single merge request label event @@ -171,5 +171,5 @@ Parameters: | `resource_label_event_id` | integer | yes | The ID of a label event | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events/120 +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/resource_label_events/120 ``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 0bcbd0aebf0..4aa0e4543e5 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -22,7 +22,7 @@ GET /runners?status=active | `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" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" ``` Example response: @@ -71,7 +71,7 @@ GET /runners/all?status=active | `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" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all" ``` Example response: @@ -134,7 +134,7 @@ GET /runners/:id | `id` | integer | yes | The ID of a runner | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` Example response: @@ -193,7 +193,7 @@ PUT /runners/:id | `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | ``` -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` Example response: @@ -247,7 +247,7 @@ DELETE /runners/:id | `id` | integer | yes | The ID of a runner | ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` ## List runner's jobs @@ -264,7 +264,7 @@ GET /runners/:id/jobs | `status` | string | no | Status of the job; one of: `running`, `success`, `failed`, `canceled` | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running" ``` Example response: @@ -340,8 +340,7 @@ 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 @@ -358,7 +357,7 @@ GET /projects/:id/runners?status=active | `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" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" ``` Example response: @@ -402,7 +401,7 @@ POST /projects/:id/runners | `runner_id` | integer | yes | The ID of a runner | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9" ``` Example response: @@ -436,7 +435,7 @@ DELETE /projects/:id/runners/:runner_id | `runner_id` | integer | yes | The ID of a runner | ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9" ``` ## Register a new Runner diff --git a/doc/api/search.md b/doc/api/search.md index 9716f682ace..aaaed7d9956 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -24,7 +24,7 @@ The response depends on the requested scope. ### Scope: projects ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=projects&search=flight +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=projects&search=flight ``` Example response: @@ -55,7 +55,7 @@ Example response: ### Scope: issues ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=issues&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=issues&search=file ``` Example response: @@ -120,7 +120,7 @@ Example response: ### Scope: merge_requests ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=merge_requests&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=merge_requests&search=file ``` Example response: @@ -197,7 +197,7 @@ Example response: ### Scope: milestones ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=milestones&search=release +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=milestones&search=release ``` Example response: @@ -222,7 +222,7 @@ Example response: ### Scope: snippet_titles ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=snippet_titles&search=sample +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=snippet_titles&search=sample ``` Example response: @@ -253,7 +253,7 @@ Example response: ### Scope: snippet_blobs ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/search?scope=snippet_blos&search=test +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=snippet_blos&search=test ``` Example response: @@ -305,7 +305,7 @@ The response depends on the requested scope. ### Scope: projects ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/3/search?scope=projects&search=flight +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/3/search?scope=projects&search=flight ``` Example response: @@ -336,7 +336,7 @@ Example response: ### Scope: issues ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/3/search?scope=issues&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/3/search?scope=issues&search=file ``` Example response: @@ -401,7 +401,7 @@ Example response: ### Scope: merge_requests ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/3/search?scope=merge_requests&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/3/search?scope=merge_requests&search=file ``` Example response: @@ -478,7 +478,7 @@ Example response: ### Scope: milestones ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/3/search?scope=milestones&search=release +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/3/search?scope=milestones&search=release ``` Example response: @@ -524,7 +524,7 @@ The response depends on the requested scope. ### Scope: issues ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/12/search?scope=issues&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/12/search?scope=issues&search=file ``` Example response: @@ -589,7 +589,7 @@ Example response: ### Scope: merge_requests ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=merge_requests&search=file +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=merge_requests&search=file ``` Example response: @@ -666,7 +666,7 @@ Example response: ### Scope: milestones ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/12/search?scope=milestones&search=release +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/12/search?scope=milestones&search=release ``` Example response: @@ -691,7 +691,7 @@ Example response: ### Scope: notes ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=notes&search=maxime +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=notes&search=maxime ``` Example response: @@ -722,8 +722,25 @@ Example response: ### Scope: wiki_blobs +Filters are available for this scope: + +- filename +- path +- extension + +To use a filter simply include it in your query like: `a query filename:some_name*`. +You may use wildcards (`*`) to use glob matching. + +Wiki blobs searches are performed on both filenames and contents. Search +results: + +- Found in filenames are displayed before results found in contents. +- May contain multiple matches for the same blob because the search string + might be found in both the filename and content, or might appear multiple + times in the content. + ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=wiki_blobs&search=bye +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=wiki_blobs&search=bye ``` Example response: @@ -746,7 +763,7 @@ Example response: ### Scope: commits ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=commits&search=bye +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=commits&search=bye ``` Example response: @@ -777,16 +794,23 @@ Example response: ### Scope: blobs Filters are available for this scope: + - filename - path - extension -to use a filter simply include it in your query like so: `a query filename:some_name*`. - +To use a filter simply include it in your query like: `a query filename:some_name*`. You may use wildcards (`*`) to use glob matching. +Blobs searches are performed on both filenames and contents. Search results: + +- Found in filenames are displayed before results found in contents. +- May contain multiple matches for the same blob because the search string + might be found in both the filename and content, or might appear multiple + times in the content. + ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation ``` Example response: diff --git a/doc/api/services.md b/doc/api/services.md index 741ea83070f..868bcdd07fc 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. | @@ -573,7 +573,7 @@ DELETE /projects/:id/services/jira ## Kubernetes -Kubernetes / Openshift integration +Kubernetes / OpenShift integration CAUTION: **Warning:** Kubernetes service integration has been deprecated in GitLab 10.3. API service endpoints will continue to work as long as the Kubernetes service is active, however if the service is inactive API endpoints will automatically return a `400 Bad Request`. Read [GitLab 10.3 release post](https://about.gitlab.com/2017/12/22/gitlab-10-3-released/#kubernetes-integration-service) for more information. @@ -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) @@ -639,7 +639,7 @@ Example response: "job_events": true, "pipeline_events": true, "properties": { - "token": "9koXpg98eAheJpvBs5tK" + "token": "<your_access_token>" } } ``` @@ -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 9b38e3a4eb7..c329e3cdf24 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -19,7 +19,7 @@ GET /application/settings ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings ``` Example response: @@ -75,7 +75,7 @@ PUT /application/settings ``` ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal ``` Example response: @@ -208,7 +208,7 @@ are listed in the descriptions of the relevant settings. | `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `sentry_dsn` | string | required by: `sentry_enabled` | Sentry Data Source Name. | -| `sentry_enabled` | boolean | no | (**If enabled, requires:** `sentry_dsn`) Sentry is an error reporting and logging tool which is currently not shipped with GitLab, available at https://getsentry.com. | +| `sentry_enabled` | boolean | no | (**If enabled, requires:** `sentry_dsn`) Sentry is an error reporting and logging tool which is currently not shipped with GitLab, available at <https://sentry.io>. | | `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. | diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index b9500916cf2..95dcf2d5277 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -15,7 +15,7 @@ GET /sidekiq/queue_metrics ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/sidekiq/queue_metrics +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/sidekiq/queue_metrics ``` Example response: @@ -40,7 +40,7 @@ GET /sidekiq/process_metrics ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/sidekiq/process_metrics +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/sidekiq/process_metrics ``` Example response: @@ -82,7 +82,7 @@ GET /sidekiq/job_stats ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/sidekiq/job_stats +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/sidekiq/job_stats ``` Example response: @@ -106,7 +106,7 @@ GET /sidekiq/compound_metrics ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/sidekiq/compound_metrics +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/sidekiq/compound_metrics ``` Example response: diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 7892866cd8e..2cbd041d132 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 -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/1 +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" 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: <your_access_token>" 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", @@ -184,7 +208,7 @@ Parameters: ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/snippets/1" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1" ``` upon successful delete a `204 No content` HTTP code shall be expected, with no data, @@ -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 -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1 +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1 ``` Example response: -``` json +```json [ { "author": { @@ -264,7 +288,7 @@ GET /snippets/:id/user_agent_detail | `id` | Integer | yes | The ID of a snippet | ```bash -curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail ``` Example response: diff --git a/doc/api/suggestions.md b/doc/api/suggestions.md new file mode 100644 index 00000000000..e88d536282a --- /dev/null +++ b/doc/api/suggestions.md @@ -0,0 +1,36 @@ +# Suggest Changes API + +Every API call to suggestions must be authenticated. + +## Applying suggestions + +Applies a suggested patch in a merge request. Users must be +at least [Developer](../user/permissions.md) to perform such action. + +``` +PUT /suggestions/:id/apply +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of a suggestion | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/suggestions/5/apply +``` + +Example response: + +```json + { + "id": 36, + "from_original_line": 10, + "to_original_line": 10, + "from_line": 10, + "to_line": 10, + "appliable": false, + "applied": true, + "from_content": " \"--talk-name=org.freedesktop.\",\n", + "to_content": " \"--talk-name=org.free.\",\n \"--talk-name=org.desktop.\",\n" + } +``` diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 7b8db6cfa8f..f8563e819db 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -20,7 +20,7 @@ GET /hooks Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/hooks +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks ``` Example response: @@ -63,7 +63,7 @@ POST /hooks Example request: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook" ``` Example response: @@ -96,7 +96,7 @@ GET /hooks/:id Example request: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/hooks/2 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks/2 ``` Example response: @@ -129,5 +129,5 @@ DELETE /hooks/:id Example request: ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/hooks/2 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/hooks/2 ```
\ No newline at end of file diff --git a/doc/api/tags.md b/doc/api/tags.md index f2a3f9f28d2..23dbf2d9ff7 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -17,6 +17,9 @@ Parameters: | `id` | integer/string| yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user| | `order_by` | string | no | Return tags ordered by `name` or `updated` fields. Default is `updated` | | `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of tags matching the search criteria | + +> Support for `search` was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54401) in GitLab 11.8. ```json [ @@ -65,7 +68,7 @@ Parameters: | `tag_name` | string | yes | The name of the tag | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0 ``` Example Response: @@ -134,7 +137,7 @@ Parameters: "description": "Amazing release. Wow" }, "name": "v1.0.0", - "target: "2695effb5807a22ff3d138d593fd856244e155e7", + "target": "2695effb5807a22ff3d138d593fd856244e155e7", "message": null } ``` diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index cecfc8cd9b9..11ec7360e06 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -120,6 +120,6 @@ Example response: ```json { "name": "Ruby", - "content": "# This file is a template, and might need editing before it works on your project.\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: \"ruby:2.3\"\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ce/ci/docker/using_docker_images.html#what-is-service\nservices:\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - gem install bundler --no-ri --no-rdoc # Bundler is not installed with the image\n - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - bundle exec rake db:migrate\n - bundle exec rake db:seed\n - bundle exec rake test\n" + "content": "# This file is a template, and might need editing before it works on your project.\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: \"ruby:2.5\"\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ce/ci/docker/using_docker_images.html#what-is-a-service\nservices:\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - rails db:migrate\n - rails db:seed\n - rails test\n\n# This deploy job uses a simple deploy flow to Heroku, other providers, e.g. AWS Elastic Beanstalk\n# are supported too: https://github.com/travis-ci/dpl\ndeploy:\n type: deploy\n environment: production\n script:\n - gem install dpl\n - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_PRODUCTION_KEY\n" } ``` diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index 8d1006e08c5..5feb1e498bd 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -116,7 +116,7 @@ If you omit the `fullname` parameter but authenticate your request, the name of the authenticated user will be used to replace the copyright holder placeholder. ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/templates/licenses/mit?project=My+Cool+Project ``` Example response: diff --git a/doc/api/todos.md b/doc/api/todos.md index 0843e4eedc6..c54c90d9f06 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -23,7 +23,7 @@ Parameters: | `type` | string | no | The type of a todo. Can be either `Issue` or `MergeRequest` | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos ``` Example Response: @@ -195,7 +195,7 @@ Parameters: | `id` | integer | yes | The ID of a todo | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos/130/mark_as_done +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos/130/mark_as_done ``` Example Response: @@ -285,8 +285,7 @@ POST /todos/mark_as_done ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/todos/donmark_as_donee +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos/mark_as_done ``` - [ce-3188]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3188 diff --git a/doc/api/users.md b/doc/api/users.md index 07f03f9c827..6000b9b900f 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 @@ -455,7 +458,7 @@ GET /user/status ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/user/status" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user/status" ``` Example response: @@ -510,7 +513,7 @@ PUT /user/status When both parameters `emoji` and `message` are empty, the status will be cleared. ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "emoji=coffee" --data "message=I crave coffee" https://gitlab.example.com/api/v4/user/status +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "emoji=coffee" --data "message=I crave coffee" https://gitlab.example.com/api/v4/user/status ``` Example responses @@ -676,7 +679,7 @@ GET /user/gpg_keys ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys ``` Example response: @@ -706,7 +709,7 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1 ``` Example response: @@ -734,7 +737,7 @@ Parameters: | key | string | yes | The new GPG key | ```bash -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys ``` Example response: @@ -764,7 +767,7 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1 ``` Returns `204 No Content` on success, or `404 Not found` if the key cannot be found. @@ -784,7 +787,7 @@ Parameters: | `id` | integer | yes | The ID of the user | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys ``` Example response: @@ -815,7 +818,7 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 ``` Example response: @@ -844,7 +847,7 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```bash -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys ``` Example response: @@ -875,7 +878,7 @@ Parameters: | `key_id` | integer | yes | The ID of the GPG key | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 ``` ## List emails @@ -1060,7 +1063,7 @@ Parameters: | `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens ``` Example response: @@ -1069,7 +1072,6 @@ Example response: [ { "active" : true, - "token" : "EsMo-vhKfXGwX9RKrwiy", "scopes" : [ "api" ], @@ -1086,7 +1088,6 @@ Example response: "read_user" ], "revoked" : true, - "token" : "ZcZRpLeEuQRprkRjYydY", "name" : "mytoken2", "created_at" : "2017-03-17T17:19:28.697Z", "id" : 3, @@ -1114,7 +1115,7 @@ Parameters: | `impersonation_token_id` | integer | yes | The ID of the impersonation token | ``` -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2 ``` Example response: @@ -1122,7 +1123,6 @@ Example response: ```json { "active" : true, - "token" : "EsMo-vhKfXGwX9RKrwiy", "scopes" : [ "api" ], @@ -1139,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 @@ -1158,7 +1160,7 @@ Parameters: | `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) | ``` -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens ``` Example response: @@ -1190,7 +1192,7 @@ DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id ``` ``` -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1 +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1 ``` Parameters: @@ -1225,7 +1227,7 @@ Parameters: | `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`. Defaults to 6 months ago. | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/activities ``` Example response: diff --git a/doc/api/version.md b/doc/api/version.md index 8b2a5b51bc5..ac19178b7ad 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -10,7 +10,7 @@ GET /version ``` ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/version +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/version ``` Example response: diff --git a/doc/api/wikis.md b/doc/api/wikis.md index fb0ec773da5..436d06cfd3a 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -18,7 +18,7 @@ GET /projects/:id/wikis | `with_content` | boolean | no | Include pages' content | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1 ``` Example response: @@ -59,20 +59,18 @@ GET /projects/:id/wikis/:slug | `slug` | string | yes | The slug (a unique string) of the wiki page | ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis/home +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/wikis/home ``` 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 @@ -91,7 +89,7 @@ POST /projects/:id/wikis | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | ```bash -curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis" +curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis" ``` Example response: @@ -123,7 +121,7 @@ PUT /projects/:id/wikis/:slug ```bash -curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" +curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" ``` Example response: @@ -151,7 +149,7 @@ DELETE /projects/:id/wikis/:slug | `slug` | string | yes | The slug (a unique string) of the wiki page | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" ``` On success the HTTP status code is `204` and no JSON response is expected. @@ -179,7 +177,7 @@ The `file=` parameter must point to a file on your filesystem and be preceded by `@`. For example: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "file=@dk.png" https://gitlab.example.com/api/v4/projects/1/wikis/attachments +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "file=@dk.png" https://gitlab.example.com/api/v4/projects/1/wikis/attachments ``` Example response: diff --git a/doc/ci/README.md b/doc/ci/README.md index dba1f38abe2..4e066a0df97 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -71,6 +71,7 @@ learn how to leverage its potential even more. - [Caching dependencies](caching/index.md) - [Git submodules](git_submodules.md) - How to run your CI jobs when Git submodules are involved +- [Pipelines for merge requests](merge_request_pipelines/index.md) - [Use SSH keys in your build environment](ssh_keys/README.md) - [Trigger pipelines through the GitLab API](triggers/README.md) - [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md) diff --git a/doc/ci/autodeploy/img/auto_deploy_btn.png b/doc/ci/autodeploy/img/auto_deploy_btn.png Binary files differdeleted file mode 100644 index ee88e5ce8c0..00000000000 --- a/doc/ci/autodeploy/img/auto_deploy_btn.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/auto_deploy_button.png b/doc/ci/autodeploy/img/auto_deploy_button.png Binary files differdeleted file mode 100644 index 0e84d9c57a1..00000000000 --- a/doc/ci/autodeploy/img/auto_deploy_button.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/auto_deploy_dropdown.png b/doc/ci/autodeploy/img/auto_deploy_dropdown.png Binary files differdeleted file mode 100644 index 4094f8ebb4e..00000000000 --- a/doc/ci/autodeploy/img/auto_deploy_dropdown.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/auto_monitoring.png b/doc/ci/autodeploy/img/auto_monitoring.png Binary files differdeleted file mode 100644 index 5a11923d199..00000000000 --- a/doc/ci/autodeploy/img/auto_monitoring.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/guide_connect_cluster.png b/doc/ci/autodeploy/img/guide_connect_cluster.png Binary files differdeleted file mode 100644 index 703d536f37a..00000000000 --- a/doc/ci/autodeploy/img/guide_connect_cluster.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/guide_integration.png b/doc/ci/autodeploy/img/guide_integration.png Binary files differdeleted file mode 100644 index ab72de2bba3..00000000000 --- a/doc/ci/autodeploy/img/guide_integration.png +++ /dev/null diff --git a/doc/ci/autodeploy/img/guide_secret.png b/doc/ci/autodeploy/img/guide_secret.png Binary files differdeleted file mode 100644 index 8469bee48b7..00000000000 --- a/doc/ci/autodeploy/img/guide_secret.png +++ /dev/null diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md index 3836216e951..985ec4b972c 100644 --- a/doc/ci/autodeploy/quick_start_guide.md +++ b/doc/ci/autodeploy/quick_start_guide.md @@ -1,95 +1 @@ -# Auto Deploy: quick start guide - -This is a step-by-step guide to deploying a project hosted on GitLab.com to Google Cloud, using Auto Deploy. - -We made a minimal [Ruby application](https://gitlab.com/gitlab-examples/minimal-ruby-app) to use as an example for this guide. It contains two files: - -* `server.rb` - our application. It will start an HTTP server on port 5000 and render “Hello, world!” -* `Dockerfile` - to build our app into a container image. It will use a ruby base image and run `server.rb` - -## Fork sample project on GitLab.com - -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. - -## 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. - -Visit the [`Kubernetes Engine`](https://console.cloud.google.com/kubernetes/list) tab and create a new cluster. You can change the name and leave the rest of the default settings. Once you have your cluster running, you need to connect to the cluster by following the Google interface. - -## Connect to Kubernetes cluster - -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` - -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`. - - - -## Copy credentials to GitLab.com project - -Once you have the Kubernetes Dashboard interface running, you should visit `Secrets` under the `Config` section. There you should find the settings we need for GitLab integration: ca.crt and token. - - - -You need to copy-paste the ca.crt and token into your project on GitLab.com in the Kubernetes integration page under project `Settings` > `Integrations` > `Project services` > `Kubernetes`. Don't actually copy the namespace though. Each project should have a unique namespace, and by leaving it blank, GitLab will create one for you. - - - -For API URL, you should use the `Endpoint` IP from your cluster page on Google Cloud Platform. - -## Expose the application to the internet - -In order to be able to visit your application, you need to install an NGINX ingress controller and point your domain name to its external IP address. - -### Set up Ingress controller - -You’ll need to make sure you have an ingress controller. If you don’t have one, do: - -```sh -brew install kubernetes-helm -helm init -helm install --name ruby-app stable/nginx-ingress -``` - -This should create several services including `ruby-app-nginx-ingress-controller`. You can list your services by running `kubectl get svc` to confirm that. - -### Point DNS at Cluster IP - -Find out the external IP address of the `ruby-app-nginx-ingress-controller` by running: - -```sh -kubectl get svc ruby-app-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` - -Use this IP address to configure your DNS. This part heavily depends on your preferences and domain provider. But in case you are not sure, just create an A record with a wildcard host like `*.<your-domain>` pointing to the external IP address you found above. - -Use `nslookup minimal-ruby-app-staging.<yourdomain>` to confirm that domain is assigned to the cluster IP. - -## Set up Auto Deploy - -Visit the home page of your GitLab.com project and press "Set up Auto Deploy" button. - - - -You will be redirected to the "New file" page where you can apply one of the Auto Deploy templates. Select "Kubernetes" to apply the template, then in the file, replace `domain.example.com` with your domain name and make any other adjustments you need. - - - -Change the target branch to `master`, and submit your changes. This should create -a new pipeline with several jobs. If you made only the domain name change, the -pipeline will have three jobs: `build`, `staging`, and `production`. - -The `build` job will create a Docker image with your new change and push it to -the GitLab Container Registry. The `staging` job will deploy this image on your -cluster. Once the deploy job succeeds you should be able to see your application by -visiting the Kubernetes dashboard. Select the namespace of your project, which -will look like `ruby-autodeploy-23`, but with a unique ID for your project, and -your app will be listed as "staging" under the "Deployment" tab. - -Once its ready - just visit http://minimal-ruby-app-staging.yourdomain.com to see “Hello, world!” +This document was moved to [another location](../../topics/autodevops/index.md#auto-deploy). diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 758ab37861b..8b2ce425cf5 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -29,8 +29,8 @@ needed to compile the project: Cache was designed to be used to speed up invocations of subsequent runs of a given job, by keeping things like dependencies (e.g., npm packages, Go vendor packages, etc.) so they don't have to be re-fetched from the public internet. - While the cache can be abused to pass intermediate build results between stages, - there may be cases where artifacts are a better fit. + While the cache can be abused to pass intermediate build results between + stages, there may be cases where artifacts are a better fit. - `artifacts`: **Use for stage results that will be passed between stages.** Artifacts were designed to upload some compiled/generated bits of the build, and they can be fetched by any number of concurrent Runners. They are @@ -39,11 +39,13 @@ needed to compile the project: directories relative to the build directory** and specifying paths which don't comply to this rule trigger an unintuitive and illogical error message (an enhancement is discussed at - https://gitlab.com/gitlab-org/gitlab-ce/issues/15530). Artifacts need to be - uploaded to the GitLab instance (not only the GitLab runner) before the next - stage job(s) can start, so you need to evaluate carefully whether your - bandwidth allows you to profit from parallelization with stages and shared - artifacts before investing time in changes to the setup. + [https://gitlab.com/gitlab-org/gitlab-ce/issues/15530](https://gitlab.com/gitlab-org/gitlab-ce/issues/15530) + ). Artifacts need to be uploaded to the GitLab instance (not only the GitLab + runner) before the next stage job(s) can start, so you need to evaluate + carefully whether your bandwidth allows you to profit from parallelization + with stages and shared artifacts before investing time in changes to the + setup. + It's sometimes confusing because the name artifact sounds like something that is only useful outside of the job, like for downloading a final image. But @@ -88,7 +90,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: that will be only available to a particular project. - [Use a `key`](../yaml/README.md#cache-key) that fits your workflow (e.g., different caches on each branch). For that, you can take advantage of the - [CI/CD predefined variables](../variables/README.md#predefined-variables-environment-variables). + [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). TIP: **Tip:** Using the same Runner for your pipeline, is the most simple and efficient way to @@ -298,7 +300,6 @@ cache: before_script: - ruby -v # Print out ruby version for debugging - - gem install bundler --no-ri --no-rdoc # Bundler is not installed with the image - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby rspec: diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 0b64c8caba7..a462c75f2f5 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. @@ -194,7 +194,7 @@ not without its own challenges: - docker run -v "$MOUNT_POINT:/mnt" my-docker-image ``` -An example project using this approach can be found here: https://gitlab.com/gitlab-examples/docker. +An example project using this approach can be found here: <https://gitlab.com/gitlab-examples/docker>. ### Use Docker socket binding @@ -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 @@ -467,11 +521,11 @@ stages: variables: DOCKER_HOST: tcp://docker:2375 DOCKER_DRIVER: overlay2 - CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project/my-image:$CI_COMMIT_REF_SLUG - CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project/my-image:latest + CONTAINER_TEST_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG + CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest before_script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY build: stage: build @@ -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 31649ee2792..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). diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index 7d4f28e1f47..f354cdb398e 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -39,8 +39,8 @@ 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 -[environment variables](../variables/README.md#predefined-variables-environment-variables) +`/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the +[environment variables](../variables/README.md#predefined-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 project's Container Registry while tagging it with the Git tag: @@ -52,9 +52,31 @@ 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 ``` + +## Using a registry with a custom certificate + +When trying to push to a Docker registry that uses a certificate that is signed +by a custom CA, you might get the following error: + +```sh +$ /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --no-push +INFO[0000] Downloading base image registry.gitlab.example.com/group/docker-image +error building image: getting stage builder for stage 0: Get https://registry.gitlab.example.com/v2/: x509: certificate signed by unknown authority +``` + +This can be solved by adding your CA's certificate to the kaniko certificate +store: + +```yaml + before_script: + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - | + echo "-----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE-----" >> /kaniko/ssl/certs/ca-certificates.crt +``` diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 4d740c32fd6..6a9917f6430 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -249,7 +249,7 @@ the basis of [Review apps](review_apps/index.md). NOTE: **Note:** The `name` and `url` parameters can use most of the CI/CD variables, -including [predefined](variables/README.md#predefined-variables-environment-variables), +including [predefined](variables/README.md#predefined-environment-variables), [project/group ones](variables/README.md#variables) and [`.gitlab-ci.yml` variables](yaml/README.md#variables). You however cannot use variables defined under `script` or on the Runner's side. There are also other variables that @@ -416,63 +416,15 @@ 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. +With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly +from source files to public pages on the environment set for Review Apps. -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 | -| ------ | ------ | -|  |  | - -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): - -```yaml -# Team data -- source: 'data/team.yml' # data/team.yml - public: 'team/' # team/ - -# Blogposts -- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb - public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/ - -# HTML files -- source: /source\/(.+?\.html).*/ # source/index.html.haml - public: '\1' # index.html - -# Other files -- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png - public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png -``` - -Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys: - -- `source` - - a string, starting and ending with `'`, for an exact match - - a regular expression, starting and ending with `/`, for a pattern match - - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. - - Can include capture groups denoted by `()` that can be referred to in the `public` path. - - Slashes (`/`) can, but don't have to, be escaped as `\/`. - - Literal periods (`.`) should be escaped as `\.`. -- `public` - - a string, starting and ending with `'`. - - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. - -The public path for a source path is determined by finding the first `source` expression that matches it, and returning the corresponding `public` path, replacing the `\N` expressions with the values of the `()` capture groups if appropriate. - -In the example above, the fact that mappings are evaluated in order of their definition is used to ensure that `source/index.html.haml` will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, and will result in a public path of `index.html`, instead of `index.html.haml`. - ---- - -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 -is a single workflow, but imagine tens of developers working on a project -at the same time. They each push to their branches, and dynamic environments are -created all the time. In that case, we probably need to do some clean up. Read +From then on, you have a full development cycle, where your 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. This is a simple workflow, +but when you have multiple developers working on a project +at the same time, each of them pushing to their own branches, dynamic environments are +created all the time. In which case, you probably want to do some clean up. Read next how environments can be stopped. ## Stopping an environment @@ -568,13 +520,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 fdf09d332a5..a8c119edaa0 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -9,7 +9,7 @@ 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 diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 9657f52159e..9e657275d50 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. @@ -107,7 +107,7 @@ Now it's time we set up [GitLab CI/CD](https://about.gitlab.com/features/gitlab- GitLab CI/CD uses a file in the root of the repo, named `.gitlab-ci.yml`, to read the definitions for jobs that will be executed by the configured GitLab Runners. You can read more about this file in the [GitLab Documentation](https://docs.gitlab.com/ee/ci/yaml/). -First of all, remember to set up variables for your deployment. Navigate to your project's **Settings > CI/CD > Variables** page +First of all, remember to set up variables for your deployment. Navigate to your project's **Settings > CI/CD > Environment variables** page and add the following ones (replace them with your current values, of course): - **MAVEN_REPO_URL**: `http://artifactory.example.com:8081/artifactory` (your Artifactory URL) diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index d36e97ebfd3..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-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..31c3df81fef 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: @@ -15,7 +22,7 @@ container_scanning: 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 + ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG CI_APPLICATION_TAG: $CI_COMMIT_SHA allow_failure: true @@ -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-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..e76767741ce --- /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..6499413baf0 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` @@ -104,12 +104,12 @@ to ensure our deployments only happen when we push to the master branch. 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) +variables](../../variables/README.md#predefined-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 @@ -138,5 +138,5 @@ buildpack: client-certificate-mapper=1.2.0_RELEASE container-security-provider=1 ``` You can then visit your deployed application (for this example, -https://gitlab-hello-world-undissembling-hotchpot.cfapps.io/) and you should +`https://gitlab-hello-world-undissembling-hotchpot.cfapps.io/`) and you should see the "Spring is here!" message. diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index f53f7c50281..010ba6b66a2 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -6,7 +6,7 @@ used with GitLab CI. >**Note:** We recommend to use Dpl if you're deploying to any of these services: -https://github.com/travis-ci/dpl#supported-providers. +<https://github.com/travis-ci/dpl#supported-providers>. ## Requirements @@ -34,7 +34,7 @@ The Dpl provides support for vast number of services, including: Heroku, Cloud F To use it simply define provider and any additional parameters required by the provider. For example if you want to use it to deploy your application to heroku, you need to specify `heroku` as provider, specify `api-key` and `app`. -There's more and all possible parameters can be found here: https://github.com/travis-ci/dpl#heroku +There's more and all possible parameters can be found here: <https://github.com/travis-ci/dpl#heroku>. ```yaml staging: @@ -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 b75ed87bc91..1e2be2e8475 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 @@ -254,7 +254,7 @@ To ensure our changes don't break the build and all tests still pass, we utilize Continuous Integration (CI) to run these checks automatically for every push. Read through this article to understand [Continuous Integration, Continuous Delivery, and Continuous Deployment](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/), and how these methods are leveraged by GitLab. -From the [last tutorial](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) we already have a `gitlab-ci.yml` file set up for building our app from +From the [last tutorial](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) we already have a `.gitlab-ci.yml` file set up for building our app from every push. We need to set up a new CI job for testing, which GitLab CI/CD will run after the build job using our generated artifacts from gulp. Please read through the [documentation on CI/CD configuration](../../../ci/yaml/README.md) file to explore its contents and adjust it to your needs. @@ -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 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..4675e20ef79 --- /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 70020d461d9..b1ccce744d8 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -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') @@ -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 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..61bf68fa0e8 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. +You'll need to create two variables in **Settings > CI/CD > Environment variables** in your GitLab project: + +- `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..46e6efccaf8 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**: +You'll need to create two variables in your project's **Settings > CI/CD > Environment 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 b3961ec91f3..66bfa41cad9 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -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/pipelines-goal.png b/doc/ci/img/pipelines-goal.png Binary files differnew file mode 100644 index 00000000000..f15716d0b8f --- /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..829a53d5d52 --- /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 differdeleted file mode 100644 index dd9ca40280a..00000000000 --- a/doc/ci/img/view_on_env_blob.png +++ /dev/null diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 1ddc1bf4d7e..2a4160f62b0 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,22 +1,26 @@ -# Getting started with interactive web terminals +# Interactive Web Terminals > [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-off commands for their CI pipeline. +running one-off commands for their CI pipeline. Since this is giving the user +shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) +is deployed, some [security precautions](../../administration/integration/terminal.md#security) were +taken to protect the users. 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). +[Shared runners on GitLab.com](../quick_start/README.md#shared-runners) do not +provide an interactive web terminal. Follow [this +issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611) for progress on +adding support. For groups and projects hosted on GitLab.com, interactive web +terminals are available when using your own group or project runner. ## Configuration Two things need to be configured for the interactive web terminal to work: - The Runner needs to have [`[session_server]` configured - properly][session-server] + properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) - 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) @@ -46,9 +50,7 @@ the terminal and type commands like a normal shell. If you have the terminal open and the job has finished with its tasks, the terminal will block the job from finishing for the duration configured in -[`[session_server].terminal_max_retention_time`][session-server] until you +[`[session_server].terminal_max_retention_time`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you close the terminal window.  - -[session-server]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index 3fd54647abb..cf18c6d9660 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`: @@ -147,7 +151,7 @@ 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`), +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. @@ -167,4 +171,4 @@ Currently, the following tools might not work because their XML formats are unsu |Case|Tool|Issue| |---|---|---| -|`<testcase>` does not have `classname` attribute|ESlint, sass-lint|https://gitlab.com/gitlab-org/gitlab-ce/issues/50964| +|`<testcase>` does not have `classname` attribute|ESlint, sass-lint|<https://gitlab.com/gitlab-org/gitlab-ce/issues/50964>| diff --git a/doc/ci/merge_request_pipelines/img/merge_request.png b/doc/ci/merge_request_pipelines/img/merge_request.png Binary files differnew file mode 100644 index 00000000000..cf9c628e9a0 --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/merge_request.png diff --git a/doc/ci/merge_request_pipelines/img/pipeline_detail.png b/doc/ci/merge_request_pipelines/img/pipeline_detail.png Binary files differnew file mode 100644 index 00000000000..6094a0975fb --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/pipeline_detail.png diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md new file mode 100644 index 00000000000..bf1e61442d4 --- /dev/null +++ b/doc/ci/merge_request_pipelines/index.md @@ -0,0 +1,83 @@ +# Pipelines for merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6. + +Usually, when you create a new merge request, a pipeline runs on the +new change and checks if it's qualified to be merged into a target branch. This +pipeline should contain only necessary jobs for checking the new changes. +For example, unit tests, lint checks, and [Review Apps](../review_apps/index.md) +are often used in this cycle. + +With pipelines for merge requests, you can design a specific pipeline structure +for merge requests. All you need to do is just adding `only: [merge_requests]` to +the jobs that you want it to run for only merge requests. +Every time, when developers create or update merge requests, a pipeline runs on +their new commits at every push to GitLab. + +NOTE: **Note**: +If you use both this feature and [Merge When Pipeline Succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md), +pipelines for merge requests take precedence over the other regular pipelines. + +For example, consider the following [`.gitlab-ci.yml`](../yaml/README.md): + +```yaml +build: + stage: build + script: ./build + only: + - branches + - tags + - merge_requests + +test: + stage: test + script: ./test + only: + - merge_requests + +deploy: + stage: deploy + script: ./deploy +``` + +After the merge request is updated with new commits, GitLab detects that changes +have occurred and creates a new pipeline for the merge request. +The pipeline fetches the latest code from the source branch and run tests against it. +In the above example, the pipeline contains only `build` and `test` jobs. +Since the `deploy` job doesn't have the `only: [merge_requests]` rule, +deployment jobs will not happen in the merge request. + +Pipelines tagged as **merge request** indicate that they were triggered +when a merge request was created or updated. + + + +The same tag is shown on the pipeline's details: + + + +## Important notes about merge requests from forked projects + +Note that the current behavior is subject to change. In the usual contribution +flow, external contributors follow the following steps: + +1. Fork a parent project. +1. Create a merge request from the forked project that targets the `master` branch +in the parent project. +1. A pipeline runs on the merge request. +1. A maintainer from the parent project checks the pipeline result, and merge +into a target branch if the latest pipeline has passed. + +Currently, those pipelines are created in a **forked** project, not in the +parent project. This means you cannot completely trust the pipeline result, +because, technically, external contributors can disguise their pipeline results +by tweaking their GitLab Runner in the forked project. + +There are multiple reasons about why GitLab doesn't allow those pipelines to be +created in the parent project, but one of the biggest reasons is security concern. +External users could steal secret variables from the parent project by modifying +`.gitlab-ci.yml`, which could be some sort of credentials. This should not happen. + +We're discussing a secure solution of running pipelines for merge requests +that submitted from forked projects, +see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-ce/issues/23902). diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 371703a12c8..d2a00b9218d 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 @@ -241,9 +241,9 @@ So each job would be represented as a `Period`, which consists of `Period#first` as when the job started and `Period#last` as when the job was finished. A simple example here would be: -* A (1, 3) -* B (2, 4) -* C (6, 7) +- A (1, 3) +- B (2, 4) +- C (6, 7) Here A begins from 1, and ends to 3. B begins from 2, and ends to 4. C begins from 6, and ends to 7. Visually it could be viewed as: @@ -294,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..1ec8a8c89c9 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -77,7 +77,7 @@ before_script: - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs - ruby -v - which ruby - - gem install bundler --no-ri --no-rdoc + - gem install bundler --no-document - bundle install --jobs $(nproc) "${FLAGS[@]}" rspec: @@ -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/view_on_env_blob.png b/doc/ci/review_apps/img/view_on_env_blob.png Binary files differnew file mode 100644 index 00000000000..acc457fbb38 --- /dev/null +++ b/doc/ci/review_apps/img/view_on_env_blob.png diff --git a/doc/ci/img/view_on_env_mr.png b/doc/ci/review_apps/img/view_on_env_mr.png Binary files differindex 2c0bd25a4f2..2c0bd25a4f2 100644 --- a/doc/ci/img/view_on_env_mr.png +++ b/doc/ci/review_apps/img/view_on_env_mr.png diff --git a/doc/ci/review_apps/img/view_on_mr_widget.png b/doc/ci/review_apps/img/view_on_mr_widget.png Binary files differnew file mode 100644 index 00000000000..efe023b07b5 --- /dev/null +++ b/doc/ci/review_apps/img/view_on_mr_widget.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 64be011008e..8b3a7b63e62 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -102,3 +102,88 @@ The following are example projects that use Review Apps with: - [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. + +## Route Maps + +> Introduced in GitLab 8.17. In GitLab 11.5 the file links +are surfaced to the merge request widget. + +Route Maps allows you to go directly from source files +to public pages on the [environment](../environments.md) defined for +Review Apps. Once set up, the review app link in the merge request +widget can take you directly to the pages changed, making it easier +and faster to preview proposed modifications. + +All you need to do is to tell GitLab how the paths of files +in your repository map to paths of pages on your website using a Route Map. +Once set, GitLab will display **View on ...** buttons, which will take you +to the pages changed directly from merge requests. + +To set up a route map, add a 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). + +### Route Maps example + +Below there's an example of a route map for [Middleman](https://middlemanapp.com), +a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com), +deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com): + +```yaml +# Team data +- source: 'data/team.yml' # data/team.yml + public: 'team/' # team/ + +# Blogposts +- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/ # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb + public: '\1/\2/\3/\4/' # 2017/01/30/around-the-world-in-6-releases/ + +# HTML files +- source: /source\/(.+?\.html).*/ # source/index.html.haml + public: '\1' # index.html + +# Other files +- source: /source\/(.*)/ # source/images/blogimages/around-the-world-in-6-releases-cover.png + public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png +``` + +Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys: + +- `source` + - a string, starting and ending with `'`, for an exact match + - a regular expression, starting and ending with `/`, for a pattern match + - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. + - Can include capture groups denoted by `()` that can be referred to in the `public` path. + - Slashes (`/`) can, but don't have to, be escaped as `\/`. + - Literal periods (`.`) should be escaped as `\.`. +- `public` + - a string, starting and ending with `'`. + - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. + +The public path for a source path is determined by finding the first +`source` expression that matches it, and returning the corresponding +`public` path, replacing the `\N` expressions with the values of the +`()` capture groups if appropriate. + +In the example above, the fact that mappings are evaluated in order +of their definition is used to ensure that `source/index.html.haml` +will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, +and will result in a public path of `index.html`, instead of +`index.html.haml`. + +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. + +  diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 83e0fa34ad6..c742dc61368 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -135,12 +135,20 @@ Consider that if you don't lock your specific Runner to a specific project, any user with Maintainer role in you project can assign your Runner to another arbitrary project without requiring your authorization, so use it with caution. +CAUTION: **Caution:** +Never add a private Runner that you're using in your private projects to a +project that you share with other people. + +CAUTION: **Caution:** +Never use a Runner from a project which has multiple maintainers in your +private project. + 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 @@ -312,7 +320,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..2902c30c7c0 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -16,7 +16,7 @@ services: - mysql:latest variables: - # Configure mysql environment variables (https://hub.docker.com/r/_/mysql/) + # Configure mysql environment variables (https://hub.docker.com/_/mysql/) MYSQL_DATABASE: el_duderino MYSQL_ROOT_PASSWORD: mysql_strong_password ``` @@ -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`. @@ -114,5 +114,5 @@ available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit and push your changes. Within a few moments the changes will be picked by a public runner and the job will begin. -[hub-mysql]: https://hub.docker.com/r/_/mysql/ +[hub-mysql]: https://hub.docker.com/_/mysql/ [mysql-example-repo]: https://gitlab.com/gitlab-examples/mysql 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 bffb0121603..61037360326 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -148,7 +148,7 @@ file. The parameter is of the form: variables[key]=value ``` -This information is also exposed in the UI. +This information is also exposed in the UI. Please note that _values_ are only viewable by Owners and Maintainers.  @@ -172,6 +172,7 @@ stages: - package run_tests: + stage: test script: - make test @@ -223,5 +224,5 @@ removed with one of the future versions of GitLab. You are advised to [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 [ee]: https://about.gitlab.com/pricing/ [variables]: ../variables/README.md -[predef]: ../variables/README.md#predefined-variables-environment-variables +[predef]: ../variables/README.md#predefined-environment-variables [registry]: ../../user/project/container_registry.md diff --git a/doc/ci/triggers/img/trigger_variables.png b/doc/ci/triggers/img/trigger_variables.png Binary files differindex 0c2a761cfa9..d273b1fe3a2 100644 --- a/doc/ci/triggers/img/trigger_variables.png +++ b/doc/ci/triggers/img/trigger_variables.png diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 2d23bf6d2fd..97e133a2e2f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,26 +1,36 @@ +--- +table_display_block: true +--- + # GitLab CI/CD Variables -When receiving a job from GitLab CI, the [Runner] prepares the build environment. -It starts by setting a list of **predefined variables** (environment variables) -and a list of **user-defined variables**. +When receiving a job from GitLab CI, the [Runner](https://docs.gitlab.com/runner/) prepares the build environment. +It starts by setting a list of: + +- [Predefined environment variables](#predefined-environment-variables). +- Other variables. ## Priority of variables -The variables can be overwritten and they take precedence over each other in -this order: +Variables of different types can take precedence over other variables, depending on where they are defined. + +The order of precedence for variables is (from highest to lowest): + +1. [Trigger variables](../triggers/README.md#pass-job-variables-to-a-trigger) or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables). +1. Project-level [variables](#variables) or [protected variables](#protected-variables). +1. Group-level [variables](#variables) or [protected variables](#protected-variables). +1. YAML-defined [job-level variables](../yaml/README.md#variables). +1. YAML-defined [global variables](../yaml/README.md#variables). +1. [Deployment variables](#deployment-variables). +1. [Predefined environment variables](#predefined-environment-variables). -1. [Trigger variables][triggers] or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables) (take precedence over all) -1. Project-level [variables](#variables) or [protected variables](#protected-variables) -1. Group-level [variables](#variables) or [protected variables](#protected-variables) -1. YAML-defined [job-level variables](../yaml/README.md#variables) -1. YAML-defined [global variables](../yaml/README.md#variables) -1. [Deployment variables](#deployment-variables) -1. [Predefined variables](#predefined-variables-environment-variables) (are the - lowest in the chain) +For example, you define: -For example, if you define `API_TOKEN=secure` as a project variable and -`API_TOKEN=yaml` in your `.gitlab-ci.yml`, the `API_TOKEN` will take the value -`secure` as the project variables are higher in the chain. +- `API_TOKEN=secure` as a project variable. +- `API_TOKEN=yaml` in your `.gitlab-ci.yml`. + +`API_TOKEN` will take the value `secure` as the project variables take precedence over those defined +in `.gitlab-ci.yml`. ## Unsupported variables @@ -28,10 +38,10 @@ There are cases where some variables cannot be used in the context of a `.gitlab-ci.yml` definition (for example under `script`). Read more about which variables are [not supported](where_variables_can_be_used.md). -## Predefined variables (Environment variables) +## Predefined environment variables Some of the predefined environment variables are available only if a minimum -version of [GitLab Runner][runner] is used. Consult the table below to find the +version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the version of Runner required. NOTE: **Note:** @@ -40,73 +50,90 @@ Starting with GitLab 9.0, we have deprecated some variables. Read the strongly advised to use the new variables as we will remove the old ones in future GitLab releases.** -| Variable | GitLab | Runner | Description | -|-------------------------------- |--------|--------|-------------| -| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job | -| **CI** | all | 0.4 | Mark that job is executed in CI environment | -| **CI_COMMIT_REF_NAME** | 9.0 | all | The branch or tag name for which project is built | -| **CI_COMMIT_REF_SLUG** | 9.0 | all | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | -| **CI_COMMIT_SHA** | 9.0 | all | The commit revision for which project is built | -| **CI_COMMIT_BEFORE_SHA** | 11.2 | all | The previous latest commit present on a branch before a push request. | -| **CI_COMMIT_TAG** | 9.0 | 0.5 | The commit tag name. Present only when building tags. | -| **CI_COMMIT_MESSAGE** | 10.8 | all | The full commit message. | -| **CI_COMMIT_TITLE** | 10.8 | all | The title of the commit - the full first line of the message | -| **CI_COMMIT_DESCRIPTION** | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | -| **CI_CONFIG_PATH** | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | -| **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | -| **CI_DEPLOY_USER** | 10.8 | all | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| -| **CI_DEPLOY_PASSWORD** | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| -| **CI_DISPOSABLE_ENVIRONMENT** | all | 10.1 | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | -| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job | -| **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. | -| **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job | -| **CI_JOB_ID** | 9.0 | all | The unique id of the current job that GitLab CI uses internally | -| **CI_JOB_MANUAL** | 8.12 | all | The flag to indicate that job was manually started | -| **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_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 | -| **CI_RUNNER_ID** | 8.10 | 0.5 | The unique id of runner being used | -| **CI_RUNNER_TAGS** | 8.10 | 0.5 | The defined runner tags | -| **CI_RUNNER_VERSION** | all | 10.6 | GitLab Runner version that is executing the current job | -| **CI_RUNNER_REVISION** | all | 10.6 | GitLab Runner revision that is executing the current job | -| **CI_RUNNER_EXECUTABLE_ARCH** | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) | -| **CI_PIPELINE_ID** | 8.10 | 0.5 | The unique id of the current pipeline that GitLab CI uses internally | -| **CI_PIPELINE_IID** | 11.0 | all | The unique id of the current pipeline scoped to project | -| **CI_PIPELINE_TRIGGERED** | all | all | The flag to indicate that job was [triggered] | -| **CI_PIPELINE_SOURCE** | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` | -| **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run | -| **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally | -| **CI_PROJECT_NAME** | 8.10 | 0.5 | The project name that is currently being built (actually it is project folder name) | -| **CI_PROJECT_NAMESPACE** | 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built | -| **CI_PROJECT_PATH** | 8.10 | 0.5 | The namespace with project name | -| **CI_PROJECT_PATH_SLUG** | 9.3 | all | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | -| **CI_PIPELINE_URL** | 11.1 | 0.5 | Pipeline details URL | -| **CI_PROJECT_URL** | 8.10 | 0.5 | The HTTP address to access project | -| **CI_PROJECT_VISIBILITY** | 10.3 | all | The project visibility (internal, private, public) | -| **CI_REGISTRY** | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry | -| **CI_REGISTRY_IMAGE** | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project | -| **CI_REGISTRY_PASSWORD** | 9.0 | all | The password to use to push containers to the GitLab Container Registry | -| **CI_REGISTRY_USER** | 9.0 | all | The username to use to push containers to the GitLab Container Registry | -| **CI_SERVER** | all | all | Mark that job is executed in CI environment | -| **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 | -| **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the job | -| **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the job | -| **GITLAB_USER_LOGIN** | 10.0 | all | The login username of the user who started the job | -| **GITLAB_USER_NAME** | 10.0 | all | The real name of the user who started the job | -| **RESTORE_CACHE_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to restore the cache running a job | - -## 9.0 Renaming +| Variable | GitLab | Runner | Description | +|-------------------------------------------|--------|--------|-------------| +| **ARTIFACT_DOWNLOAD_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to download artifacts running a job | +| **CI** | all | 0.4 | Mark that job is executed in CI environment | +| **CI_COMMIT_BEFORE_SHA** | 11.2 | all | The previous latest commit present on a branch before a push request. | +| **CI_COMMIT_DESCRIPTION** | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | +| **CI_COMMIT_MESSAGE** | 10.8 | all | The full commit message. | +| **CI_COMMIT_REF_NAME** | 9.0 | all | The branch or tag name for which project is built | +| **CI_COMMIT_REF_SLUG** | 9.0 | all | `$CI_COMMIT_REF_NAME` lowercased, shortened to 63 bytes, and with everything except `0-9` and `a-z` replaced with `-`. No leading / trailing `-`. Use in URLs, host names and domain names. | +| **CI_COMMIT_SHA** | 9.0 | all | The commit revision for which project is built | +| **CI_COMMIT_SHORT_SHA** | 11.7 | all | The first eight characters of `CI_COMMIT_SHA` | +| **CI_COMMIT_TAG** | 9.0 | 0.5 | The commit tag name. Present only when building tags. | +| **CI_COMMIT_TITLE** | 10.8 | all | The title of the commit - the full first line of the message | +| **CI_CONFIG_PATH** | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | +| **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | +| **CI_DEPLOY_PASSWORD** | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| +| **CI_DEPLOY_USER** | 10.8 | all | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| +| **CI_DISPOSABLE_ENVIRONMENT** | all | 10.1 | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | +| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmenturl) is set. | +| **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. | +| **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job. Only present if [`environment:url`](../yaml/README.md#environmenturl) is set. | +| **CI_JOB_ID** | 9.0 | all | The unique id of the current job that GitLab CI uses internally | +| **CI_JOB_MANUAL** | 8.12 | all | The flag to indicate that job was manually started | +| **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_JOB_URL** | 11.1 | 0.5 | Job details URL | +| **CI_MERGE_REQUEST_ID** | 11.6 | all | The ID of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_IID** | 11.6 | all | The IID of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_PROJECT_ID** | 11.6 | all | The ID of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_PROJECT_PATH** | 11.6 | all | The path of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`) | +| **CI_MERGE_REQUEST_PROJECT_URL** | 11.6 | all | The URL of the project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`) | +| **CI_MERGE_REQUEST_REF_PATH** | 11.6 | all | The ref path of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`) | +| **CI_MERGE_REQUEST_SOURCE_BRANCH_NAME** | 11.6 | all | The source branch name of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_SOURCE_PROJECT_ID** | 11.6 | all | The ID of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_SOURCE_PROJECT_PATH** | 11.6 | all | The path of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_SOURCE_PROJECT_URL** | 11.6 | all | The URL of the source project of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **CI_MERGE_REQUEST_TARGET_BRANCH_NAME** | 11.6 | all | The target branch name of the merge request if it's [pipelines for merge requests](../merge_request_pipelines/index.md) | +| **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_API_V4_URL** | 11.7 | all | The GitLab API v4 root URL | +| **CI_PAGES_DOMAIN** | 11.8 | all | The configured domain that hosts GitLab Pages. | +| **CI_PAGES_URL** | 11.8 | all | URL to GitLab Pages-built pages. Always belongs to a subdomain of `CI_PAGES_DOMAIN`. | +| **CI_PIPELINE_ID** | 8.10 | all | The unique id of the current pipeline that GitLab CI uses internally | +| **CI_PIPELINE_IID** | 11.0 | all | The unique id of the current pipeline scoped to project | +| **CI_PIPELINE_SOURCE** | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` | +| **CI_PIPELINE_TRIGGERED** | all | all | The flag to indicate that job was [triggered] | +| **CI_PIPELINE_URL** | 11.1 | 0.5 | Pipeline details URL | +| **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run | +| **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally | +| **CI_PROJECT_NAME** | 8.10 | 0.5 | The project name that is currently being built (actually it is project folder name) | +| **CI_PROJECT_NAMESPACE** | 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built | +| **CI_PROJECT_PATH** | 8.10 | 0.5 | The namespace with project name | +| **CI_PROJECT_PATH_SLUG** | 9.3 | all | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | +| **CI_PROJECT_URL** | 8.10 | 0.5 | The HTTP(S) address to access project | +| **CI_PROJECT_VISIBILITY** | 10.3 | all | The project visibility (internal, private, public) | +| **CI_REGISTRY** | 8.10 | 0.5 | If the Container Registry is enabled it returns the address of GitLab's Container Registry | +| **CI_REGISTRY_IMAGE** | 8.10 | 0.5 | If the Container Registry is enabled for the project it returns the address of the registry tied to the specific project | +| **CI_REGISTRY_PASSWORD** | 9.0 | all | The password to use to push containers to the GitLab Container Registry | +| **CI_REGISTRY_USER** | 9.0 | all | The username to use to push containers to the GitLab Container Registry | +| **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 | +| **CI_RUNNER_EXECUTABLE_ARCH** | all | 10.6 | The OS/architecture of the GitLab Runner executable (note that this is not necessarily the same as the environment of the executor) | +| **CI_RUNNER_ID** | 8.10 | 0.5 | The unique id of runner being used | +| **CI_RUNNER_REVISION** | all | 10.6 | GitLab Runner revision that is executing the current job | +| **CI_RUNNER_TAGS** | 8.10 | 0.5 | The defined runner tags | +| **CI_RUNNER_VERSION** | all | 10.6 | GitLab Runner version that is executing the current job | +| **CI_SERVER** | all | all | Mark that job is executed in CI environment | +| **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 | +| **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the job | +| **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the job | +| **GITLAB_USER_LOGIN** | 10.0 | all | The login username of the user who started the job | +| **GITLAB_USER_NAME** | 10.0 | all | The real name of the user who started the job | +| **RESTORE_CACHE_ATTEMPTS** | 8.15 | 1.9 | Number of attempts to restore the cache running a job | + +## GitLab 9.0 renaming To follow conventions of naming across GitLab, and to further move away from the `build` term and toward `job` CI variables have been renamed for the 9.0 @@ -135,11 +162,11 @@ future GitLab releases.** ## `.gitlab-ci.yml` defined variables NOTE **Note:** -This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher. +This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher. GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the build environment. The variables are hence saved in the repository, and they -are meant to store non-sensitive project configuration, e.g., `RAILS_ENV` or +are meant to store non-sensitive project configuration. For example, `RAILS_ENV` or `DATABASE_URL`. For example, if you set the variable below globally (not inside a job), it will @@ -174,8 +201,7 @@ script: ## Variables -NOTE: **Note:** -Group-level variables were added in GitLab 9.4. +> Group-level variables were introduced in GitLab 9.4. CAUTION: **Important:** Be aware that variables are not masked, and their values can be shown @@ -188,24 +214,25 @@ GitLab CI allows you to define per-project or per-group variables that are set in the pipeline environment. The variables are stored out of the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner making them available during a pipeline run. It's the recommended method to -use for storing things like passwords, SSH keys and credentials. +use for storing things like passwords, SSH keys, and credentials. + +Project-level variables can be added by: -Project-level variables can be added by going to your project's -**Settings > CI/CD**, then finding the section called **Variables**. +1. Navigating to your project's **Settings > CI/CD** page. +1. Inputing variable keys and values in the **Environment variables** section. -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. +Group-level variables can be added by: - +1. Navigating to your group's **Settings > CI/CD** page. +1. Inputing variable keys and values in the **Environment variables** section. Any variables of + [subgroups](../../user/group/subgroups/index.md) will be inherited recursively. Once you set them, they will be available for all subsequent pipelines. You can also [protect your variables](#protected-variables). ### Protected variables ->**Notes:** -This feature requires GitLab 9.3 or higher. +> Introduced in GitLab 9.3. Variables could be protected. Whenever a variable is protected, it would only be securely passed to pipelines running on the @@ -226,8 +253,7 @@ Variables can be specified for a single pipeline run when a [manual pipeline](.. ## Deployment variables -NOTE: **Note:** -This feature requires GitLab CI 8.15 or higher. +> Introduced in GitLab 8.15. [Project services](../../user/project/integrations/project_services.md) that are responsible for deployment configuration may define their own variables that @@ -238,6 +264,23 @@ the project services that you are using to learn which variables they define. An example project service that defines deployment variables is the [Kubernetes integration](../../user/project/clusters/index.md#deployment-variables). +## Auto DevOps application variables + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/49056) in GitLab 11.7. + +You can configure [Auto DevOps](../../topics/autodevops/index.md) to +pass CI variables to the running application by prefixing the key of the +variable with `K8S_SECRET_`. + +These [prefixed +variables](../../topics/autodevops/index.md#application-secret-variables) will +then be available as environment variables on the running application +container. + +CAUTION: **Caution:** +Variables with multiline values are not currently supported due to +limitations with the current Auto DevOps scripting environment. + ## Debug tracing > Introduced in GitLab Runner 1.7. @@ -306,6 +349,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_DEBUG_TRACE=false ++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 ++ CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_SHORT_SHA=dd648b2e +++ CI_COMMIT_SHORT_SHA=dd648b2e ++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 ++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 ++ export CI_COMMIT_REF_NAME=master @@ -360,6 +405,10 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_SERVER_VERSION=8.14.3-ee ++ export CI_SERVER_REVISION=82823 ++ CI_SERVER_REVISION=82823 +++ export CI_PAGES_DOMAIN=gitlab.io +++ CI_PAGES_DOMAIN=gitlab.io +++ export CI_PAGES_URL=https://gitlab-examples.gitlab.io/ci-debug-trace +++ CI_PAGES_URL=https://gitlab-examples.gitlab.io/ci-debug-trace ++ export CI_PROJECT_ID=17893 ++ CI_PROJECT_ID=17893 ++ export CI_PROJECT_NAME=ci-debug-trace @@ -452,6 +501,7 @@ Example values: ```bash export CI_JOB_ID="50" export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" +export CI_COMMIT_SHORT_SHA="1ecfd275" export CI_COMMIT_REF_NAME="master" export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" export CI_COMMIT_TAG="1.0.0" @@ -462,6 +512,8 @@ export CI_JOB_TRIGGERED="true" export CI_JOB_TOKEN="abcde-1234ABCD5678ef" export CI_PIPELINE_ID="1000" export CI_PIPELINE_IID="10" +export CI_PAGES_DOMAIN="gitlab.io" +export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-ce" export CI_PROJECT_ID="34" export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce" export CI_PROJECT_NAME="gitlab-ce" @@ -488,7 +540,7 @@ export CI_REGISTRY_PASSWORD="longalfanumstring" ## Variables expressions -> Variables expressions were added in GitLab 10.7. +> Introduced in GitLab 10.7. It is possible to use variables expressions with only / except policies in `.gitlab-ci.yml`. By using this approach you can limit what jobs are going to @@ -577,11 +629,8 @@ Below you can find supported syntax reference: [envs]: ../environments.md [protected branches]: ../../user/project/protected_branches.md [protected tags]: ../../user/project/protected_tags.md -[runner]: https://docs.gitlab.com/runner/ [shellexecutors]: https://docs.gitlab.com/runner/executors/ [triggered]: ../triggers/README.md -[triggers]: ../triggers/README.md#pass-job-variables-to-a-trigger -[subgroups]: ../../user/group/subgroups/index.md [builds-policies]: ../yaml/README.md#only-and-except-complex [gitlab-deploy-token]: ../../user/project/deploy_tokens/index.md#gitlab-deploy-token [registry]: ../../user/project/container_registry.md diff --git a/doc/ci/variables/img/variables.png b/doc/ci/variables/img/variables.png Binary files differdeleted file mode 100644 index d2dc99bbac0..00000000000 --- a/doc/ci/variables/img/variables.png +++ /dev/null diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 4e8ce10c9cb..1d98e8426fe 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -17,7 +17,7 @@ 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: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) | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 24d60a0cdcc..4c39b14b1d0 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -55,138 +55,28 @@ A job is defined by a list of parameters that define the job behavior. | Keyword | Required | Description | |---------------|----------|-------------| -| script | yes | Defines a shell script which is executed by Runner | -| extends | no | Defines a configuration entry that this job is going to inherit from | -| image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | -| services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | -| stage | no | Defines a job stage (default: `test`) | -| type | no | Alias for `stage` | -| variables | no | Define job variables on a job level | -| only | no | Defines a list of git refs for which job is created | -| except | no | Defines a list of git refs for which job is not created | -| tags | no | Defines a list of tags which are used to select Runner | -| allow_failure | no | Allow job to fail. Failed job doesn't contribute to commit status | -| when | no | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` | -| dependencies | no | Define other jobs that a job depends on so that you can pass artifacts between them| -| artifacts | no | Define list of [job artifacts](#artifacts) | -| cache | no | Define list of files that should be cached between subsequent runs | -| before_script | no | Override a set of commands that are executed before job | -| 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 | - -### `extends` - -> Introduced in GitLab 11.3. - -`extends` defines an entry name that a job that uses `extends` is going to -inherit from. - -It is an alternative to using [YAML anchors](#anchors) and is a little -more flexible and readable: - -```yaml -.tests: - script: rake test - stage: test - only: - refs: - - branches - -rspec: - extends: .tests - script: rake rspec - only: - variables: - - $RSPEC -``` - -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: - script: rake rspec - stage: test - only: - refs: - - branches - variables: - - $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. - -`extends` supports multi-level inheritance, however it is not recommended to -use more than three levels. The maximum nesting level that is supported is 10. -The following example has two levels of inheritance: - -```yaml -.tests: - only: - - pushes - -.rspec: - extends: .tests - script: rake rspec - -rspec 1: - variables: - RSPEC_SUITE: '1' - extends: .rspec - -rspec 2: - variables: - RSPEC_SUITE: '2' - extends: .rspec - -spinach: - extends: .tests - script: rake spinach -``` - -`extends` works across configuration files combined with [`include`](#include). - -### `pages` - -`pages` is a special job that is used to upload static content to GitLab that -can be used to serve your website. It has a special syntax, so the two -requirements below must be met: - -1. Any static content must be placed under a `public/` directory -1. `artifacts` with a path to the `public/` directory must be defined - -The example below simply moves all files from the root of the project to the -`public/` directory. The `.public` workaround is so `cp` doesn't also copy -`public/` to itself in an infinite loop: - -```yaml -pages: - stage: deploy - script: - - mkdir .public - - cp -r * .public - - mv .public public - artifacts: - paths: - - public - only: - - master -``` - -Read more on [GitLab Pages user documentation](../../user/project/pages/index.md). +| [script](#script) | yes | Defines a shell script which is executed by Runner | +| [extends](#extends) | no | Defines a configuration entry that this job is going to inherit from | +| [include](#include) | no | Defines a configuration entry that allows this job to include external YAML files | +| [image](#image-and-services) | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | +| [services](#image-and-services) | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | +| [stage](#stage) | no | Defines a job stage (default: `test`) | +| type | no | Alias for `stage` | +| [variables](#variables) | no | Define job variables on a job level | +| [only](#only-and-except-simplified) | no | Defines a list of git refs for which job is created | +| [except](#only-and-except-simplified) | no | Defines a list of git refs for which job is not created | +| [tags](#tags) | no | Defines a list of tags which are used to select Runner | +| [allow_failure](#allow_failure) | no | Allow job to fail. Failed job doesn't contribute to commit status | +| [when](#when) | no | Define when to run job. Can be `on_success`, `on_failure`, `always` or `manual` | +| [dependencies](#dependencies) | no | Define other jobs that a job depends on so that you can pass artifacts between them| +| [artifacts](#artifacts) | no | Define list of [job artifacts](#artifacts) | +| [cache](#cache) | no | Define list of files that should be cached between subsequent runs | +| [before_script](#before_script-and-after_script) | no | Override a set of commands that are executed before job | +| [after_script](#before_script-and-after_script) | no | Override a set of commands that are executed after job | +| [environment](#environment) | no | Defines a name of environment to which deployment is done by this job | +| [coverage](#coverage) | no | Define code coverage settings for a given job | +| [retry](#retry) | no | Define when and how many times a job can be auto-retried in case of a failure | +| [parallel](#parallel) | no | Defines how many instances of a job should be run in parallel | ## `image` and `services` @@ -202,7 +92,7 @@ used for time of the job. The configuration of this feature is covered in jobs, including deploy jobs, but after the restoration of [artifacts](#artifacts). This can be an array or a multi-line string. -`after_script` is used to define the command that will be run after for all +`after_script` is used to define the command that will be run after all jobs, including failed ones. This has to be an array or a multi-line string. The `before_script` and the main `script` are concatenated and run in a single context/container. @@ -258,7 +148,7 @@ There are also two edge cases worth mentioning: 1. If no `stages` are defined in `.gitlab-ci.yml`, then the `build`, `test` and `deploy` are allowed to be used as job's stage by default. -2. If a job doesn't specify a `stage`, the job is assigned the `test` stage. +1. If a job doesn't specify a `stage`, the job is assigned the `test` stage. ## `stage` @@ -326,30 +216,31 @@ a "key: value" pair. Be careful when using special characters: jobs are created: 1. `only` defines the names of branches and tags for which the job will run. -2. `except` defines the names of branches and tags for which the job will +1. `except` defines the names of branches and tags for which the job will **not** run. 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 +- `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 to specify a repository path to filter jobs for +- `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. In addition, `only` and `except` allow the use of special keywords: | **Value** | **Description** | | --------- | ---------------- | -| `branches` | When a branch is pushed. | -| `tags` | When a tag is pushed. | -| `api` | When pipeline has been triggered by a second pipelines API (not triggers API). | -| `external` | When using CI services other than GitLab. | -| `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. | -| `pushes` | Pipeline is triggered by a `git push` by the user. | -| `schedules` | For [scheduled pipelines][schedules]. | -| `triggers` | For pipelines created using a trigger token. | -| `web` | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). | +| `branches` | When a git reference of a pipeline is a branch. | +| `tags` | When a git reference of a pipeline is a tag. | +| `api` | When pipeline has been triggered by a second pipelines API (not triggers API). | +| `external` | When using CI services other than GitLab. | +| `pipelines` | For multi-project triggers, created using the API with `CI_JOB_TOKEN`. | +| `pushes` | Pipeline is triggered by a `git push` by the user. | +| `schedules` | For [scheduled pipelines][schedules]. | +| `triggers` | For pipelines created using a trigger token. | +| `web` | For pipelines created using **Run pipeline** button in GitLab UI (under your project's **Pipelines**). | +| `merge_requests` | When a merge request is created or updated (See [pipelines for merge requests](../merge_request_pipelines/index.md)). | In the example below, `job` will run only for refs that start with `issue-`, whereas all branches will be skipped: @@ -390,51 +281,84 @@ job: The above example will run `job` for all branches on `gitlab-org/gitlab-ce`, except master. +If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by +default. If it doesn't have an `except` rule, it is empty. + +For example, + +```yaml +job: + script: echo 'test' +``` + +is translated to: + +```yaml +job: + script: echo 'test' + only: ['branches', 'tags'] +``` + ## `only` and `except` (complex) -> `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 +> - `refs` and `kubernetes` policies introduced in GitLab 10.0. +> - `variables` policy introduced in GitLab 10.7. +> - `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in GitLab 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 -policy configuration. +GitLab supports both simple and complex strategies, so it's possible to use an +array and a hash configuration scheme. -GitLab now supports both, simple and complex strategies, so it is possible to -use an array and a hash configuration scheme. +Four keys are available: -Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`. +- `refs` +- `variables` +- `changes` +- `kubernetes` -### `refs` and `kubernetes` +If you use multiple keys under `only` or `except`, they act as an AND. The logic is: -Refs strategy equals to simplified only/except configuration, whereas -kubernetes strategy accepts only `active` keyword. +> (any of refs) AND (any of variables) AND (any of changes) AND (if kubernetes is active) -### `only:variables` +### `only:refs` and `except:refs` -`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 -evaluate in order to decide whether a job should be created or not. +The `refs` strategy can take the same values as the +[simplified only/except configuration](#only-and-except-simplified). -See the example below. Job is going to be created only when pipeline has been -scheduled or runs for a `master` branch, and only if kubernetes service is -active in the project. +In the example below, the `deploy` job is going to be created only when the +pipeline has been [scheduled][schedules] or runs for the `master` branch: ```yaml -job: +deploy: only: refs: - master - schedules +``` + +### `only:kubernetes` and `except:kubernetes` + +The `kubernetes` strategy accepts only the `active` keyword. + +In the example below, the `deploy` job is going to be created only when the +Kubernetes service is active in the project: + +```yaml +deploy: + only: kubernetes: active ``` +### `only:variables` and `except:variables` + +The `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 +evaluate in order to decide whether a job should be created or not. + Examples of using variables expressions: ```yaml @@ -448,7 +372,7 @@ deploy: - $STAGING ``` -Another use case is exluding jobs depending on a commit message _(added in 11.0)_: +Another use case is excluding jobs depending on a commit message: ```yaml end-to-end: @@ -458,11 +382,11 @@ end-to-end: - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ ``` -Learn more about variables expressions on [a separate page][variables-expressions]. +Learn more about [variables expressions](../variables/README.md#variables-expressions). -### `only:changes` +### `only:changes` and `except:changes` -Using `changes` keyword with `only` or `except` makes it possible to define if +Using the `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: @@ -474,14 +398,18 @@ docker build: 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 +existing branch, GitLab creates and triggers the `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 subdirectories inside the `dockerfiles` directory. +- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory. CAUTION: **Warning:** There are some caveats when using this feature with new branches and tags. See @@ -545,15 +473,17 @@ osx job: ## `allow_failure` -`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`. +`allow_failure` allows a job to fail without impacting the rest of the CI +suite. +The default value is `false`, except for [manual](#whenmanual) jobs. + +When enabled and the job fails, the job will show an orange warning in the UI. +However, the logical flow of the pipeline will consider the job a +success/passed, and is not blocked. -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 -displayed on the merge request or commit or job page. This is to be used by -jobs that are allowed to fail, but where failure indicates some other (manual) -steps should be taken elsewhere. +Assuming all other jobs are successful, the job's stage and its pipeline will +show the same orange warning. However, the associated commit will be marked +"passed", without warnings. In the example below, `job1` and `job2` will run in parallel, but if `job1` fails, it will not stop the next stage from running, since it's marked with @@ -585,12 +515,13 @@ failure. `when` can be set to one of the following values: 1. `on_success` - execute job only when all jobs from prior stages - succeed. This is the default. + succeed (or are considered succeeding because they are marked + `allow_failure`). This is the default. 1. `on_failure` - execute job only when at least one job from prior stages fails. 1. `always` - execute job regardless of the status of jobs from prior stages. 1. `manual` - execute job manually (added in GitLab 8.10). Read about - [manual actions](#when-manual) below. + [manual actions](#whenmanual) below. For example: @@ -634,9 +565,9 @@ cleanup_job: The above script will: 1. Execute `cleanup_build_job` only when `build_job` fails. -2. Always execute `cleanup_job` as the last step in pipeline regardless of +1. Always execute `cleanup_job` as the last step in pipeline regardless of success or failure. -3. Allow you to manually execute `deploy_job` from GitLab's UI. +1. Allow you to manually execute `deploy_job` from GitLab's UI. ### `when:manual` @@ -650,7 +581,7 @@ Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions would be a deployment to a production environment. Manual actions can be started from the pipeline, job, environment, and deployment views. Read more at the -[environments documentation][env-manual]. +[environments documentation](../environments.md#manually-deploying-to-environments). Manual actions can be either optional or blocking. Blocking manual actions will block the execution of the pipeline at the stage this action is defined in. It's @@ -681,7 +612,7 @@ 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_key` must be less than or equal to one hour. Examples of valid values include: +provided. `start_in` key must be less than or equal to one hour. Examples of valid values include: - `10 seconds` - `30 minutes` @@ -809,7 +740,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. @@ -1292,13 +1223,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 @@ -1307,8 +1242,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 @@ -1325,8 +1261,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 @@ -1334,6 +1268,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. @@ -1430,18 +1439,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: @@ -1449,101 +1460,285 @@ 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-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. -> 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) +> - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. +> - Available for Starter, Premium and Ultimate since 10.6. +> - [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. +`include` requires the external YAML file to have the extensions `.yml` or `.yaml`, +otherwise the external file will not be included. -In the following example, the content of `.before-script-template.yml` will be -automatically fetched and evaluated along with the content of `.gitlab-ci.yml`: +The files defined in `include` are: + +- Deep merged with those in `.gitlab-ci.yml`. +- Always evaluated first and merged with the content of `.gitlab-ci.yml`, + regardless of the position of the `include` keyword. + +TIP: **Tip:** +Use merging to customize and override included CI/CD configurations with local +definitions. + +Recursive includes are not supported. Your external files should not use the +`include` keyword as it will be ignored. + +NOTE: **Note:** +Using YAML aliases across different YAML files sourced by `include` is not +supported. You must only refer to aliases in the same file. Instead +of using YAML anchors, you can use the [`extends` keyword](#extends). + +`include` supports four include methods: + +- [`local`](#includelocal) +- [`file`](#includefile) +- [`template`](#includetemplate) +- [`remote`](#includeremote) + +See [usage examples](#include-examples). + +### `include:local` + +`include:local` includes a file from the same repository as `.gitlab-ci.yml`. +It's referenced using full paths relative to the root directory (`/`). + +You can only use files that are currently tracked by Git on the same branch +your configuration file is on. In other words, when using a `include:local`, make +sure that both `.gitlab-ci.yml` and the local file are on the same branch. + +NOTE: **Note:** +Including local files through Git submodules paths is not supported. + +Example: ```yaml -# Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml +include: + - local: '/templates/.gitlab-ci-template.yml' +``` -before_script: - - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs - - gem install bundler --no-ri --no-rdoc - - bundle install --jobs $(nproc) "${FLAGS[@]}" +### `include:file` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53903) in GitLab 11.7. + +To include files from another private project under the same GitLab instance, +use `include:file`. This file is referenced using full paths relative to the +root directory (`/`). For example: + +```yaml +include: + - project: 'my-group/my-project' + file: '/templates/.gitlab-ci-template.yml' ``` +You can also specify `ref`, with the default being the `HEAD` of the project: + ```yaml -# Content of .gitlab-ci.yml +include: + - project: 'my-group/my-project' + ref: master + file: '/templates/.gitlab-ci-template.yml' -include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + - project: 'my-group/my-project' + ref: v1.0.0 + file: '/templates/.gitlab-ci-template.yml' -rspec: - script: - - bundle exec rspec + - project: 'my-group/my-project' + ref: 787123b47f14b552955ca2786bc9542ae66fee5b # Git SHA + file: '/templates/.gitlab-ci-template.yml' ``` -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: +### `include:template` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53445) in GitLab 11.7. + +`include:template` can be used to include `.gitlab-ci.yml` templates that are +[shipped with GitLab](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/ci/templates). + +For example: ```yaml -# Single string +# File sourced from GitLab's template collection +include: + - template: Auto-DevOps.gitlab-ci.yml +``` -include: '/templates/.after-script-template.yml' +### `include:remote` + +`include:remote` can be used to include a file from a different location, +using HTTP/HTTPS, referenced by using the full URL. The remote file must be +publicly accessible through a simple GET request as authentication schemas +in the remote URL is not supported. For example: + +```yaml +include: + - remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' ``` +NOTE: **Note for GitLab admins:** +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 **Admin area > Settings > Network > Outbound requests** section. + +### `include` examples + +Here are a few more `include` examples. + +#### Single string or array of multiple values + +You can include your extra YAML file(s) either as a single string or +an array of multiple values. The following examples are all valid. + +Single string with the `include:local` method implied: + ```yaml -# Array +include: '/templates/.after-script-template.yml' +``` + +Array with `include` method implied: +```yaml include: - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' - '/templates/.after-script-template.yml' ``` ---- +Single string with `include` method specified explicitly: -`include` supports two types of files: +```yaml +include: + remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' +``` -- **local** to the same repository, referenced by using full paths in the same - repository, with `/` being the root directory. For example: +Array with `include:remote` being the single item: - ```yaml - # Within the repository - include: '/templates/.gitlab-ci-template.yml' - ``` +```yaml +include: + - remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' +``` + +Array with multiple `include` methods specified explicitly: + +```yaml +include: + - remote: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + - local: '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml +``` - NOTE: **Note:** - You can only use files that are currently tracked by Git on the same branch - your configuration file is. In other words, when using a **local file**, make - sure that both `.gitlab-ci.yml` and the local file are on the same branch. +Array mixed syntax: - NOTE: **Note:** - We don't support the inclusion of local files through Git submodules paths. +```yaml +include: + - 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + - '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + - project: 'my-group/my-project' + ref: master + file: '/templates/.gitlab-ci-template.yml' +``` -- **remote** in a different location, accessed using HTTP/HTTPS, referenced - using the full URL. For example: +#### Re-using a `before_script` template - ```yaml - include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml' - ``` +In the following example, the content of `.before-script-template.yml` will be +automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. - 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. +Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: ---- +```yaml +before_script: + - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs + - gem install bundler --no-document + - bundle install --jobs $(nproc) "${FLAGS[@]}" +``` +Content of `.gitlab-ci.yml`: -Since GitLab 10.8 we are now recursively merging the files defined in `include` -with those in `.gitlab-ci.yml`. Files defined by `include` are always -evaluated first and recursively merged with the content of `.gitlab-ci.yml`, no -matter the position of the `include` keyword. You can take advantage of -recursive merging to customize and override details in included CI -configurations with local definitions. +```yaml +include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' + +rspec: + script: + - bundle exec rspec +``` + +#### Overriding external template values The following example shows specific YAML-defined variables and details of the `production` job from an include file being customized in `.gitlab-ci.yml`. -```yaml -# Content of https://company.com/autodevops-template.yml +Content of `https://company.com/autodevops-template.yml`: +```yaml variables: POSTGRES_USER: user POSTGRES_PASSWORD: testing_password @@ -1561,9 +1756,9 @@ production: - master ``` -```yaml -# Content of .gitlab-ci.yml +Content of `.gitlab-ci.yml`: +```yaml include: 'https://company.com/autodevops-template.yml' image: alpine:latest @@ -1587,18 +1782,14 @@ with the environment url of the `production` job defined in `autodevops-template.yml` have been overridden by new values defined in `.gitlab-ci.yml`. -NOTE: **Note:** -Recursive includes are not supported meaning your external files -should not use the `include` keyword, as it will be ignored. - -Recursive merging lets you extend and override dictionary mappings, but +The merging lets you extend and override dictionary mappings, but you cannot add or modify items to an included array. For example, to add an additional item to the production job script, you must repeat the -existing script items. +existing script items: -```yaml -# Content of https://company.com/autodevops-template.yml +Content of `https://company.com/autodevops-template.yml`: +```yaml production: stage: production script: @@ -1606,9 +1797,9 @@ production: - deploy ``` -```yaml -# Content of .gitlab-ci.yml +Content of `.gitlab-ci.yml`: +```yaml include: 'https://company.com/autodevops-template.yml' stages: @@ -1616,7 +1807,7 @@ stages: production: script: - - install_depedencies + - install_dependencies - deploy - notify_owner ``` @@ -1625,10 +1816,140 @@ In this case, if `install_dependencies` and `deploy` were not repeated in `.gitlab-ci.yml`, they would not be part of the script for the `production` job in the combined CI configuration. +## `extends` + +> Introduced in GitLab 11.3. + +`extends` defines an entry name that a job that uses `extends` is going to +inherit from. + +It is an alternative to using [YAML anchors](#anchors) and is a little +more flexible and readable: + +```yaml +.tests: + script: rake test + stage: test + only: + refs: + - branches + +rspec: + extends: .tests + script: rake rspec + only: + variables: + - $RSPEC +``` + +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: + script: rake rspec + stage: test + only: + refs: + - branches + variables: + - $RSPEC +``` + NOTE: **Note:** -We currently do not support using YAML aliases across different YAML files -sourced by `include`. You must only refer to aliases in the same file. Instead -of using YAML anchors you can use [`extends` keyword](#extends). +Note that `script: rake test` has been overwritten by `script: rake rspec`. + +If you do want to include the `rake test`, see [`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. + +`extends` supports multi-level inheritance, however it is not recommended to +use more than three levels. The maximum nesting level that is supported is 10. +The following example has two levels of inheritance: + +```yaml +.tests: + only: + - pushes + +.rspec: + extends: .tests + script: rake rspec + +rspec 1: + variables: + RSPEC_SUITE: '1' + extends: .rspec + +rspec 2: + variables: + RSPEC_SUITE: '2' + extends: .rspec + +spinach: + extends: .tests + script: rake spinach +``` + +## Using `extends` and `include` together + +`extends` works across configuration files combined with `include`. + +For example, if you have a local `included.yml` file: + +```yaml +.template: + script: + - echo Hello! +``` + +Then, in `.gitlab-ci.yml` you can use it like this: + +```yaml +include: included.yml + +useTemplate: + image: alpine + extends: .template +``` + +This will run a job called `useTemplate` that runs `echo Hello!` as defined in +the `.template` job, and uses the `alpine` Docker image as defined in the local job. + +## `pages` + +`pages` is a special job that is used to upload static content to GitLab that +can be used to serve your website. It has a special syntax, so the two +requirements below must be met: + +- Any static content must be placed under a `public/` directory. +- `artifacts` with a path to the `public/` directory must be defined. + +The example below simply moves all files from the root of the project to the +`public/` directory. The `.public` workaround is so `cp` doesn't also copy +`public/` to itself in an infinite loop: + +```yaml +pages: + stage: deploy + script: + - mkdir .public + - cp -r * .public + - mv .public public + artifacts: + paths: + - public + only: + - master +``` + +Read more on [GitLab Pages user documentation](../../user/project/pages/index.md). ## `variables` @@ -1655,15 +1976,8 @@ 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). +Runner itself](../variables/README.md#predefined-environment-variables). One example would be `CI_COMMIT_REF_NAME` which has the value of the branch or tag name for which project is built. Apart from the variables you can set in `.gitlab-ci.yml`, there are also the so called @@ -1674,9 +1988,9 @@ which can be set in GitLab's UI. ### Git strategy -> Introduced in GitLab 8.9 as an experimental feature. May change or be removed - completely in future releases. `GIT_STRATEGY=none` requires GitLab Runner - v1.7+. +> Introduced in GitLab 8.9 as an experimental feature. May change or be removed +> completely in future releases. `GIT_STRATEGY=none` requires GitLab Runner +> v1.7+. You can set the `GIT_STRATEGY` used for getting recent application code, either globally or per-job in the [`variables`](#variables) section. If left @@ -1712,6 +2026,11 @@ variables: GIT_STRATEGY: none ``` +NOTE: **Note:** `GIT_STRATEGY` is not supported for +[Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html), +but may be in the future. See the [support Git strategy with Kubernetes executor feature proposal](https://gitlab.com/gitlab-org/gitlab-runner/issues/3847) +for updates. + ### Git submodule strategy > Requires GitLab Runner v1.10+. @@ -2004,6 +2323,13 @@ with an API call. If your commit message contains `[ci skip]` or `[skip ci]`, using any capitalization, the commit will be created but the pipeline will be skipped. +Alternatively, one can pass the `ci.skip` [Git push option][push-option] if +using Git 2.10 or newer: + +```sh +git push -o ci.skip +``` + ## Validate the .gitlab-ci.yml Each instance of GitLab CI has an embedded debug tool called Lint, which validates the @@ -2017,17 +2343,15 @@ try to quote them, or change them to a different form (e.g., `/bin/true`). ## Examples -Visit the [examples README][examples] to see a list of examples using GitLab -CI with various languages. +See a [list of examples](../examples/README.md "CI/CD examples") for using +GitLab CI/CD with various languages. -[env-manual]: ../environments.md#manually-deploying-to-environments -[examples]: ../examples/README.md [ce-6323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6323 -[environment]: ../environments.md [ce-6669]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6669 -[variables]: ../variables/README.md [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983 [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447 [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 +[environment]: ../environments.md "CI/CD environments" +[schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules" +[variables]: ../variables/README.md "CI/CD variables" +[push-option]: https://git-scm.com/docs/git-push#git-push--oltoptiongt diff --git a/doc/development/README.md b/doc/development/README.md index 14dfe8eb1f3..05715274a81 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -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 @@ -46,6 +47,7 @@ description: 'Learn how to contribute to GitLab.' - [Avoid modules with instance variables](module_with_instance_variables.md) if possible - [How to dump production data to staging](db_dump.md) - [Working with the GitHub importer](github_importer.md) +- [Import/Export development documentation](import_export.md) - [Working with Merge Request diffs](diffs.md) - [Permissions](permissions.md) - [Prometheus metrics](prometheus_metrics.md) diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index ea6f14da3b9..c47ce0f1182 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 @@ -113,9 +113,9 @@ the meaning of the various columns can be found at Because the output of this query relies on the actual usage of your database it may be affected by factors such as (but not limited to): -* Certain queries never being executed, thus not being able to use certain +- Certain queries never being executed, thus not being able to use certain indexes. -* Certain tables having little data, resulting in PostgreSQL using sequence +- Certain tables having little data, resulting in PostgreSQL using sequence scans instead of index scans. In other words, this data is only reliable for a frequently used database with 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/api_styleguide.md b/doc/development/api_styleguide.md index ce444ebdde4..4fc38a460f8 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -14,7 +14,7 @@ Always use an [Entity] to present the endpoint's payload. ## Methods and parameters description Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods) -(see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb +(see <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/api/environments.rb> for a good example): - `desc` for the method summary. You should pass it a block for additional @@ -49,14 +49,14 @@ end `params` block. It filters out the params that have been passed, but are not allowed. -– https://github.com/ruby-grape/grape#declared +– <https://github.com/ruby-grape/grape#declared> ### Exclude params from parent namespaces! > By default `declared(params) `includes parameters that were defined in all parent namespaces. -– https://github.com/ruby-grape/grape#include-parent-namespaces +– <https://github.com/ruby-grape/grape#include-parent-namespaces> In most cases you will want to exclude params from the parent namespaces: 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 9dd78806a12..fed772b9240 100644 --- a/doc/development/automatic_ce_ee_merge.md +++ b/doc/development/automatic_ce_ee_merge.md @@ -1,54 +1,28 @@ # Automatic CE->EE merge -GitLab Community Edition is merged automatically every 3 hours into the -Enterprise Edition (look for the [`CE Upstream` merge requests]). - -This merge is done automatically in a -[scheduled pipeline](https://gitlab.com/gitlab-org/release-tools/-/jobs/43201679). - -## What to do if you are pinged in a `CE Upstream` merge request to resolve a conflict? - -1. Please resolve the conflict as soon as possible or ask someone else to do it - - It's ok to resolve more conflicts than the one that you are asked to resolve. - In that case, it's a good habit to ask for a double-check on your resolution - by someone who is familiar with the code you touched. -1. Once you have resolved your conflicts, push to the branch (no force-push) -1. Assign the merge request to the next person that has to resolve a conflict -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 need any help, you can ping the current [release managers], or ask in - the `#ce-to-ee` Slack channel - -A few notes about the automatic CE->EE merge job: - -- If a merge is already in progress, the job - [doesn't create a new one](https://gitlab.com/gitlab-org/release-tools/-/jobs/43157687). -- If there is nothing to merge (i.e. EE is up-to-date with CE), the job doesn't - create a new one -- The job posts messages to the `#ce-to-ee` Slack channel to inform what's the - current CE->EE merge status (e.g. "A new MR has been created", "A MR is still pending") - -[`CE Upstream` merge requests]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?label_name%5B%5D=CE+upstream -[release managers]: https://about.gitlab.com/release-managers/ +Commits pushed to CE `master` are automatically merged into EE `master` roughly +every 5 minutes. Changes are merged using the `recursive=ours` merge strategy in +the context of EE. This means that any merge conflicts are resolved by taking +the EE changes and discarding the CE changes. This removes the need for +resolving conflicts or reverting changes, at the cost of **absolutely +requiring** EE merge requests to be created whenever a CE merge request causes +merge conflicts. Failing to do so can result in changes not making their way +into EE. + +## Always create an EE merge request if there are conflicts + +In CI there is a job called `ee_compat_check`, which checks if a CE MR causes +merge conflicts with EE. If this job reports conflicts, you **must** create an +EE merge request. If you are an external contributor you can ask the reviewer to +do this for you. ## Always merge EE merge requests before their CE counterparts **In order to avoid conflicts in the CE->EE merge, you should always merge the EE version of your CE merge request first, if present.** -The rationale for this is that as CE->EE merges are done automatically every few -hours, it can happen that: - -1. A CE merge request that needs EE-specific changes is merged -1. The automatic CE->EE merge happens -1. Conflicts due to the CE merge request occur since its EE merge request isn't - merged yet -1. The automatic merge bot will ping someone to resolve the conflict **that are - already resolved in the EE merge request that isn't merged yet** - -That's a waste of time, and that's why you should merge EE merge request before -their CE counterpart. +Failing to do so will lead to CE changes being discarded when merging into EE, +if they cause merge conflicts. ## Avoiding CE->EE merge conflicts beforehand @@ -174,7 +148,7 @@ merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`: - To cherry-pick multiple commits, such as B and D in a range [A > B > C > D], use: ```shell - git cherry-pick commmit-B-SHA commit-D-SHA + git cherry-pick commit-B-SHA commit-D-SHA ``` For example, suppose commit B SHA = `4f5e4018c09ed797fdf446b3752f82e46f5af502`, @@ -196,6 +170,60 @@ you are not required to submit the EE-equivalent MR, but it's still recommended. job failed, you are required to submit the EE MR so that you can fix the conflicts in EE before merging your changes into CE. +## FAQ + +### How does automatic merging work? + +The automatic merging is performed using a project called [Merge +Train](https://gitlab.com/gitlab-org/merge-train/). This project will clone CE +and EE master, and merge CE master into EE master using `git merge +--strategy=recursive --strategy-option=ours`. This process runs multiple times +per hour. + +For more information on the exact implementation you can refer to the source +code. + +### Why merge automatically? + +As we work towards continuous deployments and a single repository for both CE +and EE, we need to first make sure that all CE changes make their way into CE as +fast as possible. Past experiences and data have shown that periodic CE to EE +merge requests do not scale, and often take a very long time to complete. For +example, [in this +comment](https://gitlab.com/gitlab-org/release/framework/issues/49#note_114614619) +we determined that the average time to close an upstream merge request is around +5 hours, with peaks up to several days. Periodic merge requests are also +frustrating to work with, because they often include many changes unrelated to +your own changes. + +To resolve these problems, we now merge changes using the `ours` strategy to +automatically resolve merge conflicts. This removes the need for resolving +conflicts in a periodic merge request, and allows us to merge changes from CE +into EE much faster. + +### My CE merge request caused conflicts after it was merged. What do I do? + +If you notice this, you should set up an EE merge request that resolves these +conflicts as **soon as possible**. Failing to do so can lead to your changes not +being available in EE, which may break tests. This in turn would prevent us from +being able to deploy. + +### Won't this setup be risky? + +No, not if there is an EE merge request for every CE merge request that causes +conflicts _and_ that EE merge request is merged first. In the past we may have +been a bit more relaxed when it comes to enforcing EE merge requests, but to +enable automatic merging we have to start requiring such merge requests even for +the smallest conflicts. + +### Some files I work with often conflict, how can I best deal with this? + +If you find you keep running into merge conflicts, consider refactoring the file +so that the EE specific changes are not intertwined with CE code. For Ruby code +you can do this by moving the EE code to a separate module, which can then be +injected into the appropriate classes or modules. See [Guidelines for +implementing Enterprise Edition features](ee_features.md) for more information. + --- [Return to Development documentation](README.md) diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index bb9a296ef12..642dac614c7 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -25,9 +25,9 @@ should only be used for data migrations. Some examples where background migrations can be useful: -* Migrating events from one table to multiple separate tables. -* Populating one column based on JSON stored in another column. -* Migrating data that depends on the output of external services (e.g. an API). +- Migrating events from one table to multiple separate tables. +- Populating one column based on JSON stored in another column. +- Migrating data that depends on the output of external services (e.g. an API). ## Isolation @@ -211,7 +211,7 @@ existing data. Since we're dealing with a lot of rows we'll schedule jobs in batches instead of doing this one by one: ```ruby -class ScheduleExtractServicesUrl < ActiveRecord::Migration +class ScheduleExtractServicesUrl < ActiveRecord::Migration[4.2] disable_ddl_transaction! class Service < ActiveRecord::Base @@ -242,7 +242,7 @@ jobs and manually run on any un-migrated rows. Such a migration would look like this: ```ruby -class ConsumeRemainingExtractServicesUrlJobs < ActiveRecord::Migration +class ConsumeRemainingExtractServicesUrlJobs < ActiveRecord::Migration[4.2] disable_ddl_transaction! class Service < ActiveRecord::Base 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 f06d40d1dbb..cd0a1f46d27 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -133,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 87437dd7720..25ea2211b64 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/workflow/code-review/#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/workflow/code-review/#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). -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]**. +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 + +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. -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]. +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. + +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 @@ -99,7 +197,7 @@ first time. ### 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. +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. @@ -109,7 +207,7 @@ It is responsibility of the author of a merge request that the merge request is ### 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&assignee_id=0) and assign any merge request they want to 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 @@ -135,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 @@ -176,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/index.md b/doc/development/contributing/index.md index 29af8dcb9bb..7ac846e4c4d 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -3,10 +3,13 @@ Thank you for your interest in contributing to GitLab. This guide details how 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 in the [Backlog (Accepting merge requests) milestone](#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 in two flavors, GitLab Community Edition (CE) our free and open source edition, and GitLab Enterprise Edition (EE) which is our commercial @@ -30,77 +33,8 @@ vulnerabilities. ## Code of conduct -### Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. - -### Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -### Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -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, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -### Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -### Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at conduct@gitlab.com. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -### Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html - -[homepage]: https://www.contributor-covenant.org +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 @@ -133,10 +67,10 @@ the remaining issues on the GitHub issue tracker. ## I want to contribute! -If you want to contribute to GitLab, [issues in the `Backlog (Accepting merge requests)` milestone][accepting-mrs-weight] -are 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! @@ -159,32 +93,32 @@ When submitting code to GitLab, you may feel that your contribution requires the When your code contains more than 500 changes, any major breaking changes, or an external library, `@mention` a maintainer in the merge request. If you are not sure who to mention, the reviewer will add one early in the merge request process. -## Workflow labels - -This [documentation](issue_workflow.md) outlines the current workflow labels. - -* [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) +## Issues + +This [documentation](issue_workflow.md) outlines the current issue 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](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) +- [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 @@ -195,7 +129,6 @@ 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/ +[team]: https://about.gitlab.com/company/team/ [getting-help]: https://about.gitlab.com/getting-help/ [codetriage]: http://www.codetriage.com/gitlabhq/gitlabhq -[accepting-mrs-weight]: https://gitlab.com/gitlab-org/gitlab-ce/issues?scope=all&utf8=✓&state=opened&assignee_id=0&milestone_title=Backlog%20(Accepting%20merge%20requests) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index cd5eee6ea36..24feb1378a1 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -6,9 +6,9 @@ scheduling into milestones. Labelling is a task for everyone. Most issues will have labels for at least one of the following: -- Type: ~"feature proposal", ~bug, ~customer, etc. +- Type: ~feature, ~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 @@ -27,8 +27,8 @@ labels, you can _always_ add the team and type, and often also the subject. Type labels are very important. They define what kind of issue this is. Every issue should have one or more. -Examples of type labels are ~"feature proposal", ~bug, ~customer, ~security, -and ~"direction". +Examples of type labels are ~feature, ~bug, ~customer, ~security, +and ~direction. A number of type labels have a priority assigned to them, which automatically makes them float to the top, depending on their importance. @@ -61,19 +61,19 @@ people. The current team labels are: - ~Configure -- ~"CI/CD" - ~Create - ~Distribution - ~Documentation - ~Geo - ~Gitaly - ~Manage -- ~Monitoring +- ~Monitor - ~Plan - ~Quality - ~Release - ~Secure - ~UX +- ~Verify The descriptions on the [labels page][labels-page] explain what falls under the responsibility of each team. @@ -148,6 +148,9 @@ This label documents the planned timeline & urgency which is used to measure aga | ~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) | +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. @@ -159,6 +162,10 @@ 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. | +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. @@ -168,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 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, @@ -185,26 +192,26 @@ 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 ~feature - 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) @@ -213,12 +220,12 @@ members to further discuss scope, design, and technical considerations. This wil 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 @@ -252,10 +259,10 @@ For feature proposals for EE, open an issue on the [issue tracker of EE][ee-tracker]. In order to help track the feature proposals, we have created a -[`feature proposal`][fpl] label. For the time being, users that are not members +[`feature`][fl] label. For the time being, users that are not members of the project cannot add labels. You can instead ask one of the [core team] -members to add the label ~"feature proposal" to the issue or add the following -code snippet right after your description in a new line: `~"feature proposal"`. +members to add the label ~feature to the issue or add the following +code snippet right after your description in a new line: `~feature`. Please keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. @@ -269,7 +276,7 @@ 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. -[fpl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature+proposal +[fl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature ## Issue tracker guidelines @@ -349,6 +356,45 @@ 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. +## 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, diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index cc7d8a1e1db..9bef0635e3f 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -2,10 +2,9 @@ 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 -[`Backlog (Accepting merge requests)` milestone in the CE issue tracker][accepting-mrs-ce] -and [EE issue tracker][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 @@ -25,8 +24,6 @@ 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. -[accepting-mrs-ce]: https://gitlab.com/gitlab-org/gitlab-ce/issues?milestone_title=Backlog%20(Accepting%20merge%20requests) -[accepting-mrs-ee]: https://gitlab.com/gitlab-org/gitlab-ee/issues?milestone_title=Backlog%20(Accepting%20merge%20requests) [gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests [gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit @@ -174,18 +171,18 @@ the feature you contribute through all of these steps. 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 merge request: -1. Note the addition in the release blog post (create one if it doesn't exist yet) https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/ -1. Upgrade guide, for example https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/7.5-to-7.6.md -1. Upgrader https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/upgrader.md#2-run-gitlab-upgrade-tool -1. Installation guide https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies -1. GitLab Development Kit https://gitlab.com/gitlab-org/gitlab-development-kit -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 +1. Note the addition in the release blog post (create one if it doesn't exist yet) <https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/> +1. Upgrade guide, for example <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/7.5-to-7.6.md> +1. Installation guide <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies> +1. GitLab Development Kit <https://gitlab.com/gitlab-org/gitlab-development-kit> +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 diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index fb0454db7d2..6f1ba5d62a5 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -23,8 +23,7 @@ 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). +[RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com). --- 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 4adae5dabe2..43fc125c21d 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -17,20 +17,20 @@ The diffs fetching process _limits_ single file diff sizes and the overall size then persisted on `merge_request_diff_files` table. 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_ +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 @@ -39,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 diff --git a/doc/development/documentation/feature-change-workflow.md b/doc/development/documentation/feature-change-workflow.md new file mode 100644 index 00000000000..b5b325683a3 --- /dev/null +++ b/doc/development/documentation/feature-change-workflow.md @@ -0,0 +1,112 @@ +--- +description: How to add docs for new or enhanced GitLab features. +--- + +# Documentation process at 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. + +- **Developers**: Author/update documentation in the same MR as their code, and +merge it by the feature freeze for the assigned milestone. Request technical writer +assistance if needed. +- **Product Managers** (PMs): In the issue for all new and enhanced features, +confirm the documentation requirements, plus the mentioned feature description +and use cases, which can be reused in docs. They can bring in a technical +writer for discussion or help, and can be called upon themselves as a doc reviewer. +- **Technical Writers**: Review doc requirements in issues, track issues and MRs +that contain docs changes, help with any questions throughout the authoring/editing process, +and review all new and updated docs content after it's merged (unless a pre-merge +review request is made). + +Beyond this process, any member of the GitLab community can also author documentation +improvements that are not associated with a new or changed feature. See the [Documentation improvement workflow](improvement-workflow.md). + +## When documentation is required + +Documentation must be delivered whenever: + +- A new or enhanced feature is shipped that impacts the user/admin experience +- There are changes to the UI or API +- A process, workflow, or previously documented feature is changed +- A feature is deprecated or removed + +Documentation is not required when a feature is changed on the backend +only and does not directly affect the way that any user or +administrator would interact with GitLab. For example, a UI restyling that offers +no difference in functionality may require documentation updates if screenshots +are now needed, or need to be updated. + +NOTE: **Note:** +When revamping documentation, if unrelated to the feature change, this should be submitted +in its own MR (using the [documentation improvement workflow](improvement-workflow.md)) +so that we can ensure the more time-sensitive doc updates are merged with code by the freeze. + +## Documenting a new or changed feature + +To follow a consistent workflow every month, documentation changes +involve the Product Managers, the developer who shipped the feature, +and the Technical Writing team. Each role is described below. + +### 1. Product Manager's role + +The Product Manager (PM) should confirm or add the following items in the issue: + +- New or updated feature name, overview/description, and use cases, all required per the [Documentation structure and template](structure.md). +- The documentation requirements for the developer working on the docs. + - What new page, new subsection of an existing page, or other update to an existing page/subsection is needed. + - Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected. + - Suggested title of any page or subsection, if applicable. +- Label the issue with `Documentation` and `docs:P1` in addition to the `Deliverable` label and correct milestone. + +Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone. + +### 2. Developer's role + +As a developer, you must ship the documentation with the code of the feature that +you are creating or updating. The documentation is an essential part of the product. + +- New and edited docs should be included in the MR introducing the code, and planned +in the issue that proposed the feature. However, if the new or changed doc requires +extensive collaboration or conversation, a separate, linked issue can be used for the planning process. +- Use the [Documentation guidelines](index.md), as well as other resources linked from there, +including the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +- If you need any help to choose the correct place for a doc, discuss a documentation +idea or outline, or request any other help, ping the Technical Writer for the relevant +[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) +in your issue or MR, or write within `#docs` on the GitLab Slack. +- The docs must be merged with the code **by the feature freeze date**, otherwise +- the feature cannot be included with the release.<!-- TODO: Policy/process for feature-flagged issues --> + +Prior to merge, documentation changes commited by the developer must be reviewed by: +* the person reviewing the code and merging the MR. +* optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested. + +After merging, documentation changing are reviewed by: +* a technical writer (for clarity, structure, grammar, etc). +* optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). +Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset. + +### 3. Technical Writer's role + +**Planning** +- Once an issue contains a Documentation label and an upcoming milestone, a +technical writer reviews the listed documentation requirements, which should have +already been reviewed by the PM. (These are non-blocking reviews; developers should +not wait to work on docs.) +- Monitor the documentation needs of issues assigned to the current and next milestone, +and participate in any needed discussion on docs planning with the dev, PM, and others. + +**Review** +- Techncial writers provide non-blocking reviews of all documentation changes, +typically after the change is merged. However, if the docs are ready in the MR while +we are awaiting other work in order to merge, the technical writer's review can commence early. +- The technical writer will confirm that the doc is clear, grammatically correct, +and discoverable, while avoiding redundancy, bad file locations, typos, broken links, +etc. The technical writer will review the documentation for the following, which +the developer and code reviewer should have already made a good-faith effort to ensure: + - Clarity. + - Relevance (make sure the content is appropriate given the impact of the feature). + - Location (make sure the doc is in the correct dir and has the correct name). + - Syntax, typos, and broken links. + - Improvements to the content. + - Accordance to the [Documentation Style Guide](styleguide.md) and [structure/template](structure.md). diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md new file mode 100644 index 00000000000..ef6392c6f7f --- /dev/null +++ b/doc/development/documentation/improvement-workflow.md @@ -0,0 +1,49 @@ +--- +description: How to improve GitLab's documentation. +--- + +# Documentation improvement workflow + +Anyone can contribute a merge request or create an issue for GitLab's documentation. + +This page covers the process for any contributions to GitLab's docs that are +not part of feature development. If you are looking for information on updating +GitLab's docs as is required with the development and release of a new feature +or feature enhancement, see the [feature-change documentation workflow](feature-change-workflow.md). + +## Who updates the docs + +Anyone can contribute! You can create a merge request with documentation +when you find errors or other room for improvement in an existing doc, or when you +have an idea for all-new documentation that would help a GitLab user or admin +to achieve or improve their DevOps workflows. + +## How to update the docs + +- Follow the described standards and processes listed on the [GitLab Documentation guidelines](index.md) page, +including linked resources: the [Structure and template](structure.md) page, [Style Guide](styleguide.md), and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). +- Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). +- If you need any help to choose the correct place for a doc, discuss a documentation +idea or outline, or request any other help, ping the Technical Writer for the relevant +[DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages) +in your issue or MR, or write within `#docs` if you are a member of GitLab's Slack workspace. + +## Merging + +Anyone with master access to the affected GitLab project can merge documentation changes. +This person must make a good-faith effort to ensure that the content is clear +(sufficiently easy for the intended audience to navigate and understand) and +that it meets the [Documentation Guidelines](index.md) and [Style Guide](styleguide.md). + +If the author or reviewer has any questions, or would like a techncial writer's review +before merging, mention the writer who is assigned to the relevant [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). + +## Technical Writer review + +The technical writing team reviews changes after they are merged, unless a prior +review is requested. + +## Other ways to help + +If you have ideas for further documentation resources that would be best +considered/handled by technical writers, devs, and other SMEs, please create an issue. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 1dcdf788a3e..828f9bfeec6 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -4,46 +4,49 @@ 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). +GitLab's documentation is [intended as the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/) for information about how to configure, use, and troubleshoot GitLab. The documentation contains use cases and usage instructions covering every GitLab feature, organized by product area and subject. This includes topics and workflows that span multiple GitLab features, as well as the use of GitLab with other applications. -## Contributing to docs +In addition to this page, the following resources to help craft and contribute documentation are available: + +- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, and more. +- [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. +- [Workflow](workflow.md) - A landing page for our key workflows: + - [Feature-change documentation workflow](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. + - [Documentation improvement worflow](improvement-workflow.md) - New content not associated with a new feature. +- [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. +- [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. + +## Source and rendered locations -Whenever a feature is changed, updated, introduced, or deprecated, the merge -request introducing these changes must be accompanied by the documentation -(either updating existing ones or creating new ones). This is also valid when -changes are introduced to the UI. +Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance. -The one responsible for writing the first piece of documentation is the developer who -wrote the code. It's the job of the Product Manager to ensure all features are -shipped with its docs, whether is a small or big change. At the pace GitLab evolves, -this is the only way to keep the docs up-to-date. If you have any questions about it, -ask a Technical Writer. Otherwise, when your content is ready, assign one of -them to review it for you. +At `/help`, only content for your current edition and version is included, whereas multiple versions' content is available at docs.gitlab.com. -We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything -is documented. +The source of the documentation is maintained in the following repository locations: -Whenever you submit a merge request for the documentation, use the -"Documentation" MR description template. If you're changing documentation -location, use the MR description template called "Change documentation -location" instead. +| Project | Path | +| --- | --- | +| [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) | +| [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | +| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | +| [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | -## Documentation workflow +Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. -Please read through the [documentation workflow](workflow.md) before getting started. +## Contributing to docs + +[Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. -## Documentation structure +To ensure that GitLab docs keep up with changes to the product, special processes and responsibilities are in place concerning all [feature changes](feature-change-workflow.md)—i.e. development work that impacts the appearance, usage, or administration of a feature. -Follow through the [documentation structure guide](structure.md) for learning -how to structure GitLab docs. +Meanwhile, anyone can contribute [documentation improvements](improvement-workflow.md) large or small that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. ## 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 its markdown rendering engine. See the [GitLab Markdown 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). See [Linting](#linting) for help to follow the guidelines. +Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. ## Documentation directory structure @@ -56,51 +59,51 @@ all docs should be linked. Every new document should be cross-linked to its rela The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have been **deprecated** and the majority their docs have been moved to their correct location -in small iterations. Please don't create new docs in these folders. +in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type. ### 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 -The documentation hierarchy can be vastly improved by providing a better layout -and organization of directories. - -Having a structured document layout, we will be able to have meaningful URLs -like `docs.gitlab.com/user/project/merge_requests/index.html`. With this pattern, -you can immediately tell that you are navigating a user related documentation -and is about the project and its merge requests. - -Do not create summaries of similar types of content (e.g. an index of all articles, videos, etc.), -rather organize content by its subject (e.g. everything related to CI goes together) +Our goal is to have a clear hierarchical structure with meaningful URLs +like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, +you can immediately tell that you are navigating to user-related documentation +about project features; specifically about merge requests. Our site's paths match +those of our repository, so the clear structure also makes documentation easier to update. + +While the documentation is home to a variety of content types, we do not organize by content type. +For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.). +Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes +it difficult to browse for the information you need and difficult to maintain up-to-date content. +Instead, organize content by its subject (e.g. everything related to CI goes together) and cross-link between any related content. -The table below shows what kind of documentation goes where. +Do not simply link out to GitLab technical blog posts. There should be an up-to-date +single source of truth on the topic within the documentation, and the top of the +blog post should be updated to link to that doc. -| 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) | +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. Related process and style guides 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 @@ -127,20 +130,25 @@ The table below shows what kind of documentation goes where. `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. -If you are unsure where a document should live, you can ping `@axil` or `@marcia` in your -merge request. +If you are unsure where a document or a content addition should live, this should +not stop you from authoring and contributing. You can use your best judgment and +then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer +at any stage in the process. The techncial writing team will review all documentation +changes, regardless, and can move content if there is a better place for it. ### Changing document location -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 -Documentation team beforehand. +Changing a document's location requires specific steps to be followed to ensure that +users can seamlessly access the new doc page, whether they are accesing content +on a GitLab instance domain at `/help` or at docs.gitlab.com. Be sure to ping a +GitLab technical writer if you have any questions during the process (such as +whether the move is necessary), and ensure that a technical writer reviews this +change prior to merging. -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: +If you indeed need to change a document's location, do not remove the old +document, but rather replace all of its content with a new line: -``` +```md This document was moved to [another location](path/to/new_doc.md). ``` @@ -154,7 +162,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 +170,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" ``` @@ -176,6 +184,7 @@ Things to note: - Since we also use inline documentation, except for the documentation itself, the document might also be referenced in the views of GitLab (`app/`) which will render when visiting `/help`, and sometimes in the testing suite (`spec/`). + You must search these paths for references to the doc and update them as well. - The above `git grep` command will search recursively in the directory you run it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` and will print the file and the line where this file is mentioned. @@ -198,7 +207,12 @@ redirect_to: '../path/to/file/README.md' It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`. -### Redirections for pages with Disqus comments +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, we need to preserve the Disqus thread. @@ -223,163 +237,39 @@ 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`. -## 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` -- `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` checks might reduce - noise. The following sample `proselint` configuration disables the `typography.symbols` checks: - -```json -{ - "checks": { - "typography.symbols": 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. - -```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, - "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`. - -## 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` | 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. +tests. If it does not, the whole application test suite will run (including docs tests). ## Merge requests for GitLab documentation Before getting started, make sure you read the introductory section "[contributing to docs](#contributing-to-docs)" above and the -[tech writing workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) -for GitLab Team members. +[documentation workflow](workflow.md). - Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md) - Use the correct [branch name](#branch-naming) - Label the MR `Documentation` - Assign the correct milestone (see note below) +Documentation will be merged if it is an improvement on existing content, +represents a good-faith effort to follow the template and style standards, +and is believed to be accurate. + +Further needs for what would make the doc even better should be immediately addressed +in a follow-up MR or issue. + 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 @@ -400,15 +290,120 @@ 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. + 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` + +Every GitLab instance includes the documentation, which is available from `/help` +(`http://my-instance.com/help`), e.g., <https://gitlab.com/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. +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 +will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be +available online on 2018-09-15, but, as the feature freeze date has passed, if +the MR does not have a "pick into 11.3" label, the milestone has to be changed +to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, +with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab +11.4 onwards, but available on docs.gitlab.com on the same day it was merged. + +### Linking to `/help` + +When you're building a new feature, you may need to link the documentation +from GitLab, the application. This is normally done in files inside the +`app/views/` directory with the help of the `help_page_path` helper method. + +In its simplest form, the HAML code to generate a link to the `/help` page is: + +```haml += link_to 'Help page', help_page_path('user/permissions') +``` + +The `help_page_path` contains the path to the document you want to link to with +the following conventions: + +- it is relative to the `doc/` directory in the GitLab repository +- the `.md` extension must be omitted +- it must not end with a slash (`/`) + +Below are some special cases where should be used depending on the context. +You can combine one or more of the following: + +1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path` + method: + + ```haml + = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link') + ``` + +1. **Opening links in a new tab.** This should be the default behavior: + + ```haml + = link_to 'Help page', help_page_path('user/permissions'), target: '_blank' + ``` + +1. **Linking to a circle icon.** Usually used in settings where a long + description cannot be used, like near checkboxes. You can basically use + any font awesome icon, but prefer the `question-circle`: + + ```haml + = link_to icon('question-circle'), help_page_path('user/permissions') + ``` + +1. **Using a button link.** Useful in places where text would be out of context + with the rest of the page layout: + + ```haml + = link_to 'Help page', help_page_path('user/permissions'), class: 'btn btn-info' + ``` + +1. **Using links inline of some text.** + + ```haml + Description to #{link_to 'Help page', help_page_path('user/permissions')}. + ``` + +1. **Adding a period at the end of the sentence.** Useful when you don't want + the period to be part of the link: + + ```haml + = succeed '.' do + Learn more in the + = link_to 'Help page', help_page_path('user/permissions') + ``` + +### GitLab `/help` tests + +Several [rspec tests](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/features/help_pages_spec.rb) +are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) will work correctly from `/help`. +For example, [GitLab.com's `/help`](https://gitlab.com/help). + +CAUTION: **Caution:** +Because the rspec tests only run in a full pipeline, and not a special [docs-only pipeline](#branch-naming), it is possible +to merge changes that will break `master` from a merge request with a successful docs-only pipeline run. + +## Docs site architecture + +See the [Docs site architecture](site_architecture/index.md) page to learn +how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com), and +to review all the assets and libraries in use. + +### Global navigation + +See the [Global navigation](site_architecture/global_nav.md) doc for information +on how the left-side navigation menu is built and updated. ## Previewing the changes live @@ -418,18 +413,18 @@ To preview your changes to documentation locally, follow this 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 +- <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. +[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. +to run it. In the mini pipeline graph, you should see a `>>` icon. Clicking it will +reveal the `review-docs-deploy-manual` job. Click the play button to start the job.  @@ -451,16 +446,6 @@ preview the changes. The docs URL can be found in two places: - 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 @@ -472,9 +457,21 @@ 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 hot details, here's what's really happening: +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) @@ -507,157 +504,151 @@ The following GitLab features are used among others: - [Artifacts](../../ci/yaml/README.md#artifacts) - [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) -## GitLab `/help` - -Every GitLab instance includes the documentation, which is available from `/help` -(`http://my-instance.com/help`), e.g., <https://gitlab.com/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 -to the MR. - -For instance, let's say your merge request has a milestone set to 11.3, which -will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be -available online on 2018-09-15, but, as the feature freeze date has passed, if -the MR does not have a "pick into 11.3" label, the milestone has to be changed -to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, -with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab -11.4 onwards, but available on docs.gitlab.com on the same day it was merged. - -### Linking to `/help` - -When you're building a new feature, you may need to link the documentation -from GitLab, the application. This is normally done in files inside the -`app/views/` directory with the help of the `help_page_path` helper method. - -In its simplest form, the HAML code to generate a link to the `/help` page is: - -```haml -= link_to 'Help page', help_page_path('user/permissions') -``` - -The `help_page_path` contains the path to the document you want to link to with -the following conventions: - -- it is relative to the `doc/` directory in the GitLab repository -- the `.md` extension must be omitted -- it must not end with a slash (`/`) - -Below are some special cases where should be used depending on the context. -You can combine one or more of the following: - -1. **Linking to an anchor link.** Use `anchor` as part of the `help_page_path` - method: - - ```haml - = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link') - ``` - -1. **Opening links in a new tab.** This should be the default behavior: - - ```haml - = link_to 'Help page', help_page_path('user/permissions'), target: '_blank' - ``` - -1. **Linking to a circle icon.** Usually used in settings where a long - description cannot be used, like near checkboxes. You can basically use - any font awesome icon, but prefer the `question-circle`: - - ```haml - = link_to icon('question-circle'), help_page_path('user/permissions') - ``` - -1. **Using a button link.** Useful in places where text would be out of context - with the rest of the page layout: - - ```haml - = link_to 'Help page', help_page_path('user/permissions'), class: 'btn btn-info' - ``` - -1. **Using links inline of some text.** +## Testing - ```haml - Description to #{link_to 'Help page', help_page_path('user/permissions')}. - ``` +We treat documentation as code, thus have implemented some testing. +Currently, the following tests are in place: -1. **Adding a period at the end of the sentence.** Useful when you don't want - the period to be part of the link: +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. +1. In a full pipeline, tests for [`/help`](#gitlab-help-tests). - ```haml - = succeed '.' do - Learn more in the - = link_to 'Help page', help_page_path('user/permissions') - ``` +### Linting -## General Documentation vs Technical Articles +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. -### General documentation +The following are some suggested linters you can install locally and sample configuration: -General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings. +- [`proselint`](#proselint) +- [`markdownlint`](#markdownlint) -### Technical Articles +NOTE: **Note:** +This list does not limit what other linters you can add to your local documentation writing toolchain. -Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found. +#### `proselint` -They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives. +`proselint` checks for common problems with English prose. It provides a + [plethora of checks](http://proselint.com/checks/) that are helpful for technical writing. -A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab. +`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: -They should be placed in a new directory named `/article-title/index.md` under a topic-related folder, and their images should be placed in `/article-title/img/`. For example, a new article on GitLab Pages should be placed in `doc/user/project/pages/article-title/` and a new article on GitLab CI/CD should be placed in `doc/ci/examples/article-title/`. +```sh +cd doc +proselint **/*.md +``` -#### Types of Technical Articles +`proselint` can also be run from within editors using plugins. For example, the following plugins + are available: -- **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 +- [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) -#### Understanding guides, tutorials, and technical overviews +##### Sample `proselint` configuration -Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`. +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: -A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them. +```json +{ + "checks": { + "typography.symbols": false, + "misc.phrasal_adjectives": false + } +} +``` -- Live example: "[Static sites and GitLab Pages domains (Part 1)](../../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../../user/project/pages/getting_started_part_four.md)" +A file with `proselint` configuration must be placed in a +[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`. -A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B. -It does not only describes steps 2 and 3, but also shows you how to accomplish them. +#### `markdownlint` -- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) +`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases)) + are followed for Markdown syntax. + Our [Documentation Style Guide](styleguide.md) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) + elaborate on which choices must be made when selecting Markdown syntax for + GitLab documentation. This tool helps catch deviations from those guidelines. -A **technical overview** is a description of what a certain feature is, and what it does, but does not walk -through the process of how to use it systematically. +`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: -- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/) +```sh +cd doc +markdownlint **/*.md +``` -#### Special format +`markdownlint` can also be run from within editors using plugins. For example, the following plugins + are available: -Every **Technical Article** contains a frontmatter at the beginning of the doc -with the following information: +- [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) -- **Type of article** (user guide, admin guide, technical overview, tutorial) -- **Knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced) -- **Author's name** and **GitLab.com handle** -- **Publication date** (ISO format YYYY-MM-DD) +##### Sample `markdownlint` configuration -For example: +The following sample `markdownlint` configuration modifies the available default rules to: +- Adhere to the [Documentation Style Guide](styleguide.md). +- Apply conventions found in the GitLab documentation. +- Allow the flexibility of using some inline HTML. -```yaml ---- -author: John Doe -author_gitlab: johnDoe -level: beginner -article_type: user guide -date: 2017-02-01 ---- +```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 +} ``` -#### Technical Articles - Writing Method +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`. -Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team. +## Danger Bot -[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 +GitLab uses [Danger](https://github.com/danger/danger) for some elements in +code review. For docs changes in merge requests, whenever a change to files under `/doc` +is made, Danger Bot leaves a comment with further instructions about the documentation +process. This is configured in the Dangerfile in the GitLab CE and EE repo under +[/danger/documentation/](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/danger/documentation). diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md new file mode 100644 index 00000000000..62ca7d6c805 --- /dev/null +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -0,0 +1,342 @@ +--- +description: "Learn how GitLab docs' global navigation works and how to add new items." +--- + +# Global navigation + +> [Introduced](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/362) +in November 2018 for GitLab 11.6. + +The global nav adds to the left sidebar the ability to +navigate and explore the contents of GitLab's documentation. + +The global nav should be maintained consistent through time to allow the +users to locate their most-visited links easily to facilitate navigation. +Therefore, any updates must be carefully considered by the technical writers. + +## Adding new items to the global nav + +To add a new doc to the nav, first and foremost, check with the technical writing team: + +- If it's applicable +- What's the exact position the doc will be added to the nav + +Once you get their approval and their guidance in regards to the position on the nav, +read trhough this page to understand how it works, and submit a merge request to the +docs site, adding the doc you wish to include in the nav into the +[global nav data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml). + +Don't forget to ask a technical writer to review your changes before merging. + +## How it works + +The global nav has 3 components: + +- **Section** + - Category + - Doc + +The available sections are described on the table below: + +| Section | Description | +| ------------- | ------------------------------------------ | +| User | Documentation for the GitLab's user UI. | +| Administrator | Documentation for the GitLab's admin area. | +| Contributor | Documentation for developing GitLab. | + +The majority of the links available on the nav were added according to the UI. +The match is not perfect, as for some UI nav items the documentation doesn't +apply, and there are also other links to help the new users to discover the +documentation. The docs under **Administration** are ordered alphabetically +for clarity. + +To see the improvements planned, check the +[global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21). + +CAUTION: **Attention!** +**Do not** [add items](#adding-new-items-to-the-global-nav) to the global nav without +the consent of one of the technical writers. + +## Composition + +The global nav is built from two files: + +- [Data](#data-file) +- [Layout](#layout-file) + +The data file feeds the layout with the links to the docs. The layout organizes +the data among the nav in containers properly [styled](#css-classes). + +### Data file + +The [data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml) +is structured in three components: sections, categories, and docs. + +#### Sections + +Each section represents the higher-level nav item. It's composed by +title and URL: + +```yaml +sections: + - section_title: Text + section_url: 'link' +``` + +The section can stand alone or contain categories within. + +#### Categories + +Each category within a section composes the second level of the nav. +It includes the category title and link. It can stand alone in the nav or contain +a third level of sub-items. + +Example of section with one stand-alone category: + +```yaml +- section_title: Section title + section_url: 'section-link' + section_categories: + - category_title: Category title + category_url: 'category-link' +``` + +Example of section with two stand-alone categories: + +```yaml +- section_title: Section title + section_url: 'section-link' + section_categories: + - category_title: Category 1 title + category_url: 'category-1-link' + + - category_title: Category 2 title + category_url: 'category-2-link' +``` + +For clarity, **always** add a blank line between categories. + +If a category URL is not present in CE (it's an EE-only document), add the +attribute `ee_only: true` below the category link. Example: + +```yaml +- category_title: Category title + category_url: 'category-link' + ee_only: true +``` + +If the category links to an external URL, e.g., [GitLab Design System](https://design.gitlab.com), +add the attribute `external_url: true` below the category title. Example: + +```yaml +- category_title: GitLab Design System + category_url: 'https://design.gitlab.com' + external_url: true +``` + +#### Docs + +Each doc represents the third level of nav links. They must be always +added within a category. + +Example with one doc link: + +```yaml +- category_title: Category title + category_url: 'category-link' + docs: + - doc_title: Document title + doc_url: 'doc-link' +``` + +A category supports as many docs as necessary, but, for clarity, try to not +overpopulate a category. + +Example with multiple docs: + +```yaml +- category_title: Category title + category_url: 'category-link' + docs: + - doc_title: Document 1 title + doc_url: 'doc-1-link' + - doc_title: Document 2 title + doc_url: 'doc-2-link' +``` + +Whenever a document is only present in EE, add the attribute `ee-only: true` +below the doc link. Example: + +```yaml +- doc_title: Document 2 title + doc_url: 'doc-2-link' + ee_only: true +``` + +If you need to add a document in an external URL, add the attribute `external_url` +below the doc link: + +```yaml +- doc_title: Document 2 title + doc_url: 'doc-2-link' + external_url: true +``` + +All nav links are clickable. If the higher-level link does not have a link +of its own, it must link to its first sub-item link, mimicking GitLab's navigation. +This must be avoided so that we don't have duplicated links nor two `.active` links +at the same time. + +Example: + +```yaml +- category_title: Operations + category_url: 'user/project/integrations/prometheus_library/' + # until we have a link to operations, the first doc link is + # repeated in the category link + docs: + - doc_title: Metrics + doc_url: 'user/project/integrations/prometheus_library/' +``` + +#### Syntax + +For all components (sections, categories, and docs), **respect the indentation** +and the following syntax rules. + +##### Titles + +- Use sentence case, capitalizing feature names. +- There's no need to wrap the titles, unless there's a special char in it. E.g., + in `GitLab CI/CD`, there's a `/` present, therefore, it must be wrapped in quotes. + As convention, wrap the titles in double quotes: `category_title: "GitLab CI/CD"`. + +##### URLs + +- As convention, always wrap URLs in single quotes `'url'`. +- Always use relative paths against the home of CE and EE. Examples: + - For `https://docs.gitlab.com/ee/README.html`, the relative URL is `README.html`. + - For `https://docs.gitlab.com/ee/user/project/cycle_analytics.html`, the relative + URL is `user/project/cycle_analytics.html` +- For `README.html` files, add the complete path `path/to/README.html`. +- For `index.html` files, use the clean (canonical) URL: `path/to/`. +- For EE-only docs, use the same relative path, but add the attribute `ee_only: true` below + the `doc_url` or `category_url`, as explained above. This will guarantee that when + the user is looking at the CE docs, it will link to the EE docs. It also displays + an "info" icon on the CE nav to make the user aware that it's a different link. + +DANGER: **Important!** +All links present on the data file must end in `.html`, not `.md`. Do not +start any relative link with a forward slash `/`. + +Examples: + +```yaml +- category_title: Issues + category_url: 'user/project/issues/' + # note that the above URL does not start with a slash and + # does not include index.html at the end + + docs: + - doc_title: Service Desk + doc_url: 'user/project/service_desk.html' + ee_only: true + # note that the URL above ends in html and, as the + # document is EE-only, the attribute ee_only is set to true. +``` + +### Layout file (logic) + +The [layout](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/global_nav.html) +is fed by the [data file](#data-file), builds the global nav, and is rendered by the +[default](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/default.html) layout. + +There are three main considerations on the logic built for the nav: + +- [Path](#path): first-level directories underneath `docs.gitlab.com/`: + - `https://docs.gitlab.com/ce/` + - `https://docs.gitlab.com/ee/` + - `https://docs.gitlab.com/omnibus/` + - `https://docs.gitlab.com/runner/` + - `https://docs.gitlab.com/debug/` + - `https://docs.gitlab.com/*` +- [EE-only](#ee-only-docs): documentation only available in `/ee/`, not on `/ce/`, e.g.: + - `https://docs.gitlab.com/ee/user/group/epics/` + - `https://docs.gitlab.com/ee/user/project/security_dashboard.html` +- [Default URL](#default-url): between CE and EE docs, the default is `ee`, therefore, all docs + should link to `/ee/` unless if on `/ce/` linking internally to `ce`. + +#### Path + +To use relative paths in the data file, we defined the variable `dir` +from the root's first-child directory, which defines the path to build +all the nav links to other pages: + +```html +<% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %> +``` + +For instance, for `https://docs.gitlab.com/ce/user/index.html`, +`dir` == `ce`, and for `https://docs.gitlab.com/omnibus/README.html`, +`dir` == `omnibus`. + +#### Default URL + +The default and canonical URL for GitLab documentation is +`http://docs.gitlab.com/ee/`, thus, all links +in the docs site should link to `/ee/` except when linking +among `/ce/` docs themselves. + +Therefore, if the user is looking at `/ee/`, `/omnibus/`, +`/runner/`, or any other highest-level dir, the nav should +point to `/ee/` docs. + +On the other hand, if the user is looking at `/ce/` docs, +all the links in the CE nav should link internally to `/ce/` +files, except for [`ee-only` docs](#ee-only-docs). + + +```html +<% if dir != 'ce' %> + <a href="/ee/<%= sec[:section_url] %>">...</a> + <% else %> + <a href="/<%= dir %>/<%= sec[:section_url] %>">...</a> + <% end %> + ... +<% end %> +``` + +This also allows the nav to be displayed on other +highest-level dirs (`/omnibus/`, `/runner/`, etc), +linking them back to `/ee/`. + +The same logic is applied to all sections (`sec[:section_url]`), +categories (`cat[:category_url]`), and docs (`doc[:doc_url]`) URLs. + +#### `ee-only` docs + +If the user is looking at the CE nav, a given doc is present only +in `/ee/`, it's tagged in the data file by `ee-only`, linking it +directly to `/ee/`. + +```html +<% if dir == 'ce' && cat[:ee_only] %> + <a href="/ee/<%= cat[:category_url] %>">...</a> +<% end %> +``` + +To make it clear that it it's a different link, an icon is displayed +on the nav link indicating that the `ee-only` doc is not available in CE. + +The `ee-only` attribute is available for `categories` (`<% if dir == 'ce' && cat[:ee_only] %>`) +and `docs` (`<% if dir == 'ce' && doc[:ee_only] %>`), but not for `sections`. + +### CSS classes + +The nav is styled in the general `stylesheet.scss`. To change +its styles, keep them grouped for better development among the team. + +The URL components have their unique styles set by the CSS classes `.level-0`, +`.level-1`, and `.level-2`. To adjust the link's font size, padding, color, etc, +use these classes. This way we guarantee that the rules for each link do not conflict + with other rules in the stylesheets. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md new file mode 100644 index 00000000000..0ce5825fd61 --- /dev/null +++ b/doc/development/documentation/site_architecture/index.md @@ -0,0 +1,66 @@ +--- +description: "Learn how GitLab's documentation website is architectured." +--- + +# Documentation site architecture + +Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) +and deploy it to <https://docs.gitlab.com>. + +## Repository + +While the source of the documentation content is stored in GitLab's respective product +repositories, the source that is used to build the documentation site _from that content_ +is located at <https://gitlab.com/gitlab-com/gitlab-docs>. See the README there for +detailed information. + +## Assets + +To provide an optimized site structure, design, and a search-engine friendly +website, along with a discoverable documentation, we use a few assets for +the GitLab Documentation website. + +### Libraries + +- [Bootstrap 3.3 components](https://getbootstrap.com/docs/3.3/components/) +- [Bootstrap 3.3 JS](https://getbootstrap.com/docs/3.3/javascript/) +- [jQuery](https://jquery.com/) 3.2.1 +- [Clipboard JS](https://clipboardjs.com/) +- [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/) + +### SEO + +- [Schema.org](https://schema.org/) +- [Google Analytics](https://marketingplatform.google.com/about/analytics/) +- [Google Tag Manager](https://developers.google.com/tag-manager/) + +## Global nav + +To understand how the global nav (left sidebar) is built, please +read through the [global navigation](global_nav.md) doc. + +## Deployment + +The docs site is deployed to production with GitLab Pages, and previewed in +merge requests with Review Apps. + +The deployment aspects will be soon transfered from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md) +to this page. + +<!-- +## Repositories + +TBA + +## Search engine + +TBA + +## Versions + +TBA + +## Helpers + +TBA +--> diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 01068e23082..ee3bd5606a5 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -1,150 +1,164 @@ --- -description: Learn the how to correctly structure GitLab documentation. +description: What to include in GitLab documentation pages. --- -# Documentation structure +# Documentation structure and template -For consistency throughout the documentation, it's important to maintain the same -structure among the docs. +This document will help you determine how to structure a page within GitLab's +documentation and what content to include. These standards help ensure consistency +and completeness throughout the documentation, and they make it easier to contribute. -Before getting started, read through the following docs: +Before getting started, familiarize yourself with [GitLab's Documentation guidelines](index.md) +and the section on Content in the [Style Guide](styleguide.md). -- [Contributing to GitLab documentation](index.md#contributing-to-docs) -- [Merge requests for GitLab documentation](index.md#merge-requests-for-gitlab-documentation) -- [Branch naming for docs-only changes](index.md#branch-naming) -- [Documentation directory structure](index.md#documentation-directory-structure) -- [Documentation style guidelines](styleguide.md) -- [Documentation workflow](workflow.md) +## Components of a documentation page -## Documentation blurb +Most pages will be dedicated to a specifig GitLab feature or to a use case that involves +one or more features, potentially in conjunction with third-party tools. -Every document should include the following content in the following sequence: +Every feature or use case document should include the following content in the following sequence, +with exceptions and details noted below and in the template included on this page. -- **Feature name**: defines an intuitive name for the feature that clearly - 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.) -- **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. +- **Title**: Top-level heading with the feature name, or a use case name, which would start with +a verb, like Configuring, Enabling, etc. +- **Introduction**: A couple sentences about the subject matter and what's to be found on this page. +- **Overview** 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/configuration. +- **Requirements**: describes what software, configuration, account, or knowledge is required. +- **Instructions**: One or more sets of detailed instructions to follow. +- **Troubleshooting** guide (recommended but not required). -For additional details, see the subsections below, as well as the [Documentation template for new docs](#Documentation-template-for-new-docs). +For additional details on each, see the [template for new docs](#template-for-new-docs), +below. -### Feature overview and use cases +Note that you can include additional subsections, as appropriate, such as 'How it Works', 'Architecture', +and other logicial divisions such as pre- and post-deployment steps. -Every major feature (regardless if present in GitLab Community or Enterprise editions) -should present, at the beginning of the document, two main sections: **overview** and -**use cases**. Every GitLab EE-only feature should also contain these sections. - -**Overview**: as the name suggests, the goal here is to provide an overview of the feature. -Describe what is it, what it does, why it is important/cool/nice-to-have, -what problem it solves, and what you can do with this feature that you couldn't -do before. - -**Use cases**: provide at least two, ideally three, use cases for every major feature. -You should answer this question: what can you do with this feature/change? Use cases -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) -- 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 -overview there. - -> **Overview** and **use cases** are required to **every** Enterprise Edition feature, -and for every **major** feature present in Community Edition. - -### Discoverability - -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). - - 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. -- 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. - -## Documentation template for new docs +## Template for new docs To start a new document, respect the file tree and file name guidelines, as well as the style guidelines. Use the following template: ```md +<!--Follow the Style Guide when working on this document. https://docs.gitlab.com/ee/development/documentation/styleguide.html +When done, remove all of this commented-out text, except a commented-out Troubleshooting section, +which, if empty, can be left in place to encourage future use.--> --- -description: "short document description." # Up to ~200 chars long. They will be displayed in Google Search Snippets. +description: "Short document description." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. --- -# Feature Name **[TIER]** (1) +# Feature Name or Use Case Name **[TIER]** (1) +<!--If writing about a use case, drop the tier, and start with a verb, e.g. 'Configuring', 'Implementing', + the goal/scenario--> -> [Introduced](link_to_issue_or_mr) in GitLab Tier X.Y (2). +<!--For pages on newly introduced features, add the following line. If only some aspects of the feature have been introduced, specify what parts of the feature.--> +> [Introduced](link_to_issue_or_mr) in GitLab (Tier) X.Y (2). -A short description for the feature (can be the same used in the frontmatter's -`description`). +An introduction -- without its own additional header -- goes here. +Offer a very short description of the feature or use case, and what to expect on this page. +(You can reuse this content, or part of it, for the front matter's `description` at the top of this file). ## Overview -To write the feature overview, you should consider answering the following questions: +The feature overview should answer the following questions: -- What is it? +- What is this feature or use case? - Who is it for? - What is the context in which it is used and are there any prerequisites/requirements? -- What can the user do with it? (Be sure to consider multiple audiences, like GitLab admin and developer-user.) -- What are the benefits to using it over any alternatives? +- What can the audience do with this? (Be sure to consider all applicable audiences, like GitLab admin and developer-user.) +- What are the benefits to using this over any alternatives? ## Use cases -Describe one to three use cases for that feature. Give real-life examples. +Describe some use cases, typically in bulleted form. Include real-life examples for each. + +If the page itself is dedicated to a use case, this section can usually include more specific scenarios +for use (e.g. variations on the main use case), but if that's not applicable, the section can be omitted. + +Examples of use cases on feature pages: +- 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) ## Requirements -State any requirements, if any, for using the feature and/or following along with the tutorial. +State any requirements for using the feature and/or following along with the instructions. -The only assumption that is redundant and doesn't need to be mentioned is having an account -on GitLab. +These can include both: +- technical requirements (e.g. an account on a third party service, an amount of storage space, prior configuration of another feature) +- prerequisite knowledge (e.g. familiarity with certain GitLab features, cloud technologies) + +Link each one to an appropriate place for more information. ## Instructions -("Instructions" is not necessarily the name of the heading) +"Instructions" is usually not the name of the heading. +This is the part of the document where you can include one or more sets of instructions, each to accomplish a specific task. +Headers should describe the task the reader will achieve by following the instructions within, typically starting with a verb. +Larger instruction sets may have subsections covering specific phases of the process. - Write a step-by-step guide, with no gaps between the steps. - Start with an h2 (`##`), break complex steps into small steps using -subheadings h3 > h4 > h5 > h6. _Never skip the hierarchy level, such +subheadings h3 > h4 > h5 > h6. _Never skip a hierarchy level, such as h2 > h4_, as it will break the TOC and may affect the breadcrumbs. - Use short and descriptive headings (up to ~50 chars). You can use one -single heading `## How it works` for the instructions when the feature +single heading like `## Configuring X` for instructions when the feature 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 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. <!-- ## Troubleshooting -Add a troubleshooting guide when possible/applicable. --> -``` +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this 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 here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> + +--- 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 c43f91278de..cda66447c2c 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -1,26 +1,24 @@ --- -description: 'Writing styles, markup, formatting, and reusing regular expressions throughout the GitLab Documentation.' +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- -# Documentation style guidelines +# Documentation Style Guide The documentation style guide defines the markup structure used in GitLab documentation. Check the [documentation guidelines](index.md) for general development instructions. -Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +See the GitLab handbook for the [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). -For help adhering to the guidelines, see [Linting](index.md#linting). +For programmatic 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. + 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. @@ -28,65 +26,181 @@ 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 - -- 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. +### 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 [GitLab 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 + +These guidelines help toward the goal of having every user's search of documentation +yield a useful result, and ensuring content is helpful and easy to consume. + +- What to include: + - Any and all helpful information, processes, and tips for implementing, + using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) + for this information. + - 'Risky' or niche problem-solving steps. There is no reason to withhold these or + store them elsewhere; simply include them along with the rest of the docs including all necessary + detail, such as specific warnings and caveats about potential ramifications. + - Any content types/sources, if relevant to users or admins. You can freely + include presentations, videos, etc.; no matter who it was originally written for, + if it is helpful to any of our audiences, we can include it. If an outside source + that's under copyright, rephrase, or summarize and link out; do not copy and paste. + - All applicable subsections as described on the [structure and template](structure.md) page, + with files organized in the [correct directory](index.md#documentation-directory-structure). +- To ensure discoverability, link to each doc from its higher-level index page and other related pages. +- 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. - Do not duplicate information. -- Be brief and clear. -- Unless there's a logical reason not to, add documents in alphabetical order. +- Structure content in alphabetical order in tables, lists, etc., unless there is + a logical reason not to (for example, when mirroring the UI or an ordered sequence). + +## Language + +- Use inclusive language and avoid jargon, as well as uncommon + 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"). +- Be clear, concise, and stick to the goal of the doc. - 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"). + [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. "GitLab's Merge Requests support X." and "Create a new merge request for Z."). + +## Text -## Formatting +- 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 +### Tables overlapping the ToC -For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/). +By default, all tables have a width of 100% on docs.gitlab.com. +In a few cases, the table will overlap the table of contents (ToC). +For these cases, add an entry to the document's frontmatter to +render them displaying block. This will make sure the table +is displayed behind the ToC, scrolling horizontally: -### Ordered and unordered lists +```md +--- +table_display_block: true +--- +``` + +## 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._ | + +## List items + +- 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. + +**Markup:** - Use dashes (`-`) for unordered lists instead of asterisks (`*`). -- Use the number one (`1`) for ordered lists. +- 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 @@ -96,23 +210,21 @@ 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 + navigate to high-level directories, and always add the file name `file.md` at the end of the link with the `.md` extension, not `.html`. Example: instead of `[text](../../merge_requests/)`, use `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or, @@ -124,15 +236,24 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, write `Read more about [GitLab Issue Boards](LINK)`. +### Unlinking emails + +By default, all email addresses will render in an email tag on docs.gitlab.com. +To escape the code block and unlink email addresses, use two backticks: + +```md +`` example@email.com `` +``` + ## Navigation 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 -(e.g., `Navigate to your project's **Settings > CI/CD**` ). +- 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 @@ -141,13 +262,13 @@ 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. - Compress gifs with <https://ezgif.com/optimize> or similar tool. - Images should be used (only when necessary) to _illustrate_ the description -of a process, not to _replace_ it. + of a process, not to _replace_ it. - Max image size: 100KB (gifs included). - The GitLab docs do not support videos yet. @@ -164,13 +285,55 @@ Inside the document: - If a heading is placed right after an image, always add three dashes (`---`) between the image and the heading. +### Remove image shadow + +All images displayed on docs.gitlab.com have a box shadow by default. +To remove the box shadow, use the image class `.image-noshadow` applied +directly to an HTML `img` tag: + +```html +<img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow"> +``` + +## 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 + ``` + + ```text + Code for which no specific highlighting class is available. + ``` + ```` + +- To display raw markdown instead of rendered markdown, use four backticks on their own lines around the + markdown to display. See [example](https://gitlab.com/gitlab-org/gitlab-ce/blob/8c1991b9bb7e3b8d606481fdea316d633cfa5eb7/doc/development/documentation/styleguide.md#L275-287). +- 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 @@ -234,12 +397,61 @@ which renders in docs.gitlab.com to: If the text spans across multiple lines it's OK to split the line. -## Specific sections and terms +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} + +## Terms + +To maintain consistency through GitLab documentation, the following guides documentation authors +on agreed styles and usage of terms. + +### Describing UI elements + +The following are styles to follow when describing UI elements on a screen: + +- For elements with a visible label, use that label in bold with matching case. For example, `the **Cancel** button`. +- For elements with a tooltip or hover label, use that label in bold with matching case. For example, `the **Add status emoji** button`. -To mention and/or reference specific terms in GitLab, please follow the styles -below. +### Verbs for UI elements -### GitLab versions and tiers +The following are recommended verbs for specific uses. + +| Recommended | Used for | Alternatives | +|:------------|:---------------------------|:---------------------------| +| "click" | buttons, links, menu items | "hit", "press", "select" | +| "check" | checkboxes | "enable", "click", "press" | +| "select" | dropdowns | "pick" | +| "expand" | expandable sections | "open" | + +### Other Verbs + +| Recommended | Used for | Alternatives | +|:------------|:--------------------------------|:-------------------| +| "go" | making a browser go to location | "navigate", "open" | + +## GitLab versions and tiers - Every piece of documentation that comes with a new feature should declare the GitLab version that feature got introduced. Right below the heading add a @@ -264,7 +476,7 @@ below. > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. ``` -#### Early versions of EE +### 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)): @@ -277,7 +489,7 @@ For example: > [Introduced](<link-to-issue>) in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/). ``` -### Product badges +## Product badges When a feature is available in EE-only tiers, add the corresponding tier according to the feature availability: @@ -290,26 +502,34 @@ 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. -E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**. +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. + +For example: + +- `**[STARTER]**` renders as **[STARTER]** +- `**[STARTER ONLY]**` renders as **[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 +### How it works Introduced by [!244](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/244), the special markup `**[STARTER]**` will generate a `span` element to trigger the badges and tooltips (`<span class="badge-trigger starter">`). When the keyword "only" is added, the corresponding GitLab.com badge will not be displayed. +## Specific sections + +Certain styles should be applied to specific sections. Styles for specific sections are outlined below. + ### GitLab Restart There are many cases that a restart/reconfigure of GitLab is required. To @@ -317,7 +537,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. ``` @@ -348,8 +568,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 @@ -386,38 +606,15 @@ 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 - two methods -- 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 +- 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 + correctly. +- Different highlighting languages are used for each config in the code block. +- The [references](#references) guide is used for reconfigure/restart. -### Fake tokens - -There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real -tokens in documentation even if the probability of a token being exploited is -low. - -You can use the following fake tokens as examples. - -| **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` | - -### API +## API Here is a list of must-have items. Use them in the exact order that appears on this document. Further explanation is given below. @@ -433,91 +630,148 @@ on this document. Further explanation is given below. - Every method must have a cURL example. - Every method must have a response body (in JSON format). -#### Method description +### API topic template + +The following can be used as a template to get started: + +````md +## Descriptive title + +One or two sentence description of what endpoint does. + +```text +METHOD /endpoint +``` + +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:----------------------| +| `attribute` | datatype | yes/no | Detailed description. | +| `attribute` | datatype | yes/no | Detailed description. | + +Example request: + +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/endpoint?parameters' +``` + +Example response: + +```json +[ + { + } +] +``` +```` + +### Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a variable used in CI. It is strongly advised not to use real +tokens in documentation even if the probability of a token being exploited is +low. + +You can use the following fake tokens as examples. + +| Token type | Token value | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `<your_access_token>` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| 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` | + +### Method description 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 +### cURL commands - Use `https://gitlab.example.com/api/v4/` as an endpoint. -- Wherever needed use this personal access token: `9koXpg98eAheJpvBs5tK`. +- Wherever needed use this personal access token: `<your_access_token>`. - Always put the request first. `GET` is the default so you don't have to include it. - Use double quotes to the URL when it includes additional parameters. - Prefer to use examples using the personal access token and don't pass data of username and password. -| 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 | +| Methods | Description | +|:-------------------------------------------|:------------------------------------------------------| +| `-H "PRIVATE-TOKEN: <your_access_token>"` | 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 | -#### cURL Examples +### cURL Examples Below is a set of [cURL][] examples that you can use in the API documentation. -##### Simple cURL command +#### Simple cURL command Get the details of a group: ```bash -curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/gitlab-org +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/gitlab-org ``` -##### cURL example with parameters passed in the URL +#### cURL example with parameters passed in the URL Create a new project under the authenticated user's namespace: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects?name=foo" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?name=foo" ``` -##### Post data using cURL's --data +#### Post data using cURL's --data Instead of using `-X POST` and appending the parameters to the URI, you can use cURL's `--data` option. The example below will create a new project `foo` under the authenticated user's namespace. ```bash -curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects" +curl --data "name=foo" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" ``` -##### Post data using JSON content +#### Post data using JSON content > **Note:** In this example we create a new group. Watch carefully the single and double quotes. ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups ``` -##### Post data using form-data +#### Post data using form-data Instead of using JSON or urlencode you can use multipart/form-data which properly handles data encoding: ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys ``` The above example is run by and administrator and will add an SSH public key titled ssh-key to user's account which has an id of 25. -##### Escape special characters +#### Escape special characters Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended to escape them when possible. In the example below we create a new issue which @@ -525,19 +779,19 @@ contains spaces in its title. Observe how spaces are escaped using the `%20` ASCII code. ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude" ``` Use `%2F` for slashes (`/`). -##### Pass arrays to API calls +#### Pass arrays to API calls The GitLab API sometimes accepts arrays of strings or integers. For example, to restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and `example.net`, you would do something like this: ```bash -curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings ``` [cURL]: http://curl.haxx.se/ "cURL website" diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 52bc059a925..7c32c92b147 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -1,186 +1,10 @@ --- -description: Learn the process of shipping documentation for GitLab. +description: Learn the processes for contributing to GitLab's documentation. --- -# Documentation process at GitLab +# Documentation workflows at 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. -- Developers: author documentation and merge it on time (up to a week after -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. - -## Requirements - -Documentation must be delivered whenever: - -- A new feature is shipped -- There are changes to the UI -- A process, workflow, or previously documented feature is changed - -Documentation is not required when a feature is changed on the backend -only and does not directly affect the way that any regular user or -administrator would interact with GitLab. - -NOTE: **Note:** -When refactoring documentation, it should be submitted in its own MR. -**Do not** join new features' MRs with refactoring existing docs, as they might have -different priorities. - -NOTE: **Note:** -[Smaller MRs are better](https://gitlab.com/gitlab-com/blog-posts/issues/185#note_4401010)! Do not mix subjects, and ship the smallest MR possible. - -### Documentation review process - -The docs shipped by the developer should be reviewed by the PM (for accuracy) and a Technical Writer (for clarity and structure). - -#### Documentation updates that require Technical Writer review - -Every documentation change that meets the criteria below must be reviewed by a Technical Writer -to ensure clarity and discoverability, and avoid redundancy, bad file locations, typos, broken links, etc. -Within the GitLab issue or MR, ping the relevant technical writer for the subject area. If you're not sure who that is, -ping any of them or all of them (`@gl\-docsteam`). - -A Technical Writer must review documentation updates that involve: - -- Docs introducing new features -- Changing documentation location -- Refactoring existing documentation -- Creating new documentation files - -If you need any help to choose the correct place for a doc, discuss a documentation -idea or outline, or request any other help, ping a Technical Writer on your issue, MR, -or on Slack in `#docs`. - -#### Skip the PM's review - -When there's a non-significant change to the docs, you can skip the review -of the PM. Add the same labels as you would for a regular doc change and -assign the correct milestone. In these cases, assign a Technical Writer -for approval/merge, or mention `@gl\-docsteam` in case you don't know -which Tech Writer to assign for. - -#### Skip the entire review - -When the MR only contains corrections to the content (typos, grammar, -broken links, etc), it can be merged without the PM's and Tech Writer's review. - -## Documentation structure - -Read through the [documentation structure](structure.md) docs for an overview. - -## Documentation workflow - -To follow a consistent workflow every month, documentation changes -involve the Product Managers, the developer who shipped the feature, -and the Technical Writing team. Each role is described below. - -### 1. Product Manager's role in the documentation process - -The Product Manager (PM) should add to the feature issue: - -- Feature name, overview/description, and use cases, for the [documentation blurb](structure.md#documentation-blurb) -- The documentation requirements for the developer working on the docs - - What new page, new subsection of an existing page, or other update to an existing page/subsection is needed. - - Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected - - Suggested title of any page or subsection, if applicable -- Label the issue with `Documentation`, `Deliverable`, `docs:P1`, and assign - the correct milestone - -### 2. Developer's role in the documentation process - -As a developer, or as a community contributor, you should ship the documentation -with the feature, as in GitLab the documentation is part of the product. - -The docs can either be shipped along with the MR introducing the code, or, -alternatively, created from a follow-up issue and MR. - -The docs should be shipped **by the feature freeze date**. Justified -exceptions are accepted, as long as the [following process](#documentation-shipped-late) -and the missed-deliverable due date (the 14th of each month) are both respected. - -#### Documentation shipped in the feature MR - -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 -- 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) -- Index: link the new doc or the new heading from the higher-level index -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 -- Assign the PM for review -- When done, mention the `@gl\-docsteam` in the MR asking for review -- **Due date**: feature freeze date and time - -#### Documentation shipped in a follow-up MR - -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) -- 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) -- Use the MR description template called "Documentation" -- Add the same labels and milestone as you did for the issue -- Assign the PM for review -- When done, mention the `@gl\-docsteam` in the MR asking for review -- **Due date**: feature freeze date and time - -#### Documentation shipped late - -Shipping late means that you are affecting the whole feature workflow -as well as other teams' priorities (PMs, tech writers, release managers, -release post reviewers), so every effort should be made to avoid this. - -If you did not ship the docs within the feature freeze, proceed as -[described above](#documentation-shipped-in-a-follow-up-mr) and, -besides the regular labels, include the labels `Pick into X.Y` and -`missed-deliverable` in the issue and the MR, and assign them the correct -milestone. - -The **due date** for **merging** `missed-deliverable` MRs is on the -**14th** of each month. - -### 3. Technical Writer's role in the documentation process - -- **Planning** - - Once an issue contains a Documentation label and the current milestone, a -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. - -- **Review** - A technical writer must review the documentation for: - - Clarity - - Relevance (make sure the content is appropriate given the impact of the feature) - - Location (make sure the doc is in the correct dir and has the correct name) - - Syntax, typos, and broken links - - Improvements to the content - - Accordance to the [docs style guide](styleguide.md) - -<!-- TBA: issue and MR description templates as part of the process --> - -<!-- -## New features vs feature updates - -- TBA: - - Describe the difference between new features and feature updates - - Creating a new doc vs updating an existing doc ---> +Documentation workflows at GitLab differ depending on the reason for the change. The two types of documentation changes are: +- [Feature-change documentation workflow](feature-change-workflow.md) - The documentation is being created or updated as part of the development and release of a new or enhanced feature. This process involves the developer of the feature (who includes new/updated documentation files as part of the same merge request containing the feature's code) and also involves the product manager and technical writer who are listed for the feature's [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). +- [Documentation improvement workflow](improvement-workflow.md) - All documentation additions not associated with a feature release. Documentation is being created or updated to improve accuracy, completeness, ease of use, or any reason other than a feature change. Anyone (and everyone) can contribute a merge request for this type of change at any time. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index f9e6efa2c30..e0985922443 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 @@ -729,6 +839,20 @@ For example there can be an `app/assets/javascripts/protected_branches/protected_branches_bundle.js` and an EE counterpart `ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js`. +The corresponding import statement would then look like this: + +```javascript +// app/assets/javascripts/protected_branches/protected_branches_bundle.js +import bundle from '~/protected_branches/protected_branches_bundle.js'; + +// ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js +// (only works in EE) +import bundle from 'ee/protected_branches/protected_branches_bundle.js'; + +// in CE: app/assets/javascripts/protected_branches/protected_branches_bundle.js +// in EE: ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js +import bundle from 'ee_else_ce/protected_branches/protected_branches_bundle.js'; +``` See the frontend guide [performance section](./fe_guide/performance.md) for information on managing page-specific javascript within EE. diff --git a/doc/development/emails.md b/doc/development/emails.md index 35ada35babe..8baf343b133 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -76,14 +76,32 @@ See the [Rails guides] for more info. ## Email namespace -If you need to implement a new feature which requires a new email handler, follow these rules: +As of GitLab 11.7, we support a new format for email handler addresses. This was done to +support catch-all mailboxes. - - You must choose a namespace. The namespace cannot contain `/` or `+`, and cannot match `\h{16}`. - - If your feature is related to a project, you will append the namespace **after** the project path, separated by a `+` - - If you have different actions in the namespace, you add the actions **after** the namespace separated by a `+`. The action name cannot contain `/` or `+`, , and cannot match `\h{16}`. - - You will register your handlers in `lib/gitlab/email/handler.rb` +If you need to implement a feature which requires a new email handler, follow these rules +for the format of the email key: -Therefore, these are the only valid formats for an email handler: +- Actions are always at the end, separated by `-`. For example `-issue` or `-merge-request` +- If your feature is related to a project, the key begins with the project identifiers (project path slug + and project id), separated by `-`. For example, `gitlab-org-gitlab-ce-20` +- Additional information, such as an author's token, can be added between the project identifiers and + the action, separated by `-`. For example, `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` +- You register your handlers in `lib/gitlab/email/handler.rb` + +Examples of valid email keys: + + - `gitlab-org-gitlab-ce-20-Author_Token12345678-issue` (create a new issue) + - `gitlab-org-gitlab-ce-20-Author_Token12345678-merge-request` (create a new merge request) + - `1234567890abcdef1234567890abcdef-unsubscribe` (unsubscribe from a conversation) + - `1234567890abcdef1234567890abcdef` (reply to a conversation) + +Please note that the action `-issue-` is used in GitLab Premium as the handler for the Service Desk feature. + +### Legacy format + +Although we continue to support the older legacy format, no new features should use a legacy format. +These are the only valid legacy formats for an email handler: - `path/to/project+namespace` - `path/to/project+namespace+action` diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md index ee0c2d534ff..52462a4bec9 100644 --- a/doc/development/fe_guide/components.md +++ b/doc/development/fe_guide/components.md @@ -1,18 +1,19 @@ # Components ## Contents -* [Dropdowns](#dropdowns) -* [Modals](#modals) + +- [Dropdowns](#dropdowns) +- [Modals](#modals) ## 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] 1. Add a specific class to the top level `.dropdown` element - ```Haml .dropdown.my-dropdown %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false } @@ -40,7 +41,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..e6aa0be671f 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> @@ -177,28 +177,28 @@ droplab.init().addData('trigger', [{ DropLab adds some CSS classes to help lower the barrier to integration. -For example, +For example: -* The `droplab-item-selected` css class is added to items that have been selected -either by a mouse click or by enter key selection. -* The `droplab-item-active` css class is added to items that have been selected -using arrow key navigation. -* You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example, -an `<li class="divider"></li>` list divider element that should not be interactive. +- The `droplab-item-selected` css class is added to items that have been selected + either by a mouse click or by enter key selection. +- The `droplab-item-active` css class is added to items that have been selected + using arrow key navigation. +- You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example, + an `<li class="divider"></li>` list divider element that should not be interactive. ## Internal events DropLab uses some custom events to help lower the barrier to integration. -For example, +For example: -* The `click.dl` event is fired when an `li` list item has been clicked. It is also -fired when a list item has been selected with the keyboard. It is also fired when a -`HookButton` button is clicked (a registered `button` tag or `a` tag trigger). -* The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. -* The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. -* The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. -* The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. +- The `click.dl` event is fired when an `li` list item has been clicked. It is also + fired when a list item has been selected with the keyboard. It is also fired when a + `HookButton` button is clicked (a registered `button` tag or `a` tag trigger). +- The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. +- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. +- The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. +- The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data. @@ -233,9 +233,9 @@ droplab.init(trigger, list, [droplabAjax], { ### Documentation -* [Ajax plugin](plugins/ajax.md) -* [Filter plugin](plugins/filter.md) -* [InputSetter plugin](plugins/input_setter.md) +- [Ajax plugin](plugins/ajax.md) +- [Filter plugin](plugins/filter.md) +- [InputSetter plugin](plugins/input_setter.md) ### Development diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md index 9c7e56fa448..b6a883ce6c4 100644 --- a/doc/development/fe_guide/droplab/plugins/ajax.md +++ b/doc/development/fe_guide/droplab/plugins/ajax.md @@ -8,10 +8,10 @@ Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `Dro `Ajax` requires 2 config values, the `endpoint` and `method`. -* `endpoint` should be a URL to the request endpoint. -* `method` should be `setData` or `addData`. -* `setData` completely replaces the dropdown with the response data. -* `addData` appends the response data to the current dropdown list. +- `endpoint` should be a URL to the request endpoint. +- `method` should be `setData` or `addData`. +- `setData` completely replaces the dropdown with the response data. +- `addData` appends the response data to the current dropdown list. ```html <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md index 0853ea4d320..ddc6a3386c7 100644 --- a/doc/development/fe_guide/droplab/plugins/filter.md +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -7,8 +7,8 @@ to the dropdown using a simple fuzzy string search of an input value. Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. -* `Filter` requires a config value for `template`. -* `template` should be the key of the objects within your data array that you want to compare +- `Filter` requires a config value for `template`. +- `template` should be the key of the objects within your data array that you want to compare to the user input string, for filtering. ```html diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index 94f3c8254a8..8e28a41f32e 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -6,9 +6,9 @@ Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. -* `InputSetter` requires a config value for `input` and `valueAttribute`. -* `input` should be the DOM element that you want to manipulate. -* `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value +- `InputSetter` requires a config value for `input` and `valueAttribute`. +- `input` should be the DOM element that you want to manipulate. +- `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value to update the `input` element with. You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. 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..3a3cb77f592 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -21,8 +21,8 @@ We also use [Axios][axios] to handle all of our network requests. We also utilize [webpack][webpack] to handle the bundling, minification, and compression of our assets. -Working with our frontend assets requires Node (v6.0 or greater) and Yarn -(v1.2 or greater). You can find information on how to install these on our +Working with our frontend assets requires Node (v8.10.0 or greater) and Yarn +(v1.10.0 or greater). You can find information on how to install these on our [installation guide][install]. ### Browser Support @@ -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. @@ -115,7 +118,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the ## [DropLab](droplab/droplab.md) Our internal `DropLab` dropdown library. -* [DropLab](droplab/droplab.md) -* [Ajax plugin](droplab/plugins/ajax.md) -* [Filter plugin](droplab/plugins/filter.md) -* [InputSetter plugin](droplab/plugins/input_setter.md) +- [DropLab](droplab/droplab.md) +- [Ajax plugin](droplab/plugins/ajax.md) +- [Filter plugin](droplab/plugins/filter.md) +- [InputSetter plugin](droplab/plugins/input_setter.md) diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index ef0eed786d2..e5a383c25f5 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -29,8 +29,8 @@ To improve the time to first render we are using lazy loading for images. This w the actual image source on the `data-src` attribute. After the HTML is rendered and JavaScript is loaded, the value of `data-src` will be moved to `src` automatically if the image is in the current viewport. -* Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy` -* If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided. +- Prepare images in HTML for lazy loading by renaming the `src` attribute to `data-src` AND adding the class `lazy`. +- If you are using the Rails `image_tag` helper, all images will be lazy-loaded by default unless `lazy: false` is provided. If you are asynchronously adding content which contains lazy images then you need to call the function `gl.lazyLoader.searchLazyImages()` which will search for lazy images and load them if needed. 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..9c614e3468a 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -6,9 +6,9 @@ To get started with Vue, read through [their documentation][vue-docs]. What is described in the following sections can be found in these examples: -- web ide: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/ide/stores -- security products: https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports -- registry: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/registry/stores +- web ide: <https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/ide/stores> +- security products: <https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports> +- registry: <https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/registry/stores> ## Vue architecture @@ -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..4b60ec80cb8 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` + - `POST`: `createSomething` + - `PUT`: `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 @@ -135,6 +137,7 @@ By following this pattern we guarantee: #### Dispatching actions To dispatch an action from a component, use the `mapActions` helper: + ```javascript import { mapActions } from 'vuex'; @@ -202,6 +205,7 @@ export const getUsersWithPets = (state, getters) => { ``` To access a getter from a component, use the `mapGetters` helper: + ```javascript import { mapGetters } from 'vuex'; @@ -224,6 +228,7 @@ export const ADD_USER = 'ADD_USER'; ### How to include the store in your application The store should be included in the main component of your application: + ```javascript // app.vue import store from 'store'; // it will include the index.js file @@ -297,12 +302,12 @@ export default { ```javascript // component.vue - + // bad created() { this.$store.commit('mutation'); } - + // good created() { this.$store.dispatch('action'); @@ -362,7 +367,8 @@ Because we're currently using [`babel-plugin-rewire`](https://github.com/speedsk `[vuex] actions should be function or object with "handler" function` To prevent this error from happening, you need to export an empty function as `default`: -``` + +```javascript // getters.js or actions.js // prevent babel-plugin-rewire from generating an invalid default during karma tests diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 0f1f079bdb4..b6161cd6163 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. @@ -112,3 +112,16 @@ feature flag. You can stub a feature flag as follows: ```ruby stub_feature_flags(my_feature_flag: false) ``` + +## Enabling a feature flag (in development) + +In the rails console (`rails c`), enter the following command to enable your feature flag + +```ruby +Feature.enable(:feature_flag_name) +``` + +## Enabling a feature flag (in production) + +Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md). + diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 6e014e8c751..b90dc90e424 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -4,15 +4,15 @@ We use the [CarrierWave] gem to handle file upload, store and retrieval. There are many places where file uploading is used, according to contexts: -* System +- System - Instance Logo (logo visible in sign in/sign up pages) - Header Logo (one displayed in the navigation bar) -* Group +- Group - Group avatars -* User +- User - User avatars - User snippet attachments -* Project +- Project - Project avatars - Issues/MR/Notes Markdown attachments - Issues/MR/Notes Legacy Markdown attachments @@ -52,7 +52,7 @@ hash of the project ID instead, if project migrates to the new approach (introdu ### Path segments -Files are stored at multiple locations and use different path schemes. +Files are stored at multiple locations and use different path schemes. All the `GitlabUploader` derived classes should comply with this path segment schema: ``` @@ -61,7 +61,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<gitlab_root>/public/` | `uploads/-/system/` | `user/avatar/:id/` | `:filename` | | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | | `CarrierWave.root` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | `CarrierWave::Uploader#store_dir` | | +| | `CarrierWave::Uploader#store_dir` | | | FileUploader | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | @@ -69,7 +69,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<gitlab_root>/shared/` | `snippets/` | `:secret/` | `:filename` | | ----------------------- + ------------------------- + --------------------------------- + -------------------------------- | | `CarrierWave.root` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | `CarrierWave::Uploader#store_dir` | | +| | `CarrierWave::Uploader#store_dir` | | | | | `FileUploader#upload_path | | ObjectStore::Concern (store = remote) @@ -77,7 +77,7 @@ All the `GitlabUploader` derived classes should comply with this path segment sc | `<bucket_name>` | <ignored> | `user/avatar/:id/` | `:filename` | | ----------------------- + ------------------------- + ----------------------------------- + -------------------------------- | | `#fog_dir` | `GitlabUploader.base_dir` | `GitlabUploader#dynamic_segment` | `CarrierWave::Uploader#filename` | -| | | `ObjectStorage::Concern#store_dir` | | +| | | `ObjectStorage::Concern#store_dir` | | | | | `ObjectStorage::Concern#upload_path | ``` diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 32beafad307..d5fc403bf8b 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -128,7 +128,26 @@ to manually run `make` again. Note that CI tests will not use your locally modified version of Gitaly. To use a custom Gitaly version in CI you need to update GITALY_SERVER_VERSION. You can use the format `=revision` to use a -non-tagged commit from https://gitlab.com/gitlab-org/gitaly in CI. +non-tagged commit from <https://gitlab.com/gitlab-org/gitaly> in CI. + +To use a different Gitaly repository, e.g., if your changes are present +on a fork, you can specify a `GITALY_REPO_URL` environment variable when +running tests: + +```shell +GITALY_REPO_URL=https://gitlab.com/nick.thomas/gitaly bundle exec rspec spec/lib/gitlab/git/repository_spec.rb +``` + +If your fork of Gitaly is private, you can generate a [Deploy Token](../user/project/deploy_tokens/index.md) +and specify it in the URL: + +```shell +GITALY_REPO_URL=https://gitlab+deploy-token-1000:token-here@gitlab.com/nick.thomas/gitaly bundle exec rspec spec/lib/gitlab/git/repository_spec.rb +``` + +To use a custom Gitaly repository in CI, for instance if you want your +GitLab fork to always use your own Gitaly fork, set `GITALY_REPO_URL` +as a [CI environment variable](../ci/variables/README.md#variables). --- diff --git a/doc/development/github_importer.md b/doc/development/github_importer.md index 0d558583bb8..5445f36b9fa 100644 --- a/doc/development/github_importer.md +++ b/doc/development/github_importer.md @@ -13,20 +13,20 @@ or Rake tasks. The parallel importer on the other hand uses Sidekiq. ## Requirements -* GitLab CE 10.2.0 or newer. -* Sidekiq workers that process the `github_importer` and +- GitLab CE 10.2.0 or newer. +- Sidekiq workers that process the `github_importer` and `github_importer_advance_stage` queues (this is enabled by default). -* Octokit (used for interacting with the GitHub API) +- Octokit (used for interacting with the GitHub API). ## Code structure The importer's codebase is broken up into the following directories: -* `lib/gitlab/github_import`: this directory contains most of the code such as +- `lib/gitlab/github_import`: this directory contains most of the code such as the classes used for importing resources. -* `app/workers/gitlab/github_import`: this directory contains the Sidekiq +- `app/workers/gitlab/github_import`: this directory contains the Sidekiq workers. -* `app/workers/concerns/gitlab/github_import`: this directory contains a few +- `app/workers/concerns/gitlab/github_import`: this directory contains a few modules reused by the various Sidekiq workers. ## Architecture overview @@ -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. @@ -188,8 +188,8 @@ projects get imported the fewer GitHub API calls will be needed. The code for this resides in: -* `lib/gitlab/github_import/user_finder.rb` -* `lib/gitlab/github_import/caching.rb` +- `lib/gitlab/github_import/user_finder.rb` +- `lib/gitlab/github_import/caching.rb` ## Mapping labels and milestones @@ -204,6 +204,6 @@ project that is being imported. The code for this resides in: -* `lib/gitlab/github_import/label_finder.rb` -* `lib/gitlab/github_import/milestone_finder.rb` -* `lib/gitlab/github_import/caching.rb` +- `lib/gitlab/github_import/label_finder.rb` +- `lib/gitlab/github_import/milestone_finder.rb` +- `lib/gitlab/github_import/caching.rb` diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 84dea7ce9aa..1b9ebb50c29 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -92,17 +92,17 @@ 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 -* Because it is not isolated therefore it might be broken at times. -* Because it doesn't work whenever the method we want to stub was defined +- Because it is not isolated therefore it might be broken at times. +- Because it doesn't work whenever the method we want to stub was defined in a prepended module, which is very likely the case in EE. We could see 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/externalization.md b/doc/development/i18n/externalization.md index 6323275426f..00db58a45a2 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -228,6 +228,16 @@ This makes use of [`Intl.DateTimeFormat`]. [`Intl.DateTimeFormat`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat +- In Ruby/HAML, we have two ways of adding format to dates and times: + + 1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for +[dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261). + If you need to add a new format, because other parts of the code could benefit from it, + you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file. + 2. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats + defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time + specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view). + ## Best practices ### Splitting sentences diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 5e13c725e15..ac910e80a89 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 + - David Planella - [GitLab](https://gitlab.com/dplanella), [Crowdin](https://crowdin.com/profile/dplanella) - Chinese Simplified - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) - Chinese Traditional @@ -14,12 +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 @@ -31,18 +57,40 @@ are very appreciative of the work done by translators and proofreaders! - 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) + - Jeongwhan Choi - [GitLab](https://gitlab.com/jeongwhanchoi), [Crowdin](https://crowdin.com/profile/jeongwhanchoi) +- Mongolian + - Proofreaders needed. +- Norwegian Bokmal + - Proofreaders needed. - Polish - Filip Mech - [GitLab](https://gitlab.com/mehenz), [Crowdin](https://crowdin.com/profile/mehenz) + - Maksymilian Roman - [GitLab](https://gitlab.com/villaincandle), [Crowdin](https://crowdin.com/profile/villaincandle) +- 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 @@ -74,6 +122,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/import_export.md b/doc/development/import_export.md new file mode 100644 index 00000000000..71db1abb201 --- /dev/null +++ b/doc/development/import_export.md @@ -0,0 +1,352 @@ +# Import/Export development documentation + +Troubleshooing and general development guidelines and tips for the [Import/Export feature](../user/project/settings/import_export.md). + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> This document is originally based on the [Import/Export 201 presentation available on YouTube](https://www.youtube.com/watch?v=V3i1OfExotE). + +## Troubleshooting commands + +Finds information about the status of the import and further logs using the JID: + +```ruby +# Rails console +Project.find_by_full_path('group/project').import_state.slice(:jid, :status, :last_error) +> {"jid"=>"414dec93f941a593ea1a6894", "status"=>"finished", "last_error"=>nil} +``` + +```bash +# Logs +grep JID /var/log/gitlab/sidekiq/current +grep "Import/Export error" /var/log/gitlab/sidekiq/current +grep "Import/Export backtrace" /var/log/gitlab/sidekiq/current +``` + +## Troubleshooting performance issues + +Read through the current performance problems using the Import/Export below. + +### OOM errors + +Out of memory (OOM) errors are normally caused by the [Sidekiq Memory Killer](https://docs.gitlab.com/ee/administration/operations/sidekiq_memory_killer.html): + +```bash +SIDEKIQ_MEMORY_KILLER_MAX_RSS = 2GB in GitLab.com +``` + +An import status `started`, and the following sidekiq logs will signal a memory issue: + +```bash +WARN: Work still in progress <struct with JID> +``` + +### Timeouts + +Timeout errors occur due to the `StuckImportJobsWorker` marking the process as failed: + +```ruby +class StuckImportJobsWorker + include ApplicationWorker + include CronjobQueue + + IMPORT_JOBS_EXPIRATION = 15.hours.to_i + + def perform + import_state_without_jid_count = mark_import_states_without_jid_as_failed! + import_state_with_jid_count = mark_import_states_with_jid_as_failed! + ... +``` + +```bash +Marked stuck import jobs as failed. JIDs: xyz +``` + +``` + +-----------+ +-----------------------------------+ + |Export Job |--->| Calls ActiveRecord `as_json` and | + +-----------+ | `to_json` on all project models | + +-----------------------------------+ + + +-----------+ +-----------------------------------+ + |Import Job |--->| Loads all JSON in memory, then | + +-----------+ | inserts into the DB in batches | + +-----------------------------------+ +``` + +### Problems and solutions + +| Problem | Possible solutions | +| -------- | -------- | +| [Slow JSON](https://gitlab.com/gitlab-org/gitlab-ce/issues/54084) loading/dumping models from the database | [split the worker](https://gitlab.com/gitlab-org/gitlab-ce/issues/54085) | +| | Batch export +| | Optimize SQL +| | Move away from `ActiveRecord` callbacks (difficult) +| High memory usage (see also some [analysis](https://gitlab.com/gitlab-org/gitlab-ce/issues/35389) | DB Commit sweet spot that uses less memory | +| | [Netflix Fast JSON API](https://github.com/Netflix/fast_jsonapi) may help | +| | Batch reading/writing to disk and any SQL + +### Temporary solutions + +While the performance problems are not tackled, there is a process to workaround +importing big projects, using a foreground import: + +[Foreground import](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5384) of big projects for customers. +(Using the import template in the [infrastructure tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/)) + +## Security + +The Import/Export feature is constantly updated (adding new things to export), however +the code hasn't been refactored in a long time. We should perform a [code audit](https://gitlab.com/gitlab-org/gitlab-ce/issues/42135) +to make sure its dynamic nature does not increase the number of security concerns. + +### Security in the code + +Some of these classes provide a layer of security to the Import/Export. + +The `AttributeCleaner` removes any prohibited keys: + +```ruby +# AttributeCleaner +# Removes all `_ids` and other prohibited keys + class AttributeCleaner + ALLOWED_REFERENCES = RelationFactory::PROJECT_REFERENCES + RelationFactory::USER_REFERENCES + ['group_id'] + + def clean + @relation_hash.reject do |key, _value| + prohibited_key?(key) || !@relation_class.attribute_method?(key) || excluded_key?(key) + end.except('id') + end + + ... + +``` + +The `AttributeConfigurationSpec` checks and confirms the addition of new columns: + +```ruby +# AttributeConfigurationSpec +<<-MSG + It looks like #{relation_class}, which is exported using the project Import/Export, has new attributes: + + Please add the attribute(s) to SAFE_MODEL_ATTRIBUTES if you consider this can be exported. + Otherwise, please blacklist the attribute(s) in IMPORT_EXPORT_CONFIG by adding it to its correspondent + model in the +excluded_attributes+ section. + + SAFE_MODEL_ATTRIBUTES: #{File.expand_path(safe_attributes_file)} + IMPORT_EXPORT_CONFIG: #{Gitlab::ImportExport.config_file} +MSG +``` + +The `ModelConfigurationSpec` checks and confirms the addition of new models: + +```ruby +# ModelConfigurationSpec +<<-MSG + New model(s) <#{new_models.join(',')}> have been added, related to #{parent_model_name}, which is exported by + the Import/Export feature. + + If you think this model should be included in the export, please add it to `#{Gitlab::ImportExport.config_file}`. + + Definitely add it to `#{File.expand_path(ce_models_yml)}` + #{"or `#{File.expand_path(ee_models_yml)}` if the model/associations are EE-specific\n" if ee_models_hash.any?} + to signal that you've handled this error and to prevent it from showing up in the future. +MSG +``` + +The `ExportFileSpec` detects encrypted or sensitive columns: + +```ruby +# ExportFileSpec +<<-MSG + Found a new sensitive word <#{key_found}>, which is part of the hash #{parent.inspect} + If you think this information shouldn't get exported, please exclude the model or attribute in + IMPORT_EXPORT_CONFIG. + + Otherwise, please add the exception to +safe_list+ in CURRENT_SPEC using #{sensitive_word} as the + key and the correspondent hash or model as the value. + + Also, if the attribute is a generated unique token, please add it to RelationFactory::TOKEN_RESET_MODELS + if it needs to be reset (to prevent duplicate column problems while importing to the same instance). + + IMPORT_EXPORT_CONFIG: #{Gitlab::ImportExport.config_file} + CURRENT_SPEC: #{__FILE__} +MSG +``` + +## Versioning + +Import/Export does not use strict SemVer, since it has frequent constant changes +during a single GitLab release. It does require an update when there is a breaking change. + +```ruby +# ImportExport +module Gitlab + module ImportExport + extend self + + # For every version update, the version history in import_export.md has to be kept up to date. + VERSION = '0.2.4' +``` + +## Version history + +The [current version history](../user/project/settings/import_export.md) also displays the equivalent GitLab version +and it is useful for knowing which versions won't be compatible between them. + +| GitLab version | Import/Export version | +| ---------------- | --------------------- | +| 11.1 to current | 0.2.4 | +| 10.8 | 0.2.3 | +| 10.4 | 0.2.2 | +| ... | ... | +| 8.10.3 | 0.1.3 | +| 8.10.0 | 0.1.2 | +| 8.9.5 | 0.1.1 | +| 8.9.0 | 0.1.0 | + +### When to bump the version up + +We will have to bump the verision if we rename model/columns or perform any format +modifications in the JSON structure or the file structure of the archive file. + +We do not need to bump the version up in any of the following cases: + +- Add a new column or a model +- Remove a column or model (unless there is a DB constraint) +- Export new things (such as a new type of upload) + + +Every time we bump the version, the integration specs will fail and can be fixed with: + +```bash +bundle exec rake gitlab:import_export:bump_version +``` + +### Renaming columns or models + +This is a relatively common occurence that will require a version bump. + +There is also the _RC problem_ - GitLab.com runs an RC, prior to any customers, +meaning that we want to bump the version up in the next version (or patch release). + +For example: + +1. Add rename to `RelationRenameService` in X.Y +2. Remove it from `RelationRenameService` in X.Y + 1 +3. Bump Import/Export version in X.Y + 1 + +```ruby +module Gitlab + module ImportExport + class RelationRenameService + RENAMES = { + 'pipelines' => 'ci_pipelines' # Added in 11.6, remove in 11.7 + }.freeze +``` + +## A quick dive into the code + +### Import/Export configuration (`import_export.yml`) + +The main configuration `import_export.yml` defines what models can be exported/imported. + +Model relationships to be included in the project import/export: + +```yaml +project_tree: + - labels: + :priorities + - milestones: + - events: + - :push_event_payload + - issues: + - events: + - ... +``` + +Only include the following attributes for the models specified: + +```yaml +included_attributes: + user: + - :id + - :email + ... + +``` + +Do not include the following attributes for the models specified: + +```yaml +excluded_attributes: + project: + - :name + - :path + - ... +``` + +Extra methods to be called by the export: + +```yaml +# Methods +methods: + labels: + - :type + label: + - :type +``` + +### Import + +The import job status moves from `none` to `finished` or `failed` into different states: + +_import\_status_: none -> scheduled -> started -> finished/failed + +While the status is `started` the `Importer` code processes each step required for the import. + +```ruby +# ImportExport::Importer +module Gitlab + module ImportExport + class Importer + def execute + if import_file && check_version! && restorers.all?(&:restore) && overwrite_project + project_tree.restored_project + else + raise Projects::ImportService::Error.new(@shared.errors.join(', ')) + end + rescue => e + raise Projects::ImportService::Error.new(e.message) + ensure + remove_import_file + end + + def restorers + [repo_restorer, wiki_restorer, project_tree, avatar_restorer, + uploads_restorer, lfs_restorer, statistics_restorer] + end +``` + +The export service, is similar to the `Importer`, restoring data instead of saving it. + +### Export + +```ruby +# ImportExport::ExportService +module Projects + module ImportExport + class ExportService < BaseService + + def save_all! + if save_services + Gitlab::ImportExport::Saver.save(project: project, shared: @shared) + notify_success + else + cleanup_and_notify_error! + end + end + + def save_services + [version_saver, avatar_saver, project_tree_saver, uploads_saver, repo_saver, + wiki_repo_saver, lfs_saver].all?(&:save) + end +``` diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 7761f65d78a..5f95cf3707c 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -11,12 +11,12 @@ Instrumenting methods is done by using the `Gitlab::Metrics::Instrumentation` module. This module offers a few different methods that can be used to instrument code: -* `instrument_method`: instruments a single class method. -* `instrument_instance_method`: instruments a single instance method. -* `instrument_class_hierarchy`: given a Class this method will recursively +- `instrument_method`: instruments a single class method. +- `instrument_instance_method`: instruments a single instance method. +- `instrument_class_hierarchy`: given a Class this method will recursively instrument all sub-classes (both class and instance methods). -* `instrument_methods`: instruments all public and private class methods of a Module. -* `instrument_instance_methods`: instruments all public and private instance methods of a +- `instrument_methods`: instruments all public and private class methods of a Module. +- `instrument_instance_methods`: instruments all public and private instance methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` @@ -35,7 +35,7 @@ Using this method is in general preferred over directly calling the various instrumentation methods. Method instrumentation should be added in the initializer -`config/initializers/8_metrics.rb`. +`config/initializers/zz_metrics.rb`. ### Examples @@ -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 ee01c89e0ed..6f1baad3a2d 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -9,8 +9,8 @@ To measure the impact of a merge request you can use [Sherlock](profiling.md#sherlock). It's also highly recommended that you read the following guides: -* [Performance Guidelines](performance.md) -* [What requires downtime?](what_requires_downtime.md) +- [Performance Guidelines](performance.md) +- [What requires downtime?](what_requires_downtime.md) ## Impact Analysis diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 6f31e5b82e5..98b54684d39 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -40,7 +40,7 @@ migrations _unless_ schema changes are absolutely required to solve a problem. ## What Requires Downtime? The document ["What Requires Downtime?"](what_requires_downtime.md) specifies -various database operations, such as +various database operations, such as - [adding, dropping, and renaming columns](what_requires_downtime.md#adding-columns) - [changing column constraints and types](what_requires_downtime.md#changing-column-constraints) @@ -59,15 +59,15 @@ the migrations that _do_ require downtime. To tag a migration, add the following two constants to the migration class' body: -* `DOWNTIME`: a boolean that when set to `true` indicates the migration requires +- `DOWNTIME`: a boolean that when set to `true` indicates the migration requires downtime. -* `DOWNTIME_REASON`: a String containing the reason for the migration requiring +- `DOWNTIME_REASON`: a String containing the reason for the migration requiring downtime. This constant **must** be set when `DOWNTIME` is set to `true`. For example: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] DOWNTIME = true DOWNTIME_REASON = 'This migration requires downtime because ...' @@ -95,7 +95,7 @@ migration. For this to work your migration needs to include the module `Gitlab::Database::MultiThreadedMigration`: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers include Gitlab::Database::MultiThreadedMigration end @@ -105,7 +105,7 @@ You can then use the method `with_multiple_threads` to perform work in separate threads. For example: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers include Gitlab::Database::MultiThreadedMigration @@ -134,12 +134,12 @@ 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 +class MyMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -167,7 +167,7 @@ the method `disable_ddl_transaction!` in the body of your migration class like so: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -187,18 +187,13 @@ 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. ```ruby -class Migration < ActiveRecord::Migration +class Migration < ActiveRecord::Migration[4.2] def change add_reference :model, :other_model, index: true, foreign_key: { on_delete: :cascade } @@ -221,7 +216,7 @@ For example, to add the column `foo` to the `projects` table with a default value of `10` you'd write the following: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -323,13 +318,38 @@ end Instead of using these methods one should use the following methods to store timestamps with timezones: -* `add_timestamps_with_timezone` -* `timestamps_with_timezone` +- `add_timestamps_with_timezone` +- `timestamps_with_timezone` This ensures all timestamps have a time zone specified. This in turn means existing timestamps won't suddenly use a different timezone when the system's timezone changes. It also makes it very clear which timezone was used in the first place. +## Storing JSON in database + +The Rails 5 natively supports `JSONB` (binary JSON) column type. +Example migration adding this column: + +```ruby +class AddOptionsToBuildMetadata < ActiveRecord::Migration[5.0] + DOWNTIME = false + + def change + add_column :ci_builds_metadata, :config_options, :jsonb + end +end +``` + +On MySQL the `JSON` and `JSONB` is translated to `TEXT 1MB`, as `JSONB` is PostgreSQL only feature. + +For above reason you have to use a serializer to provide a translation layer +in order to support PostgreSQL and MySQL seamlessly: + +```ruby +class BuildMetadata + serialize :config_options, Serializers::JSON # rubocop:disable Cop/ActiveRecordSerialize +end +``` ## Testing @@ -370,7 +390,7 @@ If you need more complex logic you can define and use models local to a migration. For example: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] class Project < ActiveRecord::Base self.table_name = 'projects' end diff --git a/doc/development/new_fe_guide/development/components.md b/doc/development/new_fe_guide/development/components.md index 899efb398cd..8ae58d30c35 100644 --- a/doc/development/new_fe_guide/development/components.md +++ b/doc/development/new_fe_guide/development/components.md @@ -6,16 +6,16 @@ We have a lot of graphing libraries in our codebase to render graphs. In an effo We chose D3 as our library going forward because of the following features: -* [Tree shaking webpack capabilities.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) -* [Compatible with vue.js as well as vanilla javascript.](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40) +- [Tree shaking webpack capabilities](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40). +- [Compatible with vue.js as well as vanilla javascript](https://github.com/d3/d3/blob/master/CHANGES.md#changes-in-d3-40). D3 is very popular across many projects outside of GitLab: -* [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html) -* [plot.ly](https://plot.ly/) -* [Droptask](https://www.droptask.com/) +- [The New York Times](https://archive.nytimes.com/www.nytimes.com/interactive/2012/02/13/us/politics/2013-budget-proposal-graphic.html) +- [plot.ly](https://plot.ly/) +- [Droptask](https://www.droptask.com/) Within GitLab, D3 has been used for the following notable features -* [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html) -* Contribution calendars +- [Prometheus graphs](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html) +- Contribution calendars diff --git a/doc/development/new_fe_guide/development/performance.md b/doc/development/new_fe_guide/development/performance.md index 244dfb3756f..640a8d64176 100644 --- a/doc/development/new_fe_guide/development/performance.md +++ b/doc/development/new_fe_guide/development/performance.md @@ -2,15 +2,15 @@ ## 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`. -There are 3 recommended high impact metrics to review on each page +There are 3 recommended high impact metrics to review on each page: -* [First visual change](https://developers.google.com/web/tools/lighthouse/audits/first-meaningful-paint) -* [Speed Index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) -* [Visual Complete 95%](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) +- [First visual change](https://developers.google.com/web/tools/lighthouse/audits/first-meaningful-paint) +- [Speed Index](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) +- [Visual Complete 95%](https://sites.google.com/a/webpagetest.org/docs/using-webpagetest/metrics/speed-index) For these metrics, lower numbers are better as it means that the website is more performant. diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index a9223ac6b0f..d74f141f08f 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -1,30 +1,255 @@ # Overview of Frontend Testing -## Types of tests in our codebase +Tests relevant for frontend development can be found at the following places: + +- `spec/javascripts/` which are run by Karma (command: `yarn karma`) and contain + - [frontend unit tests](#frontend-unit-tests) + - [frontend component tests](#frontend-component-tests) + - [frontend integration tests](#frontend-integration-tests) +- `spec/frontend/` which are run by Jest (command: `yarn jest`) 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) + +All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/` (see also [#52483](https://gitlab.com/gitlab-org/gitlab-ce/issues/52483)). + +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: + +- [Old testing guide](../../testing_guide/frontend_testing.html). +- [Notes on testing Vue components](../../fe_guide/vue.html#testing-vue-components). -* **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/`) +## Frontend unit tests -## RSpec: Ruby unit tests `/spec/**/*.rb` +Unit tests are on the lowest abstraction level and typically test functionality that is not directly perceivable by a user. -These tests are meant to unit test the ruby models, controllers and helpers. +### When to use unit tests -### When do we write/update these 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> -Whenever we create or modify any Ruby models, controllers or helpers we add/update corresponding tests. +<details> + <summary>Vuex actions</summary> + Any Vuex action needs to work in a consistent way independent of the component it is triggered from. +</details> ---- +<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> -## RSpec: Full feature tests `/spec/features/**/*.rb` +### When *not* to use unit tests -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). +<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> + +<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> -### When do we write/update these tests? +<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> -When we add a new feature, we write at least two tests covering the success and the failure scenarios. +## 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. + +See also the [RSpec testing guidelines](../../testing_guide/best_practices.md#rspec). + +### 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 +273,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. - -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. +## Test helpers -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,12 +298,12 @@ 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`. -* `createComponentWithStore` -* `mountComponentWithStore` +- `createComponentWithStore` +- `mountComponentWithStore` Examples of usage: @@ -133,6 +334,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 +342,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/ + +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/modules/index.md b/doc/development/new_fe_guide/modules/index.md index 0a7f2dbd819..a7820442df0 100644 --- a/doc/development/new_fe_guide/modules/index.md +++ b/doc/development/new_fe_guide/modules/index.md @@ -1,5 +1,5 @@ # Modules -* [DirtySubmit](dirty_submit.md) +- [DirtySubmit](dirty_submit.md) - Disable form submits until there are unsaved changes.
\ No newline at end of file + Disable form submits until there are unsaved changes. diff --git a/doc/development/new_fe_guide/style/prettier.md b/doc/development/new_fe_guide/style/prettier.md index 6395af6f815..4495f38f262 100644 --- a/doc/development/new_fe_guide/style/prettier.md +++ b/doc/development/new_fe_guide/style/prettier.md @@ -47,13 +47,48 @@ 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. + +## VSCode Settings + +### Format on Save + +To automatically format your files with Prettier, add the following properties to your User or Workspace Settings: + +```javascript +{ + "[javascript]": { + "editor.formatOnSave": true + }, + "[vue]": { + "editor.formatOnSave": true + }, +} +``` + +### Conflicts with Vetur Extension + +There are some [runtime issues](https://github.com/vuejs/vetur/issues/950) with [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) and [the Vetur extension](https://marketplace.visualstudio.com/items?itemName=octref.vetur) for VSCode. To fix this, try adding the following properties to your User or Workspace Settings: + +```javascript +{ + "prettier.disableLanguages": [], + "vetur.format.defaultFormatter.html": "none", + "vetur.format.defaultFormatter.js": "none", + "vetur.format.defaultFormatter.css": "none", + "vetur.format.defaultFormatter.less": "none", + "vetur.format.defaultFormatter.postcss": "none", + "vetur.format.defaultFormatter.scss": "none", + "vetur.format.defaultFormatter.stylus": "none", + "vetur.format.defaultFormatter.ts": "none", +} +``` diff --git a/doc/development/ordering_table_columns.md b/doc/development/ordering_table_columns.md index e9c6481635b..3e49a65f5ab 100644 --- a/doc/development/ordering_table_columns.md +++ b/doc/development/ordering_table_columns.md @@ -30,7 +30,7 @@ ideal column order would be the following: - `user_id` (integer, 4 bytes) - `name` (text, variable) -or +or - `name` (text, variable) - `id` (integer, 4 bytes) @@ -47,8 +47,7 @@ type size in descending order with variable sizes (`text`, `varchar`, arrays, ## Type Sizes -While the PostgreSQL documentation -(https://www.postgresql.org/docs/current/static/datatype.html) contains plenty +While the [PostgreSQL documentation](https://www.postgresql.org/docs/current/datatype.html) contains plenty 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. @@ -138,7 +137,7 @@ This would produce the following chunks: | variable | data | 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 +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 c7b10dfd5ce..972c93be817 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -9,23 +9,23 @@ 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: -* The 95th percentile -* The 99th percentile -* The mean +- The 95th percentile +- The 99th percentile +- The mean When providing screenshots of graphs, make sure that both the X and Y axes and the legend are clearly visible. If you happen to have access to GitLab.com's own @@ -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 +- [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 @@ -268,11 +269,11 @@ piece of code is worth optimizing. The only two things you can do are: Some examples of changes that aren't really important/worth the effort: -* Replacing double quotes with single quotes. -* Replacing usage of Array with Set when the list of values is very small. -* Replacing library A with library B when both only take up 0.1% of the total +- Replacing double quotes with single quotes. +- Replacing usage of Array with Set when the list of values is very small. +- Replacing library A with library B when both only take up 0.1% of the total execution time. -* Calling `freeze` on every string (see [String Freezing](#string-freezing)). +- Calling `freeze` on every string (see [String Freezing](#string-freezing)). ## Slow Operations & Sidekiq diff --git a/doc/development/policies.md b/doc/development/policies.md index 62141356f59..97424d90fb5 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -13,7 +13,7 @@ Permissions are broken into two parts: `conditions` and `rules`. Conditions are Conditions are defined by the `condition` method, and are given a name and a block. The block will be executed in the context of the policy object - so it can access `@user` and `@subject`, as well as call any methods defined on the policy. Note that `@user` may be nil (in the anonymous case), but `@subject` is guaranteed to be a real instance of the subject class. -``` ruby +```ruby class FooPolicy < BasePolicy condition(:is_public) do # @subject guaranteed to be an instance of Foo @@ -37,7 +37,7 @@ Conditions are cached according to their scope. Scope and ordering will be cover A `rule` is a logical combination of conditions and other rules, that are configured to enable or prevent certain abilities. It is important to note that the rule configuration is static - a rule's logic cannot touch the database or know about `@user` or `@subject`. This allows us to cache only at the condition level. Rules are specified through the `rule` method, which takes a block of DSL configuration, and returns an object that responds to `#enable` or `#prevent`: -``` ruby +```ruby class FooPolicy < BasePolicy # ... @@ -57,10 +57,10 @@ end Within the rule DSL, you can use: -* A regular word mentions a condition by name - a rule that is in effect when that condition is truthy. -* `~` indicates negation -* `&` and `|` are logical combinations, also available as `all?(...)` and `any?(...)` -* `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. +- A regular word mentions a condition by name - a rule that is in effect when that condition is truthy. +- `~` indicates negation. +- `&` and `|` are logical combinations, also available as `all?(...)` and `any?(...)`. +- `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. ## Scores, Order, Performance @@ -72,7 +72,7 @@ When a policy is asked whether a particular ability is allowed (`policy.allowed? Sometimes, a condition will only use data from `@user` or only from `@subject`. In this case, we want to change the scope of the caching, so that we don't recalculate conditions unnecessarily. For example, given: -``` ruby +```ruby class FooPolicy < BasePolicy condition(:expensive_condition) { @subject.expensive_query? } @@ -82,7 +82,7 @@ end Naively, if we call `Ability.can?(user1, :some_ability, foo)` and `Ability.can?(user2, :some_ability, foo)`, we would have to calculate the condition twice - since they are for different users. But if we use the `scope: :subject` option: -``` ruby +```ruby condition(:expensive_condition, scope: :subject) { @subject.expensive_query? } ``` @@ -93,7 +93,7 @@ both user and subject (including a simple anonymous check!) your result will be Sometimes we are checking permissions for a lot of users for one subject, or a lot of subjects for one user. In this case, we want to set a *preferred scope* - i.e. tell the system that we prefer rules that can be cached on the repeated parameter. For example, in `Ability.users_that_can_read_project`: -``` ruby +```ruby def users_that_can_read_project(users, project) DeclarativePolicy.subject_scope do users.select { |u| allowed?(u, :read_project, project) } @@ -105,9 +105,9 @@ This will, for example, prefer checking `project.public?` to checking `user.admi ## Delegation -Delegation is the inclusion of rules from another policy, on a different subject. For example, +Delegation is the inclusion of rules from another policy, on a different subject. For example: -``` ruby +```ruby class FooPolicy < BasePolicy delegate { @subject.project } end diff --git a/doc/development/polymorphic_associations.md b/doc/development/polymorphic_associations.md index d63b9fb115f..5d69c8add38 100644 --- a/doc/development/polymorphic_associations.md +++ b/doc/development/polymorphic_associations.md @@ -7,9 +7,9 @@ usually works by adding two columns to a table: a target type column, and a target id. For example, at the time of writing we have such a setup for `members` with the following columns: -* `source_type`: a string defining the model to use, can be either `Project` or +- `source_type`: a string defining the model to use, can be either `Project` or `Namespace`. -* `source_id`: the ID of the row to retrieve based on `source_type`. For +- `source_id`: the ID of the row to retrieve based on `source_type`. For example, when `source_type` is `Project` then `source_id` will contain a project ID. @@ -92,10 +92,10 @@ AND source_id = 4 Instead such a table should be broken up into separate tables. For example, you may end up with 4 tables in this case: -* project_members -* group_members -* pending_project_members -* pending_group_members +- project_members +- group_members +- pending_project_members +- pending_group_members This makes querying data trivial. For example, to get the members of a group you'd run: diff --git a/doc/development/post_deployment_migrations.md b/doc/development/post_deployment_migrations.md index cfc91539bee..a41096aa3eb 100644 --- a/doc/development/post_deployment_migrations.md +++ b/doc/development/post_deployment_migrations.md @@ -57,19 +57,19 @@ 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. Some other examples where these migrations are useful: -* Cleaning up data generated due to a bug in GitLab -* Removing tables -* Migrating jobs from one Sidekiq queue to another +- Cleaning up data generated due to a bug in GitLab +- Removing tables +- Migrating jobs from one Sidekiq queue to another diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 0ca8bb67a77..0b0c6dfc8cf 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -77,8 +77,11 @@ that builds on this to add some additional niceties, such as allowing configuration with a single Yaml file for multiple URLs, and uploading of the profile and log output to S3. -For GitLab.com, you can find the latest results here: -<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics> +For GitLab.com, currently the latest profiling data has been [moved from +Redash to Looker](https://gitlab.com/gitlab-com/Product/issues/5#note_121194467). +We are [currently investigating how to make this data +public](https://gitlab.com/meltano/looker/issues/294). + ## Sherlock diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index b6b6d9665ea..0511e735843 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -30,7 +30,7 @@ You might want to add additional database migration that makes a decision what t For example: you might be interested in migrating all dependent data to a different metric. ```ruby -class ImportCommonMetrics < ActiveRecord::Migration +class ImportCommonMetrics < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers require Rails.root.join('db/importers/common_metrics_importer.rb') 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 2ad748d4802..ae9bf863419 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -38,6 +38,14 @@ Note that since you can't see the questions from stdout, you might just want to `echo 'yes'` to keep it running. It would still print the errors on stderr so no worries about missing errors. +### Extra Project seed options + +There are a few environment flags you can pass to change how projects are seeded + +- `SIZE`: defaults to `8`, max: `32`. Amount of projects to create. +- `LARGE_PROJECTS`: defaults to false. If set will clone 6 large projects to help with testing. +- `FORK`: defaults to false. If set to `true` will fork `torvalds/linux` five times. Can also be set to an existing project full_path and it will fork that instead. + ### Notes for MySQL Since the seeds would contain various UTF-8 characters, such as emojis or so, diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 83d7d42bd1f..01cedf734fb 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -149,11 +149,11 @@ typically in JSON. These are class methods defined by _GitLab itself_, including the following methods provided by Active Record: -* `find` -* `find_by_id` -* `delete_all` -* `destroy` -* `destroy_all` +- `find` +- `find_by_id` +- `delete_all` +- `destroy` +- `destroy_all` Any other methods such as `find_by(some_column: X)` are not included, and instead fall under the "Active Record" abstraction. @@ -163,10 +163,10 @@ instead fall under the "Active Record" abstraction. Instance methods defined on Active Record models by _GitLab itself_. Methods provided by Active Record are not included, except for the following methods: -* `save` -* `update` -* `destroy` -* `delete` +- `save` +- `update` +- `destroy` +- `delete` ### Active Record diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index dada59ce242..ef1aba95712 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -10,12 +10,12 @@ disable those changes, without having to revert an entire release. Starting with GitLab 11.4, developers are required to use feature flags for non-trivial changes. Such changes include: -* New features (e.g. a new merge request widget, epics, etc). -* Complex performance improvements that may require additional testing in +- New features (e.g. a new merge request widget, epics, etc). +- Complex performance improvements that may require additional testing in production, such as rewriting complex queries. -* Invasive changes to the user interface, such as a new navigation bar or the +- Invasive changes to the user interface, such as a new navigation bar or the removal of a sidebar. -* Adding support for importing projects from a third-party service. +- Adding support for importing projects from a third-party service. In all cases, those working on the changes can best decide if a feature flag is necessary. For example, changing the color of a button doesn't need a feature @@ -152,14 +152,31 @@ 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. -## Undefined feature flags default to "on" +## Implicit feature flags -By default, the [`Project#feature_available?`][project-fa], +The [`Project#feature_available?`][project-fa], [`Namespace#feature_available?`][namespace-fa] (EE), and -[`License.feature_available?`][license-fa] (EE) methods will check if the -specified feature is behind a feature flag. Unless the feature is explicitly -disabled or limited to a percentage of users, the feature flag check will -default to `true`. +[`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 @@ -171,7 +188,3 @@ to be shipped. You can do this via ChatOps: Note that you can do this at any time, even before the merge request using the flag has been merged! - -[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 diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md index 84b61bd7e61..2b3a9481b93 100644 --- a/doc/development/sidekiq_debugging.md +++ b/doc/development/sidekiq_debugging.md @@ -11,6 +11,11 @@ Example: gitlab_rails['env'] = {"SIDEKIQ_LOG_ARGUMENTS" => "1"} ``` -Please note: It is not recommend to enable this setting in production because some +Please note: It is not recommend to enable this setting in production because some Sidekiq jobs (such as sending a password reset email) take secret arguments (for -example the password reset token).
\ No newline at end of file +example the password reset token). + +When using [Sidekiq JSON logging](../administration/logs.md#sidekiqlog), +arguments logs are limited to a maximum size of 10 kilobytes of text; +any arguments after this limit will be discarded and replaced with a +single argument containing the string `"..."`. 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/sql.md b/doc/development/sql.md index e1e1d31a85f..06005a0a6f8 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -106,7 +106,7 @@ transaction. Transactions for migrations can be disabled using the following pattern: ```ruby -class MigrationName < ActiveRecord::Migration +class MigrationName < ActiveRecord::Migration[4.2] disable_ddl_transaction! end ``` @@ -114,7 +114,7 @@ end For example: ```ruby -class AddUsersLowerUsernameEmailIndexes < ActiveRecord::Migration +class AddUsersLowerUsernameEmailIndexes < ActiveRecord::Migration[4.2] disable_ddl_transaction! def up 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/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index acbfa1850b4..4cc3812b0f0 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -19,6 +19,16 @@ Here are some things to keep in mind regarding test performance: ## RSpec +To run rspec tests: + +```sh +# run all tests +bundle exec rspec + +# run test for path +bundle exec rspec spec/[path]/[to]/[spec].rb +``` + ### General guidelines - Use a single, top-level `describe ClassName` block. @@ -111,7 +121,7 @@ failure. In CI you can download these files as job artifacts. Also, you can manually take screenshots at any point in a test by adding the methods below. Be sure to remove them when they are no longer needed! See -https://github.com/mattheworiordan/capybara-screenshot#manual-screenshots for +<https://github.com/mattheworiordan/capybara-screenshot#manual-screenshots> for more. Add `screenshot_and_save_page` in a `:js` spec to screenshot what Capybara @@ -209,6 +219,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 +404,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 +414,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 +426,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 +480,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/ci.md b/doc/development/testing_guide/ci.md index 8d9706a9501..d685cacf9ea 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -31,11 +31,7 @@ After that, the next pipeline will use the up-to-date The GitLab test suite is [monitored] for the `master` branch, and any branch that includes `rspec-profile` in their name. -A [public dashboard] is available for everyone to see. Feel free to look at the -slowest test files and try to improve them. - [monitored]: ../performance.md#rspec-profiling -[public dashboard]: https://redash.gitlab.com/public/dashboards/l1WhHXaxrCWM5Ai9D7YDqHKehq6OU3bx5gssaiWe?org_slug=default ## CI setup 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/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index bbb2313ea7b..3d568c37fba 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -5,6 +5,39 @@ It's a test that sometimes fails, but if you retry it enough times, it passes, eventually. +## Quarantined tests + +When a test frequently fails in `master`, +[a ~"broken master" issue](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) +should be created. +If the test cannot be fixed in a timely fashion, there is an impact on the +productivity of all the developers, so it should be placed in quarantine by +assigning the `:quarantine` metadata. + +This means it will be skipped unless run with `--tag quarantine`: + +```shell +bin/rspec --tag quarantine +``` + +**Before putting a test in quarantine, you should make sure that a +~"broken master" issue exists for it so it won't stay in quarantine forever.** + +Once a test is in quarantine, there are 3 choices: + +- Should the test be fixed (i.e. get rid of its flakiness)? +- Should the test be moved to a lower level of testing? +- Should the test be removed entirely (e.g. because there's already a + lower-level test, or it's duplicating another same-level test, or it's testing + too much etc.)? + +### Quarantine tests on the CI + +Quarantined tests are run on the CI in dedicated jobs that are allowed to fail: + +- `rspec-pg-quarantine` and `rspec-mysql-quarantine` (CE & EE) +- `rspec-pg-quarantine-ee` and `rspec-mysql-quarantine-ee` (EE only) + ## Automatic retries and flaky tests detection On our CI, we use [rspec-retry] to automatically retry a failing example a few @@ -15,51 +48,51 @@ examples in a JSON report file on `master` (`retrieve-tests-metadata` and `updat is detected in any other branch (`flaky-examples-check` job). In the future, the `flaky-examples-check` job will not be allowed to fail. -This was originally implemented in: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13021. +This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13021>. [rspec-retry]: https://github.com/NoRedInk/rspec-retry [`spec/spec_helper.rb`]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/spec_helper.rb ## Problems we had in the past at GitLab -- [`rspec-retry` is bitting us when some API specs fail](https://gitlab.com/gitlab-org/gitlab-ce/issues/29242): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9825 -- [Sporadic RSpec failures due to `PG::UniqueViolation`](https://gitlab.com/gitlab-org/gitlab-ce/issues/28307#note_24958837): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9846 - - Follow-up: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10688 - - [Capybara.reset_session! should be called before requests are blocked](https://gitlab.com/gitlab-org/gitlab-ce/issues/33779): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12224 +- [`rspec-retry` is bitting us when some API specs fail](https://gitlab.com/gitlab-org/gitlab-ce/issues/29242): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9825> +- [Sporadic RSpec failures due to `PG::UniqueViolation`](https://gitlab.com/gitlab-org/gitlab-ce/issues/28307#note_24958837): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9846> + - Follow-up: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10688> + - [Capybara.reset_session! should be called before requests are blocked](https://gitlab.com/gitlab-org/gitlab-ce/issues/33779): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12224> - FFaker generates funky data that tests are not ready to handle (and tests should be predictable so that's bad!): - - [Make `spec/mailers/notify_spec.rb` more robust](https://gitlab.com/gitlab-org/gitlab-ce/issues/20121): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10015 - - [Transient failure in spec/requests/api/commits_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/27988#note_25342521): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9944 - - [Replace FFaker factory data with sequences](https://gitlab.com/gitlab-org/gitlab-ce/issues/29643): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10184 - - [Transient failure in spec/finders/issues_finder_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/30211#note_26707685): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10404 + - [Make `spec/mailers/notify_spec.rb` more robust](https://gitlab.com/gitlab-org/gitlab-ce/issues/20121): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10015> + - [Transient failure in spec/requests/api/commits_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/27988#note_25342521): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9944> + - [Replace FFaker factory data with sequences](https://gitlab.com/gitlab-org/gitlab-ce/issues/29643): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10184> + - [Transient failure in spec/finders/issues_finder_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/30211#note_26707685): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10404> ### Time-sensitive flaky tests -- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10046 -- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10306 +- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10046> +- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10306> ### Array order expectation -- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10148 +- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10148> ### Feature tests -- [Be sure to create all the data the test need before starting exercize](https://gitlab.com/gitlab-org/gitlab-ce/issues/32622#note_31128195): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12059 -- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34609#note_34048715): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12604 -- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34698#note_34276286): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12664 -- [Assert against the underlying database state instead of against a page's content](https://gitlab.com/gitlab-org/gitlab-ce/issues/31437): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10934 +- [Be sure to create all the data the test need before starting exercize](https://gitlab.com/gitlab-org/gitlab-ce/issues/32622#note_31128195): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12059> +- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34609#note_34048715): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12604> +- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34698#note_34276286): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12664> +- [Assert against the underlying database state instead of against a page's content](https://gitlab.com/gitlab-org/gitlab-ce/issues/31437): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10934> #### Capybara viewport size related issues -- [Transient failure of spec/features/issues/filtered_search/filter_issues_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/29241#note_26743936): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10411 +- [Transient failure of spec/features/issues/filtered_search/filter_issues_spec.rb](https://gitlab.com/gitlab-org/gitlab-ce/issues/29241#note_26743936): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10411> #### Capybara JS driver related issues -- [Don't wait for AJAX when no AJAX request is fired](https://gitlab.com/gitlab-org/gitlab-ce/issues/30461): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10454 -- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34647): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12626 +- [Don't wait for AJAX when no AJAX request is fired](https://gitlab.com/gitlab-org/gitlab-ce/issues/30461): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10454> +- [Bis](https://gitlab.com/gitlab-org/gitlab-ce/issues/34647): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12626> #### PhantomJS / WebKit related issues -- Memory is through the roof! (TL;DR: Load images but block images requests!): https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12003 +- Memory is through the roof! (TL;DR: Load images but block images requests!): <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12003> ## Resources diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index f8993653aec..6012f1080ab 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -185,8 +185,8 @@ See this [section][vue-test]. `rake karma` runs the frontend-only (JavaScript) tests. It consists of two subtasks: -* `rake karma:fixtures` (re-)generates fixtures -* `rake karma:tests` actually executes the tests +- `rake karma:fixtures` (re-)generates fixtures +- `rake karma:tests` actually executes the tests As long as the fixtures don't change, `rake karma:tests` (or `yarn karma`) is sufficient (and saves you some time). @@ -243,14 +243,14 @@ supported by the PhantomJS test runner which is used for both Karma and RSpec tests. We polyfill some JavaScript objects for older browsers, but some features are still unavailable: -* Array.from -* Array.first -* Async functions -* Generators -* Array destructuring -* For..Of -* Symbol/Symbol.iterator -* Spread +- Array.from +- Array.first +- Async functions +- Generators +- Array destructuring +- For..Of +- Symbol/Symbol.iterator +- Spread Until these are polyfilled appropriately, they should not be used. Please update this list with additional unsupported features. diff --git a/doc/development/testing_guide/img/review_apps_cicd_architecture.png b/doc/development/testing_guide/img/review_apps_cicd_architecture.png Binary files differnew file mode 100644 index 00000000000..87e472076f3 --- /dev/null +++ b/doc/development/testing_guide/img/review_apps_cicd_architecture.png diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 25c6371f3d7..3af97717775 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -1,81 +1,176 @@ -# 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**. +### CD/CD architecture diagram + + + +<details> +<summary>Show mermaid source</summary> +<pre> +graph TD + B1 -.->|2. once gitlab:assets:compile is done,<br />triggers a CNG-mirror pipeline and wait for it to be done| A2 + C1 -.->|2. once review-build-cng is done,<br />Helm deploys the Review App using the Cloud<br/>Native images built by the CNG-mirror pipeline| A3 + +subgraph gitlab-ce/ee `test` stage + A1[gitlab:assets:compile] + B1[review-build-cng] -->|1. wait for| A1 + C1[review-deploy] -->|1. wait for| B1 + D1[review-qa-smoke] -->|1. wait for| C1 + D1[review-qa-smoke] -.->|2. once review-deploy is done| E1>gitlab-qa runs the smoke<br/>suite against the Review App] + end + +subgraph CNG-mirror pipeline + A2>Cloud Native images are built]; + end + +subgraph GCP `gitlab-review-apps` project + A3>"Cloud Native images are deployed to the<br />`review-apps-ce` or `review-apps-ee` Kubernetes (GKE) cluster"]; + end +</pre> +</details> + +### Detailed explanation + +1. On every [pipeline][gitlab-pipeline] during the `test` stage, the + [`review-build-cng`][review-build-cng] and + [`review-deploy`][review-deploy] jobs are automatically started. + - The [`review-deploy`][review-deploy] job waits for the + [`review-build-cng`][review-build-cng] job to finish. + - The [`review-build-cng`][review-build-cng] job waits for the + [`gitlab:assets:compile`][gitlab:assets:compile] job to finish since the + [`CNG-mirror`][cng-mirror] pipeline triggered in the following step depends on it. +1. Once the [`gitlab:assets:compile`][gitlab:assets:compile] job is done, + [`review-build-cng`][review-build-cng] [triggers a pipeline][cng-pipeline] + in the [`CNG-mirror`][cng-mirror] project. + - The [`CNG-mirror`][cng-pipeline] 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]. + - We use the [`CNG-mirror`][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. +1. Once the [`review-build-cng`][review-build-cng] job is done, the + [`review-deploy`][review-deploy] job deploys the Review App 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`][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**. **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 - -[^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 +- 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. + +Note that both jobs first wait for the `review-deploy` job to be finished. + +## How to? + +### Find my Review App slug? + +1. Open the `review-deploy` job. +1. Look for `Checking for previous deployment of review-*`. +1. For instance for `Checking for previous deployment of review-qa-raise-e-12chm0`, + your Review App slug would be `review-qa-raise-e-12chm0` in this case. + +### Run a Rails console? + +1. [Filter Workloads by your Review App slug](https://console.cloud.google.com/kubernetes/workload?project=gitlab-review-apps) + , e.g. `review-29951-issu-id2qax`. +1. Find and open the `task-runner` Deployment, e.g. `review-29951-issu-id2qax-task-runner`. +1. Click on the Pod in the "Managed pods" section, e.g. `review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz`. +1. Click on the `KUBECTL` dropdown, then `Exec` -> `task-runner`. +1. Replace `-c task-runner -- ls` with `-- /srv/gitlab/bin/rails c` from the + default command or + - Run `kubectl exec --namespace review-apps-ce -it review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz -- /srv/gitlab/bin/rails c` + and + - Replace `review-apps-ce` with `review-apps-ee` if the Review App + is running EE, and + - Replace `review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz` + with your Pod's name. + +### Dig into a Pod's logs? + +1. [Filter Workloads by your Review App slug](https://console.cloud.google.com/kubernetes/workload?project=gitlab-review-apps) + , e.g. `review-1979-1-mul-dnvlhv`. +1. Find and open the `migrations` Deployment, e.g. + `review-1979-1-mul-dnvlhv-migrations.1`. +1. Click on the Pod in the "Managed pods" section, e.g. + `review-1979-1-mul-dnvlhv-migrations.1-nqwtx`. +1. Click on the `Container logs` link. ## 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 +[charts-1068]: https://gitlab.com/charts/gitlab/issues/1068 +[gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ce/pipelines/44362587 +[gitlab:assets:compile]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/149511610 +[review-build-cng]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/149511623 +[review-deploy]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/149511624 [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/44364657 [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-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..070b6477a7a 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -6,7 +6,7 @@ _This diagram demonstrates the relative priority of each test type we use. `e2e` ## Unit tests -Formal definition: https://en.wikipedia.org/wiki/Unit_testing +Formal definition: <https://en.wikipedia.org/wiki/Unit_testing> These kind of tests ensure that a single unit of code (a method) works as expected (given an input, it has a predictable output). These tests should be @@ -32,9 +32,13 @@ records should use stubs/doubles as much as possible. ## Integration tests -Formal definition: https://en.wikipedia.org/wiki/Integration_testing +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/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index adf8795a5e3..01a0044f096 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -625,9 +625,9 @@ This is a bit of a difficult question to answer, because the definition of "bad" is relative to the problem you are trying to solve. However, some patterns are best avoided in most cases, such as: -* Sequential scans on large tables -* Filters that remove a lot of rows -* Performing a certain step (e.g. an index scan) that requires _a lot_ of +- Sequential scans on large tables +- Filters that remove a lot of rows +- Performing a certain step (e.g. an index scan) that requires _a lot_ of buffers (e.g. more than 512 MB for GitLab.com). As a general guideline, aim for a query that: @@ -650,8 +650,8 @@ different queries. The only _rule_ is that you _must always measure_ your query (preferably using a production-like database) using `EXPLAIN (ANALYZE, BUFFERS)` and related tools such as: -* <https://explain.depesz.com/> -* <http://tatiyants.com/postgres-query-plan-visualization/> +- <https://explain.depesz.com/> +- <http://tatiyants.com/postgres-query-plan-visualization/> GitLab employees can also use our chatops solution, available in Slack using the `/chatops` slash command. You can use chatops to get a query plan by running the diff --git a/doc/development/utilities.md b/doc/development/utilities.md index 0d074a3ef05..0e396baccff 100644 --- a/doc/development/utilities.md +++ b/doc/development/utilities.md @@ -4,7 +4,7 @@ We developed a number of utilities to ease development. ## [`MergeHash`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/merge_hash.rb) -* Deep merges an array of hashes: +- Deep merges an array of hashes: ``` ruby Gitlab::Utils::MergeHash.merge( @@ -31,7 +31,7 @@ We developed a number of utilities to ease development. ] ``` -* Extracts all keys and values from a hash into an array: +- Extracts all keys and values from a hash into an array: ``` ruby Gitlab::Utils::MergeHash.crush( @@ -47,14 +47,14 @@ We developed a number of utilities to ease development. ## [`Override`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/override.rb) -* This utility could help us check if a particular method would override +- This utility could help us check if a particular method would override another method or not. It has the same idea of Java's `@Override` annotation or Scala's `override` keyword. However we only do this check when `ENV['STATIC_VERIFICATION']` is set to avoid production runtime overhead. This is useful to check: - * If we have typos in overriding methods. - * If we renamed the overridden methods, making original overriding methods + - If we have typos in overriding methods. + - If we renamed the overridden methods, making original overriding methods overrides nothing. Here's a simple example: @@ -92,7 +92,7 @@ We developed a number of utilities to ease development. ## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb) -* Memoize the value even if it is `nil` or `false`. +- Memoize the value even if it is `nil` or `false`. We often do `@value ||= compute`, however this doesn't work well if `compute` might eventually give `nil` and we don't want to compute again. @@ -126,7 +126,7 @@ We developed a number of utilities to ease development. end ``` -* Clear memoization +- Clear memoization ``` ruby class Find @@ -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 f9c395b2dff..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 setup. 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/verifying_database_capabilities.md b/doc/development/verifying_database_capabilities.md index ffdeff47d4a..661ab9cef1a 100644 --- a/doc/development/verifying_database_capabilities.md +++ b/doc/development/verifying_database_capabilities.md @@ -6,9 +6,9 @@ necessary to add database (version) specific behaviour. To facilitate this we have the following methods that you can use: -* `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used -* `Gitlab::Database.mysql?`: returns `true` if MySQL is being used -* `Gitlab::Database.version`: returns the PostgreSQL version number as a string +- `Gitlab::Database.postgresql?`: returns `true` if PostgreSQL is being used +- `Gitlab::Database.mysql?`: returns `true` if MySQL is being used +- `Gitlab::Database.version`: returns the PostgreSQL version number as a string in the format `X.Y.Z`. This method does not work for MySQL This allows you to write code such as: diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index b668c9de6a0..24edd05da2f 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -88,7 +88,7 @@ renaming. For example ```ruby # A regular migration in db/migrate -class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration +class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -118,7 +118,7 @@ We can perform this cleanup using ```ruby # A post-deployment migration in db/post_migrate -class CleanupUsersUpdatedAtRename < ActiveRecord::Migration +class CleanupUsersUpdatedAtRename < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -157,7 +157,7 @@ as follows: ```ruby # A regular migration in db/migrate -class ChangeUsersUsernameStringToText < ActiveRecord::Migration +class ChangeUsersUsernameStringToText < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -178,7 +178,7 @@ Next we need to clean up our changes using a post-deployment migration: ```ruby # A post-deployment migration in db/post_migrate -class ChangeUsersUsernameStringToTextCleanup < ActiveRecord::Migration +class ChangeUsersUsernameStringToTextCleanup < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -213,7 +213,7 @@ the work / load over a longer time period, without slowing down deployments. For example, to change the column type using a background migration: ```ruby -class ExampleMigration < ActiveRecord::Migration +class ExampleMigration < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -257,7 +257,7 @@ release) by a cleanup migration, which should steal from the queue and handle any remaining rows. For example: ```ruby -class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration +class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration[4.2] include Gitlab::Database::MigrationHelpers DOWNTIME = false @@ -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. @@ -322,7 +322,7 @@ Migrations can take advantage of this by using the method `add_concurrent_index`. For example: ```ruby -class MyMigration < ActiveRecord::Migration +class MyMigration < ActiveRecord::Migration[4.2] def up add_concurrent_index :projects, :column_name end diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 33f46e8d4f3..978ffde84ad 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -1,27 +1,28 @@ -# How to create a project in GitLab +# Create a project -> **Notes:** -> - For a list of words that are not allowed to be used as project names see the -> [reserved names][reserved]. +[Projects](../user/project/index.md) combine many features of GitLab together. -1. In your dashboard, click the green **New project** button or use the plus - icon in the upper right corner of the navigation bar. +NOTE: **Note:** +For a list of words that cannot be used as project names see +[Reserved project and group names](../user/reserved_names.md). -  +To create a project in GitLab: -1. This opens the **New project** page. +1. In your dashboard, click the green **New project** button or use the plus + icon in the navigation bar. This opens the **New project** page. +1. On the **New project** page, choose if you want to: + - Create a [blank project](#blank-projects). + - Create a project using with one of the available [project templates](#project-templates). + - [Import a project](../user/project/import/index.md) from a different repository, + if enabled on your GitLab instance. Contact your GitLab admin if this + is unavailable. -  +## Blank projects -1. Choose if you want start a blank project, or with one of the predefined - [Project Templates](https://gitlab.com/gitlab-org/project-templates): - this will kickstart your repository code and CI automatically. - Otherwise, if you have a project in a different repository, you can [import it] by - clicking on the **Import project** tab, provided this is enabled in - your GitLab instance. Ask your administrator if not. +To create a new blank project on the **New project** page: -1. Provide the following information: - - Enter the name of your project in the **Project name** field. You can't use +1. On the **Blank project** tab, provide the following information: + - The name of your project in the **Project name** field. You can't use special characters, but you can use spaces, hyphens, underscores or even emoji. - The **Project description (optional)** field enables you to enter a @@ -31,11 +32,64 @@ - Changing the **Visibility Level** modifies the project's [viewing and access rights](../public_access/public_access.md) for users. - Selecting the **Initialize repository with a README** option creates a - README so that the Git repository is initialized, has a default branch and + README file so that the Git repository is initialized, has a default branch, and can be cloned. - 1. Click **Create project**. +## Project templates + +Project templates can pre-populate your project with necessary files to get you started quickly. + +There are two types of project templates: + +- [Built-in templates](#builtin-templates), sourced from the [`project-templates`](https://gitlab.com/gitlab-org/project-templates) group. +- [Custom project templates](#custom-project-templates-premium-only), for custom templates configured by GitLab administrators and users. + +### Built-in templates + +Built-in templates are project templates that are: + +- Developed and maintained in the + [`project-templates`](https://gitlab.com/gitlab-org/project-templates) group. +- Released with GitLab. + +To use a built-in template on the **New project** page: + +1. On the **Create from template** tab. +1. From the list of available built-in templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is the same as for + using a [blank project](#blank-projects). + +TIP: **Tip:** +You can improve the existing built-in templates or contribute new ones on the +[`project-templates`](https://gitlab.com/gitlab-org/project-templates) group. + +### Custom project templates **[PREMIUM ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6860) in +[GitLab Premium](https://about.gitlab.com/pricing) 11.2. + +Creating new projects based on custom project templates is a convenient option to bootstrap a project. + +Custom projects are available from the **Instance** or **Group** tabs under the **Create from template** tab, +depending on the type of template. + +To use a custom project template on the **New project** page: + +1. On the **Create from template** tab, select the **Instance** tab or the **Group** tab. +1. From the list of available custom templates, click the: + - **Preview** button to look at the template source itself. + - **Use template** button to start creating the project. +1. Finish creating the project by filling out the project's details. The process is the same as for + using a [blank project](#blank-projects). + +For information on configuring custom project templates, see: + +- [Custom instance-level project templates](../user/admin_area/custom_project_templates.md), for instance-level templates. +- [Custom group-level project templates](../user/group/custom_project_templates.md), for group-level templates. + ## Push to create a new project > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26388) in GitLab 10.5. @@ -46,20 +100,20 @@ GitLab to create the new project, all without leaving your terminal. If you have namespace, we will automatically create a new project under that GitLab namespace with its visibility set to Private by default (you can later change it in the [project's settings](../public_access/public_access.md#how-to-change-project-visibility)). -This can be done by using either SSH or HTTP: +This can be done by using either SSH or HTTPS: -``` +```sh ## Git push using SSH git push --set-upstream git@gitlab.example.com:namespace/nonexistent-project.git master -## Git push using HTTP +## Git push using HTTPS git push --set-upstream https://gitlab.example.com/namespace/nonexistent-project.git master ``` Once the push finishes successfully, a remote message will indicate the command to set the remote and the URL to the new project: -``` +```text remote: remote: The private project namespace/nonexistent-project was created. remote: @@ -70,6 +124,3 @@ remote: To view the project, visit: remote: https://gitlab.example.com/namespace/nonexistent-project remote: ``` - -[import it]: ../workflow/importing/README.md -[reserved]: ../user/reserved_names.md 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/gitlab-basics/img/create_new_project_button.png b/doc/gitlab-basics/img/create_new_project_button.png Binary files differdeleted file mode 100644 index 567f104880f..00000000000 --- a/doc/gitlab-basics/img/create_new_project_button.png +++ /dev/null diff --git a/doc/gitlab-basics/img/create_new_project_info.png b/doc/gitlab-basics/img/create_new_project_info.png Binary files differdeleted file mode 100644 index 2693a7f9a6d..00000000000 --- a/doc/gitlab-basics/img/create_new_project_info.png +++ /dev/null diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 0d9994c9925..e30afdf8a40 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -68,6 +68,54 @@ git config --global --list ## Basic Git commands +Start using Git via the command line with the most basic +commands as described below. + +### Clone a repository + +To start working locally on an existing remote repository, +clone it with the command `git clone <repository path>`. +By cloning a repository, you'll download a copy of its +files into your local computer, preserving the Git +connection with the remote repository. + +You can either clone it via HTTPS or [SSH](../ssh/README.md). +If you chose to clone it via HTTPS, you'll have to enter your +credentials every time you pull and push. With SSH, you enter +your credentials once and can pull and push straightaway. + +You can find both paths (HTTPS and SSH) by navigating to +your project's landing page and clicking **Clone**. GitLab +will prompt you with both paths, from which you can copy +and paste in your command line. + +As an example, consider a repository path: + +- HTTPS: `https://gitlab.com/gitlab-org/gitlab-ce.git` +- SSH: `` git@gitlab.com:gitlab-org/gitlab-ce.git `` + +To get started, open a terminal window in the directory +you wish to clone the repository files into, and run one +of the following commands. + +Clone via HTTPS: + +```bash +git clone https://gitlab.com/gitlab-org/gitlab-ce.git +``` + +Clone via SSH: + +```bash +git clone git@gitlab.com:gitlab-org/gitlab-ce.git +``` + +Both commands will download a copy of the files in a +folder named after the project's name. + +You can then navigate to the directory and start working +on it locally. + ### Go to the master branch to pull the latest changes from there ```bash diff --git a/doc/img/devops-stages.png b/doc/img/devops-stages.png Binary files differnew file mode 100644 index 00000000000..424bce95607 --- /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..ae48306e65e 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -5,8 +5,25 @@ description: Read through the GitLab installation methods. # Installation -GitLab can be installed via various ways. Check the [installation methods][methods] -for an overview. +GitLab can be installed in most GNU/Linux distributions and in a number +of cloud providers. To get the best experience from GitLab you need to balance +performance, reliability, ease of administration (backups, upgrades and troubleshooting), +and cost of hosting. + +There are many ways you can install GitLab depending on your platform: + +1. **Omnibus Gitlab**: The official deb/rpm packages that contain a bundle of GitLab + and the various components it depends on like PostgreSQL, Redis, Sidekiq, etc. +1. **GitLab Helm chart**: The cloud native Helm chart for installing GitLab and all + its components on Kubernetes. +1. **Docker**: The Omnibus GitLab packages dockerized. +1. **Source**: Install GitLab and all its components from scratch. + +TIP: **If in doubt, choose Omnibus:** +The Omnibus GitLab packages are mature, scalable, support +[high availability](../administration/high_availability/README.md) and are used +today on GitLab.com. The Helm charts are recommended for those who are familiar +with Kubernetes. ## Requirements @@ -14,36 +31,58 @@ Before installing GitLab, make sure to check the [requirements documentation](re which includes useful information on the supported Operating Systems as well as the hardware requirements. -## Installation methods - -- [Installation using the Omnibus packages](https://about.gitlab.com/downloads/) - - Install GitLab using our official deb/rpm repositories. This is the - recommended way. -- [Installation from source](installation.md) - Install GitLab from source. - Useful for unsupported systems like *BSD. For an overview of the directory - structure, read the [structure documentation](structure.md). -- [Docker](docker.md) - Install GitLab using Docker. - -## Install GitLab on cloud providers - -- [Installing in Kubernetes](kubernetes/index.md): Install GitLab into a Kubernetes - Cluster using our official Helm Chart Repository. -- [Install GitLab on OpenShift](openshift_and_gitlab/index.md) -- [Install GitLab on DC/OS](https://mesosphere.com/blog/gitlab-dcos/) via [GitLab-Mesosphere integration](https://about.gitlab.com/2016/09/16/announcing-gitlab-and-mesosphere/) -- [Install GitLab on Azure](azure/index.md) -- [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. -- [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. +## Installing GitLab using the Omnibus GitLab package (recommended) + +The Omnibus GitLab package uses our official deb/rpm repositories. This is +recommended for most users. + +If you need additional flexibility and resilience, we recommend deploying +GitLab as described in our [High Availability documentation](../administration/high_availability/README.md). + +[**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/) + +## Installing GitLab on Kubernetes via the GitLab Helm charts + +NOTE: **Kubernetes experience required:** +We recommend being familiar with Kubernetes before using it to deploy GitLab in +production. The methods for management, observability, and some concepts are +different than traditional deployments. + +When installing GitLab on Kubernetes, there are some trade-offs that you +need to be aware of: -## Database +- Administration and troubleshooting requires Kubernetes knowledge. +- It can be more expensive for smaller installations. The default installation + requires more resources than a single node Omnibus deployment, as most services + are deployed in a redundant fashion. +- There are some feature [limitations to be aware of](kubernetes/gitlab_chart.md#limitations). -While the recommended database is PostgreSQL, we provide information to install -GitLab using MySQL. Check the [MySQL documentation](database_mysql.md) for more -information. +[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](kubernetes/index.md) -[methods]: https://about.gitlab.com/installation/ +## Installing GitLab with Docker + +GitLab maintains a set of official Docker images based on the Omnibus GitLab package. + +[**> Install GitLab using the official GitLab Docker images.**](docker.md) + +## Installing GitLab from source + +If the GitLab Omnibus package is not available in your distribution, you can +install GitLab from source: Useful for unsupported systems like *BSD. For an +overview of the directory structure, read the [structure documentation](structure.md). + +[**> Install GitLab from source.**](installation.md) + +## Installing GitLab on cloud providers + +GitLab can be installed on a variety of cloud providers by using any of +the above methods, provided the cloud provider supports it. + +- [Install on AWS](aws/index.md): Install Omnibus GitLab on AWS using the community AMIs that GitLab provides. +- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md): Install Omnibus GitLab on a VM in GCP. +- [Install GitLab on Azure](azure/index.md): Install Omnibus GitLab from Azure Marketplace. +- [Install GitLab on OpenShift](openshift_and_gitlab/index.md): Install GitLab using the Docker image on OpenShift. +- [Install GitLab on DC/OS](https://mesosphere.com/blog/gitlab-dcos/): Install GitLab on Mesosphere DC/OS via the [GitLab-Mesosphere integration](https://about.gitlab.com/2016/09/16/announcing-gitlab-and-mesosphere/). +- [Install GitLab on DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): Install Omnibus GitLab on DigitalOcean. +- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md): + Quickly test any version of GitLab on DigitalOcean using Docker Machine. 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..6e10d9647b1 --- /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..a07d42dd6fb --- /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..431dbb0251b --- /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..08a9b169267 --- /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..e209a00b38c --- /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 7835401cc0b..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 diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md index acaed53e052..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 @@ -84,14 +89,15 @@ GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/m 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 676392eacf2..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` -##### Set up 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/docker.md b/doc/install/docker.md index c7dc9db70c5..d0129f0f5c4 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -7,9 +7,10 @@ GitLab provides official Docker images to allowing you to easily take advantage ## Omnibus GitLab based images GitLab maintains a set of [official Docker images](https://hub.docker.com/r/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include: -* [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/) -* [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/) -* [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/) + +- [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/) +- [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/) +- [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/) A [complete usage guide](https://docs.gitlab.com/omnibus/docker/) to these images is available, as well as the [Dockerfile used for building the images](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docker). diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index ab5f7507f24..aa4b3dccf7d 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -22,14 +22,14 @@ Once you have performed those two steps, you can [create a VM](#creating-the-vm) To deploy GitLab on GCP you need to follow five simple steps: -1. Go to https://console.cloud.google.com/compute/instances and login with your Google credentials. +1. Go to <https://console.cloud.google.com/compute/instances> and login with your Google credentials. 1. Click on **Create**  1. On the next page, you can select the type of VM as well as the - estimated costs. Provide the name of the instance, desired datacenter, and machine type. Note that GitLab recommends at least 2 vCPU's and 4GB of RAM. + estimated costs. Provide the name of the instance, desired datacenter, and machine type. Note that GitLab recommends at least 2 vCPU's and 4GB of RAM.  @@ -51,7 +51,7 @@ After a few seconds, the instance will be created and available to log in. The n  -1. Next, follow the instructions for installing GitLab for the operating system you choose, at https://about.gitlab.com/installation/. You can use the IP address from the step above, as the hostname. +1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/installation/>. You can use the IP address from the step above, as the hostname. 1. Congratulations! GitLab is now installed and you can access it via your browser. To finish installation, open the URL in your browser and provide the initial administrator password. The username for this account is `root`. diff --git a/doc/install/installation.md b/doc/install/installation.md index 9e2e58657f1..1f65e3415d1 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -6,28 +6,29 @@ Since an installation from source is a lot of work and error prone we strongly r One reason the Omnibus package is more reliable is its use of Runit to restart any of the GitLab processes in case one crashes. On heavily used GitLab instances the memory usage of the Sidekiq background worker will grow over time. -Omnibus packages solve this by [letting the Sidekiq terminate gracefully](http://docs.gitlab.com/ce/operations/sidekiq_memory_killer.html) if it uses too much memory. + +Omnibus packages solve this by [letting the Sidekiq terminate gracefully](../administration/operations/sidekiq_memory_killer.md) if it uses too much memory. After this termination Runit will detect Sidekiq is not running and will start it. Since installations from source don't have Runit, Sidekiq can't be terminated and its memory usage will grow over time. ## 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-4-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-7-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. +If the highest number stable branch is unclear, check the [GitLab blog](https://about.gitlab.com/blog/) for installation guide links by version. ## Important Notes This guide is long because it covers many cases and includes all commands you need, this is [one of the few installation scripts that actually works out of the box](https://twitter.com/robinvdvleuten/status/424163226532986880). -This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/). +This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS, we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/). -This is the official installation guide to set up a production server. To set up a **development installation** or for many other installation options please see [the installation section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#installation). +This is the official installation guide to set up a production server. To set up a **development installation** or for many other installation options, see [the installation section of the README](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#installation). -The following steps have been known to work. Please **use caution when you deviate** from this guide. Make sure you don't violate any assumptions GitLab makes about its environment. For example many people run into permission problems because they changed the location of directories or run services as the wrong user. +The following steps have been known to work. **Use caution when you deviate** from this guide. Make sure you don't violate any assumptions GitLab makes about its environment. For example, many people run into permission problems because they changed the location of directories or run services as the wrong user. -If you find a bug/error in this guide please **submit a merge request** +If you find a bug/error in this guide, **submit a merge request** following the [contributing guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md). @@ -35,77 +36,102 @@ following the The GitLab installation consists of setting up the following components: -1. Packages / Dependencies -1. Ruby -1. Go -1. Node -1. System Users -1. Database -1. Redis -1. GitLab -1. Nginx +1. [Packages and dependencies](#1-packages-and-dependencies). +1. [Ruby](#2-ruby). +1. [Go](#3-go). +1. [Node](#4-node). +1. [System users](#5-system-users). +1. [Database](#6-database). +1. [Redis](#7-redis). +1. [GitLab](#8-gitlab). +1. [Nginx](#9-nginx). -## 1. Packages / Dependencies +## 1. Packages and dependencies `sudo` is not installed on Debian by default. Make sure your system is up-to-date and install it. - # run as root! - apt-get update -y - apt-get upgrade -y - apt-get install sudo -y +```sh +# run as root! +apt-get update -y +apt-get upgrade -y +apt-get install sudo -y +``` -**Note:** During this installation some files will need to be edited manually. If you are familiar with vim set it as default editor with the commands below. If you are not familiar with vim please skip this and keep using the default editor. +NOTE: **Note:** +During this installation, some files will need to be edited manually. If you are familiar with vim, set it as default editor with the commands below. If you are not familiar with vim, skip this and keep using the default editor. - # Install vim and set as default editor - sudo apt-get install -y vim - sudo update-alternatives --set editor /usr/bin/vim.basic +```sh +# Install vim and set as default editor +sudo apt-get install -y vim +sudo update-alternatives --set editor /usr/bin/vim.basic +``` Install the required packages (needed to compile Ruby and native extensions to Ruby gems): - sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev libreadline-dev libncurses5-dev libffi-dev curl openssh-server checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libicu-dev logrotate rsync python-docutils pkg-config cmake +```sh +sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libre2-dev \ + libreadline-dev libncurses5-dev libffi-dev curl openssh-server checkinstall libxml2-dev \ + libxslt-dev libcurl4-openssl-dev libicu-dev logrotate rsync python-docutils pkg-config cmake +``` Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but you can [install re2 manually](https://github.com/google/re2/wiki/Install). -If you want to use Kerberos for user authentication, then install libkrb5-dev: +If you want to use Kerberos for user authentication, install `libkrb5-dev`: - sudo apt-get install libkrb5-dev +```sh +sudo apt-get install libkrb5-dev +``` -**Note:** If you don't know what Kerberos is, you can assume you don't need it. +NOTE: **Note:** +If you don't know what Kerberos is, you can assume you don't need it. -Make sure you have the right version of Git installed +Make sure you have the right version of Git installed: - # Install Git - sudo apt-get install -y git-core +```sh +# Install Git +sudo apt-get install -y git-core - # Make sure Git is version 2.9.5 or higher - git --version +# 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. - # Remove packaged Git - sudo apt-get remove git-core +```sh +# Remove packaged Git +sudo apt-get remove git-core + +# Install dependencies +sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential - # Install dependencies - sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential +# Download and compile from source +cd /tmp +curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.18.0.tar.gz +echo '94faf2c0b02a7920b0b46f4961d8e9cad08e81418614102898a55f980fa3e7e4 git-2.18.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.18.0.tar.gz +cd git-2.18.0/ +./configure +make prefix=/usr/local all - # Download and compile from source - cd /tmp - curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.18.0.tar.gz - echo '94faf2c0b02a7920b0b46f4961d8e9cad08e81418614102898a55f980fa3e7e4 git-2.18.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.18.0.tar.gz - cd git-2.18.0/ - ./configure - make prefix=/usr/local all +# Install into /usr/local/bin +sudo make prefix=/usr/local install - # Install into /usr/local/bin - sudo make prefix=/usr/local install +# When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git +``` - # When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git +For the [Custom Favicon](../customization/favicon.md) to work, GraphicsMagick +needs to be installed. + +```sh +sudo apt-get install -y graphicsmagick +``` **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 +```sh +sudo apt-get install -y postfix +``` Then select 'Internet Site' and press enter to confirm the hostname. @@ -127,22 +153,28 @@ instructions are designed to install Ruby from the official source code. Remove the old Ruby 1.8 if present: - sudo apt-get remove ruby1.8 +```sh +sudo apt-get remove ruby1.8 +``` 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 - - ./configure --disable-install-rdoc - make - sudo make install +```sh +mkdir /tmp/ruby && cd /tmp/ruby +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 +sudo make install +``` -Then install the Bundler Gem: +Then install the Bundler gem (a version below 2.x): - sudo gem install bundler --no-ri --no-rdoc +```sh +sudo gem install bundler --no-document --version '< 2' +``` ## 3. Go @@ -151,81 +183,91 @@ GitLab we need a Go compiler. The instructions below assume you use 64-bit Linux. You can find downloads for other platforms at the [Go download page](https://golang.org/dl). - # 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 +```sh +# 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 +``` ## 4. Node -Since GitLab 8.17, GitLab requires the use of Node to compile javascript -assets, and Yarn to manage javascript dependencies. The current minimum -requirements for these are node >= v6.0.0 and yarn >= v1.2.0. In many distros +Since GitLab 8.17, GitLab requires the use of Node to compile JavaScript +assets, and Yarn to manage JavaScript dependencies. The current minimum +requirements for these are: + +- `node` >= v8.10.0. +- `yarn` >= v1.10.0. + +In many distros, the versions provided by the official package repositories are out of date, so we'll need to install through the following commands: - # install node v8.x - curl --location https://deb.nodesource.com/setup_8.x | sudo bash - - sudo apt-get install -y nodejs - - 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 +```sh +# install node v8.x +curl --location https://deb.nodesource.com/setup_8.x | sudo bash - +sudo apt-get install -y nodejs + +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 +``` Visit the official websites for [node](https://nodejs.org/en/download/package-manager/) and [yarn](https://yarnpkg.com/en/docs/install/) if you have any trouble with these steps. -## 5. System Users +## 5. System users Create a `git` user for GitLab: - sudo adduser --disabled-login --gecos 'GitLab' git +```sh +sudo adduser --disabled-login --gecos 'GitLab' git +``` ## 6. Database -We recommend using a PostgreSQL database. For MySQL check the -[MySQL setup guide](database_mysql.md). +We recommend using a PostgreSQL database. For MySQL, see the [MySQL setup guide](database_mysql.md). -> **Note**: because we need to make use of extensions and concurrent index removal, -you need at least PostgreSQL 9.2. +NOTE: **Note:** +Because we need to make use of extensions and concurrent index removal, you need at least PostgreSQL 9.2. 1. Install the database packages: - ```bash + ```sh sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib ``` 1. Create a database user for GitLab: - ```bash + ```sh sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" ``` 1. Create the `pg_trgm` extension (required for GitLab 8.6+): - ```bash + ```sh sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" ``` 1. Create the GitLab production database and grant all privileges on database: - ```bash + ```sh sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;" ``` 1. Try connecting to the new database with the new user: - ```bash + ```sh sudo -u git -H psql -d gitlabhq_production ``` 1. Check if the `pg_trgm` extension is enabled: - ```bash + ```sh SELECT true AS enabled FROM pg_available_extensions WHERE name = 'pg_trgm' @@ -243,7 +285,7 @@ you need at least PostgreSQL 9.2. 1. Quit the database session: - ```bash + ```sh gitlabhq_production> \q ``` @@ -251,7 +293,7 @@ you need at least PostgreSQL 9.2. GitLab requires at least Redis 2.8. -If you are using Debian 8 or Ubuntu 14.04 and up, then you can simply install +If you are using Debian 8 or Ubuntu 14.04 and up, you can simply install Redis 2.8 with: ```sh @@ -262,7 +304,7 @@ If you are using Debian 7 or Ubuntu 12.04, follow the special documentation on [an alternate Redis installation](redis.md). Once done, follow the rest of the guide here. -``` +```sh # Configure redis to use sockets sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig @@ -294,146 +336,171 @@ sudo usermod -aG redis git ## 8. GitLab - # We'll install GitLab into home directory of the user "git" - cd /home/git +```sh +# We'll install GitLab into home directory of the user "git" +cd /home/git +``` ### Clone the Source - # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-4-stable gitlab +```sh +# Clone GitLab repository +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-7-stable gitlab +``` -**Note:** You can change `11-4-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +CAUTION: **Caution:** +You can change `11-7-stable` to `master` if you want the *bleeding edge* version, but never install `master` on a production server! ### Configure It - # Go to GitLab installation folder - cd /home/git/gitlab +```sh +# Go to GitLab installation folder +cd /home/git/gitlab - # Copy the example GitLab config - sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml +# Copy the example GitLab config +sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml - # Update GitLab config file, follow the directions at top of file - sudo -u git -H editor config/gitlab.yml +# Update GitLab config file, follow the directions at top of file +sudo -u git -H editor config/gitlab.yml - # Copy the example secrets file - sudo -u git -H cp config/secrets.yml.example config/secrets.yml - sudo -u git -H chmod 0600 config/secrets.yml +# Copy the example secrets file +sudo -u git -H cp config/secrets.yml.example config/secrets.yml +sudo -u git -H chmod 0600 config/secrets.yml - # Make sure GitLab can write to the log/ and tmp/ directories - sudo chown -R git log/ - sudo chown -R git tmp/ - sudo chmod -R u+rwX,go-w log/ - sudo chmod -R u+rwX tmp/ +# Make sure GitLab can write to the log/ and tmp/ directories +sudo chown -R git log/ +sudo chown -R git tmp/ +sudo chmod -R u+rwX,go-w log/ +sudo chmod -R u+rwX tmp/ - # Make sure GitLab can write to the tmp/pids/ and tmp/sockets/ directories - sudo chmod -R u+rwX tmp/pids/ - sudo chmod -R u+rwX tmp/sockets/ +# Make sure GitLab can write to the tmp/pids/ and tmp/sockets/ directories +sudo chmod -R u+rwX tmp/pids/ +sudo chmod -R u+rwX tmp/sockets/ - # Create the public/uploads/ directory - sudo -u git -H mkdir public/uploads/ +# Create the public/uploads/ directory +sudo -u git -H mkdir public/uploads/ - # Make sure only the GitLab user has access to the public/uploads/ directory - # now that files in public/uploads are served by gitlab-workhorse - sudo chmod 0700 public/uploads +# Make sure only the GitLab user has access to the public/uploads/ directory +# now that files in public/uploads are served by gitlab-workhorse +sudo chmod 0700 public/uploads - # Change the permissions of the directory where CI job traces are stored - sudo chmod -R u+rwX builds/ +# Change the permissions of the directory where CI job traces are stored +sudo chmod -R u+rwX builds/ - # Change the permissions of the directory where CI artifacts are stored - sudo chmod -R u+rwX shared/artifacts/ +# Change the permissions of the directory where CI artifacts are stored +sudo chmod -R u+rwX shared/artifacts/ - # Change the permissions of the directory where GitLab Pages are stored - sudo chmod -R ug+rwX shared/pages/ +# Change the permissions of the directory where GitLab Pages are stored +sudo chmod -R ug+rwX shared/pages/ - # Copy the example Unicorn config - sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb +# Copy the example Unicorn config +sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb - # Find number of cores - nproc +# Find number of cores +nproc - # Enable cluster mode if you expect to have a high load instance - # Set the number of workers to at least the number of cores - # Ex. change amount of workers to 3 for 2GB RAM server - sudo -u git -H editor config/unicorn.rb +# Enable cluster mode if you expect to have a high load instance +# Set the number of workers to at least the number of cores +# Ex. change amount of workers to 3 for 2GB RAM server +sudo -u git -H editor config/unicorn.rb - # Copy the example Rack attack config - sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb +# Copy the example Rack attack config +sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb - # Configure Git global settings for git user - # 'autocrlf' is needed for the web editor - sudo -u git -H git config --global core.autocrlf input +# Configure Git global settings for git user +# 'autocrlf' is needed for the web editor +sudo -u git -H git config --global core.autocrlf input - # Disable 'git gc --auto' because GitLab already runs 'git gc' when needed - sudo -u git -H git config --global gc.auto 0 +# Disable 'git gc --auto' because GitLab already runs 'git gc' when needed +sudo -u git -H git config --global gc.auto 0 - # Enable packfile bitmaps - sudo -u git -H git config --global repack.writeBitmaps true +# Enable packfile bitmaps +sudo -u git -H git config --global repack.writeBitmaps true - # Enable push options - sudo -u git -H git config --global receive.advertisePushOptions true +# Enable push options +sudo -u git -H git config --global receive.advertisePushOptions true - # Configure Redis connection settings - sudo -u git -H cp config/resque.yml.example config/resque.yml +# Configure Redis connection settings +sudo -u git -H cp config/resque.yml.example config/resque.yml - # Change the Redis socket path if you are not using the default Debian / Ubuntu configuration - sudo -u git -H editor config/resque.yml +# Change the Redis socket path if you are not using the default Debian / Ubuntu configuration +sudo -u git -H editor config/resque.yml +``` -**Important Note:** Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. +CAUTION: **Caution:** +Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. -**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. +NOTE: **Note:** +If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. ### Configure GitLab DB Settings - # PostgreSQL only: - sudo -u git cp config/database.yml.postgresql config/database.yml +```sh +# PostgreSQL only: +sudo -u git cp config/database.yml.postgresql config/database.yml + +# MySQL only: +sudo -u git cp config/database.yml.mysql config/database.yml + +# MySQL and remote PostgreSQL only: +# Update username/password in config/database.yml. +# You only need to adapt the production settings (first part). +# If you followed the database guide then please do as follows: +# Change 'secure password' with the value you have given to $password +# You can keep the double quotes around the password +sudo -u git -H editor config/database.yml + +# PostgreSQL and MySQL: +# Make config/database.yml readable to git only +sudo -u git -H chmod o-rwx config/database.yml +``` - # MySQL only: - sudo -u git cp config/database.yml.mysql config/database.yml +### Install Gems - # MySQL and remote PostgreSQL only: - # Update username/password in config/database.yml. - # You only need to adapt the production settings (first part). - # If you followed the database guide then please do as follows: - # Change 'secure password' with the value you have given to $password - # You can keep the double quotes around the password - sudo -u git -H editor config/database.yml +NOTE: **Note:** +As of Bundler 1.5.2, you can invoke `bundle install -jN` (where `N` is the number of your processor cores) and enjoy parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with `nproc`. For more information, see this [post](https://robots.thoughtbot.com/parallel-gem-installing-using-bundler). - # PostgreSQL and MySQL: - # Make config/database.yml readable to git only - sudo -u git -H chmod o-rwx config/database.yml +Make sure you have `bundle` (run `bundle -v`): -### Install Gems +- `>= 1.5.2`, because some [issues](https://devcenter.heroku.com/changelog-items/411) were [fixed](https://github.com/bundler/bundler/pull/2817) in 1.5.2. +- `< 2.x`. -**Note:** As of bundler 1.5.2, you can invoke `bundle install -jN` (where `N` the number of your processor cores) and enjoy the parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with `nproc`. For more information check this [post](https://robots.thoughtbot.com/parallel-gem-installing-using-bundler). First make sure you have bundler >= 1.5.2 (run `bundle -v`) as it addresses some [issues](https://devcenter.heroku.com/changelog-items/411) that were [fixed](https://github.com/bundler/bundler/pull/2817) in 1.5.2. - - # For PostgreSQL (note, the option says "without ... mysql") - sudo -u git -H bundle install --deployment --without development test mysql aws kerberos +```sh +# For PostgreSQL (note, the option says "without ... mysql") +sudo -u git -H bundle install --deployment --without development test mysql aws kerberos - # Or if you use MySQL (note, the option says "without ... postgres") - sudo -u git -H bundle install --deployment --without development test postgres aws kerberos +# Or if you use MySQL (note, the option says "without ... postgres") +sudo -u git -H bundle install --deployment --without development test postgres aws kerberos +``` -**Note:** If you want to use Kerberos for user authentication, then omit `kerberos` in the `--without` option above. +NOTE: **Note:** +If you want to use Kerberos for user authentication, omit `kerberos` in the `--without` option above. ### Install GitLab Shell GitLab Shell is an SSH access and repository management software developed specially for GitLab. - # Run the installation task for gitlab-shell (replace `REDIS_URL` if needed): - sudo -u git -H bundle exec rake gitlab:shell:install REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production SKIP_STORAGE_VALIDATION=true +```sh +# Run the installation task for gitlab-shell (replace `REDIS_URL` if needed): +sudo -u git -H bundle exec rake gitlab:shell:install REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production SKIP_STORAGE_VALIDATION=true - # By default, the gitlab-shell config is generated from your main GitLab config. - # You can review (and modify) the gitlab-shell config as follows: - sudo -u git -H editor /home/git/gitlab-shell/config.yml +# By default, the gitlab-shell config is generated from your main GitLab config. +# You can review (and modify) the gitlab-shell config as follows: +sudo -u git -H editor /home/git/gitlab-shell/config.yml +``` -**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. +NOTE: **Note:** +If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. -**Note:** Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in /etc/hosts ("127.0.0.1 hostname"). This might be necessary for example if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with "Check GitLab API access: FAILED. code: 401" and pushing commits will be rejected with "[remote rejected] master -> master (hook declined)". +NOTE: **Note:** +Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with "Check GitLab API access: FAILED. code: 401" and pushing commits will be rejected with "[remote rejected] master -> master (hook declined)". -**Note:** GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several manners: +NOTE: **Note:** +GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several ways: -* Export `RUBYOPT=--disable-gems` environment variable for the processes -* Compile Ruby with `configure --disable-rubygems` to disable RubyGems by default. Not recommended for system-wide Ruby. -* Omnibus GitLab [replaces the *shebang* line of the `gitlab-shell/bin/*` scripts](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1707) +- Export `RUBYOPT=--disable-gems` environment variable for the processes. +- Compile Ruby with `configure --disable-rubygems` to disable RubyGems by default. Not recommended for system-wide Ruby. +- Omnibus GitLab [replaces the *shebang* line of the `gitlab-shell/bin/*` scripts](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1707). ### Install gitlab-workhorse @@ -441,57 +508,74 @@ GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The following command-line will install GitLab-Workhorse in `/home/git/gitlab-workhorse` which is the recommended location. - sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production +```sh +sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" 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:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production +```sh +sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production +``` -### Install gitlab-pages +### Install GitLab Pages -GitLab-Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands will install GitLab-Pages in `/home/git/gitlab-pages`. For additional setup steps, please consult the [administration guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be ran several different ways. +GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands will install GitLab Pages in `/home/git/gitlab-pages`. For additional setup steps, consult the [administration guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be run several different ways. - cd /home/git - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git - cd gitlab-pages - sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) - sudo -u git -H make +```sh +cd /home/git +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git +cd gitlab-pages +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` ### 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 +```sh +# Fetch Gitaly source with Git and compile with Go +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 +```sh +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: - # Restrict Gitaly socket access - sudo chmod 0700 /home/git/gitlab/tmp/sockets/private - sudo chown git /home/git/gitlab/tmp/sockets/private +```sh +# Restrict Gitaly socket access +sudo chmod 0700 /home/git/gitlab/tmp/sockets/private +sudo chown git /home/git/gitlab/tmp/sockets/private - # If you are using non-default settings you need to update config.toml - cd /home/git/gitaly - sudo -u git -H editor config.toml +# If you are using non-default settings you need to update config.toml +cd /home/git/gitaly +sudo -u git -H editor config.toml +``` For more information about configuring Gitaly see [doc/administration/gitaly](../administration/gitaly). ### Initialize Database and Activate Advanced Features - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production - # Type 'yes' to create the database tables. +```sh +sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production +# Type 'yes' to create the database tables. - # or you can skip the question by adding force=yes - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes +# or you can skip the question by adding force=yes +sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production force=yes - # When done you see 'Administrator account created:' +# When done you see 'Administrator account created:' +``` -**Note:** You can set the Administrator/root password and e-mail by supplying them in environmental variables, `GITLAB_ROOT_PASSWORD` and `GITLAB_ROOT_EMAIL` respectively, as seen below. If you don't set the password (and it is set to the default one) please wait with exposing GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login you'll be forced to change the default password. +NOTE: **Note:** +You can set the Administrator/root password and e-mail by supplying them in environmental variables, `GITLAB_ROOT_PASSWORD` and `GITLAB_ROOT_EMAIL` respectively, as seen below. If you don't set the password (and it is set to the default one), wait to expose GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login, you'll be forced to change the default password. - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail +```sh +sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail +``` ### Secure secrets.yml @@ -503,71 +587,93 @@ Otherwise your secrets are exposed if one of your backups is compromised. Download the init script (will be `/etc/init.d/gitlab`): - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +```sh +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` And if you are installing with a non-default folder or user copy and edit the defaults file: - sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab +```sh +sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab +``` -If you installed GitLab in another directory or as a user other than the default you should change these settings in `/etc/default/gitlab`. Do not edit `/etc/init.d/gitlab` as it will be changed on upgrade. +If you installed GitLab in another directory or as a user other than the default, you should change these settings in `/etc/default/gitlab`. Do not edit `/etc/init.d/gitlab` as it will be changed on upgrade. Make GitLab start on boot: - sudo update-rc.d gitlab defaults 21 +```sh +sudo update-rc.d gitlab defaults 21 +``` ### Set up Logrotate - sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab +```sh +sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab +``` ### Check Application Status Check if GitLab and its environment are configured correctly: - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - +```sh +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` ### Compile GetText PO files - sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production +```sh +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production +``` ### Compile Assets - sudo -u git -H yarn install --production --pure-lockfile - sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production +```sh +sudo -u git -H yarn install --production --pure-lockfile +sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production +``` ### Start Your GitLab Instance - sudo service gitlab start - # or - sudo /etc/init.d/gitlab restart +```sh +sudo service gitlab start +# or +sudo /etc/init.d/gitlab restart +``` ## 9. Nginx -**Note:** Nginx is the officially supported web server for GitLab. If you cannot or do not want to use Nginx as your web server, have a look at the [GitLab recipes](https://gitlab.com/gitlab-org/gitlab-recipes/). +NOTE: **Note:** +Nginx is the officially supported web server for GitLab. If you cannot or do not want to use Nginx as your web server, see [GitLab recipes](https://gitlab.com/gitlab-org/gitlab-recipes/). ### Installation - sudo apt-get install -y nginx +```sh +sudo apt-get install -y nginx +``` ### Site Configuration Copy the example site config: - sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab - sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab +```sh +sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab +sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab +``` -Make sure to edit the config file to match your setup. Also, ensure that you match your paths to GitLab, especially if installing for a user other than the 'git' user: +Make sure to edit the config file to match your setup. Also, ensure that you match your paths to GitLab, especially if installing for a user other than the `git` user: - # Change YOUR_SERVER_FQDN to the fully-qualified - # domain name of your host serving GitLab. - # - # Remember to match your paths to GitLab, especially - # if installing for a user other than 'git'. - # - # If using Ubuntu default nginx install: - # either remove the default_server from the listen line - # or else sudo rm -f /etc/nginx/sites-enabled/default - sudo editor /etc/nginx/sites-available/gitlab +```sh +# Change YOUR_SERVER_FQDN to the fully-qualified +# domain name of your host serving GitLab. +# +# Remember to match your paths to GitLab, especially +# if installing for a user other than 'git'. +# +# If using Ubuntu default nginx install: +# either remove the default_server from the listen line +# or else sudo rm -f /etc/nginx/sites-enabled/default +sudo editor /etc/nginx/sites-available/gitlab +``` If you intend to enable GitLab pages, there is a separate Nginx config you need to use. Read all about the needed configuration at the @@ -579,13 +685,17 @@ to use. Read all about the needed configuration at the Validate your `gitlab` or `gitlab-ssl` Nginx config file with the following command: - sudo nginx -t +```sh +sudo nginx -t +``` You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` Nginx config file for typos, etc. as indicated in the error message given. ### Restart - sudo service nginx restart +```sh +sudo service nginx restart +``` ## Done! @@ -593,9 +703,11 @@ You should receive `syntax is okay` and `test is successful` messages. If you re To make sure you didn't miss anything run a more thorough check with: - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +```sh +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` -If all items are green, then congratulations on successfully installing GitLab! +If all items are green, congratulations on successfully installing GitLab! NOTE: Supply `SANITIZE=true` environment variable to `gitlab:check` to omit project names from the output of the check command. @@ -637,11 +749,11 @@ To use GitLab with HTTPS: 1. Update `ssl_certificate` and `ssl_certificate_key`. 1. Review the configuration file and consider applying other security and performance enhancing features. -Using a self-signed certificate is discouraged but if you must use it follow the normal directions then: +Using a self-signed certificate is discouraged but if you must use it, follow the normal directions. Then: 1. Generate a self-signed SSL certificate: - ``` + ```sh mkdir -p /etc/nginx/ssl/ cd /etc/nginx/ssl/ sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key @@ -655,16 +767,16 @@ See the ["Reply by email" documentation](../administration/reply_by_email.md) fo ### LDAP Authentication -You can configure LDAP authentication in `config/gitlab.yml`. Please restart GitLab after editing this file. +You can configure LDAP authentication in `config/gitlab.yml`. Restart GitLab after editing this file. ### Using Custom Omniauth Providers -See the [omniauth integration document](../integration/omniauth.md) +See the [omniauth integration document](../integration/omniauth.md). ### Build your projects -GitLab can build your projects. To enable that feature you need GitLab Runners to do that for you. -Checkout the [GitLab Runner section](https://about.gitlab.com/gitlab-ci/#gitlab-runner) to install it +GitLab can build your projects. To enable that feature, you need GitLab Runners to do that for you. +See the [GitLab Runner section](https://about.gitlab.com/product/continuous-integration/#gitlab-runner) to install it. ### Adding your Trusted Proxies @@ -680,37 +792,45 @@ for the changes to take effect. If you'd like to connect to a Redis server on a non-standard port or on a different host, you can configure its connection string via the `config/resque.yml` file. - # example - production: - url: redis://redis.example.tld:6379 +``` +# example +production: + url: redis://redis.example.tld:6379 +``` -If you want to connect the Redis server via socket, then use the "unix:" URL scheme and the path to the Redis socket file in the `config/resque.yml` file. +If you want to connect the Redis server via socket, use the "unix:" URL scheme and the path to the Redis socket file in the `config/resque.yml` file. - # example - production: - url: unix:/path/to/redis/socket +``` +# example +production: + url: unix:/path/to/redis/socket +``` Also you can use environment variables in the `config/resque.yml` file: - # example - production: - url: <%= ENV.fetch('GITLAB_REDIS_URL') %> +``` +# example +production: + url: <%= ENV.fetch('GITLAB_REDIS_URL') %> +``` ### Custom SSH Connection If you are running SSH on a non-standard port, you must change the GitLab user's SSH config. - # Add to /home/git/.ssh/config - host localhost # Give your setup a name (here: override localhost) - user git # Your remote git user - port 2222 # Your port number - hostname 127.0.0.1; # Your server name or IP +``` +# Add to /home/git/.ssh/config +host localhost # Give your setup a name (here: override localhost) + user git # Your remote git user + port 2222 # Your port number + hostname 127.0.0.1; # Your server name or IP +``` You also need to change the corresponding options (e.g. `ssh_user`, `ssh_host`, `admin_uri`) in the `config\gitlab.yml` file. ### Additional Markup Styles -Apart from the always supported markdown style there are other rich text files that GitLab can display. But 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. +Apart from the always supported markdown style, there are other rich text files that GitLab can display. But you might have to install a dependency to do so. See the [github-markup gem README](https://github.com/gitlabhq/markup#markups) for more information. ## Troubleshooting diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 6d1bc4aedc4..26ced45de7b 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -1,7 +1,14 @@ # GitLab Helm Chart -This is the official and recommended way to install GitLab on a cloud native environment. -For more information on other available GitLab Helm Charts, see the [charts overview](index.md#chart-overview). +This is the official way to install GitLab on a cloud native environment. + +NOTE: **Kubernetes experience required:** +Our Helm charts are recommended for those who are familiar with Kubernetes. +If you're not sure if Kubernetes is for you, our +[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended) +are mature, scalable, support [high availability](../../administration/high_availability/README.md) +and are used today on GitLab.com. +It is not necessary to have GitLab installed on Kubernetes in order to use [GitLab Kubernetes integration](https://docs.gitlab.com/ee/user/project/clusters/index.html). ## Introduction @@ -31,7 +38,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 @@ -40,8 +47,9 @@ In order to deploy GitLab on Kubernetes, the following are required: 1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md). 1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended. - - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster) - [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) + - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster) + - [IBM IKS](https://console.bluemix.net/docs/tutorials/scalable-webapp-kubernetes.html#create_kube_cluster) - [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal) 1. A [wildcard DNS entry and external IP address](preparation/networking.md) 1. [Authenticate and connect](preparation/connect.md) to the cluster @@ -112,8 +120,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_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index 498b702cab1..2ae5485869e 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -7,7 +7,7 @@ instead. A comparison of the two charts is available in [this video](https://you For more information on available GitLab Helm Charts, see the [charts overview](index.md#chart-overview). - This GitLab-Omnibus chart has been tested on Google Kubernetes Engine and Azure Container Service. -- This work is based partially on: https://github.com/lwolf/kubernetes-gitlab/. GitLab would like to thank Sergey Nuzhdin for his work. +- This work is based partially on: <https://github.com/lwolf/kubernetes-gitlab/>. GitLab would like to thank Sergey Nuzhdin for his work. ## Introduction @@ -32,7 +32,7 @@ The deployment includes: ## Limitations [High Availability](../../administration/high_availability/README.md) and -[Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html) are not supported. +[Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) are not supported. ## Requirements 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/kubernetes/index.md b/doc/install/kubernetes/index.md index 69171fbb341..281630174e7 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -4,11 +4,19 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes. # Installing GitLab on Kubernetes +NOTE: **Kubernetes experience required:** +Our Helm charts are recommended for those who are familiar with Kubernetes. +If you're not sure if Kubernetes is for you, our +[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended) +are mature, scalable, support [high availability](../../administration/high_availability/README.md) +and are used today on GitLab.com. +It is not necessary to have GitLab installed on Kubernetes in order to use [GitLab Kubernetes integration](https://docs.gitlab.com/ee/user/project/clusters/index.html). + The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is -to take advantage of GitLab's Helm charts. [Helm] is a package -management tool for Kubernetes, allowing apps to be easily managed via their -Charts. A [Chart] is a detailed description of the application including how it -should be deployed, upgraded, and configured. +to take advantage of GitLab's Helm charts. [Helm](https://github.com/kubernetes/helm/blob/master/README.md) +is a package management tool for Kubernetes, allowing apps to be easily managed via their +Charts. A [Chart](https://github.com/kubernetes/charts) is a detailed description +of the application including how it should be deployed, upgraded, and configured. ## GitLab Chart @@ -32,29 +40,3 @@ and you'd like to leverage the Runner's it can be deployed with the GitLab Runner chart. Learn more about [gitlab-runner chart](gitlab_runner_chart.md). - -## Deprecated Charts - -CAUTION: **Deprecated:** -These charts are **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md) -instead. - -### GitLab-Omnibus Chart - -This chart is based on the [GitLab Omnibus Docker images](https://docs.gitlab.com/omnibus/docker/). -It deploys and configures nearly all features of GitLab, including: - -- a [GitLab Runner](https://docs.gitlab.com/runner/) -- [Container Registry](../../user/project/container_registry.html#gitlab-container-registry) -- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/) -- [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego) -- and an [NGINX load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). - -Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md). - -### Community Contributed Charts - -The community has also contributed GitLab [CE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ce) and [EE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ee) charts to the [Helm Stable Repository](https://github.com/kubernetes/charts#repository-structure). These charts are [deprecated](https://github.com/kubernetes/charts/issues/1138) in favor of the [official Chart](gitlab_chart.md). - -[chart]: https://github.com/kubernetes/charts -[helm]: https://github.com/kubernetes/helm/blob/master/README.md diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 5c8a830ac8f..509020d1975 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -8,6 +8,12 @@ date: 2016-06-28 # How to install GitLab on OpenShift Origin 3 +CAUTION: **Deprecated:** +This article is deprecated. Use the official Kubernetes Helm charts for +installing GitLab to OpenShift. Check out the +[official installation docs](https://gitlab.com/charts/gitlab/blob/master/doc/cloud/openshift.md) +for details. + ## Introduction [OpenShift Origin][openshift] is an open source container application @@ -18,7 +24,7 @@ In this tutorial, we will see how to deploy GitLab in OpenShift using GitLab's official Docker image while getting familiar with the web interface and CLI tools that will help us achieve our goal. -For a video demonstration on installing GitLab on Openshift, check the article [In 13 minutes from Kubernetes to a complete application development tool](https://about.gitlab.com/2016/11/14/idea-to-production/). +For a video demonstration on installing GitLab on OpenShift, check the article [In 13 minutes from Kubernetes to a complete application development tool](https://about.gitlab.com/2016/11/14/idea-to-production/). --- @@ -505,7 +511,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" @@ -518,7 +524,7 @@ PaaS and managing your applications with the ease of containers. [templates]: https://docs.openshift.org/latest/architecture/core_concepts/templates.html "Documentation - OpenShift templates" [old-post]: https://blog.openshift.com/deploy-gitlab-openshift/ "Old post - Deploy GitLab on OpenShift" [line]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/658c065c8d022ce858dd63eaeeadb0b2ddc8deea/docker/openshift-template.json#L239 "GitLab - OpenShift template" -[oc-gh]: https://github.com/openshift/origin/releases/tag/v1.3.0 "Openshift 1.3.0 release on GitHub" +[oc-gh]: https://github.com/openshift/origin/releases/tag/v1.3.0 "OpenShift Origin 1.3.0 release on GitHub" [ha]: ../../administration/high_availability/gitlab.html "Documentation - GitLab High Availability" [replicas]: https://docs.openshift.org/latest/architecture/core_concepts/deployments.html#replication-controllers "Documentation - Replication controller" [autoscaling]: https://docs.openshift.org/latest/dev_guide/pod_autoscaling.html "Documentation - Autoscale" diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 13a6a1c68ad..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 @@ -104,7 +104,7 @@ 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 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. [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/install/structure.md b/doc/install/structure.md index d58b0040eef..8fc6ab4ab2f 100644 --- a/doc/install/structure.md +++ b/doc/install/structure.md @@ -9,10 +9,10 @@ This is the directory structure you will end up with following the instructions | |-- gitlab-shell | |-- repositories -* `/home/git/.ssh` - contains openssh settings. Specifically the `authorized_keys` file managed by gitlab-shell. -* `/home/git/gitlab` - GitLab core software. -* `/home/git/gitlab-shell` - Core add-on component of GitLab. Maintains SSH cloning and other functionality. -* `/home/git/repositories` - bare repositories for all projects organized by namespace. This is where the git repositories which are pushed/pulled are maintained for all projects. **This area is critical data for projects. [Keep a backup](../raketasks/backup_restore.md)** +- `/home/git/.ssh` - contains openssh settings. Specifically the `authorized_keys` file managed by gitlab-shell. +- `/home/git/gitlab` - GitLab core software. +- `/home/git/gitlab-shell` - Core add-on component of GitLab. Maintains SSH cloning and other functionality. +- `/home/git/repositories` - bare repositories for all projects organized by namespace. This is where the git repositories which are pushed/pulled are maintained for all projects. **This area is critical data for projects. [Keep a backup](../raketasks/backup_restore.md).** *Note: the default locations for repositories can be configured in `config/gitlab.yml` of GitLab and `config.yml` of gitlab-shell.* diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index a6436b5f926..35024a78fca 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -18,19 +18,19 @@ from happening. To use Akismet: -1. Go to the URL: https://akismet.com/account/ +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..e2ed7a4b1ab 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". @@ -21,12 +21,12 @@ configuration file. For example: - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` 1. Fill in the Allowed Callback URLs: - - http://`YOUR_GITLAB_URL`/users/auth/auth0/callback (or) - - https://`YOUR_GITLAB_URL`/users/auth/auth0/callback + - `http://YOUR_GITLAB_URL/users/auth/auth0/callback` (or) + - `https://YOUR_GITLAB_URL/users/auth/auth0/callback` 1. Fill in the Allowed Origins (CORS): - - http://`YOUR_GITLAB_URL` (or) - - https://`YOUR_GITLAB_URL` + - `http://YOUR_GITLAB_URL` (or) + - `https://YOUR_GITLAB_URL` 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/azure.md b/doc/integration/azure.md index 634dd952448..7a6d4bb143f 100644 --- a/doc/integration/azure.md +++ b/doc/integration/azure.md @@ -15,12 +15,12 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap - Type: 'WEB APPLICATION AND/OR WEB API' 1. On the "App properties" page enter the needed URI's and click the "Complete" button. - - SIGN-IN URL: Enter the URL of your GitLab installation (e.g 'https://gitlab.mycompany.com/') - - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g 'https://mycompany.onmicrosoft.com/gitlab') + - SIGN-IN URL: Enter the URL of your GitLab installation (e.g `https://gitlab.mycompany.com/`) + - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g `https://mycompany.onmicrosoft.com/gitlab`) 1. Select "Configure" in the top menu. -1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. https://gitlab.mycompany.com/users/auth/azure_oauth2/callback). +1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. `https://gitlab.mycompany.com/users/auth/azure_oauth2/callback`). 1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu.. @@ -28,7 +28,7 @@ To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your ap 1. Select "View endpoints" from the bottom menu. -1. You will see lots of endpoint URLs in the form 'https://login.microsoftonline.com/TENANT ID/...', note down the TENANT ID part of one of those endpoints. +1. You will see lots of endpoint URLs in the form `https://login.microsoftonline.com/TENANT ID/...`, note down the TENANT ID part of one of those endpoints. 1. On your GitLab server, open the configuration file. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index bf587b5b296..68ec8c4b5c2 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -43,9 +43,13 @@ you to use. | :--- | :---------- | | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. | | **Application description** | Fill this in if you wish. | - | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | + | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. | | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | + NOTE: Be sure to append `/users/auth` to the end of the callback URL + to prevent a [OAuth2 convert + redirect](http://tetraph.com/covert_redirect/) vulnerability. + NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will see an "Invalid redirect_uri" message. For more details, see [the Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). @@ -54,6 +58,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 7a83b8e4b35..eca9aa16499 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -1,28 +1,36 @@ -# 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}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port. +  + + NOTE: Be sure to append `/users/auth` to the end of the callback URL + to prevent a [OAuth2 convert + redirect](http://tetraph.com/covert_redirect/) vulnerability. + +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 +105,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. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index c19320471e3..cc5d444c069 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -14,9 +14,9 @@ To get this functioning, you need to be registered with Google. Pay close attention to: -* Email account used by GitLab to send notification emails needs to have "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". -* "A very very low rate of spam complaints from users." -* Emails must be authenticated via DKIM or SPF -* Before sending the final form("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. +- Email account used by GitLab to send notification emails needs to have "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". +- "A very very low rate of spam complaints from users." +- Emails must be authenticated via DKIM or SPF. +- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/1517). diff --git a/doc/integration/google.md b/doc/integration/google.md index 73e2f5826ff..d2b4e119978 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -35,7 +35,6 @@ 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. 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..b72cf03dd4d 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..0a1fe0ca65a --- /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..5786b822f53 --- /dev/null +++ b/doc/integration/img/github_register_app.png diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index acc9db15826..c02a29dffb4 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -3,8 +3,11 @@ This document is about using GitLab as an OAuth authentication service provider to sign in to other services. -If you want to use other OAuth authentication service providers to sign in to -GitLab, please see the [OAuth2 client documentation](../api/oauth2.md). +If you want to use: + +- Other OAuth authentication service providers to sign in to + GitLab, see the [OAuth2 client documentation](omniauth.md). +- The related API, see [Applications API](../api/applications.md). ## Introduction to OAuth @@ -28,7 +31,7 @@ GitLab supports two ways of adding a new OAuth2 application to an instance. You can either add an application as a regular user or add it in the admin area. What this means is that GitLab can actually have instance-wide and a user-wide applications. There is no difference between them except for the different -permission levels they are set (user/admin). The default callback URL is +permission levels they are set (user/admin). The default callback URL is `http://your-gitlab.example.com/users/auth/gitlab/callback` ## Adding an application through the profile diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 4e1d5ba9b35..f5f1f9486c2 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -66,7 +66,7 @@ that are in common for all providers that we need to consider. To change these settings: -* **For omnibus package** +- **For omnibus package** Open the configuration file: @@ -89,7 +89,7 @@ To change these settings: gitlab_rails['omniauth_block_auto_created_users'] = true ``` -* **For installations from source** +- **For installations from source** Open the configuration file: diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md index 932cd479d56..825c3654492 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 v2 keys. +1. Log in to your GitLab server, with administrator credentials. +1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`). +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..bb3cd9a005f 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -287,7 +287,7 @@ so you will not be able to sign in using local credentials. Make sure that at le of the SAML users has admin permissions. You may also bypass the auto signin feature by browsing to -https://gitlab.example.com/users/sign_in?auto_sign_in=false. +`https://gitlab.example.com/users/sign_in?auto_sign_in=false`. ### `attribute_statements` @@ -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/integration/twitter.md b/doc/integration/twitter.md index d0976b6201e..1cbfd81dfa9 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -10,8 +10,8 @@ To enable the Twitter OmniAuth provider you must register your application with - Name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Description: Create a description. - - Website: The URL to your GitLab installation. 'https://gitlab.example.com' - - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' + - Website: The URL to your GitLab installation. `https://gitlab.example.com` + - Callback URL: `https://gitlab.example.com/users/auth/twitter/callback` - Agree to the "Developer Agreement".  diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 9347a834510..4c4b423f40f 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.md @@ -71,7 +71,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=r ``` If this fails you need to fix it before upgrading to 8.0. Also see -https://about.gitlab.com/getting-help/ +<https://about.gitlab.com/get-help/> ### 2. Check source and target database types @@ -118,7 +118,7 @@ From this point on, GitLab CI will be unavailable for your end users. ### 1. Upgrade GitLab to 8.0 First upgrade your GitLab server to version 8.0: -https://about.gitlab.com/update/ +<https://about.gitlab.com/update/> ### 2. Disable CI on the GitLab server during the migration diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 03ba2ae8817..1d656574acd 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -3,21 +3,23 @@ ## Versioning GitLab follows the [Semantic Versioning](http://semver.org/) for its releases: -`(Major).(Minor).(Patch)` in a [pragmatic way]. - -- **Major version**: Whenever there is something significant or any backwards - incompatible changes are introduced to the public API. -- **Minor version**: When new, backwards compatible functionality is introduced - to the public API or a minor feature is introduced, or when a set of smaller - features is rolled out. -- **Patch number**: When backwards compatible bug fixes are introduced that fix - incorrect behavior. +`(Major).(Minor).(Patch)` in a [pragmatic way](https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e). For example, for GitLab version 10.5.7: -* `10` represents major version -* `5` represents minor version -* `7` represents patch number +- `10` represents the major version. The major release was 10.0.0, but often referred to as 10.0. +- `5` represents the minor version. The minor release was 10.5.0, but often referred to as 10.5. +- `7` represents the patch number. + +Any part of the version number can increment into multiple digits, for example, 13.10.11. + +The following table describes the version types and their release cadence: + +| Version type | Description | Cadence | +|:-------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Major | For significant changes, or when any backward-incompatible changes are introduced to the public API. | Yearly. The next major release is GitLab 12.0 on June 22, 2019. Subsequent major releases will be scheduled for May 22 each year, by default. | | +| Minor | For when new backward-compatible functionality is introduced to the public API, a minor feature is introduced, or when a set of smaller features is rolled out. | Monthly on the 22nd. | +| Patch | For backward-compatible bug fixes that fix incorrect behavior. See [Patch releases](#patch-releases). | As needed. | ## Patch releases @@ -55,20 +57,20 @@ cases you need to consider. It is considered safe to jump between patch versions and minor versions within one major version. For example, it is safe to: -* Upgrade the patch version: - * `8.9.0` -> `8.9.7` - * `8.9.0` -> `8.9.1` - * `8.9.2` -> `8.9.6` -* Upgrade the minor version: - * `8.9.4` -> `8.12.3` - * `9.2.3` -> `9.5.5` +- Upgrade the patch version: + - `8.9.0` -> `8.9.7` + - `8.9.0` -> `8.9.1` + - `8.9.2` -> `8.9.6` +- Upgrade the minor version: + - `8.9.4` -> `8.12.3` + - `9.2.3` -> `9.5.5` Upgrading the major version requires more attention. We cannot guarantee that upgrading between major versions will be seamless. As previously mentioned, major versions are reserved for backwards incompatible changes. We recommend that you first upgrade to the latest available minor version within your major version. By doing this, you can address any deprecation messages -that could possibly change behaviour in the next major release. +that could change behavior in the next major release. Please see the table below for some examples: @@ -79,9 +81,5 @@ Please see the table below for some examples: | 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 -[Responsible Disclosure Policy][disclosure]. - -[rel]: https://gitlab.com/gitlab-org/release-tools/blob/master/doc/ -[disclosure]: https://about.gitlab.com/disclosure/ -[pragmatic way]: https://gist.github.com/jashkenas/cbd2b088e20279ae2c8e +[release documentation](https://gitlab.com/gitlab-org/release/docs). You may also want to read our +[Responsible Disclosure Policy](https://about.gitlab.com/security/disclosure/). diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 2b9cce6539f..037b71a27b9 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 @@ -244,6 +311,11 @@ For installations from source: remote_directory: 'my.s3.bucket' # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional # encryption: 'AES256' + # Turns on AWS Server-Side Encryption with Amazon Customer-Provided Encryption Keys for backups, this is optional + # This should be set to the base64-encoded encryption key for Amazon S3 to use to encrypt or decrypt your data. + # 'encryption' must also be set in order for this to have any effect. + # To avoid storing the key on disk, the key can also be specified via the `GITLAB_BACKUP_ENCRYPTION_KEY` environment variable. + # encryption_key: '<base64 key>' # Specifies Amazon S3 storage class to use for backups, this is optional # storage_class: 'STANDARD' ``` @@ -306,7 +378,7 @@ with the name of your bucket: If you want to use Google Cloud Storage to save backups, you'll have to create an access key from the Google console first: -1. Go to the storage settings page https://console.cloud.google.com/storage/settings +1. Go to the storage settings page <https://console.cloud.google.com/storage/settings> 1. Select "Interoperability" and create an access key 1. Make note of the "Access Key" and "Secret" and replace them in the configurations below @@ -370,33 +442,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 +487,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 +548,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,6 +609,8 @@ 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: @@ -569,6 +662,7 @@ Restoring database tables: - Loading fixture wikis...[SKIPPING] Restoring repositories: - Restoring repository abcd... [DONE] +- Object pool 1 ... Deleting tmp directories...[DONE] ``` @@ -580,7 +674,7 @@ Restart GitLab: sudo service gitlab restart ``` -### Restore for Omnibus installations +### Restore for Omnibus GitLab installations This procedure assumes that: @@ -629,10 +723,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 @@ -643,19 +737,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 @@ -711,5 +800,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/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 5f3143f76cd..df3dab118b2 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -38,8 +38,6 @@ ## List the webhooks from projects in a given **NAMESPACE**: # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:list NAMESPACE=/ + sudo gitlab-rake gitlab:web_hook:list NAMESPACE=acme # source installations - bundle exec rake gitlab:web_hook:list NAMESPACE=/ RAILS_ENV=production - -> Note: `/` is the global namespace. + bundle exec rake gitlab:web_hook:list NAMESPACE=acme RAILS_ENV=production diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 94ba5d1375d..d61a205d954 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -17,8 +17,8 @@ GitLab supports both gzip and [SPDY][ngx-spdy] and mitigates the CRIME vulnerability by deactivating gzip when HTTPS is enabled. You can see the sources of the files in question: -* [Source installation NGINX file][source-nginx] -* [Omnibus installation NGINX file][omnibus-nginx] +- [Source installation NGINX file][source-nginx] +- [Omnibus installation NGINX file][omnibus-nginx] Although SPDY is enabled in Omnibus installations, CRIME relies on compression (the 'C') and the default compression level in NGINX's SPDY module is 0 @@ -52,9 +52,9 @@ vulnerability. ### References -* Nginx ["Module ngx_http_spdy_module"][ngx-spdy] -* Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"][nessus] -* Wikipedia contributors, ["CRIME"][wiki-crime] Wikipedia, The Free Encyclopedia +- Nginx ["Module ngx_http_spdy_module"][ngx-spdy] +- Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"][nessus] +- Wikipedia contributors, ["CRIME"][wiki-crime] Wikipedia, The Free Encyclopedia [source-nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/nginx/gitlab-ssl [omnibus-nginx]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/templates/default/nginx-gitlab-http.conf.erb diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 3efb19c1526..ad83dc05a93 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -10,8 +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 -`gitlab_rails['rack_attack_git_basic_auth'] = true`. +using this feature, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). By default, user sign-in, user sign-up (if enabled), and user password reset is limited to 6 requests per minute. After trying for 6 times, the client will @@ -35,13 +34,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 +54,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 +97,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 +128,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 cd290a80314..4b65b901487 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -6,15 +6,15 @@ password to login, they'll be prompted for a code generated by an application on their phone. You can read more about it here: -[Two-factor Authentication (2FA)](../profile/two_factor_authentication.md) +[Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md) ## Enforcing 2FA for all users Users on GitLab, can enable it without any admin's intervention. If you want to 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/webhooks.md b/doc/security/webhooks.md index b17b0a4bc4a..8c26bbac6a7 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -6,13 +6,13 @@ With [Webhooks](../user/project/integrations/webhooks.md), you and your project Things get hairy, however, when a Webhook is set up with a URL that doesn't point to an external, but to an internal service, that may do something completely unintended when the webhook is triggered and the POST request is sent. -Because Webhook requests are made by the GitLab server itself, these have complete access to everything running on the server (http://localhost:123) or within the server's local network (http://192.168.1.12:345), even if these services are otherwise protected and inaccessible from the outside world. +Because Webhook requests are made by the GitLab server itself, these have complete access to everything running on the server (`http://localhost:123`) or within the server's local network (`http://192.168.1.12:345`), even if these services are otherwise protected and inaccessible from the outside world. -If a web service does not require authentication, Webhooks can be used to trigger destructive commands by getting the GitLab server to make POST requests to endpoints like "http://localhost:123/some-resource/delete". +If a web service does not require authentication, Webhooks can be used to trigger destructive commands by getting the GitLab server to make POST requests to endpoints like `http://localhost:123/some-resource/delete`. To prevent this type of exploitation from happening, starting with GitLab 10.6, all Webhook requests to the current GitLab instance server address and/or in a private network will be forbidden by default. That means that all requests made to 127.0.0.1, ::1 and 0.0.0.0, as well as IPv4 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and IPv6 site-local (ffc0::/10) addresses won't be allowed. -This behavior can be overridden by enabling the option *"Allow requests to the local network from hooks and services"* in the *"Outbound requests"* section inside the Admin area under **Settings** (`/admin/application_settings`): +This behavior can be overridden by enabling the option *"Allow requests to the local network from hooks and services"* in the *"Outbound requests"* section inside the Admin area under **Settings** (`/admin/application_settings/network`):  diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 5db042326f3..09a97fcea07 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -8,163 +8,243 @@ 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). + +## ED25519 SSH keys -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. +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. -Note that Public SSH key may also be named as follows: +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. -- `id_dsa.pub` -- `id_ecdsa.pub` -- `id_ed25519.pub` +## 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:** - - ```bash - cat ~/.ssh/id_rsa.pub | clip - ``` + You can also open the key in a graphical editor and copy it from there, + but be careful not to accidentally change anything. -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 -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. +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): + +```bash +ssh -T git@gitlab.com +``` + +The first time you connect to GitLab via SSH, you will be asked to verify the +authenticity of the GitLab host you are connecting to. +For example, when connecting to GitLab.com, answer `yes` to add GitLab.com to +the list of trusted hosts: + +``` +The authenticity of host 'gitlab.com (35.231.145.151)' can't be established. +ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw. +Are you sure you want to continue connecting (yes/no)? yes +Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts. +``` + +NOTE: **Note:** +For GitLab.com, consult the +[SSH host keys fingerprints](../user/gitlab_com/index.md#ssh-host-keys-fingerprints), +to make sure you're connecting to the correct server. + +Once added to the list of known hosts, you won't be asked to validate the +authenticity of GitLab's host again. Run the above command once more, and +you should only 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 @@ -238,9 +318,7 @@ not implicitly give any access just by setting them up. ### Eclipse -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 +How to add your SSH key to Eclipse: <https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration> ## SSH on the GitLab server diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index cce02d218c2..6d63906ea4d 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -272,7 +272,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-ce/issues/39675>. **Group removed:** @@ -289,7 +289,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-ce/issues/39675>. **Group renamed:** @@ -309,7 +309,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-ce/issues/39675>. **New Group Member:** diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 9546f43eea8..a354d3e7884 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -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://github.com/kanboard/plugin-gitlab-auth) -- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) -- [Set up Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) +- [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) +- [OKD - Configuring Authentication and User Agent](https://docs.okd.io/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index c60d25eda1b..325de50cab0 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -2,14 +2,15 @@ > [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 will be enabled by default for all -projects. If it's not explicitly enabled for the project, Auto DevOps will be automatically +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) @@ -17,33 +18,38 @@ 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 @@ -126,7 +132,8 @@ in three places: - either under the project's CI/CD settings while [enabling Auto DevOps](#enabling-auto-devops) - or in instance-wide settings in the **admin area > Settings** under the "Continuous Integration and Delivery" section -- or at the project or group level as a variable: `AUTO_DEVOPS_DOMAIN` (required if you want to use [multiple clusters](#using-multiple-kubernetes-clusters)) +- or at the project as a variable: `AUTO_DEVOPS_DOMAIN` (required if you want to use [multiple clusters](#using-multiple-kubernetes-clusters)) +- or at the group level as a variable: `AUTO_DEVOPS_DOMAIN` A wildcard DNS A record matching the base domain(s) is required, for example, given a base domain of `example.com`, you'd need a DNS entry like: @@ -186,7 +193,7 @@ To add a different cluster for each environment: and Ingress. 1. Make sure you have [configured your DNS](#auto-devops-base-domain) with the specified Auto DevOps domains. -1. Navigate to your project's **Settings > CI/CD > Variables** and add +1. Navigate to your project's **Settings > CI/CD > Environment variables** and add the `AUTO_DEVOPS_DOMAIN` variables with their respective environment scope. @@ -197,23 +204,44 @@ 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 +NOTE: **Note:** +Auto DevOps is not supported for a group with multiple clusters, as it +is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group +level. This will be resolved in the future with the [following issue]( +https://gitlab.com/gitlab-org/gitlab-ce/issues/52363). + +## 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. -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 +### Enabling/disabling Auto DevOps at the instance-level (Administrators only) -Once saved, an Auto DevOps pipeline will be triggered on the default branch. +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. 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. + +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 @@ -222,12 +250,6 @@ 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/disable Auto DevOps instance-wide](../../user/admin_area/settings/continuous_integration.md#auto-devops), -and all projects that haven't explicitly set an option will have Auto DevOps -enabled/disabled 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)`. @@ -262,21 +284,44 @@ to understand how each one works. ### Auto Build -Auto Build creates a build of the application in one of two ways: - -- If there is a `Dockerfile`, it will use `docker build` to create a Docker image. -- Otherwise, it will use [Herokuish](https://github.com/gliderlabs/herokuish) - and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) - to automatically detect and build the application into a Docker image. +Auto Build creates a build of the application using an existing `Dockerfile` or +Heroku buildpacks. Either way, the resulting Docker image is automatically pushed to the [Container Registry][container-registry] and tagged with the commit SHA. -CAUTION: **Important:** +#### Auto Build using a Dockerfile + +If a project's repository contains a `Dockerfile`, Auto Build will use +`docker build` to create a Docker image. + If you are also using Auto Review Apps and Auto Deploy and choose to provide your own `Dockerfile`, make sure you expose your application to port `5000` as this is the port assumed by the default Helm chart. +#### Auto Build using Heroku buildpacks + +Auto Build builds an application using a project's `Dockerfile` if present, or +otherwise it will use [Herokuish](https://github.com/gliderlabs/herokuish) +and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) +to automatically detect and build the application into a Docker image. + +Each buildpack requires certain files to be in your project's repository for +Auto Build to successfully build your application. For example, the following +files are required at the root of your application's repository, depending on +the language: + +- A `Pipfile` or `requirements.txt` file for Python projects. +- A `Gemfile` or `Gemfile.lock` file for Ruby projects. + +For the requirements of other languages and frameworks, read the +[buildpacks docs](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). + +TIP: **Tip:** +If Auto Build fails despite the project meeting the buildpack requirements, set +a project variable `TRACE=true` to enable verbose logging, which may help to +troubleshoot. + ### Auto Test Auto Test automatically runs the appropriate tests for your application using @@ -299,8 +344,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]** @@ -313,9 +357,15 @@ 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. + +NOTE: **Note:** +The Auto SAST job requires GitLab Runner 11.5 or above. + ### Auto Dependency Scanning **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 10.7. @@ -329,6 +379,12 @@ 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. + +NOTE: **Note:** +The Auto Dependency Scanning job requires GitLab Runner 11.5 or above. + ### Auto License Management **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 11.0. @@ -342,6 +398,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. @@ -352,9 +411,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:** @@ -374,6 +436,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 @@ -391,9 +456,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. @@ -406,8 +474,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 @@ -447,14 +515,23 @@ 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. Note that this means that if any deploy succeeds, +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 @@ -462,9 +539,9 @@ a helm pre-upgrade hook. For example, in a Rails application: -* `DB_INITIALIZE` can be set to `cd /app && RAILS_ENV=production +- `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` +- `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 @@ -519,7 +596,7 @@ To view the metrics, open the While Auto DevOps provides great defaults to get you started, you can customize almost everything to fit your needs; from custom [buildpacks](#custom-buildpacks), to [`Dockerfile`s](#custom-dockerfile), [Helm charts](#custom-helm-chart), or -even copying the complete [CI/CD configuration](#customizing-gitlab-ci-yml) +even copying the complete [CI/CD configuration](#customizing-gitlab-ciyml) into your project to enable staging and canary deployments, and more. ### Custom buildpacks @@ -554,8 +631,13 @@ 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) - `AUTO_DEVOPS_CHART` with the URL of a custom chart to use. +- **Project variable** - Create a [project variable](../../ci/variables/README.md#variables) + `AUTO_DEVOPS_CHART` with the URL of a custom chart to use or create two project variables `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository and `AUTO_DEVOPS_CHART` with the path to the chart. + +### Custom Helm chart per environment **[PREMIUM]** + +You can specify the use of a custom Helm chart per environment by scoping the environment variable +to the desired environment. See [Limiting environment scopes of variables](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-variables-premium). ### Customizing `.gitlab-ci.yml` @@ -601,14 +683,17 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | ------------ | --------------- | | `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain); by default set automatically by the [Auto DevOps setting](#enabling-auto-devops). | | `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/auto-deploy-app). | +| `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | | `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1. | | `CANARY_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html); defaults to 1 | | `CANARY_PRODUCTION_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) in the production environment. This takes precedence over `CANARY_REPLICAS`; defaults to 1 | +| `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. | +| `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. | | `POSTGRES_ENABLED` | Whether PostgreSQL is enabled; defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL. | | `POSTGRES_USER` | The PostgreSQL user; defaults to `user`. Set it to use a custom username. | | `POSTGRES_PASSWORD` | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password. | -| `POSTGRES_DB` | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name. | +| `POSTGRES_DB` | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-environment-variables). Set it to use a custom database name. | | `BUILDPACK_URL` | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` | | `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).| @@ -625,10 +710,11 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `REVIEW_DISABLED` | From GitLab 11.0, this variable can be used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs will not be created. | | `DAST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `dast` job. If the variable is present, the job will not be created. | | `PERFORMANCE_DISABLED` | From GitLab 11.0, this variable can be used to disable the `performance` job. If the variable is present, the job will not be created. | +| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | 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:** @@ -636,6 +722,63 @@ You should *not* scale your application using Kubernetes directly. This can cause confusion with Helm not detecting the change, and subsequent deploys with Auto DevOps can undo your changes. +#### Application secret variables + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/49056) in GitLab 11.7. + +Some applications need to define secret variables that are +accessible by the deployed application. Auto DevOps detects variables where the key starts with +`K8S_SECRET_` and make these prefixed variables available to the +deployed application, as environment variables. + +To configure your application variables: + +1. Go to your project's **Settings > CI/CD**, then expand the section + called **Variables**. + +2. Create a CI Variable, ensuring the key is prefixed with + `K8S_SECRET_`. For example, you can create a variable with key +`K8S_SECRET_RAILS_MASTER_KEY`. + +3. Run an Auto Devops pipeline either by manually creating a new + pipeline or by pushing a code change to GitLab. + +Auto DevOps pipelines will take your application secret variables to +populate a Kubernetes secret. This secret is unique per environment. +When deploying your application, the secret is loaded as environment +variables in the container running the application. Following the +example above, you can see the secret below containing the +`RAILS_MASTER_KEY` variable. + +```sh +$ kubectl get secret production-secret -n minimal-ruby-app-54 -o yaml +apiVersion: v1 +data: + RAILS_MASTER_KEY: MTIzNC10ZXN0 +kind: Secret +metadata: + creationTimestamp: 2018-12-20T01:48:26Z + name: production-secret + namespace: minimal-ruby-app-54 + resourceVersion: "429422" + selfLink: /api/v1/namespaces/minimal-ruby-app-54/secrets/production-secret + uid: 57ac2bfd-03f9-11e9-b812-42010a9400e4 +type: Opaque +``` + +CAUTION: **Caution:** +Variables with multiline values are not currently supported due to +limitations with the current Auto DevOps scripting environment. + +NOTE: **Note:** +Environment variables are generally considered immutable in a Kubernetes +pod. Therefore, if you update an application secret without changing any +code then manually create a new pipeline, you will find that any running +application pods will not have the updated secrets. In this case, you +can either push a code update to GitLab to force the Kubernetes +Deployment to recreate pods or manually delete running pods to +cause Kubernetes to create new pods with updated secrets. + #### Advanced replica variables setup Apart from the two replica-related variables for production mentioned above, @@ -706,7 +849,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. @@ -719,7 +862,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 diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index b12e86cb0a9..9749bd63f2b 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -84,6 +84,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). @@ -213,7 +216,7 @@ deployment and clicking a square will take you to the pod's logs page. TIP: **Tip:** There is only one pod hosting the application at the moment, but you can add more pods by defining the [`REPLICAS` variable](index.md#environment-variables) -under **Settings > CI/CD > Variables**. +under **Settings > CI/CD > Environment variables**. ### Working with branches 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 5edf92b3b09..3e7d02770e4 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -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 6ff27e495fb..404a686f1cf 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -241,7 +241,7 @@ Our free SaaS for public and private repositories. ### GitLab Geo -Allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational version. It [can be used](https://docs.gitlab.com/ee/gitlab-geo/README.html) for cloning and fetching projects, in addition to reading any data. This will make working with large repositories over large distances much faster. +Allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational version. It [can be used](https://docs.gitlab.com/ee/administration/geo/replication/index.html) for cloning and fetching projects, in addition to reading any data. This will make working with large repositories over large distances much faster. ### GitLab High Availability @@ -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 @@ -407,7 +407,7 @@ A free disaster recovery [software](https://help.ubuntu.com/community/MondoMindi #### Mount -External reference: +External reference: As stated on the [wikipedia page](https://en.wikipedia.org/wiki/Mount_(Unix)), "Mounting makes file systems, files, directories, devices and special files available for use and available to the user." @@ -423,7 +423,7 @@ A set of symbols that are used to organize objects of various kinds so that thes ### Nginx -A web [server](https://www.nginx.com/resources/wiki/) (pronounced "engine x"). [It can act]((https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/nginx.md) as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache. +A web [server](https://www.nginx.com/resources/wiki/) (pronounced "engine x"). [It can act](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/nginx.md) as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache. ### OAuth @@ -447,7 +447,7 @@ Software for which the original source code is freely [available](https://openso #### Open Source Stewardship -[Related blog post](https://about.gitlab.com/2016/01/11/being-a-good-open-source-steward/). +[Related blog post](https://about.gitlab.com/2016/01/11/being-a-good-open-source-steward/). ### Owner @@ -557,7 +557,7 @@ Software that is hosted centrally and accessed on-demand (i.e. whenever you want This term is often used by people when they mean "Version Control." -### Scrum +### Scrum An Agile [framework](https://www.scrum.org/Resources/What-is-Scrum) designed to typically help complete complex software projects. It's made up of several parts: product requirements backlog, sprint planning, sprint (development), sprint review, and retrospec (analyzing the sprint). The goal is to end up with potentially shippable products. @@ -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 @@ -697,7 +697,7 @@ A [website/system](http://www.wiki.com/) that allows for collaborative editing o ### Working area -Files that have been modified but are not committed. Check them by using the command "git status". +Files that have been modified but are not committed. Check them by using the command "git status". ### Working Tree diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 0a7ce922de1..77a1892b656 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. @@ -66,10 +66,10 @@ RDS instances as well. The subnets are listed with their name, AZ and CIDR block: -* gitlab-public-10.0.0.0 - us-west-2a - 10.0.0.0 -* gitlab-private-10.0.1.0 - us-west-2a - 10.0.1.0 -* gitlab-public-10.0.2.0 - us-west-2b - 10.0.2.0 -* gitlab-private-10.0.3.0 - us-west-2b - 10.0.3.0 +- gitlab-public-10.0.0.0 - us-west-2a - 10.0.0.0 +- gitlab-private-10.0.1.0 - us-west-2a - 10.0.1.0 +- gitlab-public-10.0.2.0 - us-west-2b - 10.0.2.0 +- gitlab-private-10.0.3.0 - us-west-2b - 10.0.3.0 ### Route Table @@ -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,8 +160,8 @@ 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 -subnet and security group and +Multi-AZ and node types. The second section will allow us to choose our +subnet and security group and  @@ -206,7 +206,7 @@ http traffic from anywhere and name it something such as `gitlab-ec2-security-group`. While we wait for it to launch we can allocate an Elastic IP and -associate it with our new EC2 instance. +associate it with our new EC2 instance. ### RDS and Redis Security Group @@ -268,13 +268,13 @@ our current case we'll specify the adapter, encoding, host, db name, username, and password. gitlab_rails['db_adapter'] = "postgresql" - gitlab_rails['db_encoding'] = "unicode" - gitlab_rails['db_database'] = "gitlabhq_production" + 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 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,12 +285,12 @@ 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 +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 - sudo gitlab-ctl status + sudo gitlab-ctl reconfigure + sudo gitlab-rake gitlab:check + sudo gitlab-ctl status If everything looks good copy the Elastic IP over to your browser and test the instance manually. @@ -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,12 +388,12 @@ 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. -* [GitLab High Availability](http://docs.gitlab.com/ce/administration/high_availability/README.html#sts=High%20Availability) -* [GitLab Geo](http://docs.gitlab.com/ee/gitlab-geo/README.html) +- [GitLab High Availability](http://docs.gitlab.com/ce/administration/high_availability/README.html#sts=High%20Availability) +- [GitLab Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) diff --git a/doc/university/high-availability/aws/img/reference-arch2.png b/doc/university/high-availability/aws/img/reference-arch2.png Binary files differindex 9f50b2f5171..a9cb6663103 100644 --- a/doc/university/high-availability/aws/img/reference-arch2.png +++ b/doc/university/high-availability/aws/img/reference-arch2.png diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md index e5eb5d97e3b..53578a34d1c 100644 --- a/doc/university/training/end-user/README.md +++ b/doc/university/training/end-user/README.md @@ -50,7 +50,7 @@ project. - Use the tools at your disposal when you get stuck. - Use `git help <command>` command - Use Google (i.e. StackOverflow, Google groups) - - Read documentation at https://git-scm.com + - Read documentation at <https://git-scm.com> --- @@ -62,7 +62,7 @@ Workshop Time! ### Setup - 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. - Linux @@ -78,7 +78,7 @@ 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 set up a different author for each project @@ -107,14 +107,14 @@ cd ~/development -or- mkdir ~/workspace -cd ~/workspace +cd ~/workspace ``` --- ## Git Basics ---- +--- ### Git Workflow @@ -136,13 +136,13 @@ cd ~/workspace issue tracking, Merge Requests, and other features. - The hosted version of GitLab is gitlab.com ---- +--- ### New Project - Sign in into your gitlab.com account - Create a project -- Choose to import from 'Any Repo by URL' and use https://gitlab.com/gitlab-org/training-examples.git +- Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git> - On your machine clone the `training-examples` 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 --- @@ -242,24 +242,26 @@ git push origin squash_some_bugs --- ### Merge Conflicts -* Happen often -* Learning to fix conflicts is hard -* Practice makes perfect -* Force push after fixing conflicts. Be careful! + +- Happen often +- Learning to fix conflicts is hard +- Practice makes perfect +- Force push after fixing conflicts. Be careful! --- ### 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 --- @@ -305,10 +307,10 @@ Create a merge request on the GitLab web UI. You'll see a conflict warning. ### Notes -* When to use `git merge` and when to use `git rebase` -* Rebase when updating your branch with master -* Merge when bringing changes from feature to master -* Reference: https://www.atlassian.com/git/tutorials/merging-vs-rebasing/ +- When to use `git merge` and when to use `git rebase` +- Rebase when updating your branch with master +- Merge when bringing changes from feature to master +- Reference: <https://www.atlassian.com/git/tutorials/merging-vs-rebasing/> --- @@ -362,15 +364,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 +391,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/env_setup.md b/doc/university/training/topics/env_setup.md index bdf805711e0..78ca30e0f55 100644 --- a/doc/university/training/topics/env_setup.md +++ b/doc/university/training/topics/env_setup.md @@ -8,7 +8,7 @@ comments: false ## Install - **Windows** - - Install 'Git for Windows' from https://git-for-windows.github.io + - Install 'Git for Windows' from <https://git-for-windows.github.io> - **Mac** - Type '`git`' in the Terminal application. diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md index 1441e4b89b2..d76ff57bfa3 100644 --- a/doc/university/training/topics/getting_started.md +++ b/doc/university/training/topics/getting_started.md @@ -8,12 +8,12 @@ comments: false ## Instantiating Repositories -* Create a new repository by instantiating it through +- Create a new repository by instantiating it through: ```bash git init ``` -* Copy an existing project by cloning the repository through +- Copy an existing project by cloning the repository through: ```bash git clone <url> @@ -23,9 +23,9 @@ comments: false ## Central Repos -* To instantiate a central repository a `--bare` flag is required. -* Bare repositories don't allow file editing or committing changes. -* Create a bare repo with +- To instantiate a central repository a `--bare` flag is required. +- Bare repositories don't allow file editing or committing changes. +- Create a bare repo with: ```bash git init --bare project-name.git @@ -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. ---------- @@ -98,5 +97,5 @@ git log ## Note -* git fetch vs pull -* Pull is git fetch + git merge +- git fetch vs pull +- Pull is git fetch + git merge diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md index b1483e725fe..e02a7deab91 100644 --- a/doc/university/training/topics/git_add.md +++ b/doc/university/training/topics/git_add.md @@ -10,13 +10,13 @@ comments: false Adds content to the index or staging area. -* Adds a list of file +- Adds a list of file: ```bash git add <files> ``` -* Adds all files including deleted ones +- Adds all files including deleted ones: ```bash git add -A @@ -26,19 +26,19 @@ Adds content to the index or staging area. ## Git add continued -* Add all text files in current dir +- Add all text files in current dir: ```bash git add *.txt ``` -* Add all text file in the project +- Add all text file in the project: ```bash git add "*.txt*" ``` -* Adds all files in directory +- Adds all files in directory: ```bash git add views/layouts/ diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md index 7e502d6dad4..127323c292c 100644 --- a/doc/university/training/topics/git_intro.md +++ b/doc/university/training/topics/git_intro.md @@ -8,7 +8,7 @@ comments: false ## Intro -https://git-scm.com/about +<https://git-scm.com/about> - Distributed version control - Does not rely on connection to a central server @@ -25,4 +25,4 @@ Use the tools at your disposal when you get stuck. - Use '`git help <command>`' command - Use Google -- Read documentation at https://git-scm.com +- Read documentation at <https://git-scm.com> diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index 3e39ea5cc9a..127fdf4d44a 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.md @@ -8,19 +8,19 @@ comments: false Git log lists commit history. It allows searching and filtering. -* Initiate log +- Initiate log: ``` git log ``` -* Retrieve set number of records: +- Retrieve set number of records: ``` git log -n 2 ``` -* Search commits by author. Allows user name or a regular expression. +- Search commits by author. Allows user name or a regular expression. ``` git log --author="user_name" @@ -28,13 +28,13 @@ Git log lists commit history. It allows searching and filtering. ---------- -* Search by comment message. +- Search by comment message: ``` git log --grep="<pattern>" ``` -* Search by date +- Search by date: ``` git log --since=1.month.ago --until=3.weeks.ago @@ -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..a7d42904229 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. ---------- @@ -68,7 +68,8 @@ git push origin conflicts_branch -f ---------- ## Note -* When to use 'git merge' and when to use 'git rebase' -* Rebase when updating your branch with master -* Merge when bringing changes from feature to master -* Reference: https://www.atlassian.com/git/tutorials/merging-vs-rebasing/ + +- When to use 'git merge' and when to use 'git rebase' +- Rebase when updating your branch with master +- Merge when bringing changes from feature to master +- Reference: <https://www.atlassian.com/git/tutorials/merging-vs-rebasing/> diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index 11cb557651f..ca3a64e4347 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.md @@ -8,13 +8,13 @@ comments: false ## Undo Commits -* Undo last commit putting everything back into the staging area. +- Undo last commit putting everything back into the staging area: ``` git reset --soft HEAD^ ``` -* Add files and change message with: +- Add files and change message with: ``` git commit --amend -m "New Message" @@ -22,13 +22,13 @@ comments: false ---------- -* Undo last and remove changes +- Undo last and remove changes: ``` git reset --hard HEAD^ ``` -* Same as last one but for two commits back +- Same as last one but for two commits back: ``` git reset --hard HEAD^^ @@ -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 ---------- @@ -73,9 +73,9 @@ git push origin master ## 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/stash.md b/doc/university/training/topics/stash.md index 315ced1a196..f1c91fb1b37 100644 --- a/doc/university/training/topics/stash.md +++ b/doc/university/training/topics/stash.md @@ -9,7 +9,7 @@ comments: false We use git stash to store our changes when they are not ready to be committed and we need to change to a different branch. -* Stash +- Stash: ``` git stash save @@ -19,7 +19,7 @@ and we need to change to a different branch. git stash save "this is a message to display on the list" ``` -* Apply stash to keep working on it +- Apply stash to keep working on it: ``` git stash apply @@ -29,7 +29,7 @@ and we need to change to a different branch. ---------- -* Every time we save a stash it gets stacked so by using list we can see all our +- Every time we save a stash it gets stacked so by using list we can see all our stashes. ``` @@ -38,7 +38,7 @@ stashes. git stash list --stat ``` -* To clean our stack we need to manually remove them. +- To clean our stack we need to manually remove them: ``` # drop top stash @@ -51,27 +51,26 @@ stashes. ---------- -* Apply and drop on one command +- Apply and drop on one command: ``` git stash pop ``` -* If we meet conflicts we need to either reset or commit our changes. - -* Conflicts through `pop` will not drop a stash afterwards. +- If we meet conflicts we need to either reset or commit our changes. +- Conflicts through `pop` will not drop a stash afterwards. ---------- ## 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/subtree.md b/doc/university/training/topics/subtree.md index b5a892dc17b..ba7c3394938 100644 --- a/doc/university/training/topics/subtree.md +++ b/doc/university/training/topics/subtree.md @@ -4,20 +4,20 @@ comments: false # Subtree -* Used when there are nested repositories. -* Not recommended when the amount of dependencies is too large -* For these cases we need a dependency control system -* Command are painfully long so aliases are necessary +- Used when there are nested repositories. +- Not recommended when the amount of dependencies is too large. +- For these cases we need a dependency control system. +- Command are painfully long so aliases are necessary. ---------- ## Subtree Aliases -* Add: git subtree add --prefix <target-folder> <url> <branch> --squash -* Pull: git subtree add --prefix <target-folder> <url> <branch> --squash -* Push: git subtree add --prefix <target-folder> <url> <branch> -* Ex: git config alias.sbp 'subtree pull --prefix st / - git@gitlab.com:balameb/subtree-nested-example.git master --squash' +- Add: git subtree add --prefix <target-folder> <url> <branch> --squash. +- Pull: git subtree add --prefix <target-folder> <url> <branch> --squash. +- Push: git subtree add --prefix <target-folder> <url> <branch>. +- Ex: git config alias.sbp 'subtree pull --prefix st / + git@gitlab.com:balameb/subtree-nested-example.git master --squash'. ---------- 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/topics/unstage.md b/doc/university/training/topics/unstage.md index ee7913637b9..da36a3218e5 100644 --- a/doc/university/training/topics/unstage.md +++ b/doc/university/training/topics/unstage.md @@ -8,13 +8,13 @@ comments: false ## Unstage -* To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch. +- To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch. ```bash git reset HEAD <file> ``` -* This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use: +- This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use: ```bash git checkout -- <file> @@ -22,14 +22,14 @@ comments: false ---------- -* To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag. +- To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag: ``` git rm '*.txt' git rm -r <dirname> ``` -* If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`. +- If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`: ``` git rm <filename> --cache 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/10.0-to-10.1.md b/doc/update/10.0-to-10.1.md index af815d26a74..d4373ca3f23 100644 --- a/doc/update/10.0-to-10.1.md +++ b/doc/update/10.0-to-10.1.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.1-to-10.2.md b/doc/update/10.1-to-10.2.md index 632e8befa74..0705b58ed7a 100644 --- a/doc/update/10.1-to-10.2.md +++ b/doc/update/10.1-to-10.2.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.2-to-10.3.md b/doc/update/10.2-to-10.3.md index f8fe4a4b6bf..33a52d3e807 100644 --- a/doc/update/10.2-to-10.3.md +++ b/doc/update/10.2-to-10.3.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.3-to-10.4.md b/doc/update/10.3-to-10.4.md index 083f6090a8a..3ba96535965 100644 --- a/doc/update/10.3-to-10.4.md +++ b/doc/update/10.3-to-10.4.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.4-to-10.5.md b/doc/update/10.4-to-10.5.md index 313419ed13d..f00bbcaeaa6 100644 --- a/doc/update/10.4-to-10.5.md +++ b/doc/update/10.4-to-10.5.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.5-to-10.6.md b/doc/update/10.5-to-10.6.md index 2f90fb62c4a..6c3f8b663cc 100644 --- a/doc/update/10.5-to-10.6.md +++ b/doc/update/10.5-to-10.6.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.6-to-10.7.md b/doc/update/10.6-to-10.7.md index b9c14395a3a..9bd354a5bcd 100644 --- a/doc/update/10.6-to-10.7.md +++ b/doc/update/10.6-to-10.7.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.7-to-10.8.md b/doc/update/10.7-to-10.8.md index 7bb628f9740..9aafd3f269f 100644 --- a/doc/update/10.7-to-10.8.md +++ b/doc/update/10.7-to-10.8.md @@ -52,7 +52,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/10.8-to-11.0.md b/doc/update/10.8-to-11.0.md index 22a0c9f950c..f6fdc342e3d 100644 --- a/doc/update/10.8-to-11.0.md +++ b/doc/update/10.8-to-11.0.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/11.0-to-11.1.md b/doc/update/11.0-to-11.1.md index 3f10a7edb8a..25a7c1cf929 100644 --- a/doc/update/11.0-to-11.1.md +++ b/doc/update/11.0-to-11.1.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/11.1-to-11.2.md b/doc/update/11.1-to-11.2.md index 3edc7e6923e..ced59c245b8 100644 --- a/doc/update/11.1-to-11.2.md +++ b/doc/update/11.1-to-11.2.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/11.2-to-11.3.md b/doc/update/11.2-to-11.3.md index d77f879ee57..fa0c6872182 100644 --- a/doc/update/11.2-to-11.3.md +++ b/doc/update/11.2-to-11.3.md @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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 index b50e21f27dd..18bbfe4747e 100644 --- a/doc/update/11.3-to-11.4.md +++ b/doc/update/11.3-to-11.4.md @@ -39,9 +39,9 @@ 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.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.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 @@ -51,7 +51,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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-4-stable:config/gitlab.yml.example +git diff origin/11-3-stable:config/gitlab.yml.example origin/11-4-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-4-stable:lib/support/nginx/gitlab-ssl +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-1-stable:lib/support/nginx/gitlab origin/11-4-stable:lib/support/nginx/gitlab +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 @@ -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-4-stable:lib/support/init.d/gitlab.default.example +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: 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..8f588f8b2ae --- /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-document --version '< 2' +``` + +### 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/11.5-to-11.6.md b/doc/update/11.5-to-11.6.md new file mode 100644 index 00000000000..f95ce54650e --- /dev/null +++ b/doc/update/11.5-to-11.6.md @@ -0,0 +1,390 @@ +--- +comments: false +--- + +# From 11.5 to 11.6 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-6-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.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 +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-document --version '< 2' +``` + +### 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-6-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-6-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 + +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-6-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-5-stable:config/gitlab.yml.example origin/11-6-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-5-stable:lib/support/nginx/gitlab-ssl origin/11-6-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-5-stable:lib/support/nginx/gitlab origin/11-6-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-6-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-6-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-5-stable:lib/support/init.d/gitlab.default.example origin/11-6-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 + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --deployment --without development test mysql aws kerberos + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --deployment --without development test postgres aws kerberos + +# 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.5) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.4 to 11.5](11.4-to-11.5.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-6-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/11.6-to-11.7.md b/doc/update/11.6-to-11.7.md new file mode 100644 index 00000000000..b4d830e8ce0 --- /dev/null +++ b/doc/update/11.6-to-11.7.md @@ -0,0 +1,390 @@ +--- +comments: false +--- + +# From 11.6 to 11.7 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-7-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: Beginning in GitLab 11.0, we only support Ruby 2.4 or higher, and dropped +support for Ruby 2.3. Be sure to upgrade 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.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 +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-document --version '< 2' +``` + +### 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.10.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-7-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-7-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 + +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-7-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-6-stable:config/gitlab.yml.example origin/11-7-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-6-stable:lib/support/nginx/gitlab-ssl origin/11-7-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-6-stable:lib/support/nginx/gitlab origin/11-7-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-7-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-7-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-6-stable:lib/support/init.d/gitlab.default.example origin/11-7-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 + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --deployment --without development test mysql aws kerberos + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --deployment --without development test postgres aws kerberos + +# 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.6) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.5 to 11.6](11.5-to-11.6.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-7-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/11.7-to-11.8.md b/doc/update/11.7-to-11.8.md new file mode 100644 index 00000000000..d5cd557d7b5 --- /dev/null +++ b/doc/update/11.7-to-11.8.md @@ -0,0 +1,394 @@ +--- +comments: false +--- + +# From 11.7 to 11.8 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-8-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: Beginning in GitLab 11.0, we only support Ruby 2.4 or higher, and dropped +support for Ruby 2.3. Be sure to upgrade 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.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 +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-document --version '< 2' +``` + +### 4. Update Node + +NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped +support for node 6. Be sure to upgrade if necessary. + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v8.10.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v8.10.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.10.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-8-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-8-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### 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 + +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-8-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-7-stable:config/gitlab.yml.example origin/11-8-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/11-7-stable:lib/support/nginx/gitlab-ssl origin/11-8-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-7-stable:lib/support/nginx/gitlab origin/11-8-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/11-7-stable:lib/support/init.d/gitlab.default.example origin/11-8-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --deployment --without development test mysql aws kerberos + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --deployment --without development test postgres aws kerberos + + +# 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.7) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.6 to 11.7](11.6-to-11.7.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/5.1-to-5.2.md b/doc/update/5.1-to-5.2.md index 4faf5fa549e..bcc9058ff99 100644 --- a/doc/update/5.1-to-5.2.md +++ b/doc/update/5.1-to-5.2.md @@ -73,15 +73,15 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production ## 5. Update config files -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example> but with your settings. ## 6. Update Init script ```bash cd /home/git/gitlab sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab sudo chmod +x /etc/init.d/gitlab ``` diff --git a/doc/update/5.1-to-5.4.md b/doc/update/5.1-to-5.4.md index 212343bac3f..5767c9cc121 100644 --- a/doc/update/5.1-to-5.4.md +++ b/doc/update/5.1-to-5.4.md @@ -70,8 +70,8 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production ## 5. Update config files -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example> but with your settings. ## 6. Update Init script diff --git a/doc/update/5.1-to-6.0.md b/doc/update/5.1-to-6.0.md index 865d38e0ca4..4993d034b6e 100644 --- a/doc/update/5.1-to-6.0.md +++ b/doc/update/5.1-to-6.0.md @@ -185,8 +185,8 @@ sudo -u git -H git config --global core.autocrlf input Note: We switched from Puma in GitLab 5.x to unicorn in GitLab 6.0. -- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/unicorn.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/unicorn.rb.example> but with your settings. ## 7. Update Init script diff --git a/doc/update/5.2-to-5.3.md b/doc/update/5.2-to-5.3.md index ed4f3ebdd53..c378d2798f4 100644 --- a/doc/update/5.2-to-5.3.md +++ b/doc/update/5.2-to-5.3.md @@ -64,8 +64,8 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production ## 4. Update config files -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example> but with your settings. ## 5. Update Init script diff --git a/doc/update/5.3-to-5.4.md b/doc/update/5.3-to-5.4.md index 7277250eb32..77b1e9e5329 100644 --- a/doc/update/5.3-to-5.4.md +++ b/doc/update/5.3-to-5.4.md @@ -68,8 +68,8 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production ## 5. Update config files -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example> but with your settings. ## 6. Update Init script diff --git a/doc/update/5.4-to-6.0.md b/doc/update/5.4-to-6.0.md index dacdf05cc9c..2d2da769b89 100644 --- a/doc/update/5.4-to-6.0.md +++ b/doc/update/5.4-to-6.0.md @@ -118,8 +118,8 @@ sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production Note: We switched from Puma in GitLab 5.4 to unicorn in GitLab 6.0. -- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example> but with your settings. ## 7. Update Init script diff --git a/doc/update/6.0-to-6.1.md b/doc/update/6.0-to-6.1.md index a3c52a1cfb4..dd409175c27 100644 --- a/doc/update/6.0-to-6.1.md +++ b/doc/update/6.0-to-6.1.md @@ -85,8 +85,8 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ## 5. Update config files -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example> but with your settings. ## 6. Update Init script diff --git a/doc/update/6.1-to-6.2.md b/doc/update/6.1-to-6.2.md index 36a395bf01e..cace80c99b7 100644 --- a/doc/update/6.1-to-6.2.md +++ b/doc/update/6.1-to-6.2.md @@ -79,15 +79,15 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ## 6. Update config files -TIP: to see what changed in `gitlab.yml.example` in this release use next command: +TIP: to see what changed in `gitlab.yml.example` in this release use next command: ``` git diff 6-1-stable:config/gitlab.yml.example 6-2-stable:config/gitlab.yml.example ``` -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example> but with your settings. - Copy rack attack middleware config: diff --git a/doc/update/6.2-to-6.3.md b/doc/update/6.2-to-6.3.md index 02e87a08b8f..7205575942a 100644 --- a/doc/update/6.2-to-6.3.md +++ b/doc/update/6.2-to-6.3.md @@ -81,8 +81,8 @@ TIP: to see what changed in gitlab.yml.example in this release use next command: git diff 6-2-stable:config/gitlab.yml.example 6-3-stable:config/gitlab.yml.example ``` -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example but with your settings. +- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example> but with your settings. ```bash # Copy rack attack middleware config diff --git a/doc/update/6.9-to-7.0.md b/doc/update/6.9-to-7.0.md index 27063948028..e1ca34305b4 100644 --- a/doc/update/6.9-to-7.0.md +++ b/doc/update/6.9-to-7.0.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 3. Get latest code @@ -110,8 +110,8 @@ There are new configuration options available for gitlab.yml. View them with the git diff origin/6-9-stable:config/gitlab.yml.example origin/7-0-stable:config/gitlab.yml.example ``` -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl but with your setting +- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab> but with your settings. +- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl> but with your setting. ### 7. Start application 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..674163091be 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 @@ -67,7 +67,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ## 3. Get latest code @@ -178,16 +178,16 @@ TIP: to see what changed in `gitlab.yml.example` in this release use next comman git diff 6-0-stable:config/gitlab.yml.example 7-14-stable:config/gitlab.yml.example ``` -* Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/gitlab.yml.example but with your settings. -* Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/unicorn.rb.example but with your settings. -* Make `/home/git/gitlab-shell/config.yml` the same as https://gitlab.com/gitlab-org/gitlab-shell/blob/v2.6.5/config.yml.example but with your settings. -* Copy rack attack middleware config +- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/gitlab.yml.example> but with your settings. +- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/unicorn.rb.example> but with your settings. +- Make `/home/git/gitlab-shell/config.yml` the same as <https://gitlab.com/gitlab-org/gitlab-shell/blob/v2.6.5/config.yml.example> but with your settings. +- Copy rack attack middleware config. ```bash sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb ``` -* Set up logrotate +- Set up logrotate ```bash sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab @@ -195,9 +195,9 @@ sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab ### Change Nginx settings -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab-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. +- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab> but with your settings. +- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab-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. ### Check the version of /usr/local/bin/git diff --git a/doc/update/7.0-to-7.1.md b/doc/update/7.0-to-7.1.md index 308e8aeb985..8b69431dee1 100644 --- a/doc/update/7.0-to-7.1.md +++ b/doc/update/7.0-to-7.1.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 3. Get latest code diff --git a/doc/update/7.1-to-7.2.md b/doc/update/7.1-to-7.2.md index 07f92ac3af6..44e5fc676b3 100644 --- a/doc/update/7.1-to-7.2.md +++ b/doc/update/7.1-to-7.2.md @@ -94,8 +94,8 @@ There are new configuration options available for `gitlab.yml`. View them with t git diff 7-1-stable:config/gitlab.yml.example 7-2-stable:config/gitlab.yml.example ``` -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl but with your setting +- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab> but with your settings. +- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl> but with your setting. Update rack attack middleware config diff --git a/doc/update/7.2-to-7.3.md b/doc/update/7.2-to-7.3.md index a16f9de54e4..2625df2def8 100644 --- a/doc/update/7.2-to-7.3.md +++ b/doc/update/7.2-to-7.3.md @@ -108,8 +108,8 @@ git diff origin/7-2-stable:config/gitlab.yml.example origin/7-3-stable:config/gi sudo -u git -H sed -i 's/:backlog => 64/:backlog => 1024/' config/unicorn.rb ``` -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab-ssl but with your setting +- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab> but with your settings. +- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab-ssl> but with your setting. ### 7. Start application diff --git a/doc/update/7.3-to-7.4.md b/doc/update/7.3-to-7.4.md index 734c655f1d1..ad7930e8728 100644 --- a/doc/update/7.3-to-7.4.md +++ b/doc/update/7.3-to-7.4.md @@ -75,11 +75,11 @@ sudo -u git -H editor config/unicorn.rb #### Change Nginx HTTPS settings -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/lib/support/nginx/gitlab-ssl but with your setting +- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/lib/support/nginx/gitlab-ssl> but with your setting. #### MySQL Databases: Update database.yml config file -* Add `collation: utf8_general_ci` to `config/database.yml` as seen in [config/database.yml.mysql][mysql]: +- Add `collation: utf8_general_ci` to `config/database.yml` as seen in [config/database.yml.mysql][mysql]: ``` sudo -u git -H editor config/database.yml @@ -136,7 +136,7 @@ SET foreign_key_checks = 1; # Find MySQL users mysql> SELECT user FROM mysql.user WHERE user LIKE '%git%'; -# If git user exists and gitlab user does not exist +# If git user exists and gitlab user does not exist # you are done with the database cleanup tasks mysql> \q diff --git a/doc/update/7.4-to-7.5.md b/doc/update/7.4-to-7.5.md index 7a3a49ff948..d93d32d1b60 100644 --- a/doc/update/7.4-to-7.5.md +++ b/doc/update/7.4-to-7.5.md @@ -77,8 +77,8 @@ git diff origin/7-4-stable:config/gitlab.yml.example origin/7-5-stable:config/gi #### Change Nginx settings -* 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 +- 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. ### 6. Start application diff --git a/doc/update/7.5-to-7.6.md b/doc/update/7.5-to-7.6.md index 0d45a9528b9..0e87918c8c0 100644 --- a/doc/update/7.5-to-7.6.md +++ b/doc/update/7.5-to-7.6.md @@ -79,8 +79,8 @@ git diff origin/7-5-stable:config/gitlab.yml.example origin/7-6-stable:config/gi #### Change Nginx settings -* 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 +- 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. #### Set up time zone (optional) diff --git a/doc/update/7.6-to-7.7.md b/doc/update/7.6-to-7.7.md index 5e0b2ca7bcd..c24b5647f21 100644 --- a/doc/update/7.6-to-7.7.md +++ b/doc/update/7.6-to-7.7.md @@ -79,8 +79,8 @@ git diff origin/7-6-stable:config/gitlab.yml.example origin/7-7-stable:config/gi #### Change Nginx settings -* 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 +- 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. #### Set up time zone (optional) diff --git a/doc/update/7.7-to-7.8.md b/doc/update/7.7-to-7.8.md index f5b1ebf0a9c..61bd5fb1298 100644 --- a/doc/update/7.7-to-7.8.md +++ b/doc/update/7.7-to-7.8.md @@ -79,9 +79,9 @@ git diff origin/7-7-stable:config/gitlab.yml.example origin/7-8-stable:config/gi #### Change Nginx settings -* 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 settings. -* A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. +- 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 settings. +- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. #### Set up time zone (optional) diff --git a/doc/update/7.8-to-7.9.md b/doc/update/7.8-to-7.9.md index 0db7698936b..c13dd5b60e6 100644 --- a/doc/update/7.8-to-7.9.md +++ b/doc/update/7.8-to-7.9.md @@ -81,9 +81,9 @@ git diff origin/7-8-stable:config/gitlab.yml.example origin/7-9-stable:config/gi #### Change Nginx settings -* 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 settings. -* A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. +- 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 settings. +- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. #### Set up time zone (optional) diff --git a/doc/update/7.9-to-7.10.md b/doc/update/7.9-to-7.10.md index 782fb0736e6..4dece93652e 100644 --- a/doc/update/7.9-to-7.10.md +++ b/doc/update/7.9-to-7.10.md @@ -77,9 +77,9 @@ git diff origin/7-9-stable:config/gitlab.yml.example origin/7-10-stable:config/g #### Change Nginx settings -* 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 settings. -* A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. +- 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 settings. +- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. #### Set up time zone (optional) diff --git a/doc/update/8.10-to-8.11.md b/doc/update/8.10-to-8.11.md index df3e34f5cc6..f8415b5159b 100644 --- a/doc/update/8.10-to-8.11.md +++ b/doc/update/8.10-to-8.11.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.11-to-8.12.md b/doc/update/8.11-to-8.12.md index 9d6a1f42375..07ac8129b4f 100644 --- a/doc/update/8.11-to-8.12.md +++ b/doc/update/8.11-to-8.12.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md index 6225dee9802..bf622deaba8 100644 --- a/doc/update/8.12-to-8.13.md +++ b/doc/update/8.12-to-8.13.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.13-to-8.14.md b/doc/update/8.13-to-8.14.md index d2508e3f980..43b636ea958 100644 --- a/doc/update/8.13-to-8.14.md +++ b/doc/update/8.13-to-8.14.md @@ -47,7 +47,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.14-to-8.15.md b/doc/update/8.14-to-8.15.md index daf8d0f2ca6..eadf1743597 100644 --- a/doc/update/8.14-to-8.15.md +++ b/doc/update/8.14-to-8.15.md @@ -50,7 +50,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.15-to-8.16.md b/doc/update/8.15-to-8.16.md index 3668142edd2..4e8d54d5010 100644 --- a/doc/update/8.15-to-8.16.md +++ b/doc/update/8.15-to-8.16.md @@ -50,7 +50,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Get latest code diff --git a/doc/update/8.16-to-8.17.md b/doc/update/8.16-to-8.17.md index ee2e31c2aec..cab28a4d1c6 100644 --- a/doc/update/8.16-to-8.17.md +++ b/doc/update/8.16-to-8.17.md @@ -50,7 +50,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 74ce52859fa..55cf0842df4 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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..10214fd8aca 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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..79d92f05257 100644 --- a/doc/update/9.1-to-9.2.md +++ b/doc/update/9.1-to-9.2.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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..98443b8bfa6 100644 --- a/doc/update/9.2-to-9.3.md +++ b/doc/update/9.2-to-9.3.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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..640b9c3997e 100644 --- a/doc/update/9.3-to-9.4.md +++ b/doc/update/9.3-to-9.4.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node @@ -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/9.4-to-9.5.md b/doc/update/9.4-to-9.5.md index 6a655f77a55..e6cfa70975e 100644 --- a/doc/update/9.4-to-9.5.md +++ b/doc/update/9.4-to-9.5.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/9.5-to-10.0.md b/doc/update/9.5-to-10.0.md index 7790d192a82..8b565f67cb1 100644 --- a/doc/update/9.5-to-10.0.md +++ b/doc/update/9.5-to-10.0.md @@ -49,7 +49,7 @@ sudo make install Install Bundler: ```bash -sudo gem install bundler --no-ri --no-rdoc +sudo gem install bundler --no-document --version '< 2' ``` ### 4. Update Node diff --git a/doc/update/README.md b/doc/update/README.md index 7d3c4c310a4..d4fc0cc91bf 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -38,12 +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 +- You have to use [post-deployment migrations](../development/post_deployment_migrations.md) (included in - zero downtime update steps below) -3. You are using PostgreSQL. If you are using MySQL please look at the release + 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/update/upgrader.md b/doc/update/upgrader.md deleted file mode 100644 index 746d6bf93e7..00000000000 --- a/doc/update/upgrader.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -comments: false ---- - -# GitLab Upgrader (deprecated) - -*DEPRECATED* We recommend to [switch to the Omnibus package and repository server](https://about.gitlab.com/update/) instead of using this script. - -Although deprecated, if someone wants to make this script into a gem or otherwise improve it merge requests are welcome. - -*Make sure you view this [upgrade guide from the 'master' branch](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/upgrader.md) for the most up to date instructions.* - -GitLab Upgrader - a ruby script that allows you easily upgrade GitLab to latest minor version. - -For example it can update your application from 6.4 to latest GitLab 6 version (like 6.6.1). - -You still need to create a backup and manually restart GitLab after running the script but all other operations are done by this upgrade script. - -If you have local changes to your GitLab repository the script will stash them and you need to use `git stash pop` after running the script. - -**GitLab Upgrader is available only for GitLab version 6.4.2 or higher.** - -**This script does NOT update gitlab-shell, it needs manual update. See step 5 below.** - -## 0. Backup - - cd /home/git/gitlab - sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production - -## 1. Stop server - - sudo service gitlab stop - -## 2. Run GitLab upgrade tool - -Please replace X.X.X with the [latest GitLab release](https://packages.gitlab.com/gitlab/gitlab-ce). - -GitLab 7.9 adds `nodejs` as a dependency. GitLab 7.6 adds `libkrb5-dev` as a dependency (installed by default on Ubuntu and OSX). GitLab 7.2 adds `pkg-config` and `cmake` as dependency. Please check the dependencies in the [installation guide.](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) - - cd /home/git/gitlab - sudo -u git -H ruby -Ilib -e 'require "gitlab/upgrader"' -e 'class Gitlab::Upgrader' -e 'def latest_version_raw' -e '"vX.X.X"' -e 'end' -e 'end' -e 'Gitlab::Upgrader.new.execute' - - # to perform a non-interactive install (no user input required) you can add -y - # sudo -u git -H ruby -Ilib -e 'require "gitlab/upgrader"' -e 'class Gitlab::Upgrader' -e 'def latest_version_raw' -e '"vX.X.X"' -e 'end' -e 'end' -e 'Gitlab::Upgrader.new.execute' -- -y - -## 3. Start application - - sudo service gitlab start - sudo service nginx restart - -## 4. Check application status - -Check if GitLab and its dependencies are configured correctly: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## 5. Upgrade GitLab Shell - -GitLab Shell might be outdated, running the commands below ensures you're using a compatible version: - -``` -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -sudo -u git -H sh -c 'if [ -x bin/compile ] ; then bin/compile ; fi' -``` - -## One line upgrade command - -You've read through the entire guide and probably already did all the steps one by one. - -Below is a one line command with step 1 to 5 for the next time you upgrade. - -Please replace X.X.X with the [latest GitLab release](https://packages.gitlab.com/gitlab/gitlab-ce). - -```bash -cd /home/git/gitlab; \ - sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production; \ - sudo service gitlab stop; \ - sudo -u git -H ruby -Ilib -e 'require "gitlab/upgrader"' -e 'class Gitlab::Upgrader' -e 'def latest_version_raw' -e '"vX.X.X"' -e 'end' -e 'end' -e 'Gitlab::Upgrader.new.execute' -- -y; \ - cd /home/git/gitlab-shell; \ - sudo -u git -H git fetch; \ - sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION`; \ - sudo -u git -H sh -c 'if [ -x bin/compile ] ; then bin/compile ; fi'; \ - cd /home/git/gitlab; \ - sudo service gitlab start; \ - sudo service nginx restart; \ - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -```
\ No newline at end of file diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index f009906256e..d2e2cf439b5 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -57,7 +57,7 @@ server. ## Installing Slony Slony will be used to upgrade the database without requiring long downtimes. -Slony can be downloaded from http://www.slony.info/. If you have installed +Slony can be downloaded from <http://www.slony.info/>. If you have installed PostgreSQL using your operating system's package manager you may also be able to install Slony using said package manager. @@ -176,10 +176,10 @@ if ($ENV{"SLONYSET"}) { In this configuration file you should replace a few placeholders before you can use it. The following placeholders should be replaced: -* `OLD_HOST`: the address of the old database server. -* `NEW_HOST`: the address of the new database server. -* `SLONY_PASSWORD`: the password of the Slony user created earlier. -* `TABLES`: the tables to replicate. +- `OLD_HOST`: the address of the old database server. +- `NEW_HOST`: the address of the new database server. +- `SLONY_PASSWORD`: the password of the Slony user created earlier. +- `TABLES`: the tables to replicate. The list of tables to replicate can be generated by running the following command on your old PostgreSQL database: diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md new file mode 100644 index 00000000000..1f4f598b121 --- /dev/null +++ b/doc/user/abuse_reports.md @@ -0,0 +1,53 @@ +# Abuse reports + +Report abuse from users to GitLab administrators. + +You can report a user through their: + +- [Profile](#reporting-abuse-through-a-users-profile) +- [Comments](#reporting-abuse-through-a-users-comment) +- [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request) + +## Reporting abuse through a user's profile + +To report abuse from a user's profile page: + +1. Click on the exclamation point report abuse button at the top right of the user's profile. +1. Complete an abuse report. +1. Click the **Send report** button. + +## Reporting abuse through a user's comment + +To report abuse from a user's comment: + +1. Click on the vertical ellipsis (⋮) more actions button to open the dropdown. +1. Select **Report as abuse**. +1. Complete an abuse report. +1. Click the **Send report** button. + + +NOTE: **Note:** +A URL to the reported user's comment will be +pre-filled in the abuse report's **Message** field. + +## Reporting abuse through a user's issue or merge request + +The **Report abuse** button is displayed at the top right of the issue or merge request: + +- When **Report abuse** is selected from the menu that appears when the **Close issue** or **Close merge request** button is clicked, for users that have permission to close the issue or merge request. +- When viewing the issue or merge request, for users that don't have permission to close the issue or merge request. + +With the **Report abuse** button displayed, to submit an abuse report: + +1. Click the **Report abuse** button. +1. Submit an abuse report. +1. Click the **Send report** button. + +NOTE: **Note:** +A URL to the reported user's issue or merge request will be pre-filled +in the abuse report's **Message** field. + +## Managing abuse reports + +Admins are able to view and resolve abuse reports. +For more information, see [abuse reports administration documentation](admin_area/abuse_reports.md). diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md new file mode 100644 index 00000000000..01c2d9607f5 --- /dev/null +++ b/doc/user/admin_area/abuse_reports.md @@ -0,0 +1,31 @@ +# Abuse reports + +View and resolve abuse reports from GitLab users. + +Admins can view abuse reports in the admin area and are able to +resolve the reports by removing the reported user, blocking the reported user, or removing the report. + +## Reporting abuse + +To find out more about reporting abuse, see [abuse reports user documentation](../abuse_reports.md). + +## Resolving abuse reports + +To access abuse reports, go to **Admin area > Abuse Reports**. + +There are 3 ways to resolve an abuse report, with a button for each method: + +- Remove user & report: [Deletes the reported user](../profile/account/delete_account.md) from the instance and removes the abuse report from the list. +- Block user: Blocks the reported user from the instance and does not remove the abuse report from the list. +- Remove report: Removes the abuse report from the list and does not restrict the access for the reported user. + + + +## Blocked users + +Blocking a user will not remove the abuse report from the list. + +Instead, the block button will be disabled and explain that the user is "Already blocked". +You are still able to remove the user and/or report if necessary. + + diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md new file mode 100644 index 00000000000..51949088521 --- /dev/null +++ b/doc/user/admin_area/broadcast_messages.md @@ -0,0 +1,51 @@ +# Broadcast Messages + +GitLab can display messages to all users of a GitLab instance in a banner that appears in the UI. + + + +NOTE: **Note:** +If more than one banner message is active at one time, they are displayed in a stack in order of creation. + +## Adding a broadcast message + +To display messages to users on your GitLab instance, add broadcast message. + +To add a broadcast message: + +1. Navigate to the **Admin Area > Messages** page. +1. Add the text for the message to the **Message** field. Markdown and emoji are supported. +1. If required, click the **Customize colors** link to edit the background color and font color of the message. +1. Select a date for the message to start and end. +1. Click the **Add broadcast message** button. + +NOTE: **Note:** +Once a broadcast message has expired, it is no longer displayed in the UI but is still listed in the +list of broadcast messages. + +## Editing a broadcast message + +If changes are required to a broadcast message, they can be edited. + +To edit a broadcast message: + +1. Navigate to the **Admin Area > Messages** page. +1. From the list of broadcast messages, click the appropriate button to edit the message. +1. After making the required changes, click the **Update broadcast message** button. + +TIP: **Tip:** +Expired messages can be made active again by changing their end date. + +## Deleting a broadcast message + +Broadcast messages that are no longer required can be deleted. + +To delete a broadcast message: + +1. Navigate to the **Admin Area > Messages** page. +1. From the list of broadcast messages, click the appropriate button to delete the message. + +Once deleted, the broadcast message is removed from the list of broadcast messages. + +NOTE: **Note:** +Broadcast messages can be deleted while active. 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..e34ba045c54 --- /dev/null +++ b/doc/user/admin_area/custom_project_templates.md @@ -0,0 +1,26 @@ +# 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](../project/index.md), creating it based on custom project templates is +a convenient bootstrap option. + +GitLab administrators can configure a GitLab group that serves as template +source for an entire GitLab instance under **Admin area > Settings > Custom project templates**. + +NOTE: **Note:** +To set project templates at a group level, +see [Custom group-level project templates](../group/custom_project_templates.md). + +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 is a member of the project. + +NOTE: **Note:** +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). diff --git a/doc/user/admin_area/img/abuse_report_blocked_user.png b/doc/user/admin_area/img/abuse_report_blocked_user.png Binary files differnew file mode 100644 index 00000000000..0cb4c7bb8ac --- /dev/null +++ b/doc/user/admin_area/img/abuse_report_blocked_user.png diff --git a/doc/user/admin_area/img/abuse_reports_page.png b/doc/user/admin_area/img/abuse_reports_page.png Binary files differnew file mode 100644 index 00000000000..81dbe976cda --- /dev/null +++ b/doc/user/admin_area/img/abuse_reports_page.png diff --git a/doc/user/admin_area/img/admin_area_settings_button.png b/doc/user/admin_area/img/admin_area_settings_button.png Binary files differindex 315ef40a375..5b969ecd668 100644 --- a/doc/user/admin_area/img/admin_area_settings_button.png +++ b/doc/user/admin_area/img/admin_area_settings_button.png diff --git a/doc/user/admin_area/img/broadcast_messages.png b/doc/user/admin_area/img/broadcast_messages.png Binary files differnew file mode 100644 index 00000000000..926d38ae049 --- /dev/null +++ b/doc/user/admin_area/img/broadcast_messages.png 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..20829a27dd7 --- /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/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 35a9d7adb28..e165a120162 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -12,9 +12,9 @@ If enabled, version check will inform you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) for all signed in users, and on the admin pages. The statuses are: -* Green: You are running the latest version of GitLab. -* Orange: An updated version of GitLab is available. -* Red: The version of GitLab you are running is vulnerable. You should install +- Green: You are running the latest version of GitLab. +- Orange: An updated version of GitLab is available. +- Red: The version of GitLab you are running is vulnerable. You should install the latest version with security fixes as soon as possible.  @@ -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/award_emojis.md b/doc/user/award_emojis.md index 93be3da44d4..e4fd08a582c 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -1,24 +1,24 @@ # Award emoji -> **Notes:** -> - First [introduced][1825] in GitLab 8.2. -> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform +> - First [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825) in GitLab 8.2. +> - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570) the usage of native emoji if the platform > supports them and falls back to images or CSS sprites. This change greatly -> improved the award emoji performance overall. +> improved award emoji performance overall. When you're collaborating online, you get fewer opportunities for high-fives -and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and -virtually everywhere where you can have a discussion. +and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), +[snippets](snippets.md), and anywhere you can have a discussion.  Award emoji make it much easier to give and receive feedback without a long -comment thread. Comments that are only emoji will automatically become -award emoji. +comment thread. + +For information on the relevant API, see [Award Emoji API](../api/award_emoji.md). ## Sort issues and merge requests on vote count -> [Introduced][2871] in GitLab 8.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781) in GitLab 8.5. You can quickly sort issues and merge requests by the number of votes they have received. The sort options can be found in the dropdown menu as "Most @@ -32,20 +32,16 @@ downvotes. ## Award emoji for comments -> [Introduced][4291] in GitLab 8.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291) in GitLab 8.9. Award emoji can also be applied to individual comments when you want to celebrate an accomplishment or agree with an opinion. -To add an award emoji, click the smile in the top right of the comment and pick -an emoji from the dropdown. If you want to remove an award emoji, just click -the emoji again and the vote will be removed. +To: + +- Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown. +- Remove an award emoji, click the emoji again and the vote will be removed.   - -[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781 -[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825 -[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291 -[ce-9570]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570 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/img/insert_suggestion.png b/doc/user/discussions/img/insert_suggestion.png Binary files differnew file mode 100644 index 00000000000..4bf293b8297 --- /dev/null +++ b/doc/user/discussions/img/insert_suggestion.png diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png Binary files differnew file mode 100644 index 00000000000..20acc1417da --- /dev/null +++ b/doc/user/discussions/img/make_suggestion.png diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png Binary files differnew file mode 100644 index 00000000000..68a67e6ae5e --- /dev/null +++ b/doc/user/discussions/img/suggestion.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 097b18ad496..84f4b0b3922 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -273,6 +273,71 @@ 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 epic/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. + +## Suggest Changes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. + +As a reviewer, you're able to suggest code changes with a simple +markdown syntax in Merge Request Diff discussions. Then, the +Merge Request author (or other users with appropriate +[permission](../permissions.md)) is able to apply these +suggestions with a click, which will generate a commit in +the Merge Request authored by the user that applied them. + +1. Choose a line of code to be changed, add a new comment, then click +on the **Insert suggestion** icon in the toolbar: + +  + + > **Note:** + The suggestion will only affect the commented line. Multi-line + suggestions are currently not supported. Will be introduced by + [#53310](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310). + +1. In the comment, add your suggestion to the pre-populated code block: + +  + +1. Click **Comment**. + + The suggestions in the comment can be applied by the merge request author + directly from the merge request: + +  + + > **Note:** + Discussions are _not_ automatically resolved. Will be introduced by + [#54405](https://gitlab.com/gitlab-org/gitlab-ce/issues/54405). + +Once the author applies a suggestion, it will be marked with the **Applied** label, +and GitLab will create a new commit with the message `Apply suggestion to <file-name>` +and push the suggested change directly into the codebase in the merge request's branch. +[Developer permission](../permissions.md) is required to do so. + +> **Note:** +Custom commit messages will be introduced by +[#54404](https://gitlab.com/gitlab-org/gitlab-ce/issues/54404). + [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 diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index e14e716a5eb..c1c9b8bf43c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -46,7 +46,7 @@ Below are the settings for [GitLab Pages]. | Setting | GitLab.com | Default | | ----------------------- | ---------------- | ------------- | | Domain name | `gitlab.io` | - | -| IP address | `52.167.214.135` | - | +| IP address | `35.185.44.232` | - | | Custom domains support | yes | no | | TLS certificates support| yes | no | @@ -281,12 +281,14 @@ of proposed changes can be found at GitLab.com adjusts the memory limits for the [unicorn-worker-killer][unicorn-worker-killer] gem. Base default: -* `memory_limit_min` = 750MiB -* `memory_limit_max` = 1024MiB + +- `memory_limit_min` = 750MiB +- `memory_limit_max` = 1024MiB Web front-ends: -* `memory_limit_min` = 1024MiB -* `memory_limit_max` = 1280MiB + +- `memory_limit_min` = 1024MiB +- `memory_limit_max` = 1280MiB ## GitLab.com at scale diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md new file mode 100644 index 00000000000..9f9b2da23e1 --- /dev/null +++ b/doc/user/group/clusters/index.md @@ -0,0 +1,132 @@ +# Group-level Kubernetes clusters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) in GitLab 11.6. +> Group Cluster integration is currently in [Beta](https://about.gitlab.com/handbook/product/#alpha-beta-ga). + +## Overview + +Similar to [project Kubernetes +clusters](../../project/clusters/index.md), Group-level Kubernetes +clusters allow you to connect a Kubernetes cluster to your group, +enabling you to use the same cluster across multiple projects. + +## Installing applications + +GitLab provides a one-click install for various applications that can be +added directly to your cluster. + +NOTE: **Note:** +Applications will be installed in a dedicated namespace called +`gitlab-managed-apps`. If you have added an existing Kubernetes cluster +with Tiller already installed, you should be careful as GitLab cannot +detect it. In this event, installing Tiller via the applications will +result in the cluster having it twice. This can lead to confusion during +deployments. + +| Application | GitLab version | Description | Helm Chart | +| ----------- | -------------- | ----------- | ---------- | +| [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](../../../topics/autodevops/index.md) or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | + +## RBAC compatibility + +For each project under a group with a Kubernetes cluster, GitLab will +create a restricted service account with [`edit` +privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) +in the project namespace. + +NOTE: **Note:** +RBAC support was introduced in +[GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-ce/issues/29398), and +Project namespace restriction was introduced in +[GitLab 11.5](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716). + +## Cluster precedence + +GitLab will use the project's cluster before using any cluster belonging +to the group containing the project if the project's cluster is available and not disabled. + +In the case of sub-groups, GitLab will use the cluster of the closest ancestor group +to the project, provided the cluster is not disabled. + +## Multiple Kubernetes clusters **[PREMIUM]** + +With GitLab Premium, you can associate more than one Kubernetes clusters to your +group. That way you can have different clusters for different environments, +like dev, staging, production, etc. + +Add another cluster similar to the first one and make sure to +[set an environment scope](#environment-scopes) that will +differentiate the new cluster from the rest. + +NOTE: **Note:** +Auto DevOps is not supported for a group with multiple clusters, as it +is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group +level. This will be resolved in the future with the [following issue]( +https://gitlab.com/gitlab-org/gitlab-ce/issues/52363). + +## Environment scopes **[PREMIUM]** + +When adding more than one Kubernetes cluster to your project, you need +to differentiate them with an environment scope. The environment scope +associates clusters with [environments](../../../ci/environments.md) +similar to how the [environment-specific +variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables) +work. + +While evaluating which environment matches the environment scope of a +cluster, [cluster precedence](#cluster-precedence) will take +effect. The cluster at the project level will take precedence, followed +by the closest ancestor group, followed by that groups' parent and so +on. + +For example, let's say we have the following Kubernetes clusters: + +| Cluster | Environment scope | Where | +| ---------- | ------------------- | ----------| +| Project | `*` | Project | +| Staging | `staging/*` | Project | +| Production | `production/*` | Project | +| Test | `test` | Group | +| Development| `*` | Group | + + +And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): + +```yaml +stages: +- test +- deploy + +test: + stage: test + script: sh test + +deploy to staging: + stage: deploy + script: make deploy + environment: + name: staging/$CI_COMMIT_REF_NAME + url: https://staging.example.com/ + +deploy to production: + stage: deploy + script: make deploy + environment: + name: production/$CI_COMMIT_REF_NAME + url: https://example.com/ +``` + +The result will then be: + +- The Project cluster will be used for the `test` job. +- The Staging cluster will be used for the `deploy to staging` job. +- The Production cluster will be used for the `deploy to production` job. + +## Unavailable features + +The following features are not currently available for group-level clusters: + +1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)). +1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). +1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md new file mode 100644 index 00000000000..8e101407ac0 --- /dev/null +++ b/doc/user/group/custom_project_templates.md @@ -0,0 +1,26 @@ +# 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](../project/index.md), creating it based on custom project templates is +a convenient bootstrap option. + +Users can configure a GitLab group that serves as template +source under a group's **Settings > General > Custom project templates**. + +NOTE: **Note:** +GitLab administrators can +[set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). + +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 is a member of the project. + +NOTE: **Note:** +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). 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..6d43e309e84 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..df98091334c 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 7d01c6f2bf6..5fea683a7fd 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -252,11 +252,24 @@ 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. +- **Kubernetes cluster integration**: connect your GitLab group with [Kubernetes clusters](clusters/index.md). - **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 +- **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 8db36c4a0e8..b6f8f55978b 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -21,8 +21,8 @@ Nested groups are only supported when you use PostgreSQL. Supporting nested groups on MySQL in an efficient way is not possible due to MySQL's limitations. See the following links for more information: -* <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> -* <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885> +- <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> +- <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885> ## Overview @@ -164,10 +164,11 @@ and you can choose the group of people to be notified. Here's a list of what you can't do with subgroups: -- [GitLab Pages](../../project/pages/index.md) are not currently working for - projects hosted under a subgroup. That means that only projects hosted under - the first parent group will work. -- Group level labels don't work in subgroups / sub projects +- [GitLab Pages](../../project/pages/index.md) supports projects hosted under + a subgroup, but not subgroup websites. + That means that only the highest-level group supports + [group websites](../../project/pages/introduction.html#user-or-group-pages), + although you can have project websites under a subgroup. - It is not possible to share a project with a group that's an ancestor of the group the project is in. That means you can only share as you walk down the hierarchy. For example, `group/subgroup01/project` **cannot** be shared diff --git a/doc/user/img/color_inline_colorchip_render_gfm.png b/doc/user/img/color_inline_colorchip_render_gfm.png Binary files differindex 6a8a674d6e0..fed8ca5c34b 100644 --- a/doc/user/img/color_inline_colorchip_render_gfm.png +++ 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 differindex bf1464457bc..3ee2abb14df 100644 --- a/doc/user/img/math_inline_sup_render_gfm.png +++ 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 differindex 3b3eb3a738a..9d192a30a85 100644 --- a/doc/user/img/mermaid_diagram_render_gfm.png +++ 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 differindex fdff8a9886c..0905a8378be 100644 --- a/doc/user/img/task_list_ordered_render_gfm.png +++ 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 differindex 2e3fb7cbb79..ccdeab6e62c 100644 --- a/doc/user/img/unordered_check_list_render_gfm.png +++ b/doc/user/img/unordered_check_list_render_gfm.png diff --git a/doc/user/index.md b/doc/user/index.md index 08995032cb1..fc68404d0c2 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -113,6 +113,7 @@ methods available in GitLab. user type (guest, reporter, developer, maintainer, owner). - [Feature highlight](feature_highlight.md): Learn more about the little blue dots around the app that explain certain features +- [Abuse reports](abuse_reports.md): Report abuse from users to GitLab administrators ## Groups 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/instance_statistics/user_cohorts.md b/doc/user/instance_statistics/user_cohorts.md index 70d5912dc4e..f52f24ef5f7 100644 --- a/doc/user/instance_statistics/user_cohorts.md +++ b/doc/user/instance_statistics/user_cohorts.md @@ -23,5 +23,5 @@ the month, but who have never actually had any activity in the instance. How do we measure the activity of users? GitLab considers a user active if: -* the user signs in -* the user has Git activity (whether push or pull). +- The user signs in. +- The user has Git activity (whether push or pull). diff --git a/doc/user/markdown.md b/doc/user/markdown.md index f9bdaea185b..f2448f240ca 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,36 +1,51 @@ -# 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] - -_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]._ +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. -_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/). +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 additional 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:** +> +> We encourage you to view this document 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 +65,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 +85,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 +108,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 @@ -116,7 +141,7 @@ GFM will autolink almost any URL you copy and paste into your text: * <a href="irc://irc.freenode.net/gitlab">irc://irc.freenode.net/gitlab</a> * http://localhost:3000 -### Multiline Blockquote +### Multiline blockquote > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote @@ -124,7 +149,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 @@ -146,7 +171,7 @@ you can quote that without having to manually prepend `>` to every line! <p>you can quote that without having to manually prepend <code>></code> to every line!</p> </blockquote> -### Code and Syntax Highlighting +### Code and syntax highlighting > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting @@ -158,7 +183,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. ``` @@ -216,7 +241,7 @@ s = "There is no highlighting for this." But let's throw in a <b>tag</b>. ``` -### Inline Diff +### Inline diff > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff @@ -248,21 +273,23 @@ 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 <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: @@ -273,7 +300,7 @@ You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-ce/ 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. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px"> +Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) 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. @@ -281,8 +308,7 @@ 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 +### Special GitLab references GFM recognizes special references. @@ -336,14 +362,14 @@ It also has a shorthand version to reference other projects from the same namesp | `project@9ba12248...b19a04f5` | commit range comparison | | `project~"Some label"` | issues with given label | -### Task Lists +### Task lists > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists 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 @@ -355,7 +381,7 @@ You can add task lists to issues, merge requests and comments. To create a task Tasks formatted as ordered lists are supported as well: -```no-highlight +``` 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -412,7 +438,7 @@ This math is inline . This is on a separate line -<div align="center"><img src="./img/math_inline_sup_render_gfm.png" ></div> +<img src="./img/math_inline_sup_render_gfm.png" > _Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ @@ -440,7 +466,7 @@ Examples: `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` -Become: +Becomes:  @@ -478,11 +504,71 @@ Becomes: For details see the [Mermaid official page][mermaid]. +### Front matter + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) + in GitLab 11.6. + +Front matter is metadata included at the beginning of a markdown document, preceding +its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/) and [Hugo](https://gohugo.io/content-management/front-matter/), +and many other applications. + +In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported. +When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document, before the rendered HTML content. +To view an example, you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). + +The following delimeters are supported: + +- YAML (`---`): + + ``` + --- + title: About Front Matter + example: + language: yaml + --- + ``` + +- TOML (`+++`): + + ``` + +++ + title = "About Front Matter" + [example] + language = "toml" + +++ + ``` + +- JSON (`;;;`): + + ``` + ;;; + { + "title": "About Front Matter" + "example": { + "language": "json" + } + } + ;;; + ``` + +Other languages are supported by adding a specifier to any of the existing +delimiters. For example: + +``` +---php +$title = "About Front Matter"; +$example = array( + 'language' => "php", +); +--- +``` + ## Standard Markdown ### Headers -```no-highlight +``` # H1 ## H2 ### H3 @@ -540,7 +626,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__. @@ -550,7 +636,7 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Become: +Becomes: Emphasis, aka italics, with *asterisks* or _underscores_. @@ -564,7 +650,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ Examples: -```no-highlight +``` 1. First ordered list item 2. Another item * Unordered sub-list. @@ -577,7 +663,7 @@ Examples: + Or pluses ``` -Become: +Becomes: 1. First ordered list item 2. Another item @@ -595,7 +681,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. @@ -616,7 +702,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. @@ -676,7 +762,7 @@ Examples: [logo]: img/markdown_logo.png -Become: +Becomes: Here's our logo: @@ -694,7 +780,7 @@ Reference-style: Examples: -```no-highlight +``` > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -703,7 +789,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. @@ -720,7 +806,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> @@ -730,7 +816,7 @@ Examples: </dl> ``` -Become: +Becomes: <dl> <dt>Definition list</dt> @@ -755,7 +841,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> @@ -788,7 +874,7 @@ ___ Underscores ``` -Become: +Becomes: Three or more... @@ -826,7 +912,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. @@ -995,7 +1081,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 4359592905d..019652b2408 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -44,6 +44,7 @@ The following table depicts the various user permission levels in a project. | View wiki pages | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | View license management reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | View Security reports **[ULTIMATE]** | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| View project code | [^1] | ✓ | ✓ | ✓ | ✓ | | Pull project code | [^1] | ✓ | ✓ | ✓ | ✓ | | Download project | [^1] | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | @@ -79,6 +80,7 @@ The following table depicts the various user permission levels in a project. | View approved/blacklisted licenses **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Use security dashboard **[ULTIMATE]** | | | ✓ | ✓ | ✓ | | Dismiss vulnerability **[ULTIMATE]** | | | ✓ | ✓ | ✓ | +| Apply code change suggestions | | | ✓ | ✓ | ✓ | | Use environment terminals | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | @@ -95,6 +97,7 @@ 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) | | | | ✓ | ✓ | @@ -156,6 +159,13 @@ Confidential issues can be accessed by reporters and higher permission levels, as well as by guest users that create a confidential issue. To learn more, read through the documentation on [permissions and access to confidential issues](project/issues/confidential_issues.md#permissions-and-access-to-confidential-issues). +### Releases permissions + +[Project Releases](project/releases/index.md) can be read by all project +members (Reporters, Developers, Maintainers, Owners) **except Guests**. +Releases can be created, updated, or deleted via [Releases APIs](../api/releases/index.md) +by project Developers, Maintainers, and Owners. + ## Group members permissions NOTE: **Note:** @@ -175,9 +185,7 @@ group. | Remove group | | | | | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | Create/edit/delete group milestones | | | ✓ | ✓ | ✓ | -| View private group epic **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | -| View internal group epic **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View public group epic **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View group epic **[ULTIMATE]** | ✓ | ✓ | ✓ | ✓ | ✓ | | Create/edit group epic **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | | Delete group epic **[ULTIMATE]** | | | | | ✓ | | View group Audit Events | | | | | ✓ | @@ -206,7 +214,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 @@ -217,7 +225,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. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 49f0ce2cd79..b497cc414af 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -25,7 +25,7 @@ Here's a list of things that will not be deleted: Instead of being deleted, these records will be moved to a system-wide "Ghost User", whose sole purpose is to act as a container for such records. -When a user is deleted from an abuse report or spam log, these associated +When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) or spam log, these associated records are not ghosted and will be removed, along with any groups the user is a sole owner of. Administrators can also request this behaviour when deleting users from the [API](../../../api/users.md#user-deletion) or the @@ -35,4 +35,3 @@ admin area. [ce-10273]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273 [ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467 [ce-11853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853 - diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index bc6ecdf4f32..83bc79925e1 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -2,8 +2,8 @@ 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 your one time password -authenticator. For example, a password manager on one of your devices. +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 one time password secret. @@ -43,8 +43,8 @@ or a U2F device. 1. Install a compatible application. We recommend [Google Authenticator] \(proprietary\) or [FreeOTP] \(open source\). 1. In the application, add a new entry in one of two ways: - * Scan the code with your phone's camera to add the entry automatically. - * Enter the details provided to add the entry manually. + - Scan the code with your phone's camera to add the entry automatically. + - Enter the details provided to add the entry manually. **In GitLab:** @@ -83,9 +83,11 @@ Click on **Register U2F Device** to complete the process. Recovery codes are not generated for U2F devices. 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 or printing them for -storage in a safe place. **Each code can be used only once** to log in to your -account. +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). @@ -104,7 +106,7 @@ Enter the pin from your one time password authenticator's application or a recov ### Log in via U2F device -1. Click **Login via U2F Device** +1. Click **Login via 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 responded to the authentication request. @@ -133,9 +135,9 @@ authenticate with Git over HTTPS on the command line or when using To disable two-factor authentication on your account (for example, if you have lost your code generation device) you can: -* [Use a saved recovery code](#use-a-saved-recovery-code) -* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh) -* [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account) +- [Use a saved recovery code](#use-a-saved-recovery-code). +- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). +- [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account). ### Use a saved recovery code @@ -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 ab62762f343..efb031b8239 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 @@ -72,7 +73,7 @@ which also covers the case where you have projects hosted with ## Private profile -The following information will be hidden from the user profile page (https://gitlab.example.com/username) if this feature is enabled: +The following information will be hidden from the user profile page (`https://gitlab.example.com/username`) if this feature is enabled: - Atom feed - Date when account is created @@ -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 @@ -132,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..0e6d4bce153 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 --decode + ``` + +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 3ec17806490..bb815695cb1 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -17,6 +17,11 @@ your account with Google Kubernetes Engine (GKE) so that you can [create new clusters](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab, or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster). +NOTE: **Note:** +From [GitLab 11.6](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) you +can also associate a Kubernetes cluster to your groups. Learn more about +[group Kubernetes clusters](../../group/clusters/index.md). + ## Adding and creating a new GKE cluster via GitLab TIP: **Tip:** @@ -49,13 +54,13 @@ 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: - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. + - **Environment scope** - The [associated environment](#setting-the-environment-scope-premium) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP console that will host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). @@ -78,8 +83,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,27 +97,70 @@ 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. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. + 1. Finally, click the **Create Kubernetes cluster** button. 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 --decode`. +- CA certificate, run `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode`. + ## Security implications CAUTION: **Important:** @@ -121,62 +169,70 @@ are trusted, so **only trusted users should be allowed to control your clusters* The default cluster configuration grants access to a wide set of functionalities needed to successfully build and deploy a containerized -application. Bare in mind that the same credentials are used for all the +application. Bear 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. - -Once RBAC is enabled for a cluster, GitLab will create the necessary service accounts -and privileges in order to install and run [GitLab managed applications](#installing-applications). +## Access controls -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. +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. 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). +[RBAC](#role-based-access-control-rbac) is recommended and the GitLab default. + +Whether [ABAC](#attribute-based-access-control-abac) or [RBAC](#role-based-access-control-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 @@ -198,31 +254,49 @@ install it manually. ## Installing applications -GitLab provides a one-click install for various applications which will be -added directly to your configured cluster. Those applications are needed for -[Review Apps](../../../ci/review_apps/index.md) and [deployments](../../../ci/environments.md). +GitLab provides a one-click install for various applications which can +be added directly to your configured cluster. Those applications are +needed for [Review Apps](../../../ci/review_apps/index.md) and +[deployments](../../../ci/environments.md). You can install them after you +[create a cluster](#adding-and-creating-a-new-gke-cluster-via-gitlab). + +To see a list of available applications to install: + +1. Navigate to your project's **Operations > Kubernetes**. +1. Select your cluster. + +Install Helm Tiller first because it's used to install other applications. NOTE: **Note:** -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 -twice, which can lead to confusion during deployments. +As of GitLab 11.6, Helm Tiller will be upgraded to the latest version supported +by GitLab before installing any of the applications. | Application | GitLab version | Description | Helm Chart | | ----------- | :------------: | ----------- | --------------- | | [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. | [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. You will also see ready-to-use DevOps Runbooks built with [Rubix](https://github.com/amit1rrr/rubix). **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 a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) 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 in [our Nurtch documentation](runbooks/index.md#nurtch-executable-runbooks). **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) + +With the exception of Knative, the applications will be installed in a dedicated +namespace called `gitlab-managed-apps`. + +CAUTION: **Caution:** +If you have an existing Kubernetes cluster with Tiller already installed, +you should be careful as GitLab cannot detect it. In this case, installing +Tiller via the applications will result in the cluster having it twice, which +can lead to confusion during deployments. ## 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. @@ -231,21 +305,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: @@ -254,20 +331,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} ' ``` -> **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}". -> ``` +Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: -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 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: + +```bash +kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +``` ### Using a static IP @@ -277,7 +357,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 @@ -287,17 +367,25 @@ to reach your apps. This heavily depends on your domain provider, but in case you aren't sure, just create an A record with a wildcard host like `*.example.com.`. -## Setting the environment scope +## Multiple Kubernetes clusters **[PREMIUM]** -NOTE: **Note:** -This is only available for [GitLab Premium][ee] where you can add more than -one Kubernetes cluster. - -When adding more than one Kubernetes clusters to your project, you need to -differentiate them with an environment scope. The environment scope associates -clusters and [environments](../../../ci/environments.md) in an 1:1 relationship -similar to how the -[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables) +> Introduced in [GitLab Premium][ee] 10.3. + +With GitLab Premium, you can associate more than one Kubernetes clusters to your +project. That way you can have different clusters for different environments, +like dev, staging, production, etc. + +Simply add another cluster, like you did the first time, and make sure to +[set an environment scope](#setting-the-environment-scope) that will +differentiate the new cluster with the rest. + +## Setting the environment scope **[PREMIUM]** + +When adding more than one Kubernetes clusters to your project, you need +to differentiate them with an environment scope. The environment scope +associates clusters with [environments](../../../ci/environments.md) +similar to how the [environment-specific +variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables) work. The default environment scope is `*`, which means all jobs, regardless of their @@ -309,11 +397,11 @@ Also, jobs that don't have an environment keyword set will not be able to access For example, let's say the following Kubernetes clusters exist in a project: -| Cluster | Environment scope | -| ---------- | ------------------- | -| Development| `*` | -| Staging | `staging/*` | -| Production | `production/*` | +| Cluster | Environment scope | +| ----------- | ----------------- | +| Development | `*` | +| Staging | `staging` | +| Production | `production` | And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): @@ -330,14 +418,14 @@ deploy to staging: stage: deploy script: make deploy environment: - name: staging/$CI_COMMIT_REF_NAME + name: staging url: https://staging.example.com/ deploy to production: stage: deploy script: make deploy environment: - name: production/$CI_COMMIT_REF_NAME + name: production url: https://example.com/ ``` @@ -347,18 +435,6 @@ The result will then be: - The staging cluster will be used for the "deploy to staging" job. - The production cluster will be used for the "deploy to production" job. -## Multiple Kubernetes clusters - -> Introduced in [GitLab Premium][ee] 10.3. - -With GitLab Premium, you can associate more than one Kubernetes clusters to your -project. That way you can have different clusters for different environments, -like dev, staging, production, etc. - -Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. - ## Deployment variables The Kubernetes cluster integration exposes the following @@ -368,18 +444,52 @@ 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. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. | +| `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. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | + +NOTE: **NOTE:** +Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main +service account of the cluster integration. + +### Troubleshooting missing `KUBECONFIG` or `KUBE_TOKEN` + +GitLab will create a new service account specifically for your CI builds. The +new service account is created when the cluster is added to the project. +Sometimes there may be errors that cause the service account creation to fail. + +In such instances, your build will not be passed the `KUBECONFIG` or +`KUBE_TOKEN` variables and, if you are using Auto DevOps, your Auto DevOps +pipelines will no longer trigger a `production` deploy build. You will need to +check the [logs](../../../administration/logs.md) to debug why the service +account creation failed. + +A common reason for failure is that the token you gave GitLab did not have +[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) +privileges as GitLab expects. + +Another common problem for why these variables are not being passed to your +builds is that they must have a matching +[`environment:name`](../../../ci/environments.md#defining-environments). If +your build has no `environment:name` set, it will not be passed the Kubernetes +credentials. + +## Monitoring your Kubernetes cluster **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4701) in [GitLab Ultimate][ee] 10.6. + +When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. + + ## 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. @@ -396,17 +506,20 @@ 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. +## View Kubernetes pod logs from GitLab **[ULTIMATE]** + +Learn how to easily +[view the logs of running pods in connected Kubernetes clusters](https://docs.gitlab.com/ee/user/project/clusters/kubernetes_pod_logs.html). + ## What you can get with the Kubernetes integration Here's what you can do with GitLab if you enable the Kubernetes integration. -### Deploy Boards - -> Available in [GitLab Premium][ee]. +### Deploy Boards **[PREMIUM]** GitLab's Deploy Boards offer a consolidated view of the current health and status of each CI [environment](../../../ci/environments.md) running on Kubernetes, @@ -414,24 +527,22 @@ displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. -[> Read more about Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) - -### Canary Deployments +[Read more about Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) -> Available in [GitLab Premium][ee]. +### Canary Deployments **[PREMIUM]** Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) and visualize your canary deployments right inside the Deploy Board, without the need to leave GitLab. -[> Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) +[Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) ### Kubernetes monitoring Automatically detect and monitor Kubernetes metrics. Automatic monitoring of [NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported. -[> Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) +[Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) ### Auto DevOps @@ -441,7 +552,7 @@ applications. To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) you will need the Kubernetes project integration enabled. -[> Read more about Auto DevOps](../../../topics/autodevops/index.md) +[Read more about Auto DevOps](../../../topics/autodevops/index.md) ### Web terminals @@ -457,9 +568,13 @@ containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any pods you create are labelled with `app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest! -## Read more +### Integrating Amazon EKS cluster with GitLab + +- Learn how to [connect and deploy to an Amazon EKS cluster](eks_and_gitlab/index.md). + +### Serverless -- [Connecting and deploying to an Amazon EKS cluster](eks_and_gitlab/index.md) +- [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..84cce311483 --- /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..37c110ed0d8 --- /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..1d338f063a9 --- /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..003e482e756 --- /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..7edc11d5b45 --- /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..75c6028a763 --- /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..04315d54d5e --- /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..70011202bf0 --- /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/app-domain.png b/doc/user/project/clusters/serverless/img/app-domain.png Binary files differnew file mode 100644 index 00000000000..d113dfadd2e --- /dev/null +++ b/doc/user/project/clusters/serverless/img/app-domain.png 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..a4a6b363b64 --- /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..678743f256e --- /dev/null +++ b/doc/user/project/clusters/serverless/img/dns-entry.png diff --git a/doc/user/project/clusters/serverless/img/function-execution.png b/doc/user/project/clusters/serverless/img/function-execution.png Binary files differnew file mode 100644 index 00000000000..93b0b6d802d --- /dev/null +++ b/doc/user/project/clusters/serverless/img/function-execution.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..93b1cbe602f --- /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..931830d83ae --- /dev/null +++ b/doc/user/project/clusters/serverless/img/knative-app.png diff --git a/doc/user/project/clusters/serverless/img/serverless-page.png b/doc/user/project/clusters/serverless/img/serverless-page.png Binary files differnew file mode 100644 index 00000000000..814b8532205 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/serverless-page.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..aa1e165e3a2 --- /dev/null +++ b/doc/user/project/clusters/serverless/index.md @@ -0,0 +1,274 @@ +# Serverless + +> Introduced in GitLab 11.5. + +CAUTION: **Caution:** +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). + +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). + +With GitLab serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. + +## Requirements + +To run Knative on Gitlab, you will need: + +1. **Kubernetes Cluster:** 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](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). +1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install + Knative. +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. **`.gitlab-ci.yml`:** 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. +1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file + will contain the information for all the functions being hosted in the repository as well as a reference to the + runtime being used. +1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): 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:** +The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** + +1. [Add a Kubernetes cluster](../index.md) 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, you can wait for the IP address to be displayed in the + **Knative IP Address** field or 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.info` then you need to create an A record with domain `*.knative.info` + pointing the ip address of the ingress. + +  + +## Deploying Functions + +> Introduced in GitLab 11.6. + +Using functions is useful for dealing with independent +events without needing to maintain a complex unified infrastructure. This allows +you to focus on a single task that can be executed/scaled automatically and independently. + +Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are offered: + +- node.js +- kaniko + +You can find all the files referenced in this doc in the [functions example project](https://gitlab.com/knative-examples/functions). + +Follow these steps to deploy a function using the Node.js runtime to your Knative instance: + +1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project. + +1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: + - Public, continue to the next step. + - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + +1. `.gitlab-ci.yml`: This template allows to define the stage, environment, and + image to be used for your functions. It must be included at the root of your repository: + + ```yaml + stages: + - deploy + + functions: + stage: deploy + environment: test + image: gcr.io/triggermesh/tm:v0.0.9 + script: + - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_REGISTRY_USER" --password "$CI_JOB_TOKEN" --push + - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_DEPLOY_USER" --password "$CI_DEPLOY_PASSWORD" --pull + - tm -n "$KUBE_NAMESPACE" deploy --wait + + ``` + + The `gitlab-ci.yml` template creates a `Deploy` stage with a `functions` job that invokes the `tm` CLI with the required parameters. + +2. `serverless.yml`: This file contains the metadata for your functions, + such as name, runtime, and environment. It must be included at the root of your repository. The following is a sample `echo` function which shows the required structure for the file. You can find the relevant files for this project in the [functions example project](https://gitlab.com/knative-examples/functions). + + ```yaml + service: my-functions + description: "Deploying functions from GitLab using Knative" + + provider: + name: triggermesh + registry-secret: gitlab-registry + environment: + FOO: BAR + + functions: + echo: + handler: echo + runtime: https://gitlab.com/triggermesh/runtimes/raw/master/nodejs.yaml + description: "echo function using node.js runtime" + buildargs: + - DIRECTORY=echo + environment: + FUNCTION: echo + ``` + + +The `serverless.yml` file references both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`), +which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it +contains three sections with distinct parameters: + +### `service` + +| Parameter | Description | +|-----------|-------------| +| `service` | Name for the Knative service which will serve the function. | +| `description` | A short description of the `service`. | + + +### `provider` + +| Parameter | Description | +|-----------|-------------| +| `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh `tm` CLI. | +| `registry-secret` | Indicates which registry will be used to store docker images. The sample function is using the GitLab Registry (`gitlab-registry`). A different registry host may be specified using `registry` key in the `provider` object. If changing the default, update the permission and the secret value on the `gitlab-ci.yml` file | +| `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. | + +### `functions` + +In the `serverless.yml` example above, the function name is `echo` and the subsequent lines contain the function attributes. + +| Parameter | Description | +|-----------|-------------| +| `handler` | The function's file name. In the example above, both the function name and the handler are the same. | +| `runtime` | The runtime to be used to execute the function. | +| `description` | A short description of the function. | +| `buildargs` | Pointer to the function file in the repo. In the sample the function is located in the `echo` directory. | +| `environment` | Sets an environment variable for the specific function only. | + +After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been +created, pushing a commit to your project will result in a +CI pipeline being executed which will deploy each function as a Knative service. +Once the deploy stage has finished, additional details for the function will +appear under **Operations > Serverless**. + + + +This page contains all functions available for the project, the description for +accessing the function, and, if available, the function's runtime information. +The details are derived from the Knative installation inside each of the project's +Kubernetes cluster. + +The function details can be retrieved directly from Knative on the cluster: + +```bash +kubectl -n "$KUBE_NAMESPACE" get services.serving.knative.dev +``` + +The sample function can now be triggered from any HTTP client using a simple `POST` call. + + + +## Deploying Serverless applications + +> Introduced in GitLab 11.5. + +NOTE: **Note:** +You can reference the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + +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 above): + +```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 +``` + +### Deploy the application with Knative + +With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to +**CI/CD > Pipelines** and click the most recent pipeline. + +### Obtain the URL for the Knative deployment + +Go to the **Operations > Serverless** page to find the URL for your deployment in the **Domain** column. + + + +Alternatively, use the CI/CD deployment job output to obtain the deployment URL. 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. + + diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 2709ebb6f05..638b73bfcb6 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -15,7 +15,7 @@ With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. -You can read more about Docker Registry at https://docs.docker.com/registry/introduction/. +You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>. ## Enable the Container Registry for your project @@ -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. @@ -278,9 +283,9 @@ In the example above, we see the following trace on the mitmproxy window: The above image shows: -* The initial PUT requests went through fine with a 201 status code. -* The 201 redirected the client to the S3 bucket. -* The HEAD request to the AWS bucket reported a 403 Unauthorized. +- The initial PUT requests went through fine with a 201 status code. +- The 201 redirected the client to the S3 bucket. +- The HEAD request to the AWS bucket reported a 403 Unauthorized. What does this mean? This strongly suggests that the S3 user does not have the right [permissions to perform a HEAD request](http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectHEAD.html). diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index ea843054f8e..b98221bea61 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -146,7 +146,8 @@ A few notes: The current permissions on the Cycle Analytics dashboard are: - Public projects - anyone can access -- Private/internal projects - any member (guest level and above) can access +- Internal projects - any authenticated user can access +- Private projects - any member Guest and above can access You can [read more about permissions][permissions] in general. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ff647b2f0a2..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 https://<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..b753593d212 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_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png Binary files differindex 2288d767d8c..6035d7ca330 100644 --- a/doc/user/project/img/issue_board_summed_weights.png +++ 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 differindex 9e819160861..41ddbb24b14 100644 --- a/doc/user/project/img/issue_boards_core.png +++ b/doc/user/project/img/issue_boards_core.png diff --git a/doc/user/project/img/issue_boards_multiple.png b/doc/user/project/img/issue_boards_multiple.png Binary files differindex 7bb088aad0b..242460925f7 100644 --- a/doc/user/project/img/issue_boards_multiple.png +++ b/doc/user/project/img/issue_boards_multiple.png diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png Binary files differindex bd9164b2961..ef9f5bbea32 100644 --- a/doc/user/project/img/issue_boards_premium.png +++ b/doc/user/project/img/issue_boards_premium.png diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index dc985e87a96..ebf87890cfd 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -27,7 +27,7 @@ request. 1. Bitbucket Server allows multiple levels of threading. GitLab import will collapse this into one discussion and quote part of the original comment. -1. Declined pull requests have unrecahable commits, which prevents the GitLab +1. Declined pull requests have unreachable commits, which prevents the GitLab importer from generating a proper diff. These pull requests will show up as empty changes. 1. Attachments in Markdown are currently not imported. 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..cf99dded5e2 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,16 +17,17 @@ 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+) - * Pull requests (GitLab.com & 8.4+) - * Wiki pages (GitLab.com & 8.4+) - * Milestones (GitLab.com & 8.7+) - * Labels (GitLab.com & 8.7+) - * Release note descriptions (GitLab.com & 8.12+) - * Pull request review comments (GitLab.com & 10.2+) - * Regular issue and pull request comments + +- Repository description (GitLab.com & 7.7+) +- Git repository data (GitLab.com & 7.7+) +- Issues (GitLab.com & 7.7+) +- Pull requests (GitLab.com & 8.4+) +- Wiki pages (GitLab.com & 8.4+) +- Milestones (GitLab.com & 8.7+) +- Labels (GitLab.com & 8.7+) +- Release note descriptions (GitLab.com & 8.12+) +- Pull request review comments (GitLab.com & 10.2+) +- Regular issue and pull request comments References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -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 @@ -91,13 +92,13 @@ 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. Go to <https://github.com/settings/tokens/new> +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 @@ -131,8 +132,8 @@ Admin access to the GitLab server is required. For large projects it may take a while to import all data. To reduce the time necessary, you can increase the number of Sidekiq workers that process the following queues: -* `github_importer` -* `github_importer_advance_stage` +- `github_importer` +- `github_importer_advance_stage` For an optimal experience, it's recommended having at least 4 Sidekiq processes (each running a number of threads equal to the number of CPU cores) that *only* process these queues. It's also recommended that these processes run on separate diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 4ea35a30bbf..ca02e4e9e96 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) @@ -24,3 +25,10 @@ but issues and merge requests can't be imported. If you want to retain all metadata like issues and merge requests, you can use the [import/export feature](../settings/import_export.md). + +## Migrating between two self-hosted GitLab instances + +The best method for migrating a project from one GitLab instance to another, +perhaps from an old server to a new server for example, is to +[back up the project](../../../raketasks/backup_restore.md), +then restore it on the new server. 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/repo_by_url.md b/doc/user/project/import/repo_by_url.md index f43e384de88..c20b1cb7f5e 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -6,7 +6,7 @@ You can import your existing repositories by providing the Git URL: 1. Switch to the **Import project** tab 1. Click on the **Repo by URL** button 1. Fill in the "Git repository URL" and the remaining project fields -1. Click **Create project** to being the import process +1. Click **Create project** to begin the import process 1. Once complete, you will be redirected to your newly created project  diff --git a/doc/user/project/index.md b/doc/user/project/index.md index e63ed88249d..6a1aadf058e 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -65,19 +65,22 @@ common actions on issues or merge requests browse, and download job artifacts - [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job), timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more - - [GKE cluster integration](clusters/index.md): Connecting your GitLab project - with Google Kubernetes Engine + - [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project + with a Kubernetes cluster - [GitLab Pages](pages/index.md): Build, test, and deploy your static website with GitLab Pages **Other features:** -- [Wiki](wiki/index.md): Document your GitLab project in an integrated Wiki -- [Snippets](../snippets.md): Store, share and collaborate on code snippets -- [Cycle Analytics](cycle_analytics.md): Review your development lifecycle -- [Syntax highlighting](highlighting.md): An alternative to customize -your code blocks, overriding GitLab's default choice of language -- [Badges](badges.md): Badges for the project overview +- [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. +- [Snippets](../snippets.md): store, share and collaborate on code snippets. +- [Cycle Analytics](cycle_analytics.md): review your development lifecycle. +- [Syntax highlighting](highlighting.md): an alternative to customize +your code blocks, overriding GitLab's default choice of language. +- [Badges](badges.md): badges for the project overview. +- [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of +the source, build output, and other metadata or artifacts +associated with a released version of your code. ### Project's integrations @@ -146,3 +149,24 @@ When [renaming a user](../profile/index.md#changing-your-username), work after a rename, making any transition a lot smoother. - The redirects will be available as long as the original path is not claimed by another group, user or project. + +## Use your project as a Go package + +Any project can be used as a Go package including private projects in subgroups. To use packages +hosted in private projects with the `go get` command, use a [`.netrc` file](https://ec.haxx.se/usingcurl-netrc.html) +and a [personal access token](../profile/personal_access_tokens.md) in the password field. + +For example: + +```text +machine example.gitlab.com +login <gitlab_user_name> +password <personal_access_token> +``` + +## Access project page with project ID + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53671) in GitLab 11.8. + +To quickly access a project from the GitLab UI using the project ID, +visit the `/projects/:id` URL in your browser or other tool accessing the project. diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 70c0d434f1f..48aabd02438 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -40,7 +40,7 @@ service in GitLab. 1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) 1. Click 'Atlassian Bamboo CI' 1. Select the 'Active' checkbox. -1. Enter the base URL of your Bamboo server. 'https://bamboo.example.com' +1. Enter the base URL of your Bamboo server. `https://bamboo.example.com` 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all 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/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index b050c83fb72..61359dcaa90 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -1,20 +1,20 @@ # Enabling emails on push -By enabling this service, you will be able to receive email notifications for -every change that is pushed to your project. +By enabling this service, you will receive email notifications for every change +that is pushed to your project. -Navigate to the [Integrations page](project_services.md#accessing-the-project-services) -and select the **Emails on push** service to configure it. +From the [Integrations page](project_services.md#accessing-the-project-services) +select **Emails on push** service to activate and configure it. In the _Recipients_ area, provide a list of emails separated by spaces or newlines. -You can configure any of the following settings depending on your preference. +The following options are available: -+ **Push events** - Email will be triggered when a push event is received -+ **Tag push events** - Email will be triggered when a tag is created and pushed -+ **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). -+ **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. +- **Push events** - Email will be triggered when a push event is received. +- **Tag push events** - Email will be triggered when a tag is created and pushed. +- **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). +- **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. ---- - - +| Settings | Notification | +| --- | --- | +|  |  | diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index eee779c50d4..0fd847d415f 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -18,7 +18,7 @@ allow GitLab to send messages only to *one* room. ### Complete these steps in HipChat -1. Go to: https://admin.hipchat.com/admin +1. Go to: <https://admin.hipchat.com/admin> 1. Click on "Group Admin" -> "Integrations". 1. Find "Build Your Own!" and click "Create". 1. Select the desired room, name the integration "GitLab", and click "Create". diff --git a/doc/user/project/integrations/img/emails_on_push_email.png b/doc/user/project/integrations/img/emails_on_push_email.png Binary files differnew file mode 100644 index 00000000000..406eeb18410 --- /dev/null +++ b/doc/user/project/integrations/img/emails_on_push_email.png diff --git a/doc/user/project/integrations/img/emails_on_push_service.png b/doc/user/project/integrations/img/emails_on_push_service.png Binary files differindex df301aa1eeb..84e42eca9a2 100644 --- a/doc/user/project/integrations/img/emails_on_push_service.png +++ b/doc/user/project/integrations/img/emails_on_push_service.png 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..4fa7a46854e --- /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..55c8fb1bdb9 --- /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..3a27b4df841 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/irker.md b/doc/user/project/integrations/irker.md index ecdd83ce8f0..f220fa8497a 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -4,12 +4,12 @@ GitLab provides a way to push update messages to an Irker server. When configured, pushes to a project will trigger the service to send data directly to the Irker server. -See the project homepage for further info: https://gitlab.com/esr/irker +See the project homepage for further info: <https://gitlab.com/esr/irker> ## Needed setup You will first need an Irker daemon. You can download the Irker code from its -repository on https://gitlab.com/esr/irker: +repository on <https://gitlab.com/esr/irker>: ``` git clone https://gitlab.com/esr/irker.git diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 30f49fefc41..754711f5919 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -31,7 +31,7 @@ directly from GitLab, as covered in the article 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 +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 @@ -45,56 +45,13 @@ 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. +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: -As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` -group. +- [Setting up an user in JIRA server](jira_server_configuration.md) -**It is important that the user `gitlab` has 'write' access to projects in Jira** +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: -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. 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 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. +- [Setting up an user in JIRA cloud](jira_cloud_configuration.md) ### Configuring GitLab @@ -117,8 +74,8 @@ in the table below. | ----- | ----------- | | `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). | +| `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.** | ### Obtaining a transition ID @@ -159,11 +116,11 @@ USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: 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. -* `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. +- `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. +- `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.  @@ -235,11 +192,11 @@ 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.) -### CAPTCHA +### CAPTCHA -CAPTCHA may be triggered after several consecutive failed login attempts +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 +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. 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..849df707521 --- /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 89de1fe4dcb..8c5461de42f 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,13 +4,13 @@ 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 -it on https://mattermost.example/admin_console/integrations/custom. +it on `https://mattermost.example/admin_console/integrations/custom`. Display name override is not enabled by default, you need to ask your admin to enable it on that same section. @@ -38,7 +38,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up 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/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 0b61a41aab0..a4698fd172a 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -9,8 +9,9 @@ within the GitLab interface.  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). + +- 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). Once enabled, GitLab will automatically detect metrics from known services in the [metric library](#monitoring-ci-cd-environments). @@ -23,14 +24,14 @@ GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cl #### Requirements -* A [connected Kubernetes cluster](../clusters/index.md) -* Helm Tiller [installed by GitLab](../clusters/index.md#installing-applications) +- A [connected Kubernetes cluster](../clusters/index.md) +- Helm Tiller [installed by GitLab](../clusters/index.md#installing-applications) #### Getting started Once you have a connected Kubernetes cluster with Helm installed, deploying a managed Prometheus is as easy as a single click. -1. Go to the `Operations > Kubernetes` page, to view your connected clusters +1. Go to the **Operations > Kubernetes** page to view your connected clusters 1. Select the cluster you would like to deploy Prometheus to 1. Click the **Install** button to deploy Prometheus to the cluster @@ -41,9 +42,10 @@ Once you have a connected Kubernetes cluster with Helm installed, deploying a ma Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#%3Ckubernetes_sd_config%3E) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): -* `prometheus.io/scrape` to `true` to enable monitoring of the resource. -* `prometheus.io/port` to define the port of the metrics endpoint. -* `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. + +- `prometheus.io/scrape` to `true` to enable monitoring of the resource. +- `prometheus.io/port` to define the port of the metrics endpoint. +- `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. CPU and Memory consumption is monitored, but requires [naming conventions](prometheus_library/kubernetes.html#specifying-the-environment) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/), this is handled automatically. @@ -56,7 +58,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 +67,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 @@ -87,7 +89,7 @@ to integrate with. Once configured, GitLab will attempt to retrieve performance metrics for any environment which has had a successful deployment. -GitLab will automatically scan the Prometheus server for metrics from known serves like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our [Prometheus Metric Library documentation](prometheus_library/metrics.html). +GitLab will automatically scan the Prometheus server for metrics from known serves like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). @@ -130,7 +132,7 @@ If the "No data found" screen continues to appear, it could be due to: [prometheus-docker-image]: https://hub.docker.com/r/prom/prometheus/ [prometheus-yml]:samples/prometheus.yml [gitlab.com-ip-range]: https://gitlab.com/gitlab-com/infrastructure/issues/434 -[ci-environment-slug]: ../../../ci/variables/#predefined-variables-environment-variables +[ci-environment-slug]: ../../../ci/variables/#predefined-environment-variables [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935 [ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408 [promgldocs]: ../../../administration/monitoring/prometheus/index.md 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..f47884996d8 --- /dev/null +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -0,0 +1,34 @@ +# 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 0.9.0-0.15.x](nginx_ingress_vts.md) +- [NGINX Ingress Controller 0.16.0+](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-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/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 6b190deaa6c..7a45c87ada0 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -34,4 +34,4 @@ Prometheus needs to be deployed into the cluster and configured properly in orde In order to isolate and only display relevant CPU and Memory metrics for a given environment, GitLab needs a method to detect which containers it is running. Because these metrics are tracked at the container level, traditional Kubernetes labels are not available. -Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. +Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name should begin with [CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-environment-variables). It can be followed by a `-` and additional content if desired. For example, a deployment name of `review-homepage-5620p5` would match the `review/homepage` environment. 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..b7601f26802 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,8 +1,10 @@ # 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/22133) in GitLab 11.7. -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. +NOTE: **Note:** NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. + +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX ingress controller. This is provided by leveraging the built-in Prometheus metrics included starting with [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160). ## Requirements @@ -12,43 +14,45 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code) | -| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) | -| HTTP Error Rate (%) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100 | +| Throughput (req/sec) | sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code) | +| Latency (ms) | sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000 | +| HTTP Error Rate (%) | sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100 | ## Configuring NGINX ingress monitoring If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: -* NGINX Ingress should be version 0.9.0 or above, with metrics enabled -* NGINX Ingress should be annotated for Prometheus monitoring -* Prometheus should be configured to monitor annotated pods + +- NGINX Ingress should be version 0.16.0 or above, with metrics enabled. +- NGINX Ingress should be annotated for Prometheus monitoring. +- Prometheus should be configured to monitor annotated pods. ### About managed NGINX Ingress deployments NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's IP](../../clusters/index.md#getting-the-external-ip-address). NGINX is configured for Prometheus monitoring, by setting: -* `enable-vts-status: "true"`, to export Prometheus metrics -* `prometheus.io/scrape: "true"`, to enable automatic discovery -* `prometheus.io/port: "10254"`, to specify the metrics port + +- `enable-vts-status: "true"`, to export Prometheus metrics. +- `prometheus.io/scrape: "true"`, to enable automatic discovery. +- `prometheus.io/port: "10254"`, to specify the metrics port. When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX ingress](https://github.com/kubernetes/ingress/tree/master/controllers/nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +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: -* `prometheus.io/scrape: "true"` -* `prometheus.io/port: "10254"` +- `prometheus.io/scrape: "true"` +- `prometheus.io/port: "10254"` Managing these settings depends on how NGINX ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible edit the NGINX ingress YML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). ## Specifying the Environment label -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 this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +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 this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. If you have used [Auto Deploy](../../../../topics/autodevops/index.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md new file mode 100644 index 00000000000..081eb8732ad --- /dev/null +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -0,0 +1,58 @@ +# Monitoring NGINX Ingress Controller with VTS metrics + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438) in GitLab 9.5. + +NOTE: **Note:** [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. + +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX ingress controller. This is provided by leveraging the included VTS Prometheus metrics exporter in [version 0.9.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#09-beta1) through [0.15.x](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0150). + +## Requirements + +[Prometheus integration](../prometheus.md) must be active. + +## Metrics supported + +| Name | Query | +| ---- | ----- | +| Throughput (req/sec) | sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code) | +| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) | +| HTTP Error Rate (%) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100 | + +## Configuring NGINX ingress monitoring + +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. + +For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: + +- NGINX Ingress should be version 0.9.0 or above, with metrics enabled. +- NGINX Ingress should be annotated for Prometheus monitoring. +- Prometheus should be configured to monitor annotated pods. + +### About managed NGINX Ingress deployments + +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's IP](../../clusters/index.md#getting-the-external-ip-address). + +NGINX is configured for Prometheus monitoring, by setting: + +- `enable-vts-status: "true"`, to export Prometheus metrics. +- `prometheus.io/scrape: "true"`, to enable automatic discovery. +- `prometheus.io/port: "10254"`, to specify the metrics port. + +When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. + +### Manually setting up NGINX Ingress for Prometheus monitoring + +Version 0.9.0 and above of [NGINX ingress](https://github.com/kubernetes/ingress-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: + +- `prometheus.io/scrape: "true"` +- `prometheus.io/port: "10254"` + +Managing these settings depends on how NGINX ingress has been deployed. If you have deployed via the [official Helm chart](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress), metrics can be enabled with `controller.stats.enabled` along with the required annotations. Alternatively it is possible edit the NGINX ingress YML directly in the [Kubernetes dashboard](https://github.com/kubernetes/dashboard). + +## Specifying the Environment label + +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 this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. + +If you have used [Auto Deploy](../../../../topics/autodevops/index.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. 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/slack.md b/doc/user/project/integrations/slack.md index af4ca35a215..bb8d276c2fc 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -23,4 +23,54 @@ The Slack Notifications Service allows your GitLab project to send events (e.g. Your Slack team will now start receiving GitLab event notifications as configured. -
\ No newline at end of file + + +## Troubleshooting + +If you're having trouble with the Slack integration not working, then start by +searching through the [Sidekiq logs](../../../administration/logs.md#sidekiqlog) +for errors relating to your Slack service. + +### Something went wrong on our end + +This is a generic error shown in the GitLab UI and doesn't mean much by itself. +You'll need to look in [the logs](../../../administration/logs.md#productionlog) to find +an error message and keep troubleshooting from there. + +### `certificate verify failed` + +You may see an entry similar to the following in your Sidekiq log: + +```text +2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} +``` + +This is probably a problem either with GitLab communicating with Slack, or GitLab +communicating with itself. The former is less likely since Slack's security certificates +should _hopefully_ always be trusted. We can establish which we're dealing with by using +the below rails console script. + +```sh +# start a rails console: +sudo gitlab-rails console production + +# or for source installs: +bundle exec rails console production +``` + +```ruby +# run this in the Rails console +# replace <SLACK URL> with your actual Slack URL +result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + +# replace <GITLAB URL> with your actual GitLab URL +result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 +``` + +If it's an issue with GitLab not trusting HTTPS connections to itself, then you may simply +need to [add your certificate to GitLab's trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + +If it's an issue with GitLab not trusting connections to Slack, then the GitLab +OpenSSL trust store probably got messed up somehow. Typically this is from overriding +the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}` +or by accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7d12cd8f7c2..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 @@ -1157,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 @@ -1190,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 464fa5987c1..7962eeada5c 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -175,6 +175,10 @@ 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. +Using the search box at the top of the menu, you can filter the listed boards. + +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 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 c33d1365001..2bf4fa287e9 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -39,34 +39,40 @@ It opens a new issue for that project labeled after its respective list. ## New issue via email -*This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available for CE/EE users, and -it's available on GitLab.com.* +At the bottom of a project's Issues List page, a link to **Email a new issue to this project** +is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured. -At the bottom of a project's issue page, click -**Email a new issue to this project**, and you will find an email address -which belongs to you. You could add this address to your contact. + + +When you click this link, an email address is displayed which belongs to you for creating issues in this project. +You can save this address as a contact in your email client for easy acceess. -This is a private email address, generated just for you. -**Keep it to yourself** as anyone who gets ahold of it can create issues or -merge requests as if they were you. You can add this address to your contact -list for easy access. +CAUTION: **Caution:** +This is a private email address, generated just for you. **Keep it to yourself**, +as anyone who gets ahold of it can create issues or merge requests as if they +were you. If the address is compromised, or you'd like it to be regenerated for +any reason, click **Email a new issue to this project** again and click the reset link. Sending an email to this address will create a new issue on your behalf for -this project, where the email subject becomes the issue title, and the email -body becomes the issue description. [Markdown] and [quick actions] are -supported. +this project, where: - +- The email subject becomes the issue title. +- The email body becomes the issue description. +- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. + +NOTE: **Note:** +In GitLab 11.7, we updated the format of the generated email address. +However the older format is still supported, allowing existing aliases +or contacts to continue working._ ## 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 +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 +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). diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md new file mode 100644 index 00000000000..032e3a73ad0 --- /dev/null +++ b/doc/user/project/issues/csv_import.md @@ -0,0 +1,63 @@ +# Importing Issues from CSV + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23532) in GitLab 11.7. + +Issues can be imported to a project by uploading a CSV file. Supported fields are +`title` and `description`. + +The user uploading the CSV file will be set as the author of the imported issues. + +> **Note:** A permission level of `Developer` or higher is required to import issues. + +To import issues: + +1. Ensure your CSV file meets the [file format](#csv-file-format) requirements. +1. Navigate to a project's Issues list page. +1. If existing issues are present, click the import icon at the top right, next to the **Edit issues** button. +1. For a project without any issues, click the button labeled **Import CSV** in the middle of the page. +1. Select the file and click the **Import issues** button. + +The file is processed in the background and a notification email is sent +to you once the import is completed. + +## CSV File Format + +### Header row + +CSV files must contain a header row beginning with at least two columns, `title` and `description`, in that order. +If additional columns are present, they will be ignored. + +### Column separator + +The column separator is automatically detected from the header row. + +Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + +### Row separator + +Lines ending in either `CRLF` or `LF` are supported. + +### Quote character + +The double-quote (`"`) character is used to quote fields so you can use the column separator within a field. To insert +a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`. + +### Data rows + +After the header row, succeeding rows must follow the same column order. The issue title is required while the +description is optional. + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. + +## Sample Data + +```csv +title,description +My Issue Title,My Issue Description +Another Title,"A description, with a comma" +"One More Title","One More Description" +``` diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png Binary files differindex df9d6f64985..dd40740aec5 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/img/similar_issues.png b/doc/user/project/issues/img/similar_issues.png Binary files differnew file mode 100644 index 00000000000..0dfb5b00e02 --- /dev/null +++ b/doc/user/project/issues/img/similar_issues.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index d71273ba970..5a3ac9c175b 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -142,16 +142,29 @@ to find out more about this feature. With [GitLab Starter](https://about.gitlab.com/pricing/), you can also create various boards per project with [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards). +### Import Issues from CSV + +You can import a CSV file containing issue titles and descriptions to create +a batch of issues simultaneously. + +When you navigate to the Issues list page, an import button is displayed. + +For further details, see [Importing issues from CSV](csv_import.md) + ### External Issue Tracker Alternatively to GitLab's built-in Issue Tracker, you can also use an [external tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, or Bugzilla. -### Issue's API +### Issue API -Read through the [API documentation](../../../api/issues.md). +See the [API documentation](../../../api/issues.md). ### Bulk editing issues -Find out about [bulk editing issues](../../project/bulk_editing.md). +See the [bulk editing issues](../../project/bulk_editing.md) page. + +### Similar issues + +See the [similar issues](similar_issues.md) page. diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index 631f511b5fa..d78721f8658 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -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/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md new file mode 100644 index 00000000000..e90ecd88ec6 --- /dev/null +++ b/doc/user/project/issues/similar_issues.md @@ -0,0 +1,16 @@ +# Similar issues + +> [Introduced][ce-22866] in GitLab 11.6. + +Similar issues suggests issues that are similar when new issues are being created. +This features requires [GraphQL] to be enabled. + + + +You can see the similar issues when typing in the title in the new issue form. +This searches both titles and descriptions across all issues the user has access +to in the current project. It then displays the first 5 issues sorted by most +recently updated. + +[GraphQL]: ../../../api/graphql/index.md +[ce-22866]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866 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/members/index.md b/doc/user/project/members/index.md index 2c2e8e2d556..2a490e3fd7f 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -77,7 +77,7 @@ GitLab users to the project. Once done, hit **Add users to project** and watch that there is a new member with the e-mail address we used above. From there on, you can resend the -invitation, change their access level or even delete them. +invitation, change their access level, or even delete them.  diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 859ac92ef89..da6e6b5fd3a 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,20 +1,72 @@ # Allow collaboration on merge requests across forks -> [Introduced][ce-17395] in GitLab 10.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395) + in GitLab 10.6. + +When a user opens a merge request from a fork, they are given the option to allow +upstream members to collaborate with them on the source branch. This allows +the members of the upstream project to make small fixes or rebase branches +before merging, reducing the back and forth of accepting external contributions. This feature is available for merge requests across forked projects that are -publicly accessible. It makes it easier for members of projects to -collaborate on merge requests across forks. +publicly accessible. When enabled for a merge request, members with merge access to the target branch of the project will be granted write permissions to the source branch of the merge request. +## Enabling commit edits from upstream members + The feature can only be enabled by users who already have push access to the -source project, and only lasts while the merge request is open. +source project and only lasts while the merge request is open. Once enabled, +upstream members will also be able to retry the pipelines and jobs of the +merge request: + +1. Enable the contribution while creating or editing a merge request. + +  + +1. Once the merge request is created, you'll see that commits from members who + can merge to the target branch are allowed. + +  + +## Pushing to the fork as the upstream member + +If the creator of the merge request has enabled contributions from upstream +members, you can push directly to the branch of the forked repository. + +Assuming that: + +- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. +- The branch of the merge request is `update-docs`. + +Here's how the process would look like: + +1. First, you need to get the changes that the merge request has introduced. + Click the **Check out branch** button that has some pre-populated + commands that you can run. + +  + +1. Use the copy to clipboard button to copy the first command and paste them + in your terminal: + + ```sh + git fetch git@gitlab.com:thedude/awesome-project.git update-docs + git checkout -b thedude-awesome-project-update-docs FETCH_HEAD + ``` + + This will fetch the branch of the forked project and then create a local branch + based off the fetched branch. -Enable this functionality while creating or editing a merge request: +1. Make any changes you want and commit. +1. Push to the forked project: - + ```sh + git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs + ``` -[ce-17395]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395 + Note the colon (`:`) between the two branches. The above command will push the + local branch `thedude-awesome-project-update-docs` to the + `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png Binary files differindex 3c81e4c27b8..e40e8a6b11c 100644 --- a/doc/user/project/merge_requests/img/allow_collaboration.png +++ b/doc/user/project/merge_requests/img/allow_collaboration.png diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png Binary files differnew file mode 100644 index 00000000000..4ba4c84c8c5 --- /dev/null +++ b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png diff --git a/doc/user/project/merge_requests/img/checkout_button.png b/doc/user/project/merge_requests/img/checkout_button.png Binary files differnew file mode 100644 index 00000000000..9850795c9b4 --- /dev/null +++ b/doc/user/project/merge_requests/img/checkout_button.png 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..c2455c2d1e5 --- /dev/null +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differindex 610f0b3d0c1..5cb2afaf976 100644 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ b/doc/user/project/merge_requests/img/create_from_email.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 differindex 40913718385..81878709487 100644 --- a/doc/user/project/merge_requests/img/filter_wip_merge_requests.png +++ 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 3b3bf88df31..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..ce1d6bab536 --- /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 f9ebf277125..b4f5a72e148 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: @@ -76,10 +76,10 @@ You can [search and filter the results](../../search/index.md#issues-and-merge-r  -## Removing the source branch +## Deleting the source branch -When creating a merge request, select the "Remove source branch when merge -request accepted" option and the source branch will be removed when the merge +When creating a merge request, select the "Delete source branch when merge +request accepted" option and the source branch will be deleted when the merge request is merged. This option is also visible in an existing merge request next to the merge @@ -87,10 +87,19 @@ request button and can be selected/deselected before merging. It's only visible to users with [Maintainer permissions](../../permissions.md) in the source project. If the user viewing the merge request does not have the correct permissions to -remove the source branch and the source branch is set for removal, the merge -request widget will show the "Removes source branch" text. +delete the source branch and the source branch is set for deletion, the merge +request widget will show the "Deletes source branch" text. - + + +## Allow collaboration on merge requests across forks + +When a user opens a merge request from a fork, they are given the option to allow +upstream maintainers to collaborate with them on the source branch. This allows +the maintainers of the upstream project to make small fixes or rebase branches +before merging, reducing the back and forth of accepting community contributions. + +[Learn more about allowing upstream members to push to forks.](allow_collaboration.md) ## Authorization for merge requests @@ -141,6 +150,25 @@ 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. + + + +## Suggest changes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. + +As a reviewer, you can add suggestions to change the content in +merge request discussions, and users with appropriate [permission](../../permissions.md) +can easily apply them to the codebase directly from the UI. Read +through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes) +to learn more. + ## Resolve conflicts When a merge request has conflicts, GitLab may provide the option to resolve @@ -150,9 +178,9 @@ those conflicts in the GitLab UI. ## Create new merge requests by email -*This feature needs [incoming email](../../../administration/incoming_email.md) +_This feature needs [incoming email](../../../administration/incoming_email.md) to be configured by a GitLab administrator to be available for CE/EE users, and -it's available on GitLab.com.* +it's available on GitLab.com._ You can create a new merge request by sending an email to a user-specific email address. The address can be obtained on the merge requests page by clicking on @@ -164,11 +192,36 @@ will be used as the merge request description. You need this feature. If it's not enabled to your instance, you may ask your GitLab administrator to do so. +This is a private email address, generated just for you. **Keep it to yourself** +as anyone who gets ahold of it can create issues or merge requests as if they were you. +You can add this address to your contact list for easy access. +  +_In GitLab 11.7, we updated the format of the generated email address. +However the older format is still supported, allowing existing aliases +or contacts to continue working._ + +### 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 +258,10 @@ have been marked as a **Work In Progress**. ## Merge request diff file navigation -The diff view has a file tree for file navigation. As you scroll through -diffs with a large number of files, you can easily jump to any changed file -using the file tree. +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.  @@ -230,12 +284,83 @@ you can preview the changes submitted to a feature-branch through a merge reques in a per-branch basis. No need to checkout the branch, install and preview locally; all your changes will be available to preview by anyone with the Review Apps link. -[Read more about Review Apps.](../../../ci/review_apps/index.md) +With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). + +## Pipelines for merge requests + +When a developer updates a merge request, a pipeline should quickly report back +its result to the developer, but often pipelines take long time to complete +because general branch pipelines contain unnecessary jobs from the merge request standpoint. +You can customize a specific pipeline structure for merge requests in order to +speed the cycle up by running only important jobs. + +Learn more about [pipelines for merge requests](../../../ci/merge_request_pipelines/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/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 2ec423dcf70..1b57331dbe7 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -18,7 +18,7 @@ Into a single commit on merge: ![A squashed commit followed by a merge commit][squashed-commit] -The squashed commit's commit message is the merge request title. And note that +The squashed commit's commit message is the merge request title. And note that the squashed commit is still followed by a merge commit, as the merge method for this example repository uses a merge commit. Squashing also works with the fast-forward merge strategy, see @@ -30,7 +30,7 @@ details. When working on a feature branch, you sometimes want to commit your current progress, but don't really care about the commit messages. Those 'work in progress commits' don't necessarily contain important information and as such -you'd rather not include them in your target branch. +you'd rather not include them in your target branch. With squash and merge, when the merge request is ready to be merged, all you have to do is enable squashing before you press merge to join @@ -56,9 +56,9 @@ This can then be overridden at the time of accepting the merge request: The squashed commit has the following metadata: -* Message: the title of the merge request. -* Author: the author of the merge request. -* Committer: the user who initiated the squash. +- Message: the title of the merge request. +- Author: the author of the merge request. +- Committer: the user who initiated the squash. ## Squash and fast-forward merge 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..d7a1a69f29d 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. @@ -238,6 +238,6 @@ test: [triggers]: ../../ci/triggers/README.md [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update [workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse -[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables +[jobenv]: ../../ci/variables/README.md#predefined-environment-variables [2fa]: ../profile/account/two_factor_authentication.md [pat]: ../profile/personal_access_tokens.md diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md new file mode 100644 index 00000000000..fe4b36062f7 --- /dev/null +++ b/doc/user/project/operations/error_tracking.md @@ -0,0 +1,30 @@ +# Error Tracking + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/169) in GitLab 11.8. + +Error tracking allows developers to easily discover and view the errors that their application may be generating. By surfacing error information where the code is being developed, efficiency and awareness can be increased. + +## Sentry error tracking + +[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab itself. + +### Deploying Sentry + +You may sign up to the cloud hosted <https://sentry.io> or deploy your own [on-premise instance](https://docs.sentry.io/server/installation/). + +### Enabling Sentry + +GitLab provides an easy way to connect Sentry to your project: + +1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. +1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. +1. Navigate to your project’s **Settings > Operations** and provide the Sentry API URL and auth token. +1. Ensure that the 'Active' checkbox is set. +1. Click **Save changes** for the changes to take effect. +1. You can now visit **Operations > Error Tracking** in your project's sidebar to [view a list](#error-tracking-list) of Sentry errors. + +## Error Tracking List + +The Error Tracking list may be found at **Operations > Error Tracking** in your project's sidebar. + + diff --git a/doc/user/project/operations/img/error_tracking_list.png b/doc/user/project/operations/img/error_tracking_list.png Binary files differnew file mode 100644 index 00000000000..aa0f9867fdb --- /dev/null +++ b/doc/user/project/operations/img/error_tracking_list.png diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 290dfa5af84..595241b2cba 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -85,6 +85,12 @@ and a project within this group is called `blog`. Your project URL is `https://gitlab.com/websites/blog/`. Once you enable GitLab Pages for this project, the site will live under `https://websites.gitlab.io/blog/`. +- You created a group for your engineering department called `engineering`, +a subgroup for all your documentation websites called `docs`, +and a project within this subgroup is called `workflows`. Your project +URL is `https://gitlab.com/engineering/docs/workflows/`. Once you enable +GitLab Pages for this project, the site will live under +`https://engineering.gitlab.io/docs/workflows`. #### User and Group Websites @@ -97,9 +103,7 @@ will be published under `https://john.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://websites.gitlab.io`. ->**Note:** -GitLab Pages [does **not** support subgroups](../../group/subgroups/index.md#limitations). -You can only create the highest level group website. +> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. **General example:** diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index e1eede8bbed..cea9628966d 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) @@ -234,26 +234,25 @@ reiterating the importance of HTTPS. ## Issuing Certificates -GitLab Pages accepts [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) certificates issued by -[Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority) -and self-signed certificates. Of course, -[you'd rather issue a certificate than generate a self-signed](https://en.wikipedia.org/wiki/Self-signed_certificate), -for security reasons and for having browsers trusting your -site's certificate. +GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by +[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +for public websites for security reasons and to ensure that browsers trust your site's certificate. -There are several different kinds of certificates, each one -with certain security level. A static personal website will +There are various kinds of certificates, each one +with a certain security level. A static personal website will not require the same security level as an online banking web app, -for instance. There are a couple Certificate Authorities that +for instance. + +There are some certificate authorities that offer free certificates, aiming to make the internet more secure to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), which issues certificates trusted by most of browsers, it's open -source, and free to use. Please read through this tutorial to -understand [how to secure your GitLab Pages website with Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/). +source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md). -With the same popularity, there are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), +Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). -Their certs are valid up to 15 years. Read through the tutorial on +Their certs are valid up to 15 years. See the tutorial on [how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). ### Adding certificates to your project diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png Binary files differindex daaf760ec08..a534ae29e0f 100644 --- a/doc/user/project/pages/img/icons/click.png +++ 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 differindex a12da1b5e8c..f37f8f361d1 100644 --- a/doc/user/project/pages/img/icons/cogs.png +++ 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 differindex e2c9577e7ce..8a3aa46eb37 100644 --- a/doc/user/project/pages/img/icons/fork.png +++ 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 differindex 3b8f8f6863e..ae455033e94 100644 --- a/doc/user/project/pages/img/icons/free.png +++ 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 differindex 1c1f0b4457b..f4c35c84112 100644 --- a/doc/user/project/pages/img/icons/lock.png +++ 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 differindex 7b99d430eef..8bad059a74c 100644 --- a/doc/user/project/pages/img/icons/monitor.png +++ 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 differindex ab5ae11310c..377eeb4edc6 100644 --- a/doc/user/project/pages/img/icons/terminal.png +++ b/doc/user/project/pages/img/icons/terminal.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 60144fa1971..ce4fccdaff3 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -166,11 +166,11 @@ with Pages, read through this series: 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 with SSL/TLS certificates. You can read the following +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/) (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps) +- [Let's Encrypt](lets_encrypt_for_gitlab_pages.md) ## Advanced use diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index fe4d15adfa1..2bb6fcd9d74 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -38,6 +38,7 @@ be served on. | Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | | Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | | Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| +| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| > **Warning:** > There are some known [limitations](#limitations) regarding namespaces served @@ -177,7 +178,7 @@ Supposed your repository contained the following files: ``` ├── index.html ├── css -│ └── main.css +│ └── main.css └── js └── main.js ``` @@ -332,7 +333,7 @@ public/ │ └ index.html.gz │ ├── css/ -│ └─┬ main.css +│ └─┬ main.css │ └ main.css.gz │ └── js/ @@ -441,6 +442,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`), @@ -452,8 +495,8 @@ don't redirect HTTP to HTTPS. [rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC" -GitLab Pages [does **not** support subgroups](../../group/subgroups/index.md#limitations). -You can only create the highest level group website. +GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). +You can only create the highest-level group website. ## Redirects in GitLab Pages diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md new file mode 100644 index 00000000000..f639188684b --- /dev/null +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -0,0 +1,158 @@ +--- +description: "How to secure GitLab Pages websites with Let's Encrypt." +--- + +# Let's Encrypt for GitLab Pages + +If you have a GitLab Pages website served under your own domain, +you might want to secure it with a SSL/TSL certificate. + +[Let's Encrypt](https://letsencrypt.org) is a free, automated, and +open source Certificate Authority. + +## Requirements + +To follow along with this tutorial, we assume you already have: + +- Created a [project](getting_started_part_two.md) in GitLab which + contains your website's source code. +- Acquired a domain (`example.com`) and added a [DNS entry](getting_started_part_three.md#dns-records) + pointing it to your Pages website. +- [Added your domain to your Pages project](getting_started_part_three.md#add-your-custom-domain-to-gitlab-pages-settings) + and verified your ownership. +- Cloned your project into your computer. +- Your website up and running, served under HTTP protocol at `http://example.com`. + +## Obtaining a Let's Encrypt certificate + +Once you have the requirements addressed, follow the instructions +below to learn how to obtain the certificate. + +NOTE: **Note:** +The instructions below were tested on macOS Mojave. For other +operating systems the steps might be slightly different. Follow the +[CertBot instructions](https://certbot.eff.org/) according to your OS. + +1. On your computer, open a terminal and navigate to your repository's + root directory: + + ```bash + cd path/to/dir + ``` + +1. Install CertBot (the tool Let's Encrypt uses to issue certificates): + + ```bash + brew install certbot + ``` + +1. Request a certificate for your domain (`example.com`) and + provide an email account (`your@email.com`) to receive notifications: + + ```bash + sudo certbot certonly -a manual -d example.com --email your@email.com + ``` + + Alternatively, you can register without adding an e-mail account, + but you won't be notified about the certificate expiration's date: + + ```bash + sudo certbot certonly -a manual -d example.com --register-unsafely-without-email + ``` + + TIP: **Tip:** + Read through CertBot's documentation on their + [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). + +1. You'll be prompted with a message to agree with their terms. + Press `A` to agree and `Y` to let they log your IP. + + CertBot will then prompt you with the following message: + + ```bash + Create a file containing just this data: + + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + + And make it available on your web server at this URL: + + http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP + + Press Enter to Continue + ``` + +1. **Do not press Enter yet.** Let's Encrypt will need to verify your + domain ownership before issuing the certificate. To do so, create 3 + consecutive directories under your website's root: + `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` + and add to the last folder an `index.html` file containing the content + referred on the previous prompt message: + + ```bash + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + ``` + + Note that this file needs to be accessed under + `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` + to allow Let's Encrypt to verify the ownership of your domain, + therefore, it needs to be part of the website content under the + repo's [`public`](index.md#how-it-works) folder. + +1. Add, commit, and push the file into your repo in GitLab. Once the pipeline + passes, press **Enter** on your terminal to continue issuing your + certificate. CertBot will then prompt you with the following message: + + ```bash + Waiting for verification... + Cleaning up challenges + + IMPORTANT NOTES: + - Congratulations! Your certificate and chain have been saved at: + /etc/letsencrypt/live/example.com/fullchain.pem + Your key file has been saved at: + /etc/letsencrypt/live/example.com/privkey.pem + Your cert will expire on 2019-03-12. To obtain a new or tweaked + version of this certificate in the future, simply run certbot + again. To non-interactively renew *all* of your certificates, run + "certbot renew" + - If you like Certbot, please consider supporting our work by: + + Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate + Donating to EFF: https://eff.org/donate-le + ``` + +## Add your certificate to GitLab Pages + +Now that your certificate has been issued, let's add it to your Pages site: + +1. Back at GitLab, navigate to your project's **Settings > Pages**, + find your domain and click **Details** and **Edit** to add your certificate. +1. From your terminal, copy and paste the certificate into the first field + **Certificate (PEM)**: + + ```bash + sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy + ``` + +1. Copy and paste the public key into the second field **Key (PEM)**: + + ```bash + sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy + ``` + +1. Click **Save changes** to apply them to your website. +1. Wait a few minutes for DNS propagation. +1. Visit your website at `https://example.com`. + +To force `https` connections on your site, navigate to your +project's **Settings > Pages** and check **Force domains with SSL +certificates to use HTTPS**. + +## Renewal + +Let's Encrypt certificates expire every 90 days and you'll have to +renew them periodically. To renew all your certificates at once, run: + +```bash +sudo certbot renew +``` diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index 9daacc37994..ec8b8444d99 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -3,7 +3,7 @@ > **Notes**: > - This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. > - In 9.2, the feature was [renamed to Pipeline Schedule][ce-10853]. -> - Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). +> - Cron notation is parsed by [Fugit](https://github.com/floraison/fugit). Pipeline schedules can be used to run a pipeline at specific intervals, for example every month on the 22nd for a certain branch. @@ -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/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 15eacc48dfe..bb9b4238ee9 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -1,7 +1,7 @@ # Pipelines settings To reach the pipelines settings navigate to your project's -**Settings ➔ CI/CD**. +**Settings > CI/CD**. The following settings can be configured per project. @@ -10,14 +10,14 @@ The following settings can be configured per project. With Git strategy, you can choose the default way your repository is fetched from GitLab in a job. -There are two options: +There are two options. Using: -- Using `git clone` which is slower since it clones the repository from scratch +- `git clone`, which is slower since it clones the repository from scratch for every job, ensuring that the project workspace is always pristine. -- Using `git fetch` which is faster as it re-uses the project workspace (falling +- `git fetch`, which is faster as it re-uses the project workspace (falling back to clone if it doesn't exist). -The default Git strategy can be overridden by the [GIT_STRATEGY variable][var] +The default Git strategy can be overridden by the [GIT_STRATEGY variable](../../../ci/yaml/README.md#git-strategy) in `.gitlab-ci.yml`. ## Timeout @@ -29,14 +29,14 @@ if the job surpasses the threshold, it is marked as failed. ### Timeout overriding on Runner level -> - [Introduced][ce-17221] in GitLab 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17221) in GitLab 10.7. Project defined timeout (either specific timeout set by user or the default -60 minutes timeout) may be [overridden on Runner level][timeout overriding]. +60 minutes timeout) may be [overridden on Runner level](../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner). ## Custom CI config path -> - [Introduced][ce-12509] in GitLab 9.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12509) in GitLab 9.4. By default we look for the `.gitlab-ci.yml` file in the project's root directory. If you require a different location **within** the repository, @@ -45,10 +45,10 @@ this filepath should be **relative** to the root. Here are some valid examples: -> * .gitlab-ci.yml -> * .my-custom-file.yml -> * my/path/.gitlab-ci.yml -> * my/path/.my-custom-file.yml +- `.gitlab-ci.yml` +- `.my-custom-file.yml` +- `my/path/.gitlab-ci.yml` +- `my/path/.my-custom-file.yml` ## Test coverage parsing @@ -59,7 +59,7 @@ job log using a regular expression. In the pipelines settings, search for the  Leave blank if you want to disable it or enter a ruby regular expression. You -can use http://rubular.com to test your regex. +can use <http://rubular.com> to test your regex. If the pipeline succeeds, the coverage is shown in the merge request widget and in the jobs table. @@ -79,28 +79,28 @@ project setting under your project's **Settings > CI/CD > General pipelines sett If **Public pipelines** is enabled (default): -- for **public** projects, anyone can view the pipelines and access the job details - (output logs and artifacts) -- for **internal** projects, any logged in user can view the pipelines +- For **public** projects, anyone can view the pipelines and access the job details + (output logs and artifacts). +- For **internal** projects, any logged in user can view the pipelines and access the job details - (output logs and artifacts) -- for **private** projects, any member (guest or higher) can view the pipelines + (output logs and artifacts). +- For **private** projects, any member (guest or higher) can view the pipelines and access the job details - (output logs and artifacts) + (output logs and artifacts). If **Public pipelines** is disabled: -- for **public** projects, anyone can view the pipelines, but only members - (reporter or higher) can access the job details (output logs and artifacts) -- for **internal** projects, any logged in user can view the pipelines, - but only members (reporter or higher) can access the job details (output logs - and artifacts) -- for **private** projects, only members (reporter or higher) - can view the pipelines and access the job details (output logs and artifacts) +- For **public** projects, anyone can view the pipelines, but only members + (reporter or higher) can access the job details (output logs and artifacts). +- For **internal** projects, any logged in user can view the pipelines. + However, only members (reporter or higher) can access the job details (output logs + and artifacts). +- For **private** projects, only members (reporter or higher) + can view the pipelines and access the job details (output logs and artifacts). ## Auto-cancel pending pipelines -> [Introduced][ce-9362] in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9362) in GitLab 9.1. If you want to auto-cancel all pending non-HEAD pipelines on branch, when new pipeline will be created (after your git push or manually from UI), @@ -132,19 +132,19 @@ Depending on the status of your job, a badge can have the following values: You can access a pipeline status badge image using the following link: -``` +```text https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg ``` ### Test coverage report badge -GitLab makes it possible to define the regular expression for [coverage report], +GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing), that each job log will be matched against. This means that each job in the pipeline can have the test coverage percentage value defined. The test coverage badge can be accessed using following link: -``` +```text https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` @@ -157,13 +157,28 @@ into your `README.md`:  ``` -### Environment Variables +### Badge styles -[Environment variables](../../../ci/variables/README.html#variables) can be set in an environment to be available to a runner. +Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Currently two styles are available: + +#### Flat (default) + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat +``` + + -[var]: ../../../ci/yaml/README.md#git-strategy -[coverage report]: #test-coverage-parsing -[timeout overriding]: ../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner -[ce-9362]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9362 -[ce-12509]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12509 -[ce-17221]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17221 +#### Flat square + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30120) in GitLab 11.8. + +```text +https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square +``` + + + +## Environment Variables + +[Environment variables](../../../ci/variables/README.html#variables) can be set in an environment to be available to a runner. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index c2f53540089..85a03d125dd 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -24,6 +24,7 @@ discussions, and descriptions: | `/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) | ✓ | ✓ | @@ -52,6 +53,7 @@ discussions, and descriptions: | `/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 diff --git a/doc/user/project/releases.md b/doc/user/project/releases.md new file mode 100644 index 00000000000..737842962a9 --- /dev/null +++ b/doc/user/project/releases.md @@ -0,0 +1 @@ +This document was moved to [another location](releases/index.md). diff --git a/doc/user/project/releases/img/releases.png b/doc/user/project/releases/img/releases.png Binary files differnew file mode 100644 index 00000000000..f8b1b7305ad --- /dev/null +++ b/doc/user/project/releases/img/releases.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md new file mode 100644 index 00000000000..00a4f6c6a6b --- /dev/null +++ b/doc/user/project/releases/index.md @@ -0,0 +1,62 @@ +# Releases + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. + +It's typical to create a [Git tag](../../../university/training/topics/tags.md) at +the moment of release to introduce a checkpoint in your source code +history, but in most cases your users will need compiled objects or other +assets output by your CI system to use them, not just the raw source +code. + +GitLab's **Releases** are a way to track deliverables in your project. Consider them +a snapshot in time of the source, build output, and other metadata or artifacts +associated with a released version of your code. + +At the moment, you can create Release entries via the [Releases API](../../../api/releases/index.md); +we recommend doing this as one of the last steps in your CI/CD release pipeline. + +## Getting started with Releases + +Start by giving a [description](#release-description) to the Release and +including its [assets](#release-assets), as follows. + +### Release description + +Every Release has a description. You can add any text you like, but we recommend +including a changelog to describe the content of your release. This will allow +your users to quickly scan the differences between each one you publish. + +NOTE: **Note:** +[Git's tagging messages](https://git-scm.com/book/en/v2/Git-Basics-Tagging) and +Release descriptions are unrelated. Description supports [markdown](../../markdown.md). + +### Release assets + +You can currently add the following types of assets to each Release: + +- [Source code](#source-code): state of the repo at the time of the Release +- [Links](#links): to content such as built binaries or documentation + +GitLab will support more asset types in the future, including objects such +as pre-built packages, compliance/security evidence, or container images. + +#### Source code + +GitLab automatically generate `zip`, `tar.gz`, `tar.bz2` and `tar` +archived source code from the given Git tag. These are read-only assets. + +#### Links + +A link is any URL which can point to whatever you like; documentation, built +binaries, or other related materials. These can be both internal or external +links from your GitLab instance. + +NOTE: **NOTE** +You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md) + +## Releases list + +Navigate to **Project > Releases** in order to see the list of releases for a given +project. + + 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 differindex c4364ef39f4..5dc7eccf189 100644 --- a/doc/user/project/repository/branches/img/branch_filter_search_box.png +++ 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 e1d8345f415..f05554ffc5b 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -2,16 +2,17 @@ Read through GiLab's branching documentation: -- [Create a branch](../web_editor.md#create-a-new-branch) -- [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) +- [Create a branch](../web_editor.md#create-a-new-branch). +- [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: -- [GitLab Flow](../../../../university/training/gitlab_flow.md#gitlab-flow): use the best of GitLab for your branching strategies -- [Getting started with Git](../../../../topics/git/index.md) and GitLab +- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. +- [GitLab Flow](../../../../university/training/gitlab_flow.md#gitlab-flow). Use the best of GitLab for your branching strategies. +- [Getting started with Git](../../../../topics/git/index.md) and GitLab. ## Default branch @@ -30,21 +31,20 @@ 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. - ## Branch filter search box -> [Introduced][https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166] in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5.  @@ -57,6 +57,3 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi - `^feature` will only match branch names that begin with 'feature'. - `feature$` will only match branch names that end with 'feature'. - -[ce-6449]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449 "Add button to delete all merged branches" -[protected]: ../../protected_branches.md diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index c6239c8e41c..c7e20f01a75 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -4,7 +4,7 @@ NOTE: **Note:** The term GPG is used for all OpenPGP/PGP/GPG related material and implementations. -> - [Introduced][ce-9546] in GitLab 9.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5. > - Subkeys support was added in GitLab 10.1. GitLab can show whether a commit is verified or not when signed with a GPG key. @@ -36,30 +36,22 @@ to be met: ## Generating a GPG key -> **Notes:** -> - If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in -> the following commands. -> - If Git is using `gpg` and you get errors like `secret key not available` or -> `gpg: signing failed: secret key not available`, run the following command to -> change to `gpg2`: -> -> ``` -> git config --global gpg.program gpg2 -> ``` - If you don't already have a GPG key, the following steps will help you get started: -1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system -1. Generate the private/public key pair with the following command: +1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system. + If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in + the following commands. +1. Generate the private/public key pair with the following command, which will + spawn a series of questions: ```sh 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`_ - This will spawn a series of questions. + NOTE: **Note:** + In some cases like Gpg4win on Windows and other macOS versions, the command + here may be `gpg --gen-key`. 1. The first question is which algorithm can be used. Select the kind you want or press <kbd>Enter</kbd> to choose the default (RSA and RSA): @@ -109,10 +101,10 @@ started: GnuPG needs to construct a user ID to identify your key. Real name: Mr. Robot - Email address: mr@robot.sh + Email address: <your_email> Comment: You selected this USER-ID: - "Mr. Robot <mr@robot.sh>" + "Mr. Robot <your_email>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O ``` @@ -121,10 +113,10 @@ started: 1. Use the following command to list the private GPG key you just created: ``` - gpg --list-secret-keys --keyid-format LONG mr@robot.sh + gpg --list-secret-keys --keyid-format LONG <your_email> ``` - Replace `mr@robot.sh` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: @@ -132,7 +124,7 @@ started: ``` sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <mr@robot.sh> + uid [ultimate] Mr. Robot <your_email> ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` @@ -146,7 +138,7 @@ started: ## Adding a GPG key to your account ->**Note:** +NOTE: **Note:** Once you add a key, you cannot edit it, only remove it. In case the paste didn't work, you'll have to remove the offending key and re-add it. @@ -174,11 +166,11 @@ key to use. 1. Use the following command to list the private GPG key you just created: - ``` - gpg --list-secret-keys --keyid-format LONG mr@robot.sh + ```sh + gpg --list-secret-keys --keyid-format LONG <your_email> ``` - Replace `mr@robot.sh` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: @@ -186,18 +178,27 @@ key to use. ``` sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <mr@robot.sh> + uid [ultimate] Mr. Robot <your_email> ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] ``` 1. Tell Git to use that key to sign the commits: - ``` + ```sh git config --global user.signingkey 30F2B65B9246B6CA ``` Replace `30F2B65B9246B6CA` with your GPG key ID. + +1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` + or `gpg: signing failed: secret key not available`, run the following command to + change to `gpg2`: + + ```sh + git config --global gpg.program gpg2 + ``` + ## Signing commits After you have [created your GPG key](#generating-a-gpg-key) and [added it to @@ -261,4 +262,7 @@ To remove a GPG key from your account: 1. Navigate to the **GPG keys** tab. 1. Click on the trash icon besides the GPG key you want to delete. -[ce-9546]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546 +## Rejecting commits that are not signed **[PREMIUM]** + +You can configure your project to reject commits that aren't GPG-signed +via [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html). diff --git a/doc/user/project/repository/img/repository_cleanup.png b/doc/user/project/repository/img/repository_cleanup.png Binary files differnew file mode 100644 index 00000000000..bda40d3e193 --- /dev/null +++ b/doc/user/project/repository/img/repository_cleanup.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index beff4b89424..fac5975a0dc 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -29,7 +29,7 @@ You can either use the user interface (UI), or connect your local computer with GitLab [through the command line](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). To configure [GitLab CI/CD](../../../ci/README.md) to build, test, and deploy -you code, add a file called [.`gitlab-ci.yml`](../../../ci/quick_start/README.md) +you code, add a file called [`.gitlab-ci.yml`](../../../ci/quick_start/README.md) to your repository's root. **From the user interface:** @@ -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 @@ -165,7 +205,7 @@ minutes.  -Not all files are detected, among others; documentation, +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. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index d534c8cbe4b..672567a8d7d 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -1,43 +1,105 @@ # Reducing the repository size using Git A GitLab Enterprise Edition administrator can set a [repository size limit][admin-repo-size] -which will prevent you to exceed it. +which will prevent you from exceeding it. When a project has reached its size limit, you will not be able to push to it, create a new merge request, or merge existing ones. You will still be able to create new issues, and clone the project though. Uploading LFS objects will also be denied. -In order to lift these restrictions, the administrator of the GitLab instance -needs to increase the limit on the particular project that exceeded it or you -need to instruct Git to rewrite changes. - If you exceed the repository size limit, your first thought might be to remove -some data, make a new commit and push back to the repository. Unfortunately, -it's not so easy and that workflow won't work. Deleting files in a commit doesn't -actually reduce the size of the repo since the earlier commits and blobs are -still around. What you need to do is rewrite history with Git's -[`filter-branch` option][gitscm]. +some data, make a new commit and push back to the repository. Perhaps you can +move some blobs to LFS, or remove some old dependency updates from history. +Unfortunately, it's not so easy and that workflow won't work. Deleting files in +a commit doesn't actually reduce the size of the repo since the earlier commits +and blobs are still around. What you need to do is rewrite history with Git's +[`filter-branch` option][gitscm], or a tool like the [BFG Repo-Cleaner][bfg]. Note that even with that method, until `git gc` runs on the GitLab side, the -"removed" commits and blobs will still be around. And if a commit was ever -included in an MR, or if a build was run for a commit, or if a user commented -on it, it will be kept around too. So, in these cases the size will not decrease. - -The only fool proof way to actually decrease the repository size is to prune all -the unneeded stuff locally, and then create a new project on GitLab and start -using that instead. +"removed" commits and blobs will still be around. You also need to be able to +push the rewritten history to GitLab, which may be impossible if you've already +exceeded the maximum size limit. -With that being said, you can try reducing your repository size with the -following method. - -## Using `git filter-branch` to purge files +In order to lift these restrictions, the administrator of the GitLab instance +needs to increase the limit on the particular project that exceeded it, so it's +always better to spot that you're approaching the limit and act proactively to +stay underneath it. If you hit the limit, and your admin can't - or won't - +temporarily increase it for you, your only option is to prune all the unneeded +stuff locally, and then create a new project on GitLab and start using that +instead. + +If you can continue to use the original project, we recommend [using the +BFG Repo-Cleaner](#using-the-bfg-repo-cleaner). It's faster and simpler than +`git filter-branch`, and GitLab can use its account of what has changed to clean +up its own internal state, maximizing the space saved. > **Warning:** > Make sure to first make a copy of your repository since rewriting history will > purge the files and information you are about to delete. Also make sure to > inform any collaborators to not use `pull` after your changes, but use `rebase`. +> **Warning:** +> This process is not suitable for removing sensitive data like password or keys +> from your repository. Information about commits, including file content, is +> cached in the database, and will remain visible even after they have been +> removed from the repository. + +## Using the BFG Repo-Cleaner + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19376) in GitLab 11.6. + +1. [Install BFG](https://rtyley.github.io/bfg-repo-cleaner/). + +1. Navigate to your repository: + + ``` + cd my_repository/ + ``` + +1. Change to the branch you want to remove the big file from: + + ``` + git checkout master + ``` + +1. Create a commit removing the large file from the branch, if it still exists: + + ``` + git rm path/to/big_file.mpg + git commit -m 'Remove unneeded large file' + ``` + +1. Rewrite history: + + ``` + bfg --delete-files path/to/big_file.mpg + ``` + + An object map file will be written to `object-id-map.old-new.txt`. Keep it + around - you'll need it for the final step! + +1. Force-push the changes to GitLab: + + ``` + git push --force-with-lease origin master + ``` + + If this step fails, someone has changed the `master` branch while you were + rewriting history. You could restore the branch and re-run BFG to preserve + their changes, or use `git push --force` to overwrite their changes. + +1. Navigate to **Project > Settings > Repository > Repository Cleanup**: + +  + + Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. + This will remove any internal git references to the old commits, and run + `git gc` against the repository. You will receive an email once it has + completed. + +## Using `git filter-branch` + 1. Navigate to your repository: ``` @@ -70,11 +132,6 @@ following method. Your repository should now be below the size limit. -> **Note:** -> As an alternative to `filter-branch`, you can use the `bfg` tool with a -> command like: `bfg --delete-files path/to/big_file.mpg`. Read the -> [BFG Repo-Cleaner][bfg] documentation for more information. - [admin-repo-size]: https://docs.gitlab.com/ee/user/admin_area/settings/account_and_limit_settings.html#repository-size-limit [bfg]: https://rtyley.github.io/bfg-repo-cleaner/ [gitscm]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#The-Nuclear-Option:-filter-branch diff --git a/doc/user/project/settings/img/general_settings.png b/doc/user/project/settings/img/general_settings.png Binary files differindex 96f5b84871f..4ff6fff5ca3 100644 --- a/doc/user/project/settings/img/general_settings.png +++ b/doc/user/project/settings/img/general_settings.png 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/import_export.md b/doc/user/project/settings/import_export.md index f94671fcf87..89008fd15b9 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -24,6 +24,10 @@ > Otherwise, a supplementary comment is left to mention the original author and > the MRs, notes or issues will be owned by the importer. > - Control project Import/Export with the [API](../../../api/project_import_export.md). +> - If an imported project contains merge requests originated from forks, +> then new branches associated with such merge requests will be created +> within a project during the import/export. Thus, the number of branches +> in the exported project could be bigger than in the original project. Existing projects running on any GitLab instance or GitLab.com can be exported with all their related data and be moved into a new GitLab instance. @@ -57,7 +61,7 @@ The following items will be exported: - Project and wiki repositories - Project uploads -- Project configuration including web hooks and services +- Project configuration, including services - Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, and other project entities - LFS objects @@ -67,6 +71,7 @@ The following items will NOT be exported: - Build traces and artifacts - Container registry images - CI variables +- Webhooks - Any encrypted tokens ## Exporting a project and its data diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 084d1161633..b09a3f927d1 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -14,10 +14,12 @@ functionality of a project. ### General project settings -Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and tags: +Adjust your project's name, description, avatar, [default branch](../repository/branches/index.md#default-branch), and topics:  +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: @@ -120,3 +122,9 @@ GitLab administrators can use the admin interface to move any project to any namespace if needed. [permissions]: ../../permissions.md##project-members-permissions + +## Operations settings + +### Error Tracking + +Configure Error Tracking to discover and view [Sentry errors within GitLab](../operations/error_tracking.md). diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 9429b1268f0..55e53b865af 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,6 +1,6 @@ # Web IDE -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ee/issues/4539) [GitLab Ultimate][ee] 10.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4539) in [GitLab Ultimate][ee] 10.4. > [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/issues/44157) in 10.7. The Web IDE makes it faster and easier to contribute changes to your projects @@ -15,13 +15,34 @@ and from merge requests. ## File finder -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18323) [GitLab Core][ce] 10.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18323) in [GitLab Core][ce] 10.8. The file finder allows you to quickly open files in the current branch by 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 @@ -44,7 +65,7 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) [GitLab Core][ce] 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) in [GitLab Core][ce] 11.0. The Web IDE can be used to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed job. The status @@ -56,7 +77,7 @@ left. ## Switching merge requests -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) [GitLab Core][ce] 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0. Switching between your authored and assigned merge requests can be done without leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list @@ -65,7 +86,7 @@ switching to a different merge request. ## Switching branches -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) [GitLab Core][ce] 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2. Switching between branches of the current project repository can be done without leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list @@ -74,7 +95,7 @@ switching to a different branch. ## Client Side Evaluation -> [Introduced in](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19764) [GitLab Core][ce] 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19764) in [GitLab Core][ce] 11.2. The Web IDE can be used to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to 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..d784ba8018e --- /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..55986eedcba 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..770cef42995 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:  @@ -31,7 +31,7 @@ on the search field on the top-right of your screen: If you want to search for issues present in a specific project, navigate to a project's **Issues** tab, and click on the field **Search or filter results...**. It will -display a dropdown menu, from which you can add filters per author, assignee, milestone, +display a dropdown menu, from which you can add filters per author, assignee, milestone, label, weight, and 'my-reaction' (based on your emoji votes). When done, press **Enter** on your keyboard to filter the issues.  @@ -40,16 +40,26 @@ 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. -* Syntax - * Searches look for all the words in a query, in any order. E.g.: searching +- Syntax + - Searches look for all the words in a query, in any order. E.g.: searching issues for `display bug` will return all issues matching both those words, in any order. - * To find the exact term, use double quotes: `"display bug"` -* Limitation - * For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching + - To find the exact term, use double quotes: `"display bug"` +- Limitation + - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching issues for `included in titles` is same as `included titles`  diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 7efb6bafee7..5c9f6ffb163 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -15,7 +15,7 @@ and private. See [Public access](../public_access/public_access.md) for more inf ## Project snippets Project snippets are always related to a specific project. -See [Project's features](project/index.md#project-39-s-features) for more information. +See [Project's features](project/index.md#projects-features) for more information. ## Discover snippets 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..1e6dcb9ea08 --- /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 ec5943fd51b..3fb553280d0 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -4,9 +4,9 @@ Documentation on how to use Git LFS are under [Managing large binary files with ## Requirements -* Git LFS is supported in GitLab starting with version 8.2. -* Support for object storage, such as AWS S3, was introduced in 10.0. -* Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. +- Git LFS is supported in GitLab starting with version 8.2. +- Support for object storage, such as AWS S3, was introduced in 10.0. +- Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. ## Configuration @@ -15,9 +15,9 @@ GitLab is installed on. There are various configuration options to help GitLab server administrators: -* Enabling/disabling Git LFS support -* Changing the location of LFS object storage -* Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html) +- Enabling/disabling Git LFS support +- Changing the location of LFS object storage +- Setting up object storage supported by [Fog](http://fog.io/about/provider_documentation.html) ### Configuration for Omnibus installations @@ -229,11 +229,11 @@ See more information in [!19581](https://gitlab.com/gitlab-org/gitlab-ce/merge_r ## Known limitations -* Support for removing unreferenced LFS objects was added in 8.14 onwards. -* LFS authentications via SSH was added with GitLab 8.12 -* Only compatible with the GitLFS client versions 1.1.0 and up, or 1.0.2. -* The storage statistics currently count each LFS object multiple times for - every project linking to it +- Support for removing unreferenced LFS objects was added in 8.14 onwards. +- LFS authentications via SSH was added with GitLab 8.12. +- Only compatible with the GitLFS client versions 1.1.0 and up, or 1.0.2. +- The storage statistics currently count each LFS object multiple times for + every project linking to it. [reconfigure gitlab]: ../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: ../../administration/restart_gitlab.md#installations-from-source "How to restart GitLab" 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 d02e921fa84..da0243705aa 100644 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -21,18 +21,18 @@ Documentation for GitLab instance administrators is under [LFS administration do ## Requirements -* Git LFS is supported in GitLab starting with version 8.2 -* Git LFS must be enabled under project settings -* [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up +- Git LFS is supported in GitLab starting with version 8.2 +- Git LFS must be enabled under project settings +- [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up ## Known limitations -* Git LFS v1 original API is not supported since it was deprecated early in LFS +- Git LFS v1 original API is not supported since it was deprecated early in LFS development -* When SSH is set as a remote, Git LFS objects still go through HTTPS -* Any Git LFS request will ask for HTTPS credentials to be provided so a good Git +- When SSH is set as a remote, Git LFS objects still go through HTTPS +- Any Git LFS request will ask for HTTPS credentials to be provided so a good Git credentials store is recommended -* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have +- Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see [troubleshooting](#troubleshooting)) >**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication @@ -158,16 +158,16 @@ git lfs unlock --id=123 --force There are a couple of reasons why this error can occur: -* You don't have permissions to access certain LFS object +- You don't have permissions to access certain LFS object Check if you have permissions to push to the project or fetch from the project. -* Project is not allowed to access the LFS object +- Project is not allowed to access the LFS object LFS object you are trying to push to the project or fetch from the project is not available to the project anymore. Probably the object was removed from the server. -* Local git repository is using deprecated LFS API +- Local git repository is using deprecated LFS API ### Invalid status for `<url>` : 501 @@ -180,15 +180,15 @@ git lfs logs last If the status `error 501` is shown, it is because: -* Git LFS is not enabled in project settings. Check your project settings and +- Git LFS is not enabled in project settings. Check your project settings and enable Git LFS. -* Git LFS support is not enabled on the GitLab server. Check with your GitLab +- Git LFS support is not enabled on the GitLab server. Check with your GitLab administrator why Git LFS is not enabled on the server. See [LFS administration documentation](lfs_administration.md) for instructions on how to enable LFS support. -* Git LFS client version is not supported by GitLab server. Check your Git LFS +- Git LFS client version is not supported by GitLab server. Check your Git LFS version with `git lfs version`. Check the Git config of the project for traces of deprecated API with `git lfs -l`. If `batch = false` is set in the config, remove the line and try to update your Git LFS client. Only version 1.0.1 and diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 731c9209224..6ce789998a4 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 | @@ -127,18 +135,22 @@ Notification emails include headers that provide extra content about the notific | X-GitLab-Pipeline-Id | Only in pipeline emails, the ID of the pipeline the notification is for | | X-GitLab-Reply-Key | A unique token to support reply by email | | X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc | +| List-Id | The path of the project in a RFC 2919 mailing list identifier useful for email organization, for example, with GMail filters | #### 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/releases.md b/doc/workflow/releases.md index 6176784fc57..00cddda24a4 100644 --- a/doc/workflow/releases.md +++ b/doc/workflow/releases.md @@ -1,14 +1,17 @@ # Releases -You can turn any git tag into a release, by adding a note to it. -Release notes behave like any other markdown form in GitLab so you can write text and drag-n-drop files to it. -Release notes are stored in the database of GitLab. +NOTE: In GitLab 11.7, we introduced the full fledged [Releases](../user/project/releases/index.md) +feature. You can still create release notes on this page, but the new method is preferred. -There are several ways to add release notes: +You can add release notes to any git tag using the notes feature. Release notes +behave like any other markdown form in GitLab so you can write text and +drag-n-drop files to it. Release notes are stored in GitLab's database. -* In the interface, when you create a new git tag with GitLab -* In the interface, by adding a note to an existing git tag -* with the GitLab API +There are several ways to add release notes: + +- In the interface, when you create a new git tag +- In the interface, by adding a note to an existing git tag +- Using the GitLab API ## New tag page with release notes text area @@ -17,4 +20,3 @@ There are several ways to add release notes: ## Tags page with button to add or edit release notes for existing git tag  - diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md index 8c4e6ea8eab..ac26aeab137 100644 --- a/doc/workflow/repository_mirroring.md +++ b/doc/workflow/repository_mirroring.md @@ -1,351 +1,402 @@ # 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 using this format: `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. +1. Fill in **Password** field with your GitHub personal access token. +1. Click the **Mirror repository** button. -### Overwrite diverged branches **[STARTER]** +The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. ->[Introduced][ee-4559] in GitLab Enterprise Edition 10.6. +The repository will push soon. To force a push, click the appropriate button. -You can choose to always update your local branch with the remote version even -if your local version has diverged from the remote. +## Pulling from a remote repository **[STARTER]** -To use this option go to your project's repository settings page under pull mirror. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. -### Hard failure **[STARTER]** +You can set up a repository to automatically have its branches, tags, and commits updated from an +upstream repository. ->[Introduced][ee-3117] in GitLab Enterprise Edition 10.2. +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. -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. +To configure mirror pulling for an existing project: - +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. - + -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. +--- -### SSH authentication **[STARTER]** + -> [Introduced][ee-2551] in GitLab Starter 9.5 +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: -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]. +- Automatically within a certain period of time. +- When a [forced update](#forcing-an-update) is initiated. -To get started, navigate to **Settings ➔ Repository ➔ Pull from a remote repository**, -enable mirroring (if not already enabled) and enter an `ssh://` URL. +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. -> **NOTE**: SCP-style URLs, e.g., `git@example.com:group/project.git`, are not -supported at this time. +### How it works -Entering the URL adds two features to the page - `Fingerprints` and -`SSH public key authentication`: +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. - +If the mirror updates successfully, it will be enqueued once again with a small backoff period. -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. +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. -Press the `Detect host keys` button. GitLab will fetch the host keys from the -server, and display the fingerprints to you: +### SSH authentication - +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) for Pull mirroring in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22982) for Push mirroring in [GitLab Core](https://about.gitlab.com/pricing/) 11.6 -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: +SSH authentication is mutual: -* [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 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. -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: +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. -``` -$ 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're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using: -(You may need to exclude `-E md5` for some older versions of SSH). +- 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). -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: +To get started: - +1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section. +1. Enter an `ssh://` URL for mirroring. -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: +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: -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**. +- **Input host keys manually**. -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: +If you click the: - +- **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. -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. +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: -Once the public key is set up on the source repository, press `Save changes` and your -mirror will begin working. +- [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 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. +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: -### How it works +```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) +``` -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. +NOTE: **Note:** +You may need to exclude `-E md5` for some older versions of SSH. -If the mirror successfully updates it will be enqueued once again with a small -backoff period. +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. -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. +### SSH public key authentication -## Pushing to a remote repository +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. ->[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. +You then need to add the public SSH key to the other repository's configuration: -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. +- 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. - +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. -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. +### Overwrite diverged branches **[STARTER]** -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. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. -In case of a diverged branch, you will see an error indicated at the **Mirror -repository** settings. +You can choose to always update your local branches with remote versions, even if they have +diverged from the remote. - +CAUTION: **Caution:** +For mirrored branches, enabling this option results in the loss of local changes. -### Push only protected branches +To use this option, check the **Overwrite diverged branches** box when creating a repository mirror. ->[Introduced][ee-3350] in GitLab Enterprise Edition 10.3. [Moved to GitLab Community Edition][ce-18715] in 10.8. +### Only mirror protected branches **[STARTER]** -You can choose to only push your protected branches from GitLab to your remote repository. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. -To use this option go to your project's repository settings page under push mirror. +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. -## Setting up a push mirror from GitLab to GitHub +To use this option, check the **Only mirror protected branches** box when creating a repository mirror. -To set up a mirror from GitLab to GitHub, you need to follow these steps: +### Hard failure **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in +> [GitLab Starter](https://about.gitlab.com/pricing/) 10.2. -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: +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: -  +- Project's main dashboard. +- Pull mirror settings page. -1. Fill in the "Git repository URL" with the personal access token replacing the password `https://GitHubUsername:GitHubPersonalAccessToken@github.com/group/project.git`: +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). + +### 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..2bb140b99d0 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -8,8 +8,9 @@ requests within GitLab. ## Overview Time Tracking lets you: -* record the time spent working on an issue or a merge request, -* add an estimate of the amount of time needed to complete an issue or a merge + +- Record the time spent working on an issue or a merge request. +- Add an estimate of the amount of time needed to complete an issue or a merge request. You don't have to indicate an estimate to enter the time spent, and vice versa. @@ -62,12 +63,14 @@ To remove all the time spent at once, use `/remove_time_spent`. ## Configuration The following time units are available: -* weeks (w) -* days (d) -* hours (h) -* minutes (m) -Default conversion rates are 1w = 5d and 1d = 8h. +- months (mo) +- weeks (w) +- days (d) +- hours (h) +- minutes (m) + +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 diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md index f94d592d0db..830f17aa7f2 100644 --- a/doc/workflow/todos.md +++ b/doc/workflow/todos.md @@ -35,6 +35,9 @@ A Todo appears in your Todos dashboard when: - the author, or - have set it to automatically merge once pipeline succeeds. +NOTE: **Note:** +When an user no longer has access to a resource related to a Todo like an issue, merge request, project or group the related Todos, for security reasons, gets deleted within the next hour. The delete is delayed to prevent data loss in case user got their access revoked by mistake. + ### Directly addressed Todos > [Introduced][ce-7926] in GitLab 9.0. |
