From 24ad2f4f0d9e8ebfd8133a572f29e52b74cd7dd5 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Tue, 21 Jun 2016 13:28:50 +0200
Subject: Restructure documentation

The big plan in motion, see https://gitlab.com/gitlab-org/gitlab-ce/issues/3349
---
 doc/user/gitlab-basics/README.md                   |  15 +
 doc/user/gitlab-basics/add-file.md                 |  31 +
 doc/user/gitlab-basics/add-image.md                |  62 ++
 doc/user/gitlab-basics/add-merge-request.md        |  42 ++
 doc/user/gitlab-basics/basic-git-commands.md       |   3 +
 .../basicsimages/add_new_merge_request.png         | Bin 0 -> 9467 bytes
 doc/user/gitlab-basics/basicsimages/add_sshkey.png | Bin 0 -> 1463 bytes
 .../gitlab-basics/basicsimages/branch_info.png     | Bin 0 -> 7978 bytes
 .../gitlab-basics/basicsimages/branch_name.png     | Bin 0 -> 2199 bytes
 doc/user/gitlab-basics/basicsimages/branches.png   | Bin 0 -> 3653 bytes
 .../basicsimages/button-create-mr.png              | Bin 0 -> 6154 bytes
 .../basicsimages/click-on-new-group.png            | Bin 0 -> 2063 bytes
 .../gitlab-basics/basicsimages/commit_changes.png  | Bin 0 -> 5567 bytes
 .../gitlab-basics/basicsimages/commit_message.png  | Bin 0 -> 5707 bytes
 doc/user/gitlab-basics/basicsimages/commits.png    | Bin 0 -> 4258 bytes
 .../basicsimages/compare_branches.png              | Bin 0 -> 1624 bytes
 .../gitlab-basics/basicsimages/create_file.png     | Bin 0 -> 2524 bytes
 .../gitlab-basics/basicsimages/create_group.png    | Bin 0 -> 3224 bytes
 doc/user/gitlab-basics/basicsimages/edit_file.png  | Bin 0 -> 2259 bytes
 .../gitlab-basics/basicsimages/file_located.png    | Bin 0 -> 3156 bytes
 doc/user/gitlab-basics/basicsimages/file_name.png  | Bin 0 -> 2544 bytes
 doc/user/gitlab-basics/basicsimages/find_file.png  | Bin 0 -> 8840 bytes
 doc/user/gitlab-basics/basicsimages/find_group.png | Bin 0 -> 6159 bytes
 doc/user/gitlab-basics/basicsimages/fork.png       | Bin 0 -> 1046 bytes
 doc/user/gitlab-basics/basicsimages/group_info.png | Bin 0 -> 16217 bytes
 doc/user/gitlab-basics/basicsimages/groups.png     | Bin 0 -> 4857 bytes
 doc/user/gitlab-basics/basicsimages/https.png      | Bin 0 -> 2887 bytes
 doc/user/gitlab-basics/basicsimages/image_file.png | Bin 0 -> 2939 bytes
 .../gitlab-basics/basicsimages/issue_title.png     | Bin 0 -> 9059 bytes
 doc/user/gitlab-basics/basicsimages/issues.png     | Bin 0 -> 4332 bytes
 doc/user/gitlab-basics/basicsimages/key.png        | Bin 0 -> 1264 bytes
 .../gitlab-basics/basicsimages/merge_requests.png  | Bin 0 -> 4381 bytes
 doc/user/gitlab-basics/basicsimages/new_issue.png  | Bin 0 -> 2974 bytes
 .../basicsimages/new_merge_request.png             | Bin 0 -> 3227 bytes
 .../gitlab-basics/basicsimages/new_project.png     | Bin 0 -> 2319 bytes
 doc/user/gitlab-basics/basicsimages/newbranch.png  | Bin 0 -> 1314 bytes
 .../gitlab-basics/basicsimages/paste_sshkey.png    | Bin 0 -> 8620 bytes
 .../basicsimages/profile_settings.png              | Bin 0 -> 1194 bytes
 .../gitlab-basics/basicsimages/project_info.png    | Bin 0 -> 21862 bytes
 .../basicsimages/public_file_link.png              | Bin 0 -> 3038 bytes
 .../gitlab-basics/basicsimages/select-group.png    | Bin 0 -> 6075 bytes
 .../gitlab-basics/basicsimages/select-group2.png   | Bin 0 -> 5049 bytes
 .../gitlab-basics/basicsimages/select_branch.png   | Bin 0 -> 12213 bytes
 .../gitlab-basics/basicsimages/select_project.png  | Bin 0 -> 16832 bytes
 doc/user/gitlab-basics/basicsimages/settings.png   | Bin 0 -> 4321 bytes
 doc/user/gitlab-basics/basicsimages/shh_keys.png   | Bin 0 -> 4981 bytes
 .../basicsimages/submit_new_issue.png              | Bin 0 -> 9083 bytes
 .../basicsimages/title_description_mr.png          | Bin 0 -> 12749 bytes
 .../gitlab-basics/basicsimages/white_space.png     | Bin 0 -> 3707 bytes
 doc/user/gitlab-basics/command-line-commands.md    |  79 +++
 doc/user/gitlab-basics/create-branch.md            |  39 +
 doc/user/gitlab-basics/create-group.md             |  43 ++
 doc/user/gitlab-basics/create-issue.md             |  27 +
 doc/user/gitlab-basics/create-project.md           |  21 +
 doc/user/gitlab-basics/create-your-ssh-keys.md     |  33 +
 doc/user/gitlab-basics/fork-project.md             |  19 +
 doc/user/gitlab-basics/start-using-git.md          | 122 ++++
 doc/user/markdown/img/logo.png                     | Bin 0 -> 11097 bytes
 doc/user/markdown/markdown.md                      | 615 ++++++++++++++++
 doc/user/permissions/permissions.md                | 101 +++
 doc/user/profile/2fa.png                           | Bin 0 -> 23415 bytes
 doc/user/profile/2fa_auth.png                      | Bin 0 -> 15569 bytes
 doc/user/profile/2fa_u2f_authenticate.png          | Bin 0 -> 54413 bytes
 doc/user/profile/2fa_u2f_register.png              | Bin 0 -> 112414 bytes
 doc/user/profile/README.md                         |   4 +
 doc/user/profile/preferences.md                    |  43 ++
 doc/user/profile/two_factor_authentication.md      | 127 ++++
 doc/user/project/container_registry/README.md      |  94 +++
 .../container_registry/img/container_registry.png  | Bin 0 -> 354050 bytes
 .../container_registry/img/project_feature.png     | Bin 0 -> 392842 bytes
 doc/user/project/project_services/bamboo.md        |  60 ++
 doc/user/project/project_services/builds_emails.md |  16 +
 .../project/project_services/emails_on_push.md     |  17 +
 doc/user/project/project_services/hipchat.md       |  54 ++
 .../project_services/img/builds_emails_service.png | Bin 0 -> 41222 bytes
 .../img/emails_on_push_service.png                 | Bin 0 -> 98160 bytes
 .../img/jira_add_gitlab_commit_message.png         | Bin 0 -> 57136 bytes
 .../img/jira_add_user_to_group.png                 | Bin 0 -> 59251 bytes
 .../project_services/img/jira_create_new_group.png | Bin 0 -> 41294 bytes
 .../img/jira_create_new_group_name.png             | Bin 0 -> 12535 bytes
 .../project_services/img/jira_create_new_user.png  | Bin 0 -> 26532 bytes
 .../project_services/img/jira_group_access.png     | Bin 0 -> 46028 bytes
 .../project_services/img/jira_issue_closed.png     | Bin 0 -> 92601 bytes
 .../project_services/img/jira_issue_reference.png  | Bin 0 -> 39942 bytes
 .../project_services/img/jira_issues_workflow.png  | Bin 0 -> 105237 bytes
 .../img/jira_merge_request_close.png               | Bin 0 -> 111150 bytes
 .../project_services/img/jira_project_name.png     | Bin 0 -> 60598 bytes
 ...jira_reference_commit_message_in_jira_issue.png | Bin 0 -> 42452 bytes
 .../project/project_services/img/jira_service.png  | Bin 0 -> 59082 bytes
 .../img/jira_service_close_issue.png               | Bin 0 -> 88433 bytes
 .../project_services/img/jira_service_page.png     | Bin 0 -> 49122 bytes
 .../img/jira_submit_gitlab_merge_request.png       | Bin 0 -> 63063 bytes
 .../img/jira_user_management_link.png              | Bin 0 -> 58211 bytes
 .../img/jira_workflow_screenshot.png               | Bin 0 -> 121534 bytes
 .../project_services/img/redmine_configuration.png | Bin 0 -> 21061 bytes
 .../img/services_templates_redmine_example.png     | Bin 0 -> 17351 bytes
 doc/user/project/project_services/irker.md         |  51 ++
 doc/user/project/project_services/jira.md          | 246 +++++++
 .../project/project_services/project_services.md   |  54 ++
 doc/user/project/project_services/redmine.md       |  21 +
 .../project/project_services/services_templates.md |  25 +
 doc/user/public_access/public_access.md            |  69 ++
 doc/user/ssh/README.md                             | 130 ++++
 doc/user/system_hooks/system_hooks.md              | 355 ++++++++++
 doc/user/web_hooks/ssl.png                         | Bin 0 -> 77165 bytes
 doc/user/web_hooks/web_hooks.md                    | 784 +++++++++++++++++++++
 doc/user/workflow/README.md                        |  28 +
 doc/user/workflow/add-user/add-user.md             | 111 +++
 .../add-user/img/access_requests_management.png    | Bin 0 -> 15105 bytes
 .../img/add_new_user_to_project_settings.png       | Bin 0 -> 22822 bytes
 .../add-user/img/add_user_email_accept.png         | Bin 0 -> 22961 bytes
 .../workflow/add-user/img/add_user_email_ready.png | Bin 0 -> 40305 bytes
 .../add-user/img/add_user_email_search.png         | Bin 0 -> 45884 bytes
 .../add-user/img/add_user_give_permissions.png     | Bin 0 -> 56480 bytes
 ...dd_user_import_members_from_another_project.png | Bin 0 -> 38874 bytes
 .../add-user/img/add_user_imported_members.png     | Bin 0 -> 37873 bytes
 .../add-user/img/add_user_list_members.png         | Bin 0 -> 24427 bytes
 .../add-user/img/add_user_members_menu.png         | Bin 0 -> 42319 bytes
 .../add-user/img/add_user_search_people.png        | Bin 0 -> 39941 bytes
 .../add-user/img/request_access_button.png         | Bin 0 -> 36588 bytes
 .../img/withdraw_access_request_button.png         | Bin 0 -> 37960 bytes
 .../workflow/authorization_for_merge_requests.md   |  40 ++
 doc/user/workflow/award_emoji.md                   |  48 ++
 doc/user/workflow/award_emoji.png                  | Bin 0 -> 6620 bytes
 doc/user/workflow/cherry_pick_changes.md           |  53 ++
 doc/user/workflow/ci_mr.png                        | Bin 0 -> 40065 bytes
 doc/user/workflow/close_issue_mr.png               | Bin 0 -> 146292 bytes
 doc/user/workflow/environment_branches.png         | Bin 0 -> 40210 bytes
 doc/user/workflow/file_finder.md                   |  46 ++
 doc/user/workflow/forking/branch_select.png        | Bin 0 -> 55352 bytes
 doc/user/workflow/forking/merge_request.png        | Bin 0 -> 60597 bytes
 doc/user/workflow/forking_workflow.md              |  59 ++
 doc/user/workflow/four_stages.png                  | Bin 0 -> 20934 bytes
 doc/user/workflow/git_pull.png                     | Bin 0 -> 167056 bytes
 doc/user/workflow/gitdashflow.png                  | Bin 0 -> 184726 bytes
 doc/user/workflow/github_flow.png                  | Bin 0 -> 20600 bytes
 doc/user/workflow/gitlab_flow.md                   | 317 +++++++++
 doc/user/workflow/gitlab_flow.png                  | Bin 0 -> 90883 bytes
 doc/user/workflow/good_commit.png                  | Bin 0 -> 28433 bytes
 doc/user/workflow/groups.md                        |  93 +++
 .../workflow/groups/access_requests_management.png | Bin 0 -> 15193 bytes
 doc/user/workflow/groups/add_member_to_group.png   | Bin 0 -> 138184 bytes
 doc/user/workflow/groups/group_dashboard.png       | Bin 0 -> 107332 bytes
 .../workflow/groups/group_with_two_projects.png    | Bin 0 -> 129319 bytes
 doc/user/workflow/groups/max_access_level.png      | Bin 0 -> 135354 bytes
 doc/user/workflow/groups/new_group_button.png      | Bin 0 -> 185406 bytes
 doc/user/workflow/groups/new_group_form.png        | Bin 0 -> 106491 bytes
 .../groups/other_group_sees_shared_project.png     | Bin 0 -> 118382 bytes
 doc/user/workflow/groups/override_access_level.png | Bin 0 -> 157193 bytes
 .../workflow/groups/project_members_via_group.png  | Bin 0 -> 151339 bytes
 doc/user/workflow/groups/request_access_button.png | Bin 0 -> 30470 bytes
 .../workflow/groups/share_project_with_groups.png  | Bin 0 -> 118868 bytes
 doc/user/workflow/groups/transfer_project.png      | Bin 0 -> 164958 bytes
 .../groups/withdraw_access_request_button.png      | Bin 0 -> 31681 bytes
 doc/user/workflow/img/award_emoji_select.png       | Bin 0 -> 65985 bytes
 .../img/award_emoji_votes_least_popular.png        | Bin 0 -> 144501 bytes
 .../img/award_emoji_votes_most_popular.png         | Bin 0 -> 136577 bytes
 .../img/award_emoji_votes_sort_options.png         | Bin 0 -> 162251 bytes
 .../workflow/img/cherry_pick_changes_commit.png    | Bin 0 -> 353067 bytes
 .../img/cherry_pick_changes_commit_modal.png       | Bin 0 -> 312659 bytes
 doc/user/workflow/img/cherry_pick_changes_mr.png   | Bin 0 -> 252085 bytes
 .../workflow/img/cherry_pick_changes_mr_modal.png  | Bin 0 -> 225569 bytes
 doc/user/workflow/img/file_finder_find_button.png  | Bin 0 -> 30974 bytes
 doc/user/workflow/img/file_finder_find_file.png    | Bin 0 -> 42658 bytes
 .../img/forking_workflow_choose_namespace.png      | Bin 0 -> 70405 bytes
 .../workflow/img/forking_workflow_fork_button.png  | Bin 0 -> 26438 bytes
 .../img/forking_workflow_path_taken_error.png      | Bin 0 -> 22380 bytes
 doc/user/workflow/img/new_branch_from_issue.png    | Bin 0 -> 120622 bytes
 doc/user/workflow/img/revert_changes_commit.png    | Bin 0 -> 360098 bytes
 .../workflow/img/revert_changes_commit_modal.png   | Bin 0 -> 327932 bytes
 doc/user/workflow/img/revert_changes_mr.png        | Bin 0 -> 367881 bytes
 doc/user/workflow/img/revert_changes_mr_modal.png  | Bin 0 -> 335010 bytes
 doc/user/workflow/img/todos_icon.png               | Bin 0 -> 7394 bytes
 doc/user/workflow/img/todos_index.png              | Bin 0 -> 184839 bytes
 .../img/web_editor_new_branch_dropdown.png         | Bin 0 -> 34233 bytes
 .../workflow/img/web_editor_new_branch_page.png    | Bin 0 -> 21618 bytes
 .../img/web_editor_new_directory_dialog.png        | Bin 0 -> 26145 bytes
 .../img/web_editor_new_directory_dropdown.png      | Bin 0 -> 33714 bytes
 .../workflow/img/web_editor_new_file_dropdown.png  | Bin 0 -> 34978 bytes
 .../workflow/img/web_editor_new_file_editor.png    | Bin 0 -> 128658 bytes
 .../workflow/img/web_editor_new_push_widget.png    | Bin 0 -> 11220 bytes
 .../workflow/img/web_editor_new_tag_dropdown.png   | Bin 0 -> 33753 bytes
 doc/user/workflow/img/web_editor_new_tag_page.png  | Bin 0 -> 75536 bytes
 .../img/web_editor_start_new_merge_request.png     | Bin 0 -> 14352 bytes
 .../workflow/img/web_editor_upload_file_dialog.png | Bin 0 -> 46219 bytes
 .../img/web_editor_upload_file_dropdown.png        | Bin 0 -> 34835 bytes
 doc/user/workflow/importing/README.md              |  17 +
 .../bitbucket_import_grant_access.png              | Bin 0 -> 30083 bytes
 .../bitbucket_import_new_project.png               | Bin 0 -> 16502 bytes
 .../bitbucket_import_select_bitbucket.png          | Bin 0 -> 46606 bytes
 .../bitbucket_import_select_project.png            | Bin 0 -> 16121 bytes
 .../fogbugz_importer/fogbugz_import_finished.png   | Bin 0 -> 53276 bytes
 .../fogbugz_importer/fogbugz_import_login.png      | Bin 0 -> 44444 bytes
 .../fogbugz_import_select_fogbogz.png              | Bin 0 -> 35415 bytes
 .../fogbugz_import_select_project.png              | Bin 0 -> 62552 bytes
 .../fogbugz_importer/fogbugz_import_user_map.png   | Bin 0 -> 157856 bytes
 .../importing/gitlab_importer/importer.png         | Bin 0 -> 40778 bytes
 .../importing/gitlab_importer/new_project_page.png | Bin 0 -> 72663 bytes
 .../img/import_projects_from_github_importer.png   | Bin 0 -> 28033 bytes
 ...mport_projects_from_github_new_project_page.png | Bin 0 -> 17225 bytes
 .../importing/import_projects_from_bitbucket.md    |  26 +
 .../importing/import_projects_from_fogbugz.md      |  29 +
 .../importing/import_projects_from_github.md       |  48 ++
 .../importing/import_projects_from_gitlab_com.md   |  18 +
 doc/user/workflow/importing/migrating_from_svn.md  |  79 +++
 doc/user/workflow/labels.md                        |  18 +
 doc/user/workflow/labels/label1.png                | Bin 0 -> 5846 bytes
 doc/user/workflow/labels/label2.png                | Bin 0 -> 16931 bytes
 doc/user/workflow/labels/label3.png                | Bin 0 -> 19360 bytes
 doc/user/workflow/lfs/lfs_administration.md        |  49 ++
 .../lfs/manage_large_binaries_with_git_lfs.md      | 155 ++++
 doc/user/workflow/merge_commits.png                | Bin 0 -> 41422 bytes
 doc/user/workflow/merge_request.png                | Bin 0 -> 169503 bytes
 doc/user/workflow/merge_requests.md                |  63 ++
 .../workflow/merge_requests/commit_compare.png     | Bin 0 -> 110376 bytes
 .../workflow/merge_requests/merge_request_diff.png | Bin 0 -> 166226 bytes
 .../merge_request_diff_without_whitespace.png      | Bin 0 -> 121476 bytes
 .../only_allow_merge_if_build_succeeds.png         | Bin 0 -> 17552 bytes
 doc/user/workflow/merge_when_build_succeeds.md     |  15 +
 .../workflow/merge_when_build_succeeds/enable.png  | Bin 0 -> 151112 bytes
 .../workflow/merge_when_build_succeeds/status.png  | Bin 0 -> 180318 bytes
 doc/user/workflow/messy_flow.png                   | Bin 0 -> 33829 bytes
 doc/user/workflow/milestones.md                    |  13 +
 doc/user/workflow/milestones/form.png              | Bin 0 -> 88591 bytes
 doc/user/workflow/milestones/group_form.png        | Bin 0 -> 77087 bytes
 doc/user/workflow/mr_inline_comments.png           | Bin 0 -> 193311 bytes
 doc/user/workflow/notifications.md                 |  93 +++
 doc/user/workflow/notifications/settings.png       | Bin 0 -> 90986 bytes
 doc/user/workflow/production_branch.png            | Bin 0 -> 21716 bytes
 doc/user/workflow/project_features.md              |  35 +
 doc/user/workflow/protected_branches.md            |  31 +
 .../protected_branches/protected_branches1.png     | Bin 0 -> 170113 bytes
 .../protected_branches/protected_branches2.png     | Bin 0 -> 25851 bytes
 doc/user/workflow/rebase.png                       | Bin 0 -> 123041 bytes
 doc/user/workflow/release_branches.png             | Bin 0 -> 44173 bytes
 doc/user/workflow/releases.md                      |  20 +
 doc/user/workflow/releases/new_tag.png             | Bin 0 -> 154755 bytes
 doc/user/workflow/releases/tags.png                | Bin 0 -> 165449 bytes
 doc/user/workflow/remove_checkbox.png              | Bin 0 -> 22272 bytes
 doc/user/workflow/revert_changes.md                |  64 ++
 .../workflow/share_projects_with_other_groups.md   |  30 +
 doc/user/workflow/share_with_group.md              |  13 +
 doc/user/workflow/share_with_group.png             | Bin 0 -> 53784 bytes
 doc/user/workflow/shortcuts.md                     |   5 +
 doc/user/workflow/shortcuts.png                    | Bin 0 -> 108255 bytes
 doc/user/workflow/timezone.md                      |  30 +
 doc/user/workflow/todos.md                         |  73 ++
 doc/user/workflow/web_editor.md                    | 152 ++++
 doc/user/workflow/wip_merge_requests.md            |  13 +
 .../wip_merge_requests/blocked_accept_button.png   | Bin 0 -> 65231 bytes
 .../workflow/wip_merge_requests/mark_as_wip.png    | Bin 0 -> 41549 bytes
 .../workflow/wip_merge_requests/unmark_as_wip.png  | Bin 0 -> 32151 bytes
 doc/user/workflow/workflow.md                      |  31 +
 253 files changed, 5317 insertions(+)
 create mode 100644 doc/user/gitlab-basics/README.md
 create mode 100644 doc/user/gitlab-basics/add-file.md
 create mode 100644 doc/user/gitlab-basics/add-image.md
 create mode 100644 doc/user/gitlab-basics/add-merge-request.md
 create mode 100644 doc/user/gitlab-basics/basic-git-commands.md
 create mode 100644 doc/user/gitlab-basics/basicsimages/add_new_merge_request.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/add_sshkey.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/branch_info.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/branch_name.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/branches.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/button-create-mr.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/click-on-new-group.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/commit_changes.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/commit_message.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/commits.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/compare_branches.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/create_file.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/create_group.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/edit_file.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/file_located.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/file_name.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/find_file.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/find_group.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/fork.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/group_info.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/groups.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/https.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/image_file.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/issue_title.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/issues.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/key.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/merge_requests.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/new_issue.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/new_merge_request.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/new_project.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/newbranch.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/paste_sshkey.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/profile_settings.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/project_info.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/public_file_link.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/select-group.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/select-group2.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/select_branch.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/select_project.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/settings.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/shh_keys.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/submit_new_issue.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/title_description_mr.png
 create mode 100644 doc/user/gitlab-basics/basicsimages/white_space.png
 create mode 100644 doc/user/gitlab-basics/command-line-commands.md
 create mode 100644 doc/user/gitlab-basics/create-branch.md
 create mode 100644 doc/user/gitlab-basics/create-group.md
 create mode 100644 doc/user/gitlab-basics/create-issue.md
 create mode 100644 doc/user/gitlab-basics/create-project.md
 create mode 100644 doc/user/gitlab-basics/create-your-ssh-keys.md
 create mode 100644 doc/user/gitlab-basics/fork-project.md
 create mode 100644 doc/user/gitlab-basics/start-using-git.md
 create mode 100644 doc/user/markdown/img/logo.png
 create mode 100644 doc/user/markdown/markdown.md
 create mode 100644 doc/user/permissions/permissions.md
 create mode 100644 doc/user/profile/2fa.png
 create mode 100644 doc/user/profile/2fa_auth.png
 create mode 100644 doc/user/profile/2fa_u2f_authenticate.png
 create mode 100644 doc/user/profile/2fa_u2f_register.png
 create mode 100644 doc/user/profile/README.md
 create mode 100644 doc/user/profile/preferences.md
 create mode 100644 doc/user/profile/two_factor_authentication.md
 create mode 100644 doc/user/project/container_registry/README.md
 create mode 100644 doc/user/project/container_registry/img/container_registry.png
 create mode 100644 doc/user/project/container_registry/img/project_feature.png
 create mode 100644 doc/user/project/project_services/bamboo.md
 create mode 100644 doc/user/project/project_services/builds_emails.md
 create mode 100644 doc/user/project/project_services/emails_on_push.md
 create mode 100644 doc/user/project/project_services/hipchat.md
 create mode 100644 doc/user/project/project_services/img/builds_emails_service.png
 create mode 100644 doc/user/project/project_services/img/emails_on_push_service.png
 create mode 100644 doc/user/project/project_services/img/jira_add_gitlab_commit_message.png
 create mode 100644 doc/user/project/project_services/img/jira_add_user_to_group.png
 create mode 100644 doc/user/project/project_services/img/jira_create_new_group.png
 create mode 100644 doc/user/project/project_services/img/jira_create_new_group_name.png
 create mode 100644 doc/user/project/project_services/img/jira_create_new_user.png
 create mode 100644 doc/user/project/project_services/img/jira_group_access.png
 create mode 100644 doc/user/project/project_services/img/jira_issue_closed.png
 create mode 100644 doc/user/project/project_services/img/jira_issue_reference.png
 create mode 100644 doc/user/project/project_services/img/jira_issues_workflow.png
 create mode 100644 doc/user/project/project_services/img/jira_merge_request_close.png
 create mode 100644 doc/user/project/project_services/img/jira_project_name.png
 create mode 100644 doc/user/project/project_services/img/jira_reference_commit_message_in_jira_issue.png
 create mode 100644 doc/user/project/project_services/img/jira_service.png
 create mode 100644 doc/user/project/project_services/img/jira_service_close_issue.png
 create mode 100644 doc/user/project/project_services/img/jira_service_page.png
 create mode 100644 doc/user/project/project_services/img/jira_submit_gitlab_merge_request.png
 create mode 100644 doc/user/project/project_services/img/jira_user_management_link.png
 create mode 100644 doc/user/project/project_services/img/jira_workflow_screenshot.png
 create mode 100644 doc/user/project/project_services/img/redmine_configuration.png
 create mode 100644 doc/user/project/project_services/img/services_templates_redmine_example.png
 create mode 100644 doc/user/project/project_services/irker.md
 create mode 100644 doc/user/project/project_services/jira.md
 create mode 100644 doc/user/project/project_services/project_services.md
 create mode 100644 doc/user/project/project_services/redmine.md
 create mode 100644 doc/user/project/project_services/services_templates.md
 create mode 100644 doc/user/public_access/public_access.md
 create mode 100644 doc/user/ssh/README.md
 create mode 100644 doc/user/system_hooks/system_hooks.md
 create mode 100644 doc/user/web_hooks/ssl.png
 create mode 100644 doc/user/web_hooks/web_hooks.md
 create mode 100644 doc/user/workflow/README.md
 create mode 100644 doc/user/workflow/add-user/add-user.md
 create mode 100644 doc/user/workflow/add-user/img/access_requests_management.png
 create mode 100644 doc/user/workflow/add-user/img/add_new_user_to_project_settings.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_email_accept.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_email_ready.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_email_search.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_give_permissions.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_imported_members.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_list_members.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_members_menu.png
 create mode 100644 doc/user/workflow/add-user/img/add_user_search_people.png
 create mode 100644 doc/user/workflow/add-user/img/request_access_button.png
 create mode 100644 doc/user/workflow/add-user/img/withdraw_access_request_button.png
 create mode 100644 doc/user/workflow/authorization_for_merge_requests.md
 create mode 100644 doc/user/workflow/award_emoji.md
 create mode 100644 doc/user/workflow/award_emoji.png
 create mode 100644 doc/user/workflow/cherry_pick_changes.md
 create mode 100644 doc/user/workflow/ci_mr.png
 create mode 100644 doc/user/workflow/close_issue_mr.png
 create mode 100644 doc/user/workflow/environment_branches.png
 create mode 100644 doc/user/workflow/file_finder.md
 create mode 100644 doc/user/workflow/forking/branch_select.png
 create mode 100644 doc/user/workflow/forking/merge_request.png
 create mode 100644 doc/user/workflow/forking_workflow.md
 create mode 100644 doc/user/workflow/four_stages.png
 create mode 100644 doc/user/workflow/git_pull.png
 create mode 100644 doc/user/workflow/gitdashflow.png
 create mode 100644 doc/user/workflow/github_flow.png
 create mode 100644 doc/user/workflow/gitlab_flow.md
 create mode 100644 doc/user/workflow/gitlab_flow.png
 create mode 100644 doc/user/workflow/good_commit.png
 create mode 100644 doc/user/workflow/groups.md
 create mode 100644 doc/user/workflow/groups/access_requests_management.png
 create mode 100644 doc/user/workflow/groups/add_member_to_group.png
 create mode 100644 doc/user/workflow/groups/group_dashboard.png
 create mode 100644 doc/user/workflow/groups/group_with_two_projects.png
 create mode 100644 doc/user/workflow/groups/max_access_level.png
 create mode 100644 doc/user/workflow/groups/new_group_button.png
 create mode 100644 doc/user/workflow/groups/new_group_form.png
 create mode 100644 doc/user/workflow/groups/other_group_sees_shared_project.png
 create mode 100644 doc/user/workflow/groups/override_access_level.png
 create mode 100644 doc/user/workflow/groups/project_members_via_group.png
 create mode 100644 doc/user/workflow/groups/request_access_button.png
 create mode 100644 doc/user/workflow/groups/share_project_with_groups.png
 create mode 100644 doc/user/workflow/groups/transfer_project.png
 create mode 100644 doc/user/workflow/groups/withdraw_access_request_button.png
 create mode 100644 doc/user/workflow/img/award_emoji_select.png
 create mode 100644 doc/user/workflow/img/award_emoji_votes_least_popular.png
 create mode 100644 doc/user/workflow/img/award_emoji_votes_most_popular.png
 create mode 100644 doc/user/workflow/img/award_emoji_votes_sort_options.png
 create mode 100644 doc/user/workflow/img/cherry_pick_changes_commit.png
 create mode 100644 doc/user/workflow/img/cherry_pick_changes_commit_modal.png
 create mode 100644 doc/user/workflow/img/cherry_pick_changes_mr.png
 create mode 100644 doc/user/workflow/img/cherry_pick_changes_mr_modal.png
 create mode 100644 doc/user/workflow/img/file_finder_find_button.png
 create mode 100644 doc/user/workflow/img/file_finder_find_file.png
 create mode 100644 doc/user/workflow/img/forking_workflow_choose_namespace.png
 create mode 100644 doc/user/workflow/img/forking_workflow_fork_button.png
 create mode 100644 doc/user/workflow/img/forking_workflow_path_taken_error.png
 create mode 100644 doc/user/workflow/img/new_branch_from_issue.png
 create mode 100644 doc/user/workflow/img/revert_changes_commit.png
 create mode 100644 doc/user/workflow/img/revert_changes_commit_modal.png
 create mode 100644 doc/user/workflow/img/revert_changes_mr.png
 create mode 100644 doc/user/workflow/img/revert_changes_mr_modal.png
 create mode 100644 doc/user/workflow/img/todos_icon.png
 create mode 100644 doc/user/workflow/img/todos_index.png
 create mode 100644 doc/user/workflow/img/web_editor_new_branch_dropdown.png
 create mode 100644 doc/user/workflow/img/web_editor_new_branch_page.png
 create mode 100644 doc/user/workflow/img/web_editor_new_directory_dialog.png
 create mode 100644 doc/user/workflow/img/web_editor_new_directory_dropdown.png
 create mode 100644 doc/user/workflow/img/web_editor_new_file_dropdown.png
 create mode 100644 doc/user/workflow/img/web_editor_new_file_editor.png
 create mode 100644 doc/user/workflow/img/web_editor_new_push_widget.png
 create mode 100644 doc/user/workflow/img/web_editor_new_tag_dropdown.png
 create mode 100644 doc/user/workflow/img/web_editor_new_tag_page.png
 create mode 100644 doc/user/workflow/img/web_editor_start_new_merge_request.png
 create mode 100644 doc/user/workflow/img/web_editor_upload_file_dialog.png
 create mode 100644 doc/user/workflow/img/web_editor_upload_file_dropdown.png
 create mode 100644 doc/user/workflow/importing/README.md
 create mode 100644 doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png
 create mode 100644 doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png
 create mode 100644 doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png
 create mode 100644 doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png
 create mode 100644 doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png
 create mode 100644 doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png
 create mode 100644 doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png
 create mode 100644 doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png
 create mode 100644 doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png
 create mode 100644 doc/user/workflow/importing/gitlab_importer/importer.png
 create mode 100644 doc/user/workflow/importing/gitlab_importer/new_project_page.png
 create mode 100644 doc/user/workflow/importing/img/import_projects_from_github_importer.png
 create mode 100644 doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png
 create mode 100644 doc/user/workflow/importing/import_projects_from_bitbucket.md
 create mode 100644 doc/user/workflow/importing/import_projects_from_fogbugz.md
 create mode 100644 doc/user/workflow/importing/import_projects_from_github.md
 create mode 100644 doc/user/workflow/importing/import_projects_from_gitlab_com.md
 create mode 100644 doc/user/workflow/importing/migrating_from_svn.md
 create mode 100644 doc/user/workflow/labels.md
 create mode 100644 doc/user/workflow/labels/label1.png
 create mode 100644 doc/user/workflow/labels/label2.png
 create mode 100644 doc/user/workflow/labels/label3.png
 create mode 100644 doc/user/workflow/lfs/lfs_administration.md
 create mode 100644 doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md
 create mode 100644 doc/user/workflow/merge_commits.png
 create mode 100644 doc/user/workflow/merge_request.png
 create mode 100644 doc/user/workflow/merge_requests.md
 create mode 100644 doc/user/workflow/merge_requests/commit_compare.png
 create mode 100644 doc/user/workflow/merge_requests/merge_request_diff.png
 create mode 100644 doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png
 create mode 100644 doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png
 create mode 100644 doc/user/workflow/merge_when_build_succeeds.md
 create mode 100644 doc/user/workflow/merge_when_build_succeeds/enable.png
 create mode 100644 doc/user/workflow/merge_when_build_succeeds/status.png
 create mode 100644 doc/user/workflow/messy_flow.png
 create mode 100644 doc/user/workflow/milestones.md
 create mode 100644 doc/user/workflow/milestones/form.png
 create mode 100644 doc/user/workflow/milestones/group_form.png
 create mode 100644 doc/user/workflow/mr_inline_comments.png
 create mode 100644 doc/user/workflow/notifications.md
 create mode 100644 doc/user/workflow/notifications/settings.png
 create mode 100644 doc/user/workflow/production_branch.png
 create mode 100644 doc/user/workflow/project_features.md
 create mode 100644 doc/user/workflow/protected_branches.md
 create mode 100644 doc/user/workflow/protected_branches/protected_branches1.png
 create mode 100644 doc/user/workflow/protected_branches/protected_branches2.png
 create mode 100644 doc/user/workflow/rebase.png
 create mode 100644 doc/user/workflow/release_branches.png
 create mode 100644 doc/user/workflow/releases.md
 create mode 100644 doc/user/workflow/releases/new_tag.png
 create mode 100644 doc/user/workflow/releases/tags.png
 create mode 100644 doc/user/workflow/remove_checkbox.png
 create mode 100644 doc/user/workflow/revert_changes.md
 create mode 100644 doc/user/workflow/share_projects_with_other_groups.md
 create mode 100644 doc/user/workflow/share_with_group.md
 create mode 100644 doc/user/workflow/share_with_group.png
 create mode 100644 doc/user/workflow/shortcuts.md
 create mode 100644 doc/user/workflow/shortcuts.png
 create mode 100644 doc/user/workflow/timezone.md
 create mode 100644 doc/user/workflow/todos.md
 create mode 100644 doc/user/workflow/web_editor.md
 create mode 100644 doc/user/workflow/wip_merge_requests.md
 create mode 100644 doc/user/workflow/wip_merge_requests/blocked_accept_button.png
 create mode 100644 doc/user/workflow/wip_merge_requests/mark_as_wip.png
 create mode 100644 doc/user/workflow/wip_merge_requests/unmark_as_wip.png
 create mode 100644 doc/user/workflow/workflow.md

