diff options
| author | Valery Sizov <valery@gitlab.com> | 2016-12-14 12:36:27 +0200 |
|---|---|---|
| committer | Valery Sizov <valery@gitlab.com> | 2016-12-14 12:36:27 +0200 |
| commit | 468d575fc73881900f4a4cb1fa71c187d77429a7 (patch) | |
| tree | 05b00d7f00e04202c34de41e6feb566426e19e3f /doc | |
| parent | 8f0cef0b6e5e950efdf3ebfe8f9f846095fff9d9 (diff) | |
| parent | 78f89f7ad900ec2f2993a70caa2eb5dbf9e2496f (diff) | |
| download | gitlab-ce-468d575fc73881900f4a4cb1fa71c187d77429a7.tar.gz | |
Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into bitbucket-oauth2
Diffstat (limited to 'doc')
93 files changed, 1553 insertions, 567 deletions
diff --git a/doc/README.md b/doc/README.md index 66c8c26e4f0..eba1e9845b1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,4 +1,4 @@ -# Documentation +# GitLab Community Edition documentation ## User documentation diff --git a/doc/administration/build_artifacts.md b/doc/administration/build_artifacts.md index 64353f7282b..3ba8387c7f0 100644 --- a/doc/administration/build_artifacts.md +++ b/doc/administration/build_artifacts.md @@ -84,7 +84,7 @@ _The artifacts are stored by default in ## Set the maximum file size of the artifacts Provided the artifacts are enabled, you can change the maximum file size of the -artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration#maximum-artifacts-size). +artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). [reconfigure gitlab]: restart_gitlab.md "How to restart GitLab" [restart gitlab]: restart_gitlab.md "How to restart GitLab" diff --git a/doc/administration/custom_hooks.md b/doc/administration/custom_hooks.md index 0387d730489..06291705702 100644 --- a/doc/administration/custom_hooks.md +++ b/doc/administration/custom_hooks.md @@ -42,6 +42,25 @@ Follow the steps below to set up a custom hook: That's it! Assuming the hook code is properly implemented the hook will fire as appropriate. +## Chained hooks support + +> [Introduced][93] in GitLab Shell 4.1.0. + +The hooks could be also placed in `hooks/<hook_name>.d` (global) or `custom_hooks/<hook_name>.d` (per project) +directories supporting chained execution of the hooks. + +The hooks are searched and executed in this order: +1. `<project>.git/hooks/` - symlink to `gitlab-shell/hooks` global dir +1. `<project>.git/hooks/<hook_name>` - executed by `git` itself, this is `gitlab-shell/hooks/<hook_name>` +1. `<project>.git/custom_hooks/<hook_name>` - per project hook (this is already existing behavior) +1. `<project>.git/custom_hooks/<hook_name>.d/*` - per project hooks +1. `<project>.git/hooks/<hook_name>.d/*` - global hooks: all executable files (minus editor backup files) + +Files in `.d` directories need to be executable and not match the backup file pattern (`*~`). + +The hooks of the same type are executed in order and execution stops on the first +script exiting with non-zero value. + ## Custom error messages > [Introduced][5073] in GitLab 8.10. @@ -54,3 +73,4 @@ STDERR takes precedence over STDOUT. [hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks [5073]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5073 +[93]: https://gitlab.com/gitlab-org/gitlab-shell/merge_requests/93 diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index 76f3a0fb387..b36cf18d459 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -41,7 +41,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL: mailroom['enable'] = false # PostgreSQL configuration - postgresql['sql_password'] = 'DB password' + gitlab_rails['db_password'] = 'DB password' postgresql['md5_auth_cidr_addresses'] = ['0.0.0.0/0'] postgresql['listen_address'] = '0.0.0.0' ``` @@ -80,7 +80,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Similarly, set the password for the `gitlab` database user. Use the same password that you specified in the `/etc/gitlab/gitlab.rb` file for - `postgresql['sql_password']`. + `gitlab_rails['db_password']`. ``` \password gitlab diff --git a/doc/api/branches.md b/doc/api/branches.md index 07dfa5d4d7f..ffcfea41453 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -22,6 +22,7 @@ Example response: [ { "name": "master", + "merged": false, "protected": true, "developers_can_push": false, "developers_can_merge": false, @@ -65,6 +66,7 @@ Example response: ```json { "name": "master", + "merged": false, "protected": true, "developers_can_push": false, "developers_can_merge": false, @@ -123,6 +125,7 @@ Example response: ] }, "name": "master", + "merged": false, "protected": true, "developers_can_push": true, "developers_can_merge": true @@ -166,6 +169,7 @@ Example response: ] }, "name": "master", + "merged": false, "protected": false, "developers_can_push": false, "developers_can_merge": false @@ -206,6 +210,7 @@ Example response: ] }, "name": "newbranch", + "merged": false, "protected": false, "developers_can_push": false, "developers_can_merge": false diff --git a/doc/api/build_triggers.md b/doc/api/build_triggers.md index 1b7a1840138..b6459971420 100644 --- a/doc/api/build_triggers.md +++ b/doc/api/build_triggers.md @@ -15,7 +15,7 @@ GET /projects/:id/triggers | `id` | integer | yes | The ID of a project | ``` -curl --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" ``` ```json @@ -51,7 +51,7 @@ GET /projects/:id/triggers/:token | `token` | string | yes | The `token` of a trigger | ``` -curl --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" ``` ```json @@ -77,7 +77,7 @@ POST /projects/:id/triggers | `id` | integer | yes | The ID of a project | ``` -curl --request POST --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" ``` ```json @@ -104,7 +104,7 @@ DELETE /projects/:id/triggers/:token | `token` | string | yes | The `token` of a trigger | ``` -curl --request DELETE --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" ``` ```json diff --git a/doc/api/build_variables.md b/doc/api/build_variables.md index a21751a49ea..917e9773913 100644 --- a/doc/api/build_variables.md +++ b/doc/api/build_variables.md @@ -13,7 +13,7 @@ GET /projects/:id/variables | `id` | integer | yes | The ID of a project | ``` -curl --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" ``` ```json @@ -43,7 +43,7 @@ GET /projects/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/TEST_VARIABLE_1" +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/TEST_VARIABLE_1" ``` ```json @@ -68,7 +68,7 @@ POST /projects/:id/variables | `value` | string | yes | The `value` of a variable | ``` -curl --request POST --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" ``` ```json @@ -93,7 +93,7 @@ PUT /projects/:id/variables/:key | `value` | string | yes | The `value` of a variable | ``` -curl --request PUT --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/NEW_VARIABLE" --form "value=updated value" +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/NEW_VARIABLE" --form "value=updated value" ``` ```json @@ -117,7 +117,7 @@ DELETE /projects/:id/variables/:key | `key` | string | yes | The `key` of a variable | ``` -curl --request DELETE --header "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/VARIABLE_1" +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/VARIABLE_1" ``` ```json diff --git a/doc/api/commits.md b/doc/api/commits.md index e1ed99d98d3..5c11d0f83bb 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -29,6 +29,8 @@ Example response: "title": "Replace sanitize with escape once", "author_name": "Dmitriy Zaporozhets", "author_email": "dzaporozhets@sphereconsultinginc.com", + "committer_name": "Administrator", + "committer_email": "admin@example.com", "created_at": "2012-09-20T11:50:22+03:00", "message": "Replace sanitize with escape once", "allow_failure": false @@ -39,6 +41,8 @@ Example response: "title": "Sanitize for network graph", "author_name": "randx", "author_email": "dmitriy.zaporozhets@gmail.com", + "committer_name": "Dmitriy", + "committer_email": "dmitriy.zaporozhets@gmail.com", "created_at": "2012-09-20T09:06:12+03:00", "message": "Sanitize for network graph", "allow_failure": false @@ -115,6 +119,8 @@ Example response: "title": "some commit message", "author_name": "Dmitriy Zaporozhets", "author_email": "dzaporozhets@sphereconsultinginc.com", + "committer_name": "Dmitriy Zaporozhets", + "committer_email": "dzaporozhets@sphereconsultinginc.com", "created_at": "2016-09-20T09:26:24.000-07:00", "message": "some commit message", "parent_ids": [ @@ -159,6 +165,8 @@ Example response: "title": "Sanitize for network graph", "author_name": "randx", "author_email": "dmitriy.zaporozhets@gmail.com", + "committer_name": "Dmitriy", + "committer_email": "dmitriy.zaporozhets@gmail.com", "created_at": "2012-09-20T09:06:12+03:00", "message": "Sanitize for network graph", "committed_date": "2012-09-20T09:06:12+03:00", @@ -175,6 +183,44 @@ Example response: } ``` +## Cherry pick a commit + +> [Introduced][ce-8047] in GitLab 8.15. + +Cherry picks a commit to a given branch. + +``` +POST /projects/:id/repository/commits/:sha/cherry_pick +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `sha` | string | yes | The commit hash | +| `branch` | string | yes | The name of the branch | + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "branch=master" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/cherry_pick" +``` + +Example response: + +```json +{ + "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad", + "short_id": "8b090c1b", + "title": "Feature added", + "author_name": "Dmitriy Zaporozhets", + "author_email": "dmitriy.zaporozhets@gmail.com", + "created_at": "2016-12-12T20:10:39.000+01:00", + "committer_name": "Administrator", + "committer_email": "admin@example.com", + "message": "Feature added\n\nSigned-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>\n" +} +``` + ## Get the diff of a commit Get the diff of a commit in a project. @@ -430,3 +476,4 @@ Example response: ``` [ce-6096]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6096 "Multi-file commit" +[ce-8047]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8047 diff --git a/doc/api/groups.md b/doc/api/groups.md index 5e6f498c365..134d7bda22f 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -50,12 +50,17 @@ GET /groups/:id/projects Parameters: -- `archived` (optional) - if passed, limit by archived status -- `visibility` (optional) - if passed, limit by visibility `public`, `internal`, `private` -- `order_by` (optional) - Return requests ordered by `id`, `name`, `path`, `created_at`, `updated_at` or `last_activity_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` -- `search` (optional) - Return list of authorized projects according to a search criteria -- `ci_enabled_first` - Return projects ordered by ci_enabled flag. Projects with enabled GitLab CI go first +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or path of a group | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | + +Example response: ```json [ diff --git a/doc/api/issues.md b/doc/api/issues.md index 16f8e32c82a..119125bcd3d 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -330,6 +330,7 @@ POST /projects/:id/issues | `labels` | string | no | Comma-separated label names for an issue | | `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_for_resolving_discussions` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -506,7 +507,7 @@ Example response: ## Subscribe to an issue -Subscribes the authenticated user to an issue to receive notifications. +Subscribes the authenticated user to an issue to receive notifications. If the user is already subscribed to the issue, the status code `304` is returned. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 12d24543bbe..662cc9da733 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -271,17 +271,18 @@ Creates a new merge request. POST /projects/:id/merge_requests ``` -Parameters: - -- `id` (required) - The ID of a project -- `source_branch` (required) - The source branch -- `target_branch` (required) - The target branch -- `assignee_id` (optional) - Assignee user ID -- `title` (required) - Title of MR -- `description` (optional) - Description of MR -- `target_project_id` (optional) - The target project (numeric id) -- `labels` (optional) - Labels for MR as a comma-separated list -- `milestone_id` (optional) - Milestone ID +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID of a project | +| `source_branch` | string | yes | The source branch | +| `target_branch` | string | yes | The target branch | +| `title` | string | yes | Title of MR | +| `assignee_id` | integer | no | Assignee user ID | +| `description` | string | no | Description of MR | +| `target_project_id` | integer | no | The target project (numeric id) | +| `labels` | string | no | Labels for MR as a comma-separated list | +| `milestone_id` | integer | no | The ID of a milestone | +| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | ```json { @@ -346,17 +347,19 @@ Updates an existing merge request. You can change the target branch, title, or e PUT /projects/:id/merge_requests/:merge_request_id ``` -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of MR -- `target_branch` - The target branch -- `assignee_id` - Assignee user ID -- `title` - Title of MR -- `description` - Description of MR -- `state_event` - New state (close|reopen|merge) -- `labels` (optional) - Labels for MR as a comma-separated list -- `milestone_id` (optional) - Milestone ID +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | string | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of a merge request | +| `source_branch` | string | yes | The source branch | +| `target_branch` | string | yes | The target branch | +| `title` | string | yes | Title of MR | +| `assignee_id` | integer | no | Assignee user ID | +| `description` | string | no | Description of MR | +| `target_project_id` | integer | no | The target project (numeric id) | +| `labels` | string | no | Labels for MR as a comma-separated list | +| `milestone_id` | integer | no | The ID of a milestone | +| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging | ```json { @@ -426,7 +429,7 @@ DELETE /projects/:id/merge_requests/:merge_request_id | `merge_request_id` | integer | yes | The ID of a project's merge request | ```bash -curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/merge_request/85 +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/merge_requests/85 ``` ## Accept MR @@ -510,7 +513,7 @@ Parameters: } ``` -## Cancel Merge When Build Succeeds +## Cancel Merge When Pipeline Succeeds If you don't have permissions to accept this merge request - you'll get a `401` @@ -807,7 +810,7 @@ Example response: ## Create a todo -Manually creates a todo for the current user on a merge request. +Manually creates a todo for the current user on a merge request. If there already exists a todo for the user on that merge request, status code `304` is returned. diff --git a/doc/api/projects.md b/doc/api/projects.md index 132be644b59..0bc2a5210aa 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -347,7 +347,8 @@ Parameters: ### Get single project Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user. -If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`). +If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`). This endpoint can be accessed without authentication if +the project is publicly accessible. ``` GET /projects/:id @@ -436,10 +437,47 @@ Parameters: } ``` +## Get project users + +Get the users list of a project. + + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `search` | string | no | Search for specific users | + +``` +GET /projects/:id/users +``` + +```json +[ + { + "id": 1, + "username": "john_smith", + "name": "John Smith", + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", + "web_url": "http://localhost:3000/john_smith" + }, + { + "id": 2, + "username": "jack_smith", + "name": "Jack Smith", + "state": "blocked", + "avatar_url": "http://gravatar.com/../e32131cd8.jpeg", + "web_url": "http://localhost:3000/jack_smith" + } +] +``` + ### Get project events -Get the events for the specified project. -Sorted from newest to oldest +Get the events for the specified project sorted from newest to oldest. This +endpoint can be accessed without authentication if the project is publicly +accessible. ``` GET /projects/:id/events @@ -1344,7 +1382,9 @@ Parameter: ## Search for projects by name -Search for projects by name which are accessible to the authenticated user. +Search for projects by name which are accessible to the authenticated user. This +endpoint can be accessed without authentication if the project is publicly +accessible. ``` GET /projects/search/:query diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 1bc6a24e914..b8c9eb2c9a8 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -60,7 +60,7 @@ Parameters: - `file_path` (required) - Full path to new file. Ex. lib/class.rb - `branch_name` (required) - The name of branch -- `encoding` (optional) - 'text' or 'base64'. Text is default. +- `encoding` (optional) - Change encoding to 'base64'. Default is text. - `author_email` (optional) - Specify the commit author's email address - `author_name` (optional) - Specify the commit author's name - `content` (required) - File content @@ -89,7 +89,7 @@ Parameters: - `file_path` (required) - Full path to file. Ex. lib/class.rb - `branch_name` (required) - The name of branch -- `encoding` (optional) - 'text' or 'base64'. Text is default. +- `encoding` (optional) - Change encoding to 'base64'. Default is text. - `author_email` (optional) - Specify the commit author's email address - `author_name` (optional) - Specify the commit author's name - `content` (required) - New file content diff --git a/doc/api/services.md b/doc/api/services.md index a5d733fe6c7..3dad953cd1e 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -139,6 +139,43 @@ Get Buildkite service settings for a project. GET /projects/:id/services/buildkite ``` +## Build-Emails + +Get emails for GitLab CI builds. + +### Create/Edit Build-Emails service + +Set Build-Emails service for a project. + +``` +PUT /projects/:id/services/builds-email +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `recipients` | string | yes | Comma-separated list of recipient email addresses | +| `add_pusher` | boolean | no | Add pusher to recipients list | +| `notify_only_broken_builds` | boolean | no | Notify only broken builds | + + +### Delete Build-Emails service + +Delete Build-Emails service for a project. + +``` +DELETE /projects/:id/services/builds-email +``` + +### Get Build-Emails service settings + +Get Build-Emails service settings for a project. + +``` +GET /projects/:id/services/builds-email +``` + ## Campfire Simple web-based real-time group chat @@ -476,12 +513,11 @@ PUT /projects/:id/services/jira | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `active` | boolean| no | Enable/disable the JIRA service. | | `url` | string | yes | The URL to the JIRA project which is being linked to this GitLab project, e.g., `https://jira.example.com`. | | `project_key` | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | | `username` | string | no | The username of the user created to be used with GitLab/JIRA. | | `password` | string | no | The password of the user created to be used with GitLab/JIRA. | -| `jira_issue_transition_id` | string | no | 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`. | +| `jira_issue_transition_id` | integer | no | 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`. | ### Delete JIRA service @@ -491,6 +527,78 @@ Remove all previously JIRA settings from a project. DELETE /projects/:id/services/jira ``` +## Mattermost Slash Commands + +Ability to receive slash commands from a Mattermost chat instance. + +### Create/Edit Mattermost Slash Command service + +Set Mattermost Slash Command for a project. + +``` +PUT /projects/:id/services/mattermost-slash-commands +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | yes | The Mattermost token | + + +### Delete Mattermost Slash Command service + +Delete Mattermost Slash Command service for a project. + +``` +DELETE /projects/:id/services/mattermost-slash-commands +``` + +### Get Mattermost Slash Command service settings + +Get Mattermost Slash Command service settings for a project. + +``` +GET /projects/:id/services/mattermost-slash-commands +``` + +## Pipeline-Emails + +Get emails for GitLab CI pipelines. + +### Create/Edit Pipeline-Emails service + +Set Pipeline-Emails service for a project. + +``` +PUT /projects/:id/services/pipelines-email +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `recipients` | string | yes | Comma-separated list of recipient email addresses | +| `add_pusher` | boolean | no | Add pusher to recipients list | +| `notify_only_broken_builds` | boolean | no | Notify only broken pipelines | + + +### Delete Pipeline-Emails service + +Delete Pipeline-Emails service for a project. + +``` +DELETE /projects/:id/services/pipelines-email +``` + +### Get Pipeline-Emails service settings + +Get Pipeline-Emails service settings for a project. + +``` +GET /projects/:id/services/pipelines-email +``` + ## PivotalTracker Project Management Software (Source Commits Endpoint) diff --git a/doc/api/snippets.md b/doc/api/snippets.md new file mode 100644 index 00000000000..5a5dc162ffe --- /dev/null +++ b/doc/api/snippets.md @@ -0,0 +1,232 @@ +# Snippets + +> [Introduced][ce-6373] in GitLab 8.15. + +### Snippet visibility level + +Snippets in GitLab can be either private, internal, or public. +You can set it with the `visibility_level` field in the snippet. + +Constants for snippet visibility levels are: + +| Visibility | Visibility level | Description | +| ---------- | ---------------- | ----------- | +| Private | `0` | The snippet is visible only to the snippet creator | +| Internal | `10` | The snippet is visible for any logged in user | +| Public | `20` | The snippet can be accessed without any authentication | + +## List snippets + +Get a list of current user's snippets. + +``` +GET /snippets +``` + +## Single snippet + +Get a single snippet. + +``` +GET /snippets/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | Integer | yes | The ID of a snippet | + +``` bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/snippets/1 +``` + +Example response: + +``` json +{ + "id": 1, + "title": "test", + "file_name": "add.rb", + "author": { + "id": 1, + "username": "john_smith", + "email": "john@example.com", + "name": "John Smith", + "state": "active", + "created_at": "2012-05-23T08:00:58Z" + }, + "expires_at": null, + "updated_at": "2012-06-28T10:52:04Z", + "created_at": "2012-06-28T10:52:04Z", + "web_url": "http://example.com/snippets/1", +} +``` + +## Create new snippet + +Creates a new snippet. The user must have permission to create new snippets. + +``` +POST /snippets +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `title` | String | yes | The title of a snippet | +| `file_name` | String | yes | The name of a snippet file | +| `content` | String | yes | The content of a snippet | +| `visibility_level` | Integer | yes | The snippet's visibility | + + +``` bash +curl --request POST --data '{"title": "This is a snippet", "content": "Hello world", "file_name": "test.txt", "visibility_level": 10 }' --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/snippets +``` + +Example response: + +``` json +{ + "id": 1, + "title": "This is a snippet", + "file_name": "test.txt", + "author": { + "id": 1, + "username": "john_smith", + "email": "john@example.com", + "name": "John Smith", + "state": "active", + "created_at": "2012-05-23T08:00:58Z" + }, + "expires_at": null, + "updated_at": "2012-06-28T10:52:04Z", + "created_at": "2012-06-28T10:52:04Z", + "web_url": "http://example.com/snippets/1", +} +``` + +## Update snippet + +Updates an existing snippet. The user must have permission to change an existing snippet. + +``` +PUT /snippets/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | Integer | yes | The ID of a snippet | +| `title` | String | no | The title of a snippet | +| `file_name` | String | no | The name of a snippet file | +| `content` | String | no | The content of a snippet | +| `visibility_level` | Integer | no | The snippet's visibility | + + +``` bash +curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data '{"title": "foo", "content": "bar"}' https://gitlab.example.com/api/v3/snippets/1 +``` + +Example response: + +``` json +{ + "id": 1, + "title": "test", + "file_name": "add.rb", + "author": { + "id": 1, + "username": "john_smith", + "email": "john@example.com", + "name": "John Smith", + "state": "active", + "created_at": "2012-05-23T08:00:58Z" + }, + "expires_at": null, + "updated_at": "2012-06-28T10:52:04Z", + "created_at": "2012-06-28T10:52:04Z", + "web_url": "http://example.com/snippets/1", +} +``` + +## Delete snippet + +Deletes an existing snippet. + +``` +DELETE /snippets/:id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | Integer | yes | The ID of a snippet | + + +``` +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/snippets/1" +``` + +upon successful delete a `204 No content` HTTP code shall be expected, with no data, +but if the snippet is non-existent, a `404 Not Found` will be returned. + +## Explore all public snippets + +``` +GET /snippets/public +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `per_page` | Integer | no | number of snippets to return per page | +| `page` | Integer | no | the page to retrieve | + +``` bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/snippets/public?per_page=2&page=1 +``` + +Example response: + +``` json +[ + { + "author": { + "avatar_url": "http://www.gravatar.com/avatar/edaf55a9e363ea263e3b981d09e0f7f7?s=80&d=identicon", + "id": 12, + "name": "Libby Rolfson", + "state": "active", + "username": "elton_wehner", + "web_url": "http://localhost:3000/elton_wehner" + }, + "created_at": "2016-11-25T16:53:34.504Z", + "file_name": "oconnerrice.rb", + "id": 49, + "raw_url": "http://localhost:3000/snippets/49/raw", + "title": "Ratione cupiditate et laborum temporibus.", + "updated_at": "2016-11-25T16:53:34.504Z", + "web_url": "http://localhost:3000/snippets/49" + }, + { + "author": { + "avatar_url": "http://www.gravatar.com/avatar/36583b28626de71061e6e5a77972c3bd?s=80&d=identicon", + "id": 16, + "name": "Llewellyn Flatley", + "state": "active", + "username": "adaline", + "web_url": "http://localhost:3000/adaline" + }, + "created_at": "2016-11-25T16:53:34.479Z", + "file_name": "muellershields.rb", + "id": 48, + "raw_url": "http://localhost:3000/snippets/48/raw", + "title": "Minus similique nesciunt vel fugiat qui ullam sunt.", + "updated_at": "2016-11-25T16:53:34.479Z", + "web_url": "http://localhost:3000/snippets/48" + } +] +``` + diff --git a/doc/api/tags.md b/doc/api/tags.md index 14573d48fe4..7f78ffc2390 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -2,7 +2,9 @@ ## List project repository tags -Get a list of repository tags from a project, sorted by name in reverse alphabetical order. +Get a list of repository tags from a project, sorted by name in reverse +alphabetical order. This endpoint can be accessed without authentication if the +repository is publicly accessible. ``` GET /projects/:id/repository/tags @@ -40,7 +42,8 @@ Parameters: ## Get a single repository tag -Get a specific repository tag determined by its name. +Get a specific repository tag determined by its name. This endpoint can be +accessed without authentication if the repository is publicly accessible. ``` GET /projects/:id/repository/tags/:tag_name diff --git a/doc/api/users.md b/doc/api/users.md index 52a6b691610..28b6c7bd491 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -291,7 +291,9 @@ Parameters: - `id` (required) - The ID of the user -## Current user +## User + +### For normal users Gets currently authenticated user. @@ -335,6 +337,53 @@ GET /user } ``` +### For admins + +Parameters: + +- `sudo` (required) - the ID of a user + +``` +GET /user +``` + +```json +{ + "id": 1, + "username": "john_smith", + "email": "john@example.com", + "name": "John Smith", + "state": "active", + "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg", + "web_url": "http://localhost:3000/john_smith", + "created_at": "2012-05-23T08:00:58Z", + "is_admin": false, + "bio": null, + "location": null, + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": "", + "last_sign_in_at": "2012-06-01T11:41:01Z", + "confirmed_at": "2012-05-23T09:05:22Z", + "theme_id": 1, + "color_scheme_id": 2, + "projects_limit": 100, + "current_sign_in_at": "2012-06-02T06:36:55Z", + "identities": [ + {"provider": "github", "extern_uid": "2435223452345"}, + {"provider": "bitbucket", "extern_uid": "john_smith"}, + {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"} + ], + "can_create_group": true, + "can_create_project": true, + "two_factor_enabled": true, + "external": false, + "private_token": "dd34asd13as" +} +``` + ## List SSH keys Get a list of currently authenticated user's SSH keys. diff --git a/doc/ci/README.md b/doc/ci/README.md index 545cc72682d..73bd2516d46 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -11,7 +11,8 @@ - [Configure a Runner, the application that runs your builds](runners/README.md) - [Use Docker images with GitLab Runner](docker/using_docker_images.md) - [Use CI to build Docker images](docker/using_docker_build.md) -- [Use variables in your `.gitlab-ci.yml`](variables/README.md) +- [CI Variables](variables/README.md) - Learn how to use variables defined in + your `.gitlab-ci.yml` or secured ones defined in your project's settings - [Use SSH keys in your build environment](ssh_keys/README.md) - [Trigger builds through the API](triggers/README.md) - [Build artifacts](../user/project/builds/artifacts.md) @@ -21,7 +22,10 @@ - [CI services (linked docker containers)](services/README.md) - [CI/CD pipelines settings](../user/project/pipelines/settings.md) - [Review Apps](review_apps/index.md) +- [Git submodules](git_submodules.md) Using Git submodules in your CI jobs ## Breaking changes -- [New CI build permissions model](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your builds. There's a new way to access your Git submodules and LFS objects in builds. +- [New CI build permissions model](../user/project/new_ci_build_permissions_model.md) + Read about what changed in GitLab 8.12 and how that affects your builds. + There's a new way to access your Git submodules and LFS objects in builds. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 89088cf9b83..28141cced3b 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -270,12 +270,16 @@ which can be avoided if a different driver is used, for example `overlay`. ## Using the GitLab Container Registry -> **Note:** -This feature requires GitLab 8.8 and GitLab Runner 1.2. - -Once you've built a Docker image, you can push it up to the built-in [GitLab Container Registry](../../user/project/container_registry.md). For example, if you're using -docker-in-docker on your runners, this is how your `.gitlab-ci.yml` could look: +> **Notes:** +- This feature requires GitLab 8.8 and GitLab Runner 1.2. +- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need + to pass a personal access token instead of your password in order to login to + GitLab's Container Registry. +Once you've built a Docker image, you can push it up to the built-in +[GitLab Container Registry](../../user/project/container_registry.md). For example, +if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml` +could look like: ```yaml build: @@ -354,10 +358,20 @@ deploy: ``` Some things you should be aware of when using the Container Registry: -* You must log in to the container registry before running commands. Putting this in `before_script` will run it before each build job. -* Using `docker build --pull` makes sure that Docker fetches any changes to base images before building just in case your cache is stale. It takes slightly longer, but means you don’t get stuck without security patches to base images. -* Doing an explicit `docker pull` before each `docker run` makes sure to fetch the latest image that was just built. This is especially important if you are using multiple runners that cache images locally. Using the git SHA in your image tag makes this less necessary since each build will be unique and you shouldn't ever have a stale image, but it's still possible if you re-build a given commit after a dependency has changed. -* You don't want to build directly to `latest` in case there are multiple builds happening simultaneously. + +- You must log in to the container registry before running commands. Putting + this in `before_script` will run it before each build job. +- Using `docker build --pull` makes sure that Docker fetches any changes to base + images before building just in case your cache is stale. It takes slightly + longer, but means you don’t get stuck without security patches to base images. +- Doing an explicit `docker pull` before each `docker run` makes sure to fetch + the latest image that was just built. This is especially important if you are + using multiple runners that cache images locally. Using the git SHA in your + image tag makes this less necessary since each build will be unique and you + shouldn't ever have a stale image, but it's still possible if you re-build a + given commit after a dependency has changed. +- You don't want to build directly to `latest` in case there are multiple builds + happening simultaneously. [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 175e9d79904..82ffb841729 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -40,7 +40,7 @@ repository with the following content: #!/bin/bash # We need to install dependencies only for Docker -[[ ! -e /.dockerenv ]] && [[ ! -e /.dockerinit ]] && exit 0 +[[ ! -e /.dockerenv ]] && exit 0 set -xe diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md new file mode 100644 index 00000000000..1d782200cca --- /dev/null +++ b/doc/ci/git_submodules.md @@ -0,0 +1,86 @@ +# Using Git submodules with GitLab CI + +> **Notes:** +- GitLab 8.12 introduced a new [CI build permissions model][newperms] and you + are encouraged to upgrade your GitLab instance if you haven't done already. + If you are **not** using GitLab 8.12 or higher, you would need to work your way + around submodules in order to access the sources of e.g., `gitlab.com/group/project` + with the use of [SSH keys](ssh_keys/README.md). +- With GitLab 8.12 onward, your permissions are used to evaluate what a CI build + can access. More information about how this system works can be found in the + [Build permissions model](../user/permissions.md#builds-permissions). +- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance. + +## Configuring the `.gitmodules` file + +If dealing with [Git submodules][gitscm], your project will probably have a file +named `.gitmodules`. + +Let's consider the following example: + +1. Your project is located at `https://gitlab.com/secret-group/my-project`. +1. To checkout your sources you usually use an SSH address like + `git@gitlab.com:secret-group/my-project.git`. +1. Your project depends on `https://gitlab.com/group/project`, which you want + to include as a submodule. + +If you are using GitLab 8.12+ and your submodule is on the same GitLab server, +you must update your `.gitmodules` file to use **relative URLs**. +Since Git allows the usage of relative URLs for your `.gitmodules` configuration, +this easily allows you to use HTTP(S) for cloning all your CI builds and SSH +for all your local checkouts. The `.gitmodules` would look like: + +```ini +[submodule "project"] + path = project + url = ../../group/project.git +``` + +The above configuration will instruct Git to automatically deduce the URL that +should be used when cloning sources. Whether you use HTTP(S) or SSH, Git will use +that same channel and it will allow to make all your CI builds use HTTP(S) +(because GitLab CI only uses HTTP(S) for cloning your sources), and all your local +clones will continue using SSH. + +For all other submodules not located on the same GitLab server, use the full +HTTP(S) protocol URL: + +```ini +[submodule "project-x"] + path = project-x + url = https://gitserver.com/group/project-x.git +``` + +Once `.gitmodules` is correctly configured, you can move on to +[configuring your `.gitlab-ci.yml`](#using-git-submodules-in-your-ci-jobs). + +## Using Git submodules in your CI jobs + +There are a few steps you need to take in order to make submodules work +correctly with your CI builds: + +1. First, make sure you have used [relative URLs](#configuring-the-gitmodules-file) + for the submodules located in the same GitLab server. +1. Then, use `git submodule sync/update` in `before_script`: + + ```yaml + before_script: + - git submodule sync --recursive + - git submodule update --init --recursive + ``` + + `--recursive` should be used in either both or none (`sync/update`) depending on + whether you have recursive submodules. + +The rationale to set the `sync` and `update` in `before_script` is because of +the way Git submodules work. On a fresh Runner workspace, Git will set the +submodule URL including the token in `.git/config` +(or `.git/modules/<submodule>/config`) based on `.gitmodules` and the current +remote URL. On subsequent builds on the same Runner, `.git/config` is cached +and already contains a full URL for the submodule, corresponding to the previous +build, and to **a token from a previous build**. `sync` allows to force updating +the full URL. + +[gitpro]: ../user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols +[gitscm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules "Git submodules documentation" +[newperms]: ../user/project/new_ci_build_permissions_model.md diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index a66165dc973..c679ea4e298 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -33,7 +33,7 @@ built and deployed under a dynamic environment and can be previewed with an also dynamically URL. The details of the Review Apps implementation depend widely on your real -technology stack and on your deployment process. The simplest case it to +technology stack and on your deployment process. The simplest case is to deploy a simple static HTML website, but it will not be that straightforward when your app is using a database for example. To make a branch be deployed on a temporary instance and booting up this instance with all required software diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index cf7c55f75f2..efca05af7b8 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -6,7 +6,7 @@ GitLab 8.12 has a completely redesigned build permissions system. Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#build-triggers). -Triggers can be used to force a rebuild of a specific branch, tag or commit, +Triggers can be used to force a rebuild of a specific `ref` (branch or tag) with an API call. ## Add a trigger @@ -29,6 +29,10 @@ irreversible. ## Trigger a build +> **Note**: +Valid refs are only the branches and tags. If you pass a commit SHA as a ref, +it will not trigger a build. + To trigger a build you need to send a `POST` request to GitLab's API endpoint: ``` @@ -36,8 +40,8 @@ POST /projects/:id/trigger/builds ``` The required parameters are the trigger's `token` and the Git `ref` on which -the trigger will be performed. Valid refs are the branch, the tag or the commit -SHA. The `:id` of a project can be found by [querying the API](../../api/projects.md) +the trigger will be performed. Valid refs are the branch and the tag. The `:id` +of a project can be found by [querying the API](../../api/projects.md) or by visiting the **Triggers** page which provides self-explanatory examples. When a rebuild is triggered, the information is exposed in GitLab's UI under diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index a4c3a731a20..d142fe266a2 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -1,22 +1,30 @@ -## Variables +# Variables -When receiving a build from GitLab CI, the runner prepares the build environment. -It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables** +When receiving a build from GitLab CI, the [Runner] prepares the build environment. +It starts by setting a list of **predefined variables** (environment variables) +and a list of **user-defined variables**. -The variables can be overwritten. They take precedence over each other in this order: -1. Trigger variables -1. Secure variables -1. YAML-defined job-level variables -1. YAML-defined global variables -1. Predefined variables +## Priority of variables -For example, if you define: -1. `API_TOKEN=SECURE` as Secure Variable -1. `API_TOKEN=YAML` as YAML-defined variable +The variables can be overwritten and they take precedence over each other in +this order: -The `API_TOKEN` will take the Secure Variable value: `SECURE`. +1. [Trigger variables][triggers] (take precedence over all) +1. [Secret variables](#secret-variables) +1. YAML-defined [job-level variables](../yaml/README.md#job-variables) +1. YAML-defined [global variables](../yaml/README.md#variables) +1. [Predefined variables](#predefined-variables-environment-variables) (are the + lowest in the chain) -### Predefined variables (Environment Variables) +For example, if you define `API_TOKEN=secure` as a secret variable and +`API_TOKEN=yaml` in your `.gitlab-ci.yml`, the `API_TOKEN` will take the value +`secure` as the secret variables are higher in the chain. + +## Predefined variables (Environment variables) + +Some of the predefined environment variables are available only if a minimum +version of [GitLab Runner][runner] is used. Consult the table below to find the +version of Runner required. | Variable | GitLab | Runner | Description | |-------------------------|--------|--------|-------------| @@ -52,7 +60,6 @@ The `API_TOKEN` will take the Secure Variable value: `SECURE`. | **GITLAB_USER_ID** | 8.12 | all | The id of the user who started the build | | **GITLAB_USER_EMAIL** | 8.12 | all | The email of the user who started the build | -**Some of the variables are only available when using runner with at least defined version.** Example values: @@ -60,7 +67,7 @@ Example values: export CI_BUILD_ID="50" export CI_BUILD_REF="1ecfd275763eff1d6b4844ea3168962458c9f27a" export CI_BUILD_REF_NAME="master" -export CI_BUILD_REPO="https://gitab-ci-token:abcde-1234ABCD5678ef@gitlab.com/gitlab-org/gitlab-ce.git" +export CI_BUILD_REPO="https://gitab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" export CI_BUILD_TAG="1.0.0" export CI_BUILD_NAME="spec:other" export CI_BUILD_STAGE="test" @@ -73,9 +80,9 @@ export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-ce" export CI_PROJECT_NAME="gitlab-ce" export CI_PROJECT_NAMESPACE="gitlab-org" export CI_PROJECT_PATH="gitlab-org/gitlab-ce" -export CI_PROJECT_URL="https://gitlab.com/gitlab-org/gitlab-ce" -export CI_REGISTRY="registry.gitlab.com" -export CI_REGISTRY_IMAGE="registry.gitlab.com/gitlab-org/gitlab-ce" +export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-ce" +export CI_REGISTRY="registry.example.com" +export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-ce" export CI_RUNNER_ID="10" export CI_RUNNER_DESCRIPTION="my runner" export CI_RUNNER_TAGS="docker, linux" @@ -84,32 +91,66 @@ export CI_SERVER_NAME="GitLab" export CI_SERVER_REVISION="70606bf" export CI_SERVER_VERSION="8.9.0" export GITLAB_USER_ID="42" -export GITLAB_USER_EMAIL="alexzander@sporer.com" +export GITLAB_USER_EMAIL="user@example.com" ``` -### YAML-defined variables -**This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher ** +## `.gitlab-ci.yaml` defined variables + +>**Note:** +This feature requires GitLab Runner 0.5.0 or higher and GitLab CI 7.14 or higher. + +GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in the +build environment. The variables are hence saved in the repository, and they +are meant to store non-sensitive project configuration, e.g., `RAILS_ENV` or +`DATABASE_URL`. -GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment. -The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL. +For example, if you set the variable below globally (not inside a job), it will +be used in all executed commands and scripts: ```yaml variables: DATABASE_URL: "postgres://postgres@postgres/my_database" ``` -These variables can be later used in all executed commands and scripts. +The YAML-defined variables are also set to all created +[service containers](../docker/using_docker_images.md), thus allowing to fine +tune them. + +Variables can be defined at a global level, but also at a job level. To turn off +global defined variables in your job, define an empty array: + +```yaml +job_name: + variables: [] +``` + +## Secret variables -The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them. +>**Notes:** +- This feature requires GitLab Runner 0.4.0 or higher. +- Be aware that secret variables are not masked, and their values can be shown + in the build logs if explicitly asked to do so. If your project is public or + internal, you can set the pipelines private from your project's Pipelines + settings. Follow the discussion in issue [#13784][ce-13784] for masking the + secret variables. -Variables can be defined at a global level, but also at a job level. +GitLab CI allows you to define per-project **secret variables** that are set in +the build environment. The secret variables are stored out of the repository +(`.gitlab-ci.yml`) and are securely passed to GitLab Runner making them +available in the build environment. It's the recommended method to use for +storing things like passwords, secret keys and credentials. -More information about Docker integration can be found in [Using Docker Images](../docker/using_docker_images.md). +Secret variables can be added by going to your project's +**Settings ➔ Variables ➔ Add variable**. -#### Debug tracing +Once you set them, they will be available for all subsequent builds. +## Debug tracing + +> Introduced in GitLab Runner 1.7. +> > **WARNING:** Enabling debug tracing can have severe security implications. The - output **will** contain the content of all your secure variables and any other + output **will** contain the content of all your secret variables and any other secrets! The output **will** be uploaded to the GitLab server and made visible in build traces! @@ -124,55 +165,162 @@ trace, resulting in a verbose build trace listing all commands that were run, variables that were set, etc. Before enabling this, you should ensure builds are visible to -[team members only](../../../user/permissions.md#project-features). You should -also [erase](../pipelines.md#seeing-build-traces) all generated build traces +[team members only](../../user/permissions.md#project-features). You should +also [erase](../pipelines.md#seeing-build-status) all generated build traces before making them visible again. To enable debug traces, set the `CI_DEBUG_TRACE` variable to `true`: ```yaml -job1: +job_name: variables: CI_DEBUG_TRACE: "true" ``` -The [example project](https://gitlab.com/gitlab-examples/ci-debug-trace) -demonstrates a working configuration, including build trace examples. +Example truncated output with debug trace set to true: -### User-defined variables (Secure Variables) -**This feature requires GitLab Runner 0.4.0 or higher** - -GitLab CI allows you to define per-project **Secure Variables** that are set in -the build environment. -The secure variables are stored out of the repository (the `.gitlab-ci.yml`). -The variables are securely passed to GitLab Runner and are available in the -build environment. -It's desired method to use them for storing passwords, secret keys or whatever -you want. +```bash +... + +export CI_SERVER_TLS_CA_FILE="/builds/gitlab-examples/ci-debug-trace.tmp/CI_SERVER_TLS_CA_FILE" +if [[ -d "/builds/gitlab-examples/ci-debug-trace/.git" ]]; then + echo $'\''\x1b[32;1mFetching changes...\x1b[0;m'\'' + $'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace" + $'\''git'\'' "config" "fetch.recurseSubmodules" "false" + $'\''rm'\'' "-f" ".git/index.lock" + $'\''git'\'' "clean" "-ffdx" + $'\''git'\'' "reset" "--hard" + $'\''git'\'' "remote" "set-url" "origin" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git" + $'\''git'\'' "fetch" "origin" "--prune" "+refs/heads/*:refs/remotes/origin/*" "+refs/tags/*:refs/tags/*" +else + $'\''mkdir'\'' "-p" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template" + $'\''rm'\'' "-r" "-f" "/builds/gitlab-examples/ci-debug-trace" + $'\''git'\'' "config" "-f" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template/config" "fetch.recurseSubmodules" "false" + echo $'\''\x1b[32;1mCloning repository...\x1b[0;m'\'' + $'\''git'\'' "clone" "--no-checkout" "https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git" "/builds/gitlab-examples/ci-debug-trace" "--template" "/builds/gitlab-examples/ci-debug-trace.tmp/git-template" + $'\''cd'\'' "/builds/gitlab-examples/ci-debug-trace" +fi +echo $'\''\x1b[32;1mChecking out dd648b2e as master...\x1b[0;m'\'' +$'\''git'\'' "checkout" "-f" "-q" "dd648b2e48ce6518303b0bb580b2ee32fadaf045" +' ++++ hostname +++ echo 'Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb...' +Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-machine-1480971377-317a7d0f-digital-ocean-4gb... +++ export CI=true +++ CI=true +++ export CI_DEBUG_TRACE=false +++ CI_DEBUG_TRACE=false +++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_BUILD_REF_NAME=master +++ CI_BUILD_REF_NAME=master +++ export CI_BUILD_ID=7046507 +++ CI_BUILD_ID=7046507 +++ export CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_PROJECT_ID=1796893 +++ CI_PROJECT_ID=1796893 +++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace +++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace +++ export CI_SERVER=yes +++ CI_SERVER=yes +++ export 'CI_SERVER_NAME=GitLab CI' +++ CI_SERVER_NAME='GitLab CI' +++ export CI_SERVER_VERSION= +++ CI_SERVER_VERSION= +++ export CI_SERVER_REVISION= +++ CI_SERVER_REVISION= +++ export GITLAB_CI=true +++ GITLAB_CI=true +++ export CI=true +++ CI=true +++ export GITLAB_CI=true +++ GITLAB_CI=true +++ export CI_BUILD_ID=7046507 +++ CI_BUILD_ID=7046507 +++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_BUILD_REF_NAME=master +++ CI_BUILD_REF_NAME=master +++ export CI_BUILD_NAME=debug_trace +++ CI_BUILD_NAME=debug_trace +++ export CI_BUILD_STAGE=test +++ CI_BUILD_STAGE=test +++ export CI_SERVER_NAME=GitLab +++ CI_SERVER_NAME=GitLab +++ export CI_SERVER_VERSION=8.14.3-ee +++ CI_SERVER_VERSION=8.14.3-ee +++ export CI_SERVER_REVISION=82823 +++ CI_SERVER_REVISION=82823 +++ export CI_PROJECT_ID=17893 +++ CI_PROJECT_ID=17893 +++ export CI_PROJECT_NAME=ci-debug-trace +++ CI_PROJECT_NAME=ci-debug-trace +++ export CI_PROJECT_PATH=gitlab-examples/ci-debug-trace +++ CI_PROJECT_PATH=gitlab-examples/ci-debug-trace +++ export CI_PROJECT_NAMESPACE=gitlab-examples +++ CI_PROJECT_NAMESPACE=gitlab-examples +++ export CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace +++ CI_PROJECT_URL=https://example.com/gitlab-examples/ci-debug-trace +++ export CI_PIPELINE_ID=52666 +++ CI_PIPELINE_ID=52666 +++ export CI_RUNNER_ID=1337 +++ CI_RUNNER_ID=1337 +++ export CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com +++ CI_RUNNER_DESCRIPTION=shared-runners-manager-1.example.com +++ export 'CI_RUNNER_TAGS=shared, docker, linux, ruby, mysql, postgres, mongo, git-annex' +++ CI_RUNNER_TAGS='shared, docker, linux, ruby, mysql, postgres, mongo, git-annex' +++ export CI_REGISTRY=registry.example.com +++ CI_REGISTRY=registry.example.com +++ export CI_DEBUG_TRACE=true +++ CI_DEBUG_TRACE=true +++ export GITLAB_USER_ID=42 +++ GITLAB_USER_ID=42 +++ export GITLAB_USER_EMAIL=user@example.com +++ GITLAB_USER_EMAIL=axilleas@axilleas.me +++ export VERY_SECURE_VARIABLE=imaverysecurevariable +++ VERY_SECURE_VARIABLE=imaverysecurevariable +++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp +++ echo -n '-----BEGIN CERTIFICATE----- +MIIFQzCCBCugAwIBAgIRAL/ElDjuf15xwja1ZnCocWAwDQYJKoZIhvcNAQELBQAw' + +... +``` -**The value of the variable can be shown in build log if explicitly asked to do so.** -If your project is public or internal you can make the builds private. +## Using the CI variables in your job scripts -Secure Variables can added by going to `Project > Variables > Add Variable`. +All variables are set as environment variables in the build environment, and +they are accessible with normal methods that are used to access such variables. +In most cases `bash` or `sh` is used to execute the build script. -They will be available for all subsequent builds. +To access the variables (predefined and user-defined) in a `bash`/`sh` environment, +prefix the variable name with the dollar sign (`$`): -### Use variables -The variables are set as environment variables in build environment and are accessible with normal methods that are used to access such variables. -In most cases the **bash** is used to execute build script. -To access variables (predefined and user-defined) in bash environment, prefix the variable name with `$`: ``` job_name: script: - echo $CI_BUILD_ID ``` -You can also list all environment variables with `export` command, -but be aware that this will also expose value of all **Secure Variables** in build log: +You can also list all environment variables with the `export` command, +but be aware that this will also expose the values of all the secret variables +you set, in the build log: + ``` job_name: script: - export ``` +[ce-13784]: https://gitlab.com/gitlab-org/gitlab-ce/issues/13784 +[runner]: https://docs.gitlab.com/runner/ [triggered]: ../triggers/README.md +[triggers]: ../triggers/README.md#pass-build-variables-to-a-trigger diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 338c9a27789..5f88974d360 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -406,14 +406,20 @@ except master. ### job variables It is possible to define build variables using a `variables` keyword on a job -level. It works basically the same way as its global-level equivalent but -allows you to define job-specific build variables. +level. It works basically the same way as its [global-level equivalent](#variables) +but allows you to define job-specific build variables. When the `variables` keyword is used on a job level, it overrides global YAML -build variables and predefined variables. +build variables and predefined variables. To turn off global defined variables +in your job, define an empty array: -Build variables priority is defined in -[variables documentation](../variables/README.md). +```yaml +job_name: + variables: [] +``` + +Build variables priority is defined in the +[variables documentation][variables]. ### tags diff --git a/doc/development/code_review.md b/doc/development/code_review.md index c5c23b5c0b8..1ef34c79971 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -70,10 +70,36 @@ experience, refactors the existing code). Then: - After a round of line notes, it can be helpful to post a summary note such as "LGTM :thumbsup:", or "Just a couple things to address." - Avoid accepting a merge request before the build succeeds. Of course, "Merge - When Build Succeeds" (MWBS) is fine. -- If you set the MR to "Merge When Build Succeeds", you should take over + When Pipeline Succeeds" (MWPS) is fine. +- If you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. +## The right balance + +One of the most difficult things during code review is finding the right +balance in how deep the reviewer can interfere with the code created by a +reviewee. + +- Learning how to find the right balance takes time; that is why we have + minibosses that become merge request endbosses after some time spent on + reviewing merge requests. +- Finding bugs and improving code style is important, but thinking about good + design is important as well. Building abstractions and good design is what + makes it possible to hide complexity and makes future changes easier. +- Asking the reviewee to change the design sometimes means the complete rewrite + of the contributed code. It's usually a good idea to ask another merge + request endboss before doing it, but have the courage to do it when you + believe it is important. +- There is a difference in doing things right and doing things right now. + Ideally, we should do the former, but in the real world we need the latter as + well. A good example is a security fix which should be released as soon as + possible. Asking the reviewee to do the major refactoring in the merge + request that is an urgent fix should be avoided. +- Doing things well today is usually better than doing something perfectly + tomorrow. Shipping a kludge today is usually worse than doing something well + tomorrow. When you are not able to find the right balance, ask other people + about their opinion. + ## Credits Largely based on the [thoughtbot code review guide]. diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 7bfc9cb361f..0f78e8238af 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -141,51 +141,3 @@ in an initializer._ ### Further reading - Stack Overflow: [Why you should not write inline JavaScript](http://programmers.stackexchange.com/questions/86589/why-should-i-avoid-inline-scripting) - -## ID-based CSS selectors need to be a bit more specific - -Normally, because HTML `id` attributes need to be unique to the page, it's -perfectly fine to write some JavaScript like the following: - -```javascript -$('#js-my-selector').hide(); -``` - -However, there's a feature of GitLab's Markdown processing that [automatically -adds anchors to header elements][ToC Processing], with the `id` attribute being -automatically generated based on the content of the header. - -Unfortunately, this feature makes it possible for user-generated content to -create a header element with the same `id` attribute we're using in our -selector, potentially breaking the JavaScript behavior. A user could break the -above example with the following Markdown: - -```markdown -## JS My Selector -``` - -Which gets converted to the following HTML: - -```html -<h2> - <a id="js-my-selector" class="anchor" href="#js-my-selector" aria-hidden="true"></a> - JS My Selector -</h2> -``` - -[ToC Processing]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/lib/banzai/filter/table_of_contents_filter.rb#L31-37 - -### Solution - -The current recommended fix for this is to make our selectors slightly more -specific: - -```javascript -$('div#js-my-selector').hide(); -``` - -### Further reading - -- Issue: [Merge request ToC anchor conflicts with tabs](https://gitlab.com/gitlab-org/gitlab-ce/issues/3908) -- Merge Request: [Make tab target selectors less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2023) -- Merge Request: [Make cross-project reference's clipboard target less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2024) diff --git a/doc/development/ux_guide/animation.md b/doc/development/ux_guide/animation.md new file mode 100644 index 00000000000..daeb15460c2 --- /dev/null +++ b/doc/development/ux_guide/animation.md @@ -0,0 +1,42 @@ +# Animation + +Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. + +## Timings + +The longer distance an object travel, the timing should be longer for the animation. However, when in doubt, we should avoid large, full screen animations. + +Subtle animations, or objects leaving the screen should take **100-200 milliseconds**. Objects entering the screen, or motion we want to use to direct user attention can take between **200-400 milliseconds**. We should avoid animations of longer than 400 milliseconds as they will make the experience appear sluggish. If a specific animation feels like it will need more than 400 milliseconds, revisit the animation to see if there is a simpler, easier, shorter animation to implement. + +## Easing + +Easing specifies the rate of change of a parameter over time (see [easings.net](http://easings.net/)). Adding an easing curve will make the motion feel more natural. Being consistent with the easing curves will make the whole experience feel more cohesive and connected. + +* When an object is entering the screen, or transforming the scale, position, or shape, use the **easeOutQuint** curve (`cubic-bezier(0.23, 1, 0.32, 1)`) +* When an object is leaving the screen, or transforming the opacity or color, no easing curve is needed. It shouldn't _slow down_ as it is exiting the screen, as that draws attention on the leaving object, where we don't want it. Adding easing to opacity and color transitions will make the motion appear less smooth. Therefore, for these cases, motion should just be **linear**. + +## Types of animations + +### Hover + +Interactive elements (links, buttons, etc.) should have a hover state. A subtle animation for this transition adds a polished feel. We should target a `200ms linear` transition for a color hover effect. + +View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here. + + + +### Dropdowns + +The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with a opacity animation `200ms linear` on the second half of the motion achieves this affect. + +View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here. + + + +### Quick update + +When information is updating in place, a quick, subtle animation is needed. The previous content should cut out, and the new content should have a quick, `200ms linear` fade in. + + + +> TODO: Add guidance for other kinds of animation
\ No newline at end of file diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md index 62ac56a6bce..76b739386a5 100644 --- a/doc/development/ux_guide/basics.md +++ b/doc/development/ux_guide/basics.md @@ -5,8 +5,6 @@ * [Typography](#typography) * [Icons](#icons) * [Color](#color) -* [Motion](#motion) -* [Voice and tone](#voice-and-tone) --- @@ -35,26 +33,15 @@ This is the typeface used for code blocks. GitLab uses the OS default font. ## Icons GitLab uses Font Awesome icons throughout our interface. - -The trash icon is used for destructive actions that deletes information. - - -The pencil icon is used for editing content such as comments. - - -The bell icon is for notifications, such as Todos. - - -The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. - - -The standard RSS icon is used for linking to RSS/atom feeds. - - -An 'x' is used for closing UI elements such as dropdowns. - - -A plus is used when creating new objects, such as issues, projects, etc. +| | | +| :-----------: | :---- | +|  | The trash icon is used for destructive actions that deletes information. | +|  | The pencil icon is used for editing content such as comments.| +|  | The bell icon is for notifications, such as Todos. | +|  | The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. | +|  | The standard RSS icon is used for linking to RSS/atom feeds. | +|  | An 'x' is used for closing UI elements such as dropdowns. | +|  | A plus is used when creating new objects, such as issues, projects, etc. | > TODO: update this section, add more general guidance to icon usage and personality, etc. @@ -62,33 +49,13 @@ A plus is used when creating new objects, such as issues, projects, etc. ## Color - -Blue is used to highlight primary active elements (such as current tab), as well as other organization and managing commands. - - -Green is for actions that create new objects. - - -Orange is used for warnings - - -Red is reserved for delete and other destructive commands - - -Grey, and white (depending on context) is used for netral, secondary elements +| | | +| :------: | :------- | +|  | Blue is used to highlight primary active elements (such as the current tab), as well as other organizational and managing commands.| +|  | Green is for actions that create new objects. | +|  | Orange is used for warnings | +|  | Red is reserved for delete and other destructive commands | +|  | Grey is used for neutral secondary elements. Depending on context, white is sometimes used instead. | > TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. ---- - -## Motion - -Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment. - -> TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. - ---- - -## Voice and tone - -The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md index 8e51edd23ef..28383ad7dfc 100644 --- a/doc/development/ux_guide/components.md +++ b/doc/development/ux_guide/components.md @@ -75,10 +75,29 @@ Text should be in sentence case, where only the first word is capitalized. "Crea > TODO: Rationalize this. Ensure that we still believe this. ### Colors -Follow the color guidance on the [basics](basics.md#color) page. The default color treatment is the white/grey button. +The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button. + +### Secondary states + +Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed. + +| Values | Info | Success | Warning | Danger | +| :------ | :------: | :------: | :------: | :------: | +| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  |  | +| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  |  | +| Background: `$color-dark` <br> Border: `$border-color-dark` |  |  |  |  | + +Since secondary buttons only have a border on their resting state, their hover and focus states add a background color, which gets darkened on active. + +| Values | Success Secondary | Close | Spam | +| :------ | :------: | :------: | :------: | +| Font: `$border-color-light` <br> Border: `$border-color-light` |  |  |  | +| Background: `$color-light` <br> Border: `$border-color-light` |  |  |  | +| Background: `$color-normal` <br> Border: `$border-color-normal` |  |  |  | --- + ## Dropdowns Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.) diff --git a/doc/development/ux_guide/copy.md b/doc/development/ux_guide/copy.md index b557fb47120..8896d450f14 100644 --- a/doc/development/ux_guide/copy.md +++ b/doc/development/ux_guide/copy.md @@ -1,6 +1,8 @@ # Copy -The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab. +The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding. + +The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab. >**Note:** We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align. diff --git a/doc/development/ux_guide/img/animation-dropdown.gif b/doc/development/ux_guide/img/animation-dropdown.gif Binary files differnew file mode 100644 index 00000000000..c9b31d26165 --- /dev/null +++ b/doc/development/ux_guide/img/animation-dropdown.gif diff --git a/doc/development/ux_guide/img/animation-hover.gif b/doc/development/ux_guide/img/animation-hover.gif Binary files differnew file mode 100644 index 00000000000..37ad9c76828 --- /dev/null +++ b/doc/development/ux_guide/img/animation-hover.gif diff --git a/doc/development/ux_guide/img/animation-quickupdate.gif b/doc/development/ux_guide/img/animation-quickupdate.gif Binary files differnew file mode 100644 index 00000000000..8db70bc3d24 --- /dev/null +++ b/doc/development/ux_guide/img/animation-quickupdate.gif diff --git a/doc/development/ux_guide/img/button-close--active.png b/doc/development/ux_guide/img/button-close--active.png Binary files differnew file mode 100644 index 00000000000..824bfc8f31b --- /dev/null +++ b/doc/development/ux_guide/img/button-close--active.png diff --git a/doc/development/ux_guide/img/button-close--hover.png b/doc/development/ux_guide/img/button-close--hover.png Binary files differnew file mode 100644 index 00000000000..0291e121894 --- /dev/null +++ b/doc/development/ux_guide/img/button-close--hover.png diff --git a/doc/development/ux_guide/img/button-close--resting.png b/doc/development/ux_guide/img/button-close--resting.png Binary files differnew file mode 100644 index 00000000000..986d7174ce7 --- /dev/null +++ b/doc/development/ux_guide/img/button-close--resting.png diff --git a/doc/development/ux_guide/img/button-danger--active.png b/doc/development/ux_guide/img/button-danger--active.png Binary files differnew file mode 100644 index 00000000000..d3c64424b26 --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--active.png diff --git a/doc/development/ux_guide/img/button-danger--hover.png b/doc/development/ux_guide/img/button-danger--hover.png Binary files differnew file mode 100644 index 00000000000..8506e093306 --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--hover.png diff --git a/doc/development/ux_guide/img/button-danger--resting.png b/doc/development/ux_guide/img/button-danger--resting.png Binary files differnew file mode 100644 index 00000000000..69ad6bb796b --- /dev/null +++ b/doc/development/ux_guide/img/button-danger--resting.png diff --git a/doc/development/ux_guide/img/button-info--active.png b/doc/development/ux_guide/img/button-info--active.png Binary files differnew file mode 100644 index 00000000000..23be20b225c --- /dev/null +++ b/doc/development/ux_guide/img/button-info--active.png diff --git a/doc/development/ux_guide/img/button-info--hover.png b/doc/development/ux_guide/img/button-info--hover.png Binary files differnew file mode 100644 index 00000000000..4cb4e38558c --- /dev/null +++ b/doc/development/ux_guide/img/button-info--hover.png diff --git a/doc/development/ux_guide/img/button-info--resting.png b/doc/development/ux_guide/img/button-info--resting.png Binary files differnew file mode 100644 index 00000000000..5883340aa83 --- /dev/null +++ b/doc/development/ux_guide/img/button-info--resting.png diff --git a/doc/development/ux_guide/img/button-spam--active.png b/doc/development/ux_guide/img/button-spam--active.png Binary files differnew file mode 100644 index 00000000000..55b44898684 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--active.png diff --git a/doc/development/ux_guide/img/button-spam--hover.png b/doc/development/ux_guide/img/button-spam--hover.png Binary files differnew file mode 100644 index 00000000000..3dc8ed34c54 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--hover.png diff --git a/doc/development/ux_guide/img/button-spam--resting.png b/doc/development/ux_guide/img/button-spam--resting.png Binary files differnew file mode 100644 index 00000000000..b6bf10a5b64 --- /dev/null +++ b/doc/development/ux_guide/img/button-spam--resting.png diff --git a/doc/development/ux_guide/img/button-success--active.png b/doc/development/ux_guide/img/button-success--active.png Binary files differnew file mode 100644 index 00000000000..895a52831cb --- /dev/null +++ b/doc/development/ux_guide/img/button-success--active.png diff --git a/doc/development/ux_guide/img/button-success--hover.png b/doc/development/ux_guide/img/button-success--hover.png Binary files differnew file mode 100644 index 00000000000..e4c74bd9778 --- /dev/null +++ b/doc/development/ux_guide/img/button-success--hover.png diff --git a/doc/development/ux_guide/img/button-success--resting.png b/doc/development/ux_guide/img/button-success--resting.png Binary files differnew file mode 100644 index 00000000000..2fa971b5347 --- /dev/null +++ b/doc/development/ux_guide/img/button-success--resting.png diff --git a/doc/development/ux_guide/img/button-success-secondary--active.png b/doc/development/ux_guide/img/button-success-secondary--active.png Binary files differnew file mode 100644 index 00000000000..e7383b36946 --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--active.png diff --git a/doc/development/ux_guide/img/button-success-secondary--hover.png b/doc/development/ux_guide/img/button-success-secondary--hover.png Binary files differnew file mode 100644 index 00000000000..4af2a68cf1b --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--hover.png diff --git a/doc/development/ux_guide/img/button-success-secondary--resting.png b/doc/development/ux_guide/img/button-success-secondary--resting.png Binary files differnew file mode 100644 index 00000000000..a5a4ec512c8 --- /dev/null +++ b/doc/development/ux_guide/img/button-success-secondary--resting.png diff --git a/doc/development/ux_guide/img/button-warning--active.png b/doc/development/ux_guide/img/button-warning--active.png Binary files differnew file mode 100644 index 00000000000..5877d46c94d --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--active.png diff --git a/doc/development/ux_guide/img/button-warning--hover.png b/doc/development/ux_guide/img/button-warning--hover.png Binary files differnew file mode 100644 index 00000000000..308e1adc8a3 --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--hover.png diff --git a/doc/development/ux_guide/img/button-warning--resting.png b/doc/development/ux_guide/img/button-warning--resting.png Binary files differnew file mode 100644 index 00000000000..28e5e601520 --- /dev/null +++ b/doc/development/ux_guide/img/button-warning--resting.png diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png Binary files differindex 2ca360173eb..844e926f1f5 100644 --- a/doc/development/ux_guide/img/color-blue.png +++ b/doc/development/ux_guide/img/color-blue.png diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png Binary files differindex 489db8f4343..5c4c23c7067 100644 --- a/doc/development/ux_guide/img/color-green.png +++ b/doc/development/ux_guide/img/color-green.png diff --git a/doc/development/ux_guide/img/color-grey.png b/doc/development/ux_guide/img/color-grey.png Binary files differindex 58c474d5ce9..5247649a0ce 100644 --- a/doc/development/ux_guide/img/color-grey.png +++ b/doc/development/ux_guide/img/color-grey.png diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png Binary files differindex 4c4b772d438..1103c715225 100644 --- a/doc/development/ux_guide/img/color-orange.png +++ b/doc/development/ux_guide/img/color-orange.png diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png Binary files differindex 3440ad48f05..77ecbbc0a20 100644 --- a/doc/development/ux_guide/img/color-red.png +++ b/doc/development/ux_guide/img/color-red.png diff --git a/doc/development/ux_guide/img/icon-add.png b/doc/development/ux_guide/img/icon-add.png Binary files differindex 0d4c1a7692a..bcad5e84591 100644 --- a/doc/development/ux_guide/img/icon-add.png +++ b/doc/development/ux_guide/img/icon-add.png diff --git a/doc/development/ux_guide/img/icon-close.png b/doc/development/ux_guide/img/icon-close.png Binary files differindex 88d2b3b0c6d..dfe1495f5fa 100644 --- a/doc/development/ux_guide/img/icon-close.png +++ b/doc/development/ux_guide/img/icon-close.png diff --git a/doc/development/ux_guide/img/icon-edit.png b/doc/development/ux_guide/img/icon-edit.png Binary files differindex f73be7a10fb..50f6f841868 100644 --- a/doc/development/ux_guide/img/icon-edit.png +++ b/doc/development/ux_guide/img/icon-edit.png diff --git a/doc/development/ux_guide/img/icon-notification.png b/doc/development/ux_guide/img/icon-notification.png Binary files differindex 4758632edd7..6ddfaa44f66 100644 --- a/doc/development/ux_guide/img/icon-notification.png +++ b/doc/development/ux_guide/img/icon-notification.png diff --git a/doc/development/ux_guide/img/icon-rss.png b/doc/development/ux_guide/img/icon-rss.png Binary files differindex c7ac9fb1349..b766488b32d 100644 --- a/doc/development/ux_guide/img/icon-rss.png +++ b/doc/development/ux_guide/img/icon-rss.png diff --git a/doc/development/ux_guide/img/icon-subscribe.png b/doc/development/ux_guide/img/icon-subscribe.png Binary files differindex 5cb277bfd5d..650168296c6 100644 --- a/doc/development/ux_guide/img/icon-subscribe.png +++ b/doc/development/ux_guide/img/icon-subscribe.png diff --git a/doc/development/ux_guide/img/icon-trash.png b/doc/development/ux_guide/img/icon-trash.png Binary files differindex 357289a6fff..b02178ca992 100644 --- a/doc/development/ux_guide/img/icon-trash.png +++ b/doc/development/ux_guide/img/icon-trash.png diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md index 8aed11ebac3..8a849f239dc 100644 --- a/doc/development/ux_guide/index.md +++ b/doc/development/ux_guide/index.md @@ -12,7 +12,17 @@ These guiding principles set a solid foundation for our design system, and shoul --- ### [Basics](basics.md) -The basic ingredients of our experience establish our personality and feel. This section includes details about typography, color, and motion. +The basic ingredients of our experience establish our personality and feel. This section includes details about typography, iconography, and color. + +--- + +### [Animation](animation.md) +Guidance on the timing, curving and motion for GitLab. + +--- + +### [Copy](copy.md) +Conventions on text and messaging within labels, buttons, and other components. --- @@ -26,11 +36,6 @@ The GitLab experience is broken apart into several surfaces. Each of these surfa --- -### [Copy](copy.md) -Conventions on text and messaging within labels, buttons, and other components. - ---- - ### [Features](features.md) The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states. diff --git a/doc/install/installation.md b/doc/install/installation.md index ee02d6024d9..2740b2982b9 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -76,7 +76,7 @@ Make sure you have the right version of Git installed # Install Git sudo apt-get install -y git-core - # Make sure Git is version 2.7.4 or higher + # Make sure Git is version 2.8.4 or higher git --version Is the system packaged Git too old? Remove it and compile from source. @@ -89,9 +89,9 @@ Is the system packaged Git too old? Remove it and compile from source. # Download and compile from source cd /tmp - curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.7.4.tar.gz - echo '7104c4f5d948a75b499a954524cb281fe30c6649d8abe20982936f75ec1f275b git-2.7.4.tar.gz' | shasum -a256 -c - && tar -xzf git-2.7.4.tar.gz - cd git-2.7.4/ + curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.8.4.tar.gz + echo '626e319f8a24fc0866167ea5f6bf3e2f38f69d6cb2e59e150f13709ca3ebf301 git-2.8.4.tar.gz' | shasum -a256 -c - && tar -xzf git-2.8.4.tar.gz + cd git-2.8.4/ ./configure make prefix=/usr/local all @@ -123,9 +123,9 @@ Remove the old Ruby 1.8 if present: Download Ruby and compile it: mkdir /tmp/ruby && cd /tmp/ruby - curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz - echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum -c - && tar xzf ruby-2.3.1.tar.gz - cd ruby-2.3.1 + curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz + echo 'a8db9ce7f9110320f33b8325200e3ecfbd2b534b ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz + cd ruby-2.3.3 ./configure --disable-install-rdoc make sudo make install @@ -175,7 +175,7 @@ We recommend using a PostgreSQL database. For MySQL check the ```bash sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" ``` - + 1. Create the `pg_trgm` extension (required for GitLab 8.6+): ```bash @@ -271,9 +271,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-14-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-15-stable gitlab -**Note:** You can change `8-14-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `8-15-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -396,15 +396,13 @@ GitLab Shell is an SSH access and repository management software developed speci ### Install gitlab-workhorse -GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. +GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The +following command-line will install GitLab-Workhorse in `/home/git/gitlab-workhorse` +which is the recommended location. - cd /home/git - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-workhorse.git - cd gitlab-workhorse - sudo -u git -H git checkout v1.0.1 - sudo -u git -H make + cd /home/git/gitlab + + sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production ### Initialize Database and Activate Advanced Features diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index eb9bbb67e7d..696c1011eeb 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -2,7 +2,7 @@ This documentation is for enabling shibboleth with omnibus-gitlab package. -In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled NIGNX provided in the omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. +In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however this is difficult to configure using the bundled Nginx provided in the omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. To enable the Shibboleth OmniAuth provider you must: diff --git a/doc/intro/README.md b/doc/intro/README.md index 1790b2b761f..1df6a52ce8a 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -23,7 +23,7 @@ Create merge requests and review code. - [Fork a project and contribute to it](../workflow/forking_workflow.md) - [Create a new merge request](../gitlab-basics/add-merge-request.md) - [Automatically close issues from merge requests](../user/project/issues/automatic_issue_closing.md) -- [Automatically merge when your builds succeed](../user/project/merge_requests/merge_when_build_succeeds.md) +- [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) - [Revert any commit](../user/project/merge_requests/revert_changes.md) - [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) diff --git a/doc/project_services/img/mattermost_console_integrations.png b/doc/project_services/img/mattermost_console_integrations.png Binary files differindex b3b8c20d7bf..92a30da5be0 100644 --- a/doc/project_services/img/mattermost_console_integrations.png +++ b/doc/project_services/img/mattermost_console_integrations.png diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 366e4b2d306..390066c9989 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -197,6 +197,7 @@ incorrectly the JIRA-GitLab integration. Make sure that the user you set up for GitLab to communicate with JIRA has the correct access permission to post comments on a ticket and to also transition the ticket, if you'd like GitLab to also take care of closing them. +JIRA issue references and update comments will not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a ticket diff --git a/doc/project_services/mattermost_slash_commands.md b/doc/project_services/mattermost_slash_commands.md index 1507dfa3abd..6fcbf6f1642 100644 --- a/doc/project_services/mattermost_slash_commands.md +++ b/doc/project_services/mattermost_slash_commands.md @@ -22,6 +22,9 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost +This step is only required when using a source install, omnibus installs will be +preconfigured with the right settings. + The first thing to do in Mattermost is to enable custom slash commands from the administrator console. @@ -32,8 +35,9 @@ the administrator console. --- -1. Click **Custom integrations** and set **Enable Custom Slash Commands** to - true. +1. Click **Custom integrations** and set **Enable Custom Slash Commands**, + **Enable custom integrations to override usernames**, and **Override + custom integrations to override profile picture icons** to true  diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 17485b11c09..f42bb6a81a2 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -353,7 +353,7 @@ restore: ```shell # This command will overwrite the contents of your GitLab database! -sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186 +sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186_2014_02_27 ``` Restart and check GitLab: diff --git a/doc/ssh/README.md b/doc/ssh/README.md index d6a0979f6ec..9803937fcf9 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -1,75 +1,141 @@ # SSH -## SSH keys +Git is a distributed version control system, which means you can work locally +but you can also share or "push" your changes to other servers. +Before you can push your changes to a GitLab server +you need a secure communication channel for sharing information. +GitLab uses Public-key or asymmetric cryptography +which encrypts a communication channel by locking it with your "private key" +and allows trusted parties to unlock it with your "public key". +If someone does not have your public key they cannot access the unencrypted message. -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: +## Locating an existing SSH key pair + +Before generating a new SSH key check if your system already has one +at the default location by opening a shell, or Command Prompt on Windows, +and running the following command: + +**Windows Command Prompt:** -**Windows Command Line:** ```bash type %userprofile%\.ssh\id_rsa.pub ``` -**GNU/Linux/Mac/PowerShell:** + +**GNU/Linux / macOS / PowerShell:** + ```bash cat ~/.ssh/id_rsa.pub ``` -If you see a long string starting with `ssh-rsa`, you can skip the `ssh-keygen` step. +If you see a string starting with `ssh-rsa` you already have an SSH key pair +and you can skip the next step **Generating a new SSH key pair** +and continue onto **Copying your public SSH key to the clipboard**. +If you don't see the string or would like to generate a SSH key pair with a +custom name continue onto the next step. -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. +## Generating a new SSH key pair -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. +1. To generate a new SSH key, use the following command: -If you want to change the password of your key later, you can use the following -command: `ssh-keygen -p <keyname>` + **GNU/Linux / macOS:** -Use the command below to show your public key: + ```bash + ssh-keygen -t rsa -C "GitLab" -b 4096 + ``` -**Windows Command Line:** -```bash -type %userprofile%\.ssh\id_rsa.pub -``` -**GNU/Linux/Mac/PowerShell:** -```bash -cat ~/.ssh/id_rsa.pub -``` + **Windows:** -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. + On Windows you will need to download + [PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) + and follow this [documentation article][winputty] to generate a SSH key pair. -To copy your public key to the clipboard, use the code below. Depending on your -OS you'll need to use a different command: +1. Next, you will be prompted to input a file path to save your key pair to. -**Windows Command Line:** -```bash -type %userprofile%\.ssh\id_rsa.pub | clip -``` + If you don't already have an SSH key pair use the suggested path by pressing + enter. Using the suggested path will allow your SSH client + to automatically use the key pair with no additional configuration. -**Windows PowerShell:** -```bash -cat ~/.ssh/id_rsa.pub | clip -``` + If you already have a key pair with the suggested file path, you will need + to input a new file path and declare what host this key pair will be used + for in your `.ssh/config` file, see **Working with non-default SSH key pair paths** + for more information. + +1. Once you have input a file path you will be prompted to input a password to + secure your SSH key pair. It is a best practice to use a password for an SSH + key pair, but it is not required and you can skip creating a password by + pressing enter. + + >**Note:** + If you want to change the password of your key, you can use `ssh-keygen -p <keyname>`. + +1. The next step is to copy the public key as we will need it afterwards. + + To copy your public key to the clipboard, use the appropriate code for your + operating system below: + + **macOS:** + + ```bash + pbcopy < ~/.ssh/id_rsa.pub + ``` + + **GNU/Linux (requires the xclip package):** + + ```bash + xclip -sel clip < ~/.ssh/id_rsa.pub + ``` + + **Windows Command Line:** + + ```bash + type %userprofile%\.ssh\id_rsa.pub | clip + ``` + + **Windows PowerShell:** + + ```bash + cat ~/.ssh/id_rsa.pub | clip + ``` + +1. The final step is to add your public SSH key to GitLab. + + Navigate to the 'SSH Keys' tab in you 'Profile Settings'. + Paste your key in the 'Key' section and give it a relevant 'Title'. + Use an identifiable title like 'Work Laptop - Windows 7' or + 'Home MacBook Pro 15'. + + If you manually copied your public SSH key make sure you copied the entire + key starting with `ssh-rsa` and ending with your email. + +## Working with non-default SSH key pair paths + +If you used a non-default file path for your GitLab SSH key pair, +you must configure your SSH client to find your GitLab SSH private key +for connections to your GitLab server (perhaps gitlab.com). + +For OpenSSH clients this is configured in the `~/.ssh/config` file. +Below are two example host configurations using their own key: -**Mac:** -```bash -pbcopy < ~/.ssh/id_rsa.pub ``` +# GitLab.com server +Host gitlab.com +RSAAuthentication yes +IdentityFile ~/.ssh/config/private-key-filename-01 -**GNU/Linux (requires xclip):** -```bash -xclip -sel clip < ~/.ssh/id_rsa.pub +# Private GitLab server +Host gitlab.company.com +RSAAuthentication yes +IdentityFile ~/.ssh/config/private-key-filename ``` +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. + ## Deploy keys Deploy keys allow read-only access to multiple projects with a single SSH @@ -89,10 +155,10 @@ 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. +a group. -Deploy keys can be shared between projects, you just need to add them to each project. +Deploy keys can be shared between projects, you just need to add them to each +project. ## Applications @@ -100,33 +166,4 @@ Deploy keys can be shared between projects, you just need to add them to each pr 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 +[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen diff --git a/doc/university/README.md b/doc/university/README.md index 8917636c59b..12727e9d56f 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -5,7 +5,7 @@ GitLab University is the best place to learn about **Version Control with Git an It doesn't replace, but accompanies our great [Documentation](https://docs.gitlab.com) and [Blog Articles](https://about.gitlab.com/blog/). -Would you like to contribute to GitLab University? Then please take a look at our contribution [process](/process) for more information. +Would you like to contribute to GitLab University? Then please take a look at our contribution [process](process) for more information. ## Gitlab University Curriculum @@ -97,7 +97,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [Markdown in GitLab](../user/markdown.md) 1. [Issues and Merge Requests - Video](https://www.youtube.com/watch?v=raXvuwet78M) -1. [Due Dates and Milestones fro GitLab Issues](https://about.gitlab.com/2016/08/05/feature-highlight-set-dates-for-issues/) +1. [Due Dates and Milestones for GitLab Issues](https://about.gitlab.com/2016/08/05/feature-highlight-set-dates-for-issues/) 1. [How to Use GitLab Labels](https://about.gitlab.com/2016/08/17/using-gitlab-labels/) 1. [Applying GitLab Labels Automatically](https://about.gitlab.com/2016/08/19/applying-gitlab-labels-automatically/) 1. [GitLab Issue Board - Product Page](https://about.gitlab.com/solutions/issueboard/) @@ -147,7 +147,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [Xebia Labs: Dev Ops Terminology](https://xebialabs.com/glossary/) 1. [Xebia Labs: Periodic Table of DevOps Tools](https://xebialabs.com/periodic-table-of-devops-tools/) -1. [Puppet Labs: State of Dev Ops 2015 - Book](https://puppetlabs.com/sites/default/files/2015-state-of-devops-report.pdf) +1. [Puppet Labs: State of Dev Ops 2016 - Book](https://puppet.com/resources/white-paper/2016-state-of-devops-report) #### 3.2. Installing GitLab with Omnibus @@ -173,7 +173,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project #### 3.6 Custom Languages -1. [How to add Syntax Highlighting Support for Custom Langauges to GitLab - Video](how to add support for your favorite language to GitLab) +1. [How to add Syntax Highlighting Support for Custom Languages to GitLab - Video](https://youtu.be/6WxTMqatrrA) #### 3.7. Scalability and High Availability @@ -198,7 +198,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project --- -## 4. External Articles +### 4. External Articles 1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](http://www.wsj.com/articles/SB10001424053111903480904576512250915629460) 1. [2014 Blog post by Chris Dixon - Software eats software development](http://cdixon.org/2014/04/13/software-eats-software-development/) @@ -206,7 +206,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project --- -## 5. Resources for GitLab Team Members +### 5. Resources for GitLab Team Members *Some content can only be accessed by GitLab team members* diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md index c0084d9d59c..8c0d3f78b55 100644 --- a/doc/update/8.12-to-8.13.md +++ b/doc/update/8.12-to-8.13.md @@ -166,7 +166,7 @@ See [smtp_settings.rb.sample] as an example. Ensure you're still up-to-date with the latest init script changes: sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - + For Ubuntu 16.04.1 LTS: sudo systemctl daemon-reload diff --git a/doc/update/8.14-to-8.15.md b/doc/update/8.14-to-8.15.md new file mode 100644 index 00000000000..5556dae2551 --- /dev/null +++ b/doc/update/8.14-to-8.15.md @@ -0,0 +1,202 @@ +# From 8.14 to 8.15 + +Make sure you view this update guide from the tag (version) of GitLab you would +like to install. In most cases this should be the highest numbered production +tag (without rc in it). You can select the tag in the version dropdown at the +top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + + sudo service gitlab stop + +### 2. Backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +We will continue supporting Ruby < 2.3 for the time being but we recommend you +upgrade to Ruby 2.3 if you're running a source installation, as this is the same +version that ships with our Omnibus package. + +You can check which version you are running with `ruby -v`. + +Download and compile Ruby: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz +echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz +cd ruby-2.3.1 +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Get latest code + +```bash +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +sudo -u git -H git checkout 8-15-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +sudo -u git -H git checkout 8-15-stable-ee +``` + +### 5. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v4.0.3 +``` + +### 6. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires +[Go 1.5](https://golang.org/dl) which should already be on your system from +GitLab 8.1. + +```bash +sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production +``` + +### 7. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache +sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production +``` + +### 8. Update configuration files + +#### New configuration options for `gitlab.yml` + +There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +git diff origin/8-14-stable:config/gitlab.yml.example origin/8-15-stable:config/gitlab.yml.example +``` + +#### Git configuration + +Configure Git to generate packfile bitmaps (introduced in Git 2.0) on +the GitLab server during `git gc`. + +```sh +sudo -u git -H git config --global repack.writeBitmaps true +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +# For HTTPS configurations +git diff origin/8-14-stable:lib/support/nginx/gitlab-ssl origin/8-15-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/8-14-stable:lib/support/nginx/gitlab origin/8-15-stable:lib/support/nginx/gitlab +``` + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +Ensure you're still up-to-date with the latest init script changes: + + sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab + +For Ubuntu 16.04.1 LTS: + + sudo systemctl daemon-reload + +### 9. Start application + + sudo service gitlab start + sudo service nginx restart + +### 10. Check application status + +Check if GitLab and its environment are configured correctly: + + sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production + +To make sure you didn't miss anything run a more thorough check: + + sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (8.14) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 8.13 to 8.14](8.13-to-8.14.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index 60729316cde..685972cfb41 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -1,7 +1,10 @@ # Universal update guide for patch versions -*Make sure you view this [upgrade guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/patch_versions.md) from the `master` branch for the most up to date instructions.* -For example from 7.14.0 to 7.14.3, also see the [semantic versioning specification](http://semver.org/). +## Select Version to Install + +Make sure you view [this update guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/patch_versions.md) from the tag (version) of GitLab you would like to install. +In most cases this should be the highest numbered production tag (without rc in it). +You can select the tag in the version dropdown in the top left corner of GitLab (below the menu bar). ### 0. Backup @@ -45,10 +48,9 @@ sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -b v`ca ### 4. Update gitlab-workhorse to the corresponding version ```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch -sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` -b v`cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` -sudo -u git -H make +cd /home/git/gitlab + +sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production ``` ### 5. Install libs, migrations, etc. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 162d1bd7ed4..4d24eb21976 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -267,6 +267,18 @@ GFM also recognizes certain cross-project references: | `namespace/project@9ba12248...b19a04f5` | commit range comparison | | `namespace/project~"Some label"` | issues with given label | +It also has a shorthand version to reference other projects from the same namespace: + +| input | references | +|:------------------------------|:------------------------| +| `project#123` | issue | +| `project!123` | merge request | +| `project%123` | milestone | +| `project$123` | snippet | +| `project@9ba12248` | specific commit | +| `project@9ba12248...b19a04f5` | commit range comparison | +| `project~"Some label"` | issues with given label | + ### Task Lists > If this is not rendered correctly, see @@ -604,7 +616,7 @@ This line is separated from the one above by two newlines, so it will be a *sepa 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 also a separate paragraph, and... This line is on its own line, because the previous line ends with two spaces. ``` @@ -616,7 +628,7 @@ This line is separated from the one above by two newlines, so it will be a *sepa 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 also a separate paragraph, and... This line is on its own line, because the previous line ends with two spaces. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index cea78864df2..39fe2409a29 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -141,10 +141,9 @@ instance and project. In addition, all admins can use the admin interface under | See events in the system | | | | ✓ | | Admin interface | | | | ✓ | -### Build permissions - -> Changed in GitLab 8.12. +### Builds permissions +>**Note:** GitLab 8.12 has a completely redesigned build permissions system. Read all about the [new model and its implications][new-mod]. diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index b205fea2c40..47a4a3f85d0 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -4,13 +4,15 @@ --- -> **Note** -Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker -versions earlier than 1.10. -> -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). +>**Notes:** +- Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker + versions earlier than 1.10. +- 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). +- Starting from GitLab 8.12, if you have 2FA enabled in your account, you need + to pass a personal access token instead of your password in order to login to + GitLab's Container Registry. With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index 5af9a5d049c..be09337319f 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -19,14 +19,14 @@ in a merged merge requests or a commit. [Learn more about cherry-picking changes.](merge_requests/cherry_pick_changes.md) -## Merge when build succeeds +## Merge when pipeline 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. +more CI builds running, you can set it to be merged automatically when CI +pipeline succeeds. This way, you don't have to wait for the pipeline to finish +and remember to merge the request manually. -[Learn more about merging when build succeeds.](merge_requests/merge_when_build_succeeds.md) +[Learn more about merging when pipeline succeeds.](merge_requests/merge_when_pipeline_succeeds.md) ## Resolve discussion comments in merge requests reviews diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png b/doc/user/project/merge_requests/img/preview_issue_for_discussions.png Binary files differnew file mode 100644 index 00000000000..9fdd387676c --- /dev/null +++ b/doc/user/project/merge_requests/img/preview_issue_for_discussions.png diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index 285b1798ac5..f37f1ce4d21 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -37,7 +37,8 @@ resolved discussions tracker. > [Introduced][ce-7125] in GitLab 8.14. -You can prevent merge requests from being merged until all discussions are resolved. +You can prevent merge requests from being merged until all discussions are +resolved. Navigate to your project's settings page, select the **Only allow merge requests to be merged if all discussions are resolved** check @@ -50,8 +51,26 @@ are resolved.  +### Move all unresolved discussions in a merge request to an issue + +> [Introduced][ce-7180] (Currently on Backlog) + +To delegate unresolved discussions to a new issue you can click the link **open +an issue to resolve them later**. + +This will prepare an issue with content referring to the merge request and +discussions. + + + +Hitting **Submit issue** will cause all discussions to be marked as resolved and +add a note referring to the newly created issue. + +You can now proceed to merge the merge request from the UI. + [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 +[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180 [resolve-discussion-button]: img/resolve_discussion_button.png [resolve-comment-button]: img/resolve_comment_button.png [discussion-view]: img/discussion_view.png diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md index d4e5b5de685..2167fdfbf7e 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -1,46 +1,5 @@ -# Merge When Build Succeeds +This document was moved to [merge_when_pipeline_succeeds](merge_when_pipeline_succeeds.md). -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 the -builds pipeline succeed. This way, you don't have to wait for the builds to -finish and remember to merge the request manually. +>[Introduced][ce-7135] by the "Rename MWBS service to Merge When Pipeline Succeeds" change. - - -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 pipeline 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. - - - -When the pipeline succeeds, the merge request will automatically be merged. -When the pipeline 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. - -## Only allow merge requests to be merged if the build succeeds - -> **Note:** -You need to have builds configured to enable this feature. - -You can prevent merge requests from being merged if their build did not succeed. - -Navigate to your project's settings page, select the -**Only allow merge requests to be merged if the build succeeds** check box and -hit **Save** for the changes to take effect. - - - -From now on, every time the pipeline fails you will not be able to merge the -merge request from the UI, until you make all relevant builds pass. - - +[ce-7135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7135 diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md new file mode 100644 index 00000000000..75ad18b28cf --- /dev/null +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -0,0 +1,46 @@ +# Merge When Pipeline 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 the +builds pipeline succeeds. This way, you don't have to wait for the builds to +finish and remember to merge the request manually. + + + +When you hit the "Merge When Pipeline Succeeds" button, the status of the merge +request will be updated to represent the impending merge. If you cannot wait +for the pipeline 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. + + + +When the pipeline succeeds, the merge request will automatically be merged. +When the pipeline 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. + +## Only allow merge requests to be merged if the pipeline succeeds + +> **Note:** +You need to have builds configured to enable this feature. + +You can prevent merge requests from being merged if their pipeline did not succeed. + +Navigate to your project's settings page, select the +**Only allow merge requests to be merged if the pipeline succeeds** check box and +hit **Save** for the changes to take effect. + + + +From now on, every time the pipeline fails you will not be able to merge the +merge request from the UI, until you make all relevant builds pass. + + diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 60b7bec2ba7..320faff65c5 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -34,9 +34,9 @@ as created be the pusher (local push or via the UI) and any build created in thi pipeline will have the permissions of the pusher. This allows us to make it really easy to evaluate the access for all projects -that have Git submodules or are using container images that the pusher would -have access too. **The permission is granted only for time that build is running. -The access is revoked after the build is finished.** +that have [Git submodules][gitsub] or are using container images that the pusher +would have access too. **The permission is granted only for time that build is +running. The access is revoked after the build is finished.** ## Types of users @@ -141,7 +141,7 @@ with GitLab 8.12. With the new build permissions model, there is now an easy way to access all dependent source code in a project. That way, we can: -1. Access a project's Git submodules +1. Access a project's [Git submodules][gitsub] 1. Access private container images 1. Access project's and submodule LFS objects @@ -179,119 +179,25 @@ As a user: ### Git submodules -> -It often happens that while working on one project, you need to use another -project from within it; perhaps it’s a library that a third party developed or -you’re developing a project separately and are using it in multiple parent -projects. -A common issue arises in these scenarios: you want to be able to treat the two -projects as separate yet still be able to use one from within the other. -> -_Excerpt from the [Git website][git-scm] about submodules._ - -If dealing with submodules, your project will probably have a file named -`.gitmodules`. And this is how it usually looks like: - -``` -[submodule "tools"] - path = tools - url = git@gitlab.com/group/tools.git -``` - -> **Note:** -If you are **not** using GitLab 8.12 or higher, you would need to work your way -around this issue in order to access the sources of `gitlab.com/group/tools` -(e.g., use [SSH keys](../ssh_keys/README.md)). -> -With GitLab 8.12 onward, your permissions are used to evaluate what a CI build -can access. More information about how this system works can be found in the -[Build permissions model](../../user/permissions.md#builds-permissions). - -To make use of the new changes, you have to update your `.gitmodules` file to -use a relative URL. - -Let's consider the following example: - -1. Your project is located at `https://gitlab.com/secret-group/my-project`. -1. To checkout your sources you usually use an SSH address like - `git@gitlab.com:secret-group/my-project.git`. -1. Your project depends on `https://gitlab.com/group/tools`. -1. You have the `.gitmodules` file with above content. - -Since Git allows the usage of relative URLs for your `.gitmodules` configuration, -this easily allows you to use HTTP for cloning all your CI builds and SSH -for all your local checkouts. - -For example, if you change the `url` of your `tools` dependency, from -`git@gitlab.com/group/tools.git` to `../../group/tools.git`, this will instruct -Git to automatically deduce the URL that should be used when cloning sources. -Whether you use HTTP or SSH, Git will use that same channel and it will allow -to make all your CI builds use HTTPS (because GitLab CI uses HTTPS for cloning -your sources), and all your local clones will continue using SSH. - -Given the above explanation, your `.gitmodules` file should eventually look -like this: - -``` -[submodule "tools"] - path = tools - url = ../../group/tools.git -``` - -However, you have to explicitly tell GitLab CI to clone your submodules as this -is not done automatically. You can achieve that by adding a `before_script` -section to your `.gitlab-ci.yml`: - -``` -before_script: - - git submodule update --init --recursive - -test: - script: - - run-my-tests -``` - -This will make GitLab CI initialize (fetch) and update (checkout) all your -submodules recursively. - -If Git does not use the newly added relative URLs but still uses your old URLs, -you might need to add `git submodule sync --recursive` to your `.gitlab-ci.yml`, -prior to running `git submodule update --init --recursive`. This transfers the -changes from your `.gitmodules` file into the `.git` folder, which is kept by -runners between runs. - -In case your environment or your Docker image doesn't have Git installed, -you have to either ask your Administrator or install the missing dependency -yourself: - -``` -# Debian / Ubuntu -before_script: - - apt-get update -y - - apt-get install -y git-core - - git submodule update --init --recursive - -# CentOS / RedHat -before_script: - - yum install git - - git submodule update --init --recursive - -# Alpine -before_script: - - apk add -U git - - git submodule update --init --recursive -``` +To properly configure submodules with GitLab CI, read the +[Git submodules documentation][gitsub]. ### Container Registry With the update permission model we also extended the support for accessing Container Registries for private projects. -> **Note:** -As GitLab Runner 1.6 doesn't yet incorporate the introduced changes for -permissions, this makes the `image:` directive to not work with private projects -automatically. The manual configuration by an Administrator is required to use -private images. We plan to remove that limitation in one of the upcoming releases. +> **Notes:** +- GitLab Runner versions prior to 1.8 don't incorporate the introduced changes + for permissions. This makes the `image:` directive to not work with private + projects automatically and it needs to be configured manually on Runner's host + with a predefined account (for example administrator's personal account with + access token created explicitly for this purpose). This issue is resolved with + latest changes in GitLab Runner 1.8 which receives GitLab credentials with + build data. +- Starting with GitLab 8.12, if you have 2FA enabled in your account, you need + to pass a personal access token instead of your password in order to login to + GitLab's Container Registry. Your builds can access all container images that you would normally have access to. The only implication is that you can push to the Container Registry of the @@ -310,7 +216,7 @@ test: [build permissions]: ../permissions.md#builds-permissions [comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302 [ext]: ../permissions.md#external-users -[git-scm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[gitsub]: ../../ci/git_submodules.md [https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols [triggers]: ../../ci/triggers/README.md [update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update diff --git a/doc/web_hooks/ssl.png b/doc/web_hooks/ssl.png Binary files differindex a552888ed96..21ddec4ebdf 100644 --- a/doc/web_hooks/ssl.png +++ b/doc/web_hooks/ssl.png diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md index cd37189fdd2..1659dd1f6cb 100644 --- a/doc/web_hooks/web_hooks.md +++ b/doc/web_hooks/web_hooks.md @@ -1,17 +1,21 @@ # Webhooks -_**Note:** -Starting from GitLab 8.5:_ +>**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 -- _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 a URL if for example 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. -Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created. +Webhooks can be used to update an external issue tracker, trigger CI builds, +update a backup mirror, or even deploy to your production server. -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. +Navigate to the webhooks page by choosing **Webhooks** from your project's +settings which can be found under the wheel icon in the upper right corner. ## Webhook endpoint tips @@ -26,21 +30,27 @@ GitLab webhooks keep in mind the following things: you are writing a low-level hook this is important to remember. - GitLab ignores the HTTP status code returned by your endpoint. -## Secret Token +## Secret token -If you specify a secret token, it will be sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. +If you specify a secret token, it will be sent with the hook request in the +`X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify +that the request is legitimate. -## SSL Verification +## 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. +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.  -## Push events +## Events + +Below are described the supported events. + +### Push events Triggered when you push to the repository except when pushing tags. @@ -121,7 +131,7 @@ X-Gitlab-Event: Push Hook } ``` -## Tag events +### Tag events Triggered when you create (or delete) tags to the repository. @@ -174,7 +184,7 @@ X-Gitlab-Event: Tag Push Hook } ``` -## Issues events +### Issues events Triggered when a new issue is created or an existing issue was updated/closed/reopened. @@ -240,7 +250,7 @@ X-Gitlab-Event: Issue Hook } } ``` -## Comment events +### 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 @@ -253,7 +263,7 @@ Valid target types: 3. `issue` 4. `snippet` -### Comment on commit +#### Comment on commit **Request header**: @@ -332,7 +342,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on merge request +#### Comment on merge request **Request header**: @@ -459,7 +469,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on issue +#### Comment on issue **Request header**: @@ -534,7 +544,7 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on code snippet +#### Comment on code snippet **Request header**: @@ -607,7 +617,7 @@ X-Gitlab-Event: Note Hook } ``` -## Merge request events +### 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. @@ -699,7 +709,7 @@ X-Gitlab-Event: Merge Request Hook } ``` -## Wiki Page events +### Wiki Page events Triggered when a wiki page is created or edited. @@ -737,9 +747,9 @@ X-Gitlab-Event: Wiki Page Hook }, "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", + "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": { @@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook } ``` -## Pipeline events +### Pipeline events Triggered on status change of Pipeline. @@ -922,8 +932,7 @@ X-Gitlab-Event: Pipeline Hook } ``` - -## Build events +### Build events Triggered on status change of a Build. @@ -935,7 +944,7 @@ X-Gitlab-Event: Build Hook **Request Body**: -``` +```json { "object_kind": "build", "ref": "gitlab-script-trigger", @@ -980,12 +989,13 @@ X-Gitlab-Event: Build Hook } ``` -#### Example webhook receiver +## 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. +a simple echo script running in a console session. For the following script to +work you need to have Ruby installed. -Save the following file as `print_http_body.rb`. +Save the following file as `print_http_body.rb`: ```ruby require 'webrick' @@ -1005,7 +1015,8 @@ 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. +When you press 'Test Hook' in GitLab, you should see something like this in the +console: ``` {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 2d9bfbc0629..59a806de210 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -25,12 +25,12 @@ - [Merge Requests](../user/project/merge_requests.md) - [Authorization for merge requests](../user/project/merge_requests/authorization_for_merge_requests.md) - [Cherry-pick changes](../user/project/merge_requests/cherry_pick_changes.md) - - [Merge when build succeeds](../user/project/merge_requests/merge_when_build_succeeds.md) + - [Merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) - [Resolve discussion comments in merge requests reviews](../user/project/merge_requests/merge_request_discussion_resolution.md) - [Resolve merge conflicts in the UI](../user/project/merge_requests/resolve_conflicts.md) - [Revert changes in the UI](../user/project/merge_requests/revert_changes.md) - [Merge requests versions](../user/project/merge_requests/versions.md) - ["Work In Progress" merge requests](../user/project/merge_requests/work_in_progress_merge_requests.md) - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md) -- [Importing from SVN, GitHub, BitBucket, etc](importing/README.md) +- [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md) - [Todos](todos.md) diff --git a/doc/workflow/merge_when_build_succeeds.md b/doc/workflow/merge_when_build_succeeds.md index 95afd12ebdb..b4f6d6117de 100644 --- a/doc/workflow/merge_when_build_succeeds.md +++ b/doc/workflow/merge_when_build_succeeds.md @@ -1 +1 @@ -This document was moved to [user/project/merge_requests/merge_when_build_succeeds](../user/project/merge_requests/merge_when_build_succeeds.md). +This document was moved to [merge_when_pipeline_succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md). |
