diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/issues.md | 99 | ||||
| -rw-r--r-- | doc/api/merge_requests.md | 34 | ||||
| -rw-r--r-- | doc/ci/examples/artifactory_and_gitlab/index.md | 4 | ||||
| -rw-r--r-- | doc/development/api_graphql_styleguide.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/icons.md | 4 | ||||
| -rw-r--r-- | doc/development/ux_guide/tips.md | 18 | ||||
| -rw-r--r-- | doc/install/digitaloceandocker.md | 102 | ||||
| -rw-r--r-- | doc/ssh/README.md | 243 | ||||
| -rw-r--r-- | doc/university/training/user_training.md | 267 | ||||
| -rw-r--r-- | doc/user/markdown.md | 111 |
10 files changed, 517 insertions, 367 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index 57e861bc62e..0dc9d706120 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -37,11 +37,11 @@ GET /issues?my_reaction_emoji=star | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone. `Any+Milestone` lists all issues that have an assigned milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -151,11 +151,11 @@ GET /groups/:id/issues?my_reaction_emoji=star | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -265,11 +265,11 @@ GET /projects/:id/issues?my_reaction_emoji=star | `iids[]` | Array[integer] | no | Return only the milestone having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -1113,6 +1113,93 @@ Example response: } ``` +## List merge requests related to issue + +Get all the merge requests that are related to the issue. + +``` +GET /projects/:id/issues/:issue_id/related_merge_requests +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```sh +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests +``` + +Example response: + +```json +[ + { + "id": 29, + "iid": 11, + "project_id": 1, + "title": "Provident eius eos blanditiis consequatur neque odit.", + "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8", + "state": "opened", + "created_at": "2018-09-18T14:36:15.510Z", + "updated_at": "2018-09-19T07:45:13.089Z", + "target_branch": "v2.x", + "source_branch": "so_long_jquery", + "upvotes": 0, + "downvotes": 0, + "author": { + "id": 14, + "name": "Verna Hills", + "username": "lawanda_reinger", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon", + "web_url": "https://gitlab.example.com/lawanda_reinger" + }, + "assignee": { + "id": 19, + "name": "Jody Baumbach", + "username": "felipa.kuvalis", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", + "web_url": "https://gitlab.example.com/felipa.kuvalis" + }, + "source_project_id": 1, + "target_project_id": 1, + "labels": [], + "work_in_progress": false, + "milestone": { + "id": 27, + "iid": 2, + "project_id": 1, + "title": "v1.0", + "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.", + "state": "active", + "created_at": "2018-09-18T14:35:44.353Z", + "updated_at": "2018-09-18T14:35:44.353Z", + "due_date": null, + "start_date": null, + "web_url": "https://gitlab.example.com/twitter/flight/milestones/2" + }, + "merge_when_pipeline_succeeds": false, + "merge_status": "cannot_be_merged", + "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12", + "merge_commit_sha": null, + "user_notes_count": 9, + "discussion_locked": null, + "should_remove_source_branch": null, + "force_remove_source_branch": false, + "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false + } +] +``` + ## List merge requests that will close issue on merge Get all the merge requests that will close issue when merged. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 0291b7e00c2..f3cfe0ad218 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -30,10 +30,10 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -43,11 +43,11 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | -| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ @@ -154,10 +154,10 @@ Parameters: | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a project | | `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -167,9 +167,9 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -266,11 +266,11 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -280,9 +280,9 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 9657f52159e..6aa0edd87b4 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -16,8 +16,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory You'll create two different projects: -- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep) -- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app) +- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep ) +- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app ) We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/). We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 6c6e198a7c3..95722c027ba 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -379,7 +379,7 @@ let(:mutation) do ) end -it 'returns a successfull response' do +it 'returns a successful response' do post_graphql_mutation(mutation, current_user: user) expect(response).to have_gitlab_http_status(:success) diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 3d8da6accc1..533e2001300 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -3,7 +3,7 @@ We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository. This repository is published on [npm][npm] and managed as a dependency via yarn. You can browse all available Icons and Illustrations [here][svg-preview]. -To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`. +To upgrade to a new version run `yarn upgrade @gitlab/svgs`. ## Icons @@ -111,6 +111,6 @@ export default { </template> ``` -[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs +[npm]: https://www.npmjs.com/package/@gitlab/svgs [gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs [svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md index 8348de4f8a2..ceb9ed56ac4 100644 --- a/doc/development/ux_guide/tips.md +++ b/doc/development/ux_guide/tips.md @@ -1,20 +1,16 @@ # Tips -## Contents -* [SVGs](#svgs) - ---- - ## SVGs When exporting SVGs, be sure to follow the following guidelines: 1. Convert all strokes to outlines. -2. Use pathfinder tools to combine overlapping paths and create compound paths. -3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. -4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. +1. Use pathfinder tools to combine overlapping paths and create compound paths. +1. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. +1. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. + +You can open your SVG in a text editor to ensure that it is clean. -You can open your svg in a text editor to ensure that it is clean. Incorrect files will look like this: ```xml @@ -35,10 +31,10 @@ Incorrect files will look like this: </svg> ``` -Correct file will look like this: +Correct files will look like this: ```xml <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> ``` -> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) +> TODO: Checkout <https://github.com/svg/svgo>. diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 676392eacf2..d67695d75b4 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,7 +1,8 @@ # Digital Ocean and Docker Machine test environment -## Warning. This guide is for quickly testing different versions of GitLab and -## not recommended for ease of future upgrades or keeping the data you create. +CAUTION: **Caution:** +This guide is for quickly testing different versions of GitLab and not recommended for ease of +future upgrades or keeping the data you create. ## Initial setup @@ -12,92 +13,88 @@ locally on either macOS or Linux. #### Install Docker Toolbox -1. [https://www.docker.com/products/docker-toolbox](https://www.docker.com/products/docker-toolbox) +- <https://www.docker.com/products/docker-toolbox> ### On Linux #### Install Docker Engine -1. [https://docs.docker.com/engine/installation/linux](https://docs.docker.com/engine/installation/linux/) +- <https://docs.docker.com/engine/installation/linux/> #### Install Docker Machine -1. [https://docs.docker.com/machine/install-machine](https://docs.docker.com/machine/install-machine/) +- <https://docs.docker.com/machine/install-machine/> -_The rest of the steps are identical for macOS and Linux_ +NOTE: **Note:** +The rest of the steps are identical for macOS and Linux. ### Create new docker host -1. Login to Digital Ocean -1. Generate a new API token at https://cloud.digitalocean.com/settings/api/tokens +1. Login to Digital Ocean. +1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. + This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. -This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. + NOTE: **Note:** + 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. -**Note: 4GB is the minimum requirement for a Docker host that will run more then one GitLab instance** + - RAM: 4GB + - Name: `gitlab-test-env-do` + - Driver: `digitalocean` -+ RAM: 4GB -+ Name: `gitlab-test-env-do` -+ Driver: `digitalocean` +1. Set the DO token: + ```sh + export DOTOKEN=<your generated token> + ``` -**Set the DO token** - Replace the string below with your generated token +1. Create the machine: -``` -export DOTOKEN=cf3dfd0662933203005c4a73396214b7879d70aabc6352573fe178d340a80248 -``` - -**Create the machine** - -``` -docker-machine create \ - --driver digitalocean \ - --digitalocean-access-token=$DOTOKEN \ - --digitalocean-size "4gb" \ - gitlab-test-env-do -``` - -+ Resource: https://docs.docker.com/machine/drivers/digital-ocean/ + ```sh + docker-machine create \ + --driver digitalocean \ + --digitalocean-access-token=$DOTOKEN \ + --digitalocean-size "4gb" \ + gitlab-test-env-do + ``` +Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. ### Creating GitLab test instance - #### Connect your shell to the new machine - In this example we'll create a GitLab EE 8.10.8 instance. - First connect the docker client to the docker host you created previously. -``` +```sh eval "$(docker-machine env gitlab-test-env-do)" ``` You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` docker host - #### Create new GitLab container -+ HTTP port: `8888` -+ SSH port: `2222` - + Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG ` -+ Hostname: IP of docker host -+ Container name: `gitlab-test-8.10` -+ GitLab version: **EE** `8.10.8-ee.0` +- HTTP port: `8888` +- SSH port: `2222` + - Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG` +- Hostname: IP of docker host +- Container name: `gitlab-test-8.10` +- GitLab version: **EE** `8.10.8-ee.0` -##### Set up container settings +##### Set up container settings -``` +```sh export SSH_PORT=2222 export HTTP_PORT=8888 export VERSION=8.10.8-ee.0 export NAME=gitlab-test-8.10 ``` -##### Create container -``` +##### Create container + +```sh docker run --detach \ --env GITLAB_OMNIBUS_CONFIG="external_url 'http://$(docker-machine ip gitlab-test-env-do):$HTTP_PORT'; gitlab_rails['gitlab_shell_ssh_port'] = $SSH_PORT;" \ --hostname $(docker-machine ip gitlab-test-env-do) \ @@ -110,23 +107,20 @@ gitlab/gitlab-ee:$VERSION ##### Retrieve the docker host IP -``` +```sh docker-machine ip gitlab-test-env-do # example output: 192.168.151.134 ``` - -+ Browse to: http://192.168.151.134:8888/ - +Browse to: <http://192.168.151.134:8888/>. ##### Execute interactive shell/edit configuration - -``` +```sh docker exec -it $NAME /bin/bash ``` -``` +```sh # example commands root@192:/# vi /etc/gitlab/gitlab.rb root@192:/# gitlab-ctl reconfigure @@ -134,6 +128,6 @@ root@192:/# gitlab-ctl reconfigure #### Resources -+ [https://docs.gitlab.com/omnibus/docker/](https://docs.gitlab.com/omnibus/docker/) -+ [https://docs.docker.com/machine/get-started/](https://docs.docker.com/machine/get-started/) -+ [https://docs.docker.com/machine/reference/ip/](https://docs.docker.com/machine/reference/ip/)+ +- <https://docs.gitlab.com/omnibus/docker/>. +- <https://docs.docker.com/machine/get-started/>. +- <https://docs.docker.com/machine/reference/ip/>. diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 5db042326f3..c5b7813b285 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -8,163 +8,224 @@ you need a secure communication channel for sharing information. The SSH protocol provides this security and allows you to authenticate to the GitLab remote server without supplying your username or password each time. -For a more detailed explanation of how the SSH protocol works, we advise you to -read [this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). +For a more detailed explanation of how the SSH protocol works, read +[this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). -## Locating an existing SSH key pair +## Requirements -Before generating a new SSH key pair check if your system already has one -at the default location by opening a shell, or Command Prompt on Windows, -and running the following command: +The only requirement is to have the OpenSSH client installed on your system. This +comes pre-installed on GNU/Linux and macOS, but not on Windows. -**Windows Command Prompt:** +Depending on your Windows version, there are different methods to work with +SSH keys. -```bash -type %userprofile%\.ssh\id_rsa.pub -``` +### Installing the SSH client for Windows 10 -**Git Bash on Windows / GNU/Linux / macOS / PowerShell:** +Starting with Windows 10, you can +[install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +where you can run Linux distributions directly on Windows, without the overhead +of a virtual machine. Once installed and set up, you'll have the Git and SSH +clients at your disposal. -```bash -cat ~/.ssh/id_rsa.pub -``` +### Installing the SSH client for Windows 8.1 and Windows 7 + +The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 +is [Git for Windows](https://gitforwindows.com). It provides a BASH +emulation (Git Bash) used for running Git from the command line and the +`ssh-keygen` command that is useful to create SSH keys as you'll learn below. + +NOTE: **Alternative tools:** +Although not explored in this page, you can use some alternative tools. +[Cygwin](https://www.cygwin.com) is a large collection of GNU and open source +tools which provide functionality similar to a Unix distribution. +[PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) +provides a graphical user interface to [create SSH keys](https://tartarus.org/~simon/putty-snapshots/htmldoc/Chapter8.html#pubkey-puttygen). + +## Types of SSH keys and which to choose + +GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on +the signing algorithm, and some of them have advantages over the others. For +more information, you can read this +[nice article on ArchWiki](https://wiki.archlinux.org/index.php/SSH_keys#Choosing_the_authentication_key_type). +We'll focus on ED25519 and RSA and here. + +NOTE: **Note:** +As an admin, you can restrict +[which keys should be permitted and their minimum length](../security/ssh_keys_restrictions.md). +By default, all keys are permitted, which is also the case for +[GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints). -If you see a string starting with `ssh-rsa` you already have an SSH key pair -and you can skip the generate portion of the next section and skip to the copy -to clipboard step. -If you don't see the string or would like to generate a SSH key pair with a -custom name continue onto the next step. +## ED25519 SSH keys -Note that Public SSH key may also be named as follows: +Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/), +you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they +are more secure and have better performance over the other types. -- `id_dsa.pub` -- `id_ecdsa.pub` -- `id_ed25519.pub` +They were introduced in OpenSSH 6.5, so any modern OS should include the +option to create them. If for any reason your OS or the GitLab instance you +interact with doesn't support this, you can fallback to RSA. + +## RSA SSH keys + +RSA keys are the most common ones and therefore the most compatible with +servers that may have an old OpenSSH version. Use them if the GitLab server +doesn't work with ED25519 keys. + +The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a +stronger RSA key pair, specify the `-b` flag with a higher bit value than the +default. + +The old, default password encoding for SSH private keys keys is +[insecure](https://latacora.singles/2018/08/03/the-default-openssh.html); +it's only a single round of an MD5 hash. Since OpenSSH version 6.5, you should +use the `-o` option to `ssh-keygen` to encode your private key in a new, more +secure format. + +If you already have an RSA SSH key pair to use with GitLab, consider upgrading it +to use the more secure password encryption format by using the following command +on the private key: + +```bash +ssh-keygen -o -f ~/.ssh/id_rsa +``` ## Generating a new SSH key pair -1. To generate a new SSH key pair, use the following command: +Before creating an SSH key pair, make sure to read about the +[different types of keys](#types-of-ssh-keys-and-which-to-choose) to understand +their differences. + +To create a new SSH key pair: - **Git Bash on Windows / GNU/Linux / macOS:** +1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows. +1. Generate a new ED25519 SSH key pair: ```bash - ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096 + ssh-keygen -t ed25519 -C "email@example.com" ``` - (Note: the `-o` option was introduced in 2014; if this command does not work for you, simply remove the `-o` option and try again) + Or, if you want to use RSA: - **Windows:** + ```bash + ssh-keygen -o -t rsa -b 4096 -C "email@example.com" + ``` - Alternatively on Windows you can download - [PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - and follow [this documentation article][winputty] to generate a SSH key pair. + The `-C` flag adds a comment in the key in case you have multiple of them + and want to tell which is which. It is optional. 1. Next, you will be prompted to input a file path to save your SSH key pair to. + If you don't already have an SSH key pair, use the suggested path by pressing + <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client + to automatically use the SSH key pair with no additional configuration. - If you don't already have an SSH key pair use the suggested path by pressing - enter. Using the suggested path will normally allow your SSH client - to automatically use the SSH key pair with no additional configuration. + If you already have an SSH key pair with the suggested file path, you will need + to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths) + this SSH key pair will be used for in your `~/.ssh/config` file. - If you already have a SSH key pair with the suggested file path, you will need - to input a new file path and declare what host this SSH key pair will be used - for in your `.ssh/config` file, see [**Working with non-default SSH key pair paths**](#working-with-non-default-ssh-key-pair-paths) - for more information. +1. Once the path is decided, you will be prompted to input a password to + secure your new SSH key pair. It's a best practice to use a password, + but it's not required and you can skip creating it by pressing + <kbd>Enter</kbd> twice. -1. Once you have input a file path you will be prompted to input a password to - secure your SSH key pair. It is a best practice to use a password for an SSH - key pair, but it is not required and you can skip creating a password by - pressing enter. + If, in any case, you want to add or change the password of your SSH key pair, + you can use the `-p`flag: - NOTE: **Note:** - If you want to change the password of your SSH key pair, you can use - `ssh-keygen -p -o -f <keyname>`. - The `-o` option was added in 2014, so if this command does not work for you, - simply remove the `-o` option and try again. + ``` + ssh-keygen -p -o -f <keyname> + ``` -## Adding a SSH key to your GitLab account +Now, it's time to add the newly created public key to your GitLab account. -1. The next step is to copy the public SSH key as we will need it afterwards. +## Adding an SSH key to your GitLab account - To copy your public SSH key to the clipboard, use the appropriate code below: +1. Copy your **public** SSH key to the clipboard by using one of the commands below + depending on your Operating System: **macOS:** ```bash - pbcopy < ~/.ssh/id_rsa.pub + pbcopy < ~/.ssh/id_ed25519.pub ``` - **GNU/Linux (requires the xclip package):** + **WSL / GNU/Linux (requires the xclip package):** ```bash - xclip -sel clip < ~/.ssh/id_rsa.pub + xclip -sel clip < ~/.ssh/id_ed25519.pub ``` - **Windows Command Line:** + **Git Bash on Windows:** ```bash - type %userprofile%\.ssh\id_rsa.pub | clip + cat ~/.ssh/id_ed25519.pub | clip ``` - **Git Bash on Windows / Windows PowerShell:** + You can also open the key in a graphical editor and copy it from there, + but be careful not to accidentally change anything. - ```bash - cat ~/.ssh/id_rsa.pub | clip - ``` - -1. The final step is to add your public SSH key to GitLab. + NOTE: **Note:** + If you opted to create an RSA key, the name might differ. - Navigate to the 'SSH Keys' tab in your 'Profile Settings'. - Paste your key in the 'Key' section and give it a relevant 'Title'. - Use an identifiable title like 'Work Laptop - Windows 7' or - 'Home MacBook Pro 15'. +1. Add your public SSH key to your GitLab account by clicking your avatar + in the upper right corner and selecting **Settings**. From there on, + navigate to **SSH Keys** and paste your public key in the "Key" section. + If you created the key with a comment, this will appear under "Title". + If not, give your key an identifiable title like _Work Laptop_ or + _Home Workstation_, and click **Add key**. + NOTE: **Note:** If you manually copied your public SSH key make sure you copied the entire - key starting with `ssh-rsa` and ending with your email. + key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email. + +## Testing that everything is set up correctly + +To test whether your SSH key was added correctly, run the following command in +your terminal (replacing `gitlab.com` with your GitLab's instance domain): -1. Optionally you can test your setup by running `ssh -T git@example.com` - (replacing `example.com` with your GitLab domain) and verifying that you - receive a `Welcome to GitLab` message. +```bash +ssh -T git@gitlab.com +``` + +You should receive a _Welcome to GitLab, `@username`!_ message. + +If the welcome message doesn't appear, run SSH's verbose mode by replacing `-T` +with `-vvvT` to understand where the error is. ## Working with non-default SSH key pair paths If you used a non-default file path for your GitLab SSH key pair, you must configure your SSH client to find your GitLab private SSH key -for connections to your GitLab server (perhaps `gitlab.com`). +for connections to GitLab. -For your current terminal session you can do so using the following commands +Open a terminal and use the following commands (replacing `other_id_rsa` with your private SSH key): -**Git Bash on Windows / GNU/Linux / macOS:** - ```bash eval $(ssh-agent -s) ssh-add ~/.ssh/other_id_rsa ``` -To retain these settings you'll need to save them to a configuration file. -For OpenSSH clients this is configured in the `~/.ssh/config` file for some -operating systems. +To retain these settings, you'll need to save them to a configuration file. +For OpenSSH clients this is configured in the `~/.ssh/config` file. In this +file you can set up configurations for multiple hosts, like GitLab.com, your +own GitLab instance, GitHub, Bitbucket, etc. + Below are two example host configurations using their own SSH key: -``` -# GitLab.com server +```conf +# GitLab.com Host gitlab.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename-01 + Preferredauthentications publickey + IdentityFile ~/.ssh/gitlab_com_rsa -# Private GitLab server +# Private GitLab instance Host gitlab.company.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename + Preferredauthentications publickey + IdentityFile ~/.ssh/example_com_rsa ``` -Due to the wide variety of SSH clients and their very large number of -configuration options, further explanation of these topics is beyond the scope -of this document. - -Public SSH keys need to be unique, as they will bind to your account. -Your SSH key is the only identifier you'll have when pushing code via SSH. -That's why it needs to uniquely map to a single user. +Public SSH keys need to be unique to GitLab, as they will bind to your account. +Your SSH key is the only identifier you'll have when pushing code via SSH, +that's why it needs to uniquely map to a single user. ## Deploy keys @@ -240,8 +301,6 @@ not implicitly give any access just by setting them up. How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration -[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen - ## SSH on the GitLab server GitLab integrates with the system-installed SSH daemon, designating a user diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index dccb6cbf071..f3a4d766522 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -6,91 +6,90 @@ comments: false --- -# Agenda +## Agenda -1. Brief history of Git -1. GitLab walkthrough -1. Configure your environment -1. Workshop +1. Brief history of Git. +1. GitLab walkthrough. +1. Configure your environment. +1. Workshop. --- -# Git introduction +## Git introduction -https://git-scm.com/about +<https://git-scm.com/about> -- Distributed version control - - Does not rely on connection to a central server - - Many copies of the complete history -- Powerful branching and merging -- Adapts to nearly any workflow -- Fast, reliable and stable file format +- Distributed version control. + - Does not rely on connection to a central server. + - Many copies of the complete history. +- Powerful branching and merging. +- Adapts to nearly any workflow. +- Fast, reliable and stable file format. --- -# Help! +## Help! Use the tools at your disposal when you get stuck. -- Use '`git help <command>`' command -- Use Google -- Read documentation at https://git-scm.com +- Use '`git help <command>`' command. +- Use Google. +- Read documentation at <https://git-scm.com>. --- -# GitLab Walkthrough +## GitLab Walkthrough  --- -# Configure your environment +## Configure your environment - Windows: Install 'Git for Windows' -> https://git-for-windows.github.io +> <https://git-for-windows.github.io> - Mac: Type '`git`' in the Terminal application. > If it's not installed, it will prompt you to install it. -- Debian: '`sudo apt-get install git-all`' -or Red Hat '`sudo yum install git-all`' +- Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' --- -# Git Workshop +## Git Workshop -## Overview +### Overview -1. Configure Git -1. Configure SSH Key -1. Create a project -1. Committing -1. Feature branching -1. Merge requests -1. Feedback and Collaboration +1. Configure Git. +1. Configure SSH Key. +1. Create a project. +1. Committing. +1. Feature branching. +1. Merge requests. +1. Feedback and Collaboration. --- -# Configure Git +## Configure Git -One-time configuration of the Git client +One-time configuration of the Git client: -```bash +```sh git config --global user.name "Your Name" git config --global user.email you@example.com ``` --- -# Configure SSH Key +## Configure SSH Key -```bash +```sh ssh-keygen -t rsa -b 4096 -C "you@computer-name" ``` -```bash +```sh # You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. Generating public/private rsa key pair. Enter file in which to save the key (/Users/you/.ssh/id_rsa): @@ -102,31 +101,30 @@ The key fingerprint is: 39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name ``` -Copy your public key and add it to your GitLab profile +Copy your public key and add it to your GitLab profile: -```bash +```sh cat ~/.ssh/id_rsa.pub ``` -```bash +```sh ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com ``` --- -# Create a project +## Create a project -- Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git +- Create a project in your user namespace. + - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. - Create a '`development`' or '`workspace`' directory in your home directory. -- Clone the '`training-examples`' project +- Clone the '`training-examples`' project. --- -# Commands +## Commands (project) -``` +```sh mkdir ~/development cd ~/development @@ -141,37 +139,37 @@ cd training-examples --- -# Git concepts +## Git concepts -**Untracked files** +### Untracked files New files that Git has not been told to track previously. -**Working area** +### Working area Files that have been modified but are not committed. -**Staging area** +### Staging area Modified files that have been marked to go in the next commit. --- -# Committing +## Committing -1. Edit '`edit_this_file.rb`' in '`training-examples`' -1. See it listed as a changed file (working area) -1. View the differences -1. Stage the file -1. Commit -1. Push the commit to the remote -1. View the git log +1. Edit '`edit_this_file.rb`' in '`training-examples`'. +1. See it listed as a changed file (working area). +1. View the differences. +1. Stage the file. +1. Commit. +1. Push the commit to the remote. +1. View the git log. --- -# Commands +## Commands (committing) -``` +```sh # Edit `edit_this_file.rb` git status git diff @@ -183,29 +181,29 @@ git log --- -# Feature branching +## Feature branching -- Efficient parallel workflow for teams -- Develop each feature in a branch -- Keeps changes isolated -- Consider a 1-to-1 link to issues -- Push branches to the server frequently - - Hint: This is a cheap backup for your work-in-progress code +- Efficient parallel workflow for teams. +- Develop each feature in a branch. +- Keeps changes isolated. +- Consider a 1-to-1 link to issues. +- Push branches to the server frequently. + - Hint: This is a cheap backup for your work-in-progress code. --- -# Feature branching +## Feature branching steps -1. Create a new feature branch called 'squash_some_bugs' +1. Create a new feature branch called 'squash_some_bugs'. 1. Edit '`bugs.rb`' and remove all the bugs. -1. Commit -1. Push +1. Commit. +1. Push. --- -# Commands +## Commands (feature branching) -``` +```sh git checkout -b squash_some_bugs # Edit `bugs.rb` git status @@ -216,51 +214,50 @@ git push origin squash_some_bugs --- -# Merge requests +## Merge requests -- When you want feedback create a merge request -- Target is the ‘default’ branch (usually master) -- Assign or mention the person you would like to review -- Add 'WIP' to the title if it's a work in progress -- When accepting, always delete the branch -- Anyone can comment, not just the assignee -- Push corrections to the same branch +- When you want feedback create a merge request. +- Target is the ‘default’ branch (usually master). +- Assign or mention the person you would like to review. +- Add 'WIP' to the title if it's a work in progress. +- When accepting, always delete the branch. +- Anyone can comment, not just the assignee. +- Push corrections to the same branch. --- -# Merge requests +## Merge requests steps -**Create your first merge request** +Create your first merge request: -1. Use the blue button in the activity feed -1. View the diff (changes) and leave a comment -1. Push a new commit to the same branch -1. Review the changes again and notice the update +1. Use the blue button in the activity feed. +1. View the diff (changes) and leave a comment. +1. Push a new commit to the same branch. +1. Review the changes again and notice the update. --- -# Feedback and Collaboration +## Feedback and Collaboration -- Merge requests are a time for feedback and collaboration -- Giving feedback is hard -- Be as kind as possible -- Receiving feedback is hard -- Be as receptive as possible -- Feedback is about the best code, not the person. You are not your code +- Merge requests are a time for feedback and collaboration. +- Giving feedback is hard. +- Be as kind as possible. +- Receiving feedback is hard. +- Be as receptive as possible. +- Feedback is about the best code, not the person. You are not your code. --- -# Feedback and Collaboration +## Feedback and Collaboration resources Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: -[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) +<https://github.com/thoughtbot/guides/tree/master/code-review>. -See GitLab merge requests for examples: -[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) +See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>. --- -# Explore GitLab projects +## Explore GitLab projects  @@ -274,31 +271,29 @@ See GitLab merge requests for examples: --- -# Tags +## Tags -- Useful for marking deployments and releases -- Annotated tags are an unchangeable part of Git history -- Soft/lightweight tags can be set and removed at will -- Many projects combine an annotated release tag with a stable branch -- Consider setting deployment/release tags automatically +- Useful for marking deployments and releases. +- Annotated tags are an unchangeable part of Git history. +- Soft/lightweight tags can be set and removed at will. +- Many projects combine an annotated release tag with a stable branch. +- Consider setting deployment/release tags automatically. --- -# Tags - -- Create a lightweight tag -- Create an annotated tag -- Push the tags to the remote repository +## Tags steps -**Additional resources** +1. Create a lightweight tag. +1. Create an annotated tag. +1. Push the tags to the remote repository. -[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) +Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>. --- -# Commands +## Commands (tags) -``` +```sh git checkout master # Lightweight tag @@ -313,31 +308,31 @@ git push origin --tags --- -# Merge conflicts +## Merge conflicts -- Happen often -- Learning to fix conflicts is hard -- Practice makes perfect +- Happen often. +- Learning to fix conflicts is hard. +- Practice makes perfect. - Force push after fixing conflicts. Be careful! --- -# Merge conflicts +## Merge conflicts steps 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. -1. Commit and push +1. Commit and push. 1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. -1. Commit and push to master -1. Create a merge request +1. Commit and push to master. +1. Create a merge request. --- -# Merge conflicts +## Merge conflicts commands After creating a merge request you should notice that conflicts exist. Resolve the conflicts locally by rebasing. -``` +```sh git rebase master # Fix conflicts by editing the files. @@ -350,7 +345,7 @@ git push origin <branch> -f --- -# Rebase with squash +## Rebase with squash You may end up with a commit log that looks like this: @@ -368,11 +363,11 @@ Squash these in to meaningful commits using an interactive rebase. --- -# Rebase with squash +## Rebase with squash commands Squash the commits on the same branch we used for the merge conflicts step. -``` +```sh git rebase -i master ``` @@ -380,17 +375,17 @@ In the editor, leave the first commit as 'pick' and set others to 'fixup'. --- -# Questions? +## Questions?  Thank you for your hard work! -**Additional Resources** +## Additional Resources -GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) -GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) -Pro git book [http://git-scm.com/book](http://git-scm.com/book) -Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) -Code School tutorial [http://try.github.io/](http://try.github.io/) -Contact Us at `subscribers@gitlab.com` +- GitLab Documentation: <http://docs.gitlab.com/>. +- GUI Clients: <http://git-scm.com/downloads/guis>. +- Pro git book: <http://git-scm.com/book>. +- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>. +- Code School tutorial: <http://try.github.io/>. +- Contact us at `subscribers@gitlab.com`. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index f9bdaea185b..96a509c4b21 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,17 +1,8 @@ # Markdown -## GitLab Flavored Markdown (GFM) - -> **Note:** -> Not all of the GitLab-specific extensions to Markdown that are described in -> this document currently work on our documentation website. -> -> For the best result, we encourage you to check this document out as rendered -> by GitLab: [markdown.md] - -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ +This markdown guide is valid for GitLab's system markdown entries and files. -_Where there are significant differences, we will try to call them out in this document._ +## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). @@ -26,11 +17,28 @@ You can use GFM in the following areas: - markdown documents inside the repository You can also use other rich text files in GitLab. You might have to install a -dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. + +> **Notes:** +> +> For the best result, we encourage you to check this document out as rendered +> by GitLab itself: [markdown.md] +> +> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown +processing of all new issues, merge requests, comments, and other Markdown content +in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the +repositories are also processed with CommonMark. Older content in issues/comments +are still processed using the [Redcarpet Ruby library][redcarpet]. +> +> _Where there are significant differences, we will try to call them out in this document._ ### Transitioning to CommonMark -You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. +You may have Markdown documents in your repository that were written using some +of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a +slightly stricter syntax, these documents may now display a little strangely +since we've transitioned to CommonMark. Numbered lists with nested lists in +particular can be displayed incorrectly. It is usually quite easy to fix. In the case of a nested list such as this: @@ -50,11 +58,18 @@ simply add a space to each nested item: In the documentation below, we try to highlight some of the differences. -If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: +If you have a need to view a document using RedCarpet, you can add the token +`legacy_render=1` to the end of the url, like this: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 -If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. +If you have a large volume of Markdown files, it can be tedious to determine +if they will be displayed correctly or not. You can use the +[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) +tool (not an officially supported product) to generate a list of files and +differences between how RedCarpet and CommonMark render the files. It can give +you a great idea if anything needs to be changed - many times nothing will need +to changed. ### Newlines @@ -63,7 +78,8 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newline GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. -A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: <!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> @@ -85,7 +101,9 @@ Sugar is sweet > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words -It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words: +It is not reasonable to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. +Therefore, GFM ignores multiple underscores in words: perform_complicated_task @@ -124,7 +142,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multili On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, GFM supports multiline blockquotes fenced by <code>>>></code>: -```no-highlight +``` >>> If you paste a message from somewhere else @@ -158,7 +176,7 @@ Blocks of code are either fenced by lines with three back-ticks <code>```</code> or are indented with four spaces. Only the fenced code blocks support syntax highlighting: -```no-highlight +``` Inline `code` has `back-ticks around` it. ``` @@ -248,21 +266,23 @@ However the wrapping tags cannot be mixed as such: > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji - Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +``` +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - :zap: You can use emoji anywhere GFM is supported. :v: +:zap: You can use emoji anywhere GFM is supported. :v: - You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. - Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: - Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. - On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. - Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +``` Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px">. Well we have a gift for you: @@ -281,7 +301,6 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. - ### Special GitLab References GFM recognizes special references. @@ -343,7 +362,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-li You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: -```no-highlight +``` - [x] Completed task - [ ] Incomplete task - [ ] Sub-task 1 @@ -355,7 +374,7 @@ You can add task lists to issues, merge requests and comments. To create a task Tasks formatted as ordered lists are supported as well: -```no-highlight +``` 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -412,7 +431,7 @@ This math is inline . This is on a separate line -<div align="center"><img src="./img/math_inline_sup_render_gfm.png" ></div> +<img src="./img/math_inline_sup_render_gfm.png" > _Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ @@ -440,7 +459,7 @@ Examples: `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` -Become: +Becomes:  @@ -482,7 +501,7 @@ For details see the [Mermaid official page][mermaid]. ### Headers -```no-highlight +``` # H1 ## H2 ### H3 @@ -540,7 +559,7 @@ Note that the Emoji processing happens before the header IDs are generated, so t Examples: -```no-highlight +``` Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. @@ -550,7 +569,7 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Become: +Becomes: Emphasis, aka italics, with *asterisks* or _underscores_. @@ -564,7 +583,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ Examples: -```no-highlight +``` 1. First ordered list item 2. Another item * Unordered sub-list. @@ -577,7 +596,7 @@ Examples: + Or pluses ``` -Become: +Becomes: 1. First ordered list item 2. Another item @@ -595,7 +614,7 @@ each subsequent paragraph should be indented to the same level as the start of t Example: -```no-highlight +``` 1. First ordered list item Second paragraph of first item. @@ -616,7 +635,7 @@ the paragraph will appear outside the list, instead of properly indented under t Example: -```no-highlight +``` 1. First ordered list item Paragraph of first item. @@ -676,7 +695,7 @@ Examples: [logo]: img/markdown_logo.png -Become: +Becomes: Here's our logo: @@ -694,7 +713,7 @@ Reference-style: Examples: -```no-highlight +``` > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -703,7 +722,7 @@ Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` -Become: +Becomes: > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -720,7 +739,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd Examples: -```no-highlight +``` <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> @@ -730,7 +749,7 @@ Examples: </dl> ``` -Become: +Becomes: <dl> <dt>Definition list</dt> @@ -788,7 +807,7 @@ ___ Underscores ``` -Become: +Becomes: Three or more... @@ -826,7 +845,7 @@ This line is *on its own line*, because the previous line ends with two spaces. spaces. ``` -Become: +Becomes: Here's a line for us to start with. |