(limited to 'doc/user')

diff --git a/doc/user/gitlab-basics/README.md b/doc/user/gitlab-basics/README.md
new file mode 100644
index 00000000000..3aa83975ace
--- /dev/null
+++ b/doc/user/gitlab-basics/README.md
@@ -0,0 +1,15 @@
+# GitLab basics
+
+Step-by-step guides on the basics of working with Git and GitLab.
+
+- [Start using Git on the command line](start-using-git.md)
+- [Create and add your SSH Keys](create-your-ssh-keys.md)
+- [Command Line basics](command-line-commands.md)
+- [Create a project](create-project.md)
+- [Create a group](create-group.md)
+- [Create a branch](create-branch.md)
+- [Fork a project](fork-project.md)
+- [Add a file](add-file.md)
+- [Add an image](add-image.md)
+- [Create a Merge Request](add-merge-request.md)
+- [Create an Issue](create-issue.md)
diff --git a/doc/user/gitlab-basics/add-file.md b/doc/user/gitlab-basics/add-file.md
new file mode 100644
index 00000000000..57136ac5c39
--- /dev/null
+++ b/doc/user/gitlab-basics/add-file.md
@@ -0,0 +1,31 @@
+# How to add a file
+
+You can create a file in your [shell](command-line-commands.md) or in GitLab.
+
+To create a file in GitLab, sign in to GitLab.
+
+Select a project on the right side of your screen:
+
+![Select a project](basicsimages/select_project.png)
+
+It's a good idea to [create a branch](create-branch.md), but it's not necessary.
+
+Go to the directory where you'd like to add the file and click on the "+" sign next to the name of the project and directory:
+
+![Create a file](basicsimages/create_file.png)
+
+Name your file (you can't add spaces, so you can use hyphens or underscores). Don't forget to include the markup language you'd like to use :
+
+![File name](basicsimages/file_name.png)
+
+Add all the information that you'd like to include in your file:
+
+![Add information](basicsimages/white_space.png)
+
+Add a commit message based on what you just added and then click on "commit changes":
+
+![Commit changes](basicsimages/commit_changes.png)
+
+### Note
+Besides its regular files, every directory needs a README.md or README.html file which works like an index, telling
+what the directory is about. It's the first document you'll find when you open a directory.
diff --git a/doc/user/gitlab-basics/add-image.md b/doc/user/gitlab-basics/add-image.md
new file mode 100644
index 00000000000..476b48a217c
--- /dev/null
+++ b/doc/user/gitlab-basics/add-image.md
@@ -0,0 +1,62 @@
+# How to add an image
+
+The following are the steps to add images to your repository in
+GitLab:
+
+Find the image that you’d like to add.
+
+In your computer files, find the GitLab project to which you'd like to add the image
+(you'll find it as a regular file). Click on every file until you find exactly where you'd
+like to add the image. There, paste the image.
+
+Go to your [shell](command-line-commands.md), and add the following commands:
+
+Add this command for every directory that you'd like to open:
+```
+cd NAME-OF-FILE-YOU'D-LIKE-TO-OPEN
+```
+
+Create a new branch:
+```
+git checkout -b NAME-OF-BRANCH
+```
+
+Check if your image was correctly added to the directory:
+```
+ls
+```
+
+You should see the name of the image in the list shown.
+
+Move up the hierarchy through directories:
+```
+cd ../
+```
+
+Check the status and you should see your image’s name in red:
+```
+git status
+```
+
+Add your changes:
+```
+git add NAME-OF-YOUR-IMAGE
+```
+
+Check the status and you should see your image’s name in green:
+```
+git status
+```
+
+Add the commit:
+```
+git commit -m “DESCRIBE COMMIT IN A FEW WORDS”
+```
+
+Now you can push (send) your changes (in the branch NAME-OF-BRANCH) to GitLab (the git remote named 'origin'):
+```
+git push origin NAME-OF-BRANCH
+```
+
+Your image will be added to your branch in your repository in GitLab. Create a [Merge Request](add-merge-request.md)
+to integrate your changes to your project.
diff --git a/doc/user/gitlab-basics/add-merge-request.md b/doc/user/gitlab-basics/add-merge-request.md
new file mode 100644
index 00000000000..236b4248ea2
--- /dev/null
+++ b/doc/user/gitlab-basics/add-merge-request.md
@@ -0,0 +1,42 @@
+# How to create a merge request
+
+Merge Requests are useful to integrate separate changes that you've made to a project, on different branches.
+
+To create a new Merge Request, sign in to GitLab.
+
+Go to the project where you'd like to merge your changes:
+
+![Select a project](basicsimages/select_project.png)
+
+Click on "Merge Requests" on the left side of your screen:
+
+![Merge requests](basicsimages/merge_requests.png)
+
+Click on "+ new Merge Request" on the right side of the screen:
+
+![New Merge Request](basicsimages/new_merge_request.png)
+
+Select a source branch or branch:
+
+![Select a branch](basicsimages/select_branch.png)
+
+Click on the "compare branches" button:
+
+![Compare branches](basicsimages/compare_branches.png)
+
+Add a title and a description to your Merge Request:
+
+![Add a title and description](basicsimages/title_description_mr.png)
+
+Select a user to review your Merge Request and to accept or close it. You may also select milestones and labels (they are optional). Then click on the "submit new Merge Request" button:
+
+![Add a new merge request](basicsimages/add_new_merge_request.png)
+
+Your Merge Request will be ready to be approved and published.
+
+### Note
+
+After you created a new branch, you'll immediately find a "create a Merge Request" button at the top of your screen.
+You may automatically create a Merge Request from your recently created branch when clicking on this button:
+
+![Automatic MR button](basicsimages/button-create-mr.png)
diff --git a/doc/user/gitlab-basics/basic-git-commands.md b/doc/user/gitlab-basics/basic-git-commands.md
new file mode 100644
index 00000000000..c2a3415cbc4
--- /dev/null
+++ b/doc/user/gitlab-basics/basic-git-commands.md
@@ -0,0 +1,3 @@
+# Basic Git commands
+
+This section is now merged into [Start using Git](start-using-git.md).
diff --git a/doc/user/gitlab-basics/basicsimages/add_new_merge_request.png b/doc/user/gitlab-basics/basicsimages/add_new_merge_request.png
new file mode 100644
index 00000000000..9d93b217a59
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/add_new_merge_request.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/add_sshkey.png b/doc/user/gitlab-basics/basicsimages/add_sshkey.png
new file mode 100644
index 00000000000..2dede97aa40
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/add_sshkey.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/branch_info.png b/doc/user/gitlab-basics/basicsimages/branch_info.png
new file mode 100644
index 00000000000..c5e38b552a5
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/branch_info.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/branch_name.png b/doc/user/gitlab-basics/basicsimages/branch_name.png
new file mode 100644
index 00000000000..06e77f5eea9
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/branch_name.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/branches.png b/doc/user/gitlab-basics/basicsimages/branches.png
new file mode 100644
index 00000000000..c18fa83b968
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/branches.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/button-create-mr.png b/doc/user/gitlab-basics/basicsimages/button-create-mr.png
new file mode 100644
index 00000000000..457af459bb9
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/button-create-mr.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/click-on-new-group.png b/doc/user/gitlab-basics/basicsimages/click-on-new-group.png
new file mode 100644
index 00000000000..94b6d5756d3
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/click-on-new-group.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/commit_changes.png b/doc/user/gitlab-basics/basicsimages/commit_changes.png
new file mode 100644
index 00000000000..81588336f37
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/commit_changes.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/commit_message.png b/doc/user/gitlab-basics/basicsimages/commit_message.png
new file mode 100644
index 00000000000..0df2c32653c
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/commit_message.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/commits.png b/doc/user/gitlab-basics/basicsimages/commits.png
new file mode 100644
index 00000000000..7e606539077
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/commits.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/compare_branches.png b/doc/user/gitlab-basics/basicsimages/compare_branches.png
new file mode 100644
index 00000000000..7eebaed9075
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/compare_branches.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/create_file.png b/doc/user/gitlab-basics/basicsimages/create_file.png
new file mode 100644
index 00000000000..688e355cca2
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/create_file.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/create_group.png b/doc/user/gitlab-basics/basicsimages/create_group.png
new file mode 100644
index 00000000000..57da898abdc
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/create_group.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/edit_file.png b/doc/user/gitlab-basics/basicsimages/edit_file.png
new file mode 100644
index 00000000000..afa68760108
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/edit_file.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/file_located.png b/doc/user/gitlab-basics/basicsimages/file_located.png
new file mode 100644
index 00000000000..1def489d16b
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/file_located.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/file_name.png b/doc/user/gitlab-basics/basicsimages/file_name.png
new file mode 100644
index 00000000000..9ac2f1c355f
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/file_name.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/find_file.png b/doc/user/gitlab-basics/basicsimages/find_file.png
new file mode 100644
index 00000000000..98639149a39
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/find_file.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/find_group.png b/doc/user/gitlab-basics/basicsimages/find_group.png
new file mode 100644
index 00000000000..5ac33c7e953
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/find_group.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/fork.png b/doc/user/gitlab-basics/basicsimages/fork.png
new file mode 100644
index 00000000000..b1f94938613
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/fork.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/group_info.png b/doc/user/gitlab-basics/basicsimages/group_info.png
new file mode 100644
index 00000000000..e78d84e4d80
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/group_info.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/groups.png b/doc/user/gitlab-basics/basicsimages/groups.png
new file mode 100644
index 00000000000..b8104343afa
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/groups.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/https.png b/doc/user/gitlab-basics/basicsimages/https.png
new file mode 100644
index 00000000000..2a31b4cf751
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/https.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/image_file.png b/doc/user/gitlab-basics/basicsimages/image_file.png
new file mode 100644
index 00000000000..1061d9c5082
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/image_file.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/issue_title.png b/doc/user/gitlab-basics/basicsimages/issue_title.png
new file mode 100644
index 00000000000..7b69c705392
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/issue_title.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/issues.png b/doc/user/gitlab-basics/basicsimages/issues.png
new file mode 100644
index 00000000000..9354d05319e
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/issues.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/key.png b/doc/user/gitlab-basics/basicsimages/key.png
new file mode 100644
index 00000000000..321805cda98
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/key.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/merge_requests.png b/doc/user/gitlab-basics/basicsimages/merge_requests.png
new file mode 100644
index 00000000000..7601d40de47
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/merge_requests.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/new_issue.png b/doc/user/gitlab-basics/basicsimages/new_issue.png
new file mode 100644
index 00000000000..94e7503dd8b
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/new_issue.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/new_merge_request.png b/doc/user/gitlab-basics/basicsimages/new_merge_request.png
new file mode 100644
index 00000000000..9120d2b1ab1
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/new_merge_request.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/new_project.png b/doc/user/gitlab-basics/basicsimages/new_project.png
new file mode 100644
index 00000000000..ac255270a66
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/new_project.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/newbranch.png b/doc/user/gitlab-basics/basicsimages/newbranch.png
new file mode 100644
index 00000000000..da1a6b604ea
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/newbranch.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/paste_sshkey.png b/doc/user/gitlab-basics/basicsimages/paste_sshkey.png
new file mode 100644
index 00000000000..9880ddfead1
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/paste_sshkey.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/profile_settings.png b/doc/user/gitlab-basics/basicsimages/profile_settings.png
new file mode 100644
index 00000000000..5f2e7a7e10c
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/profile_settings.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/project_info.png b/doc/user/gitlab-basics/basicsimages/project_info.png
new file mode 100644
index 00000000000..6c06ff351fa
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/project_info.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/public_file_link.png b/doc/user/gitlab-basics/basicsimages/public_file_link.png
new file mode 100644
index 00000000000..1a60a3d880a
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/public_file_link.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/select-group.png b/doc/user/gitlab-basics/basicsimages/select-group.png
new file mode 100644
index 00000000000..d02c2255ff2
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/select-group.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/select-group2.png b/doc/user/gitlab-basics/basicsimages/select-group2.png
new file mode 100644
index 00000000000..fd40bce499b
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/select-group2.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/select_branch.png b/doc/user/gitlab-basics/basicsimages/select_branch.png
new file mode 100644
index 00000000000..3475b2df576
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/select_branch.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/select_project.png b/doc/user/gitlab-basics/basicsimages/select_project.png
new file mode 100644
index 00000000000..6d5aa439124
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/select_project.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/settings.png b/doc/user/gitlab-basics/basicsimages/settings.png
new file mode 100644
index 00000000000..9bf9c5a0d39
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/settings.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/shh_keys.png b/doc/user/gitlab-basics/basicsimages/shh_keys.png
new file mode 100644
index 00000000000..d7ef4dafe77
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/shh_keys.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/submit_new_issue.png b/doc/user/gitlab-basics/basicsimages/submit_new_issue.png
new file mode 100644
index 00000000000..18944417085
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/submit_new_issue.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/title_description_mr.png b/doc/user/gitlab-basics/basicsimages/title_description_mr.png
new file mode 100644
index 00000000000..e08eb628414
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/title_description_mr.png differ
diff --git a/doc/user/gitlab-basics/basicsimages/white_space.png b/doc/user/gitlab-basics/basicsimages/white_space.png
new file mode 100644
index 00000000000..6363a09360e
Binary files /dev/null and b/doc/user/gitlab-basics/basicsimages/white_space.png differ
diff --git a/doc/user/gitlab-basics/command-line-commands.md b/doc/user/gitlab-basics/command-line-commands.md
new file mode 100644
index 00000000000..addd3b6b6eb
--- /dev/null
+++ b/doc/user/gitlab-basics/command-line-commands.md
@@ -0,0 +1,79 @@
+# Command Line basic commands
+
+## Start working on your project
+
+In Git, when you copy a project you say you "clone" it. To work on a git project locally (from your own computer), you will need to clone it. To do this, sign in to GitLab.
+
+When you are on your Dashboard, click on the project that you'd like to clone, which you'll find at the right side of your screen.
+
+![Select a project](basicsimages/select_project.png)
+
+To work in the project, you can copy a link to the Git repository through a SSH or a HTTPS protocol. SSH is easier to use after it's been [setup](create-your-ssh-keys.md). When you're in the project, click on the HTTPS or SSH button at the right side of your screen. Then copy the link (you'll have to paste it on your shell in the next step).
+
+![Copy the HTTPS or SSH](basicsimages/https.png)
+
+## On the command line
+
+### Clone your project
+Go to your computer's shell and type the following command:
+```
+git clone PASTE HTTPS OR SSH HERE
+```
+
+A clone of the project will be created in your computer.
+
+### Go into a project, directory or file to work in it
+```
+cd NAME-OF-PROJECT-OR-FILE
+```
+
+### Go back one directory or file
+```
+cd ../
+```
+
+### View what’s in the directory that you are in
+```
+ls
+```
+
+### Create a directory
+```
+mkdir NAME-OF-YOUR-DIRECTORY
+```
+
+### Create a README.md or file in directory
+```
+touch README.md
+nano README.md
+#### ADD YOUR INFORMATION
+#### Press: control + X
+#### Type: Y
+#### Press: enter
+```
+
+### Remove a file
+```
+rm NAME-OF-FILE
+```
+
+### Remove a directory and all of its contents
+```
+rm -rf NAME-OF-DIRECTORY
+```
+
+### View history in the command line
+```
+history
+```
+
+### Carry out commands for which the account you are using lacks authority
+You will be asked for an administrator’s password.
+```
+sudo
+```
+
+### Tell where you are
+```
+pwd
+```
diff --git a/doc/user/gitlab-basics/create-branch.md b/doc/user/gitlab-basics/create-branch.md
new file mode 100644
index 00000000000..7556b0f663e
--- /dev/null
+++ b/doc/user/gitlab-basics/create-branch.md
@@ -0,0 +1,39 @@
+# How to create a branch
+
+A branch is an independent line of development.
+
+New commits are recorded in the history for the current branch, which results in taking the source from someone’s repository (the place where the history of your work is stored) at certain point in time, and apply your own changes to it in the history of the project.
+
+To add changes to your GitLab project, you should create a branch. You can do it in your [shell](basic-git-commands.md) or in GitLab.
+
+To create a new branch in GitLab, sign in and then select a project on the right side of your screen:
+
+![Select a project](basicsimages/select_project.png)
+
+Click on "commits" on the menu on the left side of your screen:
+
+![Commits](basicsimages/commits.png)
+
+Click on the "branches" tab:
+
+![Branches](basicsimages/branches.png)
+
+Click on the "new branch" button on the right side of the screen:
+
+![New branch](basicsimages/newbranch.png)
+
+Fill out the information required:
+
+1. Add a name for your new branch (you can't add spaces, so you can use hyphens or underscores)
+
+1. On the "create from" space, add the the name of the branch you want to branch off from
+
+1. Click on the button "create branch"
+
+![Branch info](basicsimages/branch_info.png)
+
+### Note:
+
+You will be able to find and select the name of your branch in the white box next to a project's name:
+
+![Branch name](basicsimages/branch_name.png)
diff --git a/doc/user/gitlab-basics/create-group.md b/doc/user/gitlab-basics/create-group.md
new file mode 100644
index 00000000000..f80ae62e442
--- /dev/null
+++ b/doc/user/gitlab-basics/create-group.md
@@ -0,0 +1,43 @@
+# How to create a group in GitLab
+
+## Create a group
+
+Your projects in GitLab can be organized in 2 different ways:
+under your own namespace for single projects, such as ´your-name/project-1'; or under groups.
+If you organize your projects under a group, it works like a folder. You can manage your group members' permissions and access to the projects.
+
+To create a group, follow the instructions below:
+
+Sign in to [GitLab.com](https://gitlab.com).
+
+When you are on your Dashboard, click on "Groups" on the left menu of your screen:
+
+![Go to groups](basicsimages/select-group2.png)
+
+Click on "New group" on the top right side of your screen:
+
+![New group](basicsimages/click-on-new-group.png)
+
+Fill out the information required:
+
+1. Add a group path or group name (you can't add spaces, so you can use hyphens or underscores)
+
+1. Add details or a group description
+
+1. You can choose a group avatar if you'd like
+
+1. Click on "create group"
+
+![Group information](basicsimages/group_info.png)
+
+## Add a project to a group
+
+There are 2 different ways to add a new project to a group:
+
+* Select a group and then click on "New project" on the right side of your screen. Then you can [create a project](create-project.md)
+
+![New project](basicsimages/new_project.png)
+
+* When you are [creating a project](create-project.md), click on "create a group" on the bottom right side of your screen
+
+![Create a group](basicsimages/create_group.png)
diff --git a/doc/user/gitlab-basics/create-issue.md b/doc/user/gitlab-basics/create-issue.md
new file mode 100644
index 00000000000..5221d85b661
--- /dev/null
+++ b/doc/user/gitlab-basics/create-issue.md
@@ -0,0 +1,27 @@
+# How to create an Issue in GitLab
+
+The Issue Tracker is a good place to add things that need to be improved or solved in a project.  
+
+To create an Issue, sign in to GitLab.
+
+Go to the project where you'd like to create the Issue:
+
+![Select a project](basicsimages/select_project.png)
+
+Click on "Issues" on the left side of your screen:
+
+![Issues](basicsimages/issues.png)
+
+Click on the "+ new issue" button on the right side of your screen:
+
+![New issue](basicsimages/new_issue.png)
+
+Add a title and a description to your issue:
+
+![Issue title and description](basicsimages/issue_title.png)
+
+You may assign the Issue to a user, add a milestone and add labels (they are all optional). Then click on "submit new issue":
+
+![Submit new issue](basicsimages/submit_new_issue.png)
+
+Your Issue will now be added to the Issue Tracker and will be ready to be reviewed. You can comment on it and mention the people involved. You can also link Issues to the Merge Requests where the Issues are solved. To do this, you can use an [Issue closing pattern](http://docs.gitlab.com/ce/customization/issue_closing.html).
diff --git a/doc/user/gitlab-basics/create-project.md b/doc/user/gitlab-basics/create-project.md
new file mode 100644
index 00000000000..f737dffc024
--- /dev/null
+++ b/doc/user/gitlab-basics/create-project.md
@@ -0,0 +1,21 @@
+# How to create a project in GitLab
+
+To create a new project, sign in to GitLab.
+
+Go to your Dashboard and click on "new project" on the right side of your screen.
+
+![Create a project](basicsimages/new_project.png)
+
+Fill out the required information:
+
+1. Project path or the name of your project (you can't add spaces, so you can use hyphens or underscores)
+
+1. Your project's description
+
+1. Select a [visibility level](https://gitlab.com/help/public_access/public_access)
+
+1. You can also [import your existing projects](http://docs.gitlab.com/ce/workflow/importing/README.html)
+
+1. Click on "create project"
+
+!![Project information](basicsimages/project_info.png)
diff --git a/doc/user/gitlab-basics/create-your-ssh-keys.md b/doc/user/gitlab-basics/create-your-ssh-keys.md
new file mode 100644
index 00000000000..f31c353f2cf
--- /dev/null
+++ b/doc/user/gitlab-basics/create-your-ssh-keys.md
@@ -0,0 +1,33 @@
+# How to create your SSH Keys
+
+You need to connect your computer to your GitLab account through SSH Keys. They are unique for every computer that you link your GitLab account with.
+
+## Generate your SSH Key
+
+Create an account on GitLab. Sign up and check your email for your confirmation link.
+
+After you confirm, go to GitLab and sign in to your account.
+
+## Add your SSH Key
+
+On the left side menu, click on "profile settings" and then click on "SSH Keys":
+
+![SSH Keys](basicsimages/shh_keys.png)
+
+Then click on the green button "Add SSH Key":
+
+![Add SSH Key](basicsimages/add_sshkey.png)
+
+There, you should paste the SSH Key that your command line will generate for you. Below you'll find the steps to generate it:
+
+![Paste SSH Key](basicsimages/paste_sshkey.png)
+
+## To generate an SSH Key on your command line
+
+Go to your [command line](start-using-git.md) and follow the [instructions](../ssh/README.md) to generate it.
+
+Copy the SSH Key that your command line created and paste it on the "Key" box on the GitLab page. The title will be added automatically.
+
+![Paste SSH Key](basicsimages/key.png)
+
+Now, you'll be able to use Git over SSH, instead of Git over HTTP.
diff --git a/doc/user/gitlab-basics/fork-project.md b/doc/user/gitlab-basics/fork-project.md
new file mode 100644
index 00000000000..5f8b81ea919
--- /dev/null
+++ b/doc/user/gitlab-basics/fork-project.md
@@ -0,0 +1,19 @@
+# How to fork a project
+
+A fork is a copy of an original repository that you can put somewhere else
+or where you can experiment and apply changes that you can later decide if
+publishing or not, without affecting your original project.
+
+It takes just a few steps to fork a project in GitLab.
+
+Sign in to GitLab.
+
+Select a project on the right side of your screen:
+
+![Select a project](basicsimages/select_project.png)
+
+Click on the "fork" button on the right side of your screen:
+
+![Fork](basicsimages/fork.png)
+
+Click on the user or group to where you'd like to add the forked project.
diff --git a/doc/user/gitlab-basics/start-using-git.md b/doc/user/gitlab-basics/start-using-git.md
new file mode 100644
index 00000000000..89ce8bcc3e8
--- /dev/null
+++ b/doc/user/gitlab-basics/start-using-git.md
@@ -0,0 +1,122 @@
+# Start using Git on the command line
+
+If you want to start using a Git and GitLab, make sure that you have created an
+account on GitLab.
+
+## Open a shell
+
+Depending on your operating system, find the shell of your preference. Here are some suggestions.
+
+- [Terminal](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line) on  Mac OSX
+
+- [GitBash](https://msysgit.github.io) on Windows
+
+- [Linux Terminal](http://www.howtogeek.com/140679/beginner-geek-how-to-start-using-the-linux-terminal/) on Linux
+
+## Check if Git has already been installed
+
+Git is usually preinstalled on Mac and Linux.
+
+Type the following command and then press enter:
+```
+git --version
+```
+
+You should receive a message that will tell you which Git version you have in your computer. If you don’t receive a "Git version" message, it means that you need to [download Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+If Git doesn't automatically download, there's an option on the website to [download manually](https://git-scm.com/downloads). Then follow the steps on the installation window.
+
+After you finished installing, open a new shell and type "git --version" again to verify that it was correctly installed.
+
+## Add your Git username and set your email
+
+It is important because every Git commit that you create will use this information.
+
+On your shell, type the following command to add your username:
+```
+git config --global user.name ADD YOUR USERNAME
+```
+
+Then verify that you have the correct username:
+```
+git config --global user.name
+```
+
+To set your email address, type the following command:
+```
+git config --global user.email ADD YOUR EMAIL
+```
+
+To verify that you entered your email correctly, type:
+```
+git config --global user.email
+```
+
+You'll need to do this only once because you are using the "--global" option. It tells Git to always use this information for anything you do on that system. If you want to override this with a different username or email address for specific projects, you can run the command without the "--global" option when you’re in that project.
+
+## Check your information
+
+To view the information that you entered, type:
+```
+git config --global --list
+```
+## Basic Git commands
+
+### Go to the master branch to pull the latest changes from there
+
+```
+git checkout master
+```
+
+### Download the latest changes in the project
+This is for you to work on an up-to-date copy (it is important to do every time you work on a project), while you setup tracking branches.
+```
+git pull REMOTE NAME-OF-BRANCH -u
+```
+(REMOTE: origin) (NAME-OF-BRANCH: could be "master" or an existing branch)
+
+### Create a branch
+Spaces won't be recognized, so you need to use a hyphen or underscore.
+```
+git checkout -b NAME-OF-BRANCH
+```
+
+### Work on a branch that has already been created
+```
+git checkout NAME-OF-BRANCH
+```
+
+### View the changes you've made
+It's important to be aware of what's happening and what's the status of your changes.
+```
+git status
+```
+
+### Add changes to commit
+You'll see your changes in red when you type "git status".
+```
+git add CHANGES IN RED
+git commit -m "DESCRIBE THE INTENTION OF THE COMMIT"
+```
+
+### Send changes to gitlab.com
+```
+git push REMOTE NAME-OF-BRANCH
+```
+
+### Delete all changes in the Git repository, but leave unstaged things
+```
+git checkout .
+```
+
+### Delete all changes in the Git repository, including untracked files
+```
+git clean -f
+```
+
+### Merge created branch with master branch
+You need to be in the created branch.
+```
+git checkout NAME-OF-BRANCH
+git merge master
+```
diff --git a/doc/user/markdown/img/logo.png b/doc/user/markdown/img/logo.png
new file mode 100644
index 00000000000..7da5f23ed9b
Binary files /dev/null and b/doc/user/markdown/img/logo.png differ
diff --git a/doc/user/markdown/markdown.md b/doc/user/markdown/markdown.md
new file mode 100644
index 00000000000..236eb7b12c4
--- /dev/null
+++ b/doc/user/markdown/markdown.md
@@ -0,0 +1,615 @@
+# Markdown
+
+## Table of Contents
+
+**[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)**
+
+* [Newlines](#newlines)
+* [Multiple underscores in words](#multiple-underscores-in-words)
+* [URL auto-linking](#url-auto-linking)
+* [Code and Syntax Highlighting](#code-and-syntax-highlighting)
+* [Inline Diff](#inline-diff)
+* [Emoji](#emoji)
+* [Special GitLab references](#special-gitlab-references)
+* [Task lists](#task-lists)
+
+**[Standard Markdown](#standard-markdown)**
+
+* [Headers](#headers)
+* [Emphasis](#emphasis)
+* [Lists](#lists)
+* [Links](#links)
+* [Images](#images)
+* [Blockquotes](#blockquotes)
+* [Inline HTML](#inline-html)
+* [Horizontal Rule](#horizontal-rule)
+* [Line Breaks](#line-breaks)
+* [Tables](#tables)
+
+**[References](#references)**
+
+## GitLab Flavored Markdown (GFM)
+
+_GitLab uses the [Redcarpet Ruby library][redcarpet] for Markdown processing._
+
+GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
+
+You can use GFM in
+
+- comments
+- issues
+- merge requests
+- milestones
+- wiki pages
+
+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.
+
+## Newlines
+
+GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p).
+
+A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.
+Line-breaks, or softreturns, are rendered if you end a line with two or more spaces
+
+    Roses are red [followed by two or more spaces]
+    Violets are blue
+
+    Sugar is sweet
+
+Roses are red  
+Violets are blue
+
+Sugar is sweet
+
+## 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
+    do_this_and_do_that_and_another_thing
+
+perform_complicated_task
+do_this_and_do_that_and_another_thing
+
+## URL auto-linking
+
+GFM will autolink almost any URL you copy and paste into your text.
+
+    * https://www.google.com
+    * https://google.com/
+    * ftp://ftp.us.debian.org/debian/
+    * smb://foo/bar/baz
+    * irc://irc.freenode.net/gitlab
+    * http://localhost:3000
+
+* https://www.google.com
+* https://google.com/
+* ftp://ftp.us.debian.org/debian/
+* smb://foo/bar/baz
+* irc://irc.freenode.net/gitlab
+* http://localhost:3000
+
+## Code and Syntax Highlighting
+
+_GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a
+list of supported languages visit the Rouge website._
+
+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.
+```
+
+Inline `code` has `back-ticks around` it.
+
+Example:
+
+    ```javascript
+    var s = "JavaScript syntax highlighting";
+    alert(s);
+    ```
+
+    ```python
+    def function():
+        #indenting works just fine in the fenced code block
+        s = "Python syntax highlighting"
+        print s
+    ```
+
+    ```ruby
+    require 'redcarpet'
+    markdown = Redcarpet.new("Hello World!")
+    puts markdown.to_html
+    ```
+
+    ```
+    No language indicated, so no syntax highlighting.
+    s = "There is no highlighting for this."
+    But let's throw in a <b>tag</b>.
+    ```
+
+becomes:
+
+```javascript
+var s = "JavaScript syntax highlighting";
+alert(s);
+```
+
+```python
+def function():
+    #indenting works just fine in the fenced code block
+    s = "Python syntax highlighting"
+    print s
+```
+
+```ruby
+require 'redcarpet'
+markdown = Redcarpet.new("Hello World!")
+puts markdown.to_html
+```
+
+```
+No language indicated, so no syntax highlighting.
+s = "There is no highlighting for this."
+But let's throw in a <b>tag</b>.
+```
+
+## Inline Diff
+
+With inline diffs tags you can display {+ additions +} or [- deletions -].
+
+The wrapping tags can be either curly braces or square brackets [+ additions +] or {- deletions -}.
+
+However the wrapping tags cannot be mixed as such:
+
+- {+ additions +]
+- [+ additions +}
+- {- deletions -]
+- [- deletions -}
+
+## Emoji
+
+	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:
+
+	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 on the supported codes.
+
+	Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup:
+
+Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
+
+: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.
+
+If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes.
+
+Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup:
+
+## Special GitLab References
+
+GFM recognizes special references.
+
+You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project.
+
+GFM will turn that reference into a link so you can navigate between them easily.
+
+GFM will recognize the following:
+
+| input                  | references                   |
+|:-----------------------|:---------------------------  |
+| `@user_name`           | specific user                |
+| `@group_name`          | specific group               |
+| `@all`                 | entire team                  |
+| `#123`                 | issue                        |
+| `!123`                 | merge request                |
+| `$123`                 | snippet                      |
+| `~123`                 | label by ID                  |
+| `~bug`                 | one-word label by name       |
+| `~"feature request"`   | multi-word label by name     |
+| `%123`                 | milestone by ID              |
+| `%v1.23`               | one-word milestone by name   |
+| `%"release candidate"` | multi-word milestone by name |
+| `9ba12248`             | specific commit              |
+| `9ba12248...b19a04f5`  | commit range comparison      |
+| `[README](doc/README)` | repository file references   |
+
+GFM also recognizes certain cross-project references:
+
+| input                                   | references              |
+|:----------------------------------------|:------------------------|
+| `namespace/project#123`                 | issue                   |
+| `namespace/project!123`                 | merge request           |
+| `namespace/project%123`                 | milestone               |
+| `namespace/project$123`                 | snippet                 |
+| `namespace/project@9ba12248`            | specific commit         |
+| `namespace/project@9ba12248...b19a04f5` | commit range comparison |
+| `namespace/project~"Some label"`        | issues with given label |
+
+## 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
+    - [x] Sub-task 2
+    - [ ] Sub-task 3
+```
+
+- [x] Completed task
+- [ ] Incomplete task
+    - [ ] Sub-task 1
+    - [x] Sub-task 2
+    - [ ] Sub-task 3
+
+Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes.
+
+# Standard Markdown
+
+## Headers
+
+```no-highlight
+# H1
+## H2
+### H3
+#### H4
+##### H5
+###### H6
+
+Alternatively, for H1 and H2, an underline-ish style:
+
+Alt-H1
+======
+
+Alt-H2
+------
+```
+
+# H1
+## H2
+### H3
+#### H4
+##### H5
+###### H6
+
+Alternatively, for H1 and H2, an underline-ish style:
+
+Alt-H1
+======
+
+Alt-H2
+------
+
+### Header IDs and links
+
+All Markdown-rendered headers automatically get IDs, except in comments.
+
+On hover a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else.
+
+The IDs are generated from the content of the header according to the following rules:
+
+1. All text is converted to lowercase
+1. All non-word text (e.g., punctuation, HTML) is removed
+1. All spaces are converted to hyphens
+1. Two or more hyphens in a row are converted to one
+1. If a header with the same ID has already been generated, a unique
+   incrementing number is appended, starting at 1.
+
+For example:
+
+```
+# This header has spaces in it
+## This header has a :thumbsup: in it
+# This header has Unicode in it: 한글
+## This header has spaces in it
+### This header has spaces in it
+```
+
+Would generate the following link IDs:
+
+1. `this-header-has-spaces-in-it`
+1. `this-header-has-a-in-it`
+1. `this-header-has-unicode-in-it-한글`
+1. `this-header-has-spaces-in-it`
+1. `this-header-has-spaces-in-it-1`
+
+Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.
+
+## Emphasis
+
+```no-highlight
+Emphasis, aka italics, with *asterisks* or _underscores_.
+
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
+
+Combined emphasis with **asterisks and _underscores_**.
+
+Strikethrough uses two tildes. ~~Scratch this.~~
+```
+
+Emphasis, aka italics, with *asterisks* or _underscores_.
+
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
+
+Combined emphasis with **asterisks and _underscores_**.
+
+Strikethrough uses two tildes. ~~Scratch this.~~
+
+## Lists
+
+```no-highlight
+1. First ordered list item
+2. Another item
+  * Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+  1. Ordered sub-list
+4. And another item.
+
+* Unordered list can use asterisks
+- Or minuses
++ Or pluses
+```
+
+1. First ordered list item
+2. Another item
+  * Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+  1. Ordered sub-list
+4. And another item.
+
+* Unordered list can use asterisks
+- Or minuses
++ Or pluses
+
+If a list item contains multiple paragraphs,
+each subsequent paragraph should be indented with four spaces.
+
+```no-highlight
+1.  First ordered list item
+
+    Second paragraph of first item.
+2.  Another item
+```
+
+1.  First ordered list item
+
+    Second paragraph of first item.
+2.  Another item
+
+If the second paragraph isn't indented with four spaces,
+the second list item will be incorrectly labeled as `1`.
+
+```no-highlight
+1. First ordered list item
+
+   Second paragraph of first item.
+2. Another item
+```
+
+1. First ordered list item
+
+   Second paragraph of first item.
+2. Another item
+
+## Links
+
+There are two ways to create links, inline-style and reference-style.
+
+    [I'm an inline-style link](https://www.google.com)
+
+    [I'm a reference-style link][Arbitrary case-insensitive reference text]
+
+    [I'm a relative reference to a repository file](LICENSE)
+
+    [You can use numbers for reference-style link definitions][1]
+
+    Or leave it empty and use the [link text itself][]
+
+    Some text to show that the reference links can follow later.
+
+    [arbitrary case-insensitive reference text]: https://www.mozilla.org
+    [1]: http://slashdot.org
+    [link text itself]: https://www.reddit.com
+
+[I'm an inline-style link](https://www.google.com)
+
+[I'm a reference-style link][Arbitrary case-insensitive reference text]
+
+[I'm a relative reference to a repository file](LICENSE)[^1]
+
+[You can use numbers for reference-style link definitions][1]
+
+Or leave it empty and use the [link text itself][]
+
+Some text to show that the reference links can follow later.
+
+[arbitrary case-insensitive reference text]: https://www.mozilla.org
+[1]: http://slashdot.org
+[link text itself]: https://www.reddit.com
+
+**Note**
+
+Relative links do not allow referencing project files in a wiki page or wiki page in a project file. The reason for this is that, in GitLab, wiki is always a separate git repository. For example:
+
+`[I'm a reference-style link](style)`
+
+will point the link to `wikis/style` when the link is inside of a wiki markdown file.
+
+## Images
+
+    Here's our logo (hover to see the title text):
+
+    Inline-style:
+    ![alt text](img/logo.png)
+
+    Reference-style:
+    ![alt text1][logo]
+
+    [logo]: img/logo.png
+
+Here's our logo:
+
+Inline-style:
+
+![alt text](img/logo.png)
+
+Reference-style:
+
+![alt text][logo]
+
+[logo]: img/logo.png
+
+## Blockquotes
+
+```no-highlight
+> Blockquotes are very handy in email to emulate reply text.
+> This line is part of the same quote.
+
+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.
+```
+
+> Blockquotes are very handy in email to emulate reply text.
+> This line is part of the same quote.
+
+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.
+
+## Inline HTML
+
+You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
+
+See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes.  In addition to the default `SanitizationFilter` whitelist, GitLab allows `span` elements.
+
+```no-highlight
+<dl>
+  <dt>Definition list</dt>
+  <dd>Is something people use sometimes.</dd>
+
+  <dt>Markdown in HTML</dt>
+  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
+</dl>
+```
+
+<dl>
+  <dt>Definition list</dt>
+  <dd>Is something people use sometimes.</dd>
+
+  <dt>Markdown in HTML</dt>
+  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
+</dl>
+
+## Horizontal Rule
+
+```
+Three or more...
+
+---
+
+Hyphens
+
+***
+
+Asterisks
+
+___
+
+Underscores
+```
+
+Three or more...
+
+---
+
+Hyphens
+
+***
+
+Asterisks
+
+___
+
+Underscores
+
+## Line Breaks
+
+My basic recommendation for learning how line breaks work is to experiment and discover -- hit &lt;Enter&gt; once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend.
+
+Here are some things to try out:
+
+```
+Here's a line for us to start with.
+
+This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
+
+This line is also a separate paragraph, but...
+This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
+
+This line is also a separate paragraph, and...  
+This line is on its own line, because the previous line ends with two
+spaces.
+```
+
+Here's a line for us to start with.
+
+This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
+
+This line is also begins a separate paragraph, but...
+This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
+
+This line is also a separate paragraph, and...  
+This line is on its own line, because the previous line ends with two
+spaces.
+
+## Tables
+
+Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them.
+
+```
+| header 1 | header 2 |
+| -------- | -------- |
+| cell 1   | cell 2   |
+| cell 3   | cell 4   |
+```
+
+Code above produces next output:
+
+| header 1 | header 2 |
+| -------- | -------- |
+| cell 1   | cell 2   |
+| cell 3   | cell 4   |
+
+**Note**
+
+The row of dashes between the table header and body must have at least three dashes in each column.
+
+By including colons in the header row, you can align the text within that column:
+
+```
+| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
+| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
+| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
+| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
+```
+
+| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
+| :----------- | :------: | ------------: | :----------- | :------: | ------------: |
+| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
+| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
+
+## References
+
+- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+- The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
+- [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown.
+
+[rouge]: http://rouge.jneen.net/ "Rouge website"
+[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website"
+[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com
diff --git a/doc/user/permissions/permissions.md b/doc/user/permissions/permissions.md
new file mode 100644
index 00000000000..963b35de3a0
--- /dev/null
+++ b/doc/user/permissions/permissions.md
@@ -0,0 +1,101 @@
+# Permissions
+
+Users have different abilities depending on the access level they have in a particular group or project.
+
+If a user is both in a project group and in the project itself, the highest permission level is used.
+
+If a user is a GitLab administrator they receive all permissions.
+
+On public and internal projects the Guest role is not enforced.
+All users will be able to create issues, leave comments, and pull or download the project code.
+
+To add or import a user, you can follow the [project users and members
+documentation](../workflow/add-user/add-user.md).
+
+## Project
+
+| Action                                | Guest   | Reporter   | Developer   | Master   | Owner  |
+|---------------------------------------|---------|------------|-------------|----------|--------|
+| Create new issue                      | ✓       | ✓          | ✓           | ✓        | ✓      |
+| Leave comments                        | ✓       | ✓          | ✓           | ✓        | ✓      |
+| See a list of builds                  | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| See a build log                       | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| Download and browse build artifacts   | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| Pull project code                     |         | ✓          | ✓           | ✓        | ✓      |
+| Download project                      |         | ✓          | ✓           | ✓        | ✓      |
+| Create code snippets                  |         | ✓          | ✓           | ✓        | ✓      |
+| Manage issue tracker                  |         | ✓          | ✓           | ✓        | ✓      |
+| Manage labels                         |         | ✓          | ✓           | ✓        | ✓      |
+| See a commit status                   |         | ✓          | ✓           | ✓        | ✓      |
+| See a container registry              |         | ✓          | ✓           | ✓        | ✓      |
+| See environments                      |         | ✓          | ✓           | ✓        | ✓      |
+| Manage merge requests                 |         |            | ✓           | ✓        | ✓      |
+| Create new merge request              |         |            | ✓           | ✓        | ✓      |
+| Create new branches                   |         |            | ✓           | ✓        | ✓      |
+| Push to non-protected branches        |         |            | ✓           | ✓        | ✓      |
+| Force push to non-protected branches  |         |            | ✓           | ✓        | ✓      |
+| Remove non-protected branches         |         |            | ✓           | ✓        | ✓      |
+| Add tags                              |         |            | ✓           | ✓        | ✓      |
+| Write a wiki                          |         |            | ✓           | ✓        | ✓      |
+| Cancel and retry builds               |         |            | ✓           | ✓        | ✓      |
+| Create or update commit status        |         |            | ✓           | ✓        | ✓      |
+| Update a container registry           |         |            | ✓           | ✓        | ✓      |
+| Remove a container registry image     |         |            | ✓           | ✓        | ✓      |
+| Create new environments               |         |            | ✓           | ✓        | ✓      |
+| Create new milestones                 |         |            |             | ✓        | ✓      |
+| Add new team members                  |         |            |             | ✓        | ✓      |
+| Push to protected branches            |         |            |             | ✓        | ✓      |
+| Enable/disable branch protection      |         |            |             | ✓        | ✓      |
+| Turn on/off prot. branch push for devs|         |            |             | ✓        | ✓      |
+| Rewrite/remove git tags               |         |            |             | ✓        | ✓      |
+| Edit project                          |         |            |             | ✓        | ✓      |
+| Add deploy keys to project            |         |            |             | ✓        | ✓      |
+| Configure project hooks               |         |            |             | ✓        | ✓      |
+| Manage runners                        |         |            |             | ✓        | ✓      |
+| Manage build triggers                 |         |            |             | ✓        | ✓      |
+| Manage variables                      |         |            |             | ✓        | ✓      |
+| Delete environments                   |         |            |             | ✓        | ✓      |
+| Switch visibility level               |         |            |             |          | ✓      |
+| Transfer project to another namespace |         |            |             |          | ✓      |
+| Remove project                        |         |            |             |          | ✓      |
+| Force push to protected branches [^2] |         |            |             |          |        |
+| Remove protected branches [^2]        |         |            |             |          |        |
+
+[^1]: If **Allow guest to access builds** is enabled in CI settings
+[^2]: Not allowed for Guest, Reporter, Developer, Master, or Owner
+
+## Group
+
+In order for a group to appear as public and be browsable, it must contain at
+least one public project.
+
+Any user can remove themselves from a group, unless they are the last Owner of the group.
+
+| Action                  | Guest | Reporter | Developer | Master | Owner |
+|-------------------------|-------|----------|-----------|--------|-------|
+| Browse group            | ✓     | ✓        | ✓         | ✓      | ✓     |
+| Edit group              |       |          |           |        | ✓     |
+| Create project in group |       |          |           | ✓      | ✓     |
+| Manage group members    |       |          |           |        | ✓     |
+| Remove group            |       |          |           |        | ✓     |
+
+## External Users
+
+In cases where it is desired that a user has access only to some internal or
+private projects, there is the option of creating **External Users**. This
+feature may be useful when for example a contractor is working on a given
+project and should only have access to that project.
+
+External users can only access projects to which they are explicitly granted
+access, thus hiding all other internal or private ones from them. Access can be
+granted by adding the user as member to the project or group.
+
+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
+will find the option to flag the user as external.
diff --git a/doc/user/profile/2fa.png b/doc/user/profile/2fa.png
new file mode 100644
index 00000000000..bbf415210d5
Binary files /dev/null and b/doc/user/profile/2fa.png differ
diff --git a/doc/user/profile/2fa_auth.png b/doc/user/profile/2fa_auth.png
new file mode 100644
index 00000000000..4a4fbe68984
Binary files /dev/null and b/doc/user/profile/2fa_auth.png differ
diff --git a/doc/user/profile/2fa_u2f_authenticate.png b/doc/user/profile/2fa_u2f_authenticate.png
new file mode 100644
index 00000000000..b9138ff60db
Binary files /dev/null and b/doc/user/profile/2fa_u2f_authenticate.png differ
diff --git a/doc/user/profile/2fa_u2f_register.png b/doc/user/profile/2fa_u2f_register.png
new file mode 100644
index 00000000000..15b3683ef73
Binary files /dev/null and b/doc/user/profile/2fa_u2f_register.png differ
diff --git a/doc/user/profile/README.md b/doc/user/profile/README.md
new file mode 100644
index 00000000000..6f8359d87fa
--- /dev/null
+++ b/doc/user/profile/README.md
@@ -0,0 +1,4 @@
+# Profile Settings
+
+- [Preferences](preferences.md)
+- [Two-factor Authentication (2FA)](two_factor_authentication.md)
diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md
new file mode 100644
index 00000000000..073b8797508
--- /dev/null
+++ b/doc/user/profile/preferences.md
@@ -0,0 +1,43 @@
+# Profile Preferences
+
+Settings in the **Profile > Preferences** page allow the user to customize
+various aspects of the site to their liking.
+
+## Application theme
+
+Changing this setting allows the user to customize the color scheme used for the
+navigation bar on the left side of the screen.
+
+The default is **Charcoal**.
+
+## Syntax highlighting theme
+
+_GitLab uses the [rouge ruby library][rouge] for syntax highlighting. For a
+list of supported languages visit the rouge website._
+
+Changing this setting allows the user to customize the theme used when viewing
+syntax highlighted code on the site.
+
+The default is **White**.
+
+## Behavior
+
+### Default Dashboard
+
+For users who have access to a large number of projects but only keep up with a
+select few, the amount of activity on the default Dashboard page can be
+overwhelming.
+
+Changing this setting allows the user to redefine what their default dashboard
+will be. Setting it to **Starred Projects** will make that Dashboard view the
+default when signing in or clicking the application logo in the upper left.
+
+The default is **Your Projects**.
+
+### Default Project view
+
+It allows user to choose what content he or she want to see on project page.
+
+The default is **Readme**.
+
+[rouge]: http://rouge.jneen.net/ "Rouge website"
diff --git a/doc/user/profile/two_factor_authentication.md b/doc/user/profile/two_factor_authentication.md
new file mode 100644
index 00000000000..82505b13401
--- /dev/null
+++ b/doc/user/profile/two_factor_authentication.md
@@ -0,0 +1,127 @@
+# Two-factor Authentication (2FA)
+
+Two-factor Authentication (2FA) provides an additional level of security to your
+GitLab account. Once enabled, in addition to supplying your username and
+password to login, you'll be prompted for a code generated by an application on
+your phone.
+
+By enabling 2FA, the only way someone other than you can log into your account
+is to know your username and password *and* have access to your phone.
+
+> **Note:**
+When you enable 2FA, don't forget to back up your recovery codes. For your safety, if you
+lose your codes for GitLab.com, we can't disable or recover them.  
+
+In addition to a phone application, GitLab supports U2F (universal 2nd factor) devices as
+the second factor of authentication. Once enabled, in addition to supplying your username and
+password to login, you'll be prompted to activate your U2F device (usually by pressing
+a button on it), and it will perform secure authentication on your behalf.
+
+> **Note:** Support for U2F devices was added in version 8.8
+
+The U2F workflow is only supported by Google Chrome at this point, so we _strongly_ recommend 
+that you set up both methods of two-factor authentication, so you can still access your account 
+from other browsers.
+
+> **Note:** GitLab officially only supports [Yubikey] U2F devices.
+
+## Enabling 2FA
+
+### Enable 2FA via mobile application
+
+**In GitLab:**
+
+1. Log in to your GitLab account.
+1. Go to your **Profile Settings**.
+1. Go to **Account**.
+1. Click **Enable Two-factor Authentication**.
+
+![Two-factor setup](2fa.png)
+
+**On your phone:**
+
+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.
+
+**In GitLab:**
+
+1. Enter the six-digit pin number from the entry on your phone into the **Pin
+   code** field.
+1. Click **Submit**.
+
+If the pin you entered was correct, you'll see a message indicating that
+Two-Factor Authentication has been enabled, and you'll be presented with a list
+of recovery codes.
+
+### Enable 2FA via U2F device
+
+**In GitLab:**
+
+1. Log in to your GitLab account.
+1. Go to your **Profile Settings**.
+1. Go to **Account**.
+1. Click **Enable Two-Factor Authentication**.
+1. Plug in your U2F device.
+1. Click on **Setup New U2F Device**.
+1. A light will start blinking on your device. Activate it by pressing its button.
+
+You will see a message indicating that your device was successfully set up. 
+Click on **Register U2F Device** to complete the process.
+
+![Two-Factor U2F Setup](2fa_u2f_register.png)
+
+## Recovery Codes
+
+Should you ever lose access to your phone, you can use one of the ten provided
+backup codes to login to your account. We suggest copying or printing them for
+storage in a safe place. **Each code can be used only once** to log in to your
+account.
+
+If you lose the recovery codes or just want to generate new ones, you can do so
+from the **Profile Settings** > **Account** page where you first enabled 2FA.
+
+> **Note:** Recovery codes are not generated for U2F devices.
+
+## Logging in with 2FA Enabled
+
+Logging in with 2FA enabled is only slightly different than a normal login.
+Enter your username and password credentials as you normally would, and you'll
+be presented with a second prompt, depending on which type of 2FA you've enabled.
+
+### Log in via mobile application
+
+Enter the pin from your phone's application or a recovery code to log in.
+
+![Two-Factor Authentication on sign in via OTP](2fa_auth.png)
+
+### Log in 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.
+Click on **Authenticate via U2F Device** to complete the process.
+
+![Two-Factor Authentication on sign in via U2F device](2fa_u2f_authenticate.png)
+
+## Disabling 2FA
+
+1. Log in to your GitLab account.
+1. Go to your **Profile Settings**.
+1. Go to **Account**.
+1. Click **Disable**, under **Two-Factor Authentication**.
+
+This will clear all your two-factor authentication registrations, including mobile
+applications and U2F devices.
+
+## Note to GitLab administrators
+
+You need to take special care to that 2FA keeps working after
+[restoring a GitLab backup](../raketasks/backup_restore.md).
+
+[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
+[FreeOTP]: https://fedorahosted.org/freeotp/
+[YubiKey]: https://www.yubico.com/products/yubikey-hardware/
diff --git a/doc/user/project/container_registry/README.md b/doc/user/project/container_registry/README.md
new file mode 100644
index 00000000000..1b465434498
--- /dev/null
+++ b/doc/user/project/container_registry/README.md
@@ -0,0 +1,94 @@
+# GitLab Container Registry
+
+> **Note:**
+This feature was [introduced][ce-4040] in GitLab 8.8.
+
+> **Note:**
+This document is about the user guide. To learn how to enable GitLab Container
+Registry across your GitLab instance, visit the
+[administrator documentation](../administration/container_registry.md).
+
+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/.
+
+---
+
+## Enable the Container Registry for your project
+
+1. First, ask your system administrator to enable GitLab Container Registry
+   following the [administration documentation](../administration/container_registry.md).
+   If you are using GitLab.com, this is enabled by default so you can start using
+   the Registry immediately.
+
+1. Go to your project's settings and enable the **Container Registry** feature
+   on your project. For new projects this might be enabled by default. For
+   existing projects you will have to explicitly enable it.
+
+    ![Enable Container Registry](img/project_feature.png)
+
+## Build and push images
+
+After you save your project's settings, you should see a new link in the
+sidebar called **Container Registry**. Following this link will get you to
+your project's Registry panel where you can see how to login to the Container
+Registry using your GitLab credentials.
+
+For example if the Registry's URL is `registry.example.com`, the you should be
+able to login with:
+
+```
+docker login registry.example.com
+```
+
+Building and publishing images should be a straightforward process. Just make
+sure that you are using the Registry URL with the namespace and project name
+that is hosted on GitLab:
+
+```
+docker build -t registry.example.com/group/project .
+docker push registry.example.com/group/project
+```
+
+## Use images from GitLab Container Registry
+
+To download and run a container from images hosted in GitLab Container Registry,
+use `docker run`:
+
+```
+docker run [options] registry.example.com/group/project [arguments]
+```
+
+For more information on running Docker containers, visit the
+[Docker documentation][docker-docs].
+
+## Control Container Registry from within GitLab
+
+GitLab offers a simple Container Registry management panel. Go to your project
+and click **Container Registry** in the left sidebar.
+
+This view will show you all tags in your project and will easily allow you to
+delete them.
+
+![Container Registry panel](img/container_registry.png)
+
+## Build and push images using GitLab CI
+
+> **Note:**
+This feature requires GitLab 8.8 and GitLab Runner 1.2.
+
+Make sure that your GitLab Runner is configured to allow building docker images.
+You have to check the [Using Docker Build documentation](../ci/docker/using_docker_build.md).
+Then see the CI documentation on [Using the GitLab Container Registry](../ci/docker/using_docker_build.md#using-the-gitlab-container-registry).
+
+## Limitations
+
+In order to use a container image from your private project as an `image:` in
+your `.gitlab-ci.yml`, you have to follow the
+[Using a private Docker Registry][private-docker]
+documentation. This workflow will be simplified in the future.
+
+[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
+[docker-docs]: https://docs.docker.com/engine/userguide/intro/
+[private-docker]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/blob/master/docs/configuration/advanced-configuration.md#using-a-private-docker-registry
diff --git a/doc/user/project/container_registry/img/container_registry.png b/doc/user/project/container_registry/img/container_registry.png
new file mode 100644
index 00000000000..e9505a73b40
Binary files /dev/null and b/doc/user/project/container_registry/img/container_registry.png differ
diff --git a/doc/user/project/container_registry/img/project_feature.png b/doc/user/project/container_registry/img/project_feature.png
new file mode 100644
index 00000000000..57a73d253c0
Binary files /dev/null and b/doc/user/project/container_registry/img/project_feature.png differ
diff --git a/doc/user/project/project_services/bamboo.md b/doc/user/project/project_services/bamboo.md
new file mode 100644
index 00000000000..51668128c62
--- /dev/null
+++ b/doc/user/project/project_services/bamboo.md
@@ -0,0 +1,60 @@
+# Atlassian Bamboo CI Service
+
+GitLab provides integration with Atlassian Bamboo for continuous integration.
+When configured, pushes to a project will trigger a build in Bamboo automatically.
+Merge requests will also display CI status showing whether the build is pending,
+failed, or completed successfully. It also provides a link to the Bamboo build
+page for more information.
+
+Bamboo doesn't quite provide the same features as a traditional build system when
+it comes to accepting webhooks and commit data. There are a few things that
+need to be configured in a Bamboo build plan before GitLab can integrate.
+
+## Setup
+
+### Complete these steps in Bamboo:
+
+1. Navigate to a Bamboo build plan and choose 'Configure plan' from the 'Actions'
+dropdown.
+1. Select the 'Triggers' tab.
+1. Click 'Add trigger'.
+1. Enter a description such as 'GitLab trigger'
+1. Choose 'Repository triggers the build when changes are committed'
+1. Check one or more repositories checkboxes
+1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a 
+whitelist of IP addresses that are allowed to trigger Bamboo builds.
+1. Save the trigger.
+1. In the left pane, select a build stage. If you have multiple build stages 
+you want to select the last stage that contains the git checkout task.
+1. Select the 'Miscellaneous' tab.
+1. Under 'Pattern Match Labelling' put '${bamboo.repository.revision.number}' 
+in the 'Labels' box.
+1. Save
+
+Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo
+service in GitLab
+
+### Complete these steps in GitLab:
+
+1. Navigate to the project you want to configure to trigger builds.
+1. Select 'Settings' in the top navigation.
+1. Select 'Services' in the left navigation.
+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 build key from your Bamboo build plan. Build keys are a short, 
+all capital letter, identifier that is unique. It will be something like PR-BLD
+1. If necessary, enter username and password for a Bamboo user that has 
+access to trigger the build plan. Leave these fields blank if you do not require
+authentication.
+1. Save or optionally click 'Test Settings'. Please note that 'Test Settings'
+will actually trigger a build in Bamboo.
+
+## Troubleshooting
+
+If builds are not triggered, these are a couple of things to keep in mind.
+
+1. Ensure you entered the right GitLab IP address in Bamboo under 'Trigger
+IP addresses'.
+1. Remember that GitLab only triggers builds on push events. A commit via the
+web interface will not trigger CI currently.
diff --git a/doc/user/project/project_services/builds_emails.md b/doc/user/project/project_services/builds_emails.md
new file mode 100644
index 00000000000..af0b1a287c7
--- /dev/null
+++ b/doc/user/project/project_services/builds_emails.md
@@ -0,0 +1,16 @@
+## Enabling build emails
+
+To receive e-mail notifications about the result status of your builds, visit
+your project's **Settings > Services > Builds emails** and activate the service.
+
+In the _Recipients_ area, provide a list of e-mails separated by comma.
+
+Check the _Add pusher_ checkbox if you want the committer to also receive
+e-mail notifications about each build's status.
+
+If you enable the _Notify only broken builds_ option, e-mail notifications will
+be sent only for failed builds.
+
+---
+
+![Builds emails service settings](img/builds_emails_service.png)
diff --git a/doc/user/project/project_services/emails_on_push.md b/doc/user/project/project_services/emails_on_push.md
new file mode 100644
index 00000000000..2f9f36f962e
--- /dev/null
+++ b/doc/user/project/project_services/emails_on_push.md
@@ -0,0 +1,17 @@
+## Enabling emails on push
+
+To receive email notifications for every change that is pushed to the project, visit
+your project's **Settings > Services > Emails on push** and activate the service.
+
+In the _Recipients_ area, provide a list of emails separated by commas.
+
+You can configure any of the following settings depending on your preference.
+
++ **Push events** - Email will be triggered when a push event is recieved
++ **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.
+
+---
+
+![Email on push service settings](img/emails_on_push_service.png)
diff --git a/doc/user/project/project_services/hipchat.md b/doc/user/project/project_services/hipchat.md
new file mode 100644
index 00000000000..021a93a288f
--- /dev/null
+++ b/doc/user/project/project_services/hipchat.md
@@ -0,0 +1,54 @@
+# Atlassian HipChat
+
+GitLab provides a way to send HipChat notifications upon a number of events,
+such as when a user pushes code, creates a branch or tag, adds a comment, and
+creates a merge request.
+
+## Setup
+
+GitLab requires the use of a HipChat v2 API token to work. v1 tokens are
+not supported at this time. Note the differences between v1 and v2 tokens:
+
+HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1
+token is allowed to send messages to *any* room.
+
+HipChat v2 API has tokens that are can be created using the Integrations tab
+in the Group or Room admin page. By design, these are lightweight tokens that
+allow GitLab to send messages only to *one* room.
+
+### Complete these steps in HipChat:
+
+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".
+1. In the "Send messages to this room by posting this URL" column, you should
+see a URL in the format:
+
+```
+    https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token>
+```
+
+HipChat is now ready to accept messages from GitLab. Next, set up the HipChat
+service in GitLab.
+
+### Complete these steps in GitLab:
+
+1. Navigate to the project you want to configure for notifications.
+1. Select "Settings" in the top navigation.
+1. Select "Services" in the left navigation.
+1. Click "HipChat".
+1. Select the "Active" checkbox.
+1. Insert the `token` field from the URL into the `Token` field on the Web page.
+1. Insert the `room` field from the URL into the `Room` field on the Web page.
+1. Save or optionally click "Test Settings".
+
+## Troubleshooting
+
+If you do not see notifications, make sure you are using a HipChat v2 API
+token, not a v1 token.
+
+Note that the v2 token is tied to a specific room. If you want to be able to
+specify arbitrary rooms, you can create an API token for a specific user in
+HipChat under "Account settings" and "API access". Use the `XXX` value under
+`auth_token=XXX`.
diff --git a/doc/user/project/project_services/img/builds_emails_service.png b/doc/user/project/project_services/img/builds_emails_service.png
new file mode 100644
index 00000000000..e604dd73ffa
Binary files /dev/null and b/doc/user/project/project_services/img/builds_emails_service.png differ
diff --git a/doc/user/project/project_services/img/emails_on_push_service.png b/doc/user/project/project_services/img/emails_on_push_service.png
new file mode 100644
index 00000000000..cd6f79ad1eb
Binary files /dev/null and b/doc/user/project/project_services/img/emails_on_push_service.png differ
diff --git a/doc/user/project/project_services/img/jira_add_gitlab_commit_message.png b/doc/user/project/project_services/img/jira_add_gitlab_commit_message.png
new file mode 100644
index 00000000000..85e54861b3e
Binary files /dev/null and b/doc/user/project/project_services/img/jira_add_gitlab_commit_message.png differ
diff --git a/doc/user/project/project_services/img/jira_add_user_to_group.png b/doc/user/project/project_services/img/jira_add_user_to_group.png
new file mode 100644
index 00000000000..e4576433889
Binary files /dev/null and b/doc/user/project/project_services/img/jira_add_user_to_group.png differ
diff --git a/doc/user/project/project_services/img/jira_create_new_group.png b/doc/user/project/project_services/img/jira_create_new_group.png
new file mode 100644
index 00000000000..edaa1326058
Binary files /dev/null and b/doc/user/project/project_services/img/jira_create_new_group.png differ
diff --git a/doc/user/project/project_services/img/jira_create_new_group_name.png b/doc/user/project/project_services/img/jira_create_new_group_name.png
new file mode 100644
index 00000000000..9e518ad7843
Binary files /dev/null and b/doc/user/project/project_services/img/jira_create_new_group_name.png differ
diff --git a/doc/user/project/project_services/img/jira_create_new_user.png b/doc/user/project/project_services/img/jira_create_new_user.png
new file mode 100644
index 00000000000..57e433dd818
Binary files /dev/null and b/doc/user/project/project_services/img/jira_create_new_user.png differ
diff --git a/doc/user/project/project_services/img/jira_group_access.png b/doc/user/project/project_services/img/jira_group_access.png
new file mode 100644
index 00000000000..47716ca6d0e
Binary files /dev/null and b/doc/user/project/project_services/img/jira_group_access.png differ
diff --git a/doc/user/project/project_services/img/jira_issue_closed.png b/doc/user/project/project_services/img/jira_issue_closed.png
new file mode 100644
index 00000000000..cabec1ae137
Binary files /dev/null and b/doc/user/project/project_services/img/jira_issue_closed.png differ
diff --git a/doc/user/project/project_services/img/jira_issue_reference.png b/doc/user/project/project_services/img/jira_issue_reference.png
new file mode 100644
index 00000000000..15739a22dc7
Binary files /dev/null and b/doc/user/project/project_services/img/jira_issue_reference.png differ
diff --git a/doc/user/project/project_services/img/jira_issues_workflow.png b/doc/user/project/project_services/img/jira_issues_workflow.png
new file mode 100644
index 00000000000..28e17be3a84
Binary files /dev/null and b/doc/user/project/project_services/img/jira_issues_workflow.png differ
diff --git a/doc/user/project/project_services/img/jira_merge_request_close.png b/doc/user/project/project_services/img/jira_merge_request_close.png
new file mode 100644
index 00000000000..1e78daf105f
Binary files /dev/null and b/doc/user/project/project_services/img/jira_merge_request_close.png differ
diff --git a/doc/user/project/project_services/img/jira_project_name.png b/doc/user/project/project_services/img/jira_project_name.png
new file mode 100644
index 00000000000..5986fdb63fb
Binary files /dev/null and b/doc/user/project/project_services/img/jira_project_name.png differ
diff --git a/doc/user/project/project_services/img/jira_reference_commit_message_in_jira_issue.png b/doc/user/project/project_services/img/jira_reference_commit_message_in_jira_issue.png
new file mode 100644
index 00000000000..0149181dc86
Binary files /dev/null and b/doc/user/project/project_services/img/jira_reference_commit_message_in_jira_issue.png differ
diff --git a/doc/user/project/project_services/img/jira_service.png b/doc/user/project/project_services/img/jira_service.png
new file mode 100644
index 00000000000..1f6628c4371
Binary files /dev/null and b/doc/user/project/project_services/img/jira_service.png differ
diff --git a/doc/user/project/project_services/img/jira_service_close_issue.png b/doc/user/project/project_services/img/jira_service_close_issue.png
new file mode 100644
index 00000000000..67dfc6144c4
Binary files /dev/null and b/doc/user/project/project_services/img/jira_service_close_issue.png differ
diff --git a/doc/user/project/project_services/img/jira_service_page.png b/doc/user/project/project_services/img/jira_service_page.png
new file mode 100644
index 00000000000..c225daa81e1
Binary files /dev/null and b/doc/user/project/project_services/img/jira_service_page.png differ
diff --git a/doc/user/project/project_services/img/jira_submit_gitlab_merge_request.png b/doc/user/project/project_services/img/jira_submit_gitlab_merge_request.png
new file mode 100644
index 00000000000..e935d9362aa
Binary files /dev/null and b/doc/user/project/project_services/img/jira_submit_gitlab_merge_request.png differ
diff --git a/doc/user/project/project_services/img/jira_user_management_link.png b/doc/user/project/project_services/img/jira_user_management_link.png
new file mode 100644
index 00000000000..2745916972c
Binary files /dev/null and b/doc/user/project/project_services/img/jira_user_management_link.png differ
diff --git a/doc/user/project/project_services/img/jira_workflow_screenshot.png b/doc/user/project/project_services/img/jira_workflow_screenshot.png
new file mode 100644
index 00000000000..8635a32eb68
Binary files /dev/null and b/doc/user/project/project_services/img/jira_workflow_screenshot.png differ
diff --git a/doc/user/project/project_services/img/redmine_configuration.png b/doc/user/project/project_services/img/redmine_configuration.png
new file mode 100644
index 00000000000..d14e526ad33
Binary files /dev/null and b/doc/user/project/project_services/img/redmine_configuration.png differ
diff --git a/doc/user/project/project_services/img/services_templates_redmine_example.png b/doc/user/project/project_services/img/services_templates_redmine_example.png
new file mode 100644
index 00000000000..384d057fc8e
Binary files /dev/null and b/doc/user/project/project_services/img/services_templates_redmine_example.png differ
diff --git a/doc/user/project/project_services/irker.md b/doc/user/project/project_services/irker.md
new file mode 100644
index 00000000000..25c0c3ad2a6
--- /dev/null
+++ b/doc/user/project/project_services/irker.md
@@ -0,0 +1,51 @@
+# Irker IRC Gateway
+
+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
+
+## Needed setup
+
+You will first need an Irker daemon. You can download the Irker code from its
+repository on https://gitlab.com/esr/irker:
+
+```
+git clone https://gitlab.com/esr/irker.git
+```
+
+Once you have downloaded the code, you can run the python script named `irkerd`.
+This script is the gateway script, it acts both as an IRC client, for sending
+messages to an IRC server obviously, and as a TCP server, for receiving messages
+from the GitLab service.
+
+If the Irker server runs on the same machine, you are done. If not, you will
+need to follow the firsts steps of the next section.
+
+## Complete these steps in GitLab:
+
+1. Navigate to the project you want to configure for notifications.
+1. Select "Settings" in the top navigation.
+1. Select "Services" in the left navigation.
+1. Click "Irker".
+1. Select the "Active" checkbox.
+1. Enter the server host address where `irkerd` runs (defaults to `localhost`)
+in the `Server host` field on the Web page
+1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the
+`Server port` field on the Web page.
+1. Optional: if `Default IRC URI` is set, it has to be in the format
+`irc[s]://domain.name` and will be prepend to each and every channel provided
+by the user which is not a full URI.
+1. Specify the recipients (e.g. #channel1, user1, etc.)
+1. Save or optionally click "Test Settings".
+
+## Note on Irker recipients
+
+Irker accepts channel names of the form `chan` and `#chan`, both for the
+`#chan` channel. If you want to send messages in query, you will need to add
+`,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter
+case, `Aorimn` is treated as a nick and no more as a channel name.
+
+Irker can also join password-protected channels. Users need to append
+`?key=thesecretpassword` to the chan name.
diff --git a/doc/user/project/project_services/jira.md b/doc/user/project/project_services/jira.md
new file mode 100644
index 00000000000..b626c746c79
--- /dev/null
+++ b/doc/user/project/project_services/jira.md
@@ -0,0 +1,246 @@
+# GitLab JIRA integration
+
+>**Note:**
+Full JIRA integration was previously exclusive to GitLab Enterprise Edition.
+With [GitLab 8.3 forward][8_3_post], this feature in now [backported][jira-ce]
+to GitLab Community Edition as well.
+
+---
+
+GitLab can be configured to interact with [JIRA Core] either using an
+on-premises instance or the SaaS solution that Atlassian offers. Configuration
+happens via username and password on a per-project basis. Connecting to a JIRA
+server via CAS is not possible.
+
+Each project can be configured to connect to a different JIRA instance or, in
+case you have a single JIRA instance, you can pre-fill the JIRA service
+settings page in GitLab with a default template. To configure the JIRA template,
+see the [Services Templates documentation][services-templates].
+
+Once the GitLab project is connected to JIRA, you can reference and close the
+issues in JIRA directly from GitLab's merge requests.
+
+## Configuration
+
+The configuration consists of two parts:
+
+- [JIRA configuration](#configuring-jira)
+- [GitLab configuration](#configuring-gitlab)
+
+### Configuring JIRA
+
+First things first, we need to create a user in JIRA which will have access to
+all projects that need to integrate with GitLab.
+
+We have split this stage in steps so it is easier to follow.
+
+---
+
+1. Login to your JIRA instance as an administrator and under **Administration**
+   go to **User Management** to create a new user.
+
+     ![JIRA user management link](img/jira_user_management_link.png)
+
+     ---
+
+1. The next step is to create a new user (e.g., `gitlab`) who has write access
+   to projects in JIRA. Enter the user's name and a _valid_ e-mail address
+   since JIRA sends a verification e-mail to set-up the password.
+   _**Note:** JIRA creates the username automatically by using the e-mail
+   prefix. You can change it later if you want._
+
+     ![JIRA create new user](img/jira_create_new_user.png)
+
+     ---
+
+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**.
+
+     ![JIRA create new user](img/jira_create_new_group.png)
+
+     ---
+
+     Give it an optional description and hit **Create group**.
+
+     ![JIRA create new group](img/jira_create_new_group_name.png)
+
+     ---
+
+1. Give the newly-created group write access by going to
+   **Application access > View configuration** and adding the `gitlab-developers`
+   group to JIRA Core.
+
+     ![JIRA group access](img/jira_group_access.png)
+
+     ---
+
+1. Add the `gitlab` user to the `gitlab-developers` group by going to
+   **Users > GitLab user > Add group** and selecting the `gitlab-developers`
+   group from the dropdown menu. Notice that the group says _Access_ which is
+   what we aim for.
+
+     ![JIRA add user to group](img/jira_add_user_to_group.png)
+
+---
+
+The JIRA configuration is over. Write down the new JIRA username and its
+password as they will be needed when configuring GitLab in the next section.
+
+### Configuring GitLab
+
+>**Note:**
+The currently supported JIRA versions are v6.x and v7.x. and GitLab
+7.8 or higher is required.
+
+---
+
+Assuming you [have already configured JIRA](#configuring-jira), now it's time
+to configure GitLab.
+
+JIRA configuration in GitLab is done via a project's
+[**Services**](../project_services/project_services.md).
+
+To enable JIRA integration in a project, navigate to the project's
+**Settings > Services > JIRA**.
+
+Fill in the required details on the page, as described in the table below.
+
+| Setting | Description |
+| ------- | ----------- |
+| `Description` | A name for the issue tracker (to differentiate between instances, for example). |
+| `Project url` | The URL to the JIRA project which is being linked to this GitLab project. It is of the form: `https://<jira_host_url>/issues/?jql=project=<jira_project>`. |
+| `Issues url`  | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. It is of the form: `https://<jira_host_url>/browse/:id`. Leave `:id` as-is, it gets replaced by GitLab at runtime. |
+| `New issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project, and it is of the form: `https://<jira_host_url>/secure/CreateIssue.jspa` |
+| `Api url`     | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`. It is of the form: `https://<jira_host_url>/rest/api/2`. |
+| `Username` | The username of the user created in [configuring JIRA step](#configuring-jira). |
+| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). |
+| `JIRA issue transition` | This setting is very important to set up correctly. It is the ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. |
+
+After saving the configuration, your GitLab project will be able to interact
+with the linked JIRA project.
+
+For example, given the settings below:
+
+- the JIRA URL is `https://jira.example.com`
+- the project is named `GITLAB`
+- the user is named `gitlab`
+- the JIRA issue transition is 151 (based on the [JIRA issue transition][trans])
+
+the following screenshot shows how the JIRA service settings should look like.
+
+![JIRA service page](img/jira_service_page.png)
+
+[trans]: img/jira_issues_workflow.png
+
+---
+
+## JIRA issues
+
+By now you should have [configured JIRA](#configuring-jira) and enabled the
+[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly
+you should be able to reference and close JIRA issues by just mentioning their
+ID in GitLab commits and merge requests.
+
+### Referencing JIRA Issues
+
+If you reference a JIRA issue, e.g., `GITLAB-1`, in a commit comment, a link
+which points back to JIRA is created.
+
+The same works for comments in merge requests as well.
+
+![JIRA add GitLab commit message](img/jira_add_gitlab_commit_message.png)
+
+---
+
+The mentioning action is two-fold, so a comment with a JIRA issue in GitLab
+will automatically add a comment in that particular JIRA issue with the link
+back to GitLab.
+
+
+![JIRA reference commit message](img/jira_reference_commit_message_in_jira_issue.png)
+
+---
+
+The comment on the JIRA issue is of the form:
+
+> USER mentioned this issue in LINK_TO_THE_MENTION
+
+Where:
+
+| Format | Description |
+| ------ | ----------- |
+| `USER` | A user that mentioned the issue. This is the link to the user profile in GitLab. |
+| `LINK_TO_THE_MENTION` | Link to the origin of mention with a name of the entity where JIRA issue was mentioned. Can be commit or merge request. |
+
+### Closing JIRA issues
+
+JIRA issues can be closed directly from GitLab by using trigger words in
+commits and merge requests. When a commit which contains the trigger word
+followed by the JIRA issue ID in the commit message is pushed, GitLab will
+add a comment in the mentioned JIRA issue and immediately close it (provided
+the transition ID was set up correctly).
+
+There are currently three trigger words, and you can use either one to achieve
+the same goal:
+
+- `Resolves GITLAB-1`
+- `Closes GITLAB-1`
+- `Fixes GITLAB-1`
+
+where `GITLAB-1` the issue ID of the JIRA project.
+
+### JIRA issue closing example
+
+Let's say for example that we submitted a bug fix and created a merge request
+in GitLab. The workflow would be something like this:
+
+1. Create a new branch
+1. Fix the bug
+1. Commit the changes and push branch to GitLab
+1. Open a new merge request and reference the JIRA issue including one of the
+   trigger words, e.g.: `Fixes GITLAB-1`, in the description
+1. Submit the merge request
+1. Ask someone to review
+1. Merge the merge request
+1. The JIRA issue is automatically closed
+
+---
+
+In the following screenshot you can see what the link references to the JIRA
+issue look like.
+
+![JIRA - submit a GitLab merge request](img/jira_submit_gitlab_merge_request.png)
+
+---
+
+Once this merge request is merged, the JIRA issue will be automatically closed
+with a link to the commit that resolved the issue.
+
+![The GitLab integration user leaves a comment on JIRA](img/jira_issue_closed.png)
+
+---
+
+You can see from the above image that there are four references to GitLab:
+
+- The first is from a comment in a specific commit
+- The second is from the JIRA issue reference in the merge request description
+- The third is from the actual commit that solved the issue
+- And the fourth is from the commit that the merge request created
+
+[services-templates]: ../project_services/services_templates.md "Services templates documentation"
+[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website"
+[jira-ce]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2146 "MR - Backport JIRA service"
+[8_3_post]: https://about.gitlab.com/2015/12/22/gitlab-8-3-released/ "GitLab 8.3 release post"
+
+## Troubleshooting
+
+### GitLab is unable to comment on a ticket
+
+Make sure that the user you set up for GitLab to communicate with JIRA has the
+correct access permission to post comments on a ticket and to also transition the
+ticket, if you'd like GitLab to also take care of closing them.
+
+### GitLab is unable to close a ticket
+
+Make sure the the `Transition ID` you set within the JIRA settings matches the
+one your project needs to close a ticket.
diff --git a/doc/user/project/project_services/project_services.md b/doc/user/project/project_services/project_services.md
new file mode 100644
index 00000000000..f81a035f70b
--- /dev/null
+++ b/doc/user/project/project_services/project_services.md
@@ -0,0 +1,54 @@
+# Project Services
+
+Project services allow you to integrate GitLab with other applications. Below
+is list of the currently supported ones.
+
+You can find these within GitLab in the Services page under Project Settings if
+you are at least a master on the project.
+Project Services are a bit like plugins in that they allow a lot of freedom in
+adding functionality to GitLab. For example there is also a service that can
+send an email every time someone pushes new commits.
+
+Because GitLab is open source we can ship with the code and tests for all
+plugins. This allows the community to keep the plugins up to date so that they
+always work in newer GitLab versions.
+
+For an overview of what projects services are available without logging in,
+please see the [project_services directory][projects-code].
+
+[projects-code]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services
+
+Click on the service links to see
+further configuration instructions and details. Contributions are welcome.
+
+## Services
+
+| Service |	Description |
+| ------- | ----------- |
+| Asana     |	Asana - Teamwork without email |
+| Assembla 	| Project Management Software (Source Commits Endpoint) |
+| [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server |
+| Buildkite | Continuous integration and deployments |
+| [Builds emails](builds_emails.md) |	Email the builds status to a list of recipients |
+| Campfire | Simple web-based real-time group chat |
+| Custom Issue Tracker | Custom issue tracker |
+| 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 |
+| Flowdock | Flowdock is a collaboration web app for technical teams |
+| Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities |
+| [HipChat](hipchat.md) | Private group chat and IM |
+| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway |
+| [JIRA](jira.md) | JIRA issue tracker |
+| JetBrains TeamCity CI | A continuous integration and build server |
+| PivotalTracker | Project Management Software (Source Commits Endpoint) |
+| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |
+| [Redmine](redmine.md) | Redmine issue tracker |
+| Slack | A team communication tool for the 21st century |
+
+## Services Templates
+
+Services templates is a way to set some predefined values in the Service of
+your liking which will then be pre-filled on each project's Service.
+
+Read more about [Services Templates in this document](services_templates.md).
diff --git a/doc/user/project/project_services/redmine.md b/doc/user/project/project_services/redmine.md
new file mode 100644
index 00000000000..b9830ea7c38
--- /dev/null
+++ b/doc/user/project/project_services/redmine.md
@@ -0,0 +1,21 @@
+# Redmine Service
+
+Go to your project's **Settings > Services > Redmine** and fill in the required
+details as described in the table below.
+
+| Field | Description |
+| ----- | ----------- |
+| `description`   | A name for the issue tracker (to differentiate between instances, for example) |
+| `project_url`   | The URL to the project in Redmine which is being linked to this GitLab project |
+| `issues_url`    | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. |
+| `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project |
+
+Once you have configured and enabled Redmine:
+
+- the **Issues** link on the GitLab project pages takes you to the appropriate
+  Redmine issue index
+- clicking **New issue** on the project dashboard creates a new Redmine issue
+
+As an example, below is a configuration for a project named gitlab-ci.
+
+![Redmine configuration](img/redmine_configuration.png)
diff --git a/doc/user/project/project_services/services_templates.md b/doc/user/project/project_services/services_templates.md
new file mode 100644
index 00000000000..be6d13b6d2b
--- /dev/null
+++ b/doc/user/project/project_services/services_templates.md
@@ -0,0 +1,25 @@
+# Services Templates
+
+A GitLab administrator can add a service template that sets a default for each
+project. This makes it much easier to configure individual projects.
+
+After the template is created, the template details will be pre-filled on a
+project's Service page.
+
+## Enable a Service template
+
+In GitLab's Admin area, navigate to **Service Templates** and choose the
+service template you wish to create.
+
+For example, in the image below you can see Redmine.
+
+![Redmine service template](img/services_templates_redmine_example.png)
+
+---
+
+**NOTE:** For each project, you will still need to configure the issue tracking
+URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used
+by your external issue tracker. Prior to GitLab v7.8, this ID was configured in
+the project settings, and GitLab would automatically update the URL configured
+in `gitlab.yml`. This behavior is now deprecated and all issue tracker URLs
+must be configured directly within the project's **Services** settings.
diff --git a/doc/user/public_access/public_access.md b/doc/user/public_access/public_access.md
new file mode 100644
index 00000000000..17bb75ececd
--- /dev/null
+++ b/doc/user/public_access/public_access.md
@@ -0,0 +1,69 @@
+# Public access
+
+GitLab allows you to change your projects' visibility in order be accessed
+**publicly** or **internally**.
+
+Projects with either of these visibility levels will be listed in the
+public access directory (`/public` under your GitLab instance).
+Here is the [GitLab.com example](https://gitlab.com/public).
+
+Internal projects will only be available to authenticated users.
+
+## Visibility of projects
+
+### Public projects
+
+Public projects can be cloned **without any** authentication.
+
+They will also be listed on the public access directory (`/public`).
+
+**Any logged in user** will have [Guest](../permissions/permissions)
+permissions on the repository.
+
+### Internal projects
+
+Internal projects can be cloned by any logged in user.
+
+They will also be listed on the public access directory (`/public`) for logged
+in users.
+
+Any logged in user will have [Guest](../permissions/permissions) permissions on
+the repository.
+
+### How to change project visibility
+
+1. Go to your project's **Settings**
+1. Change "Visibility Level" to either Public, Internal or Private
+
+## Visibility of groups
+
+>**Note:**
+[Starting with][3323] GitLab 8.6, the group visibility has changed and can be
+configured the same way as projects. In previous versions, a group's page was
+always visible to all users.
+
+Like with projects, the visibility of a group can be set to dictate whether
+anonymous users, all signed in users, or only explicit group members can view
+it. The restriction for visibility levels on the application setting level also
+applies to groups, so if that's set to internal, the explore page will be empty
+for anonymous users. The group page now has a visibility level icon.
+
+[3323]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3323
+
+## Visibility of users
+
+The public page of a user, located at `/u/username`, is always visible whether
+you are logged in or not.
+
+When visiting the public page of a user, you can only see the projects which
+you are privileged to.
+
+If the public level is restricted, user profiles are only visible to logged in users.
+
+
+## Restricting the use of public or internal projects
+
+In the Admin area under **Settings** (`/admin/application_settings`), you can
+restrict the use of visibility levels for users when they create a project or a
+snippet. This is useful to prevent people exposing their repositories to public
+by accident. The restricted visibility settings do not apply to admin users.
diff --git a/doc/user/ssh/README.md b/doc/user/ssh/README.md
new file mode 100644
index 00000000000..a1198e5878f
--- /dev/null
+++ b/doc/user/ssh/README.md
@@ -0,0 +1,130 @@
+# SSH
+
+## SSH keys
+
+An SSH key allows you to establish a secure connection between your
+computer and GitLab. Before generating an SSH key in your shell, check if your system
+already has one by running the following command:
+
+**Windows Command Line:**
+```bash
+type %userprofile%\.ssh\id_rsa.pub
+```
+**GNU/Linux/Mac/PowerShell:**
+```bash
+cat ~/.ssh/id_rsa.pub
+```
+
+If you see a long string starting with `ssh-rsa`, you can skip the `ssh-keygen` step.
+
+Note: It is a best practice to use a password for an SSH key, but it is not
+required and you can skip creating a password by pressing enter. Note that
+the password you choose here can't be altered or retrieved.
+
+To generate a new SSH key, use the following command:
+```bash
+ssh-keygen -t rsa -C "$your_email"
+```
+This command will prompt you for a location and filename to store the key
+pair and for a password. When prompted for the location and filename, just
+press enter to use the default. If you use a different name, the key will not
+be used automatically.
+
+Use the command below to show your public key:
+
+**Windows Command Line:**
+```bash
+type %userprofile%\.ssh\id_rsa.pub
+```
+**GNU/Linux/Mac/PowerShell:**
+```bash
+cat ~/.ssh/id_rsa.pub
+```
+
+Copy-paste the key to the 'My SSH Keys' section under the 'SSH' tab in your
+user profile. Please copy the complete key starting with `ssh-rsa` and ending
+with your username and host.
+
+To copy your public key to the clipboard, use the code below. Depending on your
+OS you'll need to use a different command:
+
+**Windows Command Line:**
+```bash
+type %userprofile%\.ssh\id_rsa.pub | clip
+```
+
+**Windows PowerShell:**
+```bash
+cat ~/.ssh/id_rsa.pub | clip
+```
+
+**Mac:**
+```bash
+pbcopy < ~/.ssh/id_rsa.pub
+```
+
+**GNU/Linux (requires xclip):**
+```bash
+xclip -sel clip < ~/.ssh/id_rsa.pub
+```
+
+## Deploy keys
+
+Deploy keys allow read-only access to multiple projects with a single SSH
+key.
+
+This is really useful for cloning repositories to your Continuous
+Integration (CI) server. By using deploy keys, you don't have to setup a
+dummy user account.
+
+If you are a project master or owner, you can add a deploy key in the
+project settings under the section 'Deploy Keys'. Press the 'New Deploy
+Key' button and upload a public SSH key. After this, the machine that uses
+the corresponding private key has read-only access to the project.
+
+You can't add the same deploy key twice with the 'New Deploy Key' option.
+If you want to add the same key to another project, please enable it in the
+list that says 'Deploy keys from projects available to you'. All the deploy
+keys of all the projects you have access to are available. This project
+access can happen through being a direct member of the project, or through
+a group. See `def accessible_deploy_keys` in `app/models/user.rb` for more
+information.
+
+Deploy keys can be shared between projects, you just need to add them to each project.
+
+## Applications
+
+### Eclipse
+
+How to add your ssh key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration
+
+## Tip: Non-default OpenSSH key file names or locations
+
+If, for whatever reason, you decide to specify a non-default location and filename for your GitLab SSH key pair, you must configure your SSH client to find your GitLab SSH private key for connections to your GitLab server (perhaps gitlab.com). For OpenSSH clients, this is handled in the `~/.ssh/config` file with a stanza similar to the following:
+
+```
+#
+# Main gitlab.com server
+#
+Host gitlab.com
+RSAAuthentication yes
+IdentityFile ~/my-ssh-key-directory/my-gitlab-private-key-filename
+User mygitlabusername
+```
+
+Another example
+```
+#
+# Our company's internal GitLab server
+#
+Host my-gitlab.company.com
+RSAAuthentication yes
+IdentityFile ~/my-ssh-key-directory/company-com-private-key-filename
+```
+
+Note in the gitlab.com example above a username was specified to override the default chosen by OpenSSH (your local username). This is only required if your local and remote usernames differ.
+
+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.
\ No newline at end of file
diff --git a/doc/user/system_hooks/system_hooks.md b/doc/user/system_hooks/system_hooks.md
new file mode 100644
index 00000000000..c44930a4ceb
--- /dev/null
+++ b/doc/user/system_hooks/system_hooks.md
@@ -0,0 +1,355 @@
+# System hooks
+
+Your GitLab instance can perform HTTP POST requests on the following events: `project_create`, `project_destroy`, `project_rename`, `project_transfer`, `user_add_to_team`, `user_remove_from_team`, `user_create`, `user_destroy`, `key_create`, `key_destroy`, `group_create`, `group_destroy`, `user_add_to_group` and `user_remove_from_group`.
+
+System hooks can be used, e.g. for logging or changing information in a LDAP server.
+
+> **Note:**
+>
+> We follow the same structure from Webhooks for Push and Tag events, but we never display commits.
+>
+> Same deprecations from Webhooks are valid here.
+
+## Hooks request example
+
+**Request header**:
+
+```
+X-Gitlab-Event: System Hook
+```
+
+**Project created:**
+
+```json
+{
+          "created_at": "2012-07-21T07:30:54Z",
+          "updated_at": "2012-07-21T07:38:22Z",
+          "event_name": "project_create",
+                "name": "StoreCloud",
+         "owner_email": "johnsmith@gmail.com",
+          "owner_name": "John Smith",
+                "path": "storecloud",
+ "path_with_namespace": "jsmith/storecloud",
+          "project_id": 74,
+  "project_visibility": "private",
+}
+```
+
+**Project destroyed:**
+
+```json
+{
+          "created_at": "2012-07-21T07:30:58Z",
+          "updated_at": "2012-07-21T07:38:22Z",
+          "event_name": "project_destroy",
+                "name": "Underscore",
+         "owner_email": "johnsmith@gmail.com",
+          "owner_name": "John Smith",
+                "path": "underscore",
+ "path_with_namespace": "jsmith/underscore",
+          "project_id": 73,
+  "project_visibility": "internal",
+}
+```
+
+**Project renamed:**
+
+```json
+{
+               "created_at": "2012-07-21T07:30:58Z",
+               "updated_at": "2012-07-21T07:38:22Z",
+               "event_name": "project_rename",
+                     "name": "Underscore",
+                     "path": "underscore",
+      "path_with_namespace": "jsmith/underscore",
+               "project_id": 73,
+               "owner_name": "John Smith",
+              "owner_email": "johnsmith@gmail.com",
+       "project_visibility": "internal",
+  "old_path_with_namespace": "jsmith/overscore",
+}
+```
+
+**Project transferred:**
+
+```json
+{
+               "created_at": "2012-07-21T07:30:58Z",
+               "updated_at": "2012-07-21T07:38:22Z",
+               "event_name": "project_transfer",
+                     "name": "Underscore",
+                     "path": "underscore",
+      "path_with_namespace": "scores/underscore",
+               "project_id": 73,
+               "owner_name": "John Smith",
+              "owner_email": "johnsmith@gmail.com",
+       "project_visibility": "internal",
+  "old_path_with_namespace": "jsmith/overscore",
+}
+```
+
+**New Team Member:**
+
+```json
+{
+                  "created_at": "2012-07-21T07:30:56Z",
+                  "updated_at": "2012-07-21T07:38:22Z",
+                  "event_name": "user_add_to_team",
+              "project_access": "Master",
+                  "project_id": 74,
+                "project_name": "StoreCloud",
+                "project_path": "storecloud",
+ "project_path_with_namespace": "jsmith/storecloud",
+                  "user_email": "johnsmith@gmail.com",
+                   "user_name": "John Smith",
+               "user_username": "johnsmith",
+                     "user_id": 41,
+          "project_visibility": "private",
+}
+```
+
+**Team Member Removed:**
+
+```json
+{
+                  "created_at": "2012-07-21T07:30:56Z",
+                  "updated_at": "2012-07-21T07:38:22Z",
+                  "event_name": "user_remove_from_team",
+              "project_access": "Master",
+                  "project_id": 74,
+                "project_name": "StoreCloud",
+                "project_path": "storecloud",
+ "project_path_with_namespace": "jsmith/storecloud",
+                  "user_email": "johnsmith@gmail.com",
+                   "user_name": "John Smith",
+               "user_username": "johnsmith",
+                     "user_id": 41,
+          "project_visibility": "private",
+}
+```
+
+**User created:**
+
+```json
+{
+   "created_at": "2012-07-21T07:44:07Z",
+   "updated_at": "2012-07-21T07:38:22Z",
+        "email": "js@gitlabhq.com",
+   "event_name": "user_create",
+         "name": "John Smith",
+     "username": "js",
+      "user_id": 41
+}
+```
+
+**User removed:**
+
+```json
+{
+   "created_at": "2012-07-21T07:44:07Z",
+   "updated_at": "2012-07-21T07:38:22Z",
+        "email": "js@gitlabhq.com",
+   "event_name": "user_destroy",
+         "name": "John Smith",
+     "username": "js",
+      "user_id": 41
+}
+```
+
+**Key added**
+
+```json
+{
+    "event_name": "key_create",
+    "created_at": "2014-08-18 18:45:16 UTC",
+    "updated_at": "2012-07-21T07:38:22Z",
+      "username": "root",
+           "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost",
+           "id": 4
+}
+```
+
+**Key removed**
+
+```json
+{
+    "event_name": "key_destroy",
+    "created_at": "2014-08-18 18:45:16 UTC",
+    "updated_at": "2012-07-21T07:38:22Z",
+      "username": "root",
+           "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost",
+            "id": 4
+}
+```
+
+**Group created:**
+
+```json
+{
+   "created_at": "2012-07-21T07:30:54Z",
+   "updated_at": "2012-07-21T07:38:22Z",
+   "event_name": "group_create",
+         "name": "StoreCloud",
+  "owner_email": "johnsmith@gmail.com",
+   "owner_name": "John Smith",
+         "path": "storecloud",
+     "group_id": 78
+}
+```
+
+**Group removed:**
+
+```json
+{
+   "created_at": "2012-07-21T07:30:54Z",
+   "updated_at": "2012-07-21T07:38:22Z",
+   "event_name": "group_destroy",
+         "name": "StoreCloud",
+  "owner_email": "johnsmith@gmail.com",
+   "owner_name": "John Smith",
+         "path": "storecloud",
+     "group_id": 78
+}
+```
+
+**New Group Member:**
+
+```json
+{
+    "created_at": "2012-07-21T07:30:56Z",
+    "updated_at": "2012-07-21T07:38:22Z",
+    "event_name": "user_add_to_group",
+  "group_access": "Master",
+      "group_id": 78,
+    "group_name": "StoreCloud",
+    "group_path": "storecloud",
+    "user_email": "johnsmith@gmail.com",
+     "user_name": "John Smith",
+ "user_username": "johnsmith",
+       "user_id": 41
+}
+```
+**Group Member Removed:**
+
+```json
+{
+    "created_at": "2012-07-21T07:30:56Z",
+    "updated_at": "2012-07-21T07:38:22Z",
+    "event_name": "user_remove_from_group",
+  "group_access": "Master",
+      "group_id": 78,
+    "group_name": "StoreCloud",
+    "group_path": "storecloud",
+    "user_email": "johnsmith@gmail.com",
+     "user_name": "John Smith",
+ "user_username": "johnsmith",
+       "user_id": 41
+}
+```
+
+## Push events
+
+Triggered when you push to the repository except when pushing tags.
+
+**Request header**:
+
+```
+X-Gitlab-Event: System Hook
+```
+
+**Request body:**
+
+```json
+{
+  "event_name": "push",
+  "before": "95790bf891e76fee5e1747ab589903a6a1f80f22",
+  "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+  "ref": "refs/heads/master",
+  "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+  "user_id": 4,
+  "user_name": "John Smith",
+  "user_email": "john@example.com",
+  "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
+  "project_id": 15,
+  "project":{
+    "name":"Diaspora",
+    "description":"",
+    "web_url":"http://example.com/mike/diaspora",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:mike/diaspora.git",
+    "git_http_url":"http://example.com/mike/diaspora.git",
+    "namespace":"Mike",
+    "visibility_level":0,
+    "path_with_namespace":"mike/diaspora",
+    "default_branch":"master",
+    "homepage":"http://example.com/mike/diaspora",
+    "url":"git@example.com:mike/diaspora.git",
+    "ssh_url":"git@example.com:mike/diaspora.git",
+    "http_url":"http://example.com/mike/diaspora.git"
+  },
+  "repository":{
+    "name": "Diaspora",
+    "url": "git@example.com:mike/diaspora.git",
+    "description": "",
+    "homepage": "http://example.com/mike/diaspora",
+    "git_http_url":"http://example.com/mike/diaspora.git",
+    "git_ssh_url":"git@example.com:mike/diaspora.git",
+    "visibility_level":0
+  },
+  "commits": [],
+  "total_commits_count": 0
+}
+```
+
+## Tag events
+
+Triggered when you create (or delete) tags to the repository.
+
+**Request header**:
+
+```
+X-Gitlab-Event: System Hook
+```
+
+**Request body:**
+
+```json
+{
+  "event_name": "tag_push",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7",
+  "ref": "refs/tags/v1.0.0",
+  "checkout_sha": "5937ac0a7beb003549fc5fd26fc247adbce4a52e",
+  "user_id": 1,
+  "user_name": "John Smith",
+  "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
+  "project_id": 1,
+  "project":{
+    "name":"Example",
+    "description":"",
+    "web_url":"http://example.com/jsmith/example",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:jsmith/example.git",
+    "git_http_url":"http://example.com/jsmith/example.git",
+    "namespace":"Jsmith",
+    "visibility_level":0,
+    "path_with_namespace":"jsmith/example",
+    "default_branch":"master",
+    "homepage":"http://example.com/jsmith/example",
+    "url":"git@example.com:jsmith/example.git",
+    "ssh_url":"git@example.com:jsmith/example.git",
+    "http_url":"http://example.com/jsmith/example.git"
+  },
+  "repository":{
+    "name": "Example",
+    "url": "ssh://git@example.com/jsmith/example.git",
+    "description": "",
+    "homepage": "http://example.com/jsmith/example",
+    "git_http_url":"http://example.com/jsmith/example.git",
+    "git_ssh_url":"git@example.com:jsmith/example.git",
+    "visibility_level":0
+  },
+  "commits": [],
+  "total_commits_count": 0
+}
+```
diff --git a/doc/user/web_hooks/ssl.png b/doc/user/web_hooks/ssl.png
new file mode 100644
index 00000000000..698f1a0f64a
Binary files /dev/null and b/doc/user/web_hooks/ssl.png differ
diff --git a/doc/user/web_hooks/web_hooks.md b/doc/user/web_hooks/web_hooks.md
new file mode 100644
index 00000000000..8559b67af04
--- /dev/null
+++ b/doc/user/web_hooks/web_hooks.md
@@ -0,0 +1,784 @@
+# Webhooks
+
+_**Note:**
+Starting from GitLab 8.5:_
+
+- _the `repository` key is deprecated in favor of the `project` key_
+- _the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key_
+- _the `project.http_url` key is deprecated in favor of the `project.git_http_url` key_
+
+Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created.
+
+You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL.
+
+Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.
+
+## Webhook endpoint tips
+
+If you are writing your own endpoint (web server) that will receive
+GitLab webhooks keep in mind the following things:
+
+-   Your endpoint should send its HTTP response as fast as possible. If
+    you wait too long, GitLab may decide the hook failed and retry it.
+-   Your endpoint should ALWAYS return a valid HTTP response. If you do
+    not do this then GitLab will think the hook failed and retry it.
+    Most HTTP libraries take care of this for you automatically but if
+    you are writing a low-level hook this is important to remember.
+-   GitLab ignores the HTTP status code returned by your endpoint.
+
+## SSL Verification
+
+By default, the SSL certificate of the webhook endpoint is verified based on
+an internal list of Certificate Authorities,
+which means the certificate cannot be self-signed.
+
+You can turn this off in the webhook settings in your GitLab projects.
+
+![SSL Verification](ssl.png)
+
+## Push events
+
+Triggered when you push to the repository except when pushing tags.
+
+**Request header**:
+
+```
+X-Gitlab-Event: Push Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "push",
+  "before": "95790bf891e76fee5e1747ab589903a6a1f80f22",
+  "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+  "ref": "refs/heads/master",
+  "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+  "user_id": 4,
+  "user_name": "John Smith",
+  "user_email": "john@example.com",
+  "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
+  "project_id": 15,
+  "project":{
+    "name":"Diaspora",
+    "description":"",
+    "web_url":"http://example.com/mike/diaspora",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:mike/diaspora.git",
+    "git_http_url":"http://example.com/mike/diaspora.git",
+    "namespace":"Mike",
+    "visibility_level":0,
+    "path_with_namespace":"mike/diaspora",
+    "default_branch":"master",
+    "homepage":"http://example.com/mike/diaspora",
+    "url":"git@example.com:mike/diaspora.git",
+    "ssh_url":"git@example.com:mike/diaspora.git",
+    "http_url":"http://example.com/mike/diaspora.git"
+  },
+  "repository":{
+    "name": "Diaspora",
+    "url": "git@example.com:mike/diaspora.git",
+    "description": "",
+    "homepage": "http://example.com/mike/diaspora",
+    "git_http_url":"http://example.com/mike/diaspora.git",
+    "git_ssh_url":"git@example.com:mike/diaspora.git",
+    "visibility_level":0
+  },
+  "commits": [
+    {
+      "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
+      "message": "Update Catalan translation to e38cb41.",
+      "timestamp": "2011-12-12T14:27:31+02:00",
+      "url": "http://example.com/mike/diaspora/commit/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
+      "author": {
+        "name": "Jordi Mallach",
+        "email": "jordi@softcatala.org"
+      },
+      "added": ["CHANGELOG"],
+      "modified": ["app/controller/application.rb"],
+      "removed": []
+    },
+    {
+      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+      "message": "fixed readme",
+      "timestamp": "2012-01-03T23:36:29+02:00",
+      "url": "http://example.com/mike/diaspora/commit/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+      "author": {
+        "name": "GitLab dev user",
+        "email": "gitlabdev@dv6700.(none)"
+      },
+      "added": ["CHANGELOG"],
+      "modified": ["app/controller/application.rb"],
+      "removed": []
+    }
+  ],
+  "total_commits_count": 4
+}
+```
+
+## Tag events
+
+Triggered when you create (or delete) tags to the repository.
+
+**Request header**:
+
+```
+X-Gitlab-Event: Tag Push Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "tag_push",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7",
+  "ref": "refs/tags/v1.0.0",
+  "checkout_sha": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7",
+  "user_id": 1,
+  "user_name": "John Smith",
+  "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
+  "project_id": 1,
+  "project":{
+    "name":"Example",
+    "description":"",
+    "web_url":"http://example.com/jsmith/example",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:jsmith/example.git",
+    "git_http_url":"http://example.com/jsmith/example.git",
+    "namespace":"Jsmith",
+    "visibility_level":0,
+    "path_with_namespace":"jsmith/example",
+    "default_branch":"master",
+    "homepage":"http://example.com/jsmith/example",
+    "url":"git@example.com:jsmith/example.git",
+    "ssh_url":"git@example.com:jsmith/example.git",
+    "http_url":"http://example.com/jsmith/example.git"
+  },
+  "repository":{
+    "name": "Example",
+    "url": "ssh://git@example.com/jsmith/example.git",
+    "description": "",
+    "homepage": "http://example.com/jsmith/example",
+    "git_http_url":"http://example.com/jsmith/example.git",
+    "git_ssh_url":"git@example.com:jsmith/example.git",
+    "visibility_level":0
+  },
+  "commits": [],
+  "total_commits_count": 0
+}
+```
+
+## Issues events
+
+Triggered when a new issue is created or an existing issue was updated/closed/reopened.
+
+**Request header**:
+
+```
+X-Gitlab-Event: Issue Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "issue",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "project":{
+    "name":"Gitlab Test",
+    "description":"Aut reprehenderit ut est.",
+    "web_url":"http://example.com/gitlabhq/gitlab-test",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git",
+    "git_http_url":"http://example.com/gitlabhq/gitlab-test.git",
+    "namespace":"GitlabHQ",
+    "visibility_level":20,
+    "path_with_namespace":"gitlabhq/gitlab-test",
+    "default_branch":"master",
+    "homepage":"http://example.com/gitlabhq/gitlab-test",
+    "url":"http://example.com/gitlabhq/gitlab-test.git",
+    "ssh_url":"git@example.com:gitlabhq/gitlab-test.git",
+    "http_url":"http://example.com/gitlabhq/gitlab-test.git"
+  },
+  "repository":{
+    "name": "Gitlab Test",
+    "url": "http://example.com/gitlabhq/gitlab-test.git",
+    "description": "Aut reprehenderit ut est.",
+    "homepage": "http://example.com/gitlabhq/gitlab-test"
+  },
+  "object_attributes": {
+    "id": 301,
+    "title": "New API: create/update/delete file",
+    "assignee_id": 51,
+    "author_id": 51,
+    "project_id": 14,
+    "created_at": "2013-12-03T17:15:43Z",
+    "updated_at": "2013-12-03T17:15:43Z",
+    "position": 0,
+    "branch_name": null,
+    "description": "Create new API for manipulations with repository",
+    "milestone_id": null,
+    "state": "opened",
+    "iid": 23,
+    "url": "http://example.com/diaspora/issues/23",
+    "action": "open"
+  },
+  "assignee": {
+    "name": "User1",
+    "username": "user1",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  }
+}
+```
+## Comment events
+
+Triggered when a new comment is made on commits, merge requests, issues, and code snippets.
+The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The
+payload will also include information about the target of the comment. For example,
+a comment on a issue will include the specific issue information under the `issue` key.
+Valid target types:
+
+1. `commit`
+2. `merge_request`
+3. `issue`
+4. `snippet`
+
+### Comment on commit
+
+**Request header**:
+
+```
+X-Gitlab-Event: Note Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "note",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "project_id": 5,
+  "project":{
+    "name":"Gitlab Test",
+    "description":"Aut reprehenderit ut est.",
+    "web_url":"http://example.com/gitlabhq/gitlab-test",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git",
+    "git_http_url":"http://example.com/gitlabhq/gitlab-test.git",
+    "namespace":"GitlabHQ",
+    "visibility_level":20,
+    "path_with_namespace":"gitlabhq/gitlab-test",
+    "default_branch":"master",
+    "homepage":"http://example.com/gitlabhq/gitlab-test",
+    "url":"http://example.com/gitlabhq/gitlab-test.git",
+    "ssh_url":"git@example.com:gitlabhq/gitlab-test.git",
+    "http_url":"http://example.com/gitlabhq/gitlab-test.git"
+  },
+  "repository":{
+    "name": "Gitlab Test",
+    "url": "http://example.com/gitlab-org/gitlab-test.git",
+    "description": "Aut reprehenderit ut est.",
+    "homepage": "http://example.com/gitlab-org/gitlab-test"
+  },
+  "object_attributes": {
+    "id": 1243,
+    "note": "This is a commit comment. How does this work?",
+    "noteable_type": "Commit",
+    "author_id": 1,
+    "created_at": "2015-05-17 18:08:09 UTC",
+    "updated_at": "2015-05-17 18:08:09 UTC",
+    "project_id": 5,
+    "attachment":null,
+    "line_code": "bec9703f7a456cd2b4ab5fb3220ae016e3e394e3_0_1",
+    "commit_id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660",
+    "noteable_id": null,
+    "system": false,
+    "st_diff": {
+      "diff": "--- /dev/null\n+++ b/six\n@@ -0,0 +1 @@\n+Subproject commit 409f37c4f05865e4fb208c771485f211a22c4c2d\n",
+      "new_path": "six",
+      "old_path": "six",
+      "a_mode": "0",
+      "b_mode": "160000",
+      "new_file": true,
+      "renamed_file": false,
+      "deleted_file": false
+    },
+    "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660#note_1243"
+  },
+  "commit": {
+    "id": "cfe32cf61b73a0d5e9f13e774abde7ff789b1660",
+    "message": "Add submodule\n\nSigned-off-by: Dmitriy Zaporozhets \u003cdmitriy.zaporozhets@gmail.com\u003e\n",
+    "timestamp": "2014-02-27T10:06:20+02:00",
+    "url": "http://example.com/gitlab-org/gitlab-test/commit/cfe32cf61b73a0d5e9f13e774abde7ff789b1660",
+    "author": {
+      "name": "Dmitriy Zaporozhets",
+      "email": "dmitriy.zaporozhets@gmail.com"
+    }
+  }
+}
+```
+
+### Comment on merge request
+
+**Request header**:
+
+```
+X-Gitlab-Event: Note Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "note",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "project_id": 5,
+  "project":{
+    "name":"Gitlab Test",
+    "description":"Aut reprehenderit ut est.",
+    "web_url":"http://example.com/gitlab-org/gitlab-test",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
+    "namespace":"Gitlab Org",
+    "visibility_level":10,
+    "path_with_namespace":"gitlab-org/gitlab-test",
+    "default_branch":"master",
+    "homepage":"http://example.com/gitlab-org/gitlab-test",
+    "url":"http://example.com/gitlab-org/gitlab-test.git",
+    "ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "http_url":"http://example.com/gitlab-org/gitlab-test.git"
+  },
+  "repository":{
+    "name": "Gitlab Test",
+    "url": "http://localhost/gitlab-org/gitlab-test.git",
+    "description": "Aut reprehenderit ut est.",
+    "homepage": "http://example.com/gitlab-org/gitlab-test"
+  },
+  "object_attributes": {
+    "id": 1244,
+    "note": "This MR needs work.",
+    "noteable_type": "MergeRequest",
+    "author_id": 1,
+    "created_at": "2015-05-17 18:21:36 UTC",
+    "updated_at": "2015-05-17 18:21:36 UTC",
+    "project_id": 5,
+    "attachment": null,
+    "line_code": null,
+    "commit_id": "",
+    "noteable_id": 7,
+    "system": false,
+    "st_diff": null,
+    "url": "http://example.com/gitlab-org/gitlab-test/merge_requests/1#note_1244"
+  },
+  "merge_request": {
+    "id": 7,
+    "target_branch": "markdown",
+    "source_branch": "master",
+    "source_project_id": 5,
+    "author_id": 8,
+    "assignee_id": 28,
+    "title": "Tempora et eos debitis quae laborum et.",
+    "created_at": "2015-03-01 20:12:53 UTC",
+    "updated_at": "2015-03-21 18:27:27 UTC",
+    "milestone_id": 11,
+    "state": "opened",
+    "merge_status": "cannot_be_merged",
+    "target_project_id": 5,
+    "iid": 1,
+    "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.",
+    "position": 0,
+    "locked_at": null,
+    "source":{
+      "name":"Gitlab Test",
+      "description":"Aut reprehenderit ut est.",
+      "web_url":"http://example.com/gitlab-org/gitlab-test",
+      "avatar_url":null,
+      "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+      "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
+      "namespace":"Gitlab Org",
+      "visibility_level":10,
+      "path_with_namespace":"gitlab-org/gitlab-test",
+      "default_branch":"master",
+      "homepage":"http://example.com/gitlab-org/gitlab-test",
+      "url":"http://example.com/gitlab-org/gitlab-test.git",
+      "ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+      "http_url":"http://example.com/gitlab-org/gitlab-test.git"
+    },
+    "target": {
+      "name":"Gitlab Test",
+      "description":"Aut reprehenderit ut est.",
+      "web_url":"http://example.com/gitlab-org/gitlab-test",
+      "avatar_url":null,
+      "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+      "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
+      "namespace":"Gitlab Org",
+      "visibility_level":10,
+      "path_with_namespace":"gitlab-org/gitlab-test",
+      "default_branch":"master",
+      "homepage":"http://example.com/gitlab-org/gitlab-test",
+      "url":"http://example.com/gitlab-org/gitlab-test.git",
+      "ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+      "http_url":"http://example.com/gitlab-org/gitlab-test.git"
+    },
+    "last_commit": {
+      "id": "562e173be03b8ff2efb05345d12df18815438a4b",
+      "message": "Merge branch 'another-branch' into 'master'\n\nCheck in this test\n",
+      "timestamp": "2015-04-08T21: 00:25-07:00",
+      "url": "http://example.com/gitlab-org/gitlab-test/commit/562e173be03b8ff2efb05345d12df18815438a4b",
+      "author": {
+        "name": "John Smith",
+        "email": "john@example.com"
+      }
+    },
+    "work_in_progress": false,
+    "assignee": {
+      "name": "User1",
+      "username": "user1",
+      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+    }
+  }
+}
+```
+
+### Comment on issue
+
+**Request header**:
+
+```
+X-Gitlab-Event: Note Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "note",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "project_id": 5,
+  "project":{
+    "name":"Gitlab Test",
+    "description":"Aut reprehenderit ut est.",
+    "web_url":"http://example.com/gitlab-org/gitlab-test",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
+    "namespace":"Gitlab Org",
+    "visibility_level":10,
+    "path_with_namespace":"gitlab-org/gitlab-test",
+    "default_branch":"master",
+    "homepage":"http://example.com/gitlab-org/gitlab-test",
+    "url":"http://example.com/gitlab-org/gitlab-test.git",
+    "ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "http_url":"http://example.com/gitlab-org/gitlab-test.git"
+  },
+  "repository":{
+    "name":"diaspora",
+    "url":"git@example.com:mike/diaspora.git",
+    "description":"",
+    "homepage":"http://example.com/mike/diaspora"
+  },
+  "object_attributes": {
+    "id": 1241,
+    "note": "Hello world",
+    "noteable_type": "Issue",
+    "author_id": 1,
+    "created_at": "2015-05-17 17:06:40 UTC",
+    "updated_at": "2015-05-17 17:06:40 UTC",
+    "project_id": 5,
+    "attachment": null,
+    "line_code": null,
+    "commit_id": "",
+    "noteable_id": 92,
+    "system": false,
+    "st_diff": null,
+    "url": "http://example.com/gitlab-org/gitlab-test/issues/17#note_1241"
+  },
+  "issue": {
+    "id": 92,
+    "title": "test",
+    "assignee_id": null,
+    "author_id": 1,
+    "project_id": 5,
+    "created_at": "2015-04-12 14:53:17 UTC",
+    "updated_at": "2015-04-26 08:28:42 UTC",
+    "position": 0,
+    "branch_name": null,
+    "description": "test",
+    "milestone_id": null,
+    "state": "closed",
+    "iid": 17
+  }
+}
+```
+
+### Comment on code snippet
+
+**Request header**:
+
+```
+X-Gitlab-Event: Note Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "note",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "project_id": 5,
+  "project":{
+    "name":"Gitlab Test",
+    "description":"Aut reprehenderit ut est.",
+    "web_url":"http://example.com/gitlab-org/gitlab-test",
+    "avatar_url":null,
+    "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "git_http_url":"http://example.com/gitlab-org/gitlab-test.git",
+    "namespace":"Gitlab Org",
+    "visibility_level":10,
+    "path_with_namespace":"gitlab-org/gitlab-test",
+    "default_branch":"master",
+    "homepage":"http://example.com/gitlab-org/gitlab-test",
+    "url":"http://example.com/gitlab-org/gitlab-test.git",
+    "ssh_url":"git@example.com:gitlab-org/gitlab-test.git",
+    "http_url":"http://example.com/gitlab-org/gitlab-test.git"
+  },
+  "repository":{
+    "name":"Gitlab Test",
+    "url":"http://example.com/gitlab-org/gitlab-test.git",
+    "description":"Aut reprehenderit ut est.",
+    "homepage":"http://example.com/gitlab-org/gitlab-test"
+  },
+  "object_attributes": {
+    "id": 1245,
+    "note": "Is this snippet doing what it's supposed to be doing?",
+    "noteable_type": "Snippet",
+    "author_id": 1,
+    "created_at": "2015-05-17 18:35:50 UTC",
+    "updated_at": "2015-05-17 18:35:50 UTC",
+    "project_id": 5,
+    "attachment": null,
+    "line_code": null,
+    "commit_id": "",
+    "noteable_id": 53,
+    "system": false,
+    "st_diff": null,
+    "url": "http://example.com/gitlab-org/gitlab-test/snippets/53#note_1245"
+  },
+  "snippet": {
+    "id": 53,
+    "title": "test",
+    "content": "puts 'Hello world'",
+    "author_id": 1,
+    "project_id": 5,
+    "created_at": "2015-04-09 02:40:38 UTC",
+    "updated_at": "2015-04-09 02:40:38 UTC",
+    "file_name": "test.rb",
+    "expires_at": null,
+    "type": "ProjectSnippet",
+    "visibility_level": 0
+  }
+}
+```
+
+## Merge request events
+
+Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch.
+
+**Request header**:
+
+```
+X-Gitlab-Event: Merge Request Hook
+```
+
+**Request body:**
+
+```json
+{
+  "object_kind": "merge_request",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+  },
+  "object_attributes": {
+    "id": 99,
+    "target_branch": "master",
+    "source_branch": "ms-viewport",
+    "source_project_id": 14,
+    "author_id": 51,
+    "assignee_id": 6,
+    "title": "MS-Viewport",
+    "created_at": "2013-12-03T17:23:34Z",
+    "updated_at": "2013-12-03T17:23:34Z",
+    "st_commits": null,
+    "st_diffs": null,
+    "milestone_id": null,
+    "state": "opened",
+    "merge_status": "unchecked",
+    "target_project_id": 14,
+    "iid": 1,
+    "description": "",
+    "source":{
+      "name":"Awesome Project",
+      "description":"Aut reprehenderit ut est.",
+      "web_url":"http://example.com/awesome_space/awesome_project",
+      "avatar_url":null,
+      "git_ssh_url":"git@example.com:awesome_space/awesome_project.git",
+      "git_http_url":"http://example.com/awesome_space/awesome_project.git",
+      "namespace":"Awesome Space",
+      "visibility_level":20,
+      "path_with_namespace":"awesome_space/awesome_project",
+      "default_branch":"master",
+      "homepage":"http://example.com/awesome_space/awesome_project",
+      "url":"http://example.com/awesome_space/awesome_project.git",
+      "ssh_url":"git@example.com:awesome_space/awesome_project.git",
+      "http_url":"http://example.com/awesome_space/awesome_project.git"
+    },
+    "target": {
+      "name":"Awesome Project",
+      "description":"Aut reprehenderit ut est.",
+      "web_url":"http://example.com/awesome_space/awesome_project",
+      "avatar_url":null,
+      "git_ssh_url":"git@example.com:awesome_space/awesome_project.git",
+      "git_http_url":"http://example.com/awesome_space/awesome_project.git",
+      "namespace":"Awesome Space",
+      "visibility_level":20,
+      "path_with_namespace":"awesome_space/awesome_project",
+      "default_branch":"master",
+      "homepage":"http://example.com/awesome_space/awesome_project",
+      "url":"http://example.com/awesome_space/awesome_project.git",
+      "ssh_url":"git@example.com:awesome_space/awesome_project.git",
+      "http_url":"http://example.com/awesome_space/awesome_project.git"
+    },
+    "last_commit": {
+      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+      "message": "fixed readme",
+      "timestamp": "2012-01-03T23:36:29+02:00",
+      "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
+      "author": {
+        "name": "GitLab dev user",
+        "email": "gitlabdev@dv6700.(none)"
+      }
+    },
+    "work_in_progress": false,
+    "url": "http://example.com/diaspora/merge_requests/1",
+    "action": "open",
+    "assignee": {
+      "name": "User1",
+      "username": "user1",
+      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
+    }
+  }
+}
+```
+
+## Wiki Page events
+
+Triggered when a wiki page is created or edited.
+
+**Request Header**:
+
+```
+X-Gitlab-Event: Wiki Page Hook
+```
+
+**Request Body**:
+
+```json
+{
+  "object_kind": "wiki_page",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon"
+  },
+  "project": {
+    "name": "awesome-project",
+    "description": "This is awesome",
+    "web_url": "http://example.com/root/awesome-project",
+    "avatar_url": null,
+    "git_ssh_url": "git@example.com:root/awesome-project.git",
+    "git_http_url": "http://example.com/root/awesome-project.git",
+    "namespace": "root",
+    "visibility_level": 0,
+    "path_with_namespace": "root/awesome-project",
+    "default_branch": "master",
+    "homepage": "http://example.com/root/awesome-project",
+    "url": "git@example.com:root/awesome-project.git",
+    "ssh_url": "git@example.com:root/awesome-project.git",
+    "http_url": "http://example.com/root/awesome-project.git"
+  },
+  "wiki": {
+    "web_url": "http://example.com/root/awesome-project/wikis/home",
+    "git_ssh_url": "git@example.com:root/awesome-project.wiki.git", 
+    "git_http_url": "http://example.com/root/awesome-project.wiki.git", 
+    "path_with_namespace": "root/awesome-project.wiki", 
+    "default_branch": "master"
+  },
+  "object_attributes": {
+    "title": "Awesome",
+    "content": "awesome content goes here",
+    "format": "markdown",
+    "message": "adding an awesome page to the wiki",
+    "slug": "awesome",
+    "url": "http://example.com/root/awesome-project/wikis/awesome",
+    "action": "create"
+  }
+}
+```
+
+#### Example webhook receiver
+
+If you want to see GitLab's webhooks in action for testing purposes you can use
+a simple echo script running in a console session.
+
+Save the following file as `print_http_body.rb`.
+
+```ruby
+require 'webrick'
+
+server = WEBrick::HTTPServer.new(:Port => ARGV.first)
+server.mount_proc '/' do |req, res|
+  puts req.body
+end
+
+trap 'INT' do
+  server.shutdown
+end
+server.start
+```
+
+Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb
+8000`.  Then add your server as a webhook receiver in GitLab as
+`http://my.host:8000/`.
+
+When you press 'Test Hook' in GitLab, you should see something like this in the console.
+
+```
+{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
+example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
+- -> /
+```
diff --git a/doc/user/workflow/README.md b/doc/user/workflow/README.md
new file mode 100644
index 00000000000..9efe41308dc
--- /dev/null
+++ b/doc/user/workflow/README.md
@@ -0,0 +1,28 @@
+# Workflow
+
+- [Authorization for merge requests](authorization_for_merge_requests.md)
+- [Change your time zone](timezone.md)
+- [Feature branch workflow](workflow.md)
+- [GitLab Flow](gitlab_flow.md)
+- [Groups](groups.md)
+- [Keyboard shortcuts](shortcuts.md)
+- [File finder](file_finder.md)
+- [Labels](labels.md)
+- [Notification emails](notifications.md)
+- [Project Features](project_features.md)
+- [Project forking workflow](forking_workflow.md)
+- [Project users](add-user/add-user.md)
+- [Protected branches](protected_branches.md)
+- [Sharing a project with a group](share_with_group.md)
+- [Share projects with other groups](share_projects_with_other_groups.md)
+- [Web Editor](web_editor.md)
+- [Releases](releases.md)
+- [Milestones](milestones.md)
+- [Merge Requests](merge_requests.md)
+- [Revert changes](revert_changes.md)
+- [Cherry-pick changes](cherry_pick_changes.md)
+- ["Work In Progress" Merge Requests](wip_merge_requests.md)
+- [Merge When Build Succeeds](merge_when_build_succeeds.md)
+- [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
+- [Importing from SVN, GitHub, BitBucket, etc](importing/README.md)
+- [Todos](todos.md)
diff --git a/doc/user/workflow/add-user/add-user.md b/doc/user/workflow/add-user/add-user.md
new file mode 100644
index 00000000000..4b551130255
--- /dev/null
+++ b/doc/user/workflow/add-user/add-user.md
@@ -0,0 +1,111 @@
+# Project users
+
+You can manage the groups and users and their access levels in all of your
+projects. You can also personalize the access level you give each user,
+per-project.
+
+You should have `master` or `owner` permissions to add or import a new user
+to your project.
+
+The first step to add or import a user, go to your project and click on
+**Members** in the drop-down menu on the right side of your screen.
+
+![Members](img/add_user_members_menu.png)
+
+---
+
+## Add a user
+
+Right next to **People**, start typing the name or username of the user you
+want to add.
+
+![Search for people](img/add_user_search_people.png)
+
+---
+
+Select the user and the [permission level](../../permissions/permissions.md)
+that you'd like to give the user. Note that you can select more than one user.
+
+![Give user permissions](img/add_user_give_permissions.png)
+
+---
+
+Once done, hit **Add users to project** and they will be immediately added to
+your project with the permissions you gave them above.
+
+![List members](img/add_user_list_members.png)
+
+---
+
+From there on, you can either remove an existing user or change their access
+level to the project.
+
+## Import users from another project
+
+You can import another project's users in your own project by hitting the
+**Import members** button on the upper right corner of the **Members** menu.
+
+In the dropdown menu, you can see only the projects you are Master on.
+
+![Import members from another project](img/add_user_import_members_from_another_project.png)
+
+---
+
+Select the one you want and hit **Import project members**. A flash message
+notifying you that the import was successful will appear, and the new members
+are now in the project's members list. Notice that the permissions that they
+had on the project you imported from are retained.
+
+![Members list of new members](img/add_user_imported_members.png)
+
+---
+
+## Invite people using their e-mail address
+
+If a user you want to give access to doesn't have an account on your GitLab
+instance, you can invite them just by typing their e-mail address in the
+user search field.
+
+![Invite user by mail](img/add_user_email_search.png)
+
+---
+
+As you can imagine, you can mix inviting multiple people and adding existing
+GitLab users to the project.
+
+![Invite user by mail ready to submit](img/add_user_email_ready.png)
+
+---
+
+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.
+
+![Invite user members list](img/add_user_email_accept.png)
+
+---
+
+Once the user accepts the invitation, they will be prompted to create a new
+GitLab account using the same e-mail address the invitation was sent to.
+
+## Request access to a project
+
+As a user, you can request to be a member of a project. Go to the project you'd
+like to be a member of, and click the **Request Access** button on the right
+side of your screen.
+
+![Request access button](img/request_access_button.png)
+
+---
+
+Project owners & masters will be notified of your request and will be able to approve or
+decline it on the members page.
+
+![Manage access requests](img/access_requests_management.png)
+
+---
+
+If you change your mind before your request is approved, just click the
+**Withdraw Access Request** button.
+
+![Withdraw access request button](img/withdraw_access_request_button.png)
diff --git a/doc/user/workflow/add-user/img/access_requests_management.png b/doc/user/workflow/add-user/img/access_requests_management.png
new file mode 100644
index 00000000000..e9641cb4f85
Binary files /dev/null and b/doc/user/workflow/add-user/img/access_requests_management.png differ
diff --git a/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png b/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png
new file mode 100644
index 00000000000..3da18cdae53
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_new_user_to_project_settings.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_email_accept.png b/doc/user/workflow/add-user/img/add_user_email_accept.png
new file mode 100644
index 00000000000..18aabf93d50
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_email_accept.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_email_ready.png b/doc/user/workflow/add-user/img/add_user_email_ready.png
new file mode 100644
index 00000000000..385d64330c0
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_email_ready.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_email_search.png b/doc/user/workflow/add-user/img/add_user_email_search.png
new file mode 100644
index 00000000000..84741edbca4
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_email_search.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_give_permissions.png b/doc/user/workflow/add-user/img/add_user_give_permissions.png
new file mode 100644
index 00000000000..7e580384e54
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_give_permissions.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png b/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png
new file mode 100644
index 00000000000..8dbd73a5bc8
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_import_members_from_another_project.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_imported_members.png b/doc/user/workflow/add-user/img/add_user_imported_members.png
new file mode 100644
index 00000000000..abac1f59c02
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_imported_members.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_list_members.png b/doc/user/workflow/add-user/img/add_user_list_members.png
new file mode 100644
index 00000000000..e17d88c6f5f
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_list_members.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_members_menu.png b/doc/user/workflow/add-user/img/add_user_members_menu.png
new file mode 100644
index 00000000000..ec5d39f402d
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_members_menu.png differ
diff --git a/doc/user/workflow/add-user/img/add_user_search_people.png b/doc/user/workflow/add-user/img/add_user_search_people.png
new file mode 100644
index 00000000000..eaa062376f4
Binary files /dev/null and b/doc/user/workflow/add-user/img/add_user_search_people.png differ
diff --git a/doc/user/workflow/add-user/img/request_access_button.png b/doc/user/workflow/add-user/img/request_access_button.png
new file mode 100644
index 00000000000..984d640b0f0
Binary files /dev/null and b/doc/user/workflow/add-user/img/request_access_button.png differ
diff --git a/doc/user/workflow/add-user/img/withdraw_access_request_button.png b/doc/user/workflow/add-user/img/withdraw_access_request_button.png
new file mode 100644
index 00000000000..ff54a0e4384
Binary files /dev/null and b/doc/user/workflow/add-user/img/withdraw_access_request_button.png differ
diff --git a/doc/user/workflow/authorization_for_merge_requests.md b/doc/user/workflow/authorization_for_merge_requests.md
new file mode 100644
index 00000000000..d1d6d94ec11
--- /dev/null
+++ b/doc/user/workflow/authorization_for_merge_requests.md
@@ -0,0 +1,40 @@
+# Authorization for Merge requests
+
+There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project.
+
+## Protected branch flow
+
+With the protected branch flow everybody works within the same GitLab project.
+
+The project maintainers get Master access and the regular developers get Developer access.
+
+The maintainers mark the authoritative branches as 'Protected'.
+
+The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches.
+
+Only users with Master access can merge changes into a protected branch.
+
+### Advantages
+
+- fewer projects means less clutter
+- developers need to consider only one remote repository
+
+### Disadvantages
+
+- manual setup of protected branch required for each new project
+
+## Forking workflow
+
+With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it.
+
+Developers create forks of the authoritative project and push their feature branches to their own forks.
+
+To get their changes into master they need to create a merge request across forks.
+
+### Advantages
+
+- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects
+
+### Disadvantages
+
+- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes)
diff --git a/doc/user/workflow/award_emoji.md b/doc/user/workflow/award_emoji.md
new file mode 100644
index 00000000000..70b35c58be6
--- /dev/null
+++ b/doc/user/workflow/award_emoji.md
@@ -0,0 +1,48 @@
+# Award emojis
+
+>**Note:**
+This feature was [introduced][1825] in GitLab 8.2.
+
+When you're collaborating online, you get fewer opportunities for high-fives
+and thumbs-ups. In order to make virtual celebrations easier, you can now vote
+on issues and merge requests using emoji!
+
+![Award emoji](img/award_emoji_select.png)
+
+This makes it much easier to give and receive feedback, without a long comment
+thread. Any comment that contains only the thumbs up or down emojis is
+converted to a vote and depicted in the emoji area.
+
+You can then use that functionality to sort issues and merge requests based on
+popularity.
+
+## Sort issues and merge requests on vote count
+
+>**Note:**
+This feature was [introduced][2871] in GitLab 8.5.
+
+You can quickly sort the issues or merge requests by the number of votes they
+have received. The sort option can be found in the right dropdown menu.
+
+![Votes sort options](img/award_emoji_votes_sort_options.png)
+
+---
+
+Sort by most popular issues/merge requests.
+
+![Votes sort by most popular](img/award_emoji_votes_most_popular.png)
+
+---
+
+Sort by least popular issues/merge requests.
+
+![Votes sort by least popular](img/award_emoji_votes_least_popular.png)
+
+---
+
+The number of upvotes and downvotes is not summed up. That means that an issue
+with 18 upvotes and 5 downvotes is considered more popular than an issue with
+17 upvotes and no downvotes.
+
+[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781
+[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825
diff --git a/doc/user/workflow/award_emoji.png b/doc/user/workflow/award_emoji.png
new file mode 100644
index 00000000000..fb26ee04393
Binary files /dev/null and b/doc/user/workflow/award_emoji.png differ
diff --git a/doc/user/workflow/cherry_pick_changes.md b/doc/user/workflow/cherry_pick_changes.md
new file mode 100644
index 00000000000..4a499009842
--- /dev/null
+++ b/doc/user/workflow/cherry_pick_changes.md
@@ -0,0 +1,53 @@
+# Cherry-pick changes
+
+>**Note:**
+This feature was [introduced][ce-3514] in GitLab 8.7.
+
+---
+
+GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick]
+with introducing a **Cherry-pick** button in Merge Requests and commit details.
+
+## Cherry-picking a Merge Request
+
+After the Merge Request has been merged, a **Cherry-pick** button will be available
+to cherry-pick the changes introduced by that Merge Request:
+
+![Cherry-pick Merge Request](img/cherry_pick_changes_mr.png)
+
+---
+
+You can cherry-pick the changes directly into the selected branch or you can opt to
+create a new Merge Request with the cherry-pick changes:
+
+![Cherry-pick Merge Request modal](img/cherry_pick_changes_mr_modal.png)
+
+## Cherry-picking a Commit
+
+You can cherry-pick a Commit from the Commit details page:
+
+![Cherry-pick commit](img/cherry_pick_changes_commit.png)
+
+---
+
+Similar to cherry-picking a Merge Request, you can opt to cherry-pick the changes
+directly into the target branch or create a new Merge Request to cherry-pick the
+changes:
+
+![Cherry-pick commit modal](img/cherry_pick_changes_commit_modal.png)
+
+---
+
+Please note that when cherry-picking merge commits, the mainline will always be the
+first parent. If you want to use a different mainline then you need to do that
+from the command line.
+
+Here is a quick example to cherry-pick a merge commit using the second parent as the
+mainline:
+
+```bash
+git cherry-pick -m 2 7a39eb0
+```
+
+[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request"
+[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation"
diff --git a/doc/user/workflow/ci_mr.png b/doc/user/workflow/ci_mr.png
new file mode 100644
index 00000000000..a577356f8e8
Binary files /dev/null and b/doc/user/workflow/ci_mr.png differ
diff --git a/doc/user/workflow/close_issue_mr.png b/doc/user/workflow/close_issue_mr.png
new file mode 100644
index 00000000000..a136d642e12
Binary files /dev/null and b/doc/user/workflow/close_issue_mr.png differ
diff --git a/doc/user/workflow/environment_branches.png b/doc/user/workflow/environment_branches.png
new file mode 100644
index 00000000000..ee893ced13b
Binary files /dev/null and b/doc/user/workflow/environment_branches.png differ
diff --git a/doc/user/workflow/file_finder.md b/doc/user/workflow/file_finder.md
new file mode 100644
index 00000000000..b69ae663272
--- /dev/null
+++ b/doc/user/workflow/file_finder.md
@@ -0,0 +1,46 @@
+# File finder
+
+_**Note:** This feature was [introduced][gh-9889] in GitLab 8.4._
+
+---
+
+The file finder feature allows you to quickly shortcut your way when you are
+searching for a file in a repository using the GitLab UI.
+
+You can find the **Find File** button when in the **Files** section of a
+project.
+
+![Find file button](img/file_finder_find_button.png)
+
+---
+
+For those who prefer to keep their fingers on the keyboard, there is a
+[shortcut button](shortcuts.md) as well, which you can invoke from _anywhere_
+in a project.
+
+Press `t` to launch the File search function when in **Issues**,
+**Merge requests**, **Milestones**, even the project's settings.
+
+Start typing what you are searching for and watch the magic happen. With the
+up/down arrows, you go up and down the results, with `Esc` you close the search
+and go back to **Files**.
+
+## How it works
+
+The File finder feature is powered by the [Fuzzy filter] library.
+
+It implements a fuzzy search with highlight, and tries to provide intuitive
+results by recognizing patterns that people use while searching.
+
+For example, consider the [GitLab CE repository][ce] and that we want to open
+the `app/controllers/admin/deploy_keys_controller.rb` file.
+
+Using fuzzy search, we start by typing letters that get us closer to the file.
+
+**Protip:** To narrow down your search, include `/` in your search terms.
+
+![Find file button](img/file_finder_find_file.png)
+
+[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request"
+[fuzzy filter]: https://github.com/jeancroy/fuzzaldrin-plus "fuzzaldrin-plus on GitHub"
+[ce]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master "GitLab CE repository"
diff --git a/doc/user/workflow/forking/branch_select.png b/doc/user/workflow/forking/branch_select.png
new file mode 100644
index 00000000000..275f64d113b
Binary files /dev/null and b/doc/user/workflow/forking/branch_select.png differ
diff --git a/doc/user/workflow/forking/merge_request.png b/doc/user/workflow/forking/merge_request.png
new file mode 100644
index 00000000000..2dc00ed08a1
Binary files /dev/null and b/doc/user/workflow/forking/merge_request.png differ
diff --git a/doc/user/workflow/forking_workflow.md b/doc/user/workflow/forking_workflow.md
new file mode 100644
index 00000000000..217a4a4012f
--- /dev/null
+++ b/doc/user/workflow/forking_workflow.md
@@ -0,0 +1,59 @@
+# Project forking workflow
+
+Forking a project to your own namespace is useful if you have no write
+access to the project you want to contribute to. If you do have write
+access or can request it, we recommend working together in the same
+repository since it is simpler. See our [GitLab Flow](gitlab_flow.md)
+document more information about using branches to work together.
+
+## Creating a fork
+
+Forking a project is in most cases a two-step process.
+
+
+1.  Click on the fork button located in the middle of the page or a project's
+    home page right next to the stars button.
+
+    ![Fork button](img/forking_workflow_fork_button.png)
+
+    ---
+
+1.  Once you do that, you'll be presented with a screen where you can choose
+    the namespace to fork to. Only namespaces (groups and your own
+    namespace) where you have write access to, will be shown. Click on the
+    namespace to create your fork there.
+
+    ![Choose namespace](img/forking_workflow_choose_namespace.png)
+
+    ---
+
+    **Note:**
+    If the namespace you chose to fork the project to has another project with
+    the same path name, you will be presented with a warning that the forking
+    could not be completed. Try to resolve the error and repeat the forking
+    process.
+
+    ![Path taken error](img/forking_workflow_path_taken_error.png)
+
+    ---
+
+After the forking is done, you can start working on the newly created
+repository. There, you will have full [Owner](../permissions/permissions.md)
+access, so you can set it up as you please.
+
+## Merging upstream
+
+Once you are ready to send your code back to the main project, you need
+to create a merge request. Choose your forked project's main branch as
+the source and the original project's main branch as the destination and
+create the [merge request](merge_requests.md).
+
+![Selecting branches](forking/branch_select.png)
+
+You can then assign the merge request to someone to have them review
+your changes. Upon pressing the 'Accept Merge Request' button, your
+changes will be added to the repository and branch you're merging into.
+
+![New merge request](forking/merge_request.png)
+
+[gitlab flow]: https://about.gitlab.com/2014/09/29/gitlab-flow/ "GitLab Flow blog post"
diff --git a/doc/user/workflow/four_stages.png b/doc/user/workflow/four_stages.png
new file mode 100644
index 00000000000..2f444fc6f79
Binary files /dev/null and b/doc/user/workflow/four_stages.png differ
diff --git a/doc/user/workflow/git_pull.png b/doc/user/workflow/git_pull.png
new file mode 100644
index 00000000000..7d47064eb14
Binary files /dev/null and b/doc/user/workflow/git_pull.png differ
diff --git a/doc/user/workflow/gitdashflow.png b/doc/user/workflow/gitdashflow.png
new file mode 100644
index 00000000000..f2f091dd10b
Binary files /dev/null and b/doc/user/workflow/gitdashflow.png differ
diff --git a/doc/user/workflow/github_flow.png b/doc/user/workflow/github_flow.png
new file mode 100644
index 00000000000..88addb623ee
Binary files /dev/null and b/doc/user/workflow/github_flow.png differ
diff --git a/doc/user/workflow/gitlab_flow.md b/doc/user/workflow/gitlab_flow.md
new file mode 100644
index 00000000000..2b2f140f8bf
--- /dev/null
+++ b/doc/user/workflow/gitlab_flow.md
@@ -0,0 +1,317 @@
+![GitLab Flow](gitlab_flow.png)
+
+## Introduction
+
+Version management with git makes branching and merging much easier than older versioning systems such as SVN.
+This allows a wide variety of branching strategies and workflows.
+Almost all of these are an improvement over the methods used before git.
+But many organizations end up with a workflow that is not clearly defined, overly complex or not integrated with issue tracking systems.
+Therefore we propose the GitLab flow as clearly defined set of best practices.
+It combines [feature driven development](https://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](http://martinfowler.com/bliki/FeatureBranch.html) with issue tracking.
+
+Organizations coming to git from other version control systems frequently find it hard to develop an effective workflow.
+This article describes the GitLab flow that integrates the git workflow with an issue tracking system.
+It offers a simple, transparent and effective way to work with git.
+
+![Four stages (working copy, index, local repo, remote repo) and three steps between them](four_stages.png)
+
+When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues.
+Most version control systems have only one step, committing from the working copy to a shared server.
+In git you add files from the working copy to the staging area. After that you commit them to the local repo.
+The third step is pushing to a shared remote repository.
+After getting used to these three steps the branching model becomes the challenge.
+
+![Multiple long running branches and merging in all directions](messy_flow.png)
+
+Since many organizations new to git have no conventions how to work with it, it can quickly become a mess.
+The biggest problem they run into is that many long running branches that each contain part of the changes are around.
+People have a hard time figuring out which branch they should develop on or deploy to production.
+Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html).
+We think there is still room for improvement and will detail a set of practices we call GitLab flow.
+
+## Git flow and its problems
+
+![Git Flow timeline by Vincent Driessen, used with permission](gitdashflow.png)
+
+Git flow was one of the first proposals to use git branches and it has gotten a lot of attention.
+It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes.
+The development happens on the develop branch, moves to a release branch and is finally merged into the master branch.
+Git flow is a well defined standard but its complexity introduces two problems.
+The first problem is that developers must use the develop branch and not master, master is reserved for code that is released to production.
+It is a convention to call your default branch master and to mostly branch from and merge to this.
+Since most tools automatically make the master branch the default one and display that one by default it is annoying to have to switch to another one.
+The second problem of git flow is the complexity introduced by the hotfix and release branches.
+These branches can be a good idea for some organizations but are overkill for the vast majority of them.
+Nowadays most organizations practice continuous delivery which means that your default branch can be deployed.
+This means that hotfix and release branches can be prevented including all the ceremony they introduce.
+An example of this ceremony is the merging back of release branches.
+Though specialized tools do exist to solve this, they require documentation and add complexity.
+Frequently developers make a mistake and for example changes are only merged into master and not into the develop branch.
+The root cause of these errors is that git flow is too complex for most of the use cases.
+And doing releases doesn't automatically mean also doing hotfixes.
+
+## GitHub flow as a simpler alternative
+
+![Master branch with feature branches merged in](github_flow.png)
+
+In reaction to git flow a simpler alternative was detailed, [GitHub flow](https://guides.github.com/introduction/flow/index.html).
+This flow has only feature branches and a master branch.
+This is very simple and clean, many organizations have adopted it with great success.
+Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches.
+Merging everything into the master branch and deploying often means you minimize the amount of code in 'inventory' which is in line with the lean and continuous delivery best practices.
+But this flow still leaves a lot of questions unanswered regarding deployments, environments, releases and integrations with issues.
+With GitLab flow we offer additional guidance for these questions.
+
+## Production branch with GitLab flow
+
+![Master branch and production branch with arrow that indicate deployments](production_branch.png)
+
+GitHub flow does assume you are able to deploy to production every time you merge a feature branch.
+This is possible for SaaS applications but are many cases where this is not possible.
+One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass App Store validation.
+Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times.
+In these cases you can make a production branch that reflects the deployed code.
+You can deploy a new version by merging in master to the production branch.
+If you need to know what code is in production you can just checkout the production branch to see.
+The approximate time of deployment is easily visible as the merge commit in the version control system.
+This time is pretty accurate if you automatically deploy your production branch.
+If you need a more exact time you can have your deployment script create a tag on each deployment.
+This flow prevents the overhead of releasing, tagging and merging that is common to git flow.
+
+## Environment branches with GitLab flow
+
+![Multiple branches with the code cascading from one to another](environment_branches.png)
+
+It might be a good idea to have an environment that is automatically updated to the master branch.
+Only in this case, the name of this environment might differ from the branch name.
+Suppose you have a staging environment, a pre-production environment and a production environment.
+In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch.
+And going live with code happens by merging the pre-production branch into the production branch.
+This workflow where commits only flow downstream ensures that everything has been tested on all environments.
+If you need to cherry-pick a commit with a hotfix it is common to develop it on a feature branch and merge it into master with a merge request, do not delete the feature branch.
+If master is good to go (it should be if you a practicing [continuous delivery](http://martinfowler.com/bliki/ContinuousDelivery.html)) you then merge it to the other branches.
+If this is not possible because more manual testing is required you can send merge requests from the feature branch to the downstream branches.
+An 'extreme' version of environment branches are setting up an environment for each feature branch as done by [Teatro](https://teatro.io/).
+
+## Release branches with GitLab flow
+
+![Master and multiple release branches that vary in length with cherry-picks from master](release_branches.png)
+
+Only in case you need to release software to the outside world you need to work with release branches.
+In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.).
+The stable branch uses master as a starting point and is created as late as possible.
+By branching as late as possible you minimize the time you have to apply bug fixes to multiple branches.
+After a release branch is announced, only serious bug fixes are included in the release branch.
+If possible these bug fixes are first merged into master and then cherry-picked into the release branch.
+This way you can't forget to cherry-pick them into master and encounter the same bug on subsequent releases.
+This is called an 'upstream first' policy that is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/about/news/archive/2013/5/a-community-for-using-openstack-with-red-hat-rdo).
+Every time a bug-fix is included in a release branch the patch version is raised (to comply with [Semantic Versioning](http://semver.org/)) by setting a new tag.
+Some projects also have a stable branch that points to the same commit as the latest released branch.
+In this flow it is not common to have a production branch (or git flow master branch).
+
+## Merge/pull requests with GitLab flow
+
+![Merge request with line comments](mr_inline_comments.png)
+
+Merge or pull requests are created in a git management application and ask an assigned person to merge two branches.
+Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch.
+Tools such as GitLab and Gitorious choose the name merge request since that is the final action that is requested of the assignee.
+In this article we'll refer to them as merge requests.
+
+If you work on a feature branch for more than a few hours it is good to share the intermediate result with the rest of the team.
+This can be done by creating a merge request without assigning it to anyone, instead you mention people in the description or a comment (/cc @mark @susan).
+This means it is not ready to be merged but feedback is welcome.
+Your team members can comment on the merge request in general or on specific lines with line comments.
+The merge requests serves as a code review tool and no separate tools such as Gerrit and reviewboard should be needed.
+If the review reveals shortcomings anyone can commit and push a fix.
+Commonly the person to do this is the creator of the merge/pull request.
+The diff in the merge/pull requests automatically updates when new commits are pushed on the branch.
+
+When you feel comfortable with it to be merged you assign it to the person that knows most about the codebase you are changing and mention any other people you would like feedback from.
+There is room for more feedback and after the assigned person feels comfortable with the result the branch is merged.
+If the assigned person does not feel comfortable they can close the merge request without merging.
+
+In GitLab it is common to protect the long-lived branches (e.g. the master branch) so that normal developers [can't modify these protected branches](http://docs.gitlab.com/ce/permissions/permissions.html).
+So if you want to merge it into a protected branch you assign it to someone with master authorizations.
+
+## Issues with GitLab flow
+
+![Merge request with the branch name 15-require-a-password-to-change-it and assignee field shown](merge_request.png)
+
+GitLab flow is a way to make the relation between the code and the issue tracker more transparent.
+
+Any significant change to the code should start with an issue where the goal is described.
+Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small.
+In GitLab each change to the codebase starts with an issue in the issue tracking system.
+If there is no issue yet it should be created first provided there is significant work involved (more than 1 hour).
+For many organizations this will be natural since the issue will have to be estimated for the sprint.
+Issue titles should describe the desired state of the system, e.g. "As an administrator I want to remove users without receiving an error" instead of "Admin can't remove users.".
+
+When you are ready to code you start a branch for the issue from the master branch.
+The name of this branch should start with the issue number, for example '15-require-a-password-to-change-it'.
+
+When you are done or want to discuss the code you open a merge request.
+This is an online place to discuss the change and review the code.
+Opening a merge request is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch.
+If you open the merge request but do not assign it to anyone it is a 'Work In Progress' merge request.
+These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet.
+_Pro tip:_ Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready.
+
+When the author thinks the code is ready the merge request is assigned to reviewer.
+The reviewer presses the merge button when they think the code is ready for inclusion in the master branch.
+In this case the code is merged and a merge commit is generated that makes this event easily visible later on.
+Merge requests always create a merge commit even when the commit could be added without one.
+This merge strategy is called 'no fast-forward' in git.
+After the merge the feature branch is deleted since it is no longer needed, in GitLab this deletion is an option when merging.
+
+Suppose that a branch is merged but a problem occurs and the issue is reopened.
+In this case it is no problem to reuse the same branch name since it was deleted when the branch was merged.
+At any time there is at most one branch for every issue.
+It is possible that one feature branch solves more than one issue.
+
+## Linking and closing issues from merge requests
+
+![Merge request showing the linked issues that will be closed](close_issue_mr.png)
+
+Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description.
+In GitLab this creates a comment in the issue that the merge requests mentions the issue.
+And the merge request shows the linked issues.
+These issues are closed once code is merged into the default branch.
+
+If you only want to make the reference without closing the issue you can also just mention it: "Duck typing is preferred. #12".
+
+If you have an issue that spans across multiple repositories, the best thing is to create an issue for each repository and link all issues to a parent issue.
+
+## Squashing commits with rebase
+
+![Vim screen showing the rebase view](rebase.png)
+
+With git you can use an interactive rebase (`rebase -i`) to squash multiple commits into one and reorder them.
+In GitLab EE and .com you can also [rebase before merge](http://docs.gitlab.com/ee/workflow/rebase_before_merge.html) from the web interface.
+This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical.
+However you should never rebase commits you have pushed to a remote server.
+Somebody can have referred to the commits or cherry-picked them.
+When you rebase you change the identifier (SHA-1) of the commit and this is confusing.
+If you do that the same change will be known under multiple identifiers and this can cause much confusion.
+If people already reviewed your code it will be hard for them to review only the improvements you made since then if you have rebased everything into one commit.
+Another reasons not to rebase is that you lose authorship information, maybe someone created a merge request, another person pushed a commit on there to improve it and a third one merged it.
+In this case rebasing all the commits into one prevent the other authors from being properly attributed and sharing part of the [git blame](https://git-scm.com/docs/git-blame).
+
+People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on.
+This will lead to many commits per change which makes the history harder to understand.
+But the advantages of having stable identifiers outweigh this drawback.
+And to understand a change in context one can always look at the merge commit that groups all the commits together when the code is merged into the master branch.
+
+After you merge multiple commits from a feature branch into the master branch this is harder to undo.
+If you would have squashed all the commits into one you could have just reverted this commit but as we indicated you should not rebase commits after they are pushed.
+Fortunately [reverting a merge made some time ago](https://git-scm.com/blog/2010/03/02/undoing-merges.html) can be done with git.
+This however, requires having specific merge commits for the commits your want to revert.
+If you revert a merge and you change your mind, revert the revert instead of merging again since git will not allow you to merge the code again otherwise.
+
+Being able to revert a merge is a good reason always to create a merge commit when you merge manually with the `--no-ff` option.
+Git management software will always create a merge commit when you accept a merge request.
+
+## Do not order commits with rebase
+
+![List of sequential merge commits](merge_commits.png)
+
+With git you can also rebase your feature branch commits to order them after the commits on the master branch.
+This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history.
+However, just like with squashing you should never rebase commits you have pushed to a remote server.
+This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend.
+When using rebase to keep your feature branch updated you [need to resolve similar conflicts again and again](https://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/).
+You can reuse recorded resolutions (rerere) sometimes, but without rebasing you only have to solve the conflicts one time and you’re set.
+There has to be a better way to avoid many merge commits.
+
+The way to prevent creating many merge commits is to not frequently merge master into the feature branch.
+We'll discuss the three reasons to merge in master: leveraging code, merge conflicts, and long running branches.
+If you need to leverage some code that was introduced in master after you created the feature branch you can sometimes solve this by just cherry-picking a commit.
+If your feature branch has a merge conflict, creating a merge commit is a normal way of solving this.
+You can prevent some merge conflicts by using [gitattributes](http://git-scm.com/docs/gitattributes) for files that can be in a random order.
+For example in GitLab our changelog file is specified in .gitattributes as `CHANGELOG merge=union` so that there are fewer merge conflicts in it.
+The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project.
+Martin Fowler, in [his article about feature branches](http://martinfowler.com/bliki/FeatureBranch.html) talks about this Continuous Integration (CI).
+At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit.
+That's continuous building, and a Good Thing, but there's no integration, so it's not CI.".
+The solution to prevent many merge commits is to keep your feature branches short-lived, the vast majority should take less than one day of work.
+If your feature branches commonly take more than a day of work, look into ways to create smaller units of work and/or use [feature toggles](http://martinfowler.com/bliki/FeatureToggle.html).
+As for the long running branches that take more than one day there are two strategies.
+In a CI strategy you can merge in master at the start of the day to prevent painful merges at a later time.
+In a synchronization point strategy you only merge in from well defined points in time, for example a tagged release.
+This strategy is [advocated by Linus Torvalds](https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html) because the state of the code at these points is better known.
+
+In conclusion, we can say that you should try to prevent merge commits, but not eliminate them.
+Your codebase should be clean but your history should represent what actually happened.
+Developing software happen in small messy steps and it is OK to have your history reflect this.
+You can use tools to view the network graphs of commits and understand the messy history that created your code.
+If you rebase code the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers.
+
+## Award emojis on issues and merge requests
+
+![Emoji bar in GitLab](award_emoji.png)
+
+It is common to voice approval or disapproval by using +1 or -1. In GitLab you
+can use emojis to give a virtual high five on issues and merge requests.
+
+## Pushing and removing branches
+
+![Remove checkbox for branch in merge requests](remove_checkbox.png)
+
+We recommend that people push their feature branches frequently, even when they are not ready for review yet.
+By doing this you prevent team members from accidentally starting to work on the same issue.
+Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software.
+However sometimes one of the two parties forgets to assign someone in the issue tracking software.
+After a branch is merged it should be removed from the source control software.
+In GitLab and similar systems this is an option when merging.
+This ensures that the branch overview in the repository management software shows only work in progress.
+This also ensures that when someone reopens the issue a new branch with the same name can be used without problem.
+When you reopen an issue you need to create a new merge request.
+
+## Committing often and with the right message
+
+![Good and bad commit message](good_commit.png)
+
+We recommend to commit early and often.
+Each time you have a functioning set of tests and code a commit can be made.
+The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version.
+This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share.
+The trick is to use the merge/pull request with multiple commits when your work is ready to share.
+The commit message should reflect your intention, not the contents of the commit.
+The contents of the commit can be easily seen anyway, the question is why you did it.
+An example of a good commit message is: "Combine templates to dry up the user views.".
+Some words that are bad commit messages because they don't contain munch information are: change, improve and refactor.
+The word fix or fixes is also a red flag, unless it comes after the commit sentence and references an issue number.
+To see more information about the formatting of commit messages please see this great [blog post by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+
+## Testing before merging
+
+![Merge requests showing the test states, red, yellow and green](ci_mr.png)
+
+In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only.
+Developers had to ensure their code did not break the master branch.
+When using GitLab flow developers create their branches from this master branch so it is essential it is green.
+Therefore each merge request must be tested before it is accepted.
+CI software like Travis and GitLab CI show the build results right in the merge request itself to make this easy.
+One drawback is that they are testing the feature branch itself and not the merged result.
+What one can do to improve this is to test the merged result itself.
+The problem is that the merge result changes every time something is merged into master.
+Retesting on every commit to master is computationally expensive and means you are more frequently waiting for test results.
+If there are no merge conflicts and the feature branches are short lived the risk is acceptable.
+If there are merge conflicts you merge the master branch into the feature branch and the CI server will rerun the tests.
+If you have long lived feature branches that last for more than a few days you should make your issues smaller.
+
+## Merging in other code
+
+![Shell output showing git pull output](git_pull.png)
+
+When initiating a feature branch, always start with an up to date master to branch off from.
+If you know beforehand that your work absolutely depends on another branch you can also branch from there.
+If you need to merge in another branch after starting explain the reason in the merge commit.
+If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch.
+Do not merge in upstream if your code will work and merge cleanly without doing so, Linus even says that [you should never merge in upstream at random points, only at major releases](https://lwn.net/Articles/328438/).
+Merging only when needed prevents creating merge commits in your feature branch that later end up littering the master history.
+
+### References
+
+- [Sketch file](https://www.dropbox.com/s/58dvsj5votbwrzv/git_flows.sketch?dl=0) with vectors of images in this article
+- [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/)
diff --git a/doc/user/workflow/gitlab_flow.png b/doc/user/workflow/gitlab_flow.png
new file mode 100644
index 00000000000..1ea191a672b
Binary files /dev/null and b/doc/user/workflow/gitlab_flow.png differ
diff --git a/doc/user/workflow/good_commit.png b/doc/user/workflow/good_commit.png
new file mode 100644
index 00000000000..3737a026644
Binary files /dev/null and b/doc/user/workflow/good_commit.png differ
diff --git a/doc/user/workflow/groups.md b/doc/user/workflow/groups.md
new file mode 100644
index 00000000000..1a316e80976
--- /dev/null
+++ b/doc/user/workflow/groups.md
@@ -0,0 +1,93 @@
+# GitLab Groups
+
+GitLab groups allow you to group projects into directories and give users to several projects at once.
+
+When you create a new project in GitLab, the default namespace for the project is the personal namespace associated with your GitLab user.
+In this document we will see how to create groups, put projects in groups and manage who can access the projects in a group.
+
+## Creating groups
+
+You can create a group by going to the 'Groups' tab of the GitLab dashboard and clicking the 'New group' button.
+
+![Click the 'New group' button in the 'Groups' tab](groups/new_group_button.png)
+
+Next, enter the name (required) and the optional description and group avatar.
+
+![Fill in the name for your new group](groups/new_group_form.png)
+
+When your group has been created you are presented with the group dashboard feed, which will be empty.
+
+![Group dashboard](groups/group_dashboard.png)
+
+You can use the 'New project' button to add a project to the new group.
+
+## Transferring an existing project into a group
+
+You can transfer an existing project into a group you own from the project settings page.
+First scroll down to the 'Dangerous settings' and click 'Show them to me'.
+Now you can pick any of the groups you manage as the new namespace for the group.
+
+![Transfer a project to a new namespace](groups/transfer_project.png)
+
+GitLab administrators can use the admin interface to move any project to any namespace if needed.
+
+## Adding users to a group
+
+One of the benefits of putting multiple projects in one group is that you can give a user to access to all projects in the group with one action.
+
+Suppose we have a group with two projects.
+
+![Group with two projects](groups/group_with_two_projects.png)
+
+On the 'Group Members' page we can now add a new user Barry to the group.
+
+![Add user Barry to the group](groups/add_member_to_group.png)
+
+Now because Barry is a 'Developer' member of the 'Open Source' group, he automatically gets 'Developer' access to all projects in the 'Open Source' group.
+
+![Barry has 'Developer' access to GitLab CI](groups/project_members_via_group.png)
+
+If necessary, you can increase the access level of an individual user for a specific project, by adding them as a Member to the project.
+
+![Barry effectively has 'Master' access to GitLab CI now](groups/override_access_level.png)
+
+## Request access to a group
+
+As a user, you can request to be a member of a group. Go to the group you'd
+like to be a member of, and click the **Request Access** button on the right
+side of your screen.
+
+![Request access button](groups/request_access_button.png)
+
+---
+
+Group owners & masters will be notified of your request and will be able to approve or
+decline it on the members page.
+
+![Manage access requests](groups/access_requests_management.png)
+
+---
+
+If you change your mind before your request is approved, just click the
+**Withdraw Access Request** button.
+
+![Withdraw access request button](groups/withdraw_access_request_button.png)
+
+## Managing group memberships via LDAP
+
+In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups.
+See [the GitLab Enterprise Edition documentation](http://docs.gitlab.com/ee/integration/ldap.html) for more information.
+
+## Allowing only admins to create groups
+
+By default, any GitLab user can create new groups.
+This ability can be disabled for individual users from the admin panel.
+It is also possible to configure GitLab so that new users default to not being able to create groups:
+
+```
+# For omnibus-gitlab, put the following in /etc/gitlab/gitlab.rb
+gitlab_rails['gitlab_default_can_create_group'] = false
+
+# For installations from source, uncomment the 'default_can_create_group'
+# line in /home/git/gitlab/config/gitlab.yml
+```
diff --git a/doc/user/workflow/groups/access_requests_management.png b/doc/user/workflow/groups/access_requests_management.png
new file mode 100644
index 00000000000..ffede8e9bd6
Binary files /dev/null and b/doc/user/workflow/groups/access_requests_management.png differ
diff --git a/doc/user/workflow/groups/add_member_to_group.png b/doc/user/workflow/groups/add_member_to_group.png
new file mode 100644
index 00000000000..fa340ce572f
Binary files /dev/null and b/doc/user/workflow/groups/add_member_to_group.png differ
diff --git a/doc/user/workflow/groups/group_dashboard.png b/doc/user/workflow/groups/group_dashboard.png
new file mode 100644
index 00000000000..7fc9048d74d
Binary files /dev/null and b/doc/user/workflow/groups/group_dashboard.png differ
diff --git a/doc/user/workflow/groups/group_with_two_projects.png b/doc/user/workflow/groups/group_with_two_projects.png
new file mode 100644
index 00000000000..87242781e4f
Binary files /dev/null and b/doc/user/workflow/groups/group_with_two_projects.png differ
diff --git a/doc/user/workflow/groups/max_access_level.png b/doc/user/workflow/groups/max_access_level.png
new file mode 100644
index 00000000000..71106a8a5a0
Binary files /dev/null and b/doc/user/workflow/groups/max_access_level.png differ
diff --git a/doc/user/workflow/groups/new_group_button.png b/doc/user/workflow/groups/new_group_button.png
new file mode 100644
index 00000000000..51e82798658
Binary files /dev/null and b/doc/user/workflow/groups/new_group_button.png differ
diff --git a/doc/user/workflow/groups/new_group_form.png b/doc/user/workflow/groups/new_group_form.png
new file mode 100644
index 00000000000..bf992c40bc2
Binary files /dev/null and b/doc/user/workflow/groups/new_group_form.png differ
diff --git a/doc/user/workflow/groups/other_group_sees_shared_project.png b/doc/user/workflow/groups/other_group_sees_shared_project.png
new file mode 100644
index 00000000000..cbf2c3c1fdc
Binary files /dev/null and b/doc/user/workflow/groups/other_group_sees_shared_project.png differ
diff --git a/doc/user/workflow/groups/override_access_level.png b/doc/user/workflow/groups/override_access_level.png
new file mode 100644
index 00000000000..f4225a63679
Binary files /dev/null and b/doc/user/workflow/groups/override_access_level.png differ
diff --git a/doc/user/workflow/groups/project_members_via_group.png b/doc/user/workflow/groups/project_members_via_group.png
new file mode 100644
index 00000000000..b13cb1cfd95
Binary files /dev/null and b/doc/user/workflow/groups/project_members_via_group.png differ
diff --git a/doc/user/workflow/groups/request_access_button.png b/doc/user/workflow/groups/request_access_button.png
new file mode 100644
index 00000000000..ff0ac8747a7
Binary files /dev/null and b/doc/user/workflow/groups/request_access_button.png differ
diff --git a/doc/user/workflow/groups/share_project_with_groups.png b/doc/user/workflow/groups/share_project_with_groups.png
new file mode 100644
index 00000000000..a5dbc89fe90
Binary files /dev/null and b/doc/user/workflow/groups/share_project_with_groups.png differ
diff --git a/doc/user/workflow/groups/transfer_project.png b/doc/user/workflow/groups/transfer_project.png
new file mode 100644
index 00000000000..044fe10d073
Binary files /dev/null and b/doc/user/workflow/groups/transfer_project.png differ
diff --git a/doc/user/workflow/groups/withdraw_access_request_button.png b/doc/user/workflow/groups/withdraw_access_request_button.png
new file mode 100644
index 00000000000..99d7a326ed8
Binary files /dev/null and b/doc/user/workflow/groups/withdraw_access_request_button.png differ
diff --git a/doc/user/workflow/img/award_emoji_select.png b/doc/user/workflow/img/award_emoji_select.png
new file mode 100644
index 00000000000..fffdfedda5d
Binary files /dev/null and b/doc/user/workflow/img/award_emoji_select.png differ
diff --git a/doc/user/workflow/img/award_emoji_votes_least_popular.png b/doc/user/workflow/img/award_emoji_votes_least_popular.png
new file mode 100644
index 00000000000..2ef5be7154f
Binary files /dev/null and b/doc/user/workflow/img/award_emoji_votes_least_popular.png differ
diff --git a/doc/user/workflow/img/award_emoji_votes_most_popular.png b/doc/user/workflow/img/award_emoji_votes_most_popular.png
new file mode 100644
index 00000000000..5b089730d93
Binary files /dev/null and b/doc/user/workflow/img/award_emoji_votes_most_popular.png differ
diff --git a/doc/user/workflow/img/award_emoji_votes_sort_options.png b/doc/user/workflow/img/award_emoji_votes_sort_options.png
new file mode 100644
index 00000000000..9bbf3f82a0b
Binary files /dev/null and b/doc/user/workflow/img/award_emoji_votes_sort_options.png differ
diff --git a/doc/user/workflow/img/cherry_pick_changes_commit.png b/doc/user/workflow/img/cherry_pick_changes_commit.png
new file mode 100644
index 00000000000..ae91d2cae53
Binary files /dev/null and b/doc/user/workflow/img/cherry_pick_changes_commit.png differ
diff --git a/doc/user/workflow/img/cherry_pick_changes_commit_modal.png b/doc/user/workflow/img/cherry_pick_changes_commit_modal.png
new file mode 100644
index 00000000000..f502f87677a
Binary files /dev/null and b/doc/user/workflow/img/cherry_pick_changes_commit_modal.png differ
diff --git a/doc/user/workflow/img/cherry_pick_changes_mr.png b/doc/user/workflow/img/cherry_pick_changes_mr.png
new file mode 100644
index 00000000000..59c610e620b
Binary files /dev/null and b/doc/user/workflow/img/cherry_pick_changes_mr.png differ
diff --git a/doc/user/workflow/img/cherry_pick_changes_mr_modal.png b/doc/user/workflow/img/cherry_pick_changes_mr_modal.png
new file mode 100644
index 00000000000..96a80f4726d
Binary files /dev/null and b/doc/user/workflow/img/cherry_pick_changes_mr_modal.png differ
diff --git a/doc/user/workflow/img/file_finder_find_button.png b/doc/user/workflow/img/file_finder_find_button.png
new file mode 100644
index 00000000000..c5005d0d7ca
Binary files /dev/null and b/doc/user/workflow/img/file_finder_find_button.png differ
diff --git a/doc/user/workflow/img/file_finder_find_file.png b/doc/user/workflow/img/file_finder_find_file.png
new file mode 100644
index 00000000000..58500f4c163
Binary files /dev/null and b/doc/user/workflow/img/file_finder_find_file.png differ
diff --git a/doc/user/workflow/img/forking_workflow_choose_namespace.png b/doc/user/workflow/img/forking_workflow_choose_namespace.png
new file mode 100644
index 00000000000..eefe5769554
Binary files /dev/null and b/doc/user/workflow/img/forking_workflow_choose_namespace.png differ
diff --git a/doc/user/workflow/img/forking_workflow_fork_button.png b/doc/user/workflow/img/forking_workflow_fork_button.png
new file mode 100644
index 00000000000..49e68d33e89
Binary files /dev/null and b/doc/user/workflow/img/forking_workflow_fork_button.png differ
diff --git a/doc/user/workflow/img/forking_workflow_path_taken_error.png b/doc/user/workflow/img/forking_workflow_path_taken_error.png
new file mode 100644
index 00000000000..7a3139506fe
Binary files /dev/null and b/doc/user/workflow/img/forking_workflow_path_taken_error.png differ
diff --git a/doc/user/workflow/img/new_branch_from_issue.png b/doc/user/workflow/img/new_branch_from_issue.png
new file mode 100644
index 00000000000..394c139e17e
Binary files /dev/null and b/doc/user/workflow/img/new_branch_from_issue.png differ
diff --git a/doc/user/workflow/img/revert_changes_commit.png b/doc/user/workflow/img/revert_changes_commit.png
new file mode 100644
index 00000000000..d84211e20db
Binary files /dev/null and b/doc/user/workflow/img/revert_changes_commit.png differ
diff --git a/doc/user/workflow/img/revert_changes_commit_modal.png b/doc/user/workflow/img/revert_changes_commit_modal.png
new file mode 100644
index 00000000000..e94d151a2af
Binary files /dev/null and b/doc/user/workflow/img/revert_changes_commit_modal.png differ
diff --git a/doc/user/workflow/img/revert_changes_mr.png b/doc/user/workflow/img/revert_changes_mr.png
new file mode 100644
index 00000000000..7adad88463b
Binary files /dev/null and b/doc/user/workflow/img/revert_changes_mr.png differ
diff --git a/doc/user/workflow/img/revert_changes_mr_modal.png b/doc/user/workflow/img/revert_changes_mr_modal.png
new file mode 100644
index 00000000000..9da78f84828
Binary files /dev/null and b/doc/user/workflow/img/revert_changes_mr_modal.png differ
diff --git a/doc/user/workflow/img/todos_icon.png b/doc/user/workflow/img/todos_icon.png
new file mode 100644
index 00000000000..879b3b51c21
Binary files /dev/null and b/doc/user/workflow/img/todos_icon.png differ
diff --git a/doc/user/workflow/img/todos_index.png b/doc/user/workflow/img/todos_index.png
new file mode 100644
index 00000000000..4ee18dd1285
Binary files /dev/null and b/doc/user/workflow/img/todos_index.png differ
diff --git a/doc/user/workflow/img/web_editor_new_branch_dropdown.png b/doc/user/workflow/img/web_editor_new_branch_dropdown.png
new file mode 100644
index 00000000000..009e4b05adf
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_branch_dropdown.png differ
diff --git a/doc/user/workflow/img/web_editor_new_branch_page.png b/doc/user/workflow/img/web_editor_new_branch_page.png
new file mode 100644
index 00000000000..dd6cfc6e7bb
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_branch_page.png differ
diff --git a/doc/user/workflow/img/web_editor_new_directory_dialog.png b/doc/user/workflow/img/web_editor_new_directory_dialog.png
new file mode 100644
index 00000000000..2c76f84f395
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_directory_dialog.png differ
diff --git a/doc/user/workflow/img/web_editor_new_directory_dropdown.png b/doc/user/workflow/img/web_editor_new_directory_dropdown.png
new file mode 100644
index 00000000000..cedf46aedfd
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_directory_dropdown.png differ
diff --git a/doc/user/workflow/img/web_editor_new_file_dropdown.png b/doc/user/workflow/img/web_editor_new_file_dropdown.png
new file mode 100644
index 00000000000..6e884f6504d
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_file_dropdown.png differ
diff --git a/doc/user/workflow/img/web_editor_new_file_editor.png b/doc/user/workflow/img/web_editor_new_file_editor.png
new file mode 100644
index 00000000000..c76473bcfa7
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_file_editor.png differ
diff --git a/doc/user/workflow/img/web_editor_new_push_widget.png b/doc/user/workflow/img/web_editor_new_push_widget.png
new file mode 100644
index 00000000000..a2108735741
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_push_widget.png differ
diff --git a/doc/user/workflow/img/web_editor_new_tag_dropdown.png b/doc/user/workflow/img/web_editor_new_tag_dropdown.png
new file mode 100644
index 00000000000..263dd635b95
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_tag_dropdown.png differ
diff --git a/doc/user/workflow/img/web_editor_new_tag_page.png b/doc/user/workflow/img/web_editor_new_tag_page.png
new file mode 100644
index 00000000000..64d7cd11ed1
Binary files /dev/null and b/doc/user/workflow/img/web_editor_new_tag_page.png differ
diff --git a/doc/user/workflow/img/web_editor_start_new_merge_request.png b/doc/user/workflow/img/web_editor_start_new_merge_request.png
new file mode 100644
index 00000000000..be12a151cac
Binary files /dev/null and b/doc/user/workflow/img/web_editor_start_new_merge_request.png differ
diff --git a/doc/user/workflow/img/web_editor_upload_file_dialog.png b/doc/user/workflow/img/web_editor_upload_file_dialog.png
new file mode 100644
index 00000000000..6dd2207bca0
Binary files /dev/null and b/doc/user/workflow/img/web_editor_upload_file_dialog.png differ
diff --git a/doc/user/workflow/img/web_editor_upload_file_dropdown.png b/doc/user/workflow/img/web_editor_upload_file_dropdown.png
new file mode 100644
index 00000000000..bf6528701b0
Binary files /dev/null and b/doc/user/workflow/img/web_editor_upload_file_dropdown.png differ
diff --git a/doc/user/workflow/importing/README.md b/doc/user/workflow/importing/README.md
new file mode 100644
index 00000000000..18e5d950866
--- /dev/null
+++ b/doc/user/workflow/importing/README.md
@@ -0,0 +1,17 @@
+# Migrating projects to a GitLab instance
+
+1. [Bitbucket](import_projects_from_bitbucket.md)
+1. [GitHub](import_projects_from_github.md)
+1. [GitLab.com](import_projects_from_gitlab_com.md)
+1. [FogBugz](import_projects_from_fogbugz.md)
+1. [SVN](migrating_from_svn.md)
+
+In addition to the specific migration documentation above, you can import any
+Git repository via HTTP from the New Project page. Be aware that if the
+repository is too large the import can timeout.
+
+### Migrating from self-hosted GitLab to GitLab.com
+
+You can copy your repos by changing the remote and pushing to the new server;
+but issues and merge requests can't be imported.
+
diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png
new file mode 100644
index 00000000000..df55a081803
Binary files /dev/null and b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png differ
diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png
new file mode 100644
index 00000000000..5253889d251
Binary files /dev/null and b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png differ
diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png
new file mode 100644
index 00000000000..ffa87ce5b2e
Binary files /dev/null and b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png differ
diff --git a/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png
new file mode 100644
index 00000000000..0e08703f421
Binary files /dev/null and b/doc/user/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png differ
diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png
new file mode 100644
index 00000000000..205c515bd3f
Binary files /dev/null and b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_finished.png differ
diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png
new file mode 100644
index 00000000000..a1e348d46ad
Binary files /dev/null and b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_login.png differ
diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png
new file mode 100644
index 00000000000..ed362846909
Binary files /dev/null and b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png differ
diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png
new file mode 100644
index 00000000000..d2fbd0267bd
Binary files /dev/null and b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png differ
diff --git a/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png
new file mode 100644
index 00000000000..b1cc4b58525
Binary files /dev/null and b/doc/user/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png differ
diff --git a/doc/user/workflow/importing/gitlab_importer/importer.png b/doc/user/workflow/importing/gitlab_importer/importer.png
new file mode 100644
index 00000000000..d2a286d8cac
Binary files /dev/null and b/doc/user/workflow/importing/gitlab_importer/importer.png differ
diff --git a/doc/user/workflow/importing/gitlab_importer/new_project_page.png b/doc/user/workflow/importing/gitlab_importer/new_project_page.png
new file mode 100644
index 00000000000..5e239208e1e
Binary files /dev/null and b/doc/user/workflow/importing/gitlab_importer/new_project_page.png differ
diff --git a/doc/user/workflow/importing/img/import_projects_from_github_importer.png b/doc/user/workflow/importing/img/import_projects_from_github_importer.png
new file mode 100644
index 00000000000..f744dc06f81
Binary files /dev/null and b/doc/user/workflow/importing/img/import_projects_from_github_importer.png differ
diff --git a/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png
new file mode 100644
index 00000000000..86be35acb37
Binary files /dev/null and b/doc/user/workflow/importing/img/import_projects_from_github_new_project_page.png differ
diff --git a/doc/user/workflow/importing/import_projects_from_bitbucket.md b/doc/user/workflow/importing/import_projects_from_bitbucket.md
new file mode 100644
index 00000000000..520c4216295
--- /dev/null
+++ b/doc/user/workflow/importing/import_projects_from_bitbucket.md
@@ -0,0 +1,26 @@
+# Import your project from Bitbucket to GitLab
+
+It takes just a few steps to import your existing Bitbucket projects to GitLab. But keep in mind that it is possible only if Bitbucket support is enabled on your GitLab instance. You can read more about Bitbucket support [here](../../integration/bitbucket.md).
+
+* Sign in to GitLab.com and go to your dashboard
+
+* Click on "New project"
+
+![New project in GitLab](bitbucket_importer/bitbucket_import_new_project.png)
+
+* Click on the "Bitbucket" button
+
+![Bitbucket](bitbucket_importer/bitbucket_import_select_bitbucket.png)
+
+* Grant GitLab access to your Bitbucket account
+
+![Grant access](bitbucket_importer/bitbucket_import_grant_access.png)
+
+* Click on the projects that you'd like to import or "Import all projects"
+
+![Import projects](bitbucket_importer/bitbucket_import_select_project.png)
+
+A new GitLab project will be created with your imported data.
+
+### Note
+Milestones and wiki pages are not imported from Bitbucket.
diff --git a/doc/user/workflow/importing/import_projects_from_fogbugz.md b/doc/user/workflow/importing/import_projects_from_fogbugz.md
new file mode 100644
index 00000000000..71af0f9ea44
--- /dev/null
+++ b/doc/user/workflow/importing/import_projects_from_fogbugz.md
@@ -0,0 +1,29 @@
+# Import your project from FogBugz to GitLab
+
+It only takes a few simple steps to import your project from FogBugz.
+The importer will import all of your cases and comments with original case
+numbers and timestamps. You will also have the opportunity to map FogBugz
+users to GitLab users.
+
+* From your GitLab dashboard click 'New project'
+
+* Click on the 'FogBugz' button
+
+![FogBugz](fogbugz_importer/fogbugz_import_select_fogbogz.png)
+
+* Enter your FogBugz URL, email address, and password.
+
+![Login](fogbugz_importer/fogbugz_import_login.png)
+
+* Create mapping from FogBugz users to GitLab users.
+
+![User Map](fogbugz_importer/fogbugz_import_user_map.png)
+
+* Select the projects you wish to import by clicking the Import buttons
+
+![Import Project](fogbugz_importer/fogbugz_import_select_project.png)
+
+* Once the import has finished click the link to take you to the project
+dashboard. Follow the directions to push your existing repository.
+
+![Finished](fogbugz_importer/fogbugz_import_finished.png)
diff --git a/doc/user/workflow/importing/import_projects_from_github.md b/doc/user/workflow/importing/import_projects_from_github.md
new file mode 100644
index 00000000000..a7dfac2c120
--- /dev/null
+++ b/doc/user/workflow/importing/import_projects_from_github.md
@@ -0,0 +1,48 @@
+# Import your project from GitHub to GitLab
+
+>**Note:**
+In order to enable the GitHub import setting, you should first
+enable the [GitHub integration][gh-import] in your GitLab instance.
+
+At its current state, GitHub importer can import:
+
+- the repository description (introduced in GitLab 7.7)
+- the git repository data (introduced in GitLab 7.7)
+- the issues (introduced in GitLab 7.7)
+- the pull requests (introduced in GitLab 8.4)
+- the wiki pages (introduced in GitLab 8.4)
+- the milestones (introduced in GitLab 8.7)
+- the labels (introduced in GitLab 8.7)
+
+With GitLab 8.7+, references to pull requests and issues are preserved.
+
+It is not yet possible to import your cross-repository pull requests (those from
+forks). We are working on improving this in the near future.
+
+The importer page is visible when you [create a new project][new-project].
+Click on the **GitHub** link and you will be redirected to GitHub for
+permission to access your projects. After accepting, you'll be automatically
+redirected to the importer.
+
+![New project page on GitLab](img/import_projects_from_github_new_project_page.png)
+
+---
+
+While at the GitHub importer page, you can see the import statuses of your
+GitHub projects. Those that are being imported will show a _started_ status,
+those already imported will be green, whereas those that are not yet imported
+have an **Import** button on the right side of the table. If you want, you can
+import all your GitHub projects in one go by hitting **Import all projects**
+in the upper left corner.
+
+![GitHub importer page](img/import_projects_from_github_importer.png)
+
+---
+
+The importer will create any new namespaces if they don't exist or in the
+case the namespace is taken, the project will be imported on the user's
+namespace.
+
+[gh-import]: ../../integration/github.md "GitHub integration"
+[ee-gh]: http://docs.gitlab.com/ee/integration/github.html "GitHub integration for GitLab EE"
+[new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"
diff --git a/doc/user/workflow/importing/import_projects_from_gitlab_com.md b/doc/user/workflow/importing/import_projects_from_gitlab_com.md
new file mode 100644
index 00000000000..dcc00074b75
--- /dev/null
+++ b/doc/user/workflow/importing/import_projects_from_gitlab_com.md
@@ -0,0 +1,18 @@
+# Project importing from GitLab.com to your private GitLab instance
+
+You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if
+GitLab support is enabled on your GitLab instance. 
+You can read more about GitLab support [here](http://docs.gitlab.com/ce/integration/gitlab.html)
+To get to the importer page you need to go to "New project" page.
+
+![New project page](gitlab_importer/new_project_page.png)
+
+Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com
+for permission to access your projects. After accepting, you'll be automatically redirected to the importer.
+
+
+![Importer page](gitlab_importer/importer.png)
+
+
+To import a project, you can simple click "Import". The importer will import your repository and issues. 
+Once the importer is done, a new GitLab project will be created with your imported data.
\ No newline at end of file
diff --git a/doc/user/workflow/importing/migrating_from_svn.md b/doc/user/workflow/importing/migrating_from_svn.md
new file mode 100644
index 00000000000..4828bb5dce6
--- /dev/null
+++ b/doc/user/workflow/importing/migrating_from_svn.md
@@ -0,0 +1,79 @@
+# Migrating from SVN to GitLab
+
+Subversion (SVN) is a central version control system (VCS) while
+Git is a distributed version control system. There are some major differences
+between the two, for more information consult your favorite search engine.
+
+If you are currently using an SVN repository, you can migrate the repository
+to Git and GitLab. We recommend a hard cut over - run the migration command once
+and then have all developers start using the new GitLab repository immediately.
+Otherwise, it's hard to keep changing in sync in both directions. The conversion
+process should be run on a local workstation.
+
+Install `svn2git`. On all systems you can install as a Ruby gem if you already
+have Ruby and Git installed.
+
+```bash
+sudo gem install svn2git
+```
+
+On Debian-based Linux distributions you can install the native packages:
+
+```bash
+sudo apt-get install git-core git-svn ruby
+```
+
+Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors.
+If you choose not to create the authors file then commits will not be attributed
+to the correct GitLab user. Some users may not consider this a big issue while
+others will want to ensure they complete this step. If you choose to map authors
+you will be required to map every author that is present on changes in the SVN
+repository. If you don't, the conversion will fail and you will have to update
+the author file accordingly. The following command will search through the
+repository and output a list of authors.
+
+```bash
+svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq
+```
+
+Use the output from the last command to construct the authors file.
+Create a file called `authors.txt` and add one mapping per line.
+
+```
+janedoe = Jane Doe <janedoe@example.com>
+johndoe = John Doe <johndoe@example.com>
+```
+
+If your SVN repository is in the standard format (trunk, branches, tags,
+not nested) the conversion is simple. For a non-standard repository see
+[svn2git documentation](https://github.com/nirvdrum/svn2git). The following
+command will checkout the repository and do the conversion in the current
+working directory. Be sure to create a new directory for each repository before
+running the `svn2git` command. The conversion process will take some time.
+
+```bash
+svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt
+```
+
+If your SVN repository requires a username and password add the
+`--username <username>` and `--password <password` flags to the above command.
+`svn2git` also supports excluding certain file paths, branches, tags, etc. See
+[svn2git documentation](https://github.com/nirvdrum/svn2git) or run
+`svn2git --help` for full documentation on all of the available options.
+
+Create a new GitLab project, where you will eventually push your converted code.
+Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab
+repository as a Git remote and push all the changes. This will push all commits,
+branches and tags.
+
+```bash
+git remote add origin git@gitlab.com:<group>/<project>.git
+git push --all origin
+git push --tags origin
+```
+
+## Contribute to this guide
+We welcome all contributions that would expand this guide with instructions on
+how to migrate from SVN and other version control systems.
+
+
diff --git a/doc/user/workflow/labels.md b/doc/user/workflow/labels.md
new file mode 100644
index 00000000000..6e4840ca5ae
--- /dev/null
+++ b/doc/user/workflow/labels.md
@@ -0,0 +1,18 @@
+# Labels
+
+In GitLab, you can easily tag issues and Merge Requests. If you have permission level `Developer` or higher, you can manage labels. To create, edit or delete a label, go to a project and then to `Issues` and then `Labels`.
+
+Here you can create a new label.
+
+![new label](labels/label1.png)
+
+You can choose to set a color.
+
+![label color](labels/label2.png)
+
+If you want to change an existing label, press edit next to the listed label.
+You will be presented with the same form as when creating a new label.
+
+![edit label](labels/label3.png)
+
+You can add labels to Merge Requests when you create or edit them.
diff --git a/doc/user/workflow/labels/label1.png b/doc/user/workflow/labels/label1.png
new file mode 100644
index 00000000000..cac661a34c8
Binary files /dev/null and b/doc/user/workflow/labels/label1.png differ
diff --git a/doc/user/workflow/labels/label2.png b/doc/user/workflow/labels/label2.png
new file mode 100644
index 00000000000..44d9fef86d4
Binary files /dev/null and b/doc/user/workflow/labels/label2.png differ
diff --git a/doc/user/workflow/labels/label3.png b/doc/user/workflow/labels/label3.png
new file mode 100644
index 00000000000..e2fce11b7a4
Binary files /dev/null and b/doc/user/workflow/labels/label3.png differ
diff --git a/doc/user/workflow/lfs/lfs_administration.md b/doc/user/workflow/lfs/lfs_administration.md
new file mode 100644
index 00000000000..9dc1e9b47e3
--- /dev/null
+++ b/doc/user/workflow/lfs/lfs_administration.md
@@ -0,0 +1,49 @@
+# GitLab Git LFS Administration
+
+Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](manage_large_binaries_with_git_lfs.md).
+
+## Requirements
+
+* Git LFS is supported in GitLab starting with version 8.2.
+* Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up.
+
+## Configuration
+
+Git LFS objects can be large in size. By default, they are stored on the server
+GitLab is installed on.
+
+There are two configuration options to help GitLab server administrators:
+
+* Enabling/disabling Git LFS support
+* Changing the location of LFS object storage
+
+### Omnibus packages
+
+In `/etc/gitlab/gitlab.rb`:
+
+```ruby
+gitlab_rails['lfs_enabled'] = false
+
+# Optionally, change the storage path location. Defaults to
+# `#{gitlab_rails['shared_path']}/lfs-objects`. Which evaluates to
+# `/var/opt/gitlab/gitlab-rails/shared/lfs-objects` by default.
+gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
+```
+
+### Installations from source
+
+In `config/gitlab.yml`:
+
+```yaml
+  lfs:
+    enabled: false
+    storage_path: /mnt/storage/lfs-objects
+```
+
+## Known limitations
+
+* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets)
+  is not supported
+* Currently, removing LFS objects from GitLab Git LFS storage is not supported
+* LFS authentications via SSH is not supported for the time being
+* Only compatible with the GitLFS client versions 1.1.0 or 1.0.2.
diff --git a/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md
new file mode 100644
index 00000000000..9fe065fa680
--- /dev/null
+++ b/doc/user/workflow/lfs/manage_large_binaries_with_git_lfs.md
@@ -0,0 +1,155 @@
+# Git LFS
+
+Managing large files such as audio, video and graphics files has always been one
+of the shortcomings of Git. The general recommendation is to not have Git repositories
+larger than 1GB to preserve performance.
+
+GitLab already supports [managing large files with git annex](http://docs.gitlab.com/ee/workflow/git_annex.html)
+(EE only), however in certain environments it is not always convenient to use
+different commands to differentiate between the large files and regular ones.
+
+Git LFS makes this simpler for the end user by removing the requirement to
+learn new commands.
+
+## How it works
+
+Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication
+to authorize client requests. Once the request is authorized, Git LFS client receives
+instructions from where to fetch or where to push the large file.
+
+## GitLab server configuration
+
+Documentation for GitLab instance administrators is under [LFS administration doc](lfs_administration.md).
+
+## Requirements
+
+* Git LFS is supported in GitLab starting with version 8.2
+* [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
+  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 good Git
+  credentials store is recommended
+* 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)
+
+## Using Git LFS
+
+Lets take a look at the workflow when you need to check large files into your Git
+repository with Git LFS. For example, if you want to upload a very large file and
+check it into your Git repository:
+
+```bash
+git clone git@gitlab.example.com:group/project.git
+git lfs install                       # initialize the Git LFS project project
+git lfs track "*.iso"                 # select the file extensions that you want to treat as large files
+```
+
+Once a certain file extension is marked for tracking as a LFS object you can use
+Git as usual without having to redo the command to track a file with the same extension:
+
+```bash
+cp ~/tmp/debian.iso ./                # copy a large file into the current directory
+git add .                             # add the large file to the project
+git commit -am "Added Debian iso"     # commit the file meta data
+git push origin master                # sync the git repo and large file to the GitLab server
+```
+
+Cloning the repository works the same as before. Git automatically detects the
+LFS-tracked files and clones them via HTTP. If you performed the git clone
+command with a SSH URL, you have to enter your GitLab credentials for HTTP
+authentication.
+
+```bash
+git clone git@gitlab.example.com:group/project.git
+```
+
+If you already cloned the repository and you want to get the latest LFS object
+that are on the remote repository, eg. from branch `master`:
+
+```bash
+git lfs fetch master
+```
+
+## Troubleshooting
+
+### error: Repository or object not found
+
+There are a couple of reasons why this error can occur:
+
+* 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
+
+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
+
+### Invalid status for <url> : 501
+
+Git LFS will log the failures into a log file.
+To view this log file, while in project directory:
+
+```bash
+git lfs logs last
+```
+
+If the status `error 501` is shown, it is because:
+
+* 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
+  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
+  newer are supported.
+
+### getsockopt: connection refused
+
+If you push a LFS object to a project and you receive an error similar to:
+`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`,
+the LFS client is trying to reach GitLab through HTTPS. However, your GitLab
+instance is being served on HTTP.
+
+This behaviour is caused by Git LFS using HTTPS connections by default when a
+`lfsurl` is not set in the Git config.
+
+To prevent this from happening, set the lfs url in project Git config:
+
+```bash
+
+git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"
+```
+
+### Credentials are always required when pushing an object
+
+Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing
+the LFS object on every push for every object, user HTTPS credentials are required.
+
+By default, Git has support for remembering the credentials for each repository
+you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials).
+
+For example, you can tell Git to remember the password for a period of time in
+which you expect to push the objects:
+
+```bash
+git config --global credential.helper 'cache --timeout=3600'
+```
+
+This will remember the credentials for an hour after which Git operations will
+require re-authentication.
+
+If you are using OS X you can use `osxkeychain` to store and encrypt your credentials.
+For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases).
+
+More details about various methods of storing the user credentials can be found
+on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
diff --git a/doc/user/workflow/merge_commits.png b/doc/user/workflow/merge_commits.png
new file mode 100644
index 00000000000..757b589d0db
Binary files /dev/null and b/doc/user/workflow/merge_commits.png differ
diff --git a/doc/user/workflow/merge_request.png b/doc/user/workflow/merge_request.png
new file mode 100644
index 00000000000..fde3ff5c854
Binary files /dev/null and b/doc/user/workflow/merge_request.png differ
diff --git a/doc/user/workflow/merge_requests.md b/doc/user/workflow/merge_requests.md
new file mode 100644
index 00000000000..d2ec56e6504
--- /dev/null
+++ b/doc/user/workflow/merge_requests.md
@@ -0,0 +1,63 @@
+# Merge Requests
+
+Merge requests allow you to exchange changes you made to source code
+
+## Only allow merge requests to be merged if the build succeeds
+
+You can prevent merge requests from being merged if their build did not succeed
+in the project settings page.
+
+![only_allow_merge_if_build_succeeds](merge_requests/only_allow_merge_if_build_succeeds.png)
+
+Navigate to project settings page and select the `Only allow merge requests to be merged if the build succeeds` check box.
+
+Please note that you need to have builds configured to enable this feature.
+
+## Checkout merge requests locally
+
+Locate the section for your GitLab remote in the `.git/config` file. It looks like this:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-ce.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+```
+
+Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section.
+
+It should look like this:
+
+```
+[remote "origin"]
+  url = https://gitlab.com/gitlab-org/gitlab-ce.git
+  fetch = +refs/heads/*:refs/remotes/origin/*
+  fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
+```
+
+Now you can fetch all the merge requests requests:
+
+```
+$ git fetch origin
+From https://gitlab.com/gitlab-org/gitlab-ce.git
+ * [new ref]         refs/merge-requests/1/head -> origin/merge-requests/1
+ * [new ref]         refs/merge-requests/2/head -> origin/merge-requests/2
+...
+```
+
+To check out a particular merge request:
+
+```
+$ git checkout origin/merge-requests/1
+```
+
+## Ignore whitespace changes in Merge Request diff view
+
+![MR diff](merge_requests/merge_request_diff.png)
+
+If you click the "Hide whitespace changes" button, you can see the diff without whitespace changes.
+
+![MR diff without whitespace](merge_requests/merge_request_diff_without_whitespace.png)
+
+It is also working on commits compare view.
+
+![Commit Compare](merge_requests/commit_compare.png)
diff --git a/doc/user/workflow/merge_requests/commit_compare.png b/doc/user/workflow/merge_requests/commit_compare.png
new file mode 100644
index 00000000000..dfd7ee220f0
Binary files /dev/null and b/doc/user/workflow/merge_requests/commit_compare.png differ
diff --git a/doc/user/workflow/merge_requests/merge_request_diff.png b/doc/user/workflow/merge_requests/merge_request_diff.png
new file mode 100644
index 00000000000..f368423c746
Binary files /dev/null and b/doc/user/workflow/merge_requests/merge_request_diff.png differ
diff --git a/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png b/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png
new file mode 100644
index 00000000000..b2d03bb66f9
Binary files /dev/null and b/doc/user/workflow/merge_requests/merge_request_diff_without_whitespace.png differ
diff --git a/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png b/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png
new file mode 100644
index 00000000000..18bebf5fe92
Binary files /dev/null and b/doc/user/workflow/merge_requests/only_allow_merge_if_build_succeeds.png differ
diff --git a/doc/user/workflow/merge_when_build_succeeds.md b/doc/user/workflow/merge_when_build_succeeds.md
new file mode 100644
index 00000000000..75e1fdff2b2
--- /dev/null
+++ b/doc/user/workflow/merge_when_build_succeeds.md
@@ -0,0 +1,15 @@
+# Merge When Build Succeeds
+
+When reviewing a merge request that looks ready to merge but still has one or more CI builds running, you can set it to be merged automatically when all builds succeed. This way, you don't have to wait for the builds to finish and remember to merge the request manually.
+
+![Enable](merge_when_build_succeeds/enable.png)
+
+When you hit the "Merge When Build Succeeds" button, the status of the merge request will be updated to represent the impending merge. If you cannot wait for the build to succeed and want to merge immediately, this option is available in the dropdown menu on the right of the main button.
+
+Both team developers and the author of the merge request have the option to cancel the automatic merge if they find a reason why it shouldn't be merged after all.
+
+![Status](merge_when_build_succeeds/status.png)
+
+When the build succeeds, the merge request will automatically be merged. When the build fails, the author gets a chance to retry any failed builds, or to push new commits to fix the failure.
+
+When the builds are retried and succeed on the second try, the merge request will automatically be merged after all. When the merge request is updated with new commits, the automatic merge is automatically canceled to allow the new changes to be reviewed.
diff --git a/doc/user/workflow/merge_when_build_succeeds/enable.png b/doc/user/workflow/merge_when_build_succeeds/enable.png
new file mode 100644
index 00000000000..633efa1246f
Binary files /dev/null and b/doc/user/workflow/merge_when_build_succeeds/enable.png differ
diff --git a/doc/user/workflow/merge_when_build_succeeds/status.png b/doc/user/workflow/merge_when_build_succeeds/status.png
new file mode 100644
index 00000000000..c856c7d14dc
Binary files /dev/null and b/doc/user/workflow/merge_when_build_succeeds/status.png differ
diff --git a/doc/user/workflow/messy_flow.png b/doc/user/workflow/messy_flow.png
new file mode 100644
index 00000000000..1addb95ca54
Binary files /dev/null and b/doc/user/workflow/messy_flow.png differ
diff --git a/doc/user/workflow/milestones.md b/doc/user/workflow/milestones.md
new file mode 100644
index 00000000000..dff36899aec
--- /dev/null
+++ b/doc/user/workflow/milestones.md
@@ -0,0 +1,13 @@
+# Milestones
+
+Milestones allow you to organize issues and merge requests into a cohesive group, optionally setting a due date. 
+A common use is keeping track of an upcoming software version. Milestones are created per-project.
+
+![milestone form](milestones/form.png)
+
+## Groups and milestones
+
+You can create a milestone for several projects in the same group simultaneously. 
+On the group's milestones page, you will be able to see the status of that milestone across all of the selected projects.
+
+![group milestone form](milestones/group_form.png)
diff --git a/doc/user/workflow/milestones/form.png b/doc/user/workflow/milestones/form.png
new file mode 100644
index 00000000000..de44c1ffc1a
Binary files /dev/null and b/doc/user/workflow/milestones/form.png differ
diff --git a/doc/user/workflow/milestones/group_form.png b/doc/user/workflow/milestones/group_form.png
new file mode 100644
index 00000000000..38862dcca68
Binary files /dev/null and b/doc/user/workflow/milestones/group_form.png differ
diff --git a/doc/user/workflow/mr_inline_comments.png b/doc/user/workflow/mr_inline_comments.png
new file mode 100644
index 00000000000..e851b95bcef
Binary files /dev/null and b/doc/user/workflow/mr_inline_comments.png differ
diff --git a/doc/user/workflow/notifications.md b/doc/user/workflow/notifications.md
new file mode 100644
index 00000000000..fe4485e148a
--- /dev/null
+++ b/doc/user/workflow/notifications.md
@@ -0,0 +1,93 @@
+# GitLab Notification Emails
+
+GitLab has a notification system in place to notify a user of events that are important for the workflow.
+
+## Notification settings
+
+You can find notification settings under the user profile.
+
+![notification settings](notifications/settings.png)
+
+Notification settings are divided into three groups:
+
+* 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.
+
+#### Global Settings
+
+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 are taking precedence over Global Settings but are on a level below Project Settings.
+This means that you can set a different level of notifications per group while still being able
+to have a finer level setting per project.
+Organization like this is suitable for users that belong to different groups but don't have the
+same need for being notified for every group they are member of.
+
+#### Project Settings
+
+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.
+
+## Notification events
+
+Below is the table of events users can be notified of:
+
+| Event                        | Sent to                                                           | Settings level               |
+|------------------------------|-------------------------------------------------------------------|------------------------------|
+| New SSH key added            | User                                                              | Security email, always sent. |
+| New email added              | 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 |
+| User added to group          | User                                                              | Sent when user is added to group |
+| Group access level changed   | User                                                              | Sent when user group access level is changed |
+| Project moved                | Project members [1]                                               | [1] not disabled |
+
+### Issue / Merge Request events
+
+In all 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 description
+  - 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
+- Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below
+
+| Event                  | Sent to |
+|------------------------|---------|
+| New issue              | |
+| Close issue            | |
+| Reassign issue         | The above, plus the old assignee |
+| Reopen issue           | |
+| New merge request      | |
+| Reassign merge request | The above, plus the old assignee |
+| Close merge request    | |
+| Reopen merge request   | |
+| Merge merge request    | |
+| New comment            | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher |
+
+You won't receive notifications for Issues, Merge Requests or Milestones
+created by yourself. You will only receive automatic notifications when
+somebody else comments or adds changes to the ones that you've created or
+mentions you.
diff --git a/doc/user/workflow/notifications/settings.png b/doc/user/workflow/notifications/settings.png
new file mode 100644
index 00000000000..7c6857aad1a
Binary files /dev/null and b/doc/user/workflow/notifications/settings.png differ
diff --git a/doc/user/workflow/production_branch.png b/doc/user/workflow/production_branch.png
new file mode 100644
index 00000000000..33fb26dd621
Binary files /dev/null and b/doc/user/workflow/production_branch.png differ
diff --git a/doc/user/workflow/project_features.md b/doc/user/workflow/project_features.md
new file mode 100644
index 00000000000..a523b3facbe
--- /dev/null
+++ b/doc/user/workflow/project_features.md
@@ -0,0 +1,35 @@
+# Project features
+
+When in a Project -> Settings, you will find Features on the bottom of the page that you can toggle.
+
+Below you will find a more elaborate explanation of each of these.
+
+## Issues
+
+Issues is a really powerful, but lightweight issue tracking system.
+
+You can make tickets, assign them to people, file them under milestones, order them with labels and have discussion in them.
+
+They integrate deeply into GitLab and are easily referenced from anywhere by using `#` and the issue number.
+
+## Merge Requests
+
+Using a merge request, you can review and discuss code before it is merged in the branch of your code.
+
+As with issues, it can be assigned; people, issues, etc. can be referenced; milestones attached.
+
+We see it as an integral part of working together on code and couldn't work without it.
+
+## Wiki
+
+This is a separate system for documentation, built right into GitLab.
+
+It is source controlled and is very convenient if you don't want to keep you documentation in your source code, but you do want to keep it in your GitLab project.
+
+## Snippets
+
+Snippets are little bits of code or text.
+
+This is a nice place to put code or text that is used semi-regularly within the project, but does not belong in source control.
+
+For example, a specific config file that is used by > the team that is only valid for the people that work on the code.
diff --git a/doc/user/workflow/protected_branches.md b/doc/user/workflow/protected_branches.md
new file mode 100644
index 00000000000..d854ec1e025
--- /dev/null
+++ b/doc/user/workflow/protected_branches.md
@@ -0,0 +1,31 @@
+# Protected branches
+
+Permissions in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches.
+
+To prevent people from messing with history or pushing code without review, we've created protected branches.
+
+A protected branch does three simple things:
+
+* it prevents pushes from everybody except users with Master permission
+* it prevents anyone from force pushing to the branch
+* it prevents anyone from deleting the branch
+
+You can make any branch a protected branch. GitLab makes the master branch a protected branch by default.
+
+To protect a branch, user needs to have at least a Master permission level, see [permissions document](../permissions/permissions.md).
+
+![protected branches page](protected_branches/protected_branches1.png)
+
+Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect.
+
+Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch.
+
+Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request.
+
+However, there are workflows where that is not needed and only protecting from force pushes and branch removal is useful.
+
+For those workflows, you can allow everyone with write access to push to a protected branch by selecting `Developers can push` check box.
+
+On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box.
+
+![Developers can push](protected_branches/protected_branches2.png)
\ No newline at end of file
diff --git a/doc/user/workflow/protected_branches/protected_branches1.png b/doc/user/workflow/protected_branches/protected_branches1.png
new file mode 100644
index 00000000000..5c2a3de5f70
Binary files /dev/null and b/doc/user/workflow/protected_branches/protected_branches1.png differ
diff --git a/doc/user/workflow/protected_branches/protected_branches2.png b/doc/user/workflow/protected_branches/protected_branches2.png
new file mode 100644
index 00000000000..2dca3541365
Binary files /dev/null and b/doc/user/workflow/protected_branches/protected_branches2.png differ
diff --git a/doc/user/workflow/rebase.png b/doc/user/workflow/rebase.png
new file mode 100644
index 00000000000..ef82c834755
Binary files /dev/null and b/doc/user/workflow/rebase.png differ
diff --git a/doc/user/workflow/release_branches.png b/doc/user/workflow/release_branches.png
new file mode 100644
index 00000000000..da7ae53413a
Binary files /dev/null and b/doc/user/workflow/release_branches.png differ
diff --git a/doc/user/workflow/releases.md b/doc/user/workflow/releases.md
new file mode 100644
index 00000000000..6176784fc57
--- /dev/null
+++ b/doc/user/workflow/releases.md
@@ -0,0 +1,20 @@
+# 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. 
+
+There are several ways to add release notes: 
+
+* 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
+
+## New tag page with release notes text area
+
+![new_tag](releases/new_tag.png)
+
+## Tags page with button to add or edit release notes for existing git tag
+
+![tags](releases/tags.png)
+
diff --git a/doc/user/workflow/releases/new_tag.png b/doc/user/workflow/releases/new_tag.png
new file mode 100644
index 00000000000..e2b64bfe17f
Binary files /dev/null and b/doc/user/workflow/releases/new_tag.png differ
diff --git a/doc/user/workflow/releases/tags.png b/doc/user/workflow/releases/tags.png
new file mode 100644
index 00000000000..aca91906c68
Binary files /dev/null and b/doc/user/workflow/releases/tags.png differ
diff --git a/doc/user/workflow/remove_checkbox.png b/doc/user/workflow/remove_checkbox.png
new file mode 100644
index 00000000000..3e247d38155
Binary files /dev/null and b/doc/user/workflow/remove_checkbox.png differ
diff --git a/doc/user/workflow/revert_changes.md b/doc/user/workflow/revert_changes.md
new file mode 100644
index 00000000000..399366b0cdc
--- /dev/null
+++ b/doc/user/workflow/revert_changes.md
@@ -0,0 +1,64 @@
+# Reverting changes
+
+_**Note:** This feature was [introduced][ce-1990] in GitLab 8.5._
+
+---
+
+GitLab implements Git's powerful feature to [revert any commit][git-revert]
+with introducing a **Revert** button in Merge Requests and commit details.
+
+## Reverting a Merge Request
+
+_**Note:** 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._
+
+After the Merge Request has been merged, a **Revert** button will be available
+to revert the changes introduced by that Merge Request:
+
+![Revert Merge Request](img/revert_changes_mr.png)
+
+---
+
+You can revert the changes directly into the selected branch or you can opt to
+create a new Merge Request with the revert changes:
+
+![Revert Merge Request modal](img/revert_changes_mr_modal.png)
+
+---
+
+After the Merge Request has been reverted, the **Revert** button will not be
+available anymore.
+
+## Reverting a Commit
+
+You can revert a Commit from the Commit details page:
+
+![Revert commit](img/revert_changes_commit.png)
+
+---
+
+Similar to reverting a Merge Request, you can opt to revert the changes
+directly into the target branch or create a new Merge Request to revert the
+changes:
+
+![Revert commit modal](img/revert_changes_commit_modal.png)
+
+---
+
+After the Commit has been reverted, the **Revert** button will not be available
+anymore.
+
+Please note that when reverting merge commits, the mainline will always be the
+first parent. If you want to use a different mainline then you need to do that
+from the command line.
+
+Here is a quick example to revert a merge commit using the second parent as the
+mainline:
+
+```bash
+git revert -m 2 7a39eb0
+```
+
+[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request"
+[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation"
diff --git a/doc/user/workflow/share_projects_with_other_groups.md b/doc/user/workflow/share_projects_with_other_groups.md
new file mode 100644
index 00000000000..4c59f59c587
--- /dev/null
+++ b/doc/user/workflow/share_projects_with_other_groups.md
@@ -0,0 +1,30 @@
+# Share Projects with other Groups
+
+In GitLab Enterprise Edition you can share projects with other groups.
+This makes it possible to add a group of users to a project with a single action.
+
+## Groups as collections of users
+
+In GitLab Community Edition groups are used primarily to [create collections of projects](groups.md).
+In GitLab Enterprise Edition you can also take advantage of the fact that groups define collections of _users_, namely the group members.
+
+## Sharing a project with a group of users
+
+The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project Acme'.
+But what if 'Project Acme' already belongs to another group, say 'Open Source'?
+This is where the (Enterprise Edition only) group sharing feature can be of use.
+
+To share 'Project Acme' with the 'Engineering' group, go to the project settings page for 'Project Acme' and use the left navigation menu to go to the 'Groups' section.
+
+![The 'Groups' section in the project settings screen (Enterprise Edition only)](groups/share_project_with_groups.png)
+
+Now you can add the 'Engineering' group with the maximum access level of your choice.
+After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard.
+
+!['Project Acme' is listed as a shared project for 'Engineering'](groups/other_group_sees_shared_project.png)
+
+## Maximum access level
+
+!['Project Acme' is shared with 'Engineering' with a maximum access level of 'Developer'](groups/max_access_level.png)
+
+In the screenshot above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Master' or 'Owner') will only have 'Developer' access to 'Project Acme'.
diff --git a/doc/user/workflow/share_with_group.md b/doc/user/workflow/share_with_group.md
new file mode 100644
index 00000000000..3b7690973cb
--- /dev/null
+++ b/doc/user/workflow/share_with_group.md
@@ -0,0 +1,13 @@
+# Sharing a project with a group
+
+If you want to share a single project in a group with another group,
+you can do so easily. By setting the permission you can quickly
+give a select group of users access to a project in a restricted manner.
+
+In a project go to the project settings -> groups.
+
+Now you can select a group that you want to share this project with and with
+which maximum access level. Users in that group are able to access this project
+with their set group access level, up to the maximum level that you've set.
+
+![Share a project with a group](share_with_group.png)
diff --git a/doc/user/workflow/share_with_group.png b/doc/user/workflow/share_with_group.png
new file mode 100644
index 00000000000..a0ca6f14552
Binary files /dev/null and b/doc/user/workflow/share_with_group.png differ
diff --git a/doc/user/workflow/shortcuts.md b/doc/user/workflow/shortcuts.md
new file mode 100644
index 00000000000..ffcb832cdd7
--- /dev/null
+++ b/doc/user/workflow/shortcuts.md
@@ -0,0 +1,5 @@
+# GitLab keyboard shortcuts
+
+You can see GitLab's keyboard shortcuts by using 'shift + ?'
+
+![Shortcuts](shortcuts.png)
\ No newline at end of file
diff --git a/doc/user/workflow/shortcuts.png b/doc/user/workflow/shortcuts.png
new file mode 100644
index 00000000000..16be0413b64
Binary files /dev/null and b/doc/user/workflow/shortcuts.png differ
diff --git a/doc/user/workflow/timezone.md b/doc/user/workflow/timezone.md
new file mode 100644
index 00000000000..7e08c0e51ac
--- /dev/null
+++ b/doc/user/workflow/timezone.md
@@ -0,0 +1,30 @@
+# Changing your time zone
+
+The global time zone configuration parameter can be changed in `config/gitlab.yml`:
+```
+    # time_zone: 'UTC'
+```
+
+Uncomment and customize if you want to change the default time zone of GitLab application.
+
+To see all available time zones, run `bundle exec rake time:zones:all`.
+
+
+## Changing time zone in omnibus installations
+
+GitLab defaults its time zone to UTC. It has a global timezone configuration parameter in `/etc/gitlab/gitlab.rb`.
+
+To update, add the time zone that best applies to your location. Here are two examples:
+```
+gitlab_rails['time_zone'] = 'America/New_York'
+```
+or
+```
+gitlab_rails['time_zone'] = 'Europe/Brussels'
+```
+
+After you added this field, reconfigure and restart:
+```
+gitlab-ctl reconfigure
+gitlab-ctl restart
+```
diff --git a/doc/user/workflow/todos.md b/doc/user/workflow/todos.md
new file mode 100644
index 00000000000..5f440fdafdd
--- /dev/null
+++ b/doc/user/workflow/todos.md
@@ -0,0 +1,73 @@
+# GitLab ToDos
+
+>**Note:** This feature was [introduced][ce-2817] in GitLab 8.5.
+
+When you log into GitLab, you normally want to see where you should spend your
+time and take some action, or what you need to keep an eye on. All without the
+mess of a huge pile of e-mail notifications. GitLab is where you do your work,
+so being able to get started quickly is very important.
+
+Todos is a chronological list of to-dos that are waiting for your input, all
+in a simple dashboard.
+
+![Todos screenshot showing a list of items to check on](img/todos_index.png)
+
+---
+
+You can access quickly your Todos dashboard by clicking the round gray icon
+next to the search bar in the upper right corner.
+
+![Todos icon](img/todos_icon.png)
+
+## What triggers a Todo
+
+A Todo appears in your Todos dashboard when:
+
+- an issue or merge request is assigned to you
+- you are `@mentioned` in an issue or merge request, be it the description of
+  the issue/merge request or in a comment
+
+>**Note:** Commenting on a commit will _not_ trigger a Todo.
+
+## How a Todo is marked as Done
+
+Any action to the corresponding issue or merge request will mark your Todo as
+**Done**. This action can include:
+
+- changing the assignee
+- changing the milestone
+- adding/removing a label
+- commenting on the issue
+
+In case where you think no action is needed, you can manually mark the todo as
+done by clicking the corresponding **Done** button, and it will disappear from
+your Todos list. If you want to mark all your Todos as done, just click on the
+**Mark all as done** button.
+
+---
+
+In order for a Todo to be marked as done, the action must be coming from you.
+So, if you close the related issue or merge the merge request yourself, and you
+had a Todo for that, it will automatically get marked as done. On the other
+hand, if someone else closes, merges or takes action on the issue or merge
+request, your Todo will remain pending. This makes sense because you may need
+to give attention to an issue even if it has been resolved.
+
+There is just one Todo per issue or merge request, so mentioning a user a
+hundred times in an issue will only trigger one Todo.
+
+## Filtering your Todos
+
+In general, there are four kinds of filters you can use on your Todos
+dashboard:
+
+| Filter | Description |
+| ------ | ----------- |
+| Project | Filter by project |
+| Author  | Filter by the author that triggered the Todo |
+| Type    | Filter by issue or merge request |
+| Action  | Filter by the action that triggered the Todo (Assigned or Mentioned)|
+
+You can choose more than one filters at the same time.
+
+[ce-2817]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2817
diff --git a/doc/user/workflow/web_editor.md b/doc/user/workflow/web_editor.md
new file mode 100644
index 00000000000..1832567a34c
--- /dev/null
+++ b/doc/user/workflow/web_editor.md
@@ -0,0 +1,152 @@
+# GitLab Web Editor
+
+Sometimes it's easier to make quick changes directly from the GitLab interface
+than to clone the project and use the Git command line tool. In this feature
+highlight we look at how you can create a new file, directory, branch or
+tag from the file browser. All of these actions are available from a single
+dropdown menu.
+
+## Create a file
+
+From a project's files page, click the '+' button to the right of the branch selector.
+Choose **New file** from the dropdown.
+
+![New file dropdown menu](img/web_editor_new_file_dropdown.png)
+
+---
+
+Enter a file name in the **File name** box. Then, add file content in the editor
+area. Add a descriptive commit message and choose a branch. The branch field
+will default to the branch you were viewing in the file browser. If you enter
+a new branch name, a checkbox will appear allowing you to start a new merge
+request after you commit the changes.
+
+When you are satisfied with your new file, click **Commit Changes** at the bottom.
+
+![Create file editor](img/web_editor_new_file_editor.png)
+
+## Upload a file
+
+The ability to create a file is great when the content is text. However, this
+doesn't work well for binary data such as images, PDFs or other file types. In
+this case you need to upload a file.
+
+From a project's files page, click the '+' button to the right of the branch
+selector. Choose **Upload file** from the dropdown.
+
+![Upload file dropdown menu](img/web_editor_upload_file_dropdown.png)
+
+---
+
+Once the upload dialog pops up there are two ways to upload your file. Either
+drag and drop a file on the pop up or use the **click to upload** link. A file
+preview will appear once you have selected a file to upload.
+
+Enter a commit message, choose a branch, and click **Upload file** when you are
+ready.
+
+![Upload file dialog](img/web_editor_upload_file_dialog.png)
+
+## Create a directory
+
+To keep files in the repository organized it is often helpful to create a new
+directory.
+
+From a project's files page, click the '+' button to the right of the branch selector.
+Choose **New directory** from the dropdown.
+
+![New directory dropdown](img/web_editor_new_directory_dropdown.png)
+
+---
+
+In the new directory dialog enter a directory name, a commit message and choose
+the target branch. Click **Create directory** to finish.
+
+![New directory dialog](img/web_editor_new_directory_dialog.png)
+
+## Create a new branch
+
+There are multiple ways to create a branch from GitLab's web interface.
+
+### Create a new branch from an issue
+
+>**Note:**
+This feature was [introduced][ce-2808] in GitLab 8.6.
+
+In case your development workflow dictates to have an issue for every merge
+request, you can quickly create a branch right on the issue page which will be
+tied with the issue itself. You can see a **New Branch** button after the issue
+description, unless there is already a branch with the same name or a referenced
+merge request.
+
+![New Branch Button](img/new_branch_from_issue.png)
+
+Once you click it, a new branch will be created that diverges from the default
+branch of your project, by default `master`. The branch name will be based on
+the title of the issue and as suffix it will have its ID. Thus, the example
+screenshot above will yield a branch named
+`2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`.
+
+After the branch is created, you can edit files in the repository to fix
+the issue. When a merge request is created based on the newly created branch,
+the description field will automatically display the [issue closing pattern]
+`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the
+merge request is merged.
+
+### Create a new branch from a project's dashboard
+
+If you want to make changes to several files before creating a new merge
+request, you can create a new branch up front. From a project's files page,
+choose **New branch** from the dropdown.
+
+![New branch dropdown](img/web_editor_new_branch_dropdown.png)
+
+---
+
+Enter a new **Branch name**. Optionally, change the **Create from** field
+to choose which branch, tag or commit SHA this new branch will originate from.
+This field will autocomplete if you start typing an existing branch or tag.
+Click **Create branch** and you will be returned to the file browser on this new
+branch.
+
+![New branch page](img/web_editor_new_branch_page.png)
+
+---
+
+You can now make changes to any files, as needed. When you're ready to merge
+the changes back to master you can use the widget at the top of the screen.
+This widget only appears for a period of time after you create the branch or
+modify files.
+
+![New push widget](img/web_editor_new_push_widget.png)
+
+## Create a new tag
+
+Tags are useful for marking major milestones such as production releases,
+release candidates, and more. You can create a tag from a branch or a commit
+SHA. From a project's files page, choose **New tag** from the dropdown.
+
+![New tag dropdown](img/web_editor_new_tag_dropdown.png)
+
+---
+
+Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you
+would like to create this new tag. You can optionally add a message and
+release notes. The release notes section supports markdown format and you can
+also upload an attachment. Click **Create tag** and you will be taken to the tag
+list page.
+
+![New tag page](img/web_editor_new_tag_page.png)
+
+## Tips
+
+When creating or uploading a new file, or creating a new directory, you can
+trigger a new merge request rather than committing directly to master. Enter
+a new branch name in the **Target branch** field. You will notice a checkbox
+appear that is labeled **Start a new merge request with these changes**. After
+you commit the changes you will be taken to a new merge request form.
+
+![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png)
+
+[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
+[issue closing pattern]: ../customization/issue_closing.md
diff --git a/doc/user/workflow/wip_merge_requests.md b/doc/user/workflow/wip_merge_requests.md
new file mode 100644
index 00000000000..46035a5e6b6
--- /dev/null
+++ b/doc/user/workflow/wip_merge_requests.md
@@ -0,0 +1,13 @@
+# "Work In Progress" Merge Requests
+
+To prevent merge requests from accidentally being accepted before they're completely ready, GitLab blocks the "Accept" button for merge requests that have been marked a **Work In Progress**.
+
+![Blocked Accept Button](wip_merge_requests/blocked_accept_button.png)
+
+To mark a merge request a Work In Progress, simply start its title with `[WIP]` or `WIP:`.
+
+![Mark as WIP](wip_merge_requests/mark_as_wip.png)
+
+To allow a Work In Progress merge request to be accepted again when it's ready, simply remove the `WIP` prefix.
+
+![Unark as WIP](wip_merge_requests/unmark_as_wip.png)
diff --git a/doc/user/workflow/wip_merge_requests/blocked_accept_button.png b/doc/user/workflow/wip_merge_requests/blocked_accept_button.png
new file mode 100644
index 00000000000..4791e5de972
Binary files /dev/null and b/doc/user/workflow/wip_merge_requests/blocked_accept_button.png differ
diff --git a/doc/user/workflow/wip_merge_requests/mark_as_wip.png b/doc/user/workflow/wip_merge_requests/mark_as_wip.png
new file mode 100644
index 00000000000..8fa83a201ac
Binary files /dev/null and b/doc/user/workflow/wip_merge_requests/mark_as_wip.png differ
diff --git a/doc/user/workflow/wip_merge_requests/unmark_as_wip.png b/doc/user/workflow/wip_merge_requests/unmark_as_wip.png
new file mode 100644
index 00000000000..d45e68f31c5
Binary files /dev/null and b/doc/user/workflow/wip_merge_requests/unmark_as_wip.png differ
diff --git a/doc/user/workflow/workflow.md b/doc/user/workflow/workflow.md
new file mode 100644
index 00000000000..f70e41df842
--- /dev/null
+++ b/doc/user/workflow/workflow.md
@@ -0,0 +1,31 @@
+# Feature branch workflow
+
+1.  Clone project:
+
+    ```bash
+    git clone git@example.com:project-name.git
+    ```
+
+1.  Create branch with your feature:
+
+    ```bash
+    git checkout -b $feature_name
+    ```
+
+1.  Write code. Commit changes:
+
+    ```bash
+    git commit -am "My feature is ready"
+    ```
+
+1.  Push your branch to GitLab:
+
+    ```bash
+    git push origin $feature_name
+    ```
+
+1.  Review your code on commits page.
+
+1.  Create a merge request.
+
+1.  Your team lead will review the code &amp; merge it to the main branch.
-- 
cgit v1.2.1