From 24ad2f4f0d9e8ebfd8133a572f29e52b74cd7dd5 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis 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 --- .../customization/branded_login_page.md | 19 + .../branded_login_page/appearance.png | Bin 0 -> 365120 bytes .../branded_login_page/custom_sign_in.png | Bin 0 -> 314111 bytes .../branded_login_page/default_login_page.png | Bin 0 -> 292731 bytes doc/administration/customization/issue_closing.md | 39 + doc/administration/customization/libravatar.md | 82 +++ .../customization/welcome_message.md | 12 + doc/administration/downgrade_ee_to_ce/README.md | 82 +++ doc/administration/hooks/custom_hooks.md | 41 ++ doc/administration/incoming_email/README.md | 302 ++++++++ doc/administration/incoming_email/postfix.md | 321 +++++++++ doc/administration/integration/README.md | 61 ++ doc/administration/integration/akismet.md | 30 + doc/administration/integration/auth0.md | 89 +++ doc/administration/integration/azure.md | 83 +++ doc/administration/integration/bitbucket.md | 140 ++++ doc/administration/integration/cas.md | 65 ++ doc/administration/integration/crowd.md | 58 ++ .../integration/external-issue-tracker.md | 30 + doc/administration/integration/facebook.md | 97 +++ doc/administration/integration/github.md | 95 +++ doc/administration/integration/gitlab.md | 84 +++ .../integration/gmail_action_buttons_for_gitlab.md | 22 + doc/administration/integration/google.md | 89 +++ .../integration/img/akismet_settings.png | Bin 0 -> 55837 bytes .../img/enabled-oauth-sign-in-sources.png | Bin 0 -> 49081 bytes .../integration/img/facebook_api_keys.png | Bin 0 -> 125921 bytes .../integration/img/facebook_app_settings.png | Bin 0 -> 134387 bytes .../integration/img/facebook_website_url.png | Bin 0 -> 42292 bytes doc/administration/integration/img/github_app.png | Bin 0 -> 75297 bytes doc/administration/integration/img/gitlab_app.png | Bin 0 -> 55325 bytes .../img/gmail_action_buttons_for_gitlab.png | Bin 0 -> 17321 bytes doc/administration/integration/img/google_app.png | Bin 0 -> 52669 bytes .../img/oauth_provider_admin_application.png | Bin 0 -> 40579 bytes .../img/oauth_provider_application_form.png | Bin 0 -> 27974 bytes .../img/oauth_provider_application_id_secret.png | Bin 0 -> 33901 bytes .../img/oauth_provider_authorized_application.png | Bin 0 -> 32225 bytes .../img/oauth_provider_user_wide_applications.png | Bin 0 -> 40632 bytes .../integration/img/twitter_app_api_keys.png | Bin 0 -> 72200 bytes .../integration/img/twitter_app_details.png | Bin 0 -> 121621 bytes doc/administration/integration/jira.md | 3 + doc/administration/integration/ldap.md | 3 + doc/administration/integration/oauth_provider.md | 80 +++ doc/administration/integration/omniauth.md | 208 ++++++ doc/administration/integration/recaptcha.md | 23 + doc/administration/integration/saml.md | 309 ++++++++ doc/administration/integration/shibboleth.md | 125 ++++ doc/administration/integration/slack.md | 41 ++ doc/administration/integration/twitter.md | 79 +++ doc/administration/logs/logs.md | 1 + doc/administration/migrate_ci_to_ce/README.md | 435 ++++++++++++ doc/administration/monitoring/health_check.md | 66 ++ .../monitoring/img/health_check_token.png | Bin 0 -> 10884 bytes .../monitoring/performance/gitlab_configuration.md | 40 ++ .../performance/grafana_configuration.md | 149 ++++ .../performance/img/grafana_dashboard_dropdown.png | Bin 0 -> 29419 bytes .../performance/img/grafana_dashboard_import.png | Bin 0 -> 40974 bytes .../img/grafana_data_source_configuration.png | Bin 0 -> 53402 bytes .../performance/img/grafana_data_source_empty.png | Bin 0 -> 44058 bytes .../performance/img/grafana_save_icon.png | Bin 0 -> 16024 bytes .../img/metrics_gitlab_configuration_settings.png | Bin 0 -> 45148 bytes .../performance/influxdb_configuration.md | 193 +++++ .../monitoring/performance/influxdb_schema.md | 88 +++ .../monitoring/performance/introduction.md | 65 ++ doc/administration/operations/README.md | 5 + .../operations/cleaning_up_redis_sessions.md | 52 ++ .../operations/moving_repositories.md | 180 +++++ .../operations/sidekiq_memory_killer.md | 40 ++ doc/administration/operations/unicorn.md | 86 +++ doc/administration/raketasks/README.md | 11 + doc/administration/raketasks/backup_hrz.png | Bin 0 -> 21955 bytes doc/administration/raketasks/backup_restore.md | 438 ++++++++++++ doc/administration/raketasks/check.md | 63 ++ .../raketasks/check_repos_output.png | Bin 0 -> 73786 bytes doc/administration/raketasks/cleanup.md | 24 + doc/administration/raketasks/features.md | 20 + doc/administration/raketasks/import.md | 68 ++ doc/administration/raketasks/list_repos.md | 30 + doc/administration/raketasks/maintenance.md | 169 +++++ doc/administration/raketasks/user_management.md | 72 ++ doc/administration/raketasks/web_hooks.md | 45 ++ doc/container_registry/README.md | 94 --- doc/container_registry/img/container_registry.png | Bin 354050 -> 0 bytes doc/container_registry/img/project_feature.png | Bin 392842 -> 0 bytes doc/customization/branded_login_page.md | 19 - .../branded_login_page/appearance.png | Bin 365120 -> 0 bytes .../branded_login_page/custom_sign_in.png | Bin 314111 -> 0 bytes .../branded_login_page/default_login_page.png | Bin 292731 -> 0 bytes doc/customization/issue_closing.md | 39 - doc/customization/libravatar.md | 82 --- doc/customization/welcome_message.md | 12 - doc/downgrade_ee_to_ce/README.md | 82 --- doc/gitlab-basics/README.md | 15 - doc/gitlab-basics/add-file.md | 31 - doc/gitlab-basics/add-image.md | 62 -- doc/gitlab-basics/add-merge-request.md | 42 -- doc/gitlab-basics/basic-git-commands.md | 3 - .../basicsimages/add_new_merge_request.png | Bin 9467 -> 0 bytes doc/gitlab-basics/basicsimages/add_sshkey.png | Bin 1463 -> 0 bytes doc/gitlab-basics/basicsimages/branch_info.png | Bin 7978 -> 0 bytes doc/gitlab-basics/basicsimages/branch_name.png | Bin 2199 -> 0 bytes doc/gitlab-basics/basicsimages/branches.png | Bin 3653 -> 0 bytes .../basicsimages/button-create-mr.png | Bin 6154 -> 0 bytes .../basicsimages/click-on-new-group.png | Bin 2063 -> 0 bytes doc/gitlab-basics/basicsimages/commit_changes.png | Bin 5567 -> 0 bytes doc/gitlab-basics/basicsimages/commit_message.png | Bin 5707 -> 0 bytes doc/gitlab-basics/basicsimages/commits.png | Bin 4258 -> 0 bytes .../basicsimages/compare_branches.png | Bin 1624 -> 0 bytes doc/gitlab-basics/basicsimages/create_file.png | Bin 2524 -> 0 bytes doc/gitlab-basics/basicsimages/create_group.png | Bin 3224 -> 0 bytes doc/gitlab-basics/basicsimages/edit_file.png | Bin 2259 -> 0 bytes doc/gitlab-basics/basicsimages/file_located.png | Bin 3156 -> 0 bytes doc/gitlab-basics/basicsimages/file_name.png | Bin 2544 -> 0 bytes doc/gitlab-basics/basicsimages/find_file.png | Bin 8840 -> 0 bytes doc/gitlab-basics/basicsimages/find_group.png | Bin 6159 -> 0 bytes doc/gitlab-basics/basicsimages/fork.png | Bin 1046 -> 0 bytes doc/gitlab-basics/basicsimages/group_info.png | Bin 16217 -> 0 bytes doc/gitlab-basics/basicsimages/groups.png | Bin 4857 -> 0 bytes doc/gitlab-basics/basicsimages/https.png | Bin 2887 -> 0 bytes doc/gitlab-basics/basicsimages/image_file.png | Bin 2939 -> 0 bytes doc/gitlab-basics/basicsimages/issue_title.png | Bin 9059 -> 0 bytes doc/gitlab-basics/basicsimages/issues.png | Bin 4332 -> 0 bytes doc/gitlab-basics/basicsimages/key.png | Bin 1264 -> 0 bytes doc/gitlab-basics/basicsimages/merge_requests.png | Bin 4381 -> 0 bytes doc/gitlab-basics/basicsimages/new_issue.png | Bin 2974 -> 0 bytes .../basicsimages/new_merge_request.png | Bin 3227 -> 0 bytes doc/gitlab-basics/basicsimages/new_project.png | Bin 2319 -> 0 bytes doc/gitlab-basics/basicsimages/newbranch.png | Bin 1314 -> 0 bytes doc/gitlab-basics/basicsimages/paste_sshkey.png | Bin 8620 -> 0 bytes .../basicsimages/profile_settings.png | Bin 1194 -> 0 bytes doc/gitlab-basics/basicsimages/project_info.png | Bin 21862 -> 0 bytes .../basicsimages/public_file_link.png | Bin 3038 -> 0 bytes doc/gitlab-basics/basicsimages/select-group.png | Bin 6075 -> 0 bytes doc/gitlab-basics/basicsimages/select-group2.png | Bin 5049 -> 0 bytes doc/gitlab-basics/basicsimages/select_branch.png | Bin 12213 -> 0 bytes doc/gitlab-basics/basicsimages/select_project.png | Bin 16832 -> 0 bytes doc/gitlab-basics/basicsimages/settings.png | Bin 4321 -> 0 bytes doc/gitlab-basics/basicsimages/shh_keys.png | Bin 4981 -> 0 bytes .../basicsimages/submit_new_issue.png | Bin 9083 -> 0 bytes .../basicsimages/title_description_mr.png | Bin 12749 -> 0 bytes doc/gitlab-basics/basicsimages/white_space.png | Bin 3707 -> 0 bytes doc/gitlab-basics/command-line-commands.md | 79 --- doc/gitlab-basics/create-branch.md | 39 - doc/gitlab-basics/create-group.md | 43 -- doc/gitlab-basics/create-issue.md | 27 - doc/gitlab-basics/create-project.md | 21 - doc/gitlab-basics/create-your-ssh-keys.md | 33 - doc/gitlab-basics/fork-project.md | 19 - doc/gitlab-basics/start-using-git.md | 122 ---- doc/hooks/custom_hooks.md | 41 -- doc/incoming_email/README.md | 302 -------- doc/incoming_email/postfix.md | 321 --------- doc/integration/README.md | 61 -- doc/integration/akismet.md | 30 - doc/integration/auth0.md | 89 --- doc/integration/azure.md | 83 --- doc/integration/bitbucket.md | 140 ---- doc/integration/cas.md | 65 -- doc/integration/crowd.md | 58 -- doc/integration/external-issue-tracker.md | 30 - doc/integration/facebook.md | 97 --- doc/integration/github.md | 95 --- doc/integration/gitlab.md | 84 --- doc/integration/gmail_action_buttons_for_gitlab.md | 22 - doc/integration/google.md | 89 --- doc/integration/img/akismet_settings.png | Bin 55837 -> 0 bytes .../img/enabled-oauth-sign-in-sources.png | Bin 49081 -> 0 bytes doc/integration/img/facebook_api_keys.png | Bin 125921 -> 0 bytes doc/integration/img/facebook_app_settings.png | Bin 134387 -> 0 bytes doc/integration/img/facebook_website_url.png | Bin 42292 -> 0 bytes doc/integration/img/github_app.png | Bin 75297 -> 0 bytes doc/integration/img/gitlab_app.png | Bin 55325 -> 0 bytes .../img/gmail_action_buttons_for_gitlab.png | Bin 17321 -> 0 bytes doc/integration/img/google_app.png | Bin 52669 -> 0 bytes .../img/oauth_provider_admin_application.png | Bin 40579 -> 0 bytes .../img/oauth_provider_application_form.png | Bin 27974 -> 0 bytes .../img/oauth_provider_application_id_secret.png | Bin 33901 -> 0 bytes .../img/oauth_provider_authorized_application.png | Bin 32225 -> 0 bytes .../img/oauth_provider_user_wide_applications.png | Bin 40632 -> 0 bytes doc/integration/img/twitter_app_api_keys.png | Bin 72200 -> 0 bytes doc/integration/img/twitter_app_details.png | Bin 121621 -> 0 bytes doc/integration/jira.md | 3 - doc/integration/ldap.md | 3 - doc/integration/oauth_provider.md | 80 --- doc/integration/omniauth.md | 208 ------ doc/integration/recaptcha.md | 23 - doc/integration/saml.md | 309 -------- doc/integration/shibboleth.md | 125 ---- doc/integration/slack.md | 41 -- doc/integration/twitter.md | 79 --- doc/logs/logs.md | 1 - doc/markdown/img/logo.png | Bin 11097 -> 0 bytes doc/markdown/markdown.md | 615 ---------------- doc/migrate_ci_to_ce/README.md | 435 ------------ doc/monitoring/health_check.md | 66 -- doc/monitoring/img/health_check_token.png | Bin 10884 -> 0 bytes doc/monitoring/performance/gitlab_configuration.md | 40 -- .../performance/grafana_configuration.md | 149 ---- .../performance/img/grafana_dashboard_dropdown.png | Bin 29419 -> 0 bytes .../performance/img/grafana_dashboard_import.png | Bin 40974 -> 0 bytes .../img/grafana_data_source_configuration.png | Bin 53402 -> 0 bytes .../performance/img/grafana_data_source_empty.png | Bin 44058 -> 0 bytes .../performance/img/grafana_save_icon.png | Bin 16024 -> 0 bytes .../img/metrics_gitlab_configuration_settings.png | Bin 45148 -> 0 bytes .../performance/influxdb_configuration.md | 193 ----- doc/monitoring/performance/influxdb_schema.md | 88 --- doc/monitoring/performance/introduction.md | 65 -- doc/operations/README.md | 5 - doc/operations/cleaning_up_redis_sessions.md | 52 -- doc/operations/moving_repositories.md | 180 ----- doc/operations/sidekiq_memory_killer.md | 40 -- doc/operations/unicorn.md | 86 --- doc/permissions/permissions.md | 101 --- doc/profile/2fa.png | Bin 23415 -> 0 bytes doc/profile/2fa_auth.png | Bin 15569 -> 0 bytes doc/profile/2fa_u2f_authenticate.png | Bin 54413 -> 0 bytes doc/profile/2fa_u2f_register.png | Bin 112414 -> 0 bytes doc/profile/README.md | 4 - doc/profile/preferences.md | 43 -- doc/profile/two_factor_authentication.md | 127 ---- doc/project_services/bamboo.md | 60 -- doc/project_services/builds_emails.md | 16 - doc/project_services/emails_on_push.md | 17 - doc/project_services/hipchat.md | 54 -- doc/project_services/img/builds_emails_service.png | Bin 41222 -> 0 bytes .../img/emails_on_push_service.png | Bin 98160 -> 0 bytes .../img/jira_add_gitlab_commit_message.png | Bin 57136 -> 0 bytes .../img/jira_add_user_to_group.png | Bin 59251 -> 0 bytes doc/project_services/img/jira_create_new_group.png | Bin 41294 -> 0 bytes .../img/jira_create_new_group_name.png | Bin 12535 -> 0 bytes doc/project_services/img/jira_create_new_user.png | Bin 26532 -> 0 bytes doc/project_services/img/jira_group_access.png | Bin 46028 -> 0 bytes doc/project_services/img/jira_issue_closed.png | Bin 92601 -> 0 bytes doc/project_services/img/jira_issue_reference.png | Bin 39942 -> 0 bytes doc/project_services/img/jira_issues_workflow.png | Bin 105237 -> 0 bytes .../img/jira_merge_request_close.png | Bin 111150 -> 0 bytes doc/project_services/img/jira_project_name.png | Bin 60598 -> 0 bytes ...jira_reference_commit_message_in_jira_issue.png | Bin 42452 -> 0 bytes doc/project_services/img/jira_service.png | Bin 59082 -> 0 bytes .../img/jira_service_close_issue.png | Bin 88433 -> 0 bytes doc/project_services/img/jira_service_page.png | Bin 49122 -> 0 bytes .../img/jira_submit_gitlab_merge_request.png | Bin 63063 -> 0 bytes .../img/jira_user_management_link.png | Bin 58211 -> 0 bytes .../img/jira_workflow_screenshot.png | Bin 121534 -> 0 bytes doc/project_services/img/redmine_configuration.png | Bin 21061 -> 0 bytes .../img/services_templates_redmine_example.png | Bin 17351 -> 0 bytes doc/project_services/irker.md | 51 -- doc/project_services/jira.md | 246 ------- doc/project_services/project_services.md | 54 -- doc/project_services/redmine.md | 21 - doc/project_services/services_templates.md | 25 - doc/public_access/public_access.md | 69 -- doc/raketasks/README.md | 11 - doc/raketasks/backup_hrz.png | Bin 21955 -> 0 bytes doc/raketasks/backup_restore.md | 438 ------------ doc/raketasks/check.md | 63 -- doc/raketasks/check_repos_output.png | Bin 73786 -> 0 bytes doc/raketasks/cleanup.md | 24 - doc/raketasks/features.md | 20 - doc/raketasks/import.md | 68 -- doc/raketasks/list_repos.md | 30 - doc/raketasks/maintenance.md | 169 ----- doc/raketasks/user_management.md | 72 -- doc/raketasks/web_hooks.md | 45 -- doc/ssh/README.md | 130 ---- doc/system_hooks/system_hooks.md | 355 ---------- 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 + doc/web_hooks/ssl.png | Bin 77165 -> 0 bytes doc/web_hooks/web_hooks.md | 784 --------------------- doc/workflow/README.md | 28 - doc/workflow/add-user/add-user.md | 111 --- .../add-user/img/access_requests_management.png | Bin 15105 -> 0 bytes .../img/add_new_user_to_project_settings.png | Bin 22822 -> 0 bytes .../add-user/img/add_user_email_accept.png | Bin 22961 -> 0 bytes doc/workflow/add-user/img/add_user_email_ready.png | Bin 40305 -> 0 bytes .../add-user/img/add_user_email_search.png | Bin 45884 -> 0 bytes .../add-user/img/add_user_give_permissions.png | Bin 56480 -> 0 bytes ...dd_user_import_members_from_another_project.png | Bin 38874 -> 0 bytes .../add-user/img/add_user_imported_members.png | Bin 37873 -> 0 bytes .../add-user/img/add_user_list_members.png | Bin 24427 -> 0 bytes .../add-user/img/add_user_members_menu.png | Bin 42319 -> 0 bytes .../add-user/img/add_user_search_people.png | Bin 39941 -> 0 bytes .../add-user/img/request_access_button.png | Bin 36588 -> 0 bytes .../img/withdraw_access_request_button.png | Bin 37960 -> 0 bytes doc/workflow/authorization_for_merge_requests.md | 40 -- doc/workflow/award_emoji.md | 48 -- doc/workflow/award_emoji.png | Bin 6620 -> 0 bytes doc/workflow/cherry_pick_changes.md | 53 -- doc/workflow/ci_mr.png | Bin 40065 -> 0 bytes doc/workflow/close_issue_mr.png | Bin 146292 -> 0 bytes doc/workflow/environment_branches.png | Bin 40210 -> 0 bytes doc/workflow/file_finder.md | 46 -- doc/workflow/forking/branch_select.png | Bin 55352 -> 0 bytes doc/workflow/forking/merge_request.png | Bin 60597 -> 0 bytes doc/workflow/forking_workflow.md | 59 -- doc/workflow/four_stages.png | Bin 20934 -> 0 bytes doc/workflow/git_pull.png | Bin 167056 -> 0 bytes doc/workflow/gitdashflow.png | Bin 184726 -> 0 bytes doc/workflow/github_flow.png | Bin 20600 -> 0 bytes doc/workflow/gitlab_flow.md | 317 --------- doc/workflow/gitlab_flow.png | Bin 90883 -> 0 bytes doc/workflow/good_commit.png | Bin 28433 -> 0 bytes doc/workflow/groups.md | 93 --- doc/workflow/groups/access_requests_management.png | Bin 15193 -> 0 bytes doc/workflow/groups/add_member_to_group.png | Bin 138184 -> 0 bytes doc/workflow/groups/group_dashboard.png | Bin 107332 -> 0 bytes doc/workflow/groups/group_with_two_projects.png | Bin 129319 -> 0 bytes doc/workflow/groups/max_access_level.png | Bin 135354 -> 0 bytes doc/workflow/groups/new_group_button.png | Bin 185406 -> 0 bytes doc/workflow/groups/new_group_form.png | Bin 106491 -> 0 bytes .../groups/other_group_sees_shared_project.png | Bin 118382 -> 0 bytes doc/workflow/groups/override_access_level.png | Bin 157193 -> 0 bytes doc/workflow/groups/project_members_via_group.png | Bin 151339 -> 0 bytes doc/workflow/groups/request_access_button.png | Bin 30470 -> 0 bytes doc/workflow/groups/share_project_with_groups.png | Bin 118868 -> 0 bytes doc/workflow/groups/transfer_project.png | Bin 164958 -> 0 bytes .../groups/withdraw_access_request_button.png | Bin 31681 -> 0 bytes doc/workflow/img/award_emoji_select.png | Bin 65985 -> 0 bytes .../img/award_emoji_votes_least_popular.png | Bin 144501 -> 0 bytes .../img/award_emoji_votes_most_popular.png | Bin 136577 -> 0 bytes .../img/award_emoji_votes_sort_options.png | Bin 162251 -> 0 bytes doc/workflow/img/cherry_pick_changes_commit.png | Bin 353067 -> 0 bytes .../img/cherry_pick_changes_commit_modal.png | Bin 312659 -> 0 bytes doc/workflow/img/cherry_pick_changes_mr.png | Bin 252085 -> 0 bytes doc/workflow/img/cherry_pick_changes_mr_modal.png | Bin 225569 -> 0 bytes doc/workflow/img/file_finder_find_button.png | Bin 30974 -> 0 bytes doc/workflow/img/file_finder_find_file.png | Bin 42658 -> 0 bytes .../img/forking_workflow_choose_namespace.png | Bin 70405 -> 0 bytes doc/workflow/img/forking_workflow_fork_button.png | Bin 26438 -> 0 bytes .../img/forking_workflow_path_taken_error.png | Bin 22380 -> 0 bytes doc/workflow/img/new_branch_from_issue.png | Bin 120622 -> 0 bytes doc/workflow/img/revert_changes_commit.png | Bin 360098 -> 0 bytes doc/workflow/img/revert_changes_commit_modal.png | Bin 327932 -> 0 bytes doc/workflow/img/revert_changes_mr.png | Bin 367881 -> 0 bytes doc/workflow/img/revert_changes_mr_modal.png | Bin 335010 -> 0 bytes doc/workflow/img/todos_icon.png | Bin 7394 -> 0 bytes doc/workflow/img/todos_index.png | Bin 184839 -> 0 bytes .../img/web_editor_new_branch_dropdown.png | Bin 34233 -> 0 bytes doc/workflow/img/web_editor_new_branch_page.png | Bin 21618 -> 0 bytes .../img/web_editor_new_directory_dialog.png | Bin 26145 -> 0 bytes .../img/web_editor_new_directory_dropdown.png | Bin 33714 -> 0 bytes doc/workflow/img/web_editor_new_file_dropdown.png | Bin 34978 -> 0 bytes doc/workflow/img/web_editor_new_file_editor.png | Bin 128658 -> 0 bytes doc/workflow/img/web_editor_new_push_widget.png | Bin 11220 -> 0 bytes doc/workflow/img/web_editor_new_tag_dropdown.png | Bin 33753 -> 0 bytes doc/workflow/img/web_editor_new_tag_page.png | Bin 75536 -> 0 bytes .../img/web_editor_start_new_merge_request.png | Bin 14352 -> 0 bytes doc/workflow/img/web_editor_upload_file_dialog.png | Bin 46219 -> 0 bytes .../img/web_editor_upload_file_dropdown.png | Bin 34835 -> 0 bytes doc/workflow/importing/README.md | 17 - .../bitbucket_import_grant_access.png | Bin 30083 -> 0 bytes .../bitbucket_import_new_project.png | Bin 16502 -> 0 bytes .../bitbucket_import_select_bitbucket.png | Bin 46606 -> 0 bytes .../bitbucket_import_select_project.png | Bin 16121 -> 0 bytes .../fogbugz_importer/fogbugz_import_finished.png | Bin 53276 -> 0 bytes .../fogbugz_importer/fogbugz_import_login.png | Bin 44444 -> 0 bytes .../fogbugz_import_select_fogbogz.png | Bin 35415 -> 0 bytes .../fogbugz_import_select_project.png | Bin 62552 -> 0 bytes .../fogbugz_importer/fogbugz_import_user_map.png | Bin 157856 -> 0 bytes .../importing/gitlab_importer/importer.png | Bin 40778 -> 0 bytes .../importing/gitlab_importer/new_project_page.png | Bin 72663 -> 0 bytes .../img/import_projects_from_github_importer.png | Bin 28033 -> 0 bytes ...mport_projects_from_github_new_project_page.png | Bin 17225 -> 0 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/workflow/importing/migrating_from_svn.md | 79 --- doc/workflow/labels.md | 18 - doc/workflow/labels/label1.png | Bin 5846 -> 0 bytes doc/workflow/labels/label2.png | Bin 16931 -> 0 bytes doc/workflow/labels/label3.png | Bin 19360 -> 0 bytes doc/workflow/lfs/lfs_administration.md | 49 -- .../lfs/manage_large_binaries_with_git_lfs.md | 155 ---- doc/workflow/merge_commits.png | Bin 41422 -> 0 bytes doc/workflow/merge_request.png | Bin 169503 -> 0 bytes doc/workflow/merge_requests.md | 63 -- doc/workflow/merge_requests/commit_compare.png | Bin 110376 -> 0 bytes doc/workflow/merge_requests/merge_request_diff.png | Bin 166226 -> 0 bytes .../merge_request_diff_without_whitespace.png | Bin 121476 -> 0 bytes .../only_allow_merge_if_build_succeeds.png | Bin 17552 -> 0 bytes doc/workflow/merge_when_build_succeeds.md | 15 - doc/workflow/merge_when_build_succeeds/enable.png | Bin 151112 -> 0 bytes doc/workflow/merge_when_build_succeeds/status.png | Bin 180318 -> 0 bytes doc/workflow/messy_flow.png | Bin 33829 -> 0 bytes doc/workflow/milestones.md | 13 - doc/workflow/milestones/form.png | Bin 88591 -> 0 bytes doc/workflow/milestones/group_form.png | Bin 77087 -> 0 bytes doc/workflow/mr_inline_comments.png | Bin 193311 -> 0 bytes doc/workflow/notifications.md | 93 --- doc/workflow/notifications/settings.png | Bin 90986 -> 0 bytes doc/workflow/production_branch.png | Bin 21716 -> 0 bytes doc/workflow/project_features.md | 35 - doc/workflow/protected_branches.md | 31 - .../protected_branches/protected_branches1.png | Bin 170113 -> 0 bytes .../protected_branches/protected_branches2.png | Bin 25851 -> 0 bytes doc/workflow/rebase.png | Bin 123041 -> 0 bytes doc/workflow/release_branches.png | Bin 44173 -> 0 bytes doc/workflow/releases.md | 20 - doc/workflow/releases/new_tag.png | Bin 154755 -> 0 bytes doc/workflow/releases/tags.png | Bin 165449 -> 0 bytes doc/workflow/remove_checkbox.png | Bin 22272 -> 0 bytes doc/workflow/revert_changes.md | 64 -- doc/workflow/share_projects_with_other_groups.md | 30 - doc/workflow/share_with_group.md | 13 - doc/workflow/share_with_group.png | Bin 53784 -> 0 bytes doc/workflow/shortcuts.md | 5 - doc/workflow/shortcuts.png | Bin 108255 -> 0 bytes doc/workflow/timezone.md | 30 - doc/workflow/todos.md | 73 -- doc/workflow/web_editor.md | 152 ---- doc/workflow/wip_merge_requests.md | 13 - .../wip_merge_requests/blocked_accept_button.png | Bin 65231 -> 0 bytes doc/workflow/wip_merge_requests/mark_as_wip.png | Bin 41549 -> 0 bytes doc/workflow/wip_merge_requests/unmark_as_wip.png | Bin 32151 -> 0 bytes doc/workflow/workflow.md | 31 - 668 files changed, 10369 insertions(+), 10369 deletions(-) create mode 100644 doc/administration/customization/branded_login_page.md create mode 100644 doc/administration/customization/branded_login_page/appearance.png create mode 100644 doc/administration/customization/branded_login_page/custom_sign_in.png create mode 100644 doc/administration/customization/branded_login_page/default_login_page.png create mode 100644 doc/administration/customization/issue_closing.md create mode 100644 doc/administration/customization/libravatar.md create mode 100644 doc/administration/customization/welcome_message.md create mode 100644 doc/administration/downgrade_ee_to_ce/README.md create mode 100644 doc/administration/hooks/custom_hooks.md create mode 100644 doc/administration/incoming_email/README.md create mode 100644 doc/administration/incoming_email/postfix.md create mode 100644 doc/administration/integration/README.md create mode 100644 doc/administration/integration/akismet.md create mode 100644 doc/administration/integration/auth0.md create mode 100644 doc/administration/integration/azure.md create mode 100644 doc/administration/integration/bitbucket.md create mode 100644 doc/administration/integration/cas.md create mode 100644 doc/administration/integration/crowd.md create mode 100644 doc/administration/integration/external-issue-tracker.md create mode 100644 doc/administration/integration/facebook.md create mode 100644 doc/administration/integration/github.md create mode 100644 doc/administration/integration/gitlab.md create mode 100644 doc/administration/integration/gmail_action_buttons_for_gitlab.md create mode 100644 doc/administration/integration/google.md create mode 100644 doc/administration/integration/img/akismet_settings.png create mode 100644 doc/administration/integration/img/enabled-oauth-sign-in-sources.png create mode 100644 doc/administration/integration/img/facebook_api_keys.png create mode 100644 doc/administration/integration/img/facebook_app_settings.png create mode 100644 doc/administration/integration/img/facebook_website_url.png create mode 100644 doc/administration/integration/img/github_app.png create mode 100644 doc/administration/integration/img/gitlab_app.png create mode 100644 doc/administration/integration/img/gmail_action_buttons_for_gitlab.png create mode 100644 doc/administration/integration/img/google_app.png create mode 100644 doc/administration/integration/img/oauth_provider_admin_application.png create mode 100644 doc/administration/integration/img/oauth_provider_application_form.png create mode 100644 doc/administration/integration/img/oauth_provider_application_id_secret.png create mode 100644 doc/administration/integration/img/oauth_provider_authorized_application.png create mode 100644 doc/administration/integration/img/oauth_provider_user_wide_applications.png create mode 100644 doc/administration/integration/img/twitter_app_api_keys.png create mode 100644 doc/administration/integration/img/twitter_app_details.png create mode 100644 doc/administration/integration/jira.md create mode 100644 doc/administration/integration/ldap.md create mode 100644 doc/administration/integration/oauth_provider.md create mode 100644 doc/administration/integration/omniauth.md create mode 100644 doc/administration/integration/recaptcha.md create mode 100644 doc/administration/integration/saml.md create mode 100644 doc/administration/integration/shibboleth.md create mode 100644 doc/administration/integration/slack.md create mode 100644 doc/administration/integration/twitter.md create mode 100644 doc/administration/logs/logs.md create mode 100644 doc/administration/migrate_ci_to_ce/README.md create mode 100644 doc/administration/monitoring/health_check.md create mode 100644 doc/administration/monitoring/img/health_check_token.png create mode 100644 doc/administration/monitoring/performance/gitlab_configuration.md create mode 100644 doc/administration/monitoring/performance/grafana_configuration.md create mode 100644 doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png create mode 100644 doc/administration/monitoring/performance/img/grafana_dashboard_import.png create mode 100644 doc/administration/monitoring/performance/img/grafana_data_source_configuration.png create mode 100644 doc/administration/monitoring/performance/img/grafana_data_source_empty.png create mode 100644 doc/administration/monitoring/performance/img/grafana_save_icon.png create mode 100644 doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png create mode 100644 doc/administration/monitoring/performance/influxdb_configuration.md create mode 100644 doc/administration/monitoring/performance/influxdb_schema.md create mode 100644 doc/administration/monitoring/performance/introduction.md create mode 100644 doc/administration/operations/README.md create mode 100644 doc/administration/operations/cleaning_up_redis_sessions.md create mode 100644 doc/administration/operations/moving_repositories.md create mode 100644 doc/administration/operations/sidekiq_memory_killer.md create mode 100644 doc/administration/operations/unicorn.md create mode 100644 doc/administration/raketasks/README.md create mode 100644 doc/administration/raketasks/backup_hrz.png create mode 100644 doc/administration/raketasks/backup_restore.md create mode 100644 doc/administration/raketasks/check.md create mode 100644 doc/administration/raketasks/check_repos_output.png create mode 100644 doc/administration/raketasks/cleanup.md create mode 100644 doc/administration/raketasks/features.md create mode 100644 doc/administration/raketasks/import.md create mode 100644 doc/administration/raketasks/list_repos.md create mode 100644 doc/administration/raketasks/maintenance.md create mode 100644 doc/administration/raketasks/user_management.md create mode 100644 doc/administration/raketasks/web_hooks.md delete mode 100644 doc/container_registry/README.md delete mode 100644 doc/container_registry/img/container_registry.png delete mode 100644 doc/container_registry/img/project_feature.png delete mode 100644 doc/customization/branded_login_page.md delete mode 100644 doc/customization/branded_login_page/appearance.png delete mode 100644 doc/customization/branded_login_page/custom_sign_in.png delete mode 100644 doc/customization/branded_login_page/default_login_page.png delete mode 100644 doc/customization/issue_closing.md delete mode 100644 doc/customization/libravatar.md delete mode 100644 doc/customization/welcome_message.md delete mode 100644 doc/downgrade_ee_to_ce/README.md delete mode 100644 doc/gitlab-basics/README.md delete mode 100644 doc/gitlab-basics/add-file.md delete mode 100644 doc/gitlab-basics/add-image.md delete mode 100644 doc/gitlab-basics/add-merge-request.md delete mode 100644 doc/gitlab-basics/basic-git-commands.md delete mode 100644 doc/gitlab-basics/basicsimages/add_new_merge_request.png delete mode 100644 doc/gitlab-basics/basicsimages/add_sshkey.png delete mode 100644 doc/gitlab-basics/basicsimages/branch_info.png delete mode 100644 doc/gitlab-basics/basicsimages/branch_name.png delete mode 100644 doc/gitlab-basics/basicsimages/branches.png delete mode 100644 doc/gitlab-basics/basicsimages/button-create-mr.png delete mode 100644 doc/gitlab-basics/basicsimages/click-on-new-group.png delete mode 100644 doc/gitlab-basics/basicsimages/commit_changes.png delete mode 100644 doc/gitlab-basics/basicsimages/commit_message.png delete mode 100644 doc/gitlab-basics/basicsimages/commits.png delete mode 100644 doc/gitlab-basics/basicsimages/compare_branches.png delete mode 100644 doc/gitlab-basics/basicsimages/create_file.png delete mode 100644 doc/gitlab-basics/basicsimages/create_group.png delete mode 100644 doc/gitlab-basics/basicsimages/edit_file.png delete mode 100644 doc/gitlab-basics/basicsimages/file_located.png delete mode 100644 doc/gitlab-basics/basicsimages/file_name.png delete mode 100644 doc/gitlab-basics/basicsimages/find_file.png delete mode 100644 doc/gitlab-basics/basicsimages/find_group.png delete mode 100644 doc/gitlab-basics/basicsimages/fork.png delete mode 100644 doc/gitlab-basics/basicsimages/group_info.png delete mode 100644 doc/gitlab-basics/basicsimages/groups.png delete mode 100644 doc/gitlab-basics/basicsimages/https.png delete mode 100644 doc/gitlab-basics/basicsimages/image_file.png delete mode 100644 doc/gitlab-basics/basicsimages/issue_title.png delete mode 100644 doc/gitlab-basics/basicsimages/issues.png delete mode 100644 doc/gitlab-basics/basicsimages/key.png delete mode 100644 doc/gitlab-basics/basicsimages/merge_requests.png delete mode 100644 doc/gitlab-basics/basicsimages/new_issue.png delete mode 100644 doc/gitlab-basics/basicsimages/new_merge_request.png delete mode 100644 doc/gitlab-basics/basicsimages/new_project.png delete mode 100644 doc/gitlab-basics/basicsimages/newbranch.png delete mode 100644 doc/gitlab-basics/basicsimages/paste_sshkey.png delete mode 100644 doc/gitlab-basics/basicsimages/profile_settings.png delete mode 100644 doc/gitlab-basics/basicsimages/project_info.png delete mode 100644 doc/gitlab-basics/basicsimages/public_file_link.png delete mode 100644 doc/gitlab-basics/basicsimages/select-group.png delete mode 100644 doc/gitlab-basics/basicsimages/select-group2.png delete mode 100644 doc/gitlab-basics/basicsimages/select_branch.png delete mode 100644 doc/gitlab-basics/basicsimages/select_project.png delete mode 100644 doc/gitlab-basics/basicsimages/settings.png delete mode 100644 doc/gitlab-basics/basicsimages/shh_keys.png delete mode 100644 doc/gitlab-basics/basicsimages/submit_new_issue.png delete mode 100644 doc/gitlab-basics/basicsimages/title_description_mr.png delete mode 100644 doc/gitlab-basics/basicsimages/white_space.png delete mode 100644 doc/gitlab-basics/command-line-commands.md delete mode 100644 doc/gitlab-basics/create-branch.md delete mode 100644 doc/gitlab-basics/create-group.md delete mode 100644 doc/gitlab-basics/create-issue.md delete mode 100644 doc/gitlab-basics/create-project.md delete mode 100644 doc/gitlab-basics/create-your-ssh-keys.md delete mode 100644 doc/gitlab-basics/fork-project.md delete mode 100644 doc/gitlab-basics/start-using-git.md delete mode 100644 doc/hooks/custom_hooks.md delete mode 100644 doc/incoming_email/README.md delete mode 100644 doc/incoming_email/postfix.md delete mode 100644 doc/integration/README.md delete mode 100644 doc/integration/akismet.md delete mode 100644 doc/integration/auth0.md delete mode 100644 doc/integration/azure.md delete mode 100644 doc/integration/bitbucket.md delete mode 100644 doc/integration/cas.md delete mode 100644 doc/integration/crowd.md delete mode 100644 doc/integration/external-issue-tracker.md delete mode 100644 doc/integration/facebook.md delete mode 100644 doc/integration/github.md delete mode 100644 doc/integration/gitlab.md delete mode 100644 doc/integration/gmail_action_buttons_for_gitlab.md delete mode 100644 doc/integration/google.md delete mode 100644 doc/integration/img/akismet_settings.png delete mode 100644 doc/integration/img/enabled-oauth-sign-in-sources.png delete mode 100644 doc/integration/img/facebook_api_keys.png delete mode 100644 doc/integration/img/facebook_app_settings.png delete mode 100644 doc/integration/img/facebook_website_url.png delete mode 100644 doc/integration/img/github_app.png delete mode 100644 doc/integration/img/gitlab_app.png delete mode 100644 doc/integration/img/gmail_action_buttons_for_gitlab.png delete mode 100644 doc/integration/img/google_app.png delete mode 100644 doc/integration/img/oauth_provider_admin_application.png delete mode 100644 doc/integration/img/oauth_provider_application_form.png delete mode 100644 doc/integration/img/oauth_provider_application_id_secret.png delete mode 100644 doc/integration/img/oauth_provider_authorized_application.png delete mode 100644 doc/integration/img/oauth_provider_user_wide_applications.png delete mode 100644 doc/integration/img/twitter_app_api_keys.png delete mode 100644 doc/integration/img/twitter_app_details.png delete mode 100644 doc/integration/jira.md delete mode 100644 doc/integration/ldap.md delete mode 100644 doc/integration/oauth_provider.md delete mode 100644 doc/integration/omniauth.md delete mode 100644 doc/integration/recaptcha.md delete mode 100644 doc/integration/saml.md delete mode 100644 doc/integration/shibboleth.md delete mode 100644 doc/integration/slack.md delete mode 100644 doc/integration/twitter.md delete mode 100644 doc/logs/logs.md delete mode 100644 doc/markdown/img/logo.png delete mode 100644 doc/markdown/markdown.md delete mode 100644 doc/migrate_ci_to_ce/README.md delete mode 100644 doc/monitoring/health_check.md delete mode 100644 doc/monitoring/img/health_check_token.png delete mode 100644 doc/monitoring/performance/gitlab_configuration.md delete mode 100644 doc/monitoring/performance/grafana_configuration.md delete mode 100644 doc/monitoring/performance/img/grafana_dashboard_dropdown.png delete mode 100644 doc/monitoring/performance/img/grafana_dashboard_import.png delete mode 100644 doc/monitoring/performance/img/grafana_data_source_configuration.png delete mode 100644 doc/monitoring/performance/img/grafana_data_source_empty.png delete mode 100644 doc/monitoring/performance/img/grafana_save_icon.png delete mode 100644 doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png delete mode 100644 doc/monitoring/performance/influxdb_configuration.md delete mode 100644 doc/monitoring/performance/influxdb_schema.md delete mode 100644 doc/monitoring/performance/introduction.md delete mode 100644 doc/operations/README.md delete mode 100644 doc/operations/cleaning_up_redis_sessions.md delete mode 100644 doc/operations/moving_repositories.md delete mode 100644 doc/operations/sidekiq_memory_killer.md delete mode 100644 doc/operations/unicorn.md delete mode 100644 doc/permissions/permissions.md delete mode 100644 doc/profile/2fa.png delete mode 100644 doc/profile/2fa_auth.png delete mode 100644 doc/profile/2fa_u2f_authenticate.png delete mode 100644 doc/profile/2fa_u2f_register.png delete mode 100644 doc/profile/README.md delete mode 100644 doc/profile/preferences.md delete mode 100644 doc/profile/two_factor_authentication.md delete mode 100644 doc/project_services/bamboo.md delete mode 100644 doc/project_services/builds_emails.md delete mode 100644 doc/project_services/emails_on_push.md delete mode 100644 doc/project_services/hipchat.md delete mode 100644 doc/project_services/img/builds_emails_service.png delete mode 100644 doc/project_services/img/emails_on_push_service.png delete mode 100644 doc/project_services/img/jira_add_gitlab_commit_message.png delete mode 100644 doc/project_services/img/jira_add_user_to_group.png delete mode 100644 doc/project_services/img/jira_create_new_group.png delete mode 100644 doc/project_services/img/jira_create_new_group_name.png delete mode 100644 doc/project_services/img/jira_create_new_user.png delete mode 100644 doc/project_services/img/jira_group_access.png delete mode 100644 doc/project_services/img/jira_issue_closed.png delete mode 100644 doc/project_services/img/jira_issue_reference.png delete mode 100644 doc/project_services/img/jira_issues_workflow.png delete mode 100644 doc/project_services/img/jira_merge_request_close.png delete mode 100644 doc/project_services/img/jira_project_name.png delete mode 100644 doc/project_services/img/jira_reference_commit_message_in_jira_issue.png delete mode 100644 doc/project_services/img/jira_service.png delete mode 100644 doc/project_services/img/jira_service_close_issue.png delete mode 100644 doc/project_services/img/jira_service_page.png delete mode 100644 doc/project_services/img/jira_submit_gitlab_merge_request.png delete mode 100644 doc/project_services/img/jira_user_management_link.png delete mode 100644 doc/project_services/img/jira_workflow_screenshot.png delete mode 100644 doc/project_services/img/redmine_configuration.png delete mode 100644 doc/project_services/img/services_templates_redmine_example.png delete mode 100644 doc/project_services/irker.md delete mode 100644 doc/project_services/jira.md delete mode 100644 doc/project_services/project_services.md delete mode 100644 doc/project_services/redmine.md delete mode 100644 doc/project_services/services_templates.md delete mode 100644 doc/public_access/public_access.md delete mode 100644 doc/raketasks/README.md delete mode 100644 doc/raketasks/backup_hrz.png delete mode 100644 doc/raketasks/backup_restore.md delete mode 100644 doc/raketasks/check.md delete mode 100644 doc/raketasks/check_repos_output.png delete mode 100644 doc/raketasks/cleanup.md delete mode 100644 doc/raketasks/features.md delete mode 100644 doc/raketasks/import.md delete mode 100644 doc/raketasks/list_repos.md delete mode 100644 doc/raketasks/maintenance.md delete mode 100644 doc/raketasks/user_management.md delete mode 100644 doc/raketasks/web_hooks.md delete mode 100644 doc/ssh/README.md delete mode 100644 doc/system_hooks/system_hooks.md 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 delete mode 100644 doc/web_hooks/ssl.png delete mode 100644 doc/web_hooks/web_hooks.md delete mode 100644 doc/workflow/README.md delete mode 100644 doc/workflow/add-user/add-user.md delete mode 100644 doc/workflow/add-user/img/access_requests_management.png delete mode 100644 doc/workflow/add-user/img/add_new_user_to_project_settings.png delete mode 100644 doc/workflow/add-user/img/add_user_email_accept.png delete mode 100644 doc/workflow/add-user/img/add_user_email_ready.png delete mode 100644 doc/workflow/add-user/img/add_user_email_search.png delete mode 100644 doc/workflow/add-user/img/add_user_give_permissions.png delete mode 100644 doc/workflow/add-user/img/add_user_import_members_from_another_project.png delete mode 100644 doc/workflow/add-user/img/add_user_imported_members.png delete mode 100644 doc/workflow/add-user/img/add_user_list_members.png delete mode 100644 doc/workflow/add-user/img/add_user_members_menu.png delete mode 100644 doc/workflow/add-user/img/add_user_search_people.png delete mode 100644 doc/workflow/add-user/img/request_access_button.png delete mode 100644 doc/workflow/add-user/img/withdraw_access_request_button.png delete mode 100644 doc/workflow/authorization_for_merge_requests.md delete mode 100644 doc/workflow/award_emoji.md delete mode 100644 doc/workflow/award_emoji.png delete mode 100644 doc/workflow/cherry_pick_changes.md delete mode 100644 doc/workflow/ci_mr.png delete mode 100644 doc/workflow/close_issue_mr.png delete mode 100644 doc/workflow/environment_branches.png delete mode 100644 doc/workflow/file_finder.md delete mode 100644 doc/workflow/forking/branch_select.png delete mode 100644 doc/workflow/forking/merge_request.png delete mode 100644 doc/workflow/forking_workflow.md delete mode 100644 doc/workflow/four_stages.png delete mode 100644 doc/workflow/git_pull.png delete mode 100644 doc/workflow/gitdashflow.png delete mode 100644 doc/workflow/github_flow.png delete mode 100644 doc/workflow/gitlab_flow.md delete mode 100644 doc/workflow/gitlab_flow.png delete mode 100644 doc/workflow/good_commit.png delete mode 100644 doc/workflow/groups.md delete mode 100644 doc/workflow/groups/access_requests_management.png delete mode 100644 doc/workflow/groups/add_member_to_group.png delete mode 100644 doc/workflow/groups/group_dashboard.png delete mode 100644 doc/workflow/groups/group_with_two_projects.png delete mode 100644 doc/workflow/groups/max_access_level.png delete mode 100644 doc/workflow/groups/new_group_button.png delete mode 100644 doc/workflow/groups/new_group_form.png delete mode 100644 doc/workflow/groups/other_group_sees_shared_project.png delete mode 100644 doc/workflow/groups/override_access_level.png delete mode 100644 doc/workflow/groups/project_members_via_group.png delete mode 100644 doc/workflow/groups/request_access_button.png delete mode 100644 doc/workflow/groups/share_project_with_groups.png delete mode 100644 doc/workflow/groups/transfer_project.png delete mode 100644 doc/workflow/groups/withdraw_access_request_button.png delete mode 100644 doc/workflow/img/award_emoji_select.png delete mode 100644 doc/workflow/img/award_emoji_votes_least_popular.png delete mode 100644 doc/workflow/img/award_emoji_votes_most_popular.png delete mode 100644 doc/workflow/img/award_emoji_votes_sort_options.png delete mode 100644 doc/workflow/img/cherry_pick_changes_commit.png delete mode 100644 doc/workflow/img/cherry_pick_changes_commit_modal.png delete mode 100644 doc/workflow/img/cherry_pick_changes_mr.png delete mode 100644 doc/workflow/img/cherry_pick_changes_mr_modal.png delete mode 100644 doc/workflow/img/file_finder_find_button.png delete mode 100644 doc/workflow/img/file_finder_find_file.png delete mode 100644 doc/workflow/img/forking_workflow_choose_namespace.png delete mode 100644 doc/workflow/img/forking_workflow_fork_button.png delete mode 100644 doc/workflow/img/forking_workflow_path_taken_error.png delete mode 100644 doc/workflow/img/new_branch_from_issue.png delete mode 100644 doc/workflow/img/revert_changes_commit.png delete mode 100644 doc/workflow/img/revert_changes_commit_modal.png delete mode 100644 doc/workflow/img/revert_changes_mr.png delete mode 100644 doc/workflow/img/revert_changes_mr_modal.png delete mode 100644 doc/workflow/img/todos_icon.png delete mode 100644 doc/workflow/img/todos_index.png delete mode 100644 doc/workflow/img/web_editor_new_branch_dropdown.png delete mode 100644 doc/workflow/img/web_editor_new_branch_page.png delete mode 100644 doc/workflow/img/web_editor_new_directory_dialog.png delete mode 100644 doc/workflow/img/web_editor_new_directory_dropdown.png delete mode 100644 doc/workflow/img/web_editor_new_file_dropdown.png delete mode 100644 doc/workflow/img/web_editor_new_file_editor.png delete mode 100644 doc/workflow/img/web_editor_new_push_widget.png delete mode 100644 doc/workflow/img/web_editor_new_tag_dropdown.png delete mode 100644 doc/workflow/img/web_editor_new_tag_page.png delete mode 100644 doc/workflow/img/web_editor_start_new_merge_request.png delete mode 100644 doc/workflow/img/web_editor_upload_file_dialog.png delete mode 100644 doc/workflow/img/web_editor_upload_file_dropdown.png delete mode 100644 doc/workflow/importing/README.md delete mode 100644 doc/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png delete mode 100644 doc/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png delete mode 100644 doc/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png delete mode 100644 doc/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png delete mode 100644 doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png delete mode 100644 doc/workflow/importing/gitlab_importer/importer.png delete mode 100644 doc/workflow/importing/gitlab_importer/new_project_page.png delete mode 100644 doc/workflow/importing/img/import_projects_from_github_importer.png delete mode 100644 doc/workflow/importing/img/import_projects_from_github_new_project_page.png delete mode 100644 doc/workflow/importing/import_projects_from_bitbucket.md delete mode 100644 doc/workflow/importing/import_projects_from_fogbugz.md delete mode 100644 doc/workflow/importing/import_projects_from_github.md delete mode 100644 doc/workflow/importing/import_projects_from_gitlab_com.md delete mode 100644 doc/workflow/importing/migrating_from_svn.md delete mode 100644 doc/workflow/labels.md delete mode 100644 doc/workflow/labels/label1.png delete mode 100644 doc/workflow/labels/label2.png delete mode 100644 doc/workflow/labels/label3.png delete mode 100644 doc/workflow/lfs/lfs_administration.md delete mode 100644 doc/workflow/lfs/manage_large_binaries_with_git_lfs.md delete mode 100644 doc/workflow/merge_commits.png delete mode 100644 doc/workflow/merge_request.png delete mode 100644 doc/workflow/merge_requests.md delete mode 100644 doc/workflow/merge_requests/commit_compare.png delete mode 100644 doc/workflow/merge_requests/merge_request_diff.png delete mode 100644 doc/workflow/merge_requests/merge_request_diff_without_whitespace.png delete mode 100644 doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png delete mode 100644 doc/workflow/merge_when_build_succeeds.md delete mode 100644 doc/workflow/merge_when_build_succeeds/enable.png delete mode 100644 doc/workflow/merge_when_build_succeeds/status.png delete mode 100644 doc/workflow/messy_flow.png delete mode 100644 doc/workflow/milestones.md delete mode 100644 doc/workflow/milestones/form.png delete mode 100644 doc/workflow/milestones/group_form.png delete mode 100644 doc/workflow/mr_inline_comments.png delete mode 100644 doc/workflow/notifications.md delete mode 100644 doc/workflow/notifications/settings.png delete mode 100644 doc/workflow/production_branch.png delete mode 100644 doc/workflow/project_features.md delete mode 100644 doc/workflow/protected_branches.md delete mode 100644 doc/workflow/protected_branches/protected_branches1.png delete mode 100644 doc/workflow/protected_branches/protected_branches2.png delete mode 100644 doc/workflow/rebase.png delete mode 100644 doc/workflow/release_branches.png delete mode 100644 doc/workflow/releases.md delete mode 100644 doc/workflow/releases/new_tag.png delete mode 100644 doc/workflow/releases/tags.png delete mode 100644 doc/workflow/remove_checkbox.png delete mode 100644 doc/workflow/revert_changes.md delete mode 100644 doc/workflow/share_projects_with_other_groups.md delete mode 100644 doc/workflow/share_with_group.md delete mode 100644 doc/workflow/share_with_group.png delete mode 100644 doc/workflow/shortcuts.md delete mode 100644 doc/workflow/shortcuts.png delete mode 100644 doc/workflow/timezone.md delete mode 100644 doc/workflow/todos.md delete mode 100644 doc/workflow/web_editor.md delete mode 100644 doc/workflow/wip_merge_requests.md delete mode 100644 doc/workflow/wip_merge_requests/blocked_accept_button.png delete mode 100644 doc/workflow/wip_merge_requests/mark_as_wip.png delete mode 100644 doc/workflow/wip_merge_requests/unmark_as_wip.png delete mode 100644 doc/workflow/workflow.md diff --git a/doc/administration/customization/branded_login_page.md b/doc/administration/customization/branded_login_page.md new file mode 100644 index 00000000000..d4d9f5f7b5e --- /dev/null +++ b/doc/administration/customization/branded_login_page.md @@ -0,0 +1,19 @@ +# Changing the appearance of the login page + +GitLab Community Edition offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page. + +By default, the page shows the GitLab logo and description. + +![default_login_page](branded_login_page/default_login_page.png) + +## Changing the appearance of the login page + +Navigate to the **Admin** area and go to the **Appearance** page. + +Fill in the required details like Title, Description and upload the company logo. + +![appearance](branded_login_page/appearance.png) + +After saving the page, your GitLab login page will have the details you filled in: + +![company_login_page](branded_login_page/custom_sign_in.png) diff --git a/doc/administration/customization/branded_login_page/appearance.png b/doc/administration/customization/branded_login_page/appearance.png new file mode 100644 index 00000000000..6bce1f0a287 Binary files /dev/null and b/doc/administration/customization/branded_login_page/appearance.png differ diff --git a/doc/administration/customization/branded_login_page/custom_sign_in.png b/doc/administration/customization/branded_login_page/custom_sign_in.png new file mode 100644 index 00000000000..d6020b029a2 Binary files /dev/null and b/doc/administration/customization/branded_login_page/custom_sign_in.png differ diff --git a/doc/administration/customization/branded_login_page/default_login_page.png b/doc/administration/customization/branded_login_page/default_login_page.png new file mode 100644 index 00000000000..795c7954d8e Binary files /dev/null and b/doc/administration/customization/branded_login_page/default_login_page.png differ diff --git a/doc/administration/customization/issue_closing.md b/doc/administration/customization/issue_closing.md new file mode 100644 index 00000000000..194b8e00299 --- /dev/null +++ b/doc/administration/customization/issue_closing.md @@ -0,0 +1,39 @@ +# Issue closing pattern + +When a commit or merge request resolves one or more issues, it is possible to automatically have these issues closed when the commit or merge request lands in the project's default branch. + +If a commit message or merge request description contains a sentence matching the regular expression below, all issues referenced from +the matched text will be closed. This happens when the commit is pushed to a project's default branch, or when a commit or merge request is merged into there. + +When not specified, the default `issue_closing_pattern` as shown below will be used: + +```bash +((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+) +``` + +Here, `%{issue_ref}` is a complex regular expression defined inside GitLab, that matches a reference to a local issue (`#123`), cross-project issue (`group/project#123`) or a link to an issue (`https://gitlab.example.com/group/project/issues/123`). + +For example: + +``` +git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes group/otherproject#22). This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23." +``` + +will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does not match the pattern. It also works with multiline commit messages. + +Tip: you can test this closing pattern at [http://rubular.com][1]. Use this site +to test your own patterns. +Because Rubular doesn't understand `%{issue_ref}`, you can replace this by `#\d+` in testing, which matches only local issue references like `#123`. + +## Change the pattern + +For Omnibus installs you can change the default pattern in `/etc/gitlab/gitlab.rb`: + +``` +issue_closing_pattern: '((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)' +``` + +For manual installs you can customize the pattern in [gitlab.yml][0] using the `issue_closing_pattern` key. + +[0]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example +[1]: http://rubular.com/r/Xmbexed1OJ diff --git a/doc/administration/customization/libravatar.md b/doc/administration/customization/libravatar.md new file mode 100644 index 00000000000..c46ce2ee203 --- /dev/null +++ b/doc/administration/customization/libravatar.md @@ -0,0 +1,82 @@ +# Use Libravatar service with GitLab + +GitLab by default supports [Gravatar](https://gravatar.com) avatar service. +Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is +[heavily based on gravatar](https://wiki.libravatar.org/api/). + +This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server. + +# Configuration + +In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set +the configuration options as follows: + +## For HTTP + +```yml + gravatar: + enabled: true + # gravatar URLs: possible placeholders: %{hash} %{size} %{email} + plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" +``` + +## For HTTPS + +```yml + gravatar: + enabled: true + # gravatar URLs: possible placeholders: %{hash} %{size} %{email} + ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" +``` + +## Self-hosted + +If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration +but the important part is to provide the same placeholders so GitLab can parse the URL correctly. + +For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is + +`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` + + +## Omnibus-gitlab example + +In `/etc/gitlab/gitlab.rb`: + +#### For http + +```ruby +gitlab_rails['gravatar_enabled'] = true +gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" +``` + +#### For https + +```ruby +gitlab_rails['gravatar_enabled'] = true +gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" +``` + + +Run `sudo gitlab-ctl reconfigure` for changes to take effect. + + +## Default URL for missing images + +[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service. + +In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set. +For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` + + +## Usage examples + +#### For Microsoft Office 365 + +If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is +most useful in a corporate installation, where all users have access to Office 365. + +```ruby +gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' +gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' +``` diff --git a/doc/administration/customization/welcome_message.md b/doc/administration/customization/welcome_message.md new file mode 100644 index 00000000000..a0cb234bea0 --- /dev/null +++ b/doc/administration/customization/welcome_message.md @@ -0,0 +1,12 @@ +# Customize the complete sign-in page + +Please see [Branded login page](branded_login_page.md) + +# Add a welcome message to the sign-in page (GitLab Community Edition) + +It is possible to add a markdown-formatted welcome message to your GitLab +sign-in page. Users of GitLab Enterprise Edition should use the [branded login +page feature](branded_login_page.md) instead. + +The welcome message (extra_sign_in_text) can now be set/changed in the Admin UI. +Admin area > Settings diff --git a/doc/administration/downgrade_ee_to_ce/README.md b/doc/administration/downgrade_ee_to_ce/README.md new file mode 100644 index 00000000000..3625c4191b8 --- /dev/null +++ b/doc/administration/downgrade_ee_to_ce/README.md @@ -0,0 +1,82 @@ +# Downgrading from EE to CE + +If you ever decide to downgrade your Enterprise Edition back to the Community +Edition, there are a few steps you need take before installing the CE package +on top of the current EE package, or, if you are in an installation from source, +before you change remotes and fetch the latest CE code. + +## Disable Enterprise-only features + +First thing to do is to disable the following features. + +### Authentication mechanisms + +Kerberos and Atlassian Crowd are only available on the Enterprise Edition, so +you should disable these mechanisms before downgrading and you should provide +alternative authentication methods to your users. + +### Git Annex + +Git Annex is also only available on the Enterprise Edition. This means that if +you have repositories that use Git Annex to store large files, these files will +no longer be easily available via Git. You should consider migrating these +repositories to use Git LFS before downgrading to the Community Edition. + +### Remove Jenkins CI Service entries from the database + +The `JenkinsService` class is only available on the Enterprise Edition codebase, +so if you downgrade to the Community Edition, you'll come across the following +error: + +``` +Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) + +ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'JenkinsService'. This +error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this +column if you didn't intend it to be used for storing the inheritance class or overwrite Service.inheritance_column to +use another column for that information.) +``` + +All services are created automatically for every project you have, so in order +to avoid getting this error, you need to remove all instances of the +`JenkinsService` from your database: + +**Omnibus Installation** + +``` +$ sudo gitlab-rails runner "Service.where(type: 'JenkinsService').delete_all" +``` + +**Source Installation** + +``` +$ bundle exec rails runner "Service.where(type: 'JenkinsService').delete_all" production +``` + +## Downgrade to CE + +After performing the above mentioned steps, you are now ready to downgrade your +GitLab installation to the Community Edition. + +**Omnibus Installation** + +To downgrade an Omnibus installation, it is sufficient to install the Community +Edition package on top of the currently installed one. You can do this manually, +by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) +you need, or by adding our CE package repository and following the +[CE installation instructions](https://about.gitlab.com/downloads/). + +**Source Installation** + +To downgrade a source installation, you need to replace the current remote of +your GitLab installation with the Community Edition's remote, fetch the latest +changes, and checkout the latest stable branch: + +``` +$ git remote set-url origin git@gitlab.com:gitlab-org/gitlab-ce.git +$ git fetch --all +$ git checkout 8-x-stable +``` + +Remember to follow the correct [update guides](../update/README.md) to make +sure all dependencies are up to date. diff --git a/doc/administration/hooks/custom_hooks.md b/doc/administration/hooks/custom_hooks.md new file mode 100644 index 00000000000..820934f97f1 --- /dev/null +++ b/doc/administration/hooks/custom_hooks.md @@ -0,0 +1,41 @@ +# Custom Git Hooks + +**Note: Custom git hooks must be configured on the filesystem of the GitLab +server. Only GitLab server administrators will be able to complete these tasks. +Please explore [webhooks](../web_hooks/web_hooks.md) as an option if you do not have filesystem access. For a user configurable Git Hooks interface, please see [GitLab Enterprise Edition Git Hooks](http://docs.gitlab.com/ee/git_hooks/git_hooks.html).** + +Git natively supports hooks that are executed on different actions. +Examples of server-side git hooks include pre-receive, post-receive, and update. +See +[Git SCM Server-Side Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks) +for more information about each hook type. + +As of gitlab-shell version 2.2.0 (which requires GitLab 7.5+), GitLab +administrators can add custom git hooks to any GitLab project. + +## Setup + +Normally, git hooks are placed in the repository or project's `hooks` directory. +GitLab creates a symlink from each project's `hooks` directory to the +gitlab-shell `hooks` directory for ease of maintenance between gitlab-shell +upgrades. As such, custom hooks are implemented a little differently. Behavior +is exactly the same once the hook is created, though. Follow these steps to +set up a custom hook. + +1. Pick a project that needs a custom git hook. +1. On the GitLab server, navigate to the project's repository directory. +For an installation from source the path is usually +`/home/git/repositories//.git`. For Omnibus installs the path is +usually `/var/opt/gitlab/git-data/repositories//.git`. +1. Create a new directory in this location called `custom_hooks`. +1. Inside the new `custom_hooks` directory, create a file with a name matching +the hook type. For a pre-receive hook the file name should be `pre-receive` with +no extension. +1. Make the hook file executable and make sure it's owned by git. +1. Write the code to make the git hook function as expected. Hooks can be +in any language. Ensure the 'shebang' at the top properly reflects the language +type. For example, if the script is in Ruby the shebang will probably be +`#!/usr/bin/env ruby`. + +That's it! Assuming the hook code is properly implemented the hook will fire +as appropriate. diff --git a/doc/administration/incoming_email/README.md b/doc/administration/incoming_email/README.md new file mode 100644 index 00000000000..5a9a1582877 --- /dev/null +++ b/doc/administration/incoming_email/README.md @@ -0,0 +1,302 @@ +# Reply by email + +GitLab can be set up to allow users to comment on issues and merge requests by +replying to notification emails. + +## Requirement + +Reply by email requires an IMAP-enabled email account. GitLab allows you to use +three strategies for this feature: +- using email sub-addressing +- using a dedicated email address +- using a catch-all mailbox + +### Email sub-addressing + +**If your provider or server supports email sub-addressing, we recommend using it.** + +[Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is +a feature where any email to `user+some_arbitrary_tag@example.com` will end up +in the mailbox for `user@example.com`, and is supported by providers such as +Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix +mail server which you can run on-premises. + +### Dedicated email address + +This solution is really simple to set up: you just have to create an email +address dedicated to receive your users' replies to GitLab notifications. + +### Catch-all mailbox + +A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will +"catch all" the emails addressed to the domain that do not exist in the mail +server. + +## How it works? + +### 1. GitLab sends a notification email + +When GitLab sends a notification and Reply by email is enabled, the `Reply-To` +header is set to the address defined in your GitLab configuration, with the +`%{key}` placeholder (if present) replaced by a specific "reply key". In +addition, this "reply key" is also added to the `References` header. + +### 2. You reply to the notification email + +When you reply to the notification email, your email client will: + +- send the email to the `Reply-To` address it got from the notification email +- set the `In-Reply-To` header to the value of the `Message-ID` header from the + notification email +- set the `References` header to the value of the `Message-ID` plus the value of + the notification email's `References` header. + +### 3. GitLab receives your reply to the notification email + +When GitLab receives your reply, it will look for the "reply key" in the +following headers, in this order: + +1. the `To` header +1. the `References` header + +If it finds a reply key, it will be able to leave your reply as a comment on +the entity the notification was about (issue, merge request, commit...). + +For more details about the `Message-ID`, `In-Reply-To`, and `References headers`, +please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). + +## Set it up + +If you want to use Gmail / Google Apps with Reply by email, make sure you have +[IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) +and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255). + +To set up a basic Postfix mail server with IMAP access on Ubuntu, follow +[these instructions](./postfix.md). + +### Omnibus package installations + +1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the + feature and fill in the details for your specific IMAP server and email account: + + ```ruby + # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com + gitlab_rails['incoming_email_enabled'] = true + + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com" + + # Email account username + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + gitlab_rails['incoming_email_email'] = "incoming" + # Email account password + gitlab_rails['incoming_email_password'] = "[REDACTED]" + + # IMAP server host + gitlab_rails['incoming_email_host'] = "gitlab.example.com" + # IMAP server port + gitlab_rails['incoming_email_port'] = 143 + # Whether the IMAP server uses SSL + gitlab_rails['incoming_email_ssl'] = false + # Whether the IMAP server uses StartTLS + gitlab_rails['incoming_email_start_tls'] = false + + # The mailbox where incoming mail will end up. Usually "inbox". + gitlab_rails['incoming_email_mailbox_name'] = "inbox" + ``` + + ```ruby + # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com + gitlab_rails['incoming_email_enabled'] = true + + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com" + + # Email account username + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com" + # Email account password + gitlab_rails['incoming_email_password'] = "[REDACTED]" + + # IMAP server host + gitlab_rails['incoming_email_host'] = "imap.gmail.com" + # IMAP server port + gitlab_rails['incoming_email_port'] = 993 + # Whether the IMAP server uses SSL + gitlab_rails['incoming_email_ssl'] = true + # Whether the IMAP server uses StartTLS + gitlab_rails['incoming_email_start_tls'] = false + + # The mailbox where incoming mail will end up. Usually "inbox". + gitlab_rails['incoming_email_mailbox_name'] = "inbox" + ``` + +1. Reconfigure GitLab and restart mailroom for the changes to take effect: + + ```sh + sudo gitlab-ctl reconfigure + sudo gitlab-ctl restart mailroom + ``` + +1. Verify that everything is configured correctly: + + ```sh + sudo gitlab-rake gitlab:incoming_email:check + ``` + +1. Reply by email should now be working. + +### Installations from source + +1. Go to the GitLab installation directory: + + ```sh + cd /home/git/gitlab + ``` + +1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature + and fill in the details for your specific IMAP server and email account: + + ```sh + sudo editor config/gitlab.yml + ``` + + ```yaml + # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com + incoming_email: + enabled: true + + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + address: "incoming+%{key}@gitlab.example.com" + + # Email account username + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + user: "incoming" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "gitlab.example.com" + # IMAP server port + port: 143 + # Whether the IMAP server uses SSL + ssl: false + # Whether the IMAP server uses StartTLS + start_tls: false + + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + ``` + + ```yaml + # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com + incoming_email: + enabled: true + + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + address: "gitlab-incoming+%{key}@gmail.com" + + # Email account username + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + user: "gitlab-incoming@gmail.com" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "imap.gmail.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true + # Whether the IMAP server uses StartTLS + start_tls: false + + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + ``` + +1. Enable `mail_room` in the init script at `/etc/default/gitlab`: + + ```sh + sudo mkdir -p /etc/default + echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab + ``` + +1. Restart GitLab: + + ```sh + sudo service gitlab restart + ``` + +1. Verify that everything is configured correctly: + + ```sh + sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production + ``` + +1. Reply by email should now be working. + +### Development + +1. Go to the GitLab installation directory. + +1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account: + + ```yaml + # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com + incoming_email: + enabled: true + + # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. + # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). + address: "gitlab-incoming+%{key}@gmail.com" + + # Email account username + # With third party providers, this is usually the full email address. + # With self-hosted email servers, this is usually the user part of the email address. + user: "gitlab-incoming@gmail.com" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "imap.gmail.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true + # Whether the IMAP server uses StartTLS + start_tls: false + + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + ``` + + As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`. + +1. Uncomment the `mail_room` line in your `Procfile`: + + ```yaml + mail_room: bundle exec mail_room -q -c config/mail_room.yml + ``` + +1. Restart GitLab: + + ```sh + bundle exec foreman start + ``` + +1. Verify that everything is configured correctly: + + ```sh + bundle exec rake gitlab:incoming_email:check RAILS_ENV=development + ``` + +1. Reply by email should now be working. diff --git a/doc/administration/incoming_email/postfix.md b/doc/administration/incoming_email/postfix.md new file mode 100644 index 00000000000..787d21f7f8f --- /dev/null +++ b/doc/administration/incoming_email/postfix.md @@ -0,0 +1,321 @@ +# Set up Postfix for Reply by email + +This document will take you through the steps of setting up a basic Postfix mail server with IMAP authentication on Ubuntu, to be used with Reply by email. + +The instructions make the assumption that you will be using the email address `incoming@gitlab.example.com`, that is, username `incoming` on host `gitlab.example.com`. Don't forget to change it to your actual host when executing the example code snippets. + +## Configure your server firewall + +1. Open up port 25 on your server so that people can send email into the server over SMTP. +2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP. + +## Install packages + +1. Install the `postfix` package if it is not installed already: + + ```sh + sudo apt-get install postfix + ``` + + When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`. + +1. Install the `mailutils` package. + + ```sh + sudo apt-get install mailutils + ``` + +## Create user + +1. Create a user for incoming email. + + ```sh + sudo useradd -m -s /bin/bash incoming + ``` + +1. Set a password for this user. + + ```sh + sudo passwd incoming + ``` + + Be sure not to forget this, you'll need it later. + +## Test the out-of-the-box setup + +1. Connect to the local SMTP server: + + ```sh + telnet localhost 25 + ``` + + You should see a prompt like this: + + ```sh + Trying 127.0.0.1... + Connected to localhost. + Escape character is '^]'. + 220 gitlab.example.com ESMTP Postfix (Ubuntu) + ``` + + If you get a `Connection refused` error instead, verify that `postfix` is running: + + ```sh + sudo postfix status + ``` + + If it is not, start it: + + ```sh + sudo postfix start + ``` + +1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: + + ``` + ehlo localhost + mail from: root@localhost + rcpt to: incoming@localhost + data + Subject: Re: Some issue + + Sounds good! + . + quit + ``` + + _**Note:** The `.` is a literal period on its own line._ + + _**Note:** If you receive an error after entering `rcpt to: incoming@localhost` + then your Postfix `my_network` configuration is not correct. The error will + say 'Temporary lookup failure'. See + [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._ + +1. Check if the `incoming` user received the email: + + ```sh + su - incoming + mail + ``` + + You should see output like this: + + ``` + "/var/mail/incoming": 1 message 1 unread + >U 1 root@localhost 59/2842 Re: Some issue + ``` + + Quit the mail app: + + ```sh + q + ``` + +1. Log out of the `incoming` account and go back to being `root`: + + ```sh + logout + ``` + +## Configure Postfix to use Maildir-style mailboxes + +Courier, which we will install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox. + +1. Configure Postfix to use Maildir-style mailboxes: + + ```sh + sudo postconf -e "home_mailbox = Maildir/" + ``` + +1. Restart Postfix: + + ```sh + sudo /etc/init.d/postfix restart + ``` + +1. Test the new setup: + + 1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_. + 1. Check if the `incoming` user received the email: + + ```sh + su - incoming + MAIL=/home/incoming/Maildir + mail + ``` + + You should see output like this: + + ``` + "/home/incoming/Maildir": 1 message 1 unread + >U 1 root@localhost 59/2842 Re: Some issue + ``` + + Quit the mail app: + + ```sh + q + ``` + + _**Note:** If `mail` returns an error `Maildir: Is a directory` then your + version of `mail` doesn't support Maildir style mailboxes. Install + `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then, + try the above steps again, substituting `heirloom-mailx` for the `mail` + command._ + +1. Log out of the `incoming` account and go back to being `root`: + + ```sh + logout + ``` + +## Install the Courier IMAP server + +1. Install the `courier-imap` package: + + ```sh + sudo apt-get install courier-imap + ``` + +## Configure Postfix to receive email from the internet + +1. Let Postfix know about the domains that it should consider local: + + ```sh + sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost" + ``` + +1. Let Postfix know about the IPs that it should consider part of the LAN: + + We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network. + + ```sh + sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24" + ``` + +1. Configure Postfix to receive mail on all interfaces, which includes the internet: + + ```sh + sudo postconf -e "inet_interfaces = all" + ``` + +1. Configure Postfix to use the `+` delimiter for sub-addressing: + + ```sh + sudo postconf -e "recipient_delimiter = +" + ``` + +1. Restart Postfix: + + ```sh + sudo service postfix restart + ``` + +## Test the final setup + +1. Test SMTP under the new setup: + + 1. Connect to the SMTP server: + + ```sh + telnet gitlab.example.com 25 + ``` + + You should see a prompt like this: + + ```sh + Trying 123.123.123.123... + Connected to gitlab.example.com. + Escape character is '^]'. + 220 gitlab.example.com ESMTP Postfix (Ubuntu) + ``` + + If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25. + + 1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: + + ``` + ehlo gitlab.example.com + mail from: root@gitlab.example.com + rcpt to: incoming@gitlab.example.com + data + Subject: Re: Some issue + + Sounds good! + . + quit + ``` + + (Note: The `.` is a literal period on its own line) + + 1. Check if the `incoming` user received the email: + + ```sh + su - incoming + MAIL=/home/incoming/Maildir + mail + ``` + + You should see output like this: + + ``` + "/home/incoming/Maildir": 1 message 1 unread + >U 1 root@gitlab.example.com 59/2842 Re: Some issue + ``` + + Quit the mail app: + + ```sh + q + ``` + + 1. Log out of the `incoming` account and go back to being `root`: + + ```sh + logout + ``` + +1. Test IMAP under the new setup: + + 1. Connect to the IMAP server: + + ```sh + telnet gitlab.example.com 143 + ``` + + You should see a prompt like this: + + ```sh + Trying 123.123.123.123... + Connected to mail.example.gitlab.com. + Escape character is '^]'. + - OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information. + ``` + + 1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt: + + ``` + a login incoming PASSWORD + ``` + + Replace PASSWORD with the password you set on the `incoming` user earlier. + + You should see output like this: + + ``` + a OK LOGIN Ok. + ``` + + 1. Disconnect from the IMAP server: + + ```sh + a logout + ``` + +## Done! + +If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) guide to configure GitLab. + +--------- + +_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._ diff --git a/doc/administration/integration/README.md b/doc/administration/integration/README.md new file mode 100644 index 00000000000..fd330dd7a7d --- /dev/null +++ b/doc/administration/integration/README.md @@ -0,0 +1,61 @@ +# GitLab Integration + +GitLab integrates with multiple third-party services to allow external issue +trackers and external authentication. + +See the documentation below for details on how to configure these services. + +- [Jira](../project_services/jira.md) Integrate with the JIRA issue tracker +- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. +- [LDAP](ldap.md) Set up sign in via LDAP +- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd and Azure +- [SAML](saml.md) Configure GitLab as a SAML 2.0 Service Provider +- [CAS](cas.md) Configure GitLab to sign in using CAS +- [Slack](slack.md) Integrate with the Slack chat service +- [OAuth2 provider](oauth_provider.md) OAuth2 application creation +- [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages +- [reCAPTCHA](recaptcha.md) Configure GitLab to use Google reCAPTCHA for new users +- [Akismet](akismet.md) Configure Akismet to stop spam + +GitLab Enterprise Edition contains [advanced Jenkins support][jenkins]. + +[jenkins]: http://docs.gitlab.com/ee/integration/jenkins.html + + +## Project services + +Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, +Pivotal Tracker, and Slack are available in the form of a [Project Service][]. + +[Project Service]: ../project_services/project_services.md + +## SSL certificate errors + +When trying to integrate GitLab with services that are using self-signed certificates, +it is very likely that SSL certificate errors will occur on different parts of the +application, most likely Sidekiq. There are 2 approaches you can take to solve this: + +1. Add the root certificate to the trusted chain of the OS. +1. If using Omnibus, you can add the certificate to GitLab's trusted certificates. + +**OS main trusted chain** + +This [resource](http://kb.kerio.com/product/kerio-connect/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) +has all the information you need to add a certificate to the main trusted chain. + +This [answer](http://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) +at SuperUser also has relevant information. + +**Omnibus Trusted Chain** + +It is enough to concatenate the certificate to the main trusted certificate: + +```bash +cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem +``` + +After that restart GitLab with: + +```bash +sudo gitlab-ctl restart +``` diff --git a/doc/administration/integration/akismet.md b/doc/administration/integration/akismet.md new file mode 100644 index 00000000000..5cc09bd536d --- /dev/null +++ b/doc/administration/integration/akismet.md @@ -0,0 +1,30 @@ +# Akismet + +GitLab leverages [Akismet](http://akismet.com) to protect against spam. Currently +GitLab uses Akismet to prevent users who are not members of a project from +creating spam via the GitLab API. Detected spam will be rejected, and +an entry in the "Spam Log" section in the Admin page will be created. + +Privacy note: GitLab submits the user's IP and user agent to Akismet. Note that +adding a user to a project will disable the Akismet check and prevent this +from happening. + +## Configuration + +To use Akismet: + +1. Go to the URL: https://akismet.com/account/ + +2. Sign-in or create a new account. + +3. Click on "Show" to reveal the API key. + +4. Go to Applications Settings on Admin Area (`admin/application_settings`) + +5. Check the `Enable Akismet` checkbox + +6. Fill in the API key from step 3. + +7. Save the configuration. + +![Screenshot of Akismet settings](img/akismet_settings.png) diff --git a/doc/administration/integration/auth0.md b/doc/administration/integration/auth0.md new file mode 100644 index 00000000000..e5247082a89 --- /dev/null +++ b/doc/administration/integration/auth0.md @@ -0,0 +1,89 @@ +# Auth0 OmniAuth Provider + +To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an +application. + +1. Sign in to the [Auth0 Console](https://manage.auth0.com). If you need to +create an account, you can do so at the same link. + +1. Select "New App/API". + +1. Provide the Application Name ('GitLab' works fine). + +1. Once created, you should see the Quick Start options. Disregard them and +select 'Settings' above the Quick Start options. + +1. At the top of the Settings screen, you should see your Domain, Client ID and +Client Secret. Take note of these as you'll need to put them in the +configuration file. For example: + - Domain: `test1234.auth0.com` + - Client ID: `t6X8L2465bNePWLOvt9yi41i` + - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` + +1. Fill in the Allowed Callback URLs: + - http://`YOUR_GITLAB_URL`/users/auth/auth0/callback (or) + - https://`YOUR_GITLAB_URL`/users/auth/auth0/callback + +1. Fill in the Allowed Origins (CORS): + - http://`YOUR_GITLAB_URL` (or) + - https://`YOUR_GITLAB_URL` + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "auth0", + "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID'', + client_secret: 'YOUR_AUTH0_CLIENT_SECRET', + namespace: 'YOUR_AUTH0_DOMAIN' + } + } + ] + ``` + + For installations from source: + + ```yaml + - { name: 'auth0', + args: { + client_id: 'YOUR_AUTH0_CLIENT_ID', + client_secret: 'YOUR_AUTH0_CLIENT_SECRET', + namespace: 'YOUR_AUTH0_DOMAIN' + } + } + ``` + +1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page +from step 5. + +1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console +page from step 5. + +1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) +for the changes to take effect. + +On the sign in page there should now be an Auth0 icon below the regular sign in +form. Click the icon to begin the authentication process. Auth0 will ask the +user to sign in and authorize the GitLab application. If everything goes well +the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/integration/azure.md b/doc/administration/integration/azure.md new file mode 100644 index 00000000000..48dddf7df44 --- /dev/null +++ b/doc/administration/integration/azure.md @@ -0,0 +1,83 @@ +# Microsoft Azure OAuth2 OmniAuth Provider + +To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. + +1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com>). + +1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab. + +1. Select "Applications" at the top bar and click the "Add" button the bottom. + +1. Select "Add an application my organization is developing". + +1. Provide the project information and click the "Next" button. + - Name: 'GitLab' works just fine here. + - Type: 'WEB APPLICATION AND/OR WEB API' + +1. On the "App properties" page enter the needed URI's and click the "Complete" button. + - SIGN-IN URL: Enter the URL of your GitLab installation (e.g 'https://gitlab.mycompany.com/') + - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g 'https://mycompany.onmicrosoft.com/gitlab') + +1. Select "Configure" in the top menu. + +1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. https://gitlab.mycompany.com/users/auth/azure_oauth2/callback). + +1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu.. + +1. Note the "CLIENT ID" and the "CLIENT SECRET". + +1. Select "View endpoints" from the bottom menu. + +1. You will see lots of endpoint URLs in the form 'https://login.microsoftonline.com/TENANT ID/...', note down the TENANT ID part of one of those endpoints. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "azure_oauth2", + "args" => { + "client_id" => "CLIENT ID", + "client_secret" => "CLIENT SECRET", + "tenant_id" => "TENANT ID", + } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'azure_oauth2', + args: { client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID" } } + ``` + +1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Microsoft icon below the regular sign in form. Click the icon to begin the authentication process. Microsoft will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/integration/bitbucket.md b/doc/administration/integration/bitbucket.md new file mode 100644 index 00000000000..63432b04432 --- /dev/null +++ b/doc/administration/integration/bitbucket.md @@ -0,0 +1,140 @@ +# Integrate your server with Bitbucket + +Import projects from Bitbucket and login to your GitLab instance with your Bitbucket account. + +To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket. +Bitbucket will generate an application ID and secret key for you to use. + +1. Sign in to Bitbucket. + +1. Navigate to your individual user settings or a team's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or a team - that is entirely up to you. + +1. Select "OAuth" in the left menu. + +1. Select "Add consumer". + +1. Provide the required details. + - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. + - Application description: Fill this in if you wish. + - URL: The URL to your GitLab installation. 'https://gitlab.company.com' +1. Select "Save". + +1. You should now see a Key and Secret in the list of OAuth customers. + Keep this page open as you continue configuration. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "bitbucket", + "app_id" => "YOUR_KEY", + "app_secret" => "YOUR_APP_SECRET", + "url" => "https://bitbucket.org/" + } + ] + ``` + + For installation from source: + + ``` + - { name: 'bitbucket', app_id: 'YOUR_KEY', + app_secret: 'YOUR_APP_SECRET' } + ``` + +1. Change 'YOUR_APP_ID' to the key from the Bitbucket application page from step 7. + +1. Change 'YOUR_APP_SECRET' to the secret from the Bitbucket application page from step 7. + +1. Save the configuration file. + +1. If you're using the omnibus package, reconfigure GitLab (```gitlab-ctl reconfigure```). + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Bitbucket icon below the regular sign in form. +Click the icon to begin the authentication process. Bitbucket will ask the user to sign in and authorize the GitLab application. +If everything goes well the user will be returned to GitLab and will be signed in. + +## Bitbucket project import + +To allow projects to be imported directly into GitLab, Bitbucket requires two extra setup steps compared to GitHub and GitLab.com. + +Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and instead requires GitLab to use SSH and identify itself using your GitLab server's SSH key. + +### Step 1: Public key + +To be able to access repositories on Bitbucket, GitLab will automatically register your public key with Bitbucket as a deploy key for the repositories to be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa.pub`, which will expand to `/home/git/.ssh/bitbucket_rsa.pub` in most configurations. + +If you have that file in place, you're all set and should see the "Import projects from Bitbucket" option enabled. If you don't, do the following: + +1. Create a new SSH key: + + ```sh + sudo -u git -H ssh-keygen + ``` + + When asked `Enter file in which to save the key` specify the correct path, eg. `/home/git/.ssh/bitbucket_rsa`. + Make sure to use an **empty passphrase**. + +1. Configure SSH client to use your new key: + + Open the SSH configuration file of the git user. + + ```sh + sudo editor /home/git/.ssh/config + ``` + + Add a host configuration for `bitbucket.org`. + + ```sh + Host bitbucket.org + IdentityFile ~/.ssh/bitbucket_rsa + User git + ``` + +### Step 2: Known hosts + +To allow GitLab to connect to Bitbucket over SSH, you need to add 'bitbucket.org' to your GitLab server's known SSH hosts. Take the following steps to do so: + +1. Manually connect to 'bitbucket.org' over SSH, while logged in as the `git` account that GitLab will use: + + ```sh + sudo -u git -H ssh bitbucket.org + ``` + +1. Verify the RSA key fingerprint you'll see in the response matches the one in the [Bitbucket documentation](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket'spublickeyfingerprints) (the specific IP address doesn't matter): + + ```sh + The authenticity of host 'bitbucket.org (207.223.240.182)' can't be established. + RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40. + Are you sure you want to continue connecting (yes/no)? + ``` + +1. If the fingerprint matches, type `yes` to continue connecting and have 'bitbucket.org' be added to your known hosts. + +1. Your GitLab server is now able to connect to Bitbucket over SSH. + +1. Restart GitLab to allow it to find the new public key. + +You should now see the "Import projects from Bitbucket" option on the New Project page enabled. diff --git a/doc/administration/integration/cas.md b/doc/administration/integration/cas.md new file mode 100644 index 00000000000..e34e306f9ac --- /dev/null +++ b/doc/administration/integration/cas.md @@ -0,0 +1,65 @@ +# CAS OmniAuth Provider + +To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name"=> "cas3", + "label"=> "cas", + "args"=> { + "url"=> 'CAS_SERVER', + "login_url"=> '/CAS_PATH/login', + "service_validate_url"=> '/CAS_PATH/p3/serviceValidate', + "logout_url"=> '/CAS_PATH/logout' + } + } + ] + ``` + + + For installations from source: + + ``` + - { name: 'cas3', + label: 'cas', + args: { + url: 'CAS_SERVER', + login_url: '/CAS_PATH/login', + service_validate_url: '/CAS_PATH/p3/serviceValidate', + logout_url: '/CAS_PATH/logout'} } + ``` + +1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`). + +1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0. + +1. Save the configuration file. + +1. Run `gitlab-ctl reconfigure` for the omnibus package. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a CAS tab in the sign in form. diff --git a/doc/administration/integration/crowd.md b/doc/administration/integration/crowd.md new file mode 100644 index 00000000000..40d93aef2a9 --- /dev/null +++ b/doc/administration/integration/crowd.md @@ -0,0 +1,58 @@ +# Crowd OmniAuth Provider + +To enable the Crowd OmniAuth provider you must register your application with Crowd. To configure Crowd integration you need an application name and password. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "crowd", + "args" => { + "crowd_server_url" => "CROWD", + "application_name" => "YOUR_APP_NAME", + "application_password" => "YOUR_APP_PASSWORD" + } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'crowd', + args: { + crowd_server_url: 'CROWD SERVER URL', + application_name: 'YOUR_APP_NAME', + application_password: 'YOUR_APP_PASSWORD' } } + ``` + +1. Change 'YOUR_APP_NAME' to the application name from Crowd applications page. + +1. Change 'YOUR_APP_PASSWORD' to the application password you've set. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Crowd tab in the sign in form. \ No newline at end of file diff --git a/doc/administration/integration/external-issue-tracker.md b/doc/administration/integration/external-issue-tracker.md new file mode 100644 index 00000000000..a2d7e922aad --- /dev/null +++ b/doc/administration/integration/external-issue-tracker.md @@ -0,0 +1,30 @@ +# External issue tracker + +GitLab has a great issue tracker but you can also use an external one such as +Jira or Redmine. Issue trackers are configurable per GitLab project and allow +you to do the following: + +- the **Issues** link on the GitLab project pages takes you to the appropriate + issue index of the external tracker +- clicking **New issue** on the project dashboard creates a new issue on the + external tracker + +## Configuration + +The configuration is done via a project's **Services**. + +### Project Service + +To enable an external issue tracker you must configure the appropriate **Service**. +Visit the links below for details: + +- [Redmine](../project_services/redmine.md) +- [Jira](../project_services/jira.md) + +### Service Template + +To save you the hassle from configuring each project's service individually, +GitLab provides the ability to set Service Templates which can then be +overridden in each project's settings. + +Read more on [Services Templates](../project_services/services_templates.md). diff --git a/doc/administration/integration/facebook.md b/doc/administration/integration/facebook.md new file mode 100644 index 00000000000..77bb75cbfca --- /dev/null +++ b/doc/administration/integration/facebook.md @@ -0,0 +1,97 @@ +# Facebook OAuth2 OmniAuth Provider + +To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. + +1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). + +1. Choose "My Apps" > "Add a New App" + +1. Select the type "Website" + +1. Enter a name for your app. This can be anything. Consider something like "<Organization>'s GitLab" or "<Your Name>'s GitLab" or +something else descriptive. + +1. Choose "Create New Facebook App ID" + +1. Select a Category, for example "Productivity" + +1. Choose "Create App ID" + +1. Enter the address of your GitLab installation at the bottom of the package + + ![Facebook Website URL](img/facebook_website_url.png) + +1. Choose "Next" + +1. Choose "Skip Quick Start" in the upper right corner + +1. Choose "Settings" in the menu on the left + +1. Fill in a contact email for your app + + ![Facebook App Settings](img/facebook_app_settings.png) + +1. Choose "Save Changes" + +1. Choose "Status & Review" in the menu on the left + +1. Change the switch on the right from No to Yes + +1. Choose "Confirm" when prompted to make the app public + +1. Choose "Dashboard" in the menu on the left + +1. Choose "Show" next to the hidden "App Secret" + +1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration. + + ![Facebook API Keys](img/facebook_api_keys.png) + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "facebook", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET" + } + ] + ``` + + For installations from source: + + ``` + - { name: 'facebook', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET' } + ``` + +1. Change 'YOUR_APP_ID' to the API key from Facebook page in step 10. + +1. Change 'YOUR_APP_SECRET' to the API secret from the Facebook page in step 10. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/integration/github.md b/doc/administration/integration/github.md new file mode 100644 index 00000000000..e7497e475c9 --- /dev/null +++ b/doc/administration/integration/github.md @@ -0,0 +1,95 @@ +# Integrate your server with GitHub + +Import projects from GitHub and login to your GitLab instance with your GitHub account. + +To enable the GitHub OmniAuth provider you must register your application with GitHub. +GitHub will generate an application ID and secret key for you to use. + +1. Sign in to GitHub. + +1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. + +1. Select "OAuth applications" in the left menu. + +1. If you already have applications listed, switch to the "Developer applications" tab. + +1. Select "Register new application". + +1. Provide the required details. + - Application name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. + - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' + - Application description: Fill this in if you wish. + - Default authorization callback URL is '${YOUR_DOMAIN}/import/github/callback' +1. Select "Register application". + +1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). + Keep this page open as you continue configuration. + ![GitHub app](img/github_app.png) + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "github", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET", + "url" => "https://github.com/", + "args" => { "scope" => "user:email" } + } + ] + ``` + + For installation from source: + + For GitHub.com: + + ``` + - { name: 'github', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + args: { scope: 'user:email' } } + ``` + + + For GitHub Enterprise: + + ``` + - { name: 'github', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + args: { scope: 'user:email' } } + ``` + + __Replace `https://github.example.com/` with your GitHub URL.__ + +1. Change 'YOUR_APP_ID' to the client ID from the GitHub application page from step 7. + +1. Change 'YOUR_APP_SECRET' to the client secret from the GitHub application page from step 7. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a GitHub icon below the regular sign in form. +Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. +If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/integration/gitlab.md b/doc/administration/integration/gitlab.md new file mode 100644 index 00000000000..b215cc7c609 --- /dev/null +++ b/doc/administration/integration/gitlab.md @@ -0,0 +1,84 @@ +# Integrate your server with GitLab.com + +Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. + +To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. +GitLab.com will generate an application ID and secret key for you to use. + +1. Sign in to GitLab.com + +1. Navigate to your profile settings. + +1. Select "Applications" in the left menu. + +1. Select "New application". + +1. Provide the required details. + - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. + - Redirect URI: + + ``` + http://your-gitlab.example.com/import/gitlab/callback + http://your-gitlab.example.com/users/auth/gitlab/callback + ``` + + The first link is required for the importer and second for the authorization. + +1. Select "Submit". + +1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). + Keep this page open as you continue configuration. + ![GitLab app](img/gitlab_app.png) + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "gitlab", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET", + "args" => { "scope" => "api" } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'gitlab', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + args: { scope: 'api' } } + ``` + +1. Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page. + +1. Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a GitLab.com icon below the regular sign in form. +Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. +If everything goes well the user will be returned to your GitLab instance and will be signed in. diff --git a/doc/administration/integration/gmail_action_buttons_for_gitlab.md b/doc/administration/integration/gmail_action_buttons_for_gitlab.md new file mode 100644 index 00000000000..05a91d9bef9 --- /dev/null +++ b/doc/administration/integration/gmail_action_buttons_for_gitlab.md @@ -0,0 +1,22 @@ +# Gmail actions buttons for GitLab + +GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). + +If correctly setup, emails that require an action will be marked in Gmail. + +![gmail_actions_button.png](img/gmail_action_buttons_for_gitlab.png) + +To get this functioning, you need to be registered with Google. +[See how to register with Google in this document.](https://developers.google.com/gmail/markup/registering-with-google) + +*This process has a lot of steps so make sure that you fulfill all requirements set by Google.* +*Your application will be rejected by Google if you fail to do so.* + +Pay close attention to: + +* Email account used by GitLab to send notification emails needs to have "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". +* "A very very low rate of spam complaints from users." +* Emails must be authenticated via DKIM or SPF +* Before sending the final form("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. + +You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/1517). diff --git a/doc/administration/integration/google.md b/doc/administration/integration/google.md new file mode 100644 index 00000000000..82978b68a34 --- /dev/null +++ b/doc/administration/integration/google.md @@ -0,0 +1,89 @@ +# Google OAuth2 OmniAuth Provider + +To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use. + +1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. + +1. Select "Create Project". + +1. Provide the project information + - Project name: 'GitLab' works just fine here. + - Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. +1. Refresh the page. You should now see your new project in the list. Click on the project. + +1. Select the "Google APIs" tab in the Overview. + +1. Select and enable the following Google APIs - listed under "Popular APIs" + - Enable `Contacts API` + - Enable `Google+ API` + +1. Select "Credentials" in the submenu. + +1. Select "Create New Client ID". + +1. Fill in the required information + - Application type: "Web Application" + - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. + - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' +1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration. ![Google app](img/google_app.png) + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "google_oauth2", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET", + "args" => { "access_type" => "offline", "approval_prompt" => '' } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'google_oauth2', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + args: { access_type: 'offline', approval_prompt: '' } } + ``` + +1. Change 'YOUR_APP_ID' to the client ID from the Google Developer page from step 10. + +1. Change 'YOUR_APP_SECRET' to the client secret from the Google Developer page from step 10. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. + +## Further Configuration + +This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding. + +At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable. + +1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window). +1. Scroll down until you find "Product Name". Change the product name to something more descriptive. +1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. diff --git a/doc/administration/integration/img/akismet_settings.png b/doc/administration/integration/img/akismet_settings.png new file mode 100644 index 00000000000..ccdd3adb1c5 Binary files /dev/null and b/doc/administration/integration/img/akismet_settings.png differ diff --git a/doc/administration/integration/img/enabled-oauth-sign-in-sources.png b/doc/administration/integration/img/enabled-oauth-sign-in-sources.png new file mode 100644 index 00000000000..95f8bbdcd24 Binary files /dev/null and b/doc/administration/integration/img/enabled-oauth-sign-in-sources.png differ diff --git a/doc/administration/integration/img/facebook_api_keys.png b/doc/administration/integration/img/facebook_api_keys.png new file mode 100644 index 00000000000..d6c44ac0f11 Binary files /dev/null and b/doc/administration/integration/img/facebook_api_keys.png differ diff --git a/doc/administration/integration/img/facebook_app_settings.png b/doc/administration/integration/img/facebook_app_settings.png new file mode 100644 index 00000000000..30dd21e198a Binary files /dev/null and b/doc/administration/integration/img/facebook_app_settings.png differ diff --git a/doc/administration/integration/img/facebook_website_url.png b/doc/administration/integration/img/facebook_website_url.png new file mode 100644 index 00000000000..dc3088bb2fa Binary files /dev/null and b/doc/administration/integration/img/facebook_website_url.png differ diff --git a/doc/administration/integration/img/github_app.png b/doc/administration/integration/img/github_app.png new file mode 100644 index 00000000000..d890345ced9 Binary files /dev/null and b/doc/administration/integration/img/github_app.png differ diff --git a/doc/administration/integration/img/gitlab_app.png b/doc/administration/integration/img/gitlab_app.png new file mode 100644 index 00000000000..3f9391a821b Binary files /dev/null and b/doc/administration/integration/img/gitlab_app.png differ diff --git a/doc/administration/integration/img/gmail_action_buttons_for_gitlab.png b/doc/administration/integration/img/gmail_action_buttons_for_gitlab.png new file mode 100644 index 00000000000..b08f54d137b Binary files /dev/null and b/doc/administration/integration/img/gmail_action_buttons_for_gitlab.png differ diff --git a/doc/administration/integration/img/google_app.png b/doc/administration/integration/img/google_app.png new file mode 100644 index 00000000000..5a62ad35009 Binary files /dev/null and b/doc/administration/integration/img/google_app.png differ diff --git a/doc/administration/integration/img/oauth_provider_admin_application.png b/doc/administration/integration/img/oauth_provider_admin_application.png new file mode 100644 index 00000000000..a2d8e14c120 Binary files /dev/null and b/doc/administration/integration/img/oauth_provider_admin_application.png differ diff --git a/doc/administration/integration/img/oauth_provider_application_form.png b/doc/administration/integration/img/oauth_provider_application_form.png new file mode 100644 index 00000000000..3a676b22393 Binary files /dev/null and b/doc/administration/integration/img/oauth_provider_application_form.png differ diff --git a/doc/administration/integration/img/oauth_provider_application_id_secret.png b/doc/administration/integration/img/oauth_provider_application_id_secret.png new file mode 100644 index 00000000000..6d68df001af Binary files /dev/null and b/doc/administration/integration/img/oauth_provider_application_id_secret.png differ diff --git a/doc/administration/integration/img/oauth_provider_authorized_application.png b/doc/administration/integration/img/oauth_provider_authorized_application.png new file mode 100644 index 00000000000..efc3b807d71 Binary files /dev/null and b/doc/administration/integration/img/oauth_provider_authorized_application.png differ diff --git a/doc/administration/integration/img/oauth_provider_user_wide_applications.png b/doc/administration/integration/img/oauth_provider_user_wide_applications.png new file mode 100644 index 00000000000..45ad8a6d468 Binary files /dev/null and b/doc/administration/integration/img/oauth_provider_user_wide_applications.png differ diff --git a/doc/administration/integration/img/twitter_app_api_keys.png b/doc/administration/integration/img/twitter_app_api_keys.png new file mode 100644 index 00000000000..1076337172a Binary files /dev/null and b/doc/administration/integration/img/twitter_app_api_keys.png differ diff --git a/doc/administration/integration/img/twitter_app_details.png b/doc/administration/integration/img/twitter_app_details.png new file mode 100644 index 00000000000..b95e8af8a74 Binary files /dev/null and b/doc/administration/integration/img/twitter_app_details.png differ diff --git a/doc/administration/integration/jira.md b/doc/administration/integration/jira.md new file mode 100644 index 00000000000..78aa6634116 --- /dev/null +++ b/doc/administration/integration/jira.md @@ -0,0 +1,3 @@ +# GitLab JIRA integration + +This document was moved under [project_services/jira](../project_services/jira.md). diff --git a/doc/administration/integration/ldap.md b/doc/administration/integration/ldap.md new file mode 100644 index 00000000000..30f0c15dacc --- /dev/null +++ b/doc/administration/integration/ldap.md @@ -0,0 +1,3 @@ +# GitLab LDAP integration + +This document was moved under [`administration/auth/ldap`](../administration/auth/ldap.md). diff --git a/doc/administration/integration/oauth_provider.md b/doc/administration/integration/oauth_provider.md new file mode 100644 index 00000000000..5f8bb57365c --- /dev/null +++ b/doc/administration/integration/oauth_provider.md @@ -0,0 +1,80 @@ +# GitLab as OAuth2 authentication service provider + +This document is about using GitLab as an OAuth authentication service provider +to sign in to other services. + +If you want to use other OAuth authentication service providers to sign in to +GitLab, please see the [OAuth2 client documentation](../api/oauth2.md). + +## Introduction to OAuth + +[OAuth] provides to client applications a 'secure delegated access' to server +resources on behalf of a resource owner. In fact, OAuth allows an authorization +server to issue access tokens to third-party clients with the approval of the +resource owner, or the end-user. + +OAuth is mostly used as a Single Sign-On service (SSO), but you can find a +lot of different uses for this functionality. For example, you can allow users +to sign in to your application with their GitLab.com account, or GitLab.com +can be used for authentication to your GitLab instance +(see [GitLab OmniAuth](gitlab.md)). + +The 'GitLab Importer' feature is also using the OAuth protocol to give access +to repositories without sharing user credentials to your GitLab.com account. + +--- + +GitLab supports two ways of adding a new OAuth2 application to an instance. You +can either add an application as a regular user or add it in the admin area. +What this means is that GitLab can actually have instance-wide and a user-wide +applications. There is no difference between them except for the different +permission levels they are set (user/admin). + +## Adding an application through the profile + +In order to add a new application via your profile, navigate to +**Profile Settings > Applications** and select **New Application**. + +![New OAuth application](img/oauth_provider_user_wide_applications.png) + +--- + +In the application form, enter a **Name** (arbitrary), and make sure to set up +correctly the **Redirect URI** which is the URL where users will be sent after +they authorize with GitLab. + +![New OAuth application form](img/oauth_provider_application_form.png) + +--- + +When you hit **Submit** you will be provided with the application ID and +the application secret which you can then use with your application that +connects to GitLab. + +![OAuth application ID and secret](img/oauth_provider_application_id_secret.png) + +--- + +## OAuth applications in the admin area + +To create an application that does not belong to a certain user, you can create +it from the admin area. + +![OAuth admin_applications](img/oauth_provider_admin_application.png) + +--- + +## Authorized applications + +Every application you authorized to use your GitLab credentials will be shown +in the **Authorized applications** section under **Profile Settings > Applications**. + +![Authorized_applications](img/oauth_provider_authorized_application.png) + +--- + +As you can see, the default scope `api` is used, which is the only scope that +GitLab supports so far. At any time you can revoke any access by just clicking +**Revoke**. + +[oauth]: http://oauth.net/2/ "OAuth website" diff --git a/doc/administration/integration/omniauth.md b/doc/administration/integration/omniauth.md new file mode 100644 index 00000000000..820f40f81a9 --- /dev/null +++ b/doc/administration/integration/omniauth.md @@ -0,0 +1,208 @@ +# OmniAuth + +GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and +other popular services. + +Configuring OmniAuth does not prevent standard GitLab authentication or LDAP +(if configured) from continuing to work. Users can choose to sign in using any +of the configured mechanisms. + +- [Initial OmniAuth Configuration](#initial-omniauth-configuration) +- [Supported Providers](#supported-providers) +- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) +- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) +- [Enable or disable Sign In with an OmniAuth provider without disabling import sources](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources) + +## Supported Providers + +This is a list of the current supported OmniAuth providers. Before proceeding +on each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +- [GitHub](github.md) +- [Bitbucket](bitbucket.md) +- [GitLab.com](gitlab.md) +- [Google](google.md) +- [Facebook](facebook.md) +- [Twitter](twitter.md) +- [Shibboleth](shibboleth.md) +- [SAML](saml.md) +- [Crowd](crowd.md) +- [Azure](azure.md) +- [Auth0](auth0.md) + +## Initial OmniAuth Configuration + +Before configuring individual OmniAuth providers there are a few global settings +that are in common for all providers that we need to consider. + +- Omniauth needs to be enabled, see details below for example. +- `allow_single_sign_on` allows you to specify the providers you want to allow to + automatically create an account. It defaults to `false`. If `false` users must + be created manually or they will not be able to sign in via OmniAuth. +- `block_auto_created_users` defaults to `true`. If `true` auto created users will + be blocked by default and will have to be unblocked by an administrator before + they are able to sign in. + +>**Note:** +If you set `block_auto_created_users` to `false`, make sure to only +define providers under `allow_single_sign_on` that you are able to control, like +SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +the Internet will be able to successfully sign in to your GitLab without +administrative approval. + +To change these settings: + +* **For omnibus package** + + Open the configuration file: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + and change: + + ```ruby + gitlab_rails['omniauth_enabled'] = true + + # CAUTION! + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. + # User accounts will be created automatically when authentication was successful. + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] + gitlab_rails['omniauth_block_auto_created_users'] = true + ``` + +* **For installations from source** + + Open the configuration file: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + + and change the following section: + + ```yaml + ## OmniAuth settings + omniauth: + # Allow login via Twitter, Google, etc. using OmniAuth providers + enabled: true + + # CAUTION! + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. + # User accounts will be created automatically when authentication was successful. + allow_single_sign_on: ["saml", "twitter"] + + # Locks down those users until they have been cleared by the admin (default: true). + block_auto_created_users: true + ``` + +Now we can choose one or more of the Supported Providers listed above to continue +the configuration process. + +## Enable OmniAuth for an Existing User + +Existing users can enable OmniAuth for specific providers after the account is +created. For example, if the user originally signed in with LDAP, an OmniAuth +provider such as Twitter can be enabled. Follow the steps below to enable an +OmniAuth provider for an existing user. + +1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. +1. Go to profile settings (the silhouette icon in the top right corner). +1. Select the "Account" tab. +1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. +1. The user will be redirected to the provider. Once the user authorized GitLab + they will be redirected back to GitLab. + +The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. + +## Configure OmniAuth Providers as External + +>**Note:** +This setting was introduced with version 8.7 of GitLab + +You can define which OmniAuth providers you want to be `external` so that all users +creating accounts via these providers will not be able to have access to internal +projects. You will need to use the full name of the provider, like `google_oauth2` +for Google. Refer to the examples for the full names of the supported providers. + +**For Omnibus installations** + +```ruby + gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] +``` + +**For installations from source** + +```yaml + omniauth: + external_providers: ['twitter', 'google_oauth2'] +``` + +## Using Custom Omniauth Providers + +>**Note:** +The following information only applies for installations from source. + +GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships +with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that +is not enough and you need to integrate with other authentication solutions. For +these cases you can use the Omniauth provider. + +### Steps + +These steps are fairly general and you will need to figure out the exact details +from the Omniauth provider's documentation. + +- Stop GitLab: + + sudo service gitlab stop + +- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile): + + gem "omniauth-your-auth-provider" + +- If you're using MySQL, install the new Omniauth provider gem by running the following command: + + sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment + +- If you're using PostgreSQL, install the new Omniauth provider gem by running the following command: + + sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment + + > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. + +- Start GitLab: + + sudo service gitlab start + +### Examples + +If you have successfully set up a provider that is not shipped with GitLab itself, +please let us know. + +You can help others by reporting successful configurations and probably share a +few insights or provide warnings for common errors or pitfalls by sharing your +experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). + +While we can't officially support every possible authentication mechanism out there, +we'd like to at least help those with specific needs. + +## Enable or disable Sign In with an OmniAuth provider without disabling import sources + +>**Note:** +This setting was introduced with version 8.8 of GitLab. + +Administrators are able to enable or disable Sign In via some OmniAuth providers. + +>**Note:** +By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. + +In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. + +![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png) diff --git a/doc/administration/integration/recaptcha.md b/doc/administration/integration/recaptcha.md new file mode 100644 index 00000000000..a301d1a613c --- /dev/null +++ b/doc/administration/integration/recaptcha.md @@ -0,0 +1,23 @@ +# reCAPTCHA + +GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) +to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page +to confirm that a real user, not a bot, is attempting to create an account. + +## Configuration + +To use reCAPTCHA, first you must create a site and private key. + +1. Go to the URL: https://www.google.com/recaptcha/admin + +2. Fill out the form necessary to obtain reCAPTCHA keys. + +3. Login to your GitLab server, with administrator credentials. + +4. Go to Applications Settings on Admin Area (`admin/application_settings`) + +5. Fill all recaptcha fields with keys from previous steps + +6. Check the `Enable reCAPTCHA` checkbox + +7. Save the configuration. diff --git a/doc/administration/integration/saml.md b/doc/administration/integration/saml.md new file mode 100644 index 00000000000..8a7205caaa4 --- /dev/null +++ b/doc/administration/integration/saml.md @@ -0,0 +1,309 @@ +# SAML OmniAuth Provider + +GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows +GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as +Microsoft ADFS to authenticate users. + +First configure SAML 2.0 support in GitLab, then register the GitLab application +in your SAML IdP: + +1. Make sure GitLab is configured with HTTPS. + See [Using HTTPS](../install/installation.md#using-https) for instructions. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. To allow your users to use SAML to sign up without having to manually create + an account first, don't forget to add the following values to your configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + + For installations from source: + + ```yaml + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. You can also automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + For installations from source: + + ```yaml + auto_link_saml_user: true + ``` + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + }, + label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + } + ] + ``` + + For installations from source: + + ```yaml + - { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + }, + label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + } + ``` + +1. Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint + of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab + installation to generate the correct value). + +1. Change the values of `idp_cert_fingerprint`, `idp_sso_target_url`, + `name_identifier_format` to match your IdP. Check + [the omniauth-saml documentation](https://github.com/omniauth/omniauth-saml) + for details on these options. + +1. Change the value of `issuer` to a unique name, which will identify the application + to the IdP. + +1. Restart GitLab for the changes to take effect. + +1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified + in `issuer`. + +To ease configuration, most IdP accept a metadata URL for the application to provide +configuration information to the IdP. To build the metadata URL for GitLab, append +`users/auth/saml/metadata` to the HTTPS URL of your GitLab installation, for instance: + ``` + https://gitlab.example.com/users/auth/saml/metadata + ``` + +At a minimum the IdP *must* provide a claim containing the user's email address, using +claim name `email` or `mail`. The email will be used to automatically generate the GitLab +username. GitLab will also use claims with name `name`, `first_name`, `last_name` +(see [the omniauth-saml gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) +for supported claims). + +On the sign in page there should now be a SAML button below the regular sign in form. +Click the icon to begin the authentication process. If everything goes well the user +will be returned to GitLab and will be signed in. + +## External Groups + +>**Note:** +This setting is only available on GitLab 8.7 and above. + +SAML login includes support for external groups. You can define in the SAML +settings which groups, to which your users belong in your IdP, you wish to be +marked as [external](../permissions/permissions.md). + +### Requirements + +First you need to tell GitLab where to look for group information. For this you +need to make sure that your IdP server sends a specific `AttributeStament` along +with the regular SAML response. Here is an example: + +```xml + + + SecurityGroup + Developers + Designers + + +``` + +The name of the attribute can be anything you like, but it must contain the groups +to which a user belongs. In order to tell GitLab where to find these groups, you need +to add a `groups_attribute:` element to your SAML settings. You will also need to +tell GitLab which groups are external via the `external_groups:` element: + +```yaml +{ name: 'saml', + label: 'Our SAML Provider', + groups_attribute: 'Groups', + external_groups: ['Freelancers', 'Interns'], + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + } } +``` + +## Customization + +### `auto_sign_in_with_provider` + +You can add this setting to your GitLab configuration to automatically redirect you +to your SAML server for authentication, thus removing the need to click a button +before actually signing in. + +For omnibus package: + +```ruby +gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' +``` + +For installations from source: + +```yaml +omniauth: + auto_sign_in_with_provider: saml +``` + +Please keep in mind that every sign in attempt will be redirected to the SAML server, +so you will not be able to sign in using local credentials. Make sure that at least one +of the SAML users has admin permissions. + +### `attribute_statements` + +>**Note:** +This setting is only available on GitLab 8.6 and above. +This setting should only be used to map attributes that are part of the +OmniAuth info hash schema. + +`attribute_statements` is used to map Attribute Names in a SAMLResponse to entries +in the OmniAuth [info hash](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). + +For example, if your SAMLResponse contains an Attribute called 'EmailAddress', +specify `{ email: ['EmailAddress'] }` to map the Attribute to the +corresponding key in the info hash. URI-named Attributes are also supported, e.g. +`{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. + +This setting allows you tell GitLab where to look for certain attributes required +to create an account. Like mentioned above, if your IdP sends the user's email +address as `EmailAddress` instead of `email`, let GitLab know by setting it on +your configuration: + +```yaml +args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', + attribute_statements: { email: ['EmailAddress'] } +} +``` + +### `allowed_clock_drift` + +The clock of the Identity Provider may drift slightly ahead of your system clocks. +To allow for a small amount of clock drift you can use `allowed_clock_drift` within +your settings. Its value must be given in a number (and/or fraction) of seconds. +The value given is added to the current time at which the response is validated. + +```yaml +args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', + attribute_statements: { email: ['EmailAddress'] }, + allowed_clock_drift: 1 # for one second clock drift +} +``` + +## Troubleshooting + +### 500 error after login + +If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, +this likely indicates that GitLab could not get the email address for the SAML user. + +Make sure the IdP provides a claim containing the user's email address, using claim name +`email` or `mail`. + +### Redirect back to login screen with no evident error + +If after signing in into your SAML server you are redirected back to the sign in page and +no error is displayed, check your `production.log` file. It will most likely contain the +message `Can't verify CSRF token authenticity`. This means that there is an error during +the SAML request, but this error never reaches GitLab due to the CSRF check. + +To bypass this you can add `skip_before_action :verify_authenticity_token` to the +`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab, +where it can then be seen in the usual logs, or as a flash message in the login +screen. + +That file is located at `/opt/gitlab/embedded/service/gitlab-rails/app/controllers` +for Omnibus installations and by default on `/home/git/gitlab/app/controllers` for +installations from source. + +### Invalid audience + +This error means that the IdP doesn't recognize GitLab as a valid sender and +receiver of SAML requests. Make sure to add the GitLab callback URL to the approved +audiences of the IdP server. + +### Missing claims + +The IdP server needs to pass certain information in order for GitLab to either +create an account, or match the login information to an existing account. `email` +is the minimum amount of information that needs to be passed. If the IdP server +is not providing this information, all SAML requests will fail. + +Make sure this information is provided. + +### Key validation error, Digest mismatch or Fingerprint mismatch + +These errors all come from a similar place, the SAML certificate. SAML requests +need to be validated using a fingerprint, a certificate or a validator. + +For this you need take the following into account: + +- If no certificate is provided in the settings, a fingerprint or fingerprint + validator needs to be provided and the response from the server must contain + a certificate (``) +- If a certificate is provided in the settings, it is no longer necessary for + the request to contain one. In this case the fingerprint or fingerprint + validators are optional + +Make sure that one of the above described scenarios is valid, or the requests will +fail with one of the mentioned errors. \ No newline at end of file diff --git a/doc/administration/integration/shibboleth.md b/doc/administration/integration/shibboleth.md new file mode 100644 index 00000000000..b6b2d4e5e88 --- /dev/null +++ b/doc/administration/integration/shibboleth.md @@ -0,0 +1,125 @@ +# Shibboleth OmniAuth Provider + +This documentation is for enabling shibboleth with omnibus-gitlab package. + +In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. + + +To enable the Shibboleth OmniAuth provider you must: + +1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. +Check https://wiki.shibboleth.net/ for more info. + +1. You can find Apache config in gitlab-recipes (https://github.com/gitlabhq/gitlab-recipes/blob/master/web-server/apache/gitlab-ssl.conf) + +Following changes are needed to enable shibboleth: + +protect omniauth-shibboleth callback URL: +``` + + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibUseHeaders On + require valid-user + + + Alias /shibboleth-sp /usr/share/shibboleth + + Satisfy any + + + + SetHandler shib + +``` +exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibboleth.sso" and "RewriteCond %{REQUEST_URI} !/shibboleth-sp", config should look like this: +``` + # Apache equivalent of Nginx try files + RewriteEngine on + RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_URI} !/Shibboleth.sso + RewriteCond %{REQUEST_URI} !/shibboleth-sp + RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] + RequestHeader set X_FORWARDED_PROTO 'https' +``` + +1. Edit /etc/gitlab/gitlab.rb configuration file, your shibboleth attributes should be in form of "HTTP_ATTRIBUTE" and you should addjust them to your need and environment. Add any other configuration you need. + +File should look like this: +``` +external_url 'https://gitlab.example.com' +gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' + +# disable Nginx +nginx['enable'] = false + +gitlab_rails['omniauth_allow_single_sign_on'] = true +gitlab_rails['omniauth_block_auto_created_users'] = false +gitlab_rails['omniauth_enabled'] = true +gitlab_rails['omniauth_providers'] = [ + { + "name" => 'shibboleth', + "args" => { + "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", + "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", + "uid_field" => 'HTTP_EPPN', + "name_field" => 'HTTP_CN', + "info_fields" => { "email" => 'HTTP_MAIL'} + } + } +] + +``` +1. Save changes and reconfigure gitlab: +``` +sudo gitlab-ctl reconfigure +``` + +On the sign in page there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (Depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. + +## Apache 2.4 / GitLab 8.6 update +The order of the first 2 Location directives is important. If they are reversed, +you will not get a shibboleth session! + +``` + + Require all granted + ProxyPassReverse http://127.0.0.1:8181 + ProxyPassReverse http://YOUR_SERVER_FQDN/ + + + + AuthType shibboleth + ShibRequestSetting requireSession 1 + ShibUseHeaders On + Require shib-session + + + Alias /shibboleth-sp /usr/share/shibboleth + + + Require all granted + + + + SetHandler shib + + + RewriteEngine on + + #Don't escape encoded characters in api requests + RewriteCond %{REQUEST_URI} ^/api/v3/.* + RewriteCond %{REQUEST_URI} !/Shibboleth.sso + RewriteCond %{REQUEST_URI} !/shibboleth-sp + RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA,NE] + + #Forward all requests to gitlab-workhorse except existing files + RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR] + RewriteCond %{REQUEST_URI} ^/uploads/.* + RewriteCond %{REQUEST_URI} !/Shibboleth.sso + RewriteCond %{REQUEST_URI} !/shibboleth-sp + RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA] + + RequestHeader set X_FORWARDED_PROTO 'https' + RequestHeader set X-Forwarded-Ssl on +``` \ No newline at end of file diff --git a/doc/administration/integration/slack.md b/doc/administration/integration/slack.md new file mode 100644 index 00000000000..f6ba80f46d5 --- /dev/null +++ b/doc/administration/integration/slack.md @@ -0,0 +1,41 @@ +# Slack integration + +## On Slack + +To enable Slack integration you must create an Incoming WebHooks integration on Slack: + +1. [Sign in to Slack](https://slack.com/signin) + +1. Visit [Incoming WebHooks](https://my.slack.com/services/new/incoming-webhook/) + +1. Choose the channel name you want to send notifications to. + +1. Click **Add Incoming WebHooks Integration** + - Optional step; You can change bot's name and avatar by clicking modifying the bot name or avatar under **Integration Settings**. + +1. Copy the **Webhook URL**, we'll need this later for GitLab. + + +## On GitLab + +After Slack is ready we need to setup GitLab. Here are the steps to achieve this. + +1. Sign in to GitLab + +1. Pick the repository you want. + +1. Navigate to Settings -> Services -> Slack + +1. Pick the triggers you want to activate + +1. Fill in your Slack details + - Webhook: Paste the Webhook URL from the step above + - Username: Fill this in if you want to change the username of the bot + - Channel: Fill this in if you want to change the channel where the messages will be posted + - Mark it as active + +1. Save your settings + +Have fun :) + +*P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them.* diff --git a/doc/administration/integration/twitter.md b/doc/administration/integration/twitter.md new file mode 100644 index 00000000000..4769f26b259 --- /dev/null +++ b/doc/administration/integration/twitter.md @@ -0,0 +1,79 @@ +# Twitter OAuth2 OmniAuth Provider + +To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. + +1. Sign in to [Twitter Application Management](https://apps.twitter.com/). + +1. Select "Create new app" + +1. Fill in the application details. + - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or + something else descriptive. + - Description: Create a description. + - Website: The URL to your GitLab installation. 'https://gitlab.example.com' + - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' + - Agree to the "Developer Agreement". + + ![Twitter App Details](img/twitter_app_details.png) +1. Select "Create your Twitter application." + +1. Select the "Settings" tab. + +1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter." + +1. Select "Update settings" at the bottom to save changes. + +1. Select the "Keys and Access Tokens" tab. + +1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. + + ![Twitter app](img/twitter_app_api_keys.png) + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "twitter", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET" + } + ] + ``` + + For installations from source: + + ``` + - { name: 'twitter', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET' } + ``` + +1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11. + +1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/administration/logs/logs.md b/doc/administration/logs/logs.md new file mode 100644 index 00000000000..a2eca62d691 --- /dev/null +++ b/doc/administration/logs/logs.md @@ -0,0 +1 @@ +This document was moved to [administration/logs.md](../administration/logs.md). diff --git a/doc/administration/migrate_ci_to_ce/README.md b/doc/administration/migrate_ci_to_ce/README.md new file mode 100644 index 00000000000..8f9ef054949 --- /dev/null +++ b/doc/administration/migrate_ci_to_ce/README.md @@ -0,0 +1,435 @@ +## Migrate GitLab CI to GitLab CE or EE + +Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise +Edition (EE), GitLab CI is no longer its own application, but is instead built +into the CE and EE applications. + +This guide will detail the process of migrating your CI installation and data +into your GitLab CE or EE installation. **You can only migrate CI data from +GitLab CI 8.0 to GitLab 8.0; migrating between other versions (e.g.7.14 to 8.1) +is not possible.** + +We recommend that you read through the entire migration process in this +document before beginning. + +### Overview + +In this document we assume you have a GitLab server and a GitLab CI server. It +does not matter if these are the same machine. + +The migration consists of three parts: updating GitLab and GitLab CI, moving +data, and redirecting traffic. + +Please note that CI builds triggered on your GitLab server in the time between +updating to 8.0 and finishing the migration will be lost. Your GitLab server +can be online for most of the procedure; the only GitLab downtime (if any) is +during the upgrade to 8.0. Your CI service will be offline from the moment you +upgrade to 8.0 until you finish the migration procedure. + +### Before upgrading + +If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**: + +```bash +mv /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/gitlab-ci/builds.$(date +%s) +``` + +run `sudo gitlab-ctl reconfigure` and you can reach CI at `gitlab.example.com/ci`. + +If you want to migrate your existing data, continue reading. + +#### 0. Updating Omnibus from versions prior to 7.13 + +If you are updating from older versions you should first update to 7.14 and then to 8.0. +Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting). + +#### 1. Verify that backups work + +Make sure that the backup script on both servers can connect to the database. + +``` +# On your CI server: +# Omnibus +sudo chown gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds +sudo gitlab-ci-rake backup:create + +# Source +cd /home/gitlab_ci/gitlab-ci +sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production +``` + +Also check on your GitLab server. + +``` +# On your GitLab server: +# Omnibus +sudo gitlab-rake gitlab:backup:create SKIP=repositories,uploads + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=repositories,uploads +``` + +If this fails you need to fix it before upgrading to 8.0. Also see +https://about.gitlab.com/getting-help/ + +#### 2. Check source and target database types + +Check what databases you use on your GitLab server and your CI server. + Look for the 'adapter:' line. If your CI server and your GitLab server use +the same database adapter no special care is needed. If your CI server uses +MySQL and your GitLab server uses PostgreSQL you need to pass a special option +during the 'Moving data' part. **If your CI server uses PostgreSQL and your +GitLab server uses MySQL you cannot migrate your CI data to GitLab 8.0.** + +``` +# On your CI server: +# Omnibus +sudo gitlab-ci-rake env:info + +# Source +cd /home/gitlab_ci/gitlab-ci +sudo -u gitlab_ci -H bundle exec rake env:info RAILS_ENV=production +``` + +``` +# On your GitLab server: +# Omnibus +sudo gitlab-rake gitlab:env:info + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +#### 3. Storage planning + +Decide where to store CI build traces on GitLab server. GitLab CI uses + files on disk to store CI build traces. The default path for these build +traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or +`/home/git/gitlab/builds` (Source). If you are storing your repository data in +a special location, or if you are using NFS, you should make sure that you +store build traces on the same storage as your Git repositories. + +### I. Upgrading + +From this point on, GitLab CI will be unavailable for your end users. + +#### 1. Upgrade GitLab to 8.0 + +First upgrade your GitLab server to version 8.0: +https://about.gitlab.com/update/ + +#### 2. Disable CI on the GitLab server during the migration + +After you update, go to the admin panel and temporarily disable CI. As + an administrator, go to **Admin Area** -> **Settings**, and under +**Continuous Integration** uncheck **Disable to prevent CI usage until rake +ci:migrate is run (8.0 only)**. + +#### 3. CI settings are now in GitLab + +If you want to use custom CI settings (e.g. change where builds are + stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or +`/home/git/gitlab/config/gitlab.yml` (Source). + +#### 4. Upgrade GitLab CI to 8.0 + +Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages, + this may have already happened when you upgraded GitLab to 8.0. + +#### 5. Disable GitLab CI on the CI server + +Disable GitLab CI after upgrading to 8.0. + +``` +# On your CI server: +# Omnibus +sudo gitlab-ctl stop ci-unicorn +sudo gitlab-ctl stop ci-sidekiq + +# Source +sudo service gitlab_ci stop +cd /home/gitlab_ci/gitlab-ci +sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production +``` + +### II. Moving data + +#### 1. Database encryption key + +Move the database encryption key from your CI server to your GitLab + server. The command below will show you what you need to copy-paste to your +GitLab server. On Omnibus GitLab servers you will have to add a line to +`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you will have +to replace the contents of `/home/git/gitlab/config/secrets.yml`. + +``` +# On your CI server: +# Omnibus +sudo gitlab-ci-rake backup:show_secrets + +# Source +cd /home/gitlab_ci/gitlab-ci +sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production +``` + +#### 2. SQL data and build traces + +Create your final CI data export. If you are converting from MySQL to + PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When +the command finishes it will print the path to your data export archive; you +will need this file later. + +``` +# On your CI server: +# Omnibus +sudo chown gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds +sudo gitlab-ci-rake backup:create + +# Source +cd /home/gitlab_ci/gitlab-ci +sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production +``` + +#### 3. Copy data to the GitLab server + +If you were running GitLab and GitLab CI on the same server you can skip this +step. + +Copy your CI data archive to your GitLab server. There are many ways to do +this, below we use SSH agent forwarding and 'scp', which will be easy and fast +for most setups. You can also copy the data archive first from the CI server to +your laptop and then from your laptop to the GitLab server. + +``` +# Start from your laptop +ssh -A ci_admin@ci_server.example +# Now on the CI server +scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~ +``` + +#### 4. Move data to the GitLab backups folder + +Make the CI data archive discoverable for GitLab. We assume below that you +store backups in the default path, adjust the command if necessary. + +``` +# On your GitLab server: +# Omnibus +sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/ + +# Source +sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ +``` + +#### 5. Import the CI data into GitLab. + +This step will delete any existing CI data on your GitLab server. There should +be no CI data yet because you turned CI on the GitLab server off earlier. + +``` +# On your GitLab server: +# Omnibus +sudo chown git:git /var/opt/gitlab/gitlab-ci/builds +sudo gitlab-rake ci:migrate + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production +``` + +#### 6. Restart GitLab + +``` +# On your GitLab server: +# Omnibus +sudo gitlab-ctl hup unicorn +sudo gitlab-ctl restart sidekiq + +# Source +sudo service gitlab reload +``` + +### III. Redirecting traffic + +If you were running GitLab CI with Omnibus packages and you were using the +internal NGINX configuration your CI service should now be available both at +`ci.example.com` (the old address) and `gitlab.example.com/ci`. **You are done!** + +If you installed GitLab CI from source we now need to configure a redirect in +NGINX so that existing CI runners can keep using the old CI server address, and +so that existing links to your CI server keep working. + +#### 1. Update Nginx configuration + +To ensure that your existing CI runners are able to communicate with the +migrated installation, and that existing build triggers still work, you'll need +to update your Nginx configuration to redirect requests for the old locations to +the new ones. + +Edit `/etc/nginx/sites-available/gitlab_ci` and paste: + +```nginx +# GITLAB CI +server { + listen 80 default_server; # e.g., listen 192.168.1.1:80; + server_name YOUR_CI_SERVER_FQDN; # e.g., server_name source.example.com; + + access_log /var/log/nginx/gitlab_ci_access.log; + error_log /var/log/nginx/gitlab_ci_error.log; + + # expose API to fix runners + location /api { + proxy_read_timeout 300; + proxy_connect_timeout 300; + proxy_redirect off; + proxy_set_header X-Real-IP $remote_addr; + + # You need to specify your DNS servers that are able to resolve YOUR_GITLAB_SERVER_FQDN + resolver 8.8.8.8 8.8.4.4; + proxy_pass $scheme://YOUR_GITLAB_SERVER_FQDN/ci$request_uri; + } + + # redirect all other CI requests + location / { + return 301 $scheme://YOUR_GITLAB_SERVER_FQDN/ci$request_uri; + } + + # adjust this to match the largest build log your runners might submit, + # set to 0 to disable limit + client_max_body_size 10m; +} +``` + +Make sure you substitute these placeholder values with your real ones: + +1. `YOUR_CI_SERVER_FQDN`: The existing public-facing address of your GitLab CI + install (e.g., `ci.gitlab.com`). +1. `YOUR_GITLAB_SERVER_FQDN`: The current public-facing address of your GitLab + CE (or EE) install (e.g., `gitlab.com`). + +**Make sure not to remove the `/ci$request_uri` part. This is required to +properly forward the requests.** + +You should also make sure that you can: + +1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server. +1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server. + +#### 2. Check Nginx configuration + + sudo nginx -t + +#### 3. Restart Nginx + + sudo /etc/init.d/nginx restart + +#### Restore from backup + +If something went wrong and you need to restore a backup, consult the [Backup +restoration](../raketasks/backup_restore.md) guide. + +### Troubleshooting + +#### show:secrets problem (Omnibus-only) +If you see errors like this: +``` +Missing `secret_key_base` or `db_key_base` for 'production' environment. The secrets will be generated and stored in `config/secrets.yml` +rake aborted! +Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml +``` + +This can happen if you are updating from versions prior to 7.13 straight to 8.0. +The fix for this is to update to Omnibus 7.14 first and then update it to 8.0. + +#### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds +To fix that issue you have to change builds/ folder permission before doing final backup: +``` +sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds +``` + +Then before executing `ci:migrate` you need to fix builds folder permission: +``` +sudo chown git:git /var/opt/gitlab/gitlab-ci/builds +``` + +#### Problems when importing CI database to GitLab +If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences: +``` +ALTER SEQUENCE +ERROR: relation "ci_builds_id_seq" does not exist +ERROR: relation "ci_commits_id_seq" does not exist +ERROR: relation "ci_events_id_seq" does not exist +ERROR: relation "ci_jobs_id_seq" does not exist +ERROR: relation "ci_projects_id_seq" does not exist +ERROR: relation "ci_runner_projects_id_seq" does not exist +ERROR: relation "ci_runners_id_seq" does not exist +ERROR: relation "ci_services_id_seq" does not exist +ERROR: relation "ci_taggings_id_seq" does not exist +ERROR: relation "ci_tags_id_seq" does not exist +CREATE TABLE +``` + +To fix that you need to apply this SQL statement before doing final backup: +``` +# Omnibus +gitlab-ci-rails dbconsole <**Note:** This feature was [introduced][ce-3888] in GitLab 8.8. + +GitLab provides a health check endpoint for uptime monitoring on the `health_check` web +endpoint. The health check reports on the overall system status based on the status of +the database connection, the state of the database migrations, and the ability to write +and access the cache. This endpoint can be provided to uptime monitoring services like +[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. + +## Access Token + +An access token needs to be provided while accessing the health check endpoint. The current +accepted token can be found on the `admin/health_check` page of your GitLab instance. + +![access token](img/health_check_token.png) + +The access token can be passed as a URL parameter: + +``` +https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN +``` + +or as an HTTP header: + +```bash +curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json +``` + +## Using the Endpoint + +Once you have the access token, health information can be retrieved as plain text, JSON, +or XML using the `health_check` endpoint: + +- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN` + +You can also ask for the status of specific services: + +- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN` +- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN` + +For example, the JSON output of the following health check: + +```bash +curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json +``` + +would be like: + +``` +{"healthy":true,"message":"success"} +``` + +## Status + +On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint +will return a valid successful HTTP status code, and a `success` message. Ideally your +uptime monitoring should look for the success message. + +[ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888 +[pingdom]: https://www.pingdom.com +[nagios-health]: https://nagios-plugins.org/doc/man/check_http.html +[newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring diff --git a/doc/administration/monitoring/img/health_check_token.png b/doc/administration/monitoring/img/health_check_token.png new file mode 100644 index 00000000000..2daf8606b00 Binary files /dev/null and b/doc/administration/monitoring/img/health_check_token.png differ diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md new file mode 100644 index 00000000000..771584268d9 --- /dev/null +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -0,0 +1,40 @@ +# GitLab Configuration + +GitLab Performance Monitoring is disabled by default. To enable it and change any of its +settings, navigate to the Admin area in **Settings > Metrics** +(`/admin/application_settings`). + +The minimum required settings you need to set are the InfluxDB host and port. +Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the +changes. + +--- + +![GitLab Performance Monitoring Admin Settings](img/metrics_gitlab_configuration_settings.png) + +--- + +Finally, a restart of all GitLab processes is required for the changes to take +effect: + +```bash +# For Omnibus installations +sudo gitlab-ctl restart + +# For installations from source +sudo service gitlab restart +``` + +## Pending Migrations + +When any migrations are pending, the metrics are disabled until the migrations +have been performed. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [InfluxDB Configuration](influxdb_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) +- [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md new file mode 100644 index 00000000000..168bd85c26a --- /dev/null +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -0,0 +1,149 @@ +# Grafana Configuration + +[Grafana](http://grafana.org/) is a tool that allows you to visualize time +series metrics through graphs and dashboards. It supports several backend +data stores, including InfluxDB. GitLab writes performance data to InfluxDB +and Grafana will allow you to query InfluxDB to display useful graphs. + +For the easiest installation and configuration, install Grafana on the same +server as InfluxDB. For larger installations, you may want to split out these +services. + +## Installation + +Grafana supplies package repositories (Yum/Apt) for easy installation. +See [Grafana installation documentation](http://docs.grafana.org/installation/) +for detailed steps. + +> **Note**: Before starting Grafana for the first time, set the admin user +and password in `/etc/grafana/grafana.ini`. Otherwise, the default password +will be `admin`. + +## Configuration + +Login as the admin user. Expand the menu by clicking the Grafana logo in the +top left corner. Choose 'Data Sources' from the menu. Then, click 'Add new' +in the top bar. + +![Grafana empty data source page](img/grafana_data_source_empty.png) + +Fill in the configuration details for the InfluxDB data source. Save and +Test Connection to ensure the configuration is correct. + +- **Name**: InfluxDB +- **Default**: Checked +- **Type**: InfluxDB 0.9.x (Even if you're using InfluxDB 0.10.x) +- **Url**: https://localhost:8086 (Or the remote URL if you've installed InfluxDB +on a separate server) +- **Access**: proxy +- **Database**: gitlab +- **User**: admin (Or the username configured when setting up InfluxDB) +- **Password**: The password configured when you set up InfluxDB + +![Grafana data source configurations](img/grafana_data_source_configuration.png) + +## Apply retention policies and create continuous queries + +If you intend to import the GitLab provided Grafana dashboards, you will need +to copy and run a set of queries against InfluxDB to create the needed data +sets. + +On the InfluxDB server, run the following command, substituting your InfluxDB +user and password: + +```bash +influxdb --username admin -password super_secret +``` + +This will drop you in to an InfluxDB interactive session. Copy the entire +contents below and paste it in to the interactive session: + +``` +CREATE RETENTION POLICY default ON gitlab DURATION 1h REPLICATION 1 DEFAULT +CREATE RETENTION POLICY downsampled ON gitlab DURATION 7d REPLICATION 1 +CREATE CONTINUOUS QUERY grape_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_git_timings_per_action FROM gitlab."default".rails_method_calls WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY grape_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.grape_markdown_render_timings_overall FROM gitlab."default".rails_transactions WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY grape_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.grape_markdown_render_timings_per_action FROM gitlab."default".rails_transactions WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY grape_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_markdown_timings_overall FROM gitlab."default".rails_method_calls WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND method =~ /^Banzai/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY grape_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_method_call_timings_per_action_and_method FROM gitlab."default".rails_method_calls WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), method, action END; +CREATE CONTINUOUS QUERY grape_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_method_call_timings_per_method FROM gitlab."default".rails_method_calls WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), method END; +CREATE CONTINUOUS QUERY grape_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.grape_transaction_counts_overall FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY grape_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.grape_transaction_counts_per_action FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY grape_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.grape_transaction_timings_overall FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY grape_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.grape_transaction_timings_per_action FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY rails_file_descriptor_counts ON gitlab BEGIN SELECT sum(value) AS count INTO gitlab.downsampled.rails_file_descriptor_counts FROM gitlab."default".rails_file_descriptors GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_gc_counts ON gitlab BEGIN SELECT sum(count) AS total, sum(minor_gc_count) AS minor, sum(major_gc_count) AS major INTO gitlab.downsampled.rails_gc_counts FROM gitlab."default".rails_gc_statistics GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_gc_timings ON gitlab BEGIN SELECT mean(total_time) AS duration_mean, percentile(total_time, 95) AS duration_95th, percentile(total_time, 99) AS duration_99th INTO gitlab.downsampled.rails_gc_timings FROM gitlab."default".rails_gc_statistics GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_git_timings_per_action FROM gitlab."default".rails_method_calls WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY rails_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.rails_markdown_render_timings_overall FROM gitlab."default".rails_transactions WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.rails_markdown_render_timings_per_action FROM gitlab."default".rails_transactions WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY rails_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_markdown_timings_overall FROM gitlab."default".rails_method_calls WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND method =~ /^Banzai/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_memory_usage_overall ON gitlab BEGIN SELECT mean(value) AS memory_mean, percentile(value, 95) AS memory_95th, percentile(value, 99) AS memory_99th INTO gitlab.downsampled.rails_memory_usage_overall FROM gitlab."default".rails_memory_usage GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_method_call_timings_per_action_and_method FROM gitlab."default".rails_method_calls WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), method, action END; +CREATE CONTINUOUS QUERY rails_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_method_call_timings_per_method FROM gitlab."default".rails_method_calls WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), method END; +CREATE CONTINUOUS QUERY rails_object_counts_overall ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.rails_object_counts_overall FROM gitlab."default".rails_object_counts GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_object_counts_per_type ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.rails_object_counts_per_type FROM gitlab."default".rails_object_counts GROUP BY time(1m), type END; +CREATE CONTINUOUS QUERY rails_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.rails_transaction_counts_overall FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.rails_transaction_counts_per_action FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY rails_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.rails_transaction_timings_overall FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY rails_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.rails_transaction_timings_per_action FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY rails_view_timings_per_action_and_view ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_view_timings_per_action_and_view FROM gitlab."default".rails_views WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action, view END; +CREATE CONTINUOUS QUERY sidekiq_file_descriptor_counts ON gitlab BEGIN SELECT sum(value) AS count INTO gitlab.downsampled.sidekiq_file_descriptor_counts FROM gitlab."default".sidekiq_file_descriptors GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_gc_counts ON gitlab BEGIN SELECT sum(count) AS total, sum(minor_gc_count) AS minor, sum(major_gc_count) AS major INTO gitlab.downsampled.sidekiq_gc_counts FROM gitlab."default".sidekiq_gc_statistics GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_gc_timings ON gitlab BEGIN SELECT mean(total_time) AS duration_mean, percentile(total_time, 95) AS duration_95th, percentile(total_time, 99) AS duration_99th INTO gitlab.downsampled.sidekiq_gc_timings FROM gitlab."default".sidekiq_gc_statistics GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_git_timings_per_action FROM gitlab."default".sidekiq_method_calls WHERE method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY sidekiq_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.sidekiq_markdown_render_timings_overall FROM gitlab."default".sidekiq_transactions WHERE (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.sidekiq_markdown_render_timings_per_action FROM gitlab."default".sidekiq_transactions WHERE (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY sidekiq_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_markdown_timings_overall FROM gitlab."default".sidekiq_method_calls WHERE method =~ /^Banzai/ GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_memory_usage_overall ON gitlab BEGIN SELECT mean(value) AS memory_mean, percentile(value, 95) AS memory_95th, percentile(value, 99) AS memory_99th INTO gitlab.downsampled.sidekiq_memory_usage_overall FROM gitlab."default".sidekiq_memory_usage GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_method_call_timings_per_action_and_method FROM gitlab."default".sidekiq_method_calls GROUP BY time(1m), method, action END; +CREATE CONTINUOUS QUERY sidekiq_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_method_call_timings_per_method FROM gitlab."default".sidekiq_method_calls GROUP BY time(1m), method END; +CREATE CONTINUOUS QUERY sidekiq_object_counts_overall ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.sidekiq_object_counts_overall FROM gitlab."default".sidekiq_object_counts GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_object_counts_per_type ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.sidekiq_object_counts_per_type FROM gitlab."default".sidekiq_object_counts GROUP BY time(1m), type END; +CREATE CONTINUOUS QUERY sidekiq_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.sidekiq_transaction_counts_overall FROM gitlab."default".sidekiq_transactions GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.sidekiq_transaction_counts_per_action FROM gitlab."default".sidekiq_transactions GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY sidekiq_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.sidekiq_transaction_timings_overall FROM gitlab."default".sidekiq_transactions GROUP BY time(1m) END; +CREATE CONTINUOUS QUERY sidekiq_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.sidekiq_transaction_timings_per_action FROM gitlab."default".sidekiq_transactions GROUP BY time(1m), action END; +CREATE CONTINUOUS QUERY sidekiq_view_timings_per_action_and_view ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_view_timings_per_action_and_view FROM gitlab."default".sidekiq_views GROUP BY time(1m), action, view END; +CREATE CONTINUOUS QUERY web_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.web_transaction_counts_overall FROM gitlab."default".rails_transactions GROUP BY time(1m) END; +``` + +## Import Dashboards + +You can now import a set of default dashboards that will give you a good +start on displaying useful information. GitLab has published a set of default +[Grafana dashboards][grafana-dashboards] to get you started. Clone the +repository or download a zip/tarball, then follow these steps to import each +JSON file. + +Open the dashboard dropdown menu and click 'Import' + +![Grafana dashboard dropdown](img/grafana_dashboard_dropdown.png) + +Click 'Choose file' and browse to the location where you downloaded or cloned +the dashboard repository. Pick one of the JSON files to import. + +![Grafana dashboard import](img/grafana_dashboard_import.png) + +Once the dashboard is imported, be sure to click save icon in the top bar. If +you do not save the dashboard after importing it will be removed when you +navigate away. + +![Grafana save icon](img/grafana_save_icon.png) + +Repeat this process for each dashboard you wish to import. + +Alternatively you can automatically import all the dashboards into your Grafana +instance. See the README of the [Grafana dashboards][grafana-dashboards] +repository for more information on this process. + +[grafana-dashboards]: https://gitlab.com/gitlab-org/grafana-dashboards + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Installation/Configuration](influxdb_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png new file mode 100644 index 00000000000..b4448c7a09f Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_dashboard_dropdown.png differ diff --git a/doc/administration/monitoring/performance/img/grafana_dashboard_import.png b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png new file mode 100644 index 00000000000..5a2d3c0937a Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_dashboard_import.png differ diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png new file mode 100644 index 00000000000..7e2e111f570 Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_data_source_configuration.png differ diff --git a/doc/administration/monitoring/performance/img/grafana_data_source_empty.png b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png new file mode 100644 index 00000000000..11e27571e64 Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_data_source_empty.png differ diff --git a/doc/administration/monitoring/performance/img/grafana_save_icon.png b/doc/administration/monitoring/performance/img/grafana_save_icon.png new file mode 100644 index 00000000000..3d4265bee8e Binary files /dev/null and b/doc/administration/monitoring/performance/img/grafana_save_icon.png differ diff --git a/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png new file mode 100644 index 00000000000..14d82b6ac98 Binary files /dev/null and b/doc/administration/monitoring/performance/img/metrics_gitlab_configuration_settings.png differ diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md new file mode 100644 index 00000000000..c30cd2950d8 --- /dev/null +++ b/doc/administration/monitoring/performance/influxdb_configuration.md @@ -0,0 +1,193 @@ +# InfluxDB Configuration + +The default settings provided by [InfluxDB] are not sufficient for a high traffic +GitLab environment. The settings discussed in this document are based on the +settings GitLab uses for GitLab.com, depending on your own needs you may need to +further adjust them. + +If you are intending to run InfluxDB on the same server as GitLab, make sure +you have plenty of RAM since InfluxDB can use quite a bit depending on traffic. + +Unless you are going with a budget setup, it's advised to run it separately. + +## Requirements + +- InfluxDB 0.9.5 or newer +- A fairly modern version of Linux +- At least 4GB of RAM +- At least 10GB of storage for InfluxDB data + +Note that the RAM and storage requirements can differ greatly depending on the +amount of data received/stored. To limit the amount of stored data users can +look into [InfluxDB Retention Policies][influxdb-retention]. + +## Installation + +Installing InfluxDB is out of the scope of this document. Please refer to the +[InfluxDB documentation]. + +## InfluxDB Server Settings + +Since InfluxDB has many settings that users may wish to customize themselves +(e.g. what port to run InfluxDB on), we'll only cover the essentials. + +The configuration file in question is usually located at +`/etc/influxdb/influxdb.conf`. Whenever you make a change in this file, +InfluxDB needs to be restarted. + +### Storage Engine + +InfluxDB comes with different storage engines and as of InfluxDB 0.9.5 a new +storage engine is available, called [TSM Tree]. All users **must** use the new +`tsm1` storage engine as this [will be the default engine][tsm1-commit] in +upcoming InfluxDB releases. + +Make sure you have the following in your configuration file: + +``` +[data] + dir = "/var/lib/influxdb/data" + engine = "tsm1" +``` + +### Admin Panel + +Production environments should have the InfluxDB admin panel **disabled**. This +feature can be disabled by adding the following to your InfluxDB configuration +file: + +``` +[admin] + enabled = false +``` + +### HTTP + +HTTP is required when using the [InfluxDB CLI] or other tools such as Grafana, +thus it should be enabled. When enabling make sure to _also_ enable +authentication: + +``` +[http] + enabled = true + auth-enabled = true +``` + +_**Note:** Before you enable authentication, you might want to [create an +admin user](#create-a-new-admin-user)._ + +### UDP + +GitLab writes data to InfluxDB via UDP and thus this must be enabled. Enabling +UDP can be done using the following settings: + +``` +[[udp]] + enabled = true + bind-address = ":8089" + database = "gitlab" + batch-size = 1000 + batch-pending = 5 + batch-timeout = "1s" + read-buffer = 209715200 +``` + +This does the following: + +1. Enable UDP and bind it to port 8089 for all addresses. +2. Store any data received in the "gitlab" database. +3. Define a batch of points to be 1000 points in size and allow a maximum of + 5 batches _or_ flush them automatically after 1 second. +4. Define a UDP read buffer size of 200 MB. + +One of the most important settings here is the UDP read buffer size as if this +value is set too low, packets will be dropped. You must also make sure the OS +buffer size is set to the same value, the default value is almost never enough. + +To set the OS buffer size to 200 MB, on Linux you can run the following command: + +```bash +sysctl -w net.core.rmem_max=209715200 +``` + +To make this permanent, add the following to `/etc/sysctl.conf` and restart the +server: + +```bash +net.core.rmem_max=209715200 +``` + +It is **very important** to make sure the buffer sizes are large enough to +handle all data sent to InfluxDB as otherwise you _will_ lose data. The above +buffer sizes are based on the traffic for GitLab.com. Depending on the amount of +traffic, users may be able to use a smaller buffer size, but we highly recommend +using _at least_ 100 MB. + +When enabling UDP, users should take care to not expose the port to the public, +as doing so will allow anybody to write data into your InfluxDB database (as +[InfluxDB's UDP protocol][udp] doesn't support authentication). We recommend either +whitelisting the allowed IP addresses/ranges, or setting up a VLAN and only +allowing traffic from members of said VLAN. + +## Create a new admin user + +If you want to [enable authentication](#http), you might want to [create an +admin user][influx-admin]: + +``` +influx -execute "CREATE USER jeff WITH PASSWORD '1234' WITH ALL PRIVILEGES" +``` + +## Create the `gitlab` database + +Once you get InfluxDB up and running, you need to create a database for GitLab. +Make sure you have changed the [storage engine](#storage-engine) to `tsm1` +before creating a database. + +_**Note:** If you [created an admin user](#create-a-new-admin-user) and enabled +[HTTP authentication](#http), remember to append the username (`-username `) +and password (`-password `) you set earlier to the commands below._ + +Run the following command to create a database named `gitlab`: + +```bash +influx -execute 'CREATE DATABASE gitlab' +``` + +The name **must** be `gitlab`, do not use any other name. + +Next, make sure that the database was successfully created: + +```bash +influx -execute 'SHOW DATABASES' +``` + +The output should be similar to: + +``` +name: databases +--------------- +name +_internal +gitlab +``` + +That's it! Now your GitLab instance should send data to InfluxDB. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) +- [Grafana Install/Configuration](grafana_configuration.md) + +[influxdb-retention]: https://docs.influxdata.com/influxdb/v0.9/query_language/database_management/#retention-policy-management +[influxdb documentation]: https://docs.influxdata.com/influxdb/v0.9/ +[influxdb cli]: https://docs.influxdata.com/influxdb/v0.9/tools/shell/ +[udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ +[influxdb]: https://influxdata.com/time-series-platform/influxdb/ +[tsm tree]: https://influxdata.com/blog/new-storage-engine-time-structured-merge-tree/ +[tsm1-commit]: https://github.com/influxdata/influxdb/commit/15d723dc77651bac83e09e2b1c94be480966cb0d +[influx-admin]: https://docs.influxdata.com/influxdb/v0.9/administration/authentication_and_authorization/#create-a-new-admin-user diff --git a/doc/administration/monitoring/performance/influxdb_schema.md b/doc/administration/monitoring/performance/influxdb_schema.md new file mode 100644 index 00000000000..41861860b6d --- /dev/null +++ b/doc/administration/monitoring/performance/influxdb_schema.md @@ -0,0 +1,88 @@ +# InfluxDB Schema + +The following measurements are currently stored in InfluxDB: + +- `PROCESS_file_descriptors` +- `PROCESS_gc_statistics` +- `PROCESS_memory_usage` +- `PROCESS_method_calls` +- `PROCESS_object_counts` +- `PROCESS_transactions` +- `PROCESS_views` + +Here, `PROCESS` is replaced with either `rails` or `sidekiq` depending on the +process type. In all series, any form of duration is stored in milliseconds. + +## PROCESS_file_descriptors + +This measurement contains the number of open file descriptors over time. The +value field `value` contains the number of descriptors. + +## PROCESS_gc_statistics + +This measurement contains Ruby garbage collection statistics such as the amount +of minor/major GC runs (relative to the last sampling interval), the time spent +in garbage collection cycles, and all fields/values returned by `GC.stat`. + +## PROCESS_memory_usage + +This measurement contains the process' memory usage (in bytes) over time. The +value field `value` contains the number of bytes. + +## PROCESS_method_calls + +This measurement contains the methods called during a transaction along with +their duration, and a name of the transaction action that invoked the method (if +available). The method call duration is stored in the value field `duration`, +while the method name is stored in the tag `method`. The tag `action` contains +the full name of the transaction action. Both the `method` and `action` fields +are in the following format: + +``` +ClassName#method_name +``` + +For example, a method called by the `show` method in the `UsersController` class +would have `action` set to `UsersController#show`. + +## PROCESS_object_counts + +This measurement is used to store retained Ruby objects (per class) and the +amount of retained objects. The number of objects is stored in the `count` value +field while the class name is stored in the `type` tag. + +## PROCESS_transactions + +This measurement is used to store basic transaction details such as the time it +took to complete a transaction, how much time was spent in SQL queries, etc. The +following value fields are available: + +| Value | Description | +| ----- | ----------- | +| `duration` | The total duration of the transaction | +| `allocated_memory` | The amount of bytes allocated while the transaction was running. This value is only reliable when using single-threaded application servers | +| `method_duration` | The total time spent in method calls | +| `sql_duration` | The total time spent in SQL queries | +| `view_duration` | The total time spent in views | + +## PROCESS_views + +This measurement is used to store view rendering timings for a transaction. The +following value fields are available: + +| Value | Description | +| ----- | ----------- | +| `duration` | The rendering time of the view | +| `view` | The path of the view, relative to the application's root directory | + +The `action` tag contains the action name of the transaction that rendered the +view. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Configuration](influxdb_configuration.md) +- [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/administration/monitoring/performance/introduction.md b/doc/administration/monitoring/performance/introduction.md new file mode 100644 index 00000000000..79904916b7e --- /dev/null +++ b/doc/administration/monitoring/performance/introduction.md @@ -0,0 +1,65 @@ +# GitLab Performance Monitoring + +GitLab comes with its own application performance measuring system as of GitLab +8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the +Community and Enterprise editions. + +Apart from this introduction, you are advised to read through the following +documents in order to understand and properly configure GitLab Performance Monitoring: + +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Install/Configuration](influxdb_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) +- [Grafana Install/Configuration](grafana_configuration.md) + +## Introduction to GitLab Performance Monitoring + +GitLab Performance Monitoring makes it possible to measure a wide variety of statistics +including (but not limited to): + +- The time it took to complete a transaction (a web request or Sidekiq job). +- The time spent in running SQL queries and rendering HAML views. +- The time spent executing (instrumented) Ruby methods. +- Ruby object allocations, and retained objects in particular. +- System statistics such as the process' memory usage and open file descriptors. +- Ruby garbage collection statistics. + +Metrics data is written to [InfluxDB][influxdb] over [UDP][influxdb-udp]. Stored +data can be visualized using [Grafana][grafana] or any other application that +supports reading data from InfluxDB. Alternatively data can be queried using the +InfluxDB CLI. + +## Metric Types + +Two types of metrics are collected: + +1. Transaction specific metrics. +1. Sampled metrics, collected at a certain interval in a separate thread. + +### Transaction Metrics + +Transaction metrics are metrics that can be associated with a single +transaction. This includes statistics such as the transaction duration, timings +of any executed SQL queries, time spent rendering HAML views, etc. These metrics +are collected for every Rack request and Sidekiq job processed. + +### Sampled Metrics + +Sampled metrics are metrics that can't be associated with a single transaction. +Examples include garbage collection statistics and retained Ruby objects. These +metrics are collected at a regular interval. This interval is made up out of two +parts: + +1. A user defined interval. +1. A randomly generated offset added on top of the interval, the same offset + can't be used twice in a row. + +The actual interval can be anywhere between a half of the defined interval and a +half above the interval. For example, for a user defined interval of 15 seconds +the actual interval can be anywhere between 7.5 and 22.5. The interval is +re-generated for every sampling run instead of being generated once and re-used +for the duration of the process' lifetime. + +[influxdb]: https://influxdata.com/time-series-platform/influxdb/ +[influxdb-udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ +[grafana]: http://grafana.org/ diff --git a/doc/administration/operations/README.md b/doc/administration/operations/README.md new file mode 100644 index 00000000000..6a35dab7b6c --- /dev/null +++ b/doc/administration/operations/README.md @@ -0,0 +1,5 @@ +# GitLab operations + +- [Sidekiq MemoryKiller](sidekiq_memory_killer.md) +- [Cleaning up Redis sessions](cleaning_up_redis_sessions.md) +- [Understanding Unicorn and unicorn-worker-killer](unicorn.md) diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md new file mode 100644 index 00000000000..93521e976d5 --- /dev/null +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -0,0 +1,52 @@ +# Cleaning up stale Redis sessions + +Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis. +Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If +you have been running a large GitLab server (thousands of users) since before +GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis +database after you upgrade to GitLab 7.3. You can also perform a cleanup while +still running GitLab 7.2 or older, but in that case new stale sessions will +start building up again after you clean up. + +In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte +hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with +GitLab 7.3.0, the keys are +prefixed with 'session:gitlab:', so they would look like +'session:gitlab:976aa289e2189b17d7ef525a6702ace9'. Below we describe how to +remove the keys in the old format. + +First we define a shell function with the proper Redis connection details. + +``` +rcli() { + # This example works for Omnibus installations of GitLab 7.3 or newer. For an + # installation from source you will have to change the socket path and the + # path to redis-cli. + sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" +} + +# test the new shell function; the response should be PONG +rcli ping +``` + +Now we do a search to see if there are any session keys in the old format for +us to clean up. + +``` +# returns the number of old-format session keys in Redis +rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l +``` + +If the number is larger than zero, you can proceed to expire the keys from +Redis. If the number is zero there is nothing to clean up. + +``` +# Tell Redis to expire each matched key after 600 seconds. +rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli +# This will print '(integer) 1' for each key that gets expired. +``` + +Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis +background save interval) your Redis database will be compacted. If you are +still using GitLab 7.2, users who are not clicking around in GitLab during the +10 minute expiry window will be signed out of GitLab. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md new file mode 100644 index 00000000000..54adb99386a --- /dev/null +++ b/doc/administration/operations/moving_repositories.md @@ -0,0 +1,180 @@ +# Moving repositories managed by GitLab + +Sometimes you need to move all repositories managed by GitLab to +another filesystem or another server. In this document we will look +at some of the ways you can copy all your repositories from +`/var/opt/gitlab/git-data/repositories` to `/mnt/gitlab/repositories`. + +We will look at three scenarios: the target directory is empty, the +target directory contains an outdated copy of the repositories, and +how to deal with thousands of repositories. + +**Each of the approaches we list can/will overwrite data in the +target directory `/mnt/gitlab/repositories`. Do not mix up the +source and the target.** + +## Target directory is empty: use a tar pipe + +If the target directory `/mnt/gitlab/repositories` is empty the +simplest thing to do is to use a tar pipe. This method has low +overhead and tar is almost always already installed on your system. +However, it is not possible to resume an interrupted tar pipe: if +that happens then all data must be copied again. + +``` +# As the git user +tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + tar -C /mnt/gitlab/repositories -xf - +``` + +If you want to see progress, replace `-xf` with `-xvf`. + +### Tar pipe to another server + +You can also use a tar pipe to copy data to another server. If your +'git' user has SSH access to the newserver as 'git@newserver', you +can pipe the data through SSH. + +``` +# As the git user +tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ + ssh git@newserver tar -C /mnt/gitlab/repositories -xf - +``` + +If you want to compress the data before it goes over the network +(which will cost you CPU cycles) you can replace `ssh` with `ssh -C`. + +## The target directory contains an outdated copy of the repositories: use rsync + +If the target directory already contains a partial / outdated copy +of the repositories it may be wasteful to copy all the data again +with tar. In this scenario it is better to use rsync. This utility +is either already installed on your system or easily installable +via apt, yum etc. + +``` +# As the 'git' user +rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + /mnt/gitlab/repositories +``` + +The `/.` in the command above is very important, without it you can +easily get the wrong directory structure in the target directory. +If you want to see progress, replace `-a` with `-av`. + +### Single rsync to another server + +If the 'git' user on your source system has SSH access to the target +server you can send the repositories over the network with rsync. + +``` +# As the 'git' user +rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ + git@newserver:/mnt/gitlab/repositories +``` + +## Thousands of Git repositories: use one rsync per repository + +Every time you start an rsync job it has to inspect all files in +the source directory, all files in the target directory, and then +decide what files to copy or not. If the source or target directory +has many contents this startup phase of rsync can become a burden +for your GitLab server. In cases like this you can make rsync's +life easier by dividing its work in smaller pieces, and sync one +repository at a time. + +In addition to rsync we will use [GNU +Parallel](http://www.gnu.org/software/parallel/). This utility is +not included in GitLab so you need to install it yourself with apt +or yum. Also note that the GitLab scripts we used below were added +in GitLab 8.1. + +** This process does not clean up repositories at the target location that no +longer exist at the source. ** If you start using your GitLab instance with +`/mnt/gitlab/repositories`, you need to run `gitlab-rake gitlab:cleanup:repos` +after switching to the new repository storage directory. + +### Parallel rsync for all repositories known to GitLab + +This will sync repositories with 10 rsync processes at a time. We keep +track of progress so that the transfer can be restarted if necessary. + +First we create a new directory, owned by 'git', to hold transfer +logs. We assume the directory is empty before we start the transfer +procedure, and that we are the only ones writing files in it. + +``` +# Omnibus +sudo mkdir /var/opt/gitlab/transfer-logs +sudo chown git:git /var/opt/gitlab/transfer-logs + +# Source +sudo -u git -H mkdir /home/git/transfer-logs +``` + +We seed the process with a list of the directories we want to copy. + +``` +# Omnibus +sudo -u git sh -c 'gitlab-rake gitlab:list_repos > /var/opt/gitlab/transfer-logs/all-repos-$(date +%s).txt' + +# Source +cd /home/git/gitlab +sudo -u git -H sh -c 'bundle exec rake gitlab:list_repos > /home/git/transfer-logs/all-repos-$(date +%s).txt' +``` + +Now we can start the transfer. The command below is idempotent, and +the number of jobs done by GNU Parallel should converge to zero. If it +does not some repositories listed in all-repos-1234.txt may have been +deleted/renamed before they could be copied. + +``` +# Omnibus +sudo -u git sh -c ' +cat /var/opt/gitlab/transfer-logs/* | sort | uniq -u |\ + /usr/bin/env JOBS=10 \ + /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \ + /var/opt/gitlab/transfer-logs/success-$(date +%s).log \ + /var/opt/gitlab/git-data/repositories \ + /mnt/gitlab/repositories +' + +# Source +cd /home/git/gitlab +sudo -u git -H sh -c ' +cat /home/git/transfer-logs/* | sort | uniq -u |\ + /usr/bin/env JOBS=10 \ + bin/parallel-rsync-repos \ + /home/git/transfer-logs/success-$(date +%s).log \ + /home/git/repositories \ + /mnt/gitlab/repositories +` +``` + +### Parallel rsync only for repositories with recent activity + +Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. +Then you might only want to sync repositories that were changed via GitLab +_after_ that time. You can use the 'SINCE' variable to tell 'rake +gitlab:list_repos' to only print repositories with recent activity. + +``` +# Omnibus +sudo gitlab-rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\ + sudo -u git \ + /usr/bin/env JOBS=10 \ + /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \ + success-$(date +%s).log \ + /var/opt/gitlab/git-data/repositories \ + /mnt/gitlab/repositories + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\ + sudo -u git -H \ + /usr/bin/env JOBS=10 \ + bin/parallel-rsync-repos \ + success-$(date +%s).log \ + /home/git/repositories \ + /mnt/gitlab/repositories +``` diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md new file mode 100644 index 00000000000..b5e78348989 --- /dev/null +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -0,0 +1,40 @@ +# Sidekiq MemoryKiller + +The GitLab Rails application code suffers from memory leaks. For web requests +this problem is made manageable using +[unicorn-worker-killer](https://github.com/kzk/unicorn-worker-killer) which +restarts Unicorn worker processes in between requests when needed. The Sidekiq +MemoryKiller applies the same approach to the Sidekiq processes used by GitLab +to process background jobs. + +Unlike unicorn-worker-killer, which is enabled by default for all GitLab +installations since GitLab 6.4, the Sidekiq MemoryKiller is enabled by default +_only_ for Omnibus packages. The reason for this is that the MemoryKiller +relies on Runit to restart Sidekiq after a memory-induced shutdown and GitLab +installations from source do not all use Runit or an equivalent. + +With the default settings, the MemoryKiller will cause a Sidekiq restart no +more often than once every 15 minutes, with the restart causing about one +minute of delay for incoming background jobs. + +## Configuring the MemoryKiller + +The MemoryKiller is controlled using environment variables. + +- `SIDEKIQ_MEMORY_KILLER_MAX_RSS`: if this variable is set, and its value is + greater than 0, then after each Sidekiq job, the MemoryKiller will check the + RSS of the Sidekiq process that executed the job. If the RSS of the Sidekiq + process (expressed in kilobytes) exceeds SIDEKIQ_MEMORY_KILLER_MAX_RSS, a + delayed shutdown is triggered. The default value for Omnibus packages is set + [in the omnibus-gitlab + repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). +- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults 900 seconds (15 minutes). When + a shutdown is triggered, the Sidekiq process will keep working normally for + another 15 minutes. +- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defaults to 30 seconds. When the grace + time has expired, the MemoryKiller tells Sidekiq to stop accepting new jobs. + Existing jobs get 30 seconds to finish. After that, the MemoryKiller tells + Sidekiq to shut down, and an external supervision mechanism (e.g. Runit) must + restart Sidekiq. +- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_SIGNAL`: defaults to `SIGKILL`. The name of + the final signal sent to the Sidekiq process when we want it to shut down. diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md new file mode 100644 index 00000000000..bad61151bda --- /dev/null +++ b/doc/administration/operations/unicorn.md @@ -0,0 +1,86 @@ +# Understanding Unicorn and unicorn-worker-killer + +## Unicorn + +GitLab uses [Unicorn](http://unicorn.bogomips.org/), a pre-forking Ruby web +server, to handle web requests (web browsers and Git HTTP clients). Unicorn is +a daemon written in Ruby and C that can load and run a Ruby on Rails +application; in our case the Rails application is GitLab Community Edition or +GitLab Enterprise Edition. + +Unicorn has a multi-process architecture to make better use of available CPU +cores (processes can run on different cores) and to have stronger fault +tolerance (most failures stay isolated in only one process and cannot take down +GitLab entirely). On startup, the Unicorn 'master' process loads a clean Ruby +environment with the GitLab application code, and then spawns 'workers' which +inherit this clean initial environment. The 'master' never handles any +requests, that is left to the workers. The operating system network stack +queues incoming requests and distributes them among the workers. + +In a perfect world, the master would spawn its pool of workers once, and then +the workers handle incoming web requests one after another until the end of +time. In reality, worker processes can crash or time out: if the master notices +that a worker takes too long to handle a request it will terminate the worker +process with SIGKILL ('kill -9'). No matter how the worker process ended, the +master process will replace it with a new 'clean' process again. Unicorn is +designed to be able to replace 'crashed' workers without dropping user +requests. + +This is what a Unicorn worker timeout looks like in `unicorn_stderr.log`. The +master process has PID 56227 below. + +``` +[2015-06-05T10:58:08.660325 #56227] ERROR -- : worker=10 PID:53009 timeout (61s > 60s), killing +[2015-06-05T10:58:08.699360 #56227] ERROR -- : reaped # worker=10 +[2015-06-05T10:58:08.708141 #62538] INFO -- : worker=10 spawned pid=62538 +[2015-06-05T10:58:08.708824 #62538] INFO -- : worker=10 ready +``` + +### Tunables + +The main tunables for Unicorn are the number of worker processes and the +request timeout after which the Unicorn master terminates a worker process. +See the [omnibus-gitlab Unicorn settings +documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.md) +if you want to adjust these settings. + +## unicorn-worker-killer + +GitLab has memory leaks. These memory leaks manifest themselves in long-running +processes, such as Unicorn workers. (The Unicorn master process is not known to +leak memory, probably because it does not handle user requests.) + +To make these memory leaks manageable, GitLab comes with the +[unicorn-worker-killer gem](https://github.com/kzk/unicorn-worker-killer). This +gem [monkey-patches](https://en.wikipedia.org/wiki/Monkey_patch) the Unicorn +workers to do a memory self-check after every 16 requests. If the memory of the +Unicorn worker exceeds a pre-set limit then the worker process exits. The +Unicorn master then automatically replaces the worker process. + +This is a robust way to handle memory leaks: Unicorn is designed to handle +workers that 'crash' so no user requests will be dropped. The +unicorn-worker-killer gem is designed to only terminate a worker process _in +between requests_, so no user requests are affected. + +This is what a Unicorn worker memory restart looks like in unicorn_stderr.log. +You see that worker 4 (PID 125918) is inspecting itself and decides to exit. +The threshold memory value was 254802235 bytes, about 250MB. With GitLab this +threshold is a random value between 200 and 250 MB. The master process (PID +117565) then reaps the worker process and spawns a new 'worker 4' with PID +127549. + +``` +[2015-06-05T12:07:41.828374 #125918] WARN -- : #: worker (pid: 125918) exceeds memory limit (256413696 bytes > 254802235 bytes) +[2015-06-05T12:07:41.828472 #125918] WARN -- : Unicorn::WorkerKiller send SIGQUIT (pid: 125918) alive: 23 sec (trial 1) +[2015-06-05T12:07:42.025916 #117565] INFO -- : reaped # worker=4 +[2015-06-05T12:07:42.034527 #127549] INFO -- : worker=4 spawned pid=127549 +[2015-06-05T12:07:42.035217 #127549] INFO -- : worker=4 ready +``` + +One other thing that stands out in the log snippet above, taken from +GitLab.com, is that 'worker 4' was serving requests for only 23 seconds. This +is a normal value for our current GitLab.com setup and traffic. + +The high frequency of Unicorn memory restarts on some GitLab sites can be a +source of confusion for administrators. Usually they are a [red +herring](https://en.wikipedia.org/wiki/Red_herring). diff --git a/doc/administration/raketasks/README.md b/doc/administration/raketasks/README.md new file mode 100644 index 00000000000..a49c43b8ef2 --- /dev/null +++ b/doc/administration/raketasks/README.md @@ -0,0 +1,11 @@ +# Rake tasks + +- [Backup restore](backup_restore.md) +- [Check](check.md) +- [Cleanup](cleanup.md) +- [Features](features.md) +- [Maintenance](maintenance.md) and self-checks +- [User management](user_management.md) +- [Webhooks](web_hooks.md) +- [Import](import.md) of git repositories in bulk +- [Rebuild authorized_keys file](http://docs.gitlab.com/ce/raketasks/maintenance.html#rebuild-authorized_keys-file) task for administrators diff --git a/doc/administration/raketasks/backup_hrz.png b/doc/administration/raketasks/backup_hrz.png new file mode 100644 index 00000000000..03e50df1d76 Binary files /dev/null and b/doc/administration/raketasks/backup_hrz.png differ diff --git a/doc/administration/raketasks/backup_restore.md b/doc/administration/raketasks/backup_restore.md new file mode 100644 index 00000000000..fa976134341 --- /dev/null +++ b/doc/administration/raketasks/backup_restore.md @@ -0,0 +1,438 @@ +# Backup restore + +![backup banner](backup_hrz.png) + +## Create a backup of the GitLab system + +A backup creates an archive file that contains the database, all repositories and all attachments. +This archive will be saved in backup_path (see `config/gitlab.yml`). +The filename will be `[TIMESTAMP]_gitlab_backup.tar`. This timestamp can be used to restore an specific backup. +You can only restore a backup to exactly the same version of GitLab that you created it +on, for example 7.2.1. The best way to migrate your repositories from one server to +another is through backup restore. + +You need to keep a separate copy of `/etc/gitlab/gitlab-secrets.json` +(for omnibus packages) or `/home/git/gitlab/.secret` (for installations +from source). This file contains the database encryption key used +for two-factor authentication. If you restore a GitLab backup without +restoring the database encryption key, users who have two-factor +authentication enabled will lose access to your GitLab server. + +``` +# use this command if you've installed GitLab with the Omnibus package +sudo gitlab-rake gitlab:backup:create + +# if you've installed GitLab from source +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +Also you can choose what should be backed up by adding environment variable SKIP. Available options: db, +uploads (attachments), repositories, builds(CI build output logs), artifacts (CI build artifacts), lfs (LFS objects). +Use a comma to specify several options at the same time. + +``` +sudo gitlab-rake gitlab:backup:create SKIP=db,uploads +``` + +Example output: + +``` +Dumping database tables: +- Dumping table events... [DONE] +- Dumping table issues... [DONE] +- Dumping table keys... [DONE] +- Dumping table merge_requests... [DONE] +- Dumping table milestones... [DONE] +- Dumping table namespaces... [DONE] +- Dumping table notes... [DONE] +- Dumping table projects... [DONE] +- Dumping table protected_branches... [DONE] +- Dumping table schema_migrations... [DONE] +- Dumping table services... [DONE] +- Dumping table snippets... [DONE] +- Dumping table taggings... [DONE] +- Dumping table tags... [DONE] +- Dumping table users... [DONE] +- Dumping table users_projects... [DONE] +- Dumping table web_hooks... [DONE] +- Dumping table wikis... [DONE] +Dumping repositories: +- Dumping repository abcd... [DONE] +Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE] +Deleting tmp directories...[DONE] +Deleting old backups... [SKIPPING] +``` + +## Upload backups to remote (cloud) storage + +Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates. +It uses the [Fog library](http://fog.io/) to perform the upload. +In the example below we use Amazon S3 for storage. +But Fog also lets you use [other storage providers](http://fog.io/storage/). + +For omnibus packages: + +```ruby +gitlab_rails['backup_upload_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-west-1', + 'aws_access_key_id' => 'AKIAKIAKI', + 'aws_secret_access_key' => 'secret123' +} +gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket' +``` + +For installations from source: + +```yaml + backup: + # snip + upload: + # Fog storage connection settings, see http://fog.io/storage/ . + connection: + provider: AWS + region: eu-west-1 + aws_access_key_id: AKIAKIAKI + aws_secret_access_key: 'secret123' + # The remote 'directory' to store your backups. For S3, this would be the bucket name. + remote_directory: 'my.s3.bucket' + # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional + # encryption: 'AES256' +``` + +If you are uploading your backups to S3 you will probably want to create a new +IAM user with restricted access rights. To give the upload user access only for +uploading backups create the following IAM profile, replacing `my.s3.bucket` +with the name of your bucket: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Stmt1412062044000", + "Effect": "Allow", + "Action": [ + "s3:AbortMultipartUpload", + "s3:GetBucketAcl", + "s3:GetBucketLocation", + "s3:GetObject", + "s3:GetObjectAcl", + "s3:ListBucketMultipartUploads", + "s3:PutObject", + "s3:PutObjectAcl" + ], + "Resource": [ + "arn:aws:s3:::my.s3.bucket/*" + ] + }, + { + "Sid": "Stmt1412062097000", + "Effect": "Allow", + "Action": [ + "s3:GetBucketLocation", + "s3:ListAllMyBuckets" + ], + "Resource": [ + "*" + ] + }, + { + "Sid": "Stmt1412062128000", + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::my.s3.bucket" + ] + } + ] +} +``` + +### Uploading to locally mounted shares + +You may also send backups to a mounted share (`NFS` / `CIFS` / `SMB` / etc.) by +using the [`Local`](https://github.com/fog/fog-local#usage) storage provider. +The directory pointed to by the `local_root` key **must** be owned by the `git` +user **when mounted** (mounting with the `uid=` of the `git` user for `CIFS` and +`SMB`) or the user that you are executing the backup tasks under (for omnibus +packages, this is the `git` user). + +The `backup_upload_remote_directory` **must** be set in addition to the +`local_root` key. This is the sub directory inside the mounted directory that +backups will be copied to, and will be created if it does not exist. If the +directory that you want to copy the tarballs to is the root of your mounted +directory, just use `.` instead. + +For omnibus packages: + +```ruby +gitlab_rails['backup_upload_connection'] = { + :provider => 'Local', + :local_root => '/mnt/backups' +} + +# The directory inside the mounted folder to copy backups to +# Use '.' to store them in the root directory +gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' +``` + +For installations from source: + +```yaml + backup: + # snip + upload: + # Fog storage connection settings, see http://fog.io/storage/ . + connection: + provider: Local + local_root: '/mnt/backups' + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + remote_directory: 'gitlab_backups' +``` + +## Backup archive permissions + +The backup archives created by GitLab (123456_gitlab_backup.tar) will have owner/group git:git and 0600 permissions by default. +This is meant to avoid other system users reading GitLab's data. +If you need the backup archives to have different permissions you can use the 'archive_permissions' setting. + +``` +# In /etc/gitlab/gitlab.rb, for omnibus packages +gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable +``` + +``` +# In gitlab.yml, for installations from source: + backup: + archive_permissions: 0644 # Makes the backup archives world-readable +``` + +## Storing configuration files + +Please be informed that a backup does not store your configuration +files. One reason for this is that your database contains encrypted +information for two-factor authentication. Storing encrypted +information along with its key in the same place defeats the purpose +of using encryption in the first place! + +If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). +If you have a cookbook installation there should be a copy of your configuration in Chef. +If you have an installation from source, please consider backing up your `.secret` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + +At the very **minimum** you should backup `/etc/gitlab/gitlab-secrets.json` +(Omnibus) or `/home/git/gitlab/.secret` (source) to preserve your +database encryption key. + +## Restore a previously created backup + +You can only restore a backup to exactly the same version of GitLab that you created it on, for example 7.2.1. + +### Prerequisites + +You need to have a working GitLab installation before you can perform +a restore. This is mainly because the system user performing the +restore actions ('git') is usually not allowed to create or delete +the SQL database it needs to import data into ('gitlabhq_production'). +All existing data will be either erased (SQL) or moved to a separate +directory (repositories, uploads). + +If some or all of your GitLab users are using two-factor authentication +(2FA) then you must also make sure to restore +`/etc/gitlab/gitlab-secrets.json` (Omnibus) or `/home/git/gitlab/.secret` +(installations from source). Note that you need to run `gitlab-ctl +reconfigure` after changing `gitlab-secrets.json`. + +### Installation from source + +``` +# Stop processes that are connected to the database +sudo service gitlab stop + +bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +Options: + +``` +BACKUP=timestamp_of_backup (required if more than one backup exists) +force=yes (do not ask if the authorized_keys file should get regenerated) +``` + +Example output: + +``` +Unpacking backup... [DONE] +Restoring database tables: +-- create_table("events", {:force=>true}) + -> 0.2231s +[...] +- Loading fixture events...[DONE] +- Loading fixture issues...[DONE] +- Loading fixture keys...[SKIPPING] +- Loading fixture merge_requests...[DONE] +- Loading fixture milestones...[DONE] +- Loading fixture namespaces...[DONE] +- Loading fixture notes...[DONE] +- Loading fixture projects...[DONE] +- Loading fixture protected_branches...[SKIPPING] +- Loading fixture schema_migrations...[DONE] +- Loading fixture services...[SKIPPING] +- Loading fixture snippets...[SKIPPING] +- Loading fixture taggings...[SKIPPING] +- Loading fixture tags...[SKIPPING] +- Loading fixture users...[DONE] +- Loading fixture users_projects...[DONE] +- Loading fixture web_hooks...[SKIPPING] +- Loading fixture wikis...[SKIPPING] +Restoring repositories: +- Restoring repository abcd... [DONE] +Deleting tmp directories...[DONE] +``` + +### Omnibus installations + +This procedure assumes that: + +- You have installed the exact same version of GitLab Omnibus with which the + backup was created +- You have run `sudo gitlab-ctl reconfigure` at least once +- GitLab is running. If not, start it using `sudo gitlab-ctl start`. + +First make sure your backup tar file is in the backup directory described in the +`gitlab.rb` configuration `gitlab_rails['backup_path']`. The default is +`/var/opt/gitlab/backups`. + +```shell +sudo cp 1393513186_gitlab_backup.tar /var/opt/gitlab/backups/ +``` + +Stop the processes that are connected to the database. Leave the rest of GitLab +running: + +```shell +sudo gitlab-ctl stop unicorn +sudo gitlab-ctl stop sidekiq +# Verify +sudo gitlab-ctl status +``` + +Next, restore the backup, specifying the timestamp of the backup you wish to +restore: + +```shell +# This command will overwrite the contents of your GitLab database! +sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186 +``` + +Restart and check GitLab: + +```shell +sudo gitlab-ctl start +sudo gitlab-rake gitlab:check SANITIZE=true +``` + +If there is a GitLab version mismatch between your backup tar file and the installed +version of GitLab, the restore command will abort with an error. Install the +[correct GitLab version](https://www.gitlab.com/downloads/archives/) and try again. + +## Configure cron to make daily backups + +### For installation from source: +``` +cd /home/git/gitlab +sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups +sudo -u git crontab -e # Edit the crontab for the git user +``` + +Add the following lines at the bottom: + +``` +# Create a full backup of the GitLab repositories and SQL database every day at 4am +0 4 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1 +``` + +The `CRON=1` environment setting tells the backup script to suppress all progress output if there are no errors. +This is recommended to reduce cron spam. + +### For omnibus installations + +To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: + +``` +sudo su - +crontab -e +``` + +There, add the following line to schedule the backup for everyday at 2 AM: + +``` +0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1 +``` + +You may also want to set a limited lifetime for backups to prevent regular +backups using all your disk space. To do this add the following lines to +`/etc/gitlab/gitlab.rb` and reconfigure: + +``` +# limit backup lifetime to 7 days - 604800 seconds +gitlab_rails['backup_keep_time'] = 604800 +``` + +NOTE: This cron job does not [backup your omnibus-gitlab configuration](#backup-and-restore-omnibus-gitlab-configuration) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + +## Alternative backup strategies + +If your GitLab server contains a lot of Git repository data you may find the GitLab backup script to be too slow. +In this case you can consider using filesystem snapshots as part of your backup strategy. + +Example: Amazon EBS + +> A GitLab server using omnibus-gitlab hosted on Amazon AWS. +> An EBS drive containing an ext4 filesystem is mounted at `/var/opt/gitlab`. +> In this case you could make an application backup by taking an EBS snapshot. +> The backup includes all repositories, uploads and Postgres data. + +Example: LVM snapshots + rsync + +> A GitLab server using omnibus-gitlab, with an LVM logical volume mounted at `/var/opt/gitlab`. +> Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. +> Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. +> Now we can have a longer running rsync job which will create a consistent replica on the remote server. +> The replica includes all repositories, uploads and Postgres data. + +If you are running GitLab on a virtualized server you can possibly also create VM snapshots of the entire GitLab server. +It is not uncommon however for a VM snapshot to require you to power down the server, so this approach is probably of limited practical use. + +## Troubleshooting + +### Restoring database backup using omnibus packages outputs warnings +If you are using backup restore procedures you might encounter the following warnings: + +``` +psql:/var/opt/gitlab/backups/db/database.sql:22: ERROR: must be owner of extension plpgsql +psql:/var/opt/gitlab/backups/db/database.sql:2931: WARNING: no privileges could be revoked for "public" (two occurrences) +psql:/var/opt/gitlab/backups/db/database.sql:2933: WARNING: no privileges were granted for "public" (two occurrences) + +``` + +Be advised that, backup is successfully restored in spite of these warnings. + +The rake task runs this as the `gitlab` user which does not have the superuser access to the database. When restore is initiated it will also run as `gitlab` user but it will also try to alter the objects it does not have access to. +Those objects have no influence on the database backup/restore but they give this annoying warning. + +For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). + +## Note +This documentation is for GitLab CE. +We backup GitLab.com and make sure your data is secure, but you can't use these methods to export / backup your data yourself from GitLab.com. + +Issues are stored in the database. They can't be stored in Git itself. + +To migrate your repositories from one server to another with an up-to-date version of +GitLab, you can use the [import rake task](import.md) to do a mass import of the +repository. Note that if you do an import rake task, rather than a backup restore, you +will have all your repositories, but not any other data. diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md new file mode 100644 index 00000000000..3ff3fee6a40 --- /dev/null +++ b/doc/administration/raketasks/check.md @@ -0,0 +1,63 @@ +# Check Rake Tasks + +## Repository Integrity + +Even though Git is very resilient and tries to prevent data integrity issues, +there are times when things go wrong. The following Rake tasks intend to +help GitLab administrators diagnose problem repositories so they can be fixed. + +There are 3 things that are checked to determine integrity. + +1. Git repository file system check ([git fsck](https://git-scm.com/docs/git-fsck)). + This step verifies the connectivity and validity of objects in the repository. +1. Check for `config.lock` in the repository directory. +1. Check for any branch/references lock files in `refs/heads`. + +It's important to note that the existence of `config.lock` or reference locks +alone do not necessarily indicate a problem. Lock files are routinely created +and removed as Git and GitLab perform operations on the repository. They serve +to prevent data integrity issues. However, if a Git operation is interrupted these +locks may not be cleaned up properly. + +The following symptoms may indicate a problem with repository integrity. If users +experience these symptoms you may use the rake tasks described below to determine +exactly which repositories are causing the trouble. + +- Receiving an error when trying to push code - `remote: error: cannot lock ref` +- A 500 error when viewing the GitLab dashboard or when accessing a specific project. + +### Check all GitLab repositories + +This task loops through all repositories on the GitLab server and runs the +3 integrity checks described previously. + +``` +# omnibus-gitlab +sudo gitlab-rake gitlab:repo:check + +# installation from source +bundle exec rake gitlab:repo:check RAILS_ENV=production +``` + +### Check repositories for a specific user + +This task checks all repositories that a specific user has access to. This is important +because sometimes you know which user is experiencing trouble but you don't know +which project might be the cause. + +If the rake task is executed without brackets at the end, you will be prompted +to enter a username. + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:user:check_repos +sudo gitlab-rake gitlab:user:check_repos[] + +# installation from source +bundle exec rake gitlab:user:check_repos RAILS_ENV=production +bundle exec rake gitlab:user:check_repos[] RAILS_ENV=production +``` + +Example output: + +![gitlab:user:check_repos output](check_repos_output.png) diff --git a/doc/administration/raketasks/check_repos_output.png b/doc/administration/raketasks/check_repos_output.png new file mode 100644 index 00000000000..916b1685101 Binary files /dev/null and b/doc/administration/raketasks/check_repos_output.png differ diff --git a/doc/administration/raketasks/cleanup.md b/doc/administration/raketasks/cleanup.md new file mode 100644 index 00000000000..8fbcbb983e9 --- /dev/null +++ b/doc/administration/raketasks/cleanup.md @@ -0,0 +1,24 @@ +# Cleanup + +## Remove garbage from filesystem. Important! Data loss! + +Remove namespaces(dirs) from `/home/git/repositories` if they don't exist in GitLab database. + +``` +# omnibus-gitlab +sudo gitlab-rake gitlab:cleanup:dirs + +# installation from source +bundle exec rake gitlab:cleanup:dirs RAILS_ENV=production +``` + +Rename repositories from `/home/git/repositories` if they don't exist in GitLab database. +The repositories get a `+orphaned+TIMESTAMP` suffix so that they cannot block new repositories from being created. + +``` +# omnibus-gitlab +sudo gitlab-rake gitlab:cleanup:repos + +# installation from source +bundle exec rake gitlab:cleanup:repos RAILS_ENV=production +``` diff --git a/doc/administration/raketasks/features.md b/doc/administration/raketasks/features.md new file mode 100644 index 00000000000..f9a46193547 --- /dev/null +++ b/doc/administration/raketasks/features.md @@ -0,0 +1,20 @@ +# Features + +## Enable usernames and namespaces for user projects + +This command will enable the namespaces feature introduced in v4.0. It will move every project in its namespace folder. + +Note: + +- Because the **repository location will change**, you will need to **update all your git URLs** to point to the new location. +- Username can be changed at [Profile / Account](/profile/account) + +**Example:** + +Old path: `git@example.org:myrepo.git` + +New path: `git@example.org:username/myrepo.git` or `git@example.org:groupname/myrepo.git` + +``` +bundle exec rake gitlab:enable_namespaces RAILS_ENV=production +``` diff --git a/doc/administration/raketasks/import.md b/doc/administration/raketasks/import.md new file mode 100644 index 00000000000..8a38937062e --- /dev/null +++ b/doc/administration/raketasks/import.md @@ -0,0 +1,68 @@ +# Import bare repositories into your GitLab instance + +## Notes + +- The owner of the project will be the first admin +- The groups will be created as needed +- The owner of the group will be the first admin +- Existing projects will be skipped + +## How to use + +### Create a new folder inside the git repositories path. This will be the name of the new group. + +- For omnibus-gitlab, it is located at: `/var/opt/gitlab/git-data/repositories` by default, unless you changed +it in the `/etc/gitlab/gitlab.rb` file. +- For installations from source, it is usually located at: `/home/git/repositories` or you can see where +your repositories are located by looking at `config/gitlab.yml` under the `gitlab_shell => repos_path` entry. + +New folder needs to have git user ownership and read/write/execute access for git user and its group: + +``` +sudo -u git mkdir /var/opt/gitlab/git-data/repositories/new_group +``` + +If you are using an installation from source, replace `/var/opt/gitlab/git-data` +with `/home/git`. + +### Copy your bare repositories inside this newly created folder: + +``` +sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repositories/new_group/ + +# Do this once when you are done copying git repositories +sudo chown -R git:git /var/opt/gitlab/git-data/repositories/new_group/ +``` + +`foo.git` needs to be owned by the git user and git users group. + +If you are using an installation from source, replace `/var/opt/gitlab/git-data` +with `/home/git`. + +### Run the command below depending on your type of installation: + +#### Omnibus Installation + +``` +$ sudo gitlab-rake gitlab:import:repos +``` + +#### Installation from source + +Before running this command you need to change the directory to where your GitLab installation is located: + +``` +$ cd /home/git/gitlab +$ sudo -u git -H bundle exec rake gitlab:import:repos RAILS_ENV=production +``` + +#### Example output + +``` +Processing abcd.git + * Created abcd (abcd.git) +Processing group/xyz.git + * Created Group group (2) + * Created xyz (group/xyz.git) +[...] +``` diff --git a/doc/administration/raketasks/list_repos.md b/doc/administration/raketasks/list_repos.md new file mode 100644 index 00000000000..476428eb4f5 --- /dev/null +++ b/doc/administration/raketasks/list_repos.md @@ -0,0 +1,30 @@ +# Listing repository directories + +You can print a list of all Git repositories on disk managed by +GitLab with the following command: + +``` +# Omnibus +sudo gitlab-rake gitlab:list_repos + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:list_repos RAILS_ENV=production +``` + +If you only want to list projects with recent activity you can pass +a date with the 'SINCE' environment variable. The time you specify +is parsed by the Rails [TimeZone#parse +function](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html#method-i-parse). + +``` +# Omnibus +sudo gitlab-rake gitlab:list_repos SINCE='Sep 1 2015' + +# Source +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:list_repos RAILS_ENV=production SINCE='Sep 1 2015' +``` + +Note that the projects listed are NOT sorted by activity; they use +the default ordering of the GitLab Rails application. diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md new file mode 100644 index 00000000000..d9dce2af480 --- /dev/null +++ b/doc/administration/raketasks/maintenance.md @@ -0,0 +1,169 @@ +# Maintenance + +## Gather information about GitLab and the system it runs on + +This command gathers information about your GitLab installation and the System it runs on. These may be useful when asking for help or reporting issues. + +``` +# omnibus-gitlab +sudo gitlab-rake gitlab:env:info + +# installation from source +bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +Example output: + +``` +System information +System: Debian 7.8 +Current User: git +Using RVM: no +Ruby Version: 2.1.5p273 +Gem Version: 2.4.3 +Bundler Version: 1.7.6 +Rake Version: 10.3.2 +Sidekiq Version: 2.17.8 + +GitLab information +Version: 7.7.1 +Revision: 41ab9e1 +Directory: /home/git/gitlab +DB Adapter: postgresql +URL: https://gitlab.example.com +HTTP Clone URL: https://gitlab.example.com/some-project.git +SSH Clone URL: git@gitlab.example.com:some-project.git +Using LDAP: no +Using Omniauth: no + +GitLab Shell +Version: 2.4.1 +Repositories: /home/git/repositories/ +Hooks: /home/git/gitlab-shell/hooks/ +Git: /usr/bin/git +``` + +## Check GitLab configuration + +Runs the following rake tasks: + +- `gitlab:gitlab_shell:check` +- `gitlab:sidekiq:check` +- `gitlab:app:check` + +It will check that each component was setup according to the installation guide and suggest fixes for issues found. + +You may also have a look at our [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide). + +``` +# omnibus-gitlab +sudo gitlab-rake gitlab:check + +# installation from source +bundle exec rake gitlab:check RAILS_ENV=production +``` + +NOTE: Use SANITIZE=true for gitlab:check if you want to omit project names from the output. + +Example output: + +``` +Checking Environment ... + +Git configured for git user? ... yes +Has python2? ... yes +python2 is supported version? ... yes + +Checking Environment ... Finished + +Checking GitLab Shell ... + +GitLab Shell version? ... OK (1.2.0) +Repo base directory exists? ... yes +Repo base directory is a symlink? ... no +Repo base owned by git:git? ... yes +Repo base access is drwxrws---? ... yes +post-receive hook up-to-date? ... yes +post-receive hooks in repos are links: ... yes + +Checking GitLab Shell ... Finished + +Checking Sidekiq ... + +Running? ... yes + +Checking Sidekiq ... Finished + +Checking GitLab ... + +Database config exists? ... yes +Database is SQLite ... no +All migrations up? ... yes +GitLab config exists? ... yes +GitLab config outdated? ... no +Log directory writable? ... yes +Tmp directory writable? ... yes +Init script exists? ... yes +Init script up-to-date? ... yes +Redis version >= 2.0.0? ... yes + +Checking GitLab ... Finished +``` + +## Rebuild authorized_keys file + +In some case it is necessary to rebuild the `authorized_keys` file. + +For Omnibus-packages: +``` +sudo gitlab-rake gitlab:shell:setup +``` + +For installations from source: +``` +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production +``` + +``` +This will rebuild an authorized_keys file. +You will lose any data stored in authorized_keys file. +Do you want to continue (yes/no)? yes +``` + +## Clear redis cache + +If for some reason the dashboard shows wrong information you might want to +clear Redis' cache. + +For Omnibus-packages: +``` +sudo gitlab-rake cache:clear +``` + +For installations from source: +``` +cd /home/git/gitlab +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +## Precompile the assets + +Sometimes during version upgrades you might end up with some wrong CSS or +missing some icons. In that case, try to precompile the assets again. + +Note that this only applies to source installations and does NOT apply to +omnibus packages. + +For installations from source: +``` +cd /home/git/gitlab +sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production +``` + +For omnibus versions, the unoptimized assets (JavaScript, CSS) are frozen at +the release of upstream GitLab. The omnibus version includes optimized versions +of those assets. Unless you are modifying the JavaScript / CSS code on your +production machine after installing the package, there should be no reason to redo +rake assets:precompile on the production machine. If you suspect that assets +have been corrupted, you should reinstall the omnibus package. diff --git a/doc/administration/raketasks/user_management.md b/doc/administration/raketasks/user_management.md new file mode 100644 index 00000000000..629d38efc53 --- /dev/null +++ b/doc/administration/raketasks/user_management.md @@ -0,0 +1,72 @@ +# User management + +## Add user as a developer to all projects + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:import:user_to_projects[username@domain.tld] + +# installation from source +bundle exec rake gitlab:import:user_to_projects[username@domain.tld] RAILS_ENV=production +``` + +## Add all users to all projects + +Notes: + +- admin users are added as masters + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:import:all_users_to_all_projects + +# installation from source +bundle exec rake gitlab:import:all_users_to_all_projects RAILS_ENV=production +``` + +## Add user as a developer to all groups + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:import:user_to_groups[username@domain.tld] + +# installation from source +bundle exec rake gitlab:import:user_to_groups[username@domain.tld] RAILS_ENV=production +``` + +## Add all users to all groups + +Notes: + +- admin users are added as owners so they can add additional users to the group + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:import:all_users_to_all_groups + +# installation from source +bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production +``` + +## Maintain tight control over the number of active users on your GitLab installation + +- Enable this setting to keep new users blocked until they have been cleared by the admin (default: false). + + +``` +block_auto_created_users: false +``` + +## Disable Two-factor Authentication (2FA) for all users + +This task will disable 2FA for all users that have it enabled. This can be +useful if GitLab's `.secret` file has been lost and users are unable to login, +for example. + +```bash +# omnibus-gitlab +sudo gitlab-rake gitlab:two_factor:disable_for_all_users + +# installation from source +bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production +``` diff --git a/doc/administration/raketasks/web_hooks.md b/doc/administration/raketasks/web_hooks.md new file mode 100644 index 00000000000..2ebf7c48f4e --- /dev/null +++ b/doc/administration/raketasks/web_hooks.md @@ -0,0 +1,45 @@ +# Webhooks + +## Add a webhook for **ALL** projects: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" + # source installations + bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production + +## Add a webhook for projects in a given **NAMESPACE**: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme + # source installations + bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production + +## Remove a webhook from **ALL** projects using: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" + # source installations + bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production + +## Remove a webhook from projects in a given **NAMESPACE**: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme + # source installations + bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production + +## List **ALL** webhooks: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:list + # source installations + bundle exec rake gitlab:web_hook:list RAILS_ENV=production + +## List the webhooks from projects in a given **NAMESPACE**: + + # omnibus-gitlab + sudo gitlab-rake gitlab:web_hook:list NAMESPACE=/ + # source installations + bundle exec rake gitlab:web_hook:list NAMESPACE=/ RAILS_ENV=production + +> Note: `/` is the global namespace. diff --git a/doc/container_registry/README.md b/doc/container_registry/README.md deleted file mode 100644 index 1b465434498..00000000000 --- a/doc/container_registry/README.md +++ /dev/null @@ -1,94 +0,0 @@ -# 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/container_registry/img/container_registry.png b/doc/container_registry/img/container_registry.png deleted file mode 100644 index e9505a73b40..00000000000 Binary files a/doc/container_registry/img/container_registry.png and /dev/null differ diff --git a/doc/container_registry/img/project_feature.png b/doc/container_registry/img/project_feature.png deleted file mode 100644 index 57a73d253c0..00000000000 Binary files a/doc/container_registry/img/project_feature.png and /dev/null differ diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md deleted file mode 100644 index d4d9f5f7b5e..00000000000 --- a/doc/customization/branded_login_page.md +++ /dev/null @@ -1,19 +0,0 @@ -# Changing the appearance of the login page - -GitLab Community Edition offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page. - -By default, the page shows the GitLab logo and description. - -![default_login_page](branded_login_page/default_login_page.png) - -## Changing the appearance of the login page - -Navigate to the **Admin** area and go to the **Appearance** page. - -Fill in the required details like Title, Description and upload the company logo. - -![appearance](branded_login_page/appearance.png) - -After saving the page, your GitLab login page will have the details you filled in: - -![company_login_page](branded_login_page/custom_sign_in.png) diff --git a/doc/customization/branded_login_page/appearance.png b/doc/customization/branded_login_page/appearance.png deleted file mode 100644 index 6bce1f0a287..00000000000 Binary files a/doc/customization/branded_login_page/appearance.png and /dev/null differ diff --git a/doc/customization/branded_login_page/custom_sign_in.png b/doc/customization/branded_login_page/custom_sign_in.png deleted file mode 100644 index d6020b029a2..00000000000 Binary files a/doc/customization/branded_login_page/custom_sign_in.png and /dev/null differ diff --git a/doc/customization/branded_login_page/default_login_page.png b/doc/customization/branded_login_page/default_login_page.png deleted file mode 100644 index 795c7954d8e..00000000000 Binary files a/doc/customization/branded_login_page/default_login_page.png and /dev/null differ diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md deleted file mode 100644 index 194b8e00299..00000000000 --- a/doc/customization/issue_closing.md +++ /dev/null @@ -1,39 +0,0 @@ -# Issue closing pattern - -When a commit or merge request resolves one or more issues, it is possible to automatically have these issues closed when the commit or merge request lands in the project's default branch. - -If a commit message or merge request description contains a sentence matching the regular expression below, all issues referenced from -the matched text will be closed. This happens when the commit is pushed to a project's default branch, or when a commit or merge request is merged into there. - -When not specified, the default `issue_closing_pattern` as shown below will be used: - -```bash -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+) -``` - -Here, `%{issue_ref}` is a complex regular expression defined inside GitLab, that matches a reference to a local issue (`#123`), cross-project issue (`group/project#123`) or a link to an issue (`https://gitlab.example.com/group/project/issues/123`). - -For example: - -``` -git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes group/otherproject#22). This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23." -``` - -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does not match the pattern. It also works with multiline commit messages. - -Tip: you can test this closing pattern at [http://rubular.com][1]. Use this site -to test your own patterns. -Because Rubular doesn't understand `%{issue_ref}`, you can replace this by `#\d+` in testing, which matches only local issue references like `#123`. - -## Change the pattern - -For Omnibus installs you can change the default pattern in `/etc/gitlab/gitlab.rb`: - -``` -issue_closing_pattern: '((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)' -``` - -For manual installs you can customize the pattern in [gitlab.yml][0] using the `issue_closing_pattern` key. - -[0]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example -[1]: http://rubular.com/r/Xmbexed1OJ diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md deleted file mode 100644 index c46ce2ee203..00000000000 --- a/doc/customization/libravatar.md +++ /dev/null @@ -1,82 +0,0 @@ -# Use Libravatar service with GitLab - -GitLab by default supports [Gravatar](https://gravatar.com) avatar service. -Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is -[heavily based on gravatar](https://wiki.libravatar.org/api/). - -This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server. - -# Configuration - -In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set -the configuration options as follows: - -## For HTTP - -```yml - gravatar: - enabled: true - # gravatar URLs: possible placeholders: %{hash} %{size} %{email} - plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -## For HTTPS - -```yml - gravatar: - enabled: true - # gravatar URLs: possible placeholders: %{hash} %{size} %{email} - ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -## Self-hosted - -If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration -but the important part is to provide the same placeholders so GitLab can parse the URL correctly. - -For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is - -`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` - - -## Omnibus-gitlab example - -In `/etc/gitlab/gitlab.rb`: - -#### For http - -```ruby -gitlab_rails['gravatar_enabled'] = true -gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -#### For https - -```ruby -gitlab_rails['gravatar_enabled'] = true -gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - - -Run `sudo gitlab-ctl reconfigure` for changes to take effect. - - -## Default URL for missing images - -[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service. - -In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set. -For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` - - -## Usage examples - -#### For Microsoft Office 365 - -If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is -most useful in a corporate installation, where all users have access to Office 365. - -```ruby -gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' -gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' -``` diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md deleted file mode 100644 index a0cb234bea0..00000000000 --- a/doc/customization/welcome_message.md +++ /dev/null @@ -1,12 +0,0 @@ -# Customize the complete sign-in page - -Please see [Branded login page](branded_login_page.md) - -# Add a welcome message to the sign-in page (GitLab Community Edition) - -It is possible to add a markdown-formatted welcome message to your GitLab -sign-in page. Users of GitLab Enterprise Edition should use the [branded login -page feature](branded_login_page.md) instead. - -The welcome message (extra_sign_in_text) can now be set/changed in the Admin UI. -Admin area > Settings diff --git a/doc/downgrade_ee_to_ce/README.md b/doc/downgrade_ee_to_ce/README.md deleted file mode 100644 index 3625c4191b8..00000000000 --- a/doc/downgrade_ee_to_ce/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# Downgrading from EE to CE - -If you ever decide to downgrade your Enterprise Edition back to the Community -Edition, there are a few steps you need take before installing the CE package -on top of the current EE package, or, if you are in an installation from source, -before you change remotes and fetch the latest CE code. - -## Disable Enterprise-only features - -First thing to do is to disable the following features. - -### Authentication mechanisms - -Kerberos and Atlassian Crowd are only available on the Enterprise Edition, so -you should disable these mechanisms before downgrading and you should provide -alternative authentication methods to your users. - -### Git Annex - -Git Annex is also only available on the Enterprise Edition. This means that if -you have repositories that use Git Annex to store large files, these files will -no longer be easily available via Git. You should consider migrating these -repositories to use Git LFS before downgrading to the Community Edition. - -### Remove Jenkins CI Service entries from the database - -The `JenkinsService` class is only available on the Enterprise Edition codebase, -so if you downgrade to the Community Edition, you'll come across the following -error: - -``` -Completed 500 Internal Server Error in 497ms (ActiveRecord: 32.2ms) - -ActionView::Template::Error (The single-table inheritance mechanism failed to locate the subclass: 'JenkinsService'. This -error is raised because the column 'type' is reserved for storing the class in case of inheritance. Please rename this -column if you didn't intend it to be used for storing the inheritance class or overwrite Service.inheritance_column to -use another column for that information.) -``` - -All services are created automatically for every project you have, so in order -to avoid getting this error, you need to remove all instances of the -`JenkinsService` from your database: - -**Omnibus Installation** - -``` -$ sudo gitlab-rails runner "Service.where(type: 'JenkinsService').delete_all" -``` - -**Source Installation** - -``` -$ bundle exec rails runner "Service.where(type: 'JenkinsService').delete_all" production -``` - -## Downgrade to CE - -After performing the above mentioned steps, you are now ready to downgrade your -GitLab installation to the Community Edition. - -**Omnibus Installation** - -To downgrade an Omnibus installation, it is sufficient to install the Community -Edition package on top of the currently installed one. You can do this manually, -by directly [downloading the package](https://packages.gitlab.com/gitlab/gitlab-ce) -you need, or by adding our CE package repository and following the -[CE installation instructions](https://about.gitlab.com/downloads/). - -**Source Installation** - -To downgrade a source installation, you need to replace the current remote of -your GitLab installation with the Community Edition's remote, fetch the latest -changes, and checkout the latest stable branch: - -``` -$ git remote set-url origin git@gitlab.com:gitlab-org/gitlab-ce.git -$ git fetch --all -$ git checkout 8-x-stable -``` - -Remember to follow the correct [update guides](../update/README.md) to make -sure all dependencies are up to date. diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md deleted file mode 100644 index 3aa83975ace..00000000000 --- a/doc/gitlab-basics/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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/gitlab-basics/add-file.md b/doc/gitlab-basics/add-file.md deleted file mode 100644 index 57136ac5c39..00000000000 --- a/doc/gitlab-basics/add-file.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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/gitlab-basics/add-image.md b/doc/gitlab-basics/add-image.md deleted file mode 100644 index 476b48a217c..00000000000 --- a/doc/gitlab-basics/add-image.md +++ /dev/null @@ -1,62 +0,0 @@ -# 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/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md deleted file mode 100644 index 236b4248ea2..00000000000 --- a/doc/gitlab-basics/add-merge-request.md +++ /dev/null @@ -1,42 +0,0 @@ -# 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/gitlab-basics/basic-git-commands.md b/doc/gitlab-basics/basic-git-commands.md deleted file mode 100644 index c2a3415cbc4..00000000000 --- a/doc/gitlab-basics/basic-git-commands.md +++ /dev/null @@ -1,3 +0,0 @@ -# Basic Git commands - -This section is now merged into [Start using Git](start-using-git.md). diff --git a/doc/gitlab-basics/basicsimages/add_new_merge_request.png b/doc/gitlab-basics/basicsimages/add_new_merge_request.png deleted file mode 100644 index 9d93b217a59..00000000000 Binary files a/doc/gitlab-basics/basicsimages/add_new_merge_request.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/add_sshkey.png b/doc/gitlab-basics/basicsimages/add_sshkey.png deleted file mode 100644 index 2dede97aa40..00000000000 Binary files a/doc/gitlab-basics/basicsimages/add_sshkey.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/branch_info.png b/doc/gitlab-basics/basicsimages/branch_info.png deleted file mode 100644 index c5e38b552a5..00000000000 Binary files a/doc/gitlab-basics/basicsimages/branch_info.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/branch_name.png b/doc/gitlab-basics/basicsimages/branch_name.png deleted file mode 100644 index 06e77f5eea9..00000000000 Binary files a/doc/gitlab-basics/basicsimages/branch_name.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/branches.png b/doc/gitlab-basics/basicsimages/branches.png deleted file mode 100644 index c18fa83b968..00000000000 Binary files a/doc/gitlab-basics/basicsimages/branches.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/button-create-mr.png b/doc/gitlab-basics/basicsimages/button-create-mr.png deleted file mode 100644 index 457af459bb9..00000000000 Binary files a/doc/gitlab-basics/basicsimages/button-create-mr.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/click-on-new-group.png b/doc/gitlab-basics/basicsimages/click-on-new-group.png deleted file mode 100644 index 94b6d5756d3..00000000000 Binary files a/doc/gitlab-basics/basicsimages/click-on-new-group.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/commit_changes.png b/doc/gitlab-basics/basicsimages/commit_changes.png deleted file mode 100644 index 81588336f37..00000000000 Binary files a/doc/gitlab-basics/basicsimages/commit_changes.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/commit_message.png b/doc/gitlab-basics/basicsimages/commit_message.png deleted file mode 100644 index 0df2c32653c..00000000000 Binary files a/doc/gitlab-basics/basicsimages/commit_message.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/commits.png b/doc/gitlab-basics/basicsimages/commits.png deleted file mode 100644 index 7e606539077..00000000000 Binary files a/doc/gitlab-basics/basicsimages/commits.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/compare_branches.png b/doc/gitlab-basics/basicsimages/compare_branches.png deleted file mode 100644 index 7eebaed9075..00000000000 Binary files a/doc/gitlab-basics/basicsimages/compare_branches.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/create_file.png b/doc/gitlab-basics/basicsimages/create_file.png deleted file mode 100644 index 688e355cca2..00000000000 Binary files a/doc/gitlab-basics/basicsimages/create_file.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/create_group.png b/doc/gitlab-basics/basicsimages/create_group.png deleted file mode 100644 index 57da898abdc..00000000000 Binary files a/doc/gitlab-basics/basicsimages/create_group.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/edit_file.png b/doc/gitlab-basics/basicsimages/edit_file.png deleted file mode 100644 index afa68760108..00000000000 Binary files a/doc/gitlab-basics/basicsimages/edit_file.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/file_located.png b/doc/gitlab-basics/basicsimages/file_located.png deleted file mode 100644 index 1def489d16b..00000000000 Binary files a/doc/gitlab-basics/basicsimages/file_located.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/file_name.png b/doc/gitlab-basics/basicsimages/file_name.png deleted file mode 100644 index 9ac2f1c355f..00000000000 Binary files a/doc/gitlab-basics/basicsimages/file_name.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/find_file.png b/doc/gitlab-basics/basicsimages/find_file.png deleted file mode 100644 index 98639149a39..00000000000 Binary files a/doc/gitlab-basics/basicsimages/find_file.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/find_group.png b/doc/gitlab-basics/basicsimages/find_group.png deleted file mode 100644 index 5ac33c7e953..00000000000 Binary files a/doc/gitlab-basics/basicsimages/find_group.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/fork.png b/doc/gitlab-basics/basicsimages/fork.png deleted file mode 100644 index b1f94938613..00000000000 Binary files a/doc/gitlab-basics/basicsimages/fork.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/group_info.png b/doc/gitlab-basics/basicsimages/group_info.png deleted file mode 100644 index e78d84e4d80..00000000000 Binary files a/doc/gitlab-basics/basicsimages/group_info.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/groups.png b/doc/gitlab-basics/basicsimages/groups.png deleted file mode 100644 index b8104343afa..00000000000 Binary files a/doc/gitlab-basics/basicsimages/groups.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/https.png b/doc/gitlab-basics/basicsimages/https.png deleted file mode 100644 index 2a31b4cf751..00000000000 Binary files a/doc/gitlab-basics/basicsimages/https.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/image_file.png b/doc/gitlab-basics/basicsimages/image_file.png deleted file mode 100644 index 1061d9c5082..00000000000 Binary files a/doc/gitlab-basics/basicsimages/image_file.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/issue_title.png b/doc/gitlab-basics/basicsimages/issue_title.png deleted file mode 100644 index 7b69c705392..00000000000 Binary files a/doc/gitlab-basics/basicsimages/issue_title.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/issues.png b/doc/gitlab-basics/basicsimages/issues.png deleted file mode 100644 index 9354d05319e..00000000000 Binary files a/doc/gitlab-basics/basicsimages/issues.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/key.png b/doc/gitlab-basics/basicsimages/key.png deleted file mode 100644 index 321805cda98..00000000000 Binary files a/doc/gitlab-basics/basicsimages/key.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/merge_requests.png b/doc/gitlab-basics/basicsimages/merge_requests.png deleted file mode 100644 index 7601d40de47..00000000000 Binary files a/doc/gitlab-basics/basicsimages/merge_requests.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/new_issue.png b/doc/gitlab-basics/basicsimages/new_issue.png deleted file mode 100644 index 94e7503dd8b..00000000000 Binary files a/doc/gitlab-basics/basicsimages/new_issue.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/new_merge_request.png b/doc/gitlab-basics/basicsimages/new_merge_request.png deleted file mode 100644 index 9120d2b1ab1..00000000000 Binary files a/doc/gitlab-basics/basicsimages/new_merge_request.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/new_project.png b/doc/gitlab-basics/basicsimages/new_project.png deleted file mode 100644 index ac255270a66..00000000000 Binary files a/doc/gitlab-basics/basicsimages/new_project.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/newbranch.png b/doc/gitlab-basics/basicsimages/newbranch.png deleted file mode 100644 index da1a6b604ea..00000000000 Binary files a/doc/gitlab-basics/basicsimages/newbranch.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/paste_sshkey.png b/doc/gitlab-basics/basicsimages/paste_sshkey.png deleted file mode 100644 index 9880ddfead1..00000000000 Binary files a/doc/gitlab-basics/basicsimages/paste_sshkey.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/profile_settings.png b/doc/gitlab-basics/basicsimages/profile_settings.png deleted file mode 100644 index 5f2e7a7e10c..00000000000 Binary files a/doc/gitlab-basics/basicsimages/profile_settings.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/project_info.png b/doc/gitlab-basics/basicsimages/project_info.png deleted file mode 100644 index 6c06ff351fa..00000000000 Binary files a/doc/gitlab-basics/basicsimages/project_info.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/public_file_link.png b/doc/gitlab-basics/basicsimages/public_file_link.png deleted file mode 100644 index 1a60a3d880a..00000000000 Binary files a/doc/gitlab-basics/basicsimages/public_file_link.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/select-group.png b/doc/gitlab-basics/basicsimages/select-group.png deleted file mode 100644 index d02c2255ff2..00000000000 Binary files a/doc/gitlab-basics/basicsimages/select-group.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/select-group2.png b/doc/gitlab-basics/basicsimages/select-group2.png deleted file mode 100644 index fd40bce499b..00000000000 Binary files a/doc/gitlab-basics/basicsimages/select-group2.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/select_branch.png b/doc/gitlab-basics/basicsimages/select_branch.png deleted file mode 100644 index 3475b2df576..00000000000 Binary files a/doc/gitlab-basics/basicsimages/select_branch.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/select_project.png b/doc/gitlab-basics/basicsimages/select_project.png deleted file mode 100644 index 6d5aa439124..00000000000 Binary files a/doc/gitlab-basics/basicsimages/select_project.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/settings.png b/doc/gitlab-basics/basicsimages/settings.png deleted file mode 100644 index 9bf9c5a0d39..00000000000 Binary files a/doc/gitlab-basics/basicsimages/settings.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/shh_keys.png b/doc/gitlab-basics/basicsimages/shh_keys.png deleted file mode 100644 index d7ef4dafe77..00000000000 Binary files a/doc/gitlab-basics/basicsimages/shh_keys.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/submit_new_issue.png b/doc/gitlab-basics/basicsimages/submit_new_issue.png deleted file mode 100644 index 18944417085..00000000000 Binary files a/doc/gitlab-basics/basicsimages/submit_new_issue.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/title_description_mr.png b/doc/gitlab-basics/basicsimages/title_description_mr.png deleted file mode 100644 index e08eb628414..00000000000 Binary files a/doc/gitlab-basics/basicsimages/title_description_mr.png and /dev/null differ diff --git a/doc/gitlab-basics/basicsimages/white_space.png b/doc/gitlab-basics/basicsimages/white_space.png deleted file mode 100644 index 6363a09360e..00000000000 Binary files a/doc/gitlab-basics/basicsimages/white_space.png and /dev/null differ diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md deleted file mode 100644 index addd3b6b6eb..00000000000 --- a/doc/gitlab-basics/command-line-commands.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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/gitlab-basics/create-branch.md b/doc/gitlab-basics/create-branch.md deleted file mode 100644 index 7556b0f663e..00000000000 --- a/doc/gitlab-basics/create-branch.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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/gitlab-basics/create-group.md b/doc/gitlab-basics/create-group.md deleted file mode 100644 index f80ae62e442..00000000000 --- a/doc/gitlab-basics/create-group.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md deleted file mode 100644 index 5221d85b661..00000000000 --- a/doc/gitlab-basics/create-issue.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md deleted file mode 100644 index f737dffc024..00000000000 --- a/doc/gitlab-basics/create-project.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md deleted file mode 100644 index f31c353f2cf..00000000000 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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/gitlab-basics/fork-project.md b/doc/gitlab-basics/fork-project.md deleted file mode 100644 index 5f8b81ea919..00000000000 --- a/doc/gitlab-basics/fork-project.md +++ /dev/null @@ -1,19 +0,0 @@ -# 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/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md deleted file mode 100644 index 89ce8bcc3e8..00000000000 --- a/doc/gitlab-basics/start-using-git.md +++ /dev/null @@ -1,122 +0,0 @@ -# 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/hooks/custom_hooks.md b/doc/hooks/custom_hooks.md deleted file mode 100644 index 820934f97f1..00000000000 --- a/doc/hooks/custom_hooks.md +++ /dev/null @@ -1,41 +0,0 @@ -# Custom Git Hooks - -**Note: Custom git hooks must be configured on the filesystem of the GitLab -server. Only GitLab server administrators will be able to complete these tasks. -Please explore [webhooks](../web_hooks/web_hooks.md) as an option if you do not have filesystem access. For a user configurable Git Hooks interface, please see [GitLab Enterprise Edition Git Hooks](http://docs.gitlab.com/ee/git_hooks/git_hooks.html).** - -Git natively supports hooks that are executed on different actions. -Examples of server-side git hooks include pre-receive, post-receive, and update. -See -[Git SCM Server-Side Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks) -for more information about each hook type. - -As of gitlab-shell version 2.2.0 (which requires GitLab 7.5+), GitLab -administrators can add custom git hooks to any GitLab project. - -## Setup - -Normally, git hooks are placed in the repository or project's `hooks` directory. -GitLab creates a symlink from each project's `hooks` directory to the -gitlab-shell `hooks` directory for ease of maintenance between gitlab-shell -upgrades. As such, custom hooks are implemented a little differently. Behavior -is exactly the same once the hook is created, though. Follow these steps to -set up a custom hook. - -1. Pick a project that needs a custom git hook. -1. On the GitLab server, navigate to the project's repository directory. -For an installation from source the path is usually -`/home/git/repositories//.git`. For Omnibus installs the path is -usually `/var/opt/gitlab/git-data/repositories//.git`. -1. Create a new directory in this location called `custom_hooks`. -1. Inside the new `custom_hooks` directory, create a file with a name matching -the hook type. For a pre-receive hook the file name should be `pre-receive` with -no extension. -1. Make the hook file executable and make sure it's owned by git. -1. Write the code to make the git hook function as expected. Hooks can be -in any language. Ensure the 'shebang' at the top properly reflects the language -type. For example, if the script is in Ruby the shebang will probably be -`#!/usr/bin/env ruby`. - -That's it! Assuming the hook code is properly implemented the hook will fire -as appropriate. diff --git a/doc/incoming_email/README.md b/doc/incoming_email/README.md deleted file mode 100644 index 5a9a1582877..00000000000 --- a/doc/incoming_email/README.md +++ /dev/null @@ -1,302 +0,0 @@ -# Reply by email - -GitLab can be set up to allow users to comment on issues and merge requests by -replying to notification emails. - -## Requirement - -Reply by email requires an IMAP-enabled email account. GitLab allows you to use -three strategies for this feature: -- using email sub-addressing -- using a dedicated email address -- using a catch-all mailbox - -### Email sub-addressing - -**If your provider or server supports email sub-addressing, we recommend using it.** - -[Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is -a feature where any email to `user+some_arbitrary_tag@example.com` will end up -in the mailbox for `user@example.com`, and is supported by providers such as -Gmail, Google Apps, Yahoo! Mail, Outlook.com and iCloud, as well as the Postfix -mail server which you can run on-premises. - -### Dedicated email address - -This solution is really simple to set up: you just have to create an email -address dedicated to receive your users' replies to GitLab notifications. - -### Catch-all mailbox - -A [catch-all mailbox](https://en.wikipedia.org/wiki/Catch-all) for a domain will -"catch all" the emails addressed to the domain that do not exist in the mail -server. - -## How it works? - -### 1. GitLab sends a notification email - -When GitLab sends a notification and Reply by email is enabled, the `Reply-To` -header is set to the address defined in your GitLab configuration, with the -`%{key}` placeholder (if present) replaced by a specific "reply key". In -addition, this "reply key" is also added to the `References` header. - -### 2. You reply to the notification email - -When you reply to the notification email, your email client will: - -- send the email to the `Reply-To` address it got from the notification email -- set the `In-Reply-To` header to the value of the `Message-ID` header from the - notification email -- set the `References` header to the value of the `Message-ID` plus the value of - the notification email's `References` header. - -### 3. GitLab receives your reply to the notification email - -When GitLab receives your reply, it will look for the "reply key" in the -following headers, in this order: - -1. the `To` header -1. the `References` header - -If it finds a reply key, it will be able to leave your reply as a comment on -the entity the notification was about (issue, merge request, commit...). - -For more details about the `Message-ID`, `In-Reply-To`, and `References headers`, -please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). - -## Set it up - -If you want to use Gmail / Google Apps with Reply by email, make sure you have -[IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) -and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255). - -To set up a basic Postfix mail server with IMAP access on Ubuntu, follow -[these instructions](./postfix.md). - -### Omnibus package installations - -1. Find the `incoming_email` section in `/etc/gitlab/gitlab.rb`, enable the - feature and fill in the details for your specific IMAP server and email account: - - ```ruby - # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com - gitlab_rails['incoming_email_enabled'] = true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - gitlab_rails['incoming_email_address'] = "incoming+%{key}@gitlab.example.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - gitlab_rails['incoming_email_email'] = "incoming" - # Email account password - gitlab_rails['incoming_email_password'] = "[REDACTED]" - - # IMAP server host - gitlab_rails['incoming_email_host'] = "gitlab.example.com" - # IMAP server port - gitlab_rails['incoming_email_port'] = 143 - # Whether the IMAP server uses SSL - gitlab_rails['incoming_email_ssl'] = false - # Whether the IMAP server uses StartTLS - gitlab_rails['incoming_email_start_tls'] = false - - # The mailbox where incoming mail will end up. Usually "inbox". - gitlab_rails['incoming_email_mailbox_name'] = "inbox" - ``` - - ```ruby - # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com - gitlab_rails['incoming_email_enabled'] = true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@gmail.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - gitlab_rails['incoming_email_email'] = "gitlab-incoming@gmail.com" - # Email account password - gitlab_rails['incoming_email_password'] = "[REDACTED]" - - # IMAP server host - gitlab_rails['incoming_email_host'] = "imap.gmail.com" - # IMAP server port - gitlab_rails['incoming_email_port'] = 993 - # Whether the IMAP server uses SSL - gitlab_rails['incoming_email_ssl'] = true - # Whether the IMAP server uses StartTLS - gitlab_rails['incoming_email_start_tls'] = false - - # The mailbox where incoming mail will end up. Usually "inbox". - gitlab_rails['incoming_email_mailbox_name'] = "inbox" - ``` - -1. Reconfigure GitLab and restart mailroom for the changes to take effect: - - ```sh - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart mailroom - ``` - -1. Verify that everything is configured correctly: - - ```sh - sudo gitlab-rake gitlab:incoming_email:check - ``` - -1. Reply by email should now be working. - -### Installations from source - -1. Go to the GitLab installation directory: - - ```sh - cd /home/git/gitlab - ``` - -1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature - and fill in the details for your specific IMAP server and email account: - - ```sh - sudo editor config/gitlab.yml - ``` - - ```yaml - # Configuration for Postfix mail server, assumes mailbox incoming@gitlab.example.com - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - address: "incoming+%{key}@gitlab.example.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - user: "incoming" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "gitlab.example.com" - # IMAP server port - port: 143 - # Whether the IMAP server uses SSL - ssl: false - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - ``` - - ```yaml - # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - address: "gitlab-incoming+%{key}@gmail.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - user: "gitlab-incoming@gmail.com" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "imap.gmail.com" - # IMAP server port - port: 993 - # Whether the IMAP server uses SSL - ssl: true - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - ``` - -1. Enable `mail_room` in the init script at `/etc/default/gitlab`: - - ```sh - sudo mkdir -p /etc/default - echo 'mail_room_enabled=true' | sudo tee -a /etc/default/gitlab - ``` - -1. Restart GitLab: - - ```sh - sudo service gitlab restart - ``` - -1. Verify that everything is configured correctly: - - ```sh - sudo -u git -H bundle exec rake gitlab:incoming_email:check RAILS_ENV=production - ``` - -1. Reply by email should now be working. - -### Development - -1. Go to the GitLab installation directory. - -1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account: - - ```yaml - # Configuration for Gmail / Google Apps, assumes mailbox gitlab-incoming@gmail.com - incoming_email: - enabled: true - - # The email address including the `%{key}` placeholder that will be replaced to reference the item being replied to. - # The placeholder can be omitted but if present, it must appear in the "user" part of the address (before the `@`). - address: "gitlab-incoming+%{key}@gmail.com" - - # Email account username - # With third party providers, this is usually the full email address. - # With self-hosted email servers, this is usually the user part of the email address. - user: "gitlab-incoming@gmail.com" - # Email account password - password: "[REDACTED]" - - # IMAP server host - host: "imap.gmail.com" - # IMAP server port - port: 993 - # Whether the IMAP server uses SSL - ssl: true - # Whether the IMAP server uses StartTLS - start_tls: false - - # The mailbox where incoming mail will end up. Usually "inbox". - mailbox: "inbox" - ``` - - As mentioned, the part after `+` is ignored, and this will end up in the mailbox for `gitlab-incoming@gmail.com`. - -1. Uncomment the `mail_room` line in your `Procfile`: - - ```yaml - mail_room: bundle exec mail_room -q -c config/mail_room.yml - ``` - -1. Restart GitLab: - - ```sh - bundle exec foreman start - ``` - -1. Verify that everything is configured correctly: - - ```sh - bundle exec rake gitlab:incoming_email:check RAILS_ENV=development - ``` - -1. Reply by email should now be working. diff --git a/doc/incoming_email/postfix.md b/doc/incoming_email/postfix.md deleted file mode 100644 index 787d21f7f8f..00000000000 --- a/doc/incoming_email/postfix.md +++ /dev/null @@ -1,321 +0,0 @@ -# Set up Postfix for Reply by email - -This document will take you through the steps of setting up a basic Postfix mail server with IMAP authentication on Ubuntu, to be used with Reply by email. - -The instructions make the assumption that you will be using the email address `incoming@gitlab.example.com`, that is, username `incoming` on host `gitlab.example.com`. Don't forget to change it to your actual host when executing the example code snippets. - -## Configure your server firewall - -1. Open up port 25 on your server so that people can send email into the server over SMTP. -2. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP. - -## Install packages - -1. Install the `postfix` package if it is not installed already: - - ```sh - sudo apt-get install postfix - ``` - - When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com`. - -1. Install the `mailutils` package. - - ```sh - sudo apt-get install mailutils - ``` - -## Create user - -1. Create a user for incoming email. - - ```sh - sudo useradd -m -s /bin/bash incoming - ``` - -1. Set a password for this user. - - ```sh - sudo passwd incoming - ``` - - Be sure not to forget this, you'll need it later. - -## Test the out-of-the-box setup - -1. Connect to the local SMTP server: - - ```sh - telnet localhost 25 - ``` - - You should see a prompt like this: - - ```sh - Trying 127.0.0.1... - Connected to localhost. - Escape character is '^]'. - 220 gitlab.example.com ESMTP Postfix (Ubuntu) - ``` - - If you get a `Connection refused` error instead, verify that `postfix` is running: - - ```sh - sudo postfix status - ``` - - If it is not, start it: - - ```sh - sudo postfix start - ``` - -1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: - - ``` - ehlo localhost - mail from: root@localhost - rcpt to: incoming@localhost - data - Subject: Re: Some issue - - Sounds good! - . - quit - ``` - - _**Note:** The `.` is a literal period on its own line._ - - _**Note:** If you receive an error after entering `rcpt to: incoming@localhost` - then your Postfix `my_network` configuration is not correct. The error will - say 'Temporary lookup failure'. See - [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._ - -1. Check if the `incoming` user received the email: - - ```sh - su - incoming - mail - ``` - - You should see output like this: - - ``` - "/var/mail/incoming": 1 message 1 unread - >U 1 root@localhost 59/2842 Re: Some issue - ``` - - Quit the mail app: - - ```sh - q - ``` - -1. Log out of the `incoming` account and go back to being `root`: - - ```sh - logout - ``` - -## Configure Postfix to use Maildir-style mailboxes - -Courier, which we will install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox. - -1. Configure Postfix to use Maildir-style mailboxes: - - ```sh - sudo postconf -e "home_mailbox = Maildir/" - ``` - -1. Restart Postfix: - - ```sh - sudo /etc/init.d/postfix restart - ``` - -1. Test the new setup: - - 1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_. - 1. Check if the `incoming` user received the email: - - ```sh - su - incoming - MAIL=/home/incoming/Maildir - mail - ``` - - You should see output like this: - - ``` - "/home/incoming/Maildir": 1 message 1 unread - >U 1 root@localhost 59/2842 Re: Some issue - ``` - - Quit the mail app: - - ```sh - q - ``` - - _**Note:** If `mail` returns an error `Maildir: Is a directory` then your - version of `mail` doesn't support Maildir style mailboxes. Install - `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then, - try the above steps again, substituting `heirloom-mailx` for the `mail` - command._ - -1. Log out of the `incoming` account and go back to being `root`: - - ```sh - logout - ``` - -## Install the Courier IMAP server - -1. Install the `courier-imap` package: - - ```sh - sudo apt-get install courier-imap - ``` - -## Configure Postfix to receive email from the internet - -1. Let Postfix know about the domains that it should consider local: - - ```sh - sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost" - ``` - -1. Let Postfix know about the IPs that it should consider part of the LAN: - - We'll assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network. - - ```sh - sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24" - ``` - -1. Configure Postfix to receive mail on all interfaces, which includes the internet: - - ```sh - sudo postconf -e "inet_interfaces = all" - ``` - -1. Configure Postfix to use the `+` delimiter for sub-addressing: - - ```sh - sudo postconf -e "recipient_delimiter = +" - ``` - -1. Restart Postfix: - - ```sh - sudo service postfix restart - ``` - -## Test the final setup - -1. Test SMTP under the new setup: - - 1. Connect to the SMTP server: - - ```sh - telnet gitlab.example.com 25 - ``` - - You should see a prompt like this: - - ```sh - Trying 123.123.123.123... - Connected to gitlab.example.com. - Escape character is '^]'. - 220 gitlab.example.com ESMTP Postfix (Ubuntu) - ``` - - If you get a `Connection refused` error instead, make sure your firewall is setup to allow inbound traffic on port 25. - - 1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: - - ``` - ehlo gitlab.example.com - mail from: root@gitlab.example.com - rcpt to: incoming@gitlab.example.com - data - Subject: Re: Some issue - - Sounds good! - . - quit - ``` - - (Note: The `.` is a literal period on its own line) - - 1. Check if the `incoming` user received the email: - - ```sh - su - incoming - MAIL=/home/incoming/Maildir - mail - ``` - - You should see output like this: - - ``` - "/home/incoming/Maildir": 1 message 1 unread - >U 1 root@gitlab.example.com 59/2842 Re: Some issue - ``` - - Quit the mail app: - - ```sh - q - ``` - - 1. Log out of the `incoming` account and go back to being `root`: - - ```sh - logout - ``` - -1. Test IMAP under the new setup: - - 1. Connect to the IMAP server: - - ```sh - telnet gitlab.example.com 143 - ``` - - You should see a prompt like this: - - ```sh - Trying 123.123.123.123... - Connected to mail.example.gitlab.com. - Escape character is '^]'. - - OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information. - ``` - - 1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt: - - ``` - a login incoming PASSWORD - ``` - - Replace PASSWORD with the password you set on the `incoming` user earlier. - - You should see output like this: - - ``` - a OK LOGIN Ok. - ``` - - 1. Disconnect from the IMAP server: - - ```sh - a logout - ``` - -## Done! - -If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [Reply by email](./README.md) guide to configure GitLab. - ---------- - -_This document was adapted from https://help.ubuntu.com/community/PostfixBasicSetupHowto, by contributors to the Ubuntu documentation wiki._ diff --git a/doc/integration/README.md b/doc/integration/README.md deleted file mode 100644 index fd330dd7a7d..00000000000 --- a/doc/integration/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# GitLab Integration - -GitLab integrates with multiple third-party services to allow external issue -trackers and external authentication. - -See the documentation below for details on how to configure these services. - -- [Jira](../project_services/jira.md) Integrate with the JIRA issue tracker -- [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. -- [LDAP](ldap.md) Set up sign in via LDAP -- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd and Azure -- [SAML](saml.md) Configure GitLab as a SAML 2.0 Service Provider -- [CAS](cas.md) Configure GitLab to sign in using CAS -- [Slack](slack.md) Integrate with the Slack chat service -- [OAuth2 provider](oauth_provider.md) OAuth2 application creation -- [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages -- [reCAPTCHA](recaptcha.md) Configure GitLab to use Google reCAPTCHA for new users -- [Akismet](akismet.md) Configure Akismet to stop spam - -GitLab Enterprise Edition contains [advanced Jenkins support][jenkins]. - -[jenkins]: http://docs.gitlab.com/ee/integration/jenkins.html - - -## Project services - -Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, -Pivotal Tracker, and Slack are available in the form of a [Project Service][]. - -[Project Service]: ../project_services/project_services.md - -## SSL certificate errors - -When trying to integrate GitLab with services that are using self-signed certificates, -it is very likely that SSL certificate errors will occur on different parts of the -application, most likely Sidekiq. There are 2 approaches you can take to solve this: - -1. Add the root certificate to the trusted chain of the OS. -1. If using Omnibus, you can add the certificate to GitLab's trusted certificates. - -**OS main trusted chain** - -This [resource](http://kb.kerio.com/product/kerio-connect/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) -has all the information you need to add a certificate to the main trusted chain. - -This [answer](http://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) -at SuperUser also has relevant information. - -**Omnibus Trusted Chain** - -It is enough to concatenate the certificate to the main trusted certificate: - -```bash -cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem -``` - -After that restart GitLab with: - -```bash -sudo gitlab-ctl restart -``` diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md deleted file mode 100644 index 5cc09bd536d..00000000000 --- a/doc/integration/akismet.md +++ /dev/null @@ -1,30 +0,0 @@ -# Akismet - -GitLab leverages [Akismet](http://akismet.com) to protect against spam. Currently -GitLab uses Akismet to prevent users who are not members of a project from -creating spam via the GitLab API. Detected spam will be rejected, and -an entry in the "Spam Log" section in the Admin page will be created. - -Privacy note: GitLab submits the user's IP and user agent to Akismet. Note that -adding a user to a project will disable the Akismet check and prevent this -from happening. - -## Configuration - -To use Akismet: - -1. Go to the URL: https://akismet.com/account/ - -2. Sign-in or create a new account. - -3. Click on "Show" to reveal the API key. - -4. Go to Applications Settings on Admin Area (`admin/application_settings`) - -5. Check the `Enable Akismet` checkbox - -6. Fill in the API key from step 3. - -7. Save the configuration. - -![Screenshot of Akismet settings](img/akismet_settings.png) diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md deleted file mode 100644 index e5247082a89..00000000000 --- a/doc/integration/auth0.md +++ /dev/null @@ -1,89 +0,0 @@ -# Auth0 OmniAuth Provider - -To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an -application. - -1. Sign in to the [Auth0 Console](https://manage.auth0.com). If you need to -create an account, you can do so at the same link. - -1. Select "New App/API". - -1. Provide the Application Name ('GitLab' works fine). - -1. Once created, you should see the Quick Start options. Disregard them and -select 'Settings' above the Quick Start options. - -1. At the top of the Settings screen, you should see your Domain, Client ID and -Client Secret. Take note of these as you'll need to put them in the -configuration file. For example: - - Domain: `test1234.auth0.com` - - Client ID: `t6X8L2465bNePWLOvt9yi41i` - - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` - -1. Fill in the Allowed Callback URLs: - - http://`YOUR_GITLAB_URL`/users/auth/auth0/callback (or) - - https://`YOUR_GITLAB_URL`/users/auth/auth0/callback - -1. Fill in the Allowed Origins (CORS): - - http://`YOUR_GITLAB_URL` (or) - - https://`YOUR_GITLAB_URL` - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) -for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "auth0", - "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID'', - client_secret: 'YOUR_AUTH0_CLIENT_SECRET', - namespace: 'YOUR_AUTH0_DOMAIN' - } - } - ] - ``` - - For installations from source: - - ```yaml - - { name: 'auth0', - args: { - client_id: 'YOUR_AUTH0_CLIENT_ID', - client_secret: 'YOUR_AUTH0_CLIENT_SECRET', - namespace: 'YOUR_AUTH0_DOMAIN' - } - } - ``` - -1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page -from step 5. - -1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console -page from step 5. - -1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) -for the changes to take effect. - -On the sign in page there should now be an Auth0 icon below the regular sign in -form. Click the icon to begin the authentication process. Auth0 will ask the -user to sign in and authorize the GitLab application. If everything goes well -the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/azure.md b/doc/integration/azure.md deleted file mode 100644 index 48dddf7df44..00000000000 --- a/doc/integration/azure.md +++ /dev/null @@ -1,83 +0,0 @@ -# Microsoft Azure OAuth2 OmniAuth Provider - -To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. - -1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com>). - -1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab. - -1. Select "Applications" at the top bar and click the "Add" button the bottom. - -1. Select "Add an application my organization is developing". - -1. Provide the project information and click the "Next" button. - - Name: 'GitLab' works just fine here. - - Type: 'WEB APPLICATION AND/OR WEB API' - -1. On the "App properties" page enter the needed URI's and click the "Complete" button. - - SIGN-IN URL: Enter the URL of your GitLab installation (e.g 'https://gitlab.mycompany.com/') - - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g 'https://mycompany.onmicrosoft.com/gitlab') - -1. Select "Configure" in the top menu. - -1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. https://gitlab.mycompany.com/users/auth/azure_oauth2/callback). - -1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu.. - -1. Note the "CLIENT ID" and the "CLIENT SECRET". - -1. Select "View endpoints" from the bottom menu. - -1. You will see lots of endpoint URLs in the form 'https://login.microsoftonline.com/TENANT ID/...', note down the TENANT ID part of one of those endpoints. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "azure_oauth2", - "args" => { - "client_id" => "CLIENT ID", - "client_secret" => "CLIENT SECRET", - "tenant_id" => "TENANT ID", - } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'azure_oauth2', - args: { client_id: "CLIENT ID", - client_secret: "CLIENT SECRET", - tenant_id: "TENANT ID" } } - ``` - -1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Microsoft icon below the regular sign in form. Click the icon to begin the authentication process. Microsoft will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md deleted file mode 100644 index 63432b04432..00000000000 --- a/doc/integration/bitbucket.md +++ /dev/null @@ -1,140 +0,0 @@ -# Integrate your server with Bitbucket - -Import projects from Bitbucket and login to your GitLab instance with your Bitbucket account. - -To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket. -Bitbucket will generate an application ID and secret key for you to use. - -1. Sign in to Bitbucket. - -1. Navigate to your individual user settings or a team's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or a team - that is entirely up to you. - -1. Select "OAuth" in the left menu. - -1. Select "Add consumer". - -1. Provide the required details. - - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. - - Application description: Fill this in if you wish. - - URL: The URL to your GitLab installation. 'https://gitlab.company.com' -1. Select "Save". - -1. You should now see a Key and Secret in the list of OAuth customers. - Keep this page open as you continue configuration. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "bitbucket", - "app_id" => "YOUR_KEY", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://bitbucket.org/" - } - ] - ``` - - For installation from source: - - ``` - - { name: 'bitbucket', app_id: 'YOUR_KEY', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the key from the Bitbucket application page from step 7. - -1. Change 'YOUR_APP_SECRET' to the secret from the Bitbucket application page from step 7. - -1. Save the configuration file. - -1. If you're using the omnibus package, reconfigure GitLab (```gitlab-ctl reconfigure```). - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Bitbucket icon below the regular sign in form. -Click the icon to begin the authentication process. Bitbucket will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. - -## Bitbucket project import - -To allow projects to be imported directly into GitLab, Bitbucket requires two extra setup steps compared to GitHub and GitLab.com. - -Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and instead requires GitLab to use SSH and identify itself using your GitLab server's SSH key. - -### Step 1: Public key - -To be able to access repositories on Bitbucket, GitLab will automatically register your public key with Bitbucket as a deploy key for the repositories to be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa.pub`, which will expand to `/home/git/.ssh/bitbucket_rsa.pub` in most configurations. - -If you have that file in place, you're all set and should see the "Import projects from Bitbucket" option enabled. If you don't, do the following: - -1. Create a new SSH key: - - ```sh - sudo -u git -H ssh-keygen - ``` - - When asked `Enter file in which to save the key` specify the correct path, eg. `/home/git/.ssh/bitbucket_rsa`. - Make sure to use an **empty passphrase**. - -1. Configure SSH client to use your new key: - - Open the SSH configuration file of the git user. - - ```sh - sudo editor /home/git/.ssh/config - ``` - - Add a host configuration for `bitbucket.org`. - - ```sh - Host bitbucket.org - IdentityFile ~/.ssh/bitbucket_rsa - User git - ``` - -### Step 2: Known hosts - -To allow GitLab to connect to Bitbucket over SSH, you need to add 'bitbucket.org' to your GitLab server's known SSH hosts. Take the following steps to do so: - -1. Manually connect to 'bitbucket.org' over SSH, while logged in as the `git` account that GitLab will use: - - ```sh - sudo -u git -H ssh bitbucket.org - ``` - -1. Verify the RSA key fingerprint you'll see in the response matches the one in the [Bitbucket documentation](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket'spublickeyfingerprints) (the specific IP address doesn't matter): - - ```sh - The authenticity of host 'bitbucket.org (207.223.240.182)' can't be established. - RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40. - Are you sure you want to continue connecting (yes/no)? - ``` - -1. If the fingerprint matches, type `yes` to continue connecting and have 'bitbucket.org' be added to your known hosts. - -1. Your GitLab server is now able to connect to Bitbucket over SSH. - -1. Restart GitLab to allow it to find the new public key. - -You should now see the "Import projects from Bitbucket" option on the New Project page enabled. diff --git a/doc/integration/cas.md b/doc/integration/cas.md deleted file mode 100644 index e34e306f9ac..00000000000 --- a/doc/integration/cas.md +++ /dev/null @@ -1,65 +0,0 @@ -# CAS OmniAuth Provider - -To enable the CAS OmniAuth provider you must register your application with your CAS instance. This requires the service URL GitLab will supply to CAS. It should be something like: `https://gitlab.example.com:443/users/auth/cas3/callback?url`. By default handling for SLO is enabled, you only need to configure CAS for backchannel logout. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name"=> "cas3", - "label"=> "cas", - "args"=> { - "url"=> 'CAS_SERVER', - "login_url"=> '/CAS_PATH/login', - "service_validate_url"=> '/CAS_PATH/p3/serviceValidate', - "logout_url"=> '/CAS_PATH/logout' - } - } - ] - ``` - - - For installations from source: - - ``` - - { name: 'cas3', - label: 'cas', - args: { - url: 'CAS_SERVER', - login_url: '/CAS_PATH/login', - service_validate_url: '/CAS_PATH/p3/serviceValidate', - logout_url: '/CAS_PATH/logout'} } - ``` - -1. Change 'CAS_PATH' to the root of your CAS instance (ie. `cas`). - -1. If your CAS instance does not use default TGC lifetimes, update the `cas3.session_duration` to at least the current TGC maximum lifetime. To explicitly disable SLO, regardless of CAS settings, set this to 0. - -1. Save the configuration file. - -1. Run `gitlab-ctl reconfigure` for the omnibus package. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a CAS tab in the sign in form. diff --git a/doc/integration/crowd.md b/doc/integration/crowd.md deleted file mode 100644 index 40d93aef2a9..00000000000 --- a/doc/integration/crowd.md +++ /dev/null @@ -1,58 +0,0 @@ -# Crowd OmniAuth Provider - -To enable the Crowd OmniAuth provider you must register your application with Crowd. To configure Crowd integration you need an application name and password. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "crowd", - "args" => { - "crowd_server_url" => "CROWD", - "application_name" => "YOUR_APP_NAME", - "application_password" => "YOUR_APP_PASSWORD" - } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'crowd', - args: { - crowd_server_url: 'CROWD SERVER URL', - application_name: 'YOUR_APP_NAME', - application_password: 'YOUR_APP_PASSWORD' } } - ``` - -1. Change 'YOUR_APP_NAME' to the application name from Crowd applications page. - -1. Change 'YOUR_APP_PASSWORD' to the application password you've set. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Crowd tab in the sign in form. \ No newline at end of file diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md deleted file mode 100644 index a2d7e922aad..00000000000 --- a/doc/integration/external-issue-tracker.md +++ /dev/null @@ -1,30 +0,0 @@ -# External issue tracker - -GitLab has a great issue tracker but you can also use an external one such as -Jira or Redmine. Issue trackers are configurable per GitLab project and allow -you to do the following: - -- the **Issues** link on the GitLab project pages takes you to the appropriate - issue index of the external tracker -- clicking **New issue** on the project dashboard creates a new issue on the - external tracker - -## Configuration - -The configuration is done via a project's **Services**. - -### Project Service - -To enable an external issue tracker you must configure the appropriate **Service**. -Visit the links below for details: - -- [Redmine](../project_services/redmine.md) -- [Jira](../project_services/jira.md) - -### Service Template - -To save you the hassle from configuring each project's service individually, -GitLab provides the ability to set Service Templates which can then be -overridden in each project's settings. - -Read more on [Services Templates](../project_services/services_templates.md). diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md deleted file mode 100644 index 77bb75cbfca..00000000000 --- a/doc/integration/facebook.md +++ /dev/null @@ -1,97 +0,0 @@ -# Facebook OAuth2 OmniAuth Provider - -To enable the Facebook OmniAuth provider you must register your application with Facebook. Facebook will generate an app ID and secret key for you to use. - -1. Sign in to the [Facebook Developer Platform](https://developers.facebook.com/). - -1. Choose "My Apps" > "Add a New App" - -1. Select the type "Website" - -1. Enter a name for your app. This can be anything. Consider something like "<Organization>'s GitLab" or "<Your Name>'s GitLab" or -something else descriptive. - -1. Choose "Create New Facebook App ID" - -1. Select a Category, for example "Productivity" - -1. Choose "Create App ID" - -1. Enter the address of your GitLab installation at the bottom of the package - - ![Facebook Website URL](img/facebook_website_url.png) - -1. Choose "Next" - -1. Choose "Skip Quick Start" in the upper right corner - -1. Choose "Settings" in the menu on the left - -1. Fill in a contact email for your app - - ![Facebook App Settings](img/facebook_app_settings.png) - -1. Choose "Save Changes" - -1. Choose "Status & Review" in the menu on the left - -1. Change the switch on the right from No to Yes - -1. Choose "Confirm" when prompted to make the app public - -1. Choose "Dashboard" in the menu on the left - -1. Choose "Show" next to the hidden "App Secret" - -1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration. - - ![Facebook API Keys](img/facebook_api_keys.png) - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "facebook", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" - } - ] - ``` - - For installations from source: - - ``` - - { name: 'facebook', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the API key from Facebook page in step 10. - -1. Change 'YOUR_APP_SECRET' to the API secret from the Facebook page in step 10. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Facebook icon below the regular sign in form. Click the icon to begin the authentication process. Facebook will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/github.md b/doc/integration/github.md deleted file mode 100644 index e7497e475c9..00000000000 --- a/doc/integration/github.md +++ /dev/null @@ -1,95 +0,0 @@ -# Integrate your server with GitHub - -Import projects from GitHub and login to your GitLab instance with your GitHub account. - -To enable the GitHub OmniAuth provider you must register your application with GitHub. -GitHub will generate an application ID and secret key for you to use. - -1. Sign in to GitHub. - -1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. - -1. Select "OAuth applications" in the left menu. - -1. If you already have applications listed, switch to the "Developer applications" tab. - -1. Select "Register new application". - -1. Provide the required details. - - Application name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. - - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' - - Application description: Fill this in if you wish. - - Default authorization callback URL is '${YOUR_DOMAIN}/import/github/callback' -1. Select "Register application". - -1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). - Keep this page open as you continue configuration. - ![GitHub app](img/github_app.png) - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "github", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://github.com/", - "args" => { "scope" => "user:email" } - } - ] - ``` - - For installation from source: - - For GitHub.com: - - ``` - - { name: 'github', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'user:email' } } - ``` - - - For GitHub Enterprise: - - ``` - - { name: 'github', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - url: "https://github.example.com/", - args: { scope: 'user:email' } } - ``` - - __Replace `https://github.example.com/` with your GitHub URL.__ - -1. Change 'YOUR_APP_ID' to the client ID from the GitHub application page from step 7. - -1. Change 'YOUR_APP_SECRET' to the client secret from the GitHub application page from step 7. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a GitHub icon below the regular sign in form. -Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md deleted file mode 100644 index b215cc7c609..00000000000 --- a/doc/integration/gitlab.md +++ /dev/null @@ -1,84 +0,0 @@ -# Integrate your server with GitLab.com - -Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. - -To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. - -1. Sign in to GitLab.com - -1. Navigate to your profile settings. - -1. Select "Applications" in the left menu. - -1. Select "New application". - -1. Provide the required details. - - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or something else descriptive. - - Redirect URI: - - ``` - http://your-gitlab.example.com/import/gitlab/callback - http://your-gitlab.example.com/users/auth/gitlab/callback - ``` - - The first link is required for the importer and second for the authorization. - -1. Select "Submit". - -1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). - Keep this page open as you continue configuration. - ![GitLab app](img/gitlab_app.png) - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "gitlab", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "scope" => "api" } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'gitlab', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'api' } } - ``` - -1. Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page. - -1. Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a GitLab.com icon below the regular sign in form. -Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to your GitLab instance and will be signed in. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md deleted file mode 100644 index 05a91d9bef9..00000000000 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ /dev/null @@ -1,22 +0,0 @@ -# Gmail actions buttons for GitLab - -GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). - -If correctly setup, emails that require an action will be marked in Gmail. - -![gmail_actions_button.png](img/gmail_action_buttons_for_gitlab.png) - -To get this functioning, you need to be registered with Google. -[See how to register with Google in this document.](https://developers.google.com/gmail/markup/registering-with-google) - -*This process has a lot of steps so make sure that you fulfill all requirements set by Google.* -*Your application will be rejected by Google if you fail to do so.* - -Pay close attention to: - -* Email account used by GitLab to send notification emails needs to have "Consistent history of sending a high volume of mail from your domain (order of hundred emails a day minimum to Gmail) for a few weeks at least". -* "A very very low rate of spam complaints from users." -* Emails must be authenticated via DKIM or SPF -* Before sending the final form("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you will have to find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there. - -You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/1517). diff --git a/doc/integration/google.md b/doc/integration/google.md deleted file mode 100644 index 82978b68a34..00000000000 --- a/doc/integration/google.md +++ /dev/null @@ -1,89 +0,0 @@ -# Google OAuth2 OmniAuth Provider - -To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use. - -1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. - -1. Select "Create Project". - -1. Provide the project information - - Project name: 'GitLab' works just fine here. - - Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. -1. Refresh the page. You should now see your new project in the list. Click on the project. - -1. Select the "Google APIs" tab in the Overview. - -1. Select and enable the following Google APIs - listed under "Popular APIs" - - Enable `Contacts API` - - Enable `Google+ API` - -1. Select "Credentials" in the submenu. - -1. Select "Create New Client ID". - -1. Fill in the required information - - Application type: "Web Application" - - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. - - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' -1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration. ![Google app](img/google_app.png) - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "google_oauth2", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "access_type" => "offline", "approval_prompt" => '' } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'google_oauth2', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { access_type: 'offline', approval_prompt: '' } } - ``` - -1. Change 'YOUR_APP_ID' to the client ID from the Google Developer page from step 10. - -1. Change 'YOUR_APP_SECRET' to the client secret from the Google Developer page from step 10. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. - -## Further Configuration - -This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding. - -At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable. - -1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window). -1. Scroll down until you find "Product Name". Change the product name to something more descriptive. -1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. diff --git a/doc/integration/img/akismet_settings.png b/doc/integration/img/akismet_settings.png deleted file mode 100644 index ccdd3adb1c5..00000000000 Binary files a/doc/integration/img/akismet_settings.png and /dev/null differ diff --git a/doc/integration/img/enabled-oauth-sign-in-sources.png b/doc/integration/img/enabled-oauth-sign-in-sources.png deleted file mode 100644 index 95f8bbdcd24..00000000000 Binary files a/doc/integration/img/enabled-oauth-sign-in-sources.png and /dev/null differ diff --git a/doc/integration/img/facebook_api_keys.png b/doc/integration/img/facebook_api_keys.png deleted file mode 100644 index d6c44ac0f11..00000000000 Binary files a/doc/integration/img/facebook_api_keys.png and /dev/null differ diff --git a/doc/integration/img/facebook_app_settings.png b/doc/integration/img/facebook_app_settings.png deleted file mode 100644 index 30dd21e198a..00000000000 Binary files a/doc/integration/img/facebook_app_settings.png and /dev/null differ diff --git a/doc/integration/img/facebook_website_url.png b/doc/integration/img/facebook_website_url.png deleted file mode 100644 index dc3088bb2fa..00000000000 Binary files a/doc/integration/img/facebook_website_url.png and /dev/null differ diff --git a/doc/integration/img/github_app.png b/doc/integration/img/github_app.png deleted file mode 100644 index d890345ced9..00000000000 Binary files a/doc/integration/img/github_app.png and /dev/null differ diff --git a/doc/integration/img/gitlab_app.png b/doc/integration/img/gitlab_app.png deleted file mode 100644 index 3f9391a821b..00000000000 Binary files a/doc/integration/img/gitlab_app.png and /dev/null differ diff --git a/doc/integration/img/gmail_action_buttons_for_gitlab.png b/doc/integration/img/gmail_action_buttons_for_gitlab.png deleted file mode 100644 index b08f54d137b..00000000000 Binary files a/doc/integration/img/gmail_action_buttons_for_gitlab.png and /dev/null differ diff --git a/doc/integration/img/google_app.png b/doc/integration/img/google_app.png deleted file mode 100644 index 5a62ad35009..00000000000 Binary files a/doc/integration/img/google_app.png and /dev/null differ diff --git a/doc/integration/img/oauth_provider_admin_application.png b/doc/integration/img/oauth_provider_admin_application.png deleted file mode 100644 index a2d8e14c120..00000000000 Binary files a/doc/integration/img/oauth_provider_admin_application.png and /dev/null differ diff --git a/doc/integration/img/oauth_provider_application_form.png b/doc/integration/img/oauth_provider_application_form.png deleted file mode 100644 index 3a676b22393..00000000000 Binary files a/doc/integration/img/oauth_provider_application_form.png and /dev/null differ diff --git a/doc/integration/img/oauth_provider_application_id_secret.png b/doc/integration/img/oauth_provider_application_id_secret.png deleted file mode 100644 index 6d68df001af..00000000000 Binary files a/doc/integration/img/oauth_provider_application_id_secret.png and /dev/null differ diff --git a/doc/integration/img/oauth_provider_authorized_application.png b/doc/integration/img/oauth_provider_authorized_application.png deleted file mode 100644 index efc3b807d71..00000000000 Binary files a/doc/integration/img/oauth_provider_authorized_application.png and /dev/null differ diff --git a/doc/integration/img/oauth_provider_user_wide_applications.png b/doc/integration/img/oauth_provider_user_wide_applications.png deleted file mode 100644 index 45ad8a6d468..00000000000 Binary files a/doc/integration/img/oauth_provider_user_wide_applications.png and /dev/null differ diff --git a/doc/integration/img/twitter_app_api_keys.png b/doc/integration/img/twitter_app_api_keys.png deleted file mode 100644 index 1076337172a..00000000000 Binary files a/doc/integration/img/twitter_app_api_keys.png and /dev/null differ diff --git a/doc/integration/img/twitter_app_details.png b/doc/integration/img/twitter_app_details.png deleted file mode 100644 index b95e8af8a74..00000000000 Binary files a/doc/integration/img/twitter_app_details.png and /dev/null differ diff --git a/doc/integration/jira.md b/doc/integration/jira.md deleted file mode 100644 index 78aa6634116..00000000000 --- a/doc/integration/jira.md +++ /dev/null @@ -1,3 +0,0 @@ -# GitLab JIRA integration - -This document was moved under [project_services/jira](../project_services/jira.md). diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md deleted file mode 100644 index 30f0c15dacc..00000000000 --- a/doc/integration/ldap.md +++ /dev/null @@ -1,3 +0,0 @@ -# GitLab LDAP integration - -This document was moved under [`administration/auth/ldap`](../administration/auth/ldap.md). diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md deleted file mode 100644 index 5f8bb57365c..00000000000 --- a/doc/integration/oauth_provider.md +++ /dev/null @@ -1,80 +0,0 @@ -# GitLab as OAuth2 authentication service provider - -This document is about using GitLab as an OAuth authentication service provider -to sign in to other services. - -If you want to use other OAuth authentication service providers to sign in to -GitLab, please see the [OAuth2 client documentation](../api/oauth2.md). - -## Introduction to OAuth - -[OAuth] provides to client applications a 'secure delegated access' to server -resources on behalf of a resource owner. In fact, OAuth allows an authorization -server to issue access tokens to third-party clients with the approval of the -resource owner, or the end-user. - -OAuth is mostly used as a Single Sign-On service (SSO), but you can find a -lot of different uses for this functionality. For example, you can allow users -to sign in to your application with their GitLab.com account, or GitLab.com -can be used for authentication to your GitLab instance -(see [GitLab OmniAuth](gitlab.md)). - -The 'GitLab Importer' feature is also using the OAuth protocol to give access -to repositories without sharing user credentials to your GitLab.com account. - ---- - -GitLab supports two ways of adding a new OAuth2 application to an instance. You -can either add an application as a regular user or add it in the admin area. -What this means is that GitLab can actually have instance-wide and a user-wide -applications. There is no difference between them except for the different -permission levels they are set (user/admin). - -## Adding an application through the profile - -In order to add a new application via your profile, navigate to -**Profile Settings > Applications** and select **New Application**. - -![New OAuth application](img/oauth_provider_user_wide_applications.png) - ---- - -In the application form, enter a **Name** (arbitrary), and make sure to set up -correctly the **Redirect URI** which is the URL where users will be sent after -they authorize with GitLab. - -![New OAuth application form](img/oauth_provider_application_form.png) - ---- - -When you hit **Submit** you will be provided with the application ID and -the application secret which you can then use with your application that -connects to GitLab. - -![OAuth application ID and secret](img/oauth_provider_application_id_secret.png) - ---- - -## OAuth applications in the admin area - -To create an application that does not belong to a certain user, you can create -it from the admin area. - -![OAuth admin_applications](img/oauth_provider_admin_application.png) - ---- - -## Authorized applications - -Every application you authorized to use your GitLab credentials will be shown -in the **Authorized applications** section under **Profile Settings > Applications**. - -![Authorized_applications](img/oauth_provider_authorized_application.png) - ---- - -As you can see, the default scope `api` is used, which is the only scope that -GitLab supports so far. At any time you can revoke any access by just clicking -**Revoke**. - -[oauth]: http://oauth.net/2/ "OAuth website" diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md deleted file mode 100644 index 820f40f81a9..00000000000 --- a/doc/integration/omniauth.md +++ /dev/null @@ -1,208 +0,0 @@ -# OmniAuth - -GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and -other popular services. - -Configuring OmniAuth does not prevent standard GitLab authentication or LDAP -(if configured) from continuing to work. Users can choose to sign in using any -of the configured mechanisms. - -- [Initial OmniAuth Configuration](#initial-omniauth-configuration) -- [Supported Providers](#supported-providers) -- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) -- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) -- [Enable or disable Sign In with an OmniAuth provider without disabling import sources](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources) - -## Supported Providers - -This is a list of the current supported OmniAuth providers. Before proceeding -on each provider's documentation, make sure to first read this document as it -contains some settings that are common for all providers. - -- [GitHub](github.md) -- [Bitbucket](bitbucket.md) -- [GitLab.com](gitlab.md) -- [Google](google.md) -- [Facebook](facebook.md) -- [Twitter](twitter.md) -- [Shibboleth](shibboleth.md) -- [SAML](saml.md) -- [Crowd](crowd.md) -- [Azure](azure.md) -- [Auth0](auth0.md) - -## Initial OmniAuth Configuration - -Before configuring individual OmniAuth providers there are a few global settings -that are in common for all providers that we need to consider. - -- Omniauth needs to be enabled, see details below for example. -- `allow_single_sign_on` allows you to specify the providers you want to allow to - automatically create an account. It defaults to `false`. If `false` users must - be created manually or they will not be able to sign in via OmniAuth. -- `block_auto_created_users` defaults to `true`. If `true` auto created users will - be blocked by default and will have to be unblocked by an administrator before - they are able to sign in. - ->**Note:** -If you set `block_auto_created_users` to `false`, make sure to only -define providers under `allow_single_sign_on` that you are able to control, like -SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on -the Internet will be able to successfully sign in to your GitLab without -administrative approval. - -To change these settings: - -* **For omnibus package** - - Open the configuration file: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - and change: - - ```ruby - gitlab_rails['omniauth_enabled'] = true - - # CAUTION! - # This allows users to login without having a user account first. Define the allowed providers - # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. - # User accounts will be created automatically when authentication was successful. - gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] - gitlab_rails['omniauth_block_auto_created_users'] = true - ``` - -* **For installations from source** - - Open the configuration file: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - - and change the following section: - - ```yaml - ## OmniAuth settings - omniauth: - # Allow login via Twitter, Google, etc. using OmniAuth providers - enabled: true - - # CAUTION! - # This allows users to login without having a user account first. Define the allowed providers - # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. - # User accounts will be created automatically when authentication was successful. - allow_single_sign_on: ["saml", "twitter"] - - # Locks down those users until they have been cleared by the admin (default: true). - block_auto_created_users: true - ``` - -Now we can choose one or more of the Supported Providers listed above to continue -the configuration process. - -## Enable OmniAuth for an Existing User - -Existing users can enable OmniAuth for specific providers after the account is -created. For example, if the user originally signed in with LDAP, an OmniAuth -provider such as Twitter can be enabled. Follow the steps below to enable an -OmniAuth provider for an existing user. - -1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. -1. Go to profile settings (the silhouette icon in the top right corner). -1. Select the "Account" tab. -1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab - they will be redirected back to GitLab. - -The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. - -## Configure OmniAuth Providers as External - ->**Note:** -This setting was introduced with version 8.7 of GitLab - -You can define which OmniAuth providers you want to be `external` so that all users -creating accounts via these providers will not be able to have access to internal -projects. You will need to use the full name of the provider, like `google_oauth2` -for Google. Refer to the examples for the full names of the supported providers. - -**For Omnibus installations** - -```ruby - gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2'] -``` - -**For installations from source** - -```yaml - omniauth: - external_providers: ['twitter', 'google_oauth2'] -``` - -## Using Custom Omniauth Providers - ->**Note:** -The following information only applies for installations from source. - -GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships -with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that -is not enough and you need to integrate with other authentication solutions. For -these cases you can use the Omniauth provider. - -### Steps - -These steps are fairly general and you will need to figure out the exact details -from the Omniauth provider's documentation. - -- Stop GitLab: - - sudo service gitlab stop - -- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile): - - gem "omniauth-your-auth-provider" - -- If you're using MySQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment - -- If you're using PostgreSQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment - - > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. - -- Start GitLab: - - sudo service gitlab start - -### Examples - -If you have successfully set up a provider that is not shipped with GitLab itself, -please let us know. - -You can help others by reporting successful configurations and probably share a -few insights or provide warnings for common errors or pitfalls by sharing your -experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). - -While we can't officially support every possible authentication mechanism out there, -we'd like to at least help those with specific needs. - -## Enable or disable Sign In with an OmniAuth provider without disabling import sources - ->**Note:** -This setting was introduced with version 8.8 of GitLab. - -Administrators are able to enable or disable Sign In via some OmniAuth providers. - ->**Note:** -By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`. - -In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable. - -![Enabled OAuth Sign-In sources](img/enabled-oauth-sign-in-sources.png) diff --git a/doc/integration/recaptcha.md b/doc/integration/recaptcha.md deleted file mode 100644 index a301d1a613c..00000000000 --- a/doc/integration/recaptcha.md +++ /dev/null @@ -1,23 +0,0 @@ -# reCAPTCHA - -GitLab leverages [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) -to protect against spam and abuse. GitLab displays the CAPTCHA form on the sign-up page -to confirm that a real user, not a bot, is attempting to create an account. - -## Configuration - -To use reCAPTCHA, first you must create a site and private key. - -1. Go to the URL: https://www.google.com/recaptcha/admin - -2. Fill out the form necessary to obtain reCAPTCHA keys. - -3. Login to your GitLab server, with administrator credentials. - -4. Go to Applications Settings on Admin Area (`admin/application_settings`) - -5. Fill all recaptcha fields with keys from previous steps - -6. Check the `Enable reCAPTCHA` checkbox - -7. Save the configuration. diff --git a/doc/integration/saml.md b/doc/integration/saml.md deleted file mode 100644 index 8a7205caaa4..00000000000 --- a/doc/integration/saml.md +++ /dev/null @@ -1,309 +0,0 @@ -# SAML OmniAuth Provider - -GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows -GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as -Microsoft ADFS to authenticate users. - -First configure SAML 2.0 support in GitLab, then register the GitLab application -in your SAML IdP: - -1. Make sure GitLab is configured with HTTPS. - See [Using HTTPS](../install/installation.md#using-https) for instructions. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) - for initial settings. - -1. To allow your users to use SAML to sign up without having to manually create - an account first, don't forget to add the following values to your configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] - gitlab_rails['omniauth_block_auto_created_users'] = false - ``` - - For installations from source: - - ```yaml - allow_single_sign_on: ["saml"] - block_auto_created_users: false - ``` - -1. You can also automatically link SAML users with existing GitLab users if their - email addresses match by adding the following setting: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_auto_link_saml_user'] = true - ``` - - For installations from source: - - ```yaml - auto_link_saml_user: true - ``` - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" - } - ] - ``` - - For installations from source: - - ```yaml - - { - name: 'saml', - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' - }, - label: 'Company Login' # optional label for SAML login button, defaults to "Saml" - } - ``` - -1. Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint - of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab - installation to generate the correct value). - -1. Change the values of `idp_cert_fingerprint`, `idp_sso_target_url`, - `name_identifier_format` to match your IdP. Check - [the omniauth-saml documentation](https://github.com/omniauth/omniauth-saml) - for details on these options. - -1. Change the value of `issuer` to a unique name, which will identify the application - to the IdP. - -1. Restart GitLab for the changes to take effect. - -1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified - in `issuer`. - -To ease configuration, most IdP accept a metadata URL for the application to provide -configuration information to the IdP. To build the metadata URL for GitLab, append -`users/auth/saml/metadata` to the HTTPS URL of your GitLab installation, for instance: - ``` - https://gitlab.example.com/users/auth/saml/metadata - ``` - -At a minimum the IdP *must* provide a claim containing the user's email address, using -claim name `email` or `mail`. The email will be used to automatically generate the GitLab -username. GitLab will also use claims with name `name`, `first_name`, `last_name` -(see [the omniauth-saml gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) -for supported claims). - -On the sign in page there should now be a SAML button below the regular sign in form. -Click the icon to begin the authentication process. If everything goes well the user -will be returned to GitLab and will be signed in. - -## External Groups - ->**Note:** -This setting is only available on GitLab 8.7 and above. - -SAML login includes support for external groups. You can define in the SAML -settings which groups, to which your users belong in your IdP, you wish to be -marked as [external](../permissions/permissions.md). - -### Requirements - -First you need to tell GitLab where to look for group information. For this you -need to make sure that your IdP server sends a specific `AttributeStament` along -with the regular SAML response. Here is an example: - -```xml - - - SecurityGroup - Developers - Designers - - -``` - -The name of the attribute can be anything you like, but it must contain the groups -to which a user belongs. In order to tell GitLab where to find these groups, you need -to add a `groups_attribute:` element to your SAML settings. You will also need to -tell GitLab which groups are external via the `external_groups:` element: - -```yaml -{ name: 'saml', - label: 'Our SAML Provider', - groups_attribute: 'Groups', - external_groups: ['Freelancers', 'Interns'], - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' - } } -``` - -## Customization - -### `auto_sign_in_with_provider` - -You can add this setting to your GitLab configuration to automatically redirect you -to your SAML server for authentication, thus removing the need to click a button -before actually signing in. - -For omnibus package: - -```ruby -gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' -``` - -For installations from source: - -```yaml -omniauth: - auto_sign_in_with_provider: saml -``` - -Please keep in mind that every sign in attempt will be redirected to the SAML server, -so you will not be able to sign in using local credentials. Make sure that at least one -of the SAML users has admin permissions. - -### `attribute_statements` - ->**Note:** -This setting is only available on GitLab 8.6 and above. -This setting should only be used to map attributes that are part of the -OmniAuth info hash schema. - -`attribute_statements` is used to map Attribute Names in a SAMLResponse to entries -in the OmniAuth [info hash](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). - -For example, if your SAMLResponse contains an Attribute called 'EmailAddress', -specify `{ email: ['EmailAddress'] }` to map the Attribute to the -corresponding key in the info hash. URI-named Attributes are also supported, e.g. -`{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. - -This setting allows you tell GitLab where to look for certain attributes required -to create an account. Like mentioned above, if your IdP sends the user's email -address as `EmailAddress` instead of `email`, let GitLab know by setting it on -your configuration: - -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', - attribute_statements: { email: ['EmailAddress'] } -} -``` - -### `allowed_clock_drift` - -The clock of the Identity Provider may drift slightly ahead of your system clocks. -To allow for a small amount of clock drift you can use `allowed_clock_drift` within -your settings. Its value must be given in a number (and/or fraction) of seconds. -The value given is added to the current time at which the response is validated. - -```yaml -args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', - attribute_statements: { email: ['EmailAddress'] }, - allowed_clock_drift: 1 # for one second clock drift -} -``` - -## Troubleshooting - -### 500 error after login - -If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, -this likely indicates that GitLab could not get the email address for the SAML user. - -Make sure the IdP provides a claim containing the user's email address, using claim name -`email` or `mail`. - -### Redirect back to login screen with no evident error - -If after signing in into your SAML server you are redirected back to the sign in page and -no error is displayed, check your `production.log` file. It will most likely contain the -message `Can't verify CSRF token authenticity`. This means that there is an error during -the SAML request, but this error never reaches GitLab due to the CSRF check. - -To bypass this you can add `skip_before_action :verify_authenticity_token` to the -`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab, -where it can then be seen in the usual logs, or as a flash message in the login -screen. - -That file is located at `/opt/gitlab/embedded/service/gitlab-rails/app/controllers` -for Omnibus installations and by default on `/home/git/gitlab/app/controllers` for -installations from source. - -### Invalid audience - -This error means that the IdP doesn't recognize GitLab as a valid sender and -receiver of SAML requests. Make sure to add the GitLab callback URL to the approved -audiences of the IdP server. - -### Missing claims - -The IdP server needs to pass certain information in order for GitLab to either -create an account, or match the login information to an existing account. `email` -is the minimum amount of information that needs to be passed. If the IdP server -is not providing this information, all SAML requests will fail. - -Make sure this information is provided. - -### Key validation error, Digest mismatch or Fingerprint mismatch - -These errors all come from a similar place, the SAML certificate. SAML requests -need to be validated using a fingerprint, a certificate or a validator. - -For this you need take the following into account: - -- If no certificate is provided in the settings, a fingerprint or fingerprint - validator needs to be provided and the response from the server must contain - a certificate (``) -- If a certificate is provided in the settings, it is no longer necessary for - the request to contain one. In this case the fingerprint or fingerprint - validators are optional - -Make sure that one of the above described scenarios is valid, or the requests will -fail with one of the mentioned errors. \ No newline at end of file diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md deleted file mode 100644 index b6b2d4e5e88..00000000000 --- a/doc/integration/shibboleth.md +++ /dev/null @@ -1,125 +0,0 @@ -# Shibboleth OmniAuth Provider - -This documentation is for enabling shibboleth with omnibus-gitlab package. - -In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. - - -To enable the Shibboleth OmniAuth provider you must: - -1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. -Check https://wiki.shibboleth.net/ for more info. - -1. You can find Apache config in gitlab-recipes (https://github.com/gitlabhq/gitlab-recipes/blob/master/web-server/apache/gitlab-ssl.conf) - -Following changes are needed to enable shibboleth: - -protect omniauth-shibboleth callback URL: -``` - - AuthType shibboleth - ShibRequestSetting requireSession 1 - ShibUseHeaders On - require valid-user - - - Alias /shibboleth-sp /usr/share/shibboleth - - Satisfy any - - - - SetHandler shib - -``` -exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibboleth.sso" and "RewriteCond %{REQUEST_URI} !/shibboleth-sp", config should look like this: -``` - # Apache equivalent of Nginx try files - RewriteEngine on - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_URI} !/Shibboleth.sso - RewriteCond %{REQUEST_URI} !/shibboleth-sp - RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] - RequestHeader set X_FORWARDED_PROTO 'https' -``` - -1. Edit /etc/gitlab/gitlab.rb configuration file, your shibboleth attributes should be in form of "HTTP_ATTRIBUTE" and you should addjust them to your need and environment. Add any other configuration you need. - -File should look like this: -``` -external_url 'https://gitlab.example.com' -gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' - -# disable Nginx -nginx['enable'] = false - -gitlab_rails['omniauth_allow_single_sign_on'] = true -gitlab_rails['omniauth_block_auto_created_users'] = false -gitlab_rails['omniauth_enabled'] = true -gitlab_rails['omniauth_providers'] = [ - { - "name" => 'shibboleth', - "args" => { - "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", - "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", - "uid_field" => 'HTTP_EPPN', - "name_field" => 'HTTP_CN', - "info_fields" => { "email" => 'HTTP_MAIL'} - } - } -] - -``` -1. Save changes and reconfigure gitlab: -``` -sudo gitlab-ctl reconfigure -``` - -On the sign in page there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (Depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. - -## Apache 2.4 / GitLab 8.6 update -The order of the first 2 Location directives is important. If they are reversed, -you will not get a shibboleth session! - -``` - - Require all granted - ProxyPassReverse http://127.0.0.1:8181 - ProxyPassReverse http://YOUR_SERVER_FQDN/ - - - - AuthType shibboleth - ShibRequestSetting requireSession 1 - ShibUseHeaders On - Require shib-session - - - Alias /shibboleth-sp /usr/share/shibboleth - - - Require all granted - - - - SetHandler shib - - - RewriteEngine on - - #Don't escape encoded characters in api requests - RewriteCond %{REQUEST_URI} ^/api/v3/.* - RewriteCond %{REQUEST_URI} !/Shibboleth.sso - RewriteCond %{REQUEST_URI} !/shibboleth-sp - RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA,NE] - - #Forward all requests to gitlab-workhorse except existing files - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f [OR] - RewriteCond %{REQUEST_URI} ^/uploads/.* - RewriteCond %{REQUEST_URI} !/Shibboleth.sso - RewriteCond %{REQUEST_URI} !/shibboleth-sp - RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA] - - RequestHeader set X_FORWARDED_PROTO 'https' - RequestHeader set X-Forwarded-Ssl on -``` \ No newline at end of file diff --git a/doc/integration/slack.md b/doc/integration/slack.md deleted file mode 100644 index f6ba80f46d5..00000000000 --- a/doc/integration/slack.md +++ /dev/null @@ -1,41 +0,0 @@ -# Slack integration - -## On Slack - -To enable Slack integration you must create an Incoming WebHooks integration on Slack: - -1. [Sign in to Slack](https://slack.com/signin) - -1. Visit [Incoming WebHooks](https://my.slack.com/services/new/incoming-webhook/) - -1. Choose the channel name you want to send notifications to. - -1. Click **Add Incoming WebHooks Integration** - - Optional step; You can change bot's name and avatar by clicking modifying the bot name or avatar under **Integration Settings**. - -1. Copy the **Webhook URL**, we'll need this later for GitLab. - - -## On GitLab - -After Slack is ready we need to setup GitLab. Here are the steps to achieve this. - -1. Sign in to GitLab - -1. Pick the repository you want. - -1. Navigate to Settings -> Services -> Slack - -1. Pick the triggers you want to activate - -1. Fill in your Slack details - - Webhook: Paste the Webhook URL from the step above - - Username: Fill this in if you want to change the username of the bot - - Channel: Fill this in if you want to change the channel where the messages will be posted - - Mark it as active - -1. Save your settings - -Have fun :) - -*P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them.* diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md deleted file mode 100644 index 4769f26b259..00000000000 --- a/doc/integration/twitter.md +++ /dev/null @@ -1,79 +0,0 @@ -# Twitter OAuth2 OmniAuth Provider - -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. - -1. Sign in to [Twitter Application Management](https://apps.twitter.com/). - -1. Select "Create new app" - -1. Fill in the application details. - - Name: This can be anything. Consider something like "\'s GitLab" or "\'s GitLab" or - something else descriptive. - - Description: Create a description. - - Website: The URL to your GitLab installation. 'https://gitlab.example.com' - - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' - - Agree to the "Developer Agreement". - - ![Twitter App Details](img/twitter_app_details.png) -1. Select "Create your Twitter application." - -1. Select the "Settings" tab. - -1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in with Twitter." - -1. Select "Update settings" at the bottom to save changes. - -1. Select the "Keys and Access Tokens" tab. - -1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. - - ![Twitter app](img/twitter_app_api_keys.png) - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For installations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "twitter", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" - } - ] - ``` - - For installations from source: - - ``` - - { name: 'twitter', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11. - -1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/logs/logs.md b/doc/logs/logs.md deleted file mode 100644 index a2eca62d691..00000000000 --- a/doc/logs/logs.md +++ /dev/null @@ -1 +0,0 @@ -This document was moved to [administration/logs.md](../administration/logs.md). diff --git a/doc/markdown/img/logo.png b/doc/markdown/img/logo.png deleted file mode 100644 index 7da5f23ed9b..00000000000 Binary files a/doc/markdown/img/logo.png and /dev/null differ diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md deleted file mode 100644 index 236eb7b12c4..00000000000 --- a/doc/markdown/markdown.md +++ /dev/null @@ -1,615 +0,0 @@ -# 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 ```, 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 tag. - ``` - -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 tag. -``` - -## 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 -
-
Definition list
-
Is something people use sometimes.
- -
Markdown in HTML
-
Does *not* work **very** well. Use HTML tags.
-
-``` - -
-
Definition list
-
Is something people use sometimes.
- -
Markdown in HTML
-
Does *not* work **very** well. Use HTML tags.
-
- -## 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 <Enter> 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/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md deleted file mode 100644 index 8f9ef054949..00000000000 --- a/doc/migrate_ci_to_ce/README.md +++ /dev/null @@ -1,435 +0,0 @@ -## Migrate GitLab CI to GitLab CE or EE - -Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise -Edition (EE), GitLab CI is no longer its own application, but is instead built -into the CE and EE applications. - -This guide will detail the process of migrating your CI installation and data -into your GitLab CE or EE installation. **You can only migrate CI data from -GitLab CI 8.0 to GitLab 8.0; migrating between other versions (e.g.7.14 to 8.1) -is not possible.** - -We recommend that you read through the entire migration process in this -document before beginning. - -### Overview - -In this document we assume you have a GitLab server and a GitLab CI server. It -does not matter if these are the same machine. - -The migration consists of three parts: updating GitLab and GitLab CI, moving -data, and redirecting traffic. - -Please note that CI builds triggered on your GitLab server in the time between -updating to 8.0 and finishing the migration will be lost. Your GitLab server -can be online for most of the procedure; the only GitLab downtime (if any) is -during the upgrade to 8.0. Your CI service will be offline from the moment you -upgrade to 8.0 until you finish the migration procedure. - -### Before upgrading - -If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**: - -```bash -mv /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/gitlab-ci/builds.$(date +%s) -``` - -run `sudo gitlab-ctl reconfigure` and you can reach CI at `gitlab.example.com/ci`. - -If you want to migrate your existing data, continue reading. - -#### 0. Updating Omnibus from versions prior to 7.13 - -If you are updating from older versions you should first update to 7.14 and then to 8.0. -Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting). - -#### 1. Verify that backups work - -Make sure that the backup script on both servers can connect to the database. - -``` -# On your CI server: -# Omnibus -sudo chown gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds -sudo gitlab-ci-rake backup:create - -# Source -cd /home/gitlab_ci/gitlab-ci -sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production -``` - -Also check on your GitLab server. - -``` -# On your GitLab server: -# Omnibus -sudo gitlab-rake gitlab:backup:create SKIP=repositories,uploads - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=repositories,uploads -``` - -If this fails you need to fix it before upgrading to 8.0. Also see -https://about.gitlab.com/getting-help/ - -#### 2. Check source and target database types - -Check what databases you use on your GitLab server and your CI server. - Look for the 'adapter:' line. If your CI server and your GitLab server use -the same database adapter no special care is needed. If your CI server uses -MySQL and your GitLab server uses PostgreSQL you need to pass a special option -during the 'Moving data' part. **If your CI server uses PostgreSQL and your -GitLab server uses MySQL you cannot migrate your CI data to GitLab 8.0.** - -``` -# On your CI server: -# Omnibus -sudo gitlab-ci-rake env:info - -# Source -cd /home/gitlab_ci/gitlab-ci -sudo -u gitlab_ci -H bundle exec rake env:info RAILS_ENV=production -``` - -``` -# On your GitLab server: -# Omnibus -sudo gitlab-rake gitlab:env:info - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -#### 3. Storage planning - -Decide where to store CI build traces on GitLab server. GitLab CI uses - files on disk to store CI build traces. The default path for these build -traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or -`/home/git/gitlab/builds` (Source). If you are storing your repository data in -a special location, or if you are using NFS, you should make sure that you -store build traces on the same storage as your Git repositories. - -### I. Upgrading - -From this point on, GitLab CI will be unavailable for your end users. - -#### 1. Upgrade GitLab to 8.0 - -First upgrade your GitLab server to version 8.0: -https://about.gitlab.com/update/ - -#### 2. Disable CI on the GitLab server during the migration - -After you update, go to the admin panel and temporarily disable CI. As - an administrator, go to **Admin Area** -> **Settings**, and under -**Continuous Integration** uncheck **Disable to prevent CI usage until rake -ci:migrate is run (8.0 only)**. - -#### 3. CI settings are now in GitLab - -If you want to use custom CI settings (e.g. change where builds are - stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or -`/home/git/gitlab/config/gitlab.yml` (Source). - -#### 4. Upgrade GitLab CI to 8.0 - -Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages, - this may have already happened when you upgraded GitLab to 8.0. - -#### 5. Disable GitLab CI on the CI server - -Disable GitLab CI after upgrading to 8.0. - -``` -# On your CI server: -# Omnibus -sudo gitlab-ctl stop ci-unicorn -sudo gitlab-ctl stop ci-sidekiq - -# Source -sudo service gitlab_ci stop -cd /home/gitlab_ci/gitlab-ci -sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production -``` - -### II. Moving data - -#### 1. Database encryption key - -Move the database encryption key from your CI server to your GitLab - server. The command below will show you what you need to copy-paste to your -GitLab server. On Omnibus GitLab servers you will have to add a line to -`/etc/gitlab/gitlab.rb`. On GitLab servers installed from source you will have -to replace the contents of `/home/git/gitlab/config/secrets.yml`. - -``` -# On your CI server: -# Omnibus -sudo gitlab-ci-rake backup:show_secrets - -# Source -cd /home/gitlab_ci/gitlab-ci -sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production -``` - -#### 2. SQL data and build traces - -Create your final CI data export. If you are converting from MySQL to - PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When -the command finishes it will print the path to your data export archive; you -will need this file later. - -``` -# On your CI server: -# Omnibus -sudo chown gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds -sudo gitlab-ci-rake backup:create - -# Source -cd /home/gitlab_ci/gitlab-ci -sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production -``` - -#### 3. Copy data to the GitLab server - -If you were running GitLab and GitLab CI on the same server you can skip this -step. - -Copy your CI data archive to your GitLab server. There are many ways to do -this, below we use SSH agent forwarding and 'scp', which will be easy and fast -for most setups. You can also copy the data archive first from the CI server to -your laptop and then from your laptop to the GitLab server. - -``` -# Start from your laptop -ssh -A ci_admin@ci_server.example -# Now on the CI server -scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~ -``` - -#### 4. Move data to the GitLab backups folder - -Make the CI data archive discoverable for GitLab. We assume below that you -store backups in the default path, adjust the command if necessary. - -``` -# On your GitLab server: -# Omnibus -sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/ - -# Source -sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ -``` - -#### 5. Import the CI data into GitLab. - -This step will delete any existing CI data on your GitLab server. There should -be no CI data yet because you turned CI on the GitLab server off earlier. - -``` -# On your GitLab server: -# Omnibus -sudo chown git:git /var/opt/gitlab/gitlab-ci/builds -sudo gitlab-rake ci:migrate - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production -``` - -#### 6. Restart GitLab - -``` -# On your GitLab server: -# Omnibus -sudo gitlab-ctl hup unicorn -sudo gitlab-ctl restart sidekiq - -# Source -sudo service gitlab reload -``` - -### III. Redirecting traffic - -If you were running GitLab CI with Omnibus packages and you were using the -internal NGINX configuration your CI service should now be available both at -`ci.example.com` (the old address) and `gitlab.example.com/ci`. **You are done!** - -If you installed GitLab CI from source we now need to configure a redirect in -NGINX so that existing CI runners can keep using the old CI server address, and -so that existing links to your CI server keep working. - -#### 1. Update Nginx configuration - -To ensure that your existing CI runners are able to communicate with the -migrated installation, and that existing build triggers still work, you'll need -to update your Nginx configuration to redirect requests for the old locations to -the new ones. - -Edit `/etc/nginx/sites-available/gitlab_ci` and paste: - -```nginx -# GITLAB CI -server { - listen 80 default_server; # e.g., listen 192.168.1.1:80; - server_name YOUR_CI_SERVER_FQDN; # e.g., server_name source.example.com; - - access_log /var/log/nginx/gitlab_ci_access.log; - error_log /var/log/nginx/gitlab_ci_error.log; - - # expose API to fix runners - location /api { - proxy_read_timeout 300; - proxy_connect_timeout 300; - proxy_redirect off; - proxy_set_header X-Real-IP $remote_addr; - - # You need to specify your DNS servers that are able to resolve YOUR_GITLAB_SERVER_FQDN - resolver 8.8.8.8 8.8.4.4; - proxy_pass $scheme://YOUR_GITLAB_SERVER_FQDN/ci$request_uri; - } - - # redirect all other CI requests - location / { - return 301 $scheme://YOUR_GITLAB_SERVER_FQDN/ci$request_uri; - } - - # adjust this to match the largest build log your runners might submit, - # set to 0 to disable limit - client_max_body_size 10m; -} -``` - -Make sure you substitute these placeholder values with your real ones: - -1. `YOUR_CI_SERVER_FQDN`: The existing public-facing address of your GitLab CI - install (e.g., `ci.gitlab.com`). -1. `YOUR_GITLAB_SERVER_FQDN`: The current public-facing address of your GitLab - CE (or EE) install (e.g., `gitlab.com`). - -**Make sure not to remove the `/ci$request_uri` part. This is required to -properly forward the requests.** - -You should also make sure that you can: - -1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server. -1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server. - -#### 2. Check Nginx configuration - - sudo nginx -t - -#### 3. Restart Nginx - - sudo /etc/init.d/nginx restart - -#### Restore from backup - -If something went wrong and you need to restore a backup, consult the [Backup -restoration](../raketasks/backup_restore.md) guide. - -### Troubleshooting - -#### show:secrets problem (Omnibus-only) -If you see errors like this: -``` -Missing `secret_key_base` or `db_key_base` for 'production' environment. The secrets will be generated and stored in `config/secrets.yml` -rake aborted! -Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml -``` - -This can happen if you are updating from versions prior to 7.13 straight to 8.0. -The fix for this is to update to Omnibus 7.14 first and then update it to 8.0. - -#### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds -To fix that issue you have to change builds/ folder permission before doing final backup: -``` -sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds -``` - -Then before executing `ci:migrate` you need to fix builds folder permission: -``` -sudo chown git:git /var/opt/gitlab/gitlab-ci/builds -``` - -#### Problems when importing CI database to GitLab -If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences: -``` -ALTER SEQUENCE -ERROR: relation "ci_builds_id_seq" does not exist -ERROR: relation "ci_commits_id_seq" does not exist -ERROR: relation "ci_events_id_seq" does not exist -ERROR: relation "ci_jobs_id_seq" does not exist -ERROR: relation "ci_projects_id_seq" does not exist -ERROR: relation "ci_runner_projects_id_seq" does not exist -ERROR: relation "ci_runners_id_seq" does not exist -ERROR: relation "ci_services_id_seq" does not exist -ERROR: relation "ci_taggings_id_seq" does not exist -ERROR: relation "ci_tags_id_seq" does not exist -CREATE TABLE -``` - -To fix that you need to apply this SQL statement before doing final backup: -``` -# Omnibus -gitlab-ci-rails dbconsole <**Note:** This feature was [introduced][ce-3888] in GitLab 8.8. - -GitLab provides a health check endpoint for uptime monitoring on the `health_check` web -endpoint. The health check reports on the overall system status based on the status of -the database connection, the state of the database migrations, and the ability to write -and access the cache. This endpoint can be provided to uptime monitoring services like -[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. - -## Access Token - -An access token needs to be provided while accessing the health check endpoint. The current -accepted token can be found on the `admin/health_check` page of your GitLab instance. - -![access token](img/health_check_token.png) - -The access token can be passed as a URL parameter: - -``` -https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN -``` - -or as an HTTP header: - -```bash -curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json -``` - -## Using the Endpoint - -Once you have the access token, health information can be retrieved as plain text, JSON, -or XML using the `health_check` endpoint: - -- `https://gitlab.example.com/health_check?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check.xml?token=ACCESS_TOKEN` - -You can also ask for the status of specific services: - -- `https://gitlab.example.com/health_check/cache.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check/database.json?token=ACCESS_TOKEN` -- `https://gitlab.example.com/health_check/migrations.json?token=ACCESS_TOKEN` - -For example, the JSON output of the following health check: - -```bash -curl -H "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json -``` - -would be like: - -``` -{"healthy":true,"message":"success"} -``` - -## Status - -On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint -will return a valid successful HTTP status code, and a `success` message. Ideally your -uptime monitoring should look for the success message. - -[ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888 -[pingdom]: https://www.pingdom.com -[nagios-health]: https://nagios-plugins.org/doc/man/check_http.html -[newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring diff --git a/doc/monitoring/img/health_check_token.png b/doc/monitoring/img/health_check_token.png deleted file mode 100644 index 2daf8606b00..00000000000 Binary files a/doc/monitoring/img/health_check_token.png and /dev/null differ diff --git a/doc/monitoring/performance/gitlab_configuration.md b/doc/monitoring/performance/gitlab_configuration.md deleted file mode 100644 index 771584268d9..00000000000 --- a/doc/monitoring/performance/gitlab_configuration.md +++ /dev/null @@ -1,40 +0,0 @@ -# GitLab Configuration - -GitLab Performance Monitoring is disabled by default. To enable it and change any of its -settings, navigate to the Admin area in **Settings > Metrics** -(`/admin/application_settings`). - -The minimum required settings you need to set are the InfluxDB host and port. -Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the -changes. - ---- - -![GitLab Performance Monitoring Admin Settings](img/metrics_gitlab_configuration_settings.png) - ---- - -Finally, a restart of all GitLab processes is required for the changes to take -effect: - -```bash -# For Omnibus installations -sudo gitlab-ctl restart - -# For installations from source -sudo service gitlab restart -``` - -## Pending Migrations - -When any migrations are pending, the metrics are disabled until the migrations -have been performed. - ---- - -Read more on: - -- [Introduction to GitLab Performance Monitoring](introduction.md) -- [InfluxDB Configuration](influxdb_configuration.md) -- [InfluxDB Schema](influxdb_schema.md) -- [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/monitoring/performance/grafana_configuration.md b/doc/monitoring/performance/grafana_configuration.md deleted file mode 100644 index 168bd85c26a..00000000000 --- a/doc/monitoring/performance/grafana_configuration.md +++ /dev/null @@ -1,149 +0,0 @@ -# Grafana Configuration - -[Grafana](http://grafana.org/) is a tool that allows you to visualize time -series metrics through graphs and dashboards. It supports several backend -data stores, including InfluxDB. GitLab writes performance data to InfluxDB -and Grafana will allow you to query InfluxDB to display useful graphs. - -For the easiest installation and configuration, install Grafana on the same -server as InfluxDB. For larger installations, you may want to split out these -services. - -## Installation - -Grafana supplies package repositories (Yum/Apt) for easy installation. -See [Grafana installation documentation](http://docs.grafana.org/installation/) -for detailed steps. - -> **Note**: Before starting Grafana for the first time, set the admin user -and password in `/etc/grafana/grafana.ini`. Otherwise, the default password -will be `admin`. - -## Configuration - -Login as the admin user. Expand the menu by clicking the Grafana logo in the -top left corner. Choose 'Data Sources' from the menu. Then, click 'Add new' -in the top bar. - -![Grafana empty data source page](img/grafana_data_source_empty.png) - -Fill in the configuration details for the InfluxDB data source. Save and -Test Connection to ensure the configuration is correct. - -- **Name**: InfluxDB -- **Default**: Checked -- **Type**: InfluxDB 0.9.x (Even if you're using InfluxDB 0.10.x) -- **Url**: https://localhost:8086 (Or the remote URL if you've installed InfluxDB -on a separate server) -- **Access**: proxy -- **Database**: gitlab -- **User**: admin (Or the username configured when setting up InfluxDB) -- **Password**: The password configured when you set up InfluxDB - -![Grafana data source configurations](img/grafana_data_source_configuration.png) - -## Apply retention policies and create continuous queries - -If you intend to import the GitLab provided Grafana dashboards, you will need -to copy and run a set of queries against InfluxDB to create the needed data -sets. - -On the InfluxDB server, run the following command, substituting your InfluxDB -user and password: - -```bash -influxdb --username admin -password super_secret -``` - -This will drop you in to an InfluxDB interactive session. Copy the entire -contents below and paste it in to the interactive session: - -``` -CREATE RETENTION POLICY default ON gitlab DURATION 1h REPLICATION 1 DEFAULT -CREATE RETENTION POLICY downsampled ON gitlab DURATION 7d REPLICATION 1 -CREATE CONTINUOUS QUERY grape_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_git_timings_per_action FROM gitlab."default".rails_method_calls WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY grape_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.grape_markdown_render_timings_overall FROM gitlab."default".rails_transactions WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY grape_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.grape_markdown_render_timings_per_action FROM gitlab."default".rails_transactions WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY grape_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_markdown_timings_overall FROM gitlab."default".rails_method_calls WHERE (action !~ /.+/ OR action =~ /^Grape#/) AND method =~ /^Banzai/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY grape_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_method_call_timings_per_action_and_method FROM gitlab."default".rails_method_calls WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), method, action END; -CREATE CONTINUOUS QUERY grape_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.grape_method_call_timings_per_method FROM gitlab."default".rails_method_calls WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), method END; -CREATE CONTINUOUS QUERY grape_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.grape_transaction_counts_overall FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY grape_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.grape_transaction_counts_per_action FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY grape_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.grape_transaction_timings_overall FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY grape_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.grape_transaction_timings_per_action FROM gitlab."default".rails_transactions WHERE action !~ /.+/ OR action =~ /^Grape#/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY rails_file_descriptor_counts ON gitlab BEGIN SELECT sum(value) AS count INTO gitlab.downsampled.rails_file_descriptor_counts FROM gitlab."default".rails_file_descriptors GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_gc_counts ON gitlab BEGIN SELECT sum(count) AS total, sum(minor_gc_count) AS minor, sum(major_gc_count) AS major INTO gitlab.downsampled.rails_gc_counts FROM gitlab."default".rails_gc_statistics GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_gc_timings ON gitlab BEGIN SELECT mean(total_time) AS duration_mean, percentile(total_time, 95) AS duration_95th, percentile(total_time, 99) AS duration_99th INTO gitlab.downsampled.rails_gc_timings FROM gitlab."default".rails_gc_statistics GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_git_timings_per_action FROM gitlab."default".rails_method_calls WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY rails_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.rails_markdown_render_timings_overall FROM gitlab."default".rails_transactions WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.rails_markdown_render_timings_per_action FROM gitlab."default".rails_transactions WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY rails_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_markdown_timings_overall FROM gitlab."default".rails_method_calls WHERE (action =~ /.+/ AND action !~ /^Grape#/) AND method =~ /^Banzai/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_memory_usage_overall ON gitlab BEGIN SELECT mean(value) AS memory_mean, percentile(value, 95) AS memory_95th, percentile(value, 99) AS memory_99th INTO gitlab.downsampled.rails_memory_usage_overall FROM gitlab."default".rails_memory_usage GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_method_call_timings_per_action_and_method FROM gitlab."default".rails_method_calls WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), method, action END; -CREATE CONTINUOUS QUERY rails_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_method_call_timings_per_method FROM gitlab."default".rails_method_calls WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), method END; -CREATE CONTINUOUS QUERY rails_object_counts_overall ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.rails_object_counts_overall FROM gitlab."default".rails_object_counts GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_object_counts_per_type ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.rails_object_counts_per_type FROM gitlab."default".rails_object_counts GROUP BY time(1m), type END; -CREATE CONTINUOUS QUERY rails_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.rails_transaction_counts_overall FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.rails_transaction_counts_per_action FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY rails_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.rails_transaction_timings_overall FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY rails_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.rails_transaction_timings_per_action FROM gitlab."default".rails_transactions WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY rails_view_timings_per_action_and_view ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.rails_view_timings_per_action_and_view FROM gitlab."default".rails_views WHERE action =~ /.+/ AND action !~ /^Grape#/ GROUP BY time(1m), action, view END; -CREATE CONTINUOUS QUERY sidekiq_file_descriptor_counts ON gitlab BEGIN SELECT sum(value) AS count INTO gitlab.downsampled.sidekiq_file_descriptor_counts FROM gitlab."default".sidekiq_file_descriptors GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_gc_counts ON gitlab BEGIN SELECT sum(count) AS total, sum(minor_gc_count) AS minor, sum(major_gc_count) AS major INTO gitlab.downsampled.sidekiq_gc_counts FROM gitlab."default".sidekiq_gc_statistics GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_gc_timings ON gitlab BEGIN SELECT mean(total_time) AS duration_mean, percentile(total_time, 95) AS duration_95th, percentile(total_time, 99) AS duration_99th INTO gitlab.downsampled.sidekiq_gc_timings FROM gitlab."default".sidekiq_gc_statistics GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_git_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_git_timings_per_action FROM gitlab."default".sidekiq_method_calls WHERE method =~ /^(Rugged|Gitlab::Git)/ GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY sidekiq_markdown_render_timings_overall ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.sidekiq_markdown_render_timings_overall FROM gitlab."default".sidekiq_transactions WHERE (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_markdown_render_timings_per_action ON gitlab BEGIN SELECT mean(banzai_cached_render_real_time) AS cached_real_mean, percentile(banzai_cached_render_real_time, 95) AS cached_real_95th, percentile(banzai_cached_render_real_time, 99) AS cached_real_99th, mean(banzai_cached_render_cpu_time) AS cached_cpu_mean, percentile(banzai_cached_render_cpu_time, 95) AS cached_cpu_95th, percentile(banzai_cached_render_cpu_time, 99) AS cached_cpu_99th, sum(banzai_cached_render_call_count) AS cached_call_count, mean(banzai_cacheless_render_real_time) AS cacheless_real_mean, percentile(banzai_cacheless_render_real_time, 95) AS cacheless_real_95th, percentile(banzai_cacheless_render_real_time, 99) AS cacheless_real_99th, mean(banzai_cacheless_render_cpu_time) AS cacheless_cpu_mean, percentile(banzai_cacheless_render_cpu_time, 95) AS cacheless_cpu_95th, percentile(banzai_cacheless_render_cpu_time, 99) AS cacheless_cpu_99th, sum(banzai_cacheless_render_call_count) AS cacheless_call_count INTO gitlab.downsampled.sidekiq_markdown_render_timings_per_action FROM gitlab."default".sidekiq_transactions WHERE (banzai_cached_render_call_count > 0 OR banzai_cacheless_render_call_count > 0) GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY sidekiq_markdown_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_markdown_timings_overall FROM gitlab."default".sidekiq_method_calls WHERE method =~ /^Banzai/ GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_memory_usage_overall ON gitlab BEGIN SELECT mean(value) AS memory_mean, percentile(value, 95) AS memory_95th, percentile(value, 99) AS memory_99th INTO gitlab.downsampled.sidekiq_memory_usage_overall FROM gitlab."default".sidekiq_memory_usage GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_method_call_timings_per_action_and_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_method_call_timings_per_action_and_method FROM gitlab."default".sidekiq_method_calls GROUP BY time(1m), method, action END; -CREATE CONTINUOUS QUERY sidekiq_method_call_timings_per_method ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_method_call_timings_per_method FROM gitlab."default".sidekiq_method_calls GROUP BY time(1m), method END; -CREATE CONTINUOUS QUERY sidekiq_object_counts_overall ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.sidekiq_object_counts_overall FROM gitlab."default".sidekiq_object_counts GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_object_counts_per_type ON gitlab BEGIN SELECT sum(count) AS count INTO gitlab.downsampled.sidekiq_object_counts_per_type FROM gitlab."default".sidekiq_object_counts GROUP BY time(1m), type END; -CREATE CONTINUOUS QUERY sidekiq_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.sidekiq_transaction_counts_overall FROM gitlab."default".sidekiq_transactions GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_transaction_counts_per_action ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.sidekiq_transaction_counts_per_action FROM gitlab."default".sidekiq_transactions GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY sidekiq_transaction_timings_overall ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.sidekiq_transaction_timings_overall FROM gitlab."default".sidekiq_transactions GROUP BY time(1m) END; -CREATE CONTINUOUS QUERY sidekiq_transaction_timings_per_action ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th, mean(sql_duration) AS sql_duration_mean, percentile(sql_duration, 95) AS sql_duration_95th, percentile(sql_duration, 99) AS sql_duration_99th, mean(view_duration) AS view_duration_mean, percentile(view_duration, 95) AS view_duration_95th, percentile(view_duration, 99) AS view_duration_99th, mean(cache_read_duration) AS cache_read_duration_mean, percentile(cache_read_duration, 99) AS cache_read_duration_99th, percentile(cache_read_duration, 95) AS cache_read_duration_95th, mean(cache_write_duration) AS cache_write_duration_mean, percentile(cache_write_duration, 99) AS cache_write_duration_99th, percentile(cache_write_duration, 95) AS cache_write_duration_95th, mean(cache_delete_duration) AS cache_delete_duration_mean, percentile(cache_delete_duration, 99) AS cache_delete_duration_99th, percentile(cache_delete_duration, 95) AS cache_delete_duration_95th, mean(cache_exists_duration) AS cache_exists_duration_mean, percentile(cache_exists_duration, 99) AS cache_exists_duration_99th, percentile(cache_exists_duration, 95) AS cache_exists_duration_95th, mean(cache_duration) AS cache_duration_mean, percentile(cache_duration, 99) AS cache_duration_99th, percentile(cache_duration, 95) AS cache_duration_95th, mean(method_duration) AS method_duration_mean, percentile(method_duration, 99) AS method_duration_99th, percentile(method_duration, 95) AS method_duration_95th INTO gitlab.downsampled.sidekiq_transaction_timings_per_action FROM gitlab."default".sidekiq_transactions GROUP BY time(1m), action END; -CREATE CONTINUOUS QUERY sidekiq_view_timings_per_action_and_view ON gitlab BEGIN SELECT mean("duration") AS duration_mean, percentile("duration", 95) AS duration_95th, percentile("duration", 99) AS duration_99th INTO gitlab.downsampled.sidekiq_view_timings_per_action_and_view FROM gitlab."default".sidekiq_views GROUP BY time(1m), action, view END; -CREATE CONTINUOUS QUERY web_transaction_counts_overall ON gitlab BEGIN SELECT count("duration") AS count INTO gitlab.downsampled.web_transaction_counts_overall FROM gitlab."default".rails_transactions GROUP BY time(1m) END; -``` - -## Import Dashboards - -You can now import a set of default dashboards that will give you a good -start on displaying useful information. GitLab has published a set of default -[Grafana dashboards][grafana-dashboards] to get you started. Clone the -repository or download a zip/tarball, then follow these steps to import each -JSON file. - -Open the dashboard dropdown menu and click 'Import' - -![Grafana dashboard dropdown](img/grafana_dashboard_dropdown.png) - -Click 'Choose file' and browse to the location where you downloaded or cloned -the dashboard repository. Pick one of the JSON files to import. - -![Grafana dashboard import](img/grafana_dashboard_import.png) - -Once the dashboard is imported, be sure to click save icon in the top bar. If -you do not save the dashboard after importing it will be removed when you -navigate away. - -![Grafana save icon](img/grafana_save_icon.png) - -Repeat this process for each dashboard you wish to import. - -Alternatively you can automatically import all the dashboards into your Grafana -instance. See the README of the [Grafana dashboards][grafana-dashboards] -repository for more information on this process. - -[grafana-dashboards]: https://gitlab.com/gitlab-org/grafana-dashboards - ---- - -Read more on: - -- [Introduction to GitLab Performance Monitoring](introduction.md) -- [GitLab Configuration](gitlab_configuration.md) -- [InfluxDB Installation/Configuration](influxdb_configuration.md) -- [InfluxDB Schema](influxdb_schema.md) diff --git a/doc/monitoring/performance/img/grafana_dashboard_dropdown.png b/doc/monitoring/performance/img/grafana_dashboard_dropdown.png deleted file mode 100644 index b4448c7a09f..00000000000 Binary files a/doc/monitoring/performance/img/grafana_dashboard_dropdown.png and /dev/null differ diff --git a/doc/monitoring/performance/img/grafana_dashboard_import.png b/doc/monitoring/performance/img/grafana_dashboard_import.png deleted file mode 100644 index 5a2d3c0937a..00000000000 Binary files a/doc/monitoring/performance/img/grafana_dashboard_import.png and /dev/null differ diff --git a/doc/monitoring/performance/img/grafana_data_source_configuration.png b/doc/monitoring/performance/img/grafana_data_source_configuration.png deleted file mode 100644 index 7e2e111f570..00000000000 Binary files a/doc/monitoring/performance/img/grafana_data_source_configuration.png and /dev/null differ diff --git a/doc/monitoring/performance/img/grafana_data_source_empty.png b/doc/monitoring/performance/img/grafana_data_source_empty.png deleted file mode 100644 index 11e27571e64..00000000000 Binary files a/doc/monitoring/performance/img/grafana_data_source_empty.png and /dev/null differ diff --git a/doc/monitoring/performance/img/grafana_save_icon.png b/doc/monitoring/performance/img/grafana_save_icon.png deleted file mode 100644 index 3d4265bee8e..00000000000 Binary files a/doc/monitoring/performance/img/grafana_save_icon.png and /dev/null differ diff --git a/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png deleted file mode 100644 index 14d82b6ac98..00000000000 Binary files a/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png and /dev/null differ diff --git a/doc/monitoring/performance/influxdb_configuration.md b/doc/monitoring/performance/influxdb_configuration.md deleted file mode 100644 index c30cd2950d8..00000000000 --- a/doc/monitoring/performance/influxdb_configuration.md +++ /dev/null @@ -1,193 +0,0 @@ -# InfluxDB Configuration - -The default settings provided by [InfluxDB] are not sufficient for a high traffic -GitLab environment. The settings discussed in this document are based on the -settings GitLab uses for GitLab.com, depending on your own needs you may need to -further adjust them. - -If you are intending to run InfluxDB on the same server as GitLab, make sure -you have plenty of RAM since InfluxDB can use quite a bit depending on traffic. - -Unless you are going with a budget setup, it's advised to run it separately. - -## Requirements - -- InfluxDB 0.9.5 or newer -- A fairly modern version of Linux -- At least 4GB of RAM -- At least 10GB of storage for InfluxDB data - -Note that the RAM and storage requirements can differ greatly depending on the -amount of data received/stored. To limit the amount of stored data users can -look into [InfluxDB Retention Policies][influxdb-retention]. - -## Installation - -Installing InfluxDB is out of the scope of this document. Please refer to the -[InfluxDB documentation]. - -## InfluxDB Server Settings - -Since InfluxDB has many settings that users may wish to customize themselves -(e.g. what port to run InfluxDB on), we'll only cover the essentials. - -The configuration file in question is usually located at -`/etc/influxdb/influxdb.conf`. Whenever you make a change in this file, -InfluxDB needs to be restarted. - -### Storage Engine - -InfluxDB comes with different storage engines and as of InfluxDB 0.9.5 a new -storage engine is available, called [TSM Tree]. All users **must** use the new -`tsm1` storage engine as this [will be the default engine][tsm1-commit] in -upcoming InfluxDB releases. - -Make sure you have the following in your configuration file: - -``` -[data] - dir = "/var/lib/influxdb/data" - engine = "tsm1" -``` - -### Admin Panel - -Production environments should have the InfluxDB admin panel **disabled**. This -feature can be disabled by adding the following to your InfluxDB configuration -file: - -``` -[admin] - enabled = false -``` - -### HTTP - -HTTP is required when using the [InfluxDB CLI] or other tools such as Grafana, -thus it should be enabled. When enabling make sure to _also_ enable -authentication: - -``` -[http] - enabled = true - auth-enabled = true -``` - -_**Note:** Before you enable authentication, you might want to [create an -admin user](#create-a-new-admin-user)._ - -### UDP - -GitLab writes data to InfluxDB via UDP and thus this must be enabled. Enabling -UDP can be done using the following settings: - -``` -[[udp]] - enabled = true - bind-address = ":8089" - database = "gitlab" - batch-size = 1000 - batch-pending = 5 - batch-timeout = "1s" - read-buffer = 209715200 -``` - -This does the following: - -1. Enable UDP and bind it to port 8089 for all addresses. -2. Store any data received in the "gitlab" database. -3. Define a batch of points to be 1000 points in size and allow a maximum of - 5 batches _or_ flush them automatically after 1 second. -4. Define a UDP read buffer size of 200 MB. - -One of the most important settings here is the UDP read buffer size as if this -value is set too low, packets will be dropped. You must also make sure the OS -buffer size is set to the same value, the default value is almost never enough. - -To set the OS buffer size to 200 MB, on Linux you can run the following command: - -```bash -sysctl -w net.core.rmem_max=209715200 -``` - -To make this permanent, add the following to `/etc/sysctl.conf` and restart the -server: - -```bash -net.core.rmem_max=209715200 -``` - -It is **very important** to make sure the buffer sizes are large enough to -handle all data sent to InfluxDB as otherwise you _will_ lose data. The above -buffer sizes are based on the traffic for GitLab.com. Depending on the amount of -traffic, users may be able to use a smaller buffer size, but we highly recommend -using _at least_ 100 MB. - -When enabling UDP, users should take care to not expose the port to the public, -as doing so will allow anybody to write data into your InfluxDB database (as -[InfluxDB's UDP protocol][udp] doesn't support authentication). We recommend either -whitelisting the allowed IP addresses/ranges, or setting up a VLAN and only -allowing traffic from members of said VLAN. - -## Create a new admin user - -If you want to [enable authentication](#http), you might want to [create an -admin user][influx-admin]: - -``` -influx -execute "CREATE USER jeff WITH PASSWORD '1234' WITH ALL PRIVILEGES" -``` - -## Create the `gitlab` database - -Once you get InfluxDB up and running, you need to create a database for GitLab. -Make sure you have changed the [storage engine](#storage-engine) to `tsm1` -before creating a database. - -_**Note:** If you [created an admin user](#create-a-new-admin-user) and enabled -[HTTP authentication](#http), remember to append the username (`-username `) -and password (`-password `) you set earlier to the commands below._ - -Run the following command to create a database named `gitlab`: - -```bash -influx -execute 'CREATE DATABASE gitlab' -``` - -The name **must** be `gitlab`, do not use any other name. - -Next, make sure that the database was successfully created: - -```bash -influx -execute 'SHOW DATABASES' -``` - -The output should be similar to: - -``` -name: databases ---------------- -name -_internal -gitlab -``` - -That's it! Now your GitLab instance should send data to InfluxDB. - ---- - -Read more on: - -- [Introduction to GitLab Performance Monitoring](introduction.md) -- [GitLab Configuration](gitlab_configuration.md) -- [InfluxDB Schema](influxdb_schema.md) -- [Grafana Install/Configuration](grafana_configuration.md) - -[influxdb-retention]: https://docs.influxdata.com/influxdb/v0.9/query_language/database_management/#retention-policy-management -[influxdb documentation]: https://docs.influxdata.com/influxdb/v0.9/ -[influxdb cli]: https://docs.influxdata.com/influxdb/v0.9/tools/shell/ -[udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ -[influxdb]: https://influxdata.com/time-series-platform/influxdb/ -[tsm tree]: https://influxdata.com/blog/new-storage-engine-time-structured-merge-tree/ -[tsm1-commit]: https://github.com/influxdata/influxdb/commit/15d723dc77651bac83e09e2b1c94be480966cb0d -[influx-admin]: https://docs.influxdata.com/influxdb/v0.9/administration/authentication_and_authorization/#create-a-new-admin-user diff --git a/doc/monitoring/performance/influxdb_schema.md b/doc/monitoring/performance/influxdb_schema.md deleted file mode 100644 index 41861860b6d..00000000000 --- a/doc/monitoring/performance/influxdb_schema.md +++ /dev/null @@ -1,88 +0,0 @@ -# InfluxDB Schema - -The following measurements are currently stored in InfluxDB: - -- `PROCESS_file_descriptors` -- `PROCESS_gc_statistics` -- `PROCESS_memory_usage` -- `PROCESS_method_calls` -- `PROCESS_object_counts` -- `PROCESS_transactions` -- `PROCESS_views` - -Here, `PROCESS` is replaced with either `rails` or `sidekiq` depending on the -process type. In all series, any form of duration is stored in milliseconds. - -## PROCESS_file_descriptors - -This measurement contains the number of open file descriptors over time. The -value field `value` contains the number of descriptors. - -## PROCESS_gc_statistics - -This measurement contains Ruby garbage collection statistics such as the amount -of minor/major GC runs (relative to the last sampling interval), the time spent -in garbage collection cycles, and all fields/values returned by `GC.stat`. - -## PROCESS_memory_usage - -This measurement contains the process' memory usage (in bytes) over time. The -value field `value` contains the number of bytes. - -## PROCESS_method_calls - -This measurement contains the methods called during a transaction along with -their duration, and a name of the transaction action that invoked the method (if -available). The method call duration is stored in the value field `duration`, -while the method name is stored in the tag `method`. The tag `action` contains -the full name of the transaction action. Both the `method` and `action` fields -are in the following format: - -``` -ClassName#method_name -``` - -For example, a method called by the `show` method in the `UsersController` class -would have `action` set to `UsersController#show`. - -## PROCESS_object_counts - -This measurement is used to store retained Ruby objects (per class) and the -amount of retained objects. The number of objects is stored in the `count` value -field while the class name is stored in the `type` tag. - -## PROCESS_transactions - -This measurement is used to store basic transaction details such as the time it -took to complete a transaction, how much time was spent in SQL queries, etc. The -following value fields are available: - -| Value | Description | -| ----- | ----------- | -| `duration` | The total duration of the transaction | -| `allocated_memory` | The amount of bytes allocated while the transaction was running. This value is only reliable when using single-threaded application servers | -| `method_duration` | The total time spent in method calls | -| `sql_duration` | The total time spent in SQL queries | -| `view_duration` | The total time spent in views | - -## PROCESS_views - -This measurement is used to store view rendering timings for a transaction. The -following value fields are available: - -| Value | Description | -| ----- | ----------- | -| `duration` | The rendering time of the view | -| `view` | The path of the view, relative to the application's root directory | - -The `action` tag contains the action name of the transaction that rendered the -view. - ---- - -Read more on: - -- [Introduction to GitLab Performance Monitoring](introduction.md) -- [GitLab Configuration](gitlab_configuration.md) -- [InfluxDB Configuration](influxdb_configuration.md) -- [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/monitoring/performance/introduction.md b/doc/monitoring/performance/introduction.md deleted file mode 100644 index 79904916b7e..00000000000 --- a/doc/monitoring/performance/introduction.md +++ /dev/null @@ -1,65 +0,0 @@ -# GitLab Performance Monitoring - -GitLab comes with its own application performance measuring system as of GitLab -8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the -Community and Enterprise editions. - -Apart from this introduction, you are advised to read through the following -documents in order to understand and properly configure GitLab Performance Monitoring: - -- [GitLab Configuration](gitlab_configuration.md) -- [InfluxDB Install/Configuration](influxdb_configuration.md) -- [InfluxDB Schema](influxdb_schema.md) -- [Grafana Install/Configuration](grafana_configuration.md) - -## Introduction to GitLab Performance Monitoring - -GitLab Performance Monitoring makes it possible to measure a wide variety of statistics -including (but not limited to): - -- The time it took to complete a transaction (a web request or Sidekiq job). -- The time spent in running SQL queries and rendering HAML views. -- The time spent executing (instrumented) Ruby methods. -- Ruby object allocations, and retained objects in particular. -- System statistics such as the process' memory usage and open file descriptors. -- Ruby garbage collection statistics. - -Metrics data is written to [InfluxDB][influxdb] over [UDP][influxdb-udp]. Stored -data can be visualized using [Grafana][grafana] or any other application that -supports reading data from InfluxDB. Alternatively data can be queried using the -InfluxDB CLI. - -## Metric Types - -Two types of metrics are collected: - -1. Transaction specific metrics. -1. Sampled metrics, collected at a certain interval in a separate thread. - -### Transaction Metrics - -Transaction metrics are metrics that can be associated with a single -transaction. This includes statistics such as the transaction duration, timings -of any executed SQL queries, time spent rendering HAML views, etc. These metrics -are collected for every Rack request and Sidekiq job processed. - -### Sampled Metrics - -Sampled metrics are metrics that can't be associated with a single transaction. -Examples include garbage collection statistics and retained Ruby objects. These -metrics are collected at a regular interval. This interval is made up out of two -parts: - -1. A user defined interval. -1. A randomly generated offset added on top of the interval, the same offset - can't be used twice in a row. - -The actual interval can be anywhere between a half of the defined interval and a -half above the interval. For example, for a user defined interval of 15 seconds -the actual interval can be anywhere between 7.5 and 22.5. The interval is -re-generated for every sampling run instead of being generated once and re-used -for the duration of the process' lifetime. - -[influxdb]: https://influxdata.com/time-series-platform/influxdb/ -[influxdb-udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ -[grafana]: http://grafana.org/ diff --git a/doc/operations/README.md b/doc/operations/README.md deleted file mode 100644 index 6a35dab7b6c..00000000000 --- a/doc/operations/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# GitLab operations - -- [Sidekiq MemoryKiller](sidekiq_memory_killer.md) -- [Cleaning up Redis sessions](cleaning_up_redis_sessions.md) -- [Understanding Unicorn and unicorn-worker-killer](unicorn.md) diff --git a/doc/operations/cleaning_up_redis_sessions.md b/doc/operations/cleaning_up_redis_sessions.md deleted file mode 100644 index 93521e976d5..00000000000 --- a/doc/operations/cleaning_up_redis_sessions.md +++ /dev/null @@ -1,52 +0,0 @@ -# Cleaning up stale Redis sessions - -Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis. -Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If -you have been running a large GitLab server (thousands of users) since before -GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis -database after you upgrade to GitLab 7.3. You can also perform a cleanup while -still running GitLab 7.2 or older, but in that case new stale sessions will -start building up again after you clean up. - -In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte -hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with -GitLab 7.3.0, the keys are -prefixed with 'session:gitlab:', so they would look like -'session:gitlab:976aa289e2189b17d7ef525a6702ace9'. Below we describe how to -remove the keys in the old format. - -First we define a shell function with the proper Redis connection details. - -``` -rcli() { - # This example works for Omnibus installations of GitLab 7.3 or newer. For an - # installation from source you will have to change the socket path and the - # path to redis-cli. - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" -} - -# test the new shell function; the response should be PONG -rcli ping -``` - -Now we do a search to see if there are any session keys in the old format for -us to clean up. - -``` -# returns the number of old-format session keys in Redis -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l -``` - -If the number is larger than zero, you can proceed to expire the keys from -Redis. If the number is zero there is nothing to clean up. - -``` -# Tell Redis to expire each matched key after 600 seconds. -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli -# This will print '(integer) 1' for each key that gets expired. -``` - -Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis -background save interval) your Redis database will be compacted. If you are -still using GitLab 7.2, users who are not clicking around in GitLab during the -10 minute expiry window will be signed out of GitLab. diff --git a/doc/operations/moving_repositories.md b/doc/operations/moving_repositories.md deleted file mode 100644 index 54adb99386a..00000000000 --- a/doc/operations/moving_repositories.md +++ /dev/null @@ -1,180 +0,0 @@ -# Moving repositories managed by GitLab - -Sometimes you need to move all repositories managed by GitLab to -another filesystem or another server. In this document we will look -at some of the ways you can copy all your repositories from -`/var/opt/gitlab/git-data/repositories` to `/mnt/gitlab/repositories`. - -We will look at three scenarios: the target directory is empty, the -target directory contains an outdated copy of the repositories, and -how to deal with thousands of repositories. - -**Each of the approaches we list can/will overwrite data in the -target directory `/mnt/gitlab/repositories`. Do not mix up the -source and the target.** - -## Target directory is empty: use a tar pipe - -If the target directory `/mnt/gitlab/repositories` is empty the -simplest thing to do is to use a tar pipe. This method has low -overhead and tar is almost always already installed on your system. -However, it is not possible to resume an interrupted tar pipe: if -that happens then all data must be copied again. - -``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - tar -C /mnt/gitlab/repositories -xf - -``` - -If you want to see progress, replace `-xf` with `-xvf`. - -### Tar pipe to another server - -You can also use a tar pipe to copy data to another server. If your -'git' user has SSH access to the newserver as 'git@newserver', you -can pipe the data through SSH. - -``` -# As the git user -tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ - ssh git@newserver tar -C /mnt/gitlab/repositories -xf - -``` - -If you want to compress the data before it goes over the network -(which will cost you CPU cycles) you can replace `ssh` with `ssh -C`. - -## The target directory contains an outdated copy of the repositories: use rsync - -If the target directory already contains a partial / outdated copy -of the repositories it may be wasteful to copy all the data again -with tar. In this scenario it is better to use rsync. This utility -is either already installed on your system or easily installable -via apt, yum etc. - -``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - /mnt/gitlab/repositories -``` - -The `/.` in the command above is very important, without it you can -easily get the wrong directory structure in the target directory. -If you want to see progress, replace `-a` with `-av`. - -### Single rsync to another server - -If the 'git' user on your source system has SSH access to the target -server you can send the repositories over the network with rsync. - -``` -# As the 'git' user -rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ - git@newserver:/mnt/gitlab/repositories -``` - -## Thousands of Git repositories: use one rsync per repository - -Every time you start an rsync job it has to inspect all files in -the source directory, all files in the target directory, and then -decide what files to copy or not. If the source or target directory -has many contents this startup phase of rsync can become a burden -for your GitLab server. In cases like this you can make rsync's -life easier by dividing its work in smaller pieces, and sync one -repository at a time. - -In addition to rsync we will use [GNU -Parallel](http://www.gnu.org/software/parallel/). This utility is -not included in GitLab so you need to install it yourself with apt -or yum. Also note that the GitLab scripts we used below were added -in GitLab 8.1. - -** This process does not clean up repositories at the target location that no -longer exist at the source. ** If you start using your GitLab instance with -`/mnt/gitlab/repositories`, you need to run `gitlab-rake gitlab:cleanup:repos` -after switching to the new repository storage directory. - -### Parallel rsync for all repositories known to GitLab - -This will sync repositories with 10 rsync processes at a time. We keep -track of progress so that the transfer can be restarted if necessary. - -First we create a new directory, owned by 'git', to hold transfer -logs. We assume the directory is empty before we start the transfer -procedure, and that we are the only ones writing files in it. - -``` -# Omnibus -sudo mkdir /var/opt/gitlab/transfer-logs -sudo chown git:git /var/opt/gitlab/transfer-logs - -# Source -sudo -u git -H mkdir /home/git/transfer-logs -``` - -We seed the process with a list of the directories we want to copy. - -``` -# Omnibus -sudo -u git sh -c 'gitlab-rake gitlab:list_repos > /var/opt/gitlab/transfer-logs/all-repos-$(date +%s).txt' - -# Source -cd /home/git/gitlab -sudo -u git -H sh -c 'bundle exec rake gitlab:list_repos > /home/git/transfer-logs/all-repos-$(date +%s).txt' -``` - -Now we can start the transfer. The command below is idempotent, and -the number of jobs done by GNU Parallel should converge to zero. If it -does not some repositories listed in all-repos-1234.txt may have been -deleted/renamed before they could be copied. - -``` -# Omnibus -sudo -u git sh -c ' -cat /var/opt/gitlab/transfer-logs/* | sort | uniq -u |\ - /usr/bin/env JOBS=10 \ - /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \ - /var/opt/gitlab/transfer-logs/success-$(date +%s).log \ - /var/opt/gitlab/git-data/repositories \ - /mnt/gitlab/repositories -' - -# Source -cd /home/git/gitlab -sudo -u git -H sh -c ' -cat /home/git/transfer-logs/* | sort | uniq -u |\ - /usr/bin/env JOBS=10 \ - bin/parallel-rsync-repos \ - /home/git/transfer-logs/success-$(date +%s).log \ - /home/git/repositories \ - /mnt/gitlab/repositories -` -``` - -### Parallel rsync only for repositories with recent activity - -Suppose you have already done one sync that started after 2015-10-1 12:00 UTC. -Then you might only want to sync repositories that were changed via GitLab -_after_ that time. You can use the 'SINCE' variable to tell 'rake -gitlab:list_repos' to only print repositories with recent activity. - -``` -# Omnibus -sudo gitlab-rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\ - sudo -u git \ - /usr/bin/env JOBS=10 \ - /opt/gitlab/embedded/service/gitlab-rails/bin/parallel-rsync-repos \ - success-$(date +%s).log \ - /var/opt/gitlab/git-data/repositories \ - /mnt/gitlab/repositories - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:list_repos SINCE='2015-10-1 12:00 UTC' |\ - sudo -u git -H \ - /usr/bin/env JOBS=10 \ - bin/parallel-rsync-repos \ - success-$(date +%s).log \ - /home/git/repositories \ - /mnt/gitlab/repositories -``` diff --git a/doc/operations/sidekiq_memory_killer.md b/doc/operations/sidekiq_memory_killer.md deleted file mode 100644 index b5e78348989..00000000000 --- a/doc/operations/sidekiq_memory_killer.md +++ /dev/null @@ -1,40 +0,0 @@ -# Sidekiq MemoryKiller - -The GitLab Rails application code suffers from memory leaks. For web requests -this problem is made manageable using -[unicorn-worker-killer](https://github.com/kzk/unicorn-worker-killer) which -restarts Unicorn worker processes in between requests when needed. The Sidekiq -MemoryKiller applies the same approach to the Sidekiq processes used by GitLab -to process background jobs. - -Unlike unicorn-worker-killer, which is enabled by default for all GitLab -installations since GitLab 6.4, the Sidekiq MemoryKiller is enabled by default -_only_ for Omnibus packages. The reason for this is that the MemoryKiller -relies on Runit to restart Sidekiq after a memory-induced shutdown and GitLab -installations from source do not all use Runit or an equivalent. - -With the default settings, the MemoryKiller will cause a Sidekiq restart no -more often than once every 15 minutes, with the restart causing about one -minute of delay for incoming background jobs. - -## Configuring the MemoryKiller - -The MemoryKiller is controlled using environment variables. - -- `SIDEKIQ_MEMORY_KILLER_MAX_RSS`: if this variable is set, and its value is - greater than 0, then after each Sidekiq job, the MemoryKiller will check the - RSS of the Sidekiq process that executed the job. If the RSS of the Sidekiq - process (expressed in kilobytes) exceeds SIDEKIQ_MEMORY_KILLER_MAX_RSS, a - delayed shutdown is triggered. The default value for Omnibus packages is set - [in the omnibus-gitlab - repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). -- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults 900 seconds (15 minutes). When - a shutdown is triggered, the Sidekiq process will keep working normally for - another 15 minutes. -- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defaults to 30 seconds. When the grace - time has expired, the MemoryKiller tells Sidekiq to stop accepting new jobs. - Existing jobs get 30 seconds to finish. After that, the MemoryKiller tells - Sidekiq to shut down, and an external supervision mechanism (e.g. Runit) must - restart Sidekiq. -- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_SIGNAL`: defaults to `SIGKILL`. The name of - the final signal sent to the Sidekiq process when we want it to shut down. diff --git a/doc/operations/unicorn.md b/doc/operations/unicorn.md deleted file mode 100644 index bad61151bda..00000000000 --- a/doc/operations/unicorn.md +++ /dev/null @@ -1,86 +0,0 @@ -# Understanding Unicorn and unicorn-worker-killer - -## Unicorn - -GitLab uses [Unicorn](http://unicorn.bogomips.org/), a pre-forking Ruby web -server, to handle web requests (web browsers and Git HTTP clients). Unicorn is -a daemon written in Ruby and C that can load and run a Ruby on Rails -application; in our case the Rails application is GitLab Community Edition or -GitLab Enterprise Edition. - -Unicorn has a multi-process architecture to make better use of available CPU -cores (processes can run on different cores) and to have stronger fault -tolerance (most failures stay isolated in only one process and cannot take down -GitLab entirely). On startup, the Unicorn 'master' process loads a clean Ruby -environment with the GitLab application code, and then spawns 'workers' which -inherit this clean initial environment. The 'master' never handles any -requests, that is left to the workers. The operating system network stack -queues incoming requests and distributes them among the workers. - -In a perfect world, the master would spawn its pool of workers once, and then -the workers handle incoming web requests one after another until the end of -time. In reality, worker processes can crash or time out: if the master notices -that a worker takes too long to handle a request it will terminate the worker -process with SIGKILL ('kill -9'). No matter how the worker process ended, the -master process will replace it with a new 'clean' process again. Unicorn is -designed to be able to replace 'crashed' workers without dropping user -requests. - -This is what a Unicorn worker timeout looks like in `unicorn_stderr.log`. The -master process has PID 56227 below. - -``` -[2015-06-05T10:58:08.660325 #56227] ERROR -- : worker=10 PID:53009 timeout (61s > 60s), killing -[2015-06-05T10:58:08.699360 #56227] ERROR -- : reaped # worker=10 -[2015-06-05T10:58:08.708141 #62538] INFO -- : worker=10 spawned pid=62538 -[2015-06-05T10:58:08.708824 #62538] INFO -- : worker=10 ready -``` - -### Tunables - -The main tunables for Unicorn are the number of worker processes and the -request timeout after which the Unicorn master terminates a worker process. -See the [omnibus-gitlab Unicorn settings -documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.md) -if you want to adjust these settings. - -## unicorn-worker-killer - -GitLab has memory leaks. These memory leaks manifest themselves in long-running -processes, such as Unicorn workers. (The Unicorn master process is not known to -leak memory, probably because it does not handle user requests.) - -To make these memory leaks manageable, GitLab comes with the -[unicorn-worker-killer gem](https://github.com/kzk/unicorn-worker-killer). This -gem [monkey-patches](https://en.wikipedia.org/wiki/Monkey_patch) the Unicorn -workers to do a memory self-check after every 16 requests. If the memory of the -Unicorn worker exceeds a pre-set limit then the worker process exits. The -Unicorn master then automatically replaces the worker process. - -This is a robust way to handle memory leaks: Unicorn is designed to handle -workers that 'crash' so no user requests will be dropped. The -unicorn-worker-killer gem is designed to only terminate a worker process _in -between requests_, so no user requests are affected. - -This is what a Unicorn worker memory restart looks like in unicorn_stderr.log. -You see that worker 4 (PID 125918) is inspecting itself and decides to exit. -The threshold memory value was 254802235 bytes, about 250MB. With GitLab this -threshold is a random value between 200 and 250 MB. The master process (PID -117565) then reaps the worker process and spawns a new 'worker 4' with PID -127549. - -``` -[2015-06-05T12:07:41.828374 #125918] WARN -- : #: worker (pid: 125918) exceeds memory limit (256413696 bytes > 254802235 bytes) -[2015-06-05T12:07:41.828472 #125918] WARN -- : Unicorn::WorkerKiller send SIGQUIT (pid: 125918) alive: 23 sec (trial 1) -[2015-06-05T12:07:42.025916 #117565] INFO -- : reaped # worker=4 -[2015-06-05T12:07:42.034527 #127549] INFO -- : worker=4 spawned pid=127549 -[2015-06-05T12:07:42.035217 #127549] INFO -- : worker=4 ready -``` - -One other thing that stands out in the log snippet above, taken from -GitLab.com, is that 'worker 4' was serving requests for only 23 seconds. This -is a normal value for our current GitLab.com setup and traffic. - -The high frequency of Unicorn memory restarts on some GitLab sites can be a -source of confusion for administrators. Usually they are a [red -herring](https://en.wikipedia.org/wiki/Red_herring). diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md deleted file mode 100644 index 963b35de3a0..00000000000 --- a/doc/permissions/permissions.md +++ /dev/null @@ -1,101 +0,0 @@ -# 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/profile/2fa.png b/doc/profile/2fa.png deleted file mode 100644 index bbf415210d5..00000000000 Binary files a/doc/profile/2fa.png and /dev/null differ diff --git a/doc/profile/2fa_auth.png b/doc/profile/2fa_auth.png deleted file mode 100644 index 4a4fbe68984..00000000000 Binary files a/doc/profile/2fa_auth.png and /dev/null differ diff --git a/doc/profile/2fa_u2f_authenticate.png b/doc/profile/2fa_u2f_authenticate.png deleted file mode 100644 index b9138ff60db..00000000000 Binary files a/doc/profile/2fa_u2f_authenticate.png and /dev/null differ diff --git a/doc/profile/2fa_u2f_register.png b/doc/profile/2fa_u2f_register.png deleted file mode 100644 index 15b3683ef73..00000000000 Binary files a/doc/profile/2fa_u2f_register.png and /dev/null differ diff --git a/doc/profile/README.md b/doc/profile/README.md deleted file mode 100644 index 6f8359d87fa..00000000000 --- a/doc/profile/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Profile Settings - -- [Preferences](preferences.md) -- [Two-factor Authentication (2FA)](two_factor_authentication.md) diff --git a/doc/profile/preferences.md b/doc/profile/preferences.md deleted file mode 100644 index 073b8797508..00000000000 --- a/doc/profile/preferences.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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/profile/two_factor_authentication.md b/doc/profile/two_factor_authentication.md deleted file mode 100644 index 82505b13401..00000000000 --- a/doc/profile/two_factor_authentication.md +++ /dev/null @@ -1,127 +0,0 @@ -# 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/project_services/bamboo.md b/doc/project_services/bamboo.md deleted file mode 100644 index 51668128c62..00000000000 --- a/doc/project_services/bamboo.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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/project_services/builds_emails.md b/doc/project_services/builds_emails.md deleted file mode 100644 index af0b1a287c7..00000000000 --- a/doc/project_services/builds_emails.md +++ /dev/null @@ -1,16 +0,0 @@ -## 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/project_services/emails_on_push.md b/doc/project_services/emails_on_push.md deleted file mode 100644 index 2f9f36f962e..00000000000 --- a/doc/project_services/emails_on_push.md +++ /dev/null @@ -1,17 +0,0 @@ -## 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/project_services/hipchat.md b/doc/project_services/hipchat.md deleted file mode 100644 index 021a93a288f..00000000000 --- a/doc/project_services/hipchat.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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//notification?auth_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/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png deleted file mode 100644 index e604dd73ffa..00000000000 Binary files a/doc/project_services/img/builds_emails_service.png and /dev/null differ diff --git a/doc/project_services/img/emails_on_push_service.png b/doc/project_services/img/emails_on_push_service.png deleted file mode 100644 index cd6f79ad1eb..00000000000 Binary files a/doc/project_services/img/emails_on_push_service.png and /dev/null differ diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png deleted file mode 100644 index 85e54861b3e..00000000000 Binary files a/doc/project_services/img/jira_add_gitlab_commit_message.png and /dev/null differ diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png deleted file mode 100644 index e4576433889..00000000000 Binary files a/doc/project_services/img/jira_add_user_to_group.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png deleted file mode 100644 index edaa1326058..00000000000 Binary files a/doc/project_services/img/jira_create_new_group.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png deleted file mode 100644 index 9e518ad7843..00000000000 Binary files a/doc/project_services/img/jira_create_new_group_name.png and /dev/null differ diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png deleted file mode 100644 index 57e433dd818..00000000000 Binary files a/doc/project_services/img/jira_create_new_user.png and /dev/null differ diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png deleted file mode 100644 index 47716ca6d0e..00000000000 Binary files a/doc/project_services/img/jira_group_access.png and /dev/null differ diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png deleted file mode 100644 index cabec1ae137..00000000000 Binary files a/doc/project_services/img/jira_issue_closed.png and /dev/null differ diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png deleted file mode 100644 index 15739a22dc7..00000000000 Binary files a/doc/project_services/img/jira_issue_reference.png and /dev/null differ diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png deleted file mode 100644 index 28e17be3a84..00000000000 Binary files a/doc/project_services/img/jira_issues_workflow.png and /dev/null differ diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png deleted file mode 100644 index 1e78daf105f..00000000000 Binary files a/doc/project_services/img/jira_merge_request_close.png and /dev/null differ diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png deleted file mode 100644 index 5986fdb63fb..00000000000 Binary files a/doc/project_services/img/jira_project_name.png and /dev/null differ diff --git a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png deleted file mode 100644 index 0149181dc86..00000000000 Binary files a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png and /dev/null differ diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png deleted file mode 100644 index 1f6628c4371..00000000000 Binary files a/doc/project_services/img/jira_service.png and /dev/null differ diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png deleted file mode 100644 index 67dfc6144c4..00000000000 Binary files a/doc/project_services/img/jira_service_close_issue.png and /dev/null differ diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png deleted file mode 100644 index c225daa81e1..00000000000 Binary files a/doc/project_services/img/jira_service_page.png and /dev/null differ diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png deleted file mode 100644 index e935d9362aa..00000000000 Binary files a/doc/project_services/img/jira_submit_gitlab_merge_request.png and /dev/null differ diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png deleted file mode 100644 index 2745916972c..00000000000 Binary files a/doc/project_services/img/jira_user_management_link.png and /dev/null differ diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png deleted file mode 100644 index 8635a32eb68..00000000000 Binary files a/doc/project_services/img/jira_workflow_screenshot.png and /dev/null differ diff --git a/doc/project_services/img/redmine_configuration.png b/doc/project_services/img/redmine_configuration.png deleted file mode 100644 index d14e526ad33..00000000000 Binary files a/doc/project_services/img/redmine_configuration.png and /dev/null differ diff --git a/doc/project_services/img/services_templates_redmine_example.png b/doc/project_services/img/services_templates_redmine_example.png deleted file mode 100644 index 384d057fc8e..00000000000 Binary files a/doc/project_services/img/services_templates_redmine_example.png and /dev/null differ diff --git a/doc/project_services/irker.md b/doc/project_services/irker.md deleted file mode 100644 index 25c0c3ad2a6..00000000000 --- a/doc/project_services/irker.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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/project_services/jira.md b/doc/project_services/jira.md deleted file mode 100644 index b626c746c79..00000000000 --- a/doc/project_services/jira.md +++ /dev/null @@ -1,246 +0,0 @@ -# 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:///issues/?jql=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:///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:///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:///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/project_services/project_services.md b/doc/project_services/project_services.md deleted file mode 100644 index f81a035f70b..00000000000 --- a/doc/project_services/project_services.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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/project_services/redmine.md b/doc/project_services/redmine.md deleted file mode 100644 index b9830ea7c38..00000000000 --- a/doc/project_services/redmine.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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/project_services/services_templates.md b/doc/project_services/services_templates.md deleted file mode 100644 index be6d13b6d2b..00000000000 --- a/doc/project_services/services_templates.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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/public_access/public_access.md b/doc/public_access/public_access.md deleted file mode 100644 index 17bb75ececd..00000000000 --- a/doc/public_access/public_access.md +++ /dev/null @@ -1,69 +0,0 @@ -# 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/raketasks/README.md b/doc/raketasks/README.md deleted file mode 100644 index a49c43b8ef2..00000000000 --- a/doc/raketasks/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Rake tasks - -- [Backup restore](backup_restore.md) -- [Check](check.md) -- [Cleanup](cleanup.md) -- [Features](features.md) -- [Maintenance](maintenance.md) and self-checks -- [User management](user_management.md) -- [Webhooks](web_hooks.md) -- [Import](import.md) of git repositories in bulk -- [Rebuild authorized_keys file](http://docs.gitlab.com/ce/raketasks/maintenance.html#rebuild-authorized_keys-file) task for administrators diff --git a/doc/raketasks/backup_hrz.png b/doc/raketasks/backup_hrz.png deleted file mode 100644 index 03e50df1d76..00000000000 Binary files a/doc/raketasks/backup_hrz.png and /dev/null differ diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md deleted file mode 100644 index fa976134341..00000000000 --- a/doc/raketasks/backup_restore.md +++ /dev/null @@ -1,438 +0,0 @@ -# Backup restore - -![backup banner](backup_hrz.png) - -## Create a backup of the GitLab system - -A backup creates an archive file that contains the database, all repositories and all attachments. -This archive will be saved in backup_path (see `config/gitlab.yml`). -The filename will be `[TIMESTAMP]_gitlab_backup.tar`. This timestamp can be used to restore an specific backup. -You can only restore a backup to exactly the same version of GitLab that you created it -on, for example 7.2.1. The best way to migrate your repositories from one server to -another is through backup restore. - -You need to keep a separate copy of `/etc/gitlab/gitlab-secrets.json` -(for omnibus packages) or `/home/git/gitlab/.secret` (for installations -from source). This file contains the database encryption key used -for two-factor authentication. If you restore a GitLab backup without -restoring the database encryption key, users who have two-factor -authentication enabled will lose access to your GitLab server. - -``` -# use this command if you've installed GitLab with the Omnibus package -sudo gitlab-rake gitlab:backup:create - -# if you've installed GitLab from source -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -Also you can choose what should be backed up by adding environment variable SKIP. Available options: db, -uploads (attachments), repositories, builds(CI build output logs), artifacts (CI build artifacts), lfs (LFS objects). -Use a comma to specify several options at the same time. - -``` -sudo gitlab-rake gitlab:backup:create SKIP=db,uploads -``` - -Example output: - -``` -Dumping database tables: -- Dumping table events... [DONE] -- Dumping table issues... [DONE] -- Dumping table keys... [DONE] -- Dumping table merge_requests... [DONE] -- Dumping table milestones... [DONE] -- Dumping table namespaces... [DONE] -- Dumping table notes... [DONE] -- Dumping table projects... [DONE] -- Dumping table protected_branches... [DONE] -- Dumping table schema_migrations... [DONE] -- Dumping table services... [DONE] -- Dumping table snippets... [DONE] -- Dumping table taggings... [DONE] -- Dumping table tags... [DONE] -- Dumping table users... [DONE] -- Dumping table users_projects... [DONE] -- Dumping table web_hooks... [DONE] -- Dumping table wikis... [DONE] -Dumping repositories: -- Dumping repository abcd... [DONE] -Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE] -Deleting tmp directories...[DONE] -Deleting old backups... [SKIPPING] -``` - -## Upload backups to remote (cloud) storage - -Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates. -It uses the [Fog library](http://fog.io/) to perform the upload. -In the example below we use Amazon S3 for storage. -But Fog also lets you use [other storage providers](http://fog.io/storage/). - -For omnibus packages: - -```ruby -gitlab_rails['backup_upload_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-west-1', - 'aws_access_key_id' => 'AKIAKIAKI', - 'aws_secret_access_key' => 'secret123' -} -gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket' -``` - -For installations from source: - -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: AWS - region: eu-west-1 - aws_access_key_id: AKIAKIAKI - aws_secret_access_key: 'secret123' - # The remote 'directory' to store your backups. For S3, this would be the bucket name. - remote_directory: 'my.s3.bucket' - # Turns on AWS Server-Side Encryption with Amazon S3-Managed Keys for backups, this is optional - # encryption: 'AES256' -``` - -If you are uploading your backups to S3 you will probably want to create a new -IAM user with restricted access rights. To give the upload user access only for -uploading backups create the following IAM profile, replacing `my.s3.bucket` -with the name of your bucket: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "Stmt1412062044000", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:GetBucketAcl", - "s3:GetBucketLocation", - "s3:GetObject", - "s3:GetObjectAcl", - "s3:ListBucketMultipartUploads", - "s3:PutObject", - "s3:PutObjectAcl" - ], - "Resource": [ - "arn:aws:s3:::my.s3.bucket/*" - ] - }, - { - "Sid": "Stmt1412062097000", - "Effect": "Allow", - "Action": [ - "s3:GetBucketLocation", - "s3:ListAllMyBuckets" - ], - "Resource": [ - "*" - ] - }, - { - "Sid": "Stmt1412062128000", - "Effect": "Allow", - "Action": [ - "s3:ListBucket" - ], - "Resource": [ - "arn:aws:s3:::my.s3.bucket" - ] - } - ] -} -``` - -### Uploading to locally mounted shares - -You may also send backups to a mounted share (`NFS` / `CIFS` / `SMB` / etc.) by -using the [`Local`](https://github.com/fog/fog-local#usage) storage provider. -The directory pointed to by the `local_root` key **must** be owned by the `git` -user **when mounted** (mounting with the `uid=` of the `git` user for `CIFS` and -`SMB`) or the user that you are executing the backup tasks under (for omnibus -packages, this is the `git` user). - -The `backup_upload_remote_directory` **must** be set in addition to the -`local_root` key. This is the sub directory inside the mounted directory that -backups will be copied to, and will be created if it does not exist. If the -directory that you want to copy the tarballs to is the root of your mounted -directory, just use `.` instead. - -For omnibus packages: - -```ruby -gitlab_rails['backup_upload_connection'] = { - :provider => 'Local', - :local_root => '/mnt/backups' -} - -# The directory inside the mounted folder to copy backups to -# Use '.' to store them in the root directory -gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' -``` - -For installations from source: - -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: Local - local_root: '/mnt/backups' - # The directory inside the mounted folder to copy backups to - # Use '.' to store them in the root directory - remote_directory: 'gitlab_backups' -``` - -## Backup archive permissions - -The backup archives created by GitLab (123456_gitlab_backup.tar) will have owner/group git:git and 0600 permissions by default. -This is meant to avoid other system users reading GitLab's data. -If you need the backup archives to have different permissions you can use the 'archive_permissions' setting. - -``` -# In /etc/gitlab/gitlab.rb, for omnibus packages -gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable -``` - -``` -# In gitlab.yml, for installations from source: - backup: - archive_permissions: 0644 # Makes the backup archives world-readable -``` - -## Storing configuration files - -Please be informed that a backup does not store your configuration -files. One reason for this is that your database contains encrypted -information for two-factor authentication. Storing encrypted -information along with its key in the same place defeats the purpose -of using encryption in the first place! - -If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). -If you have a cookbook installation there should be a copy of your configuration in Chef. -If you have an installation from source, please consider backing up your `.secret` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). - -At the very **minimum** you should backup `/etc/gitlab/gitlab-secrets.json` -(Omnibus) or `/home/git/gitlab/.secret` (source) to preserve your -database encryption key. - -## Restore a previously created backup - -You can only restore a backup to exactly the same version of GitLab that you created it on, for example 7.2.1. - -### Prerequisites - -You need to have a working GitLab installation before you can perform -a restore. This is mainly because the system user performing the -restore actions ('git') is usually not allowed to create or delete -the SQL database it needs to import data into ('gitlabhq_production'). -All existing data will be either erased (SQL) or moved to a separate -directory (repositories, uploads). - -If some or all of your GitLab users are using two-factor authentication -(2FA) then you must also make sure to restore -`/etc/gitlab/gitlab-secrets.json` (Omnibus) or `/home/git/gitlab/.secret` -(installations from source). Note that you need to run `gitlab-ctl -reconfigure` after changing `gitlab-secrets.json`. - -### Installation from source - -``` -# Stop processes that are connected to the database -sudo service gitlab stop - -bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -Options: - -``` -BACKUP=timestamp_of_backup (required if more than one backup exists) -force=yes (do not ask if the authorized_keys file should get regenerated) -``` - -Example output: - -``` -Unpacking backup... [DONE] -Restoring database tables: --- create_table("events", {:force=>true}) - -> 0.2231s -[...] -- Loading fixture events...[DONE] -- Loading fixture issues...[DONE] -- Loading fixture keys...[SKIPPING] -- Loading fixture merge_requests...[DONE] -- Loading fixture milestones...[DONE] -- Loading fixture namespaces...[DONE] -- Loading fixture notes...[DONE] -- Loading fixture projects...[DONE] -- Loading fixture protected_branches...[SKIPPING] -- Loading fixture schema_migrations...[DONE] -- Loading fixture services...[SKIPPING] -- Loading fixture snippets...[SKIPPING] -- Loading fixture taggings...[SKIPPING] -- Loading fixture tags...[SKIPPING] -- Loading fixture users...[DONE] -- Loading fixture users_projects...[DONE] -- Loading fixture web_hooks...[SKIPPING] -- Loading fixture wikis...[SKIPPING] -Restoring repositories: -- Restoring repository abcd... [DONE] -Deleting tmp directories...[DONE] -``` - -### Omnibus installations - -This procedure assumes that: - -- You have installed the exact same version of GitLab Omnibus with which the - backup was created -- You have run `sudo gitlab-ctl reconfigure` at least once -- GitLab is running. If not, start it using `sudo gitlab-ctl start`. - -First make sure your backup tar file is in the backup directory described in the -`gitlab.rb` configuration `gitlab_rails['backup_path']`. The default is -`/var/opt/gitlab/backups`. - -```shell -sudo cp 1393513186_gitlab_backup.tar /var/opt/gitlab/backups/ -``` - -Stop the processes that are connected to the database. Leave the rest of GitLab -running: - -```shell -sudo gitlab-ctl stop unicorn -sudo gitlab-ctl stop sidekiq -# Verify -sudo gitlab-ctl status -``` - -Next, restore the backup, specifying the timestamp of the backup you wish to -restore: - -```shell -# This command will overwrite the contents of your GitLab database! -sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186 -``` - -Restart and check GitLab: - -```shell -sudo gitlab-ctl start -sudo gitlab-rake gitlab:check SANITIZE=true -``` - -If there is a GitLab version mismatch between your backup tar file and the installed -version of GitLab, the restore command will abort with an error. Install the -[correct GitLab version](https://www.gitlab.com/downloads/archives/) and try again. - -## Configure cron to make daily backups - -### For installation from source: -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups -sudo -u git crontab -e # Edit the crontab for the git user -``` - -Add the following lines at the bottom: - -``` -# Create a full backup of the GitLab repositories and SQL database every day at 4am -0 4 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1 -``` - -The `CRON=1` environment setting tells the backup script to suppress all progress output if there are no errors. -This is recommended to reduce cron spam. - -### For omnibus installations - -To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: - -``` -sudo su - -crontab -e -``` - -There, add the following line to schedule the backup for everyday at 2 AM: - -``` -0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1 -``` - -You may also want to set a limited lifetime for backups to prevent regular -backups using all your disk space. To do this add the following lines to -`/etc/gitlab/gitlab.rb` and reconfigure: - -``` -# limit backup lifetime to 7 days - 604800 seconds -gitlab_rails['backup_keep_time'] = 604800 -``` - -NOTE: This cron job does not [backup your omnibus-gitlab configuration](#backup-and-restore-omnibus-gitlab-configuration) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). - -## Alternative backup strategies - -If your GitLab server contains a lot of Git repository data you may find the GitLab backup script to be too slow. -In this case you can consider using filesystem snapshots as part of your backup strategy. - -Example: Amazon EBS - -> A GitLab server using omnibus-gitlab hosted on Amazon AWS. -> An EBS drive containing an ext4 filesystem is mounted at `/var/opt/gitlab`. -> In this case you could make an application backup by taking an EBS snapshot. -> The backup includes all repositories, uploads and Postgres data. - -Example: LVM snapshots + rsync - -> A GitLab server using omnibus-gitlab, with an LVM logical volume mounted at `/var/opt/gitlab`. -> Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. -> Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. -> Now we can have a longer running rsync job which will create a consistent replica on the remote server. -> The replica includes all repositories, uploads and Postgres data. - -If you are running GitLab on a virtualized server you can possibly also create VM snapshots of the entire GitLab server. -It is not uncommon however for a VM snapshot to require you to power down the server, so this approach is probably of limited practical use. - -## Troubleshooting - -### Restoring database backup using omnibus packages outputs warnings -If you are using backup restore procedures you might encounter the following warnings: - -``` -psql:/var/opt/gitlab/backups/db/database.sql:22: ERROR: must be owner of extension plpgsql -psql:/var/opt/gitlab/backups/db/database.sql:2931: WARNING: no privileges could be revoked for "public" (two occurrences) -psql:/var/opt/gitlab/backups/db/database.sql:2933: WARNING: no privileges were granted for "public" (two occurrences) - -``` - -Be advised that, backup is successfully restored in spite of these warnings. - -The rake task runs this as the `gitlab` user which does not have the superuser access to the database. When restore is initiated it will also run as `gitlab` user but it will also try to alter the objects it does not have access to. -Those objects have no influence on the database backup/restore but they give this annoying warning. - -For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). - -## Note -This documentation is for GitLab CE. -We backup GitLab.com and make sure your data is secure, but you can't use these methods to export / backup your data yourself from GitLab.com. - -Issues are stored in the database. They can't be stored in Git itself. - -To migrate your repositories from one server to another with an up-to-date version of -GitLab, you can use the [import rake task](import.md) to do a mass import of the -repository. Note that if you do an import rake task, rather than a backup restore, you -will have all your repositories, but not any other data. diff --git a/doc/raketasks/check.md b/doc/raketasks/check.md deleted file mode 100644 index 3ff3fee6a40..00000000000 --- a/doc/raketasks/check.md +++ /dev/null @@ -1,63 +0,0 @@ -# Check Rake Tasks - -## Repository Integrity - -Even though Git is very resilient and tries to prevent data integrity issues, -there are times when things go wrong. The following Rake tasks intend to -help GitLab administrators diagnose problem repositories so they can be fixed. - -There are 3 things that are checked to determine integrity. - -1. Git repository file system check ([git fsck](https://git-scm.com/docs/git-fsck)). - This step verifies the connectivity and validity of objects in the repository. -1. Check for `config.lock` in the repository directory. -1. Check for any branch/references lock files in `refs/heads`. - -It's important to note that the existence of `config.lock` or reference locks -alone do not necessarily indicate a problem. Lock files are routinely created -and removed as Git and GitLab perform operations on the repository. They serve -to prevent data integrity issues. However, if a Git operation is interrupted these -locks may not be cleaned up properly. - -The following symptoms may indicate a problem with repository integrity. If users -experience these symptoms you may use the rake tasks described below to determine -exactly which repositories are causing the trouble. - -- Receiving an error when trying to push code - `remote: error: cannot lock ref` -- A 500 error when viewing the GitLab dashboard or when accessing a specific project. - -### Check all GitLab repositories - -This task loops through all repositories on the GitLab server and runs the -3 integrity checks described previously. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:repo:check - -# installation from source -bundle exec rake gitlab:repo:check RAILS_ENV=production -``` - -### Check repositories for a specific user - -This task checks all repositories that a specific user has access to. This is important -because sometimes you know which user is experiencing trouble but you don't know -which project might be the cause. - -If the rake task is executed without brackets at the end, you will be prompted -to enter a username. - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:user:check_repos -sudo gitlab-rake gitlab:user:check_repos[] - -# installation from source -bundle exec rake gitlab:user:check_repos RAILS_ENV=production -bundle exec rake gitlab:user:check_repos[] RAILS_ENV=production -``` - -Example output: - -![gitlab:user:check_repos output](check_repos_output.png) diff --git a/doc/raketasks/check_repos_output.png b/doc/raketasks/check_repos_output.png deleted file mode 100644 index 916b1685101..00000000000 Binary files a/doc/raketasks/check_repos_output.png and /dev/null differ diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md deleted file mode 100644 index 8fbcbb983e9..00000000000 --- a/doc/raketasks/cleanup.md +++ /dev/null @@ -1,24 +0,0 @@ -# Cleanup - -## Remove garbage from filesystem. Important! Data loss! - -Remove namespaces(dirs) from `/home/git/repositories` if they don't exist in GitLab database. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:cleanup:dirs - -# installation from source -bundle exec rake gitlab:cleanup:dirs RAILS_ENV=production -``` - -Rename repositories from `/home/git/repositories` if they don't exist in GitLab database. -The repositories get a `+orphaned+TIMESTAMP` suffix so that they cannot block new repositories from being created. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:cleanup:repos - -# installation from source -bundle exec rake gitlab:cleanup:repos RAILS_ENV=production -``` diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md deleted file mode 100644 index f9a46193547..00000000000 --- a/doc/raketasks/features.md +++ /dev/null @@ -1,20 +0,0 @@ -# Features - -## Enable usernames and namespaces for user projects - -This command will enable the namespaces feature introduced in v4.0. It will move every project in its namespace folder. - -Note: - -- Because the **repository location will change**, you will need to **update all your git URLs** to point to the new location. -- Username can be changed at [Profile / Account](/profile/account) - -**Example:** - -Old path: `git@example.org:myrepo.git` - -New path: `git@example.org:username/myrepo.git` or `git@example.org:groupname/myrepo.git` - -``` -bundle exec rake gitlab:enable_namespaces RAILS_ENV=production -``` diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md deleted file mode 100644 index 8a38937062e..00000000000 --- a/doc/raketasks/import.md +++ /dev/null @@ -1,68 +0,0 @@ -# Import bare repositories into your GitLab instance - -## Notes - -- The owner of the project will be the first admin -- The groups will be created as needed -- The owner of the group will be the first admin -- Existing projects will be skipped - -## How to use - -### Create a new folder inside the git repositories path. This will be the name of the new group. - -- For omnibus-gitlab, it is located at: `/var/opt/gitlab/git-data/repositories` by default, unless you changed -it in the `/etc/gitlab/gitlab.rb` file. -- For installations from source, it is usually located at: `/home/git/repositories` or you can see where -your repositories are located by looking at `config/gitlab.yml` under the `gitlab_shell => repos_path` entry. - -New folder needs to have git user ownership and read/write/execute access for git user and its group: - -``` -sudo -u git mkdir /var/opt/gitlab/git-data/repositories/new_group -``` - -If you are using an installation from source, replace `/var/opt/gitlab/git-data` -with `/home/git`. - -### Copy your bare repositories inside this newly created folder: - -``` -sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repositories/new_group/ - -# Do this once when you are done copying git repositories -sudo chown -R git:git /var/opt/gitlab/git-data/repositories/new_group/ -``` - -`foo.git` needs to be owned by the git user and git users group. - -If you are using an installation from source, replace `/var/opt/gitlab/git-data` -with `/home/git`. - -### Run the command below depending on your type of installation: - -#### Omnibus Installation - -``` -$ sudo gitlab-rake gitlab:import:repos -``` - -#### Installation from source - -Before running this command you need to change the directory to where your GitLab installation is located: - -``` -$ cd /home/git/gitlab -$ sudo -u git -H bundle exec rake gitlab:import:repos RAILS_ENV=production -``` - -#### Example output - -``` -Processing abcd.git - * Created abcd (abcd.git) -Processing group/xyz.git - * Created Group group (2) - * Created xyz (group/xyz.git) -[...] -``` diff --git a/doc/raketasks/list_repos.md b/doc/raketasks/list_repos.md deleted file mode 100644 index 476428eb4f5..00000000000 --- a/doc/raketasks/list_repos.md +++ /dev/null @@ -1,30 +0,0 @@ -# Listing repository directories - -You can print a list of all Git repositories on disk managed by -GitLab with the following command: - -``` -# Omnibus -sudo gitlab-rake gitlab:list_repos - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:list_repos RAILS_ENV=production -``` - -If you only want to list projects with recent activity you can pass -a date with the 'SINCE' environment variable. The time you specify -is parsed by the Rails [TimeZone#parse -function](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html#method-i-parse). - -``` -# Omnibus -sudo gitlab-rake gitlab:list_repos SINCE='Sep 1 2015' - -# Source -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:list_repos RAILS_ENV=production SINCE='Sep 1 2015' -``` - -Note that the projects listed are NOT sorted by activity; they use -the default ordering of the GitLab Rails application. diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md deleted file mode 100644 index d9dce2af480..00000000000 --- a/doc/raketasks/maintenance.md +++ /dev/null @@ -1,169 +0,0 @@ -# Maintenance - -## Gather information about GitLab and the system it runs on - -This command gathers information about your GitLab installation and the System it runs on. These may be useful when asking for help or reporting issues. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:env:info - -# installation from source -bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -Example output: - -``` -System information -System: Debian 7.8 -Current User: git -Using RVM: no -Ruby Version: 2.1.5p273 -Gem Version: 2.4.3 -Bundler Version: 1.7.6 -Rake Version: 10.3.2 -Sidekiq Version: 2.17.8 - -GitLab information -Version: 7.7.1 -Revision: 41ab9e1 -Directory: /home/git/gitlab -DB Adapter: postgresql -URL: https://gitlab.example.com -HTTP Clone URL: https://gitlab.example.com/some-project.git -SSH Clone URL: git@gitlab.example.com:some-project.git -Using LDAP: no -Using Omniauth: no - -GitLab Shell -Version: 2.4.1 -Repositories: /home/git/repositories/ -Hooks: /home/git/gitlab-shell/hooks/ -Git: /usr/bin/git -``` - -## Check GitLab configuration - -Runs the following rake tasks: - -- `gitlab:gitlab_shell:check` -- `gitlab:sidekiq:check` -- `gitlab:app:check` - -It will check that each component was setup according to the installation guide and suggest fixes for issues found. - -You may also have a look at our [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide). - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:check - -# installation from source -bundle exec rake gitlab:check RAILS_ENV=production -``` - -NOTE: Use SANITIZE=true for gitlab:check if you want to omit project names from the output. - -Example output: - -``` -Checking Environment ... - -Git configured for git user? ... yes -Has python2? ... yes -python2 is supported version? ... yes - -Checking Environment ... Finished - -Checking GitLab Shell ... - -GitLab Shell version? ... OK (1.2.0) -Repo base directory exists? ... yes -Repo base directory is a symlink? ... no -Repo base owned by git:git? ... yes -Repo base access is drwxrws---? ... yes -post-receive hook up-to-date? ... yes -post-receive hooks in repos are links: ... yes - -Checking GitLab Shell ... Finished - -Checking Sidekiq ... - -Running? ... yes - -Checking Sidekiq ... Finished - -Checking GitLab ... - -Database config exists? ... yes -Database is SQLite ... no -All migrations up? ... yes -GitLab config exists? ... yes -GitLab config outdated? ... no -Log directory writable? ... yes -Tmp directory writable? ... yes -Init script exists? ... yes -Init script up-to-date? ... yes -Redis version >= 2.0.0? ... yes - -Checking GitLab ... Finished -``` - -## Rebuild authorized_keys file - -In some case it is necessary to rebuild the `authorized_keys` file. - -For Omnibus-packages: -``` -sudo gitlab-rake gitlab:shell:setup -``` - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production -``` - -``` -This will rebuild an authorized_keys file. -You will lose any data stored in authorized_keys file. -Do you want to continue (yes/no)? yes -``` - -## Clear redis cache - -If for some reason the dashboard shows wrong information you might want to -clear Redis' cache. - -For Omnibus-packages: -``` -sudo gitlab-rake cache:clear -``` - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## Precompile the assets - -Sometimes during version upgrades you might end up with some wrong CSS or -missing some icons. In that case, try to precompile the assets again. - -Note that this only applies to source installations and does NOT apply to -omnibus packages. - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -For omnibus versions, the unoptimized assets (JavaScript, CSS) are frozen at -the release of upstream GitLab. The omnibus version includes optimized versions -of those assets. Unless you are modifying the JavaScript / CSS code on your -production machine after installing the package, there should be no reason to redo -rake assets:precompile on the production machine. If you suspect that assets -have been corrupted, you should reinstall the omnibus package. diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md deleted file mode 100644 index 629d38efc53..00000000000 --- a/doc/raketasks/user_management.md +++ /dev/null @@ -1,72 +0,0 @@ -# User management - -## Add user as a developer to all projects - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:user_to_projects[username@domain.tld] - -# installation from source -bundle exec rake gitlab:import:user_to_projects[username@domain.tld] RAILS_ENV=production -``` - -## Add all users to all projects - -Notes: - -- admin users are added as masters - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:all_users_to_all_projects - -# installation from source -bundle exec rake gitlab:import:all_users_to_all_projects RAILS_ENV=production -``` - -## Add user as a developer to all groups - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:user_to_groups[username@domain.tld] - -# installation from source -bundle exec rake gitlab:import:user_to_groups[username@domain.tld] RAILS_ENV=production -``` - -## Add all users to all groups - -Notes: - -- admin users are added as owners so they can add additional users to the group - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:all_users_to_all_groups - -# installation from source -bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production -``` - -## Maintain tight control over the number of active users on your GitLab installation - -- Enable this setting to keep new users blocked until they have been cleared by the admin (default: false). - - -``` -block_auto_created_users: false -``` - -## Disable Two-factor Authentication (2FA) for all users - -This task will disable 2FA for all users that have it enabled. This can be -useful if GitLab's `.secret` file has been lost and users are unable to login, -for example. - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:two_factor:disable_for_all_users - -# installation from source -bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production -``` diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md deleted file mode 100644 index 2ebf7c48f4e..00000000000 --- a/doc/raketasks/web_hooks.md +++ /dev/null @@ -1,45 +0,0 @@ -# Webhooks - -## Add a webhook for **ALL** projects: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" - # source installations - bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production - -## Add a webhook for projects in a given **NAMESPACE**: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme - # source installations - bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production - -## Remove a webhook from **ALL** projects using: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" - # source installations - bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production - -## Remove a webhook from projects in a given **NAMESPACE**: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme - # source installations - bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production - -## List **ALL** webhooks: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:list - # source installations - bundle exec rake gitlab:web_hook:list RAILS_ENV=production - -## List the webhooks from projects in a given **NAMESPACE**: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:list NAMESPACE=/ - # source installations - bundle exec rake gitlab:web_hook:list NAMESPACE=/ RAILS_ENV=production - -> Note: `/` is the global namespace. diff --git a/doc/ssh/README.md b/doc/ssh/README.md deleted file mode 100644 index a1198e5878f..00000000000 --- a/doc/ssh/README.md +++ /dev/null @@ -1,130 +0,0 @@ -# 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/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md deleted file mode 100644 index c44930a4ceb..00000000000 --- a/doc/system_hooks/system_hooks.md +++ /dev/null @@ -1,355 +0,0 @@ -# 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/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 ```, 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 tag. + ``` + +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 tag. +``` + +## 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 +
+
Definition list
+
Is something people use sometimes.
+ +
Markdown in HTML
+
Does *not* work **very** well. Use HTML tags.
+
+``` + +
+
Definition list
+
Is something people use sometimes.
+ +
Markdown in HTML
+
Does *not* work **very** well. Use HTML tags.
+
+ +## 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 <Enter> 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//notification?auth_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:///issues/?jql=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:///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:///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:///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",} +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 +johndoe = John Doe +``` + +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 ` and `--password /.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 : 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 /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 & merge it to the main branch. diff --git a/doc/web_hooks/ssl.png b/doc/web_hooks/ssl.png deleted file mode 100644 index 698f1a0f64a..00000000000 Binary files a/doc/web_hooks/ssl.png and /dev/null differ diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md deleted file mode 100644 index 8559b67af04..00000000000 --- a/doc/web_hooks/web_hooks.md +++ /dev/null @@ -1,784 +0,0 @@ -# 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",} -example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 -- -> / -``` diff --git a/doc/workflow/README.md b/doc/workflow/README.md deleted file mode 100644 index 9efe41308dc..00000000000 --- a/doc/workflow/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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/workflow/add-user/add-user.md b/doc/workflow/add-user/add-user.md deleted file mode 100644 index 4b551130255..00000000000 --- a/doc/workflow/add-user/add-user.md +++ /dev/null @@ -1,111 +0,0 @@ -# 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/workflow/add-user/img/access_requests_management.png b/doc/workflow/add-user/img/access_requests_management.png deleted file mode 100644 index e9641cb4f85..00000000000 Binary files a/doc/workflow/add-user/img/access_requests_management.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_new_user_to_project_settings.png b/doc/workflow/add-user/img/add_new_user_to_project_settings.png deleted file mode 100644 index 3da18cdae53..00000000000 Binary files a/doc/workflow/add-user/img/add_new_user_to_project_settings.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_email_accept.png b/doc/workflow/add-user/img/add_user_email_accept.png deleted file mode 100644 index 18aabf93d50..00000000000 Binary files a/doc/workflow/add-user/img/add_user_email_accept.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_email_ready.png b/doc/workflow/add-user/img/add_user_email_ready.png deleted file mode 100644 index 385d64330c0..00000000000 Binary files a/doc/workflow/add-user/img/add_user_email_ready.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_email_search.png b/doc/workflow/add-user/img/add_user_email_search.png deleted file mode 100644 index 84741edbca4..00000000000 Binary files a/doc/workflow/add-user/img/add_user_email_search.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_give_permissions.png b/doc/workflow/add-user/img/add_user_give_permissions.png deleted file mode 100644 index 7e580384e54..00000000000 Binary files a/doc/workflow/add-user/img/add_user_give_permissions.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_import_members_from_another_project.png b/doc/workflow/add-user/img/add_user_import_members_from_another_project.png deleted file mode 100644 index 8dbd73a5bc8..00000000000 Binary files a/doc/workflow/add-user/img/add_user_import_members_from_another_project.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_imported_members.png b/doc/workflow/add-user/img/add_user_imported_members.png deleted file mode 100644 index abac1f59c02..00000000000 Binary files a/doc/workflow/add-user/img/add_user_imported_members.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_list_members.png b/doc/workflow/add-user/img/add_user_list_members.png deleted file mode 100644 index e17d88c6f5f..00000000000 Binary files a/doc/workflow/add-user/img/add_user_list_members.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_members_menu.png b/doc/workflow/add-user/img/add_user_members_menu.png deleted file mode 100644 index ec5d39f402d..00000000000 Binary files a/doc/workflow/add-user/img/add_user_members_menu.png and /dev/null differ diff --git a/doc/workflow/add-user/img/add_user_search_people.png b/doc/workflow/add-user/img/add_user_search_people.png deleted file mode 100644 index eaa062376f4..00000000000 Binary files a/doc/workflow/add-user/img/add_user_search_people.png and /dev/null differ diff --git a/doc/workflow/add-user/img/request_access_button.png b/doc/workflow/add-user/img/request_access_button.png deleted file mode 100644 index 984d640b0f0..00000000000 Binary files a/doc/workflow/add-user/img/request_access_button.png and /dev/null differ diff --git a/doc/workflow/add-user/img/withdraw_access_request_button.png b/doc/workflow/add-user/img/withdraw_access_request_button.png deleted file mode 100644 index ff54a0e4384..00000000000 Binary files a/doc/workflow/add-user/img/withdraw_access_request_button.png and /dev/null differ diff --git a/doc/workflow/authorization_for_merge_requests.md b/doc/workflow/authorization_for_merge_requests.md deleted file mode 100644 index d1d6d94ec11..00000000000 --- a/doc/workflow/authorization_for_merge_requests.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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/workflow/award_emoji.md b/doc/workflow/award_emoji.md deleted file mode 100644 index 70b35c58be6..00000000000 --- a/doc/workflow/award_emoji.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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/workflow/award_emoji.png b/doc/workflow/award_emoji.png deleted file mode 100644 index fb26ee04393..00000000000 Binary files a/doc/workflow/award_emoji.png and /dev/null differ diff --git a/doc/workflow/cherry_pick_changes.md b/doc/workflow/cherry_pick_changes.md deleted file mode 100644 index 4a499009842..00000000000 --- a/doc/workflow/cherry_pick_changes.md +++ /dev/null @@ -1,53 +0,0 @@ -# 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/workflow/ci_mr.png b/doc/workflow/ci_mr.png deleted file mode 100644 index a577356f8e8..00000000000 Binary files a/doc/workflow/ci_mr.png and /dev/null differ diff --git a/doc/workflow/close_issue_mr.png b/doc/workflow/close_issue_mr.png deleted file mode 100644 index a136d642e12..00000000000 Binary files a/doc/workflow/close_issue_mr.png and /dev/null differ diff --git a/doc/workflow/environment_branches.png b/doc/workflow/environment_branches.png deleted file mode 100644 index ee893ced13b..00000000000 Binary files a/doc/workflow/environment_branches.png and /dev/null differ diff --git a/doc/workflow/file_finder.md b/doc/workflow/file_finder.md deleted file mode 100644 index b69ae663272..00000000000 --- a/doc/workflow/file_finder.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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/workflow/forking/branch_select.png b/doc/workflow/forking/branch_select.png deleted file mode 100644 index 275f64d113b..00000000000 Binary files a/doc/workflow/forking/branch_select.png and /dev/null differ diff --git a/doc/workflow/forking/merge_request.png b/doc/workflow/forking/merge_request.png deleted file mode 100644 index 2dc00ed08a1..00000000000 Binary files a/doc/workflow/forking/merge_request.png and /dev/null differ diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md deleted file mode 100644 index 217a4a4012f..00000000000 --- a/doc/workflow/forking_workflow.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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/workflow/four_stages.png b/doc/workflow/four_stages.png deleted file mode 100644 index 2f444fc6f79..00000000000 Binary files a/doc/workflow/four_stages.png and /dev/null differ diff --git a/doc/workflow/git_pull.png b/doc/workflow/git_pull.png deleted file mode 100644 index 7d47064eb14..00000000000 Binary files a/doc/workflow/git_pull.png and /dev/null differ diff --git a/doc/workflow/gitdashflow.png b/doc/workflow/gitdashflow.png deleted file mode 100644 index f2f091dd10b..00000000000 Binary files a/doc/workflow/gitdashflow.png and /dev/null differ diff --git a/doc/workflow/github_flow.png b/doc/workflow/github_flow.png deleted file mode 100644 index 88addb623ee..00000000000 Binary files a/doc/workflow/github_flow.png and /dev/null differ diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md deleted file mode 100644 index 2b2f140f8bf..00000000000 --- a/doc/workflow/gitlab_flow.md +++ /dev/null @@ -1,317 +0,0 @@ -![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/workflow/gitlab_flow.png b/doc/workflow/gitlab_flow.png deleted file mode 100644 index 1ea191a672b..00000000000 Binary files a/doc/workflow/gitlab_flow.png and /dev/null differ diff --git a/doc/workflow/good_commit.png b/doc/workflow/good_commit.png deleted file mode 100644 index 3737a026644..00000000000 Binary files a/doc/workflow/good_commit.png and /dev/null differ diff --git a/doc/workflow/groups.md b/doc/workflow/groups.md deleted file mode 100644 index 1a316e80976..00000000000 --- a/doc/workflow/groups.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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/workflow/groups/access_requests_management.png b/doc/workflow/groups/access_requests_management.png deleted file mode 100644 index ffede8e9bd6..00000000000 Binary files a/doc/workflow/groups/access_requests_management.png and /dev/null differ diff --git a/doc/workflow/groups/add_member_to_group.png b/doc/workflow/groups/add_member_to_group.png deleted file mode 100644 index fa340ce572f..00000000000 Binary files a/doc/workflow/groups/add_member_to_group.png and /dev/null differ diff --git a/doc/workflow/groups/group_dashboard.png b/doc/workflow/groups/group_dashboard.png deleted file mode 100644 index 7fc9048d74d..00000000000 Binary files a/doc/workflow/groups/group_dashboard.png and /dev/null differ diff --git a/doc/workflow/groups/group_with_two_projects.png b/doc/workflow/groups/group_with_two_projects.png deleted file mode 100644 index 87242781e4f..00000000000 Binary files a/doc/workflow/groups/group_with_two_projects.png and /dev/null differ diff --git a/doc/workflow/groups/max_access_level.png b/doc/workflow/groups/max_access_level.png deleted file mode 100644 index 71106a8a5a0..00000000000 Binary files a/doc/workflow/groups/max_access_level.png and /dev/null differ diff --git a/doc/workflow/groups/new_group_button.png b/doc/workflow/groups/new_group_button.png deleted file mode 100644 index 51e82798658..00000000000 Binary files a/doc/workflow/groups/new_group_button.png and /dev/null differ diff --git a/doc/workflow/groups/new_group_form.png b/doc/workflow/groups/new_group_form.png deleted file mode 100644 index bf992c40bc2..00000000000 Binary files a/doc/workflow/groups/new_group_form.png and /dev/null differ diff --git a/doc/workflow/groups/other_group_sees_shared_project.png b/doc/workflow/groups/other_group_sees_shared_project.png deleted file mode 100644 index cbf2c3c1fdc..00000000000 Binary files a/doc/workflow/groups/other_group_sees_shared_project.png and /dev/null differ diff --git a/doc/workflow/groups/override_access_level.png b/doc/workflow/groups/override_access_level.png deleted file mode 100644 index f4225a63679..00000000000 Binary files a/doc/workflow/groups/override_access_level.png and /dev/null differ diff --git a/doc/workflow/groups/project_members_via_group.png b/doc/workflow/groups/project_members_via_group.png deleted file mode 100644 index b13cb1cfd95..00000000000 Binary files a/doc/workflow/groups/project_members_via_group.png and /dev/null differ diff --git a/doc/workflow/groups/request_access_button.png b/doc/workflow/groups/request_access_button.png deleted file mode 100644 index ff0ac8747a7..00000000000 Binary files a/doc/workflow/groups/request_access_button.png and /dev/null differ diff --git a/doc/workflow/groups/share_project_with_groups.png b/doc/workflow/groups/share_project_with_groups.png deleted file mode 100644 index a5dbc89fe90..00000000000 Binary files a/doc/workflow/groups/share_project_with_groups.png and /dev/null differ diff --git a/doc/workflow/groups/transfer_project.png b/doc/workflow/groups/transfer_project.png deleted file mode 100644 index 044fe10d073..00000000000 Binary files a/doc/workflow/groups/transfer_project.png and /dev/null differ diff --git a/doc/workflow/groups/withdraw_access_request_button.png b/doc/workflow/groups/withdraw_access_request_button.png deleted file mode 100644 index 99d7a326ed8..00000000000 Binary files a/doc/workflow/groups/withdraw_access_request_button.png and /dev/null differ diff --git a/doc/workflow/img/award_emoji_select.png b/doc/workflow/img/award_emoji_select.png deleted file mode 100644 index fffdfedda5d..00000000000 Binary files a/doc/workflow/img/award_emoji_select.png and /dev/null differ diff --git a/doc/workflow/img/award_emoji_votes_least_popular.png b/doc/workflow/img/award_emoji_votes_least_popular.png deleted file mode 100644 index 2ef5be7154f..00000000000 Binary files a/doc/workflow/img/award_emoji_votes_least_popular.png and /dev/null differ diff --git a/doc/workflow/img/award_emoji_votes_most_popular.png b/doc/workflow/img/award_emoji_votes_most_popular.png deleted file mode 100644 index 5b089730d93..00000000000 Binary files a/doc/workflow/img/award_emoji_votes_most_popular.png and /dev/null differ diff --git a/doc/workflow/img/award_emoji_votes_sort_options.png b/doc/workflow/img/award_emoji_votes_sort_options.png deleted file mode 100644 index 9bbf3f82a0b..00000000000 Binary files a/doc/workflow/img/award_emoji_votes_sort_options.png and /dev/null differ diff --git a/doc/workflow/img/cherry_pick_changes_commit.png b/doc/workflow/img/cherry_pick_changes_commit.png deleted file mode 100644 index ae91d2cae53..00000000000 Binary files a/doc/workflow/img/cherry_pick_changes_commit.png and /dev/null differ diff --git a/doc/workflow/img/cherry_pick_changes_commit_modal.png b/doc/workflow/img/cherry_pick_changes_commit_modal.png deleted file mode 100644 index f502f87677a..00000000000 Binary files a/doc/workflow/img/cherry_pick_changes_commit_modal.png and /dev/null differ diff --git a/doc/workflow/img/cherry_pick_changes_mr.png b/doc/workflow/img/cherry_pick_changes_mr.png deleted file mode 100644 index 59c610e620b..00000000000 Binary files a/doc/workflow/img/cherry_pick_changes_mr.png and /dev/null differ diff --git a/doc/workflow/img/cherry_pick_changes_mr_modal.png b/doc/workflow/img/cherry_pick_changes_mr_modal.png deleted file mode 100644 index 96a80f4726d..00000000000 Binary files a/doc/workflow/img/cherry_pick_changes_mr_modal.png and /dev/null differ diff --git a/doc/workflow/img/file_finder_find_button.png b/doc/workflow/img/file_finder_find_button.png deleted file mode 100644 index c5005d0d7ca..00000000000 Binary files a/doc/workflow/img/file_finder_find_button.png and /dev/null differ diff --git a/doc/workflow/img/file_finder_find_file.png b/doc/workflow/img/file_finder_find_file.png deleted file mode 100644 index 58500f4c163..00000000000 Binary files a/doc/workflow/img/file_finder_find_file.png and /dev/null differ diff --git a/doc/workflow/img/forking_workflow_choose_namespace.png b/doc/workflow/img/forking_workflow_choose_namespace.png deleted file mode 100644 index eefe5769554..00000000000 Binary files a/doc/workflow/img/forking_workflow_choose_namespace.png and /dev/null differ diff --git a/doc/workflow/img/forking_workflow_fork_button.png b/doc/workflow/img/forking_workflow_fork_button.png deleted file mode 100644 index 49e68d33e89..00000000000 Binary files a/doc/workflow/img/forking_workflow_fork_button.png and /dev/null differ diff --git a/doc/workflow/img/forking_workflow_path_taken_error.png b/doc/workflow/img/forking_workflow_path_taken_error.png deleted file mode 100644 index 7a3139506fe..00000000000 Binary files a/doc/workflow/img/forking_workflow_path_taken_error.png and /dev/null differ diff --git a/doc/workflow/img/new_branch_from_issue.png b/doc/workflow/img/new_branch_from_issue.png deleted file mode 100644 index 394c139e17e..00000000000 Binary files a/doc/workflow/img/new_branch_from_issue.png and /dev/null differ diff --git a/doc/workflow/img/revert_changes_commit.png b/doc/workflow/img/revert_changes_commit.png deleted file mode 100644 index d84211e20db..00000000000 Binary files a/doc/workflow/img/revert_changes_commit.png and /dev/null differ diff --git a/doc/workflow/img/revert_changes_commit_modal.png b/doc/workflow/img/revert_changes_commit_modal.png deleted file mode 100644 index e94d151a2af..00000000000 Binary files a/doc/workflow/img/revert_changes_commit_modal.png and /dev/null differ diff --git a/doc/workflow/img/revert_changes_mr.png b/doc/workflow/img/revert_changes_mr.png deleted file mode 100644 index 7adad88463b..00000000000 Binary files a/doc/workflow/img/revert_changes_mr.png and /dev/null differ diff --git a/doc/workflow/img/revert_changes_mr_modal.png b/doc/workflow/img/revert_changes_mr_modal.png deleted file mode 100644 index 9da78f84828..00000000000 Binary files a/doc/workflow/img/revert_changes_mr_modal.png and /dev/null differ diff --git a/doc/workflow/img/todos_icon.png b/doc/workflow/img/todos_icon.png deleted file mode 100644 index 879b3b51c21..00000000000 Binary files a/doc/workflow/img/todos_icon.png and /dev/null differ diff --git a/doc/workflow/img/todos_index.png b/doc/workflow/img/todos_index.png deleted file mode 100644 index 4ee18dd1285..00000000000 Binary files a/doc/workflow/img/todos_index.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_branch_dropdown.png b/doc/workflow/img/web_editor_new_branch_dropdown.png deleted file mode 100644 index 009e4b05adf..00000000000 Binary files a/doc/workflow/img/web_editor_new_branch_dropdown.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_branch_page.png b/doc/workflow/img/web_editor_new_branch_page.png deleted file mode 100644 index dd6cfc6e7bb..00000000000 Binary files a/doc/workflow/img/web_editor_new_branch_page.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_directory_dialog.png b/doc/workflow/img/web_editor_new_directory_dialog.png deleted file mode 100644 index 2c76f84f395..00000000000 Binary files a/doc/workflow/img/web_editor_new_directory_dialog.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_directory_dropdown.png b/doc/workflow/img/web_editor_new_directory_dropdown.png deleted file mode 100644 index cedf46aedfd..00000000000 Binary files a/doc/workflow/img/web_editor_new_directory_dropdown.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_file_dropdown.png b/doc/workflow/img/web_editor_new_file_dropdown.png deleted file mode 100644 index 6e884f6504d..00000000000 Binary files a/doc/workflow/img/web_editor_new_file_dropdown.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_file_editor.png b/doc/workflow/img/web_editor_new_file_editor.png deleted file mode 100644 index c76473bcfa7..00000000000 Binary files a/doc/workflow/img/web_editor_new_file_editor.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_push_widget.png b/doc/workflow/img/web_editor_new_push_widget.png deleted file mode 100644 index a2108735741..00000000000 Binary files a/doc/workflow/img/web_editor_new_push_widget.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_tag_dropdown.png b/doc/workflow/img/web_editor_new_tag_dropdown.png deleted file mode 100644 index 263dd635b95..00000000000 Binary files a/doc/workflow/img/web_editor_new_tag_dropdown.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_new_tag_page.png b/doc/workflow/img/web_editor_new_tag_page.png deleted file mode 100644 index 64d7cd11ed1..00000000000 Binary files a/doc/workflow/img/web_editor_new_tag_page.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_start_new_merge_request.png b/doc/workflow/img/web_editor_start_new_merge_request.png deleted file mode 100644 index be12a151cac..00000000000 Binary files a/doc/workflow/img/web_editor_start_new_merge_request.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_upload_file_dialog.png b/doc/workflow/img/web_editor_upload_file_dialog.png deleted file mode 100644 index 6dd2207bca0..00000000000 Binary files a/doc/workflow/img/web_editor_upload_file_dialog.png and /dev/null differ diff --git a/doc/workflow/img/web_editor_upload_file_dropdown.png b/doc/workflow/img/web_editor_upload_file_dropdown.png deleted file mode 100644 index bf6528701b0..00000000000 Binary files a/doc/workflow/img/web_editor_upload_file_dropdown.png and /dev/null differ diff --git a/doc/workflow/importing/README.md b/doc/workflow/importing/README.md deleted file mode 100644 index 18e5d950866..00000000000 --- a/doc/workflow/importing/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# 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/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png b/doc/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png deleted file mode 100644 index df55a081803..00000000000 Binary files a/doc/workflow/importing/bitbucket_importer/bitbucket_import_grant_access.png and /dev/null differ diff --git a/doc/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png b/doc/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png deleted file mode 100644 index 5253889d251..00000000000 Binary files a/doc/workflow/importing/bitbucket_importer/bitbucket_import_new_project.png and /dev/null differ diff --git a/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png b/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png deleted file mode 100644 index ffa87ce5b2e..00000000000 Binary files a/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_bitbucket.png and /dev/null differ diff --git a/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png b/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png deleted file mode 100644 index 0e08703f421..00000000000 Binary files a/doc/workflow/importing/bitbucket_importer/bitbucket_import_select_project.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png deleted file mode 100644 index 205c515bd3f..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_finished.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png deleted file mode 100644 index a1e348d46ad..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_login.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png deleted file mode 100644 index ed362846909..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_fogbogz.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png deleted file mode 100644 index d2fbd0267bd..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_select_project.png and /dev/null differ diff --git a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png b/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png deleted file mode 100644 index b1cc4b58525..00000000000 Binary files a/doc/workflow/importing/fogbugz_importer/fogbugz_import_user_map.png and /dev/null differ diff --git a/doc/workflow/importing/gitlab_importer/importer.png b/doc/workflow/importing/gitlab_importer/importer.png deleted file mode 100644 index d2a286d8cac..00000000000 Binary files a/doc/workflow/importing/gitlab_importer/importer.png and /dev/null differ diff --git a/doc/workflow/importing/gitlab_importer/new_project_page.png b/doc/workflow/importing/gitlab_importer/new_project_page.png deleted file mode 100644 index 5e239208e1e..00000000000 Binary files a/doc/workflow/importing/gitlab_importer/new_project_page.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/workflow/importing/img/import_projects_from_github_importer.png deleted file mode 100644 index f744dc06f81..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_github_importer.png and /dev/null differ diff --git a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png deleted file mode 100644 index 86be35acb37..00000000000 Binary files a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png and /dev/null differ diff --git a/doc/workflow/importing/import_projects_from_bitbucket.md b/doc/workflow/importing/import_projects_from_bitbucket.md deleted file mode 100644 index 520c4216295..00000000000 --- a/doc/workflow/importing/import_projects_from_bitbucket.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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/workflow/importing/import_projects_from_fogbugz.md b/doc/workflow/importing/import_projects_from_fogbugz.md deleted file mode 100644 index 71af0f9ea44..00000000000 --- a/doc/workflow/importing/import_projects_from_fogbugz.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md deleted file mode 100644 index a7dfac2c120..00000000000 --- a/doc/workflow/importing/import_projects_from_github.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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/workflow/importing/import_projects_from_gitlab_com.md b/doc/workflow/importing/import_projects_from_gitlab_com.md deleted file mode 100644 index dcc00074b75..00000000000 --- a/doc/workflow/importing/import_projects_from_gitlab_com.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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/workflow/importing/migrating_from_svn.md b/doc/workflow/importing/migrating_from_svn.md deleted file mode 100644 index 4828bb5dce6..00000000000 --- a/doc/workflow/importing/migrating_from_svn.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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 -johndoe = John Doe -``` - -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 ` and `--password /.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/workflow/labels.md b/doc/workflow/labels.md deleted file mode 100644 index 6e4840ca5ae..00000000000 --- a/doc/workflow/labels.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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/workflow/labels/label1.png b/doc/workflow/labels/label1.png deleted file mode 100644 index cac661a34c8..00000000000 Binary files a/doc/workflow/labels/label1.png and /dev/null differ diff --git a/doc/workflow/labels/label2.png b/doc/workflow/labels/label2.png deleted file mode 100644 index 44d9fef86d4..00000000000 Binary files a/doc/workflow/labels/label2.png and /dev/null differ diff --git a/doc/workflow/labels/label3.png b/doc/workflow/labels/label3.png deleted file mode 100644 index e2fce11b7a4..00000000000 Binary files a/doc/workflow/labels/label3.png and /dev/null differ diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md deleted file mode 100644 index 9dc1e9b47e3..00000000000 --- a/doc/workflow/lfs/lfs_administration.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md deleted file mode 100644 index 9fe065fa680..00000000000 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ /dev/null @@ -1,155 +0,0 @@ -# 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 : 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 /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/workflow/merge_commits.png b/doc/workflow/merge_commits.png deleted file mode 100644 index 757b589d0db..00000000000 Binary files a/doc/workflow/merge_commits.png and /dev/null differ diff --git a/doc/workflow/merge_request.png b/doc/workflow/merge_request.png deleted file mode 100644 index fde3ff5c854..00000000000 Binary files a/doc/workflow/merge_request.png and /dev/null differ diff --git a/doc/workflow/merge_requests.md b/doc/workflow/merge_requests.md deleted file mode 100644 index d2ec56e6504..00000000000 --- a/doc/workflow/merge_requests.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/workflow/merge_requests/commit_compare.png b/doc/workflow/merge_requests/commit_compare.png deleted file mode 100644 index dfd7ee220f0..00000000000 Binary files a/doc/workflow/merge_requests/commit_compare.png and /dev/null differ diff --git a/doc/workflow/merge_requests/merge_request_diff.png b/doc/workflow/merge_requests/merge_request_diff.png deleted file mode 100644 index f368423c746..00000000000 Binary files a/doc/workflow/merge_requests/merge_request_diff.png and /dev/null differ diff --git a/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png b/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png deleted file mode 100644 index b2d03bb66f9..00000000000 Binary files a/doc/workflow/merge_requests/merge_request_diff_without_whitespace.png and /dev/null differ diff --git a/doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png b/doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png deleted file mode 100644 index 18bebf5fe92..00000000000 Binary files a/doc/workflow/merge_requests/only_allow_merge_if_build_succeeds.png and /dev/null differ diff --git a/doc/workflow/merge_when_build_succeeds.md b/doc/workflow/merge_when_build_succeeds.md deleted file mode 100644 index 75e1fdff2b2..00000000000 --- a/doc/workflow/merge_when_build_succeeds.md +++ /dev/null @@ -1,15 +0,0 @@ -# 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/workflow/merge_when_build_succeeds/enable.png b/doc/workflow/merge_when_build_succeeds/enable.png deleted file mode 100644 index 633efa1246f..00000000000 Binary files a/doc/workflow/merge_when_build_succeeds/enable.png and /dev/null differ diff --git a/doc/workflow/merge_when_build_succeeds/status.png b/doc/workflow/merge_when_build_succeeds/status.png deleted file mode 100644 index c856c7d14dc..00000000000 Binary files a/doc/workflow/merge_when_build_succeeds/status.png and /dev/null differ diff --git a/doc/workflow/messy_flow.png b/doc/workflow/messy_flow.png deleted file mode 100644 index 1addb95ca54..00000000000 Binary files a/doc/workflow/messy_flow.png and /dev/null differ diff --git a/doc/workflow/milestones.md b/doc/workflow/milestones.md deleted file mode 100644 index dff36899aec..00000000000 --- a/doc/workflow/milestones.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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/workflow/milestones/form.png b/doc/workflow/milestones/form.png deleted file mode 100644 index de44c1ffc1a..00000000000 Binary files a/doc/workflow/milestones/form.png and /dev/null differ diff --git a/doc/workflow/milestones/group_form.png b/doc/workflow/milestones/group_form.png deleted file mode 100644 index 38862dcca68..00000000000 Binary files a/doc/workflow/milestones/group_form.png and /dev/null differ diff --git a/doc/workflow/mr_inline_comments.png b/doc/workflow/mr_inline_comments.png deleted file mode 100644 index e851b95bcef..00000000000 Binary files a/doc/workflow/mr_inline_comments.png and /dev/null differ diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md deleted file mode 100644 index fe4485e148a..00000000000 --- a/doc/workflow/notifications.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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/workflow/notifications/settings.png b/doc/workflow/notifications/settings.png deleted file mode 100644 index 7c6857aad1a..00000000000 Binary files a/doc/workflow/notifications/settings.png and /dev/null differ diff --git a/doc/workflow/production_branch.png b/doc/workflow/production_branch.png deleted file mode 100644 index 33fb26dd621..00000000000 Binary files a/doc/workflow/production_branch.png and /dev/null differ diff --git a/doc/workflow/project_features.md b/doc/workflow/project_features.md deleted file mode 100644 index a523b3facbe..00000000000 --- a/doc/workflow/project_features.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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/workflow/protected_branches.md b/doc/workflow/protected_branches.md deleted file mode 100644 index d854ec1e025..00000000000 --- a/doc/workflow/protected_branches.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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/workflow/protected_branches/protected_branches1.png b/doc/workflow/protected_branches/protected_branches1.png deleted file mode 100644 index 5c2a3de5f70..00000000000 Binary files a/doc/workflow/protected_branches/protected_branches1.png and /dev/null differ diff --git a/doc/workflow/protected_branches/protected_branches2.png b/doc/workflow/protected_branches/protected_branches2.png deleted file mode 100644 index 2dca3541365..00000000000 Binary files a/doc/workflow/protected_branches/protected_branches2.png and /dev/null differ diff --git a/doc/workflow/rebase.png b/doc/workflow/rebase.png deleted file mode 100644 index ef82c834755..00000000000 Binary files a/doc/workflow/rebase.png and /dev/null differ diff --git a/doc/workflow/release_branches.png b/doc/workflow/release_branches.png deleted file mode 100644 index da7ae53413a..00000000000 Binary files a/doc/workflow/release_branches.png and /dev/null differ diff --git a/doc/workflow/releases.md b/doc/workflow/releases.md deleted file mode 100644 index 6176784fc57..00000000000 --- a/doc/workflow/releases.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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/workflow/releases/new_tag.png b/doc/workflow/releases/new_tag.png deleted file mode 100644 index e2b64bfe17f..00000000000 Binary files a/doc/workflow/releases/new_tag.png and /dev/null differ diff --git a/doc/workflow/releases/tags.png b/doc/workflow/releases/tags.png deleted file mode 100644 index aca91906c68..00000000000 Binary files a/doc/workflow/releases/tags.png and /dev/null differ diff --git a/doc/workflow/remove_checkbox.png b/doc/workflow/remove_checkbox.png deleted file mode 100644 index 3e247d38155..00000000000 Binary files a/doc/workflow/remove_checkbox.png and /dev/null differ diff --git a/doc/workflow/revert_changes.md b/doc/workflow/revert_changes.md deleted file mode 100644 index 399366b0cdc..00000000000 --- a/doc/workflow/revert_changes.md +++ /dev/null @@ -1,64 +0,0 @@ -# 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/workflow/share_projects_with_other_groups.md b/doc/workflow/share_projects_with_other_groups.md deleted file mode 100644 index 4c59f59c587..00000000000 --- a/doc/workflow/share_projects_with_other_groups.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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/workflow/share_with_group.md b/doc/workflow/share_with_group.md deleted file mode 100644 index 3b7690973cb..00000000000 --- a/doc/workflow/share_with_group.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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/workflow/share_with_group.png b/doc/workflow/share_with_group.png deleted file mode 100644 index a0ca6f14552..00000000000 Binary files a/doc/workflow/share_with_group.png and /dev/null differ diff --git a/doc/workflow/shortcuts.md b/doc/workflow/shortcuts.md deleted file mode 100644 index ffcb832cdd7..00000000000 --- a/doc/workflow/shortcuts.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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/workflow/shortcuts.png b/doc/workflow/shortcuts.png deleted file mode 100644 index 16be0413b64..00000000000 Binary files a/doc/workflow/shortcuts.png and /dev/null differ diff --git a/doc/workflow/timezone.md b/doc/workflow/timezone.md deleted file mode 100644 index 7e08c0e51ac..00000000000 --- a/doc/workflow/timezone.md +++ /dev/null @@ -1,30 +0,0 @@ -# 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/workflow/todos.md b/doc/workflow/todos.md deleted file mode 100644 index 5f440fdafdd..00000000000 --- a/doc/workflow/todos.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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/workflow/web_editor.md b/doc/workflow/web_editor.md deleted file mode 100644 index 1832567a34c..00000000000 --- a/doc/workflow/web_editor.md +++ /dev/null @@ -1,152 +0,0 @@ -# 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/workflow/wip_merge_requests.md b/doc/workflow/wip_merge_requests.md deleted file mode 100644 index 46035a5e6b6..00000000000 --- a/doc/workflow/wip_merge_requests.md +++ /dev/null @@ -1,13 +0,0 @@ -# "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/workflow/wip_merge_requests/blocked_accept_button.png b/doc/workflow/wip_merge_requests/blocked_accept_button.png deleted file mode 100644 index 4791e5de972..00000000000 Binary files a/doc/workflow/wip_merge_requests/blocked_accept_button.png and /dev/null differ diff --git a/doc/workflow/wip_merge_requests/mark_as_wip.png b/doc/workflow/wip_merge_requests/mark_as_wip.png deleted file mode 100644 index 8fa83a201ac..00000000000 Binary files a/doc/workflow/wip_merge_requests/mark_as_wip.png and /dev/null differ diff --git a/doc/workflow/wip_merge_requests/unmark_as_wip.png b/doc/workflow/wip_merge_requests/unmark_as_wip.png deleted file mode 100644 index d45e68f31c5..00000000000 Binary files a/doc/workflow/wip_merge_requests/unmark_as_wip.png and /dev/null differ diff --git a/doc/workflow/workflow.md b/doc/workflow/workflow.md deleted file mode 100644 index f70e41df842..00000000000 --- a/doc/workflow/workflow.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 & merge it to the main branch. -- cgit v1.2.1