Commit 202d4113 authored by Job van der Voort's avatar Job van der Voort

Merge branch 'docs/overview-features-5-ee' into 'master'

Add overview and use cases for MR-related docs

See merge request !2350
parents d0d27531 100b0e54
# Multi-Project Pipeline Graphs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/2121) in
[GitLab Enterprise Edition Premium 9.3](https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs).
## Overview
GitLab CI/CD is a powerful continuous integration tool built-in GitLab.
GitLab CI works not only per project, but also across projects. When you
configure GitLab CI for your project, you can visualize the stages
of your [jobs](pipelines.md#jobs) on a chart called [pipeline graph](pipelines.md#pipeline-graphs).
When you set up [GitLab CI/CD](README.md) across multiple projects, you can visualize
the entire pipeline, including all multi-project stages.
![Multi-project pipeline graph](img/multi_project_pipeline_graph.png)
Multi-Project Pipeline Graphs are useful for larger projects, especially those
adopting a [microservices architecture](https://about.gitlab.com/2016/08/16/trends-in-version-control-land-microservices/),
that often have a set of interdependent components which form the complete product.
## Use cases
Let's assume you deploy your web app from different projects in GitLab:
- One for the free version, which has its own pipeline that builds and tests your app
- One for the paid version adds-ons, which also pass through builds and tests
- One for the documentation, which also builds, tests, and deploys with an SSG
With Multi-Project Pipeline Graphs, you can visualize the entire pipeline in a
beautiful and clear chart, including all stages of builds and tests for the three projects.
## How it works
Using the [`CI_JOB_TOKEN` when triggering pipelines](triggers/README.md#ci-job-token), GitLab
recognizes the source of the job token, and thus internally ties these pipelines
together which makes it easy to start visualizing their relationships.
Those relationships are displayed in the pipeline graph by showing inbound and
outbound connections for upstream and downstream pipeline dependencies.
......@@ -186,22 +186,12 @@ by name. The order of severity is:
![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
### Multi-project pipelines graphs
### Multi-Project Pipelines Graphs
> [Introduced][ee-2121] in [GitLab Enterprise Edition Premium][eep] 9.3.
With [Multi-Project Pipeline Graphs](multi_project_pipeline_graphs.md),
you can visualize cross-project pipelines.
Using the [`CI_JOB_TOKEN` when triggering pipelines][triggers], GitLab
recognizes the source of the job token, and thus internally ties these pipelines
together which makes it easy to start visualizing their relationships.
Those relationships are displayed in the pipeline graph by showing inbound and
outbound connections for upstream and downstream pipeline dependencies.
![Multi-projects pipelines graphs](img/multi_project_pipelines_graph.png)
This is useful for larger projects, especially those adopting a micro-services
architecture, that often have a set of interdependent components which form the
complete product.
It is available only in [GitLab Enterprise Edition Premium][eep].
## How the pipeline duration is calculated
......@@ -244,7 +234,7 @@ respective link in the [Pipelines settings] page.
[manual]: yaml/README.md#manual
[env-manual]: environments.md#manually-deploying-to-environments
[stages]: yaml/README.md#stages
[runners]: runners/README.html
[runners]: runners/README.md
[pipelines settings]: ../user/project/pipelines/settings.md
[triggers]: triggers/README.md#ci-job-token
[ce-5742]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5742
......
......@@ -2,12 +2,28 @@
> [Introduced][ee-1984] in [GitLab Enterprise Edition Starter][ee] 9.3.
## Overview
If you are using [GitLab CI][ci], you can analyze your source code quality using
the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab
can show the Code Climate report right in the merge request widget area.
![Code Quality Widget][quality-widget]
## Use cases
For instance, consider the following workflow:
1. Your backend team member starts a new implementation for making certain feature in your app faster
1. With Code Quality reports, they analize how their implementation is impacting the code quality
1. The metrics show that their code degrade the quality in 10 points
1. You ask a co-worker to help them with this modification
1. They both work on the changes until Code Quality report displays no degradations, only improvements
1. You approve the merge request and authorize its deployment to staging
1. Once verified, their changes are deployed to production
## How it works
In order for the report to show in the merge request, you need to specify a
`codeclimate` job (exact name) that will analyze the code and upload the resulting
`codeclimate.json` as an artifact. GitLab will then check this file and show
......@@ -18,7 +34,7 @@ If the Code Climate report doesn't have anything to compare to, no information
will be displayed in the merge request area. That is the case when you add the
`codeclimate` job in your `.gitlab-ci.yml` for the very first time.
Consecutive merge requests will have something to compare to and the code quality
diff will be shown properly.
report will be shown properly.
For more information on how the `codeclimate` job should look like, check the
example on [analyzing a project's code quality with Code Climate CLI][cc-docs].
......
......@@ -3,6 +3,59 @@
Merge requests allow you to exchange changes you made to source code and
collaborate with other people on the same project.
## Overview
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.
With GitLab merge requests, you can:
- Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching)
- Discuss and review the proposed modifications inline
- Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project
- Build, test, and deploy your code is a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md)
- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests)
- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#pipeline-graphs)
- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request
- Assign it to any registered user, and change the assignee how many times you need
- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.html#time-tracking)
- [Resolve merge conflicts from the UI](#resolve-conflicts)
With [GitLab Enterprise Edition][ee], you can also:
- View the deployment process across projects with [Multi-Project Pipeline Graphs](../../../ci/multi_project_pipeline_graphs.md) (available only in GitLab Enterprise Edition Premium)
- Request [approvals](#merge-request-approvals) from your managers (available in GitLab Enterprise Edition Starter)
- Enable [fast-forward merge requests](#fast-forward-merge-requests) (available in GitLab Enterprise Edition Starter)
- [Squash and merge](#squash-and-merge) for a cleaner commit history (available in GitLab Enterprise Edition Starter)
- Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch (available in GitLab Enterprise Edition Starter)
- Analise the impact of your changes with [Code Quality reports](#code-quality-reports) (available only in GitLab Enterprise Edition Starter)
## Use cases
A. Consider you are a software developer working in a team:
1. You checkout a new branch, and submit your changes through a merge request
1. You gather feedback from your team
1. You work on the implementation optimizing code with [Code Quality reports](#code-quality-reports)
1. You build and test your changes with GitLab CI/CD
1. You request the approval from your manager
1. Your manager pushes a commit with his final review and set the merge request to [merge when pipeline succeeds](#merge-when-pipeline-succeeds)
1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#manual-actions) for GitLab CI/CD
1. Your implementations were successfully shipped to your customer
B. Consider you're a web developer writing a webpage for your company's website:
1. You checkout a new branch, and submit a new page through a merge request
1. You gather feedback from your reviewers
1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md)
1. You request your web designers for their implementation
1. You request the approval from your manager
1. Once approved, your merge request is [squashed and merged](#squash-and-merge), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production
## Authorization for merge requests
There are two main ways to have a merge request flow with GitLab:
......@@ -91,7 +144,7 @@ list of approvers that will need to approve every merge request in a project.
A merge commit is created for every merge, but the branch is only merged if
a fast-forward merge is possible. This ensures that if the merge request build
suceedeed, the target branch build will also succeed after merging.
succeeded, the target branch build will also succeed after merging.
Navigate to a project's settings, select the **Merge commit with semi-linear
history** option under **Merge Requests: Merge method** and save your changes.
......@@ -105,7 +158,7 @@ creating merge commits, you can configure this on a per-project basis.
[Read more about fast-forward merge requests.](fast_forward_merge.md)
## Code quality diff
## Code Quality reports
> Introduced in [GitLab Enterprise Edition Starter][products] 9.3.
......@@ -113,7 +166,16 @@ If you are using [GitLab CI][ci], you can analyze your source code quality using
the [Code Climate][cc] analyzer [Docker image][cd]. Going a step further, GitLab
can show the Code Climate report right in the merge request widget area.
[Read more about code quality diff.](code_quality_diff.md)
[Read more about Code Quality reports.](code_quality_diff.md)
## Live preview with Review Apps
If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,
you can preview the changes submitted to a feature-branch through a merge request
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)
## Ignore whitespace changes in Merge Request diff view
......@@ -219,3 +281,4 @@ git checkout origin/merge-requests/1
[ci]: ../../../ci/README.md
[cc]: https://codeclimate.com/
[cd]: https://hub.docker.com/r/codeclimate/codeclimate/
[ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition"
# Merge request approvals
> Introduced in GitLab Enterprise Edition 7.13.
> Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only), available in [GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee/).
## Overview
If you want to make sure every merge request is approved by one or more
people, you can enforce this workflow by using merge request approvals.
Merge request approvals allow you to set the number of necessary approvals
and predefine a list of approvers that will need to approve every
merge request in a project.
## Use cases
There are numerous use cases for merge request approvals. For instance,
let's consider you're a backend developer working in a team:
1. You submit changes to your project via merge request
1. You gather feedback from your team members in the merge request
1. You build, test, and deploy your app with [GitLab CI/CD](../../../ci/README.md)
1. Once everything is ready to ship, you add your manager and the project manager as approvers to that merge request
1. Your approvers get a notification and review your modifications
1. You need to address your managers' comments, so you push again to your branch
1. Once you pushed, that merge request will need another round of approvals
1. You ask your managers again for their approval
1. They approve and merge
This example workflow prevents your implementations from being merged before getting approvals from both managers.
## Configuring Approvals
You can configure the approvals in the project settings, under merge requests.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment