diff options
Diffstat (limited to 'doc')
106 files changed, 2411 insertions, 822 deletions
diff --git a/doc/README.md b/doc/README.md index 7d4f84857e0..5089e1e70f6 100644 --- a/doc/README.md +++ b/doc/README.md @@ -30,6 +30,7 @@ - [User permissions](ci/permissions/README.md) - [API](ci/api/README.md) - [Triggering builds through the API](ci/triggers/README.md) +- [Build artifacts](ci/build_artifacts/README.md) ### CI Languages @@ -53,6 +54,7 @@ - [Custom git hooks](hooks/custom_hooks.md) Custom git hooks (on the filesystem) for when web hooks aren't enough. - [Install](install/README.md) Requirements, directory structures and installation from source. +- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components - [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter. - [Issue closing](customization/issue_closing.md) Customize how to close an issue from commit messages. - [Libravatar](customization/libravatar.md) Use Libravatar for user avatars. @@ -67,6 +69,8 @@ - [Reply by email](incoming_email/README.md) Allow users to comment on issues and merge requests by replying to notification emails. - [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE. - [Git LFS configuration](workflow/lfs/lfs_administration.md) +- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast. +- [GitLab Performance Monitoring](monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics ## Contributor documentation diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index 1eb3a74d304..0faef526d43 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -17,6 +17,8 @@ DATABASE_URL | url | For example: postgresql://localhost/blog_development?pool=5 GITLAB_EMAIL_FROM | email | Email address used in the "From" field in mails sent by GitLab GITLAB_EMAIL_DISPLAY_NAME | string | Name used in the "From" field in mails sent by GitLab GITLAB_EMAIL_REPLY_TO | email | Email address used in the "Reply-To" field in mails sent by GitLab +GITLAB_UNICORN_MEMORY_MIN | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer +GITLAB_UNICORN_MEMORY_MAX | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer ## Complete database variables @@ -45,6 +47,7 @@ GITLAB_DATABASE_PORT | 5432 ## Adding more variables We welcome merge requests to make more settings configurable via variables. +Please make changes in the file config/initializers/1_settings.rb Please stick to the naming scheme "GITLAB_#{name 1_settings.rb in upper case}". ## Omnibus configuration diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md new file mode 100644 index 00000000000..a5fa7d358a2 --- /dev/null +++ b/doc/administration/housekeeping.md @@ -0,0 +1,22 @@ +# Housekeeping + +_**Note:** This feature was [introduced][ce-2371] in GitLab 8.4_ + +--- + +The housekeeping function runs `git gc` ([man page][man]) on the current +project Git repository. + +`git gc` runs a number of housekeeping tasks, such as compressing file +revisions (to reduce disk space and increase performance) and removing +unreachable objects which may have been created from prior invocations of +`git add`. + +You can find this option under your **[Project] > Settings**. + +--- + + + +[ce-2371]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2371 "Housekeeping merge request" +[man]: https://www.kernel.org/pub/software/scm/git/docs/git-gc.html "git gc man page" diff --git a/doc/administration/img/housekeeping_settings.png b/doc/administration/img/housekeeping_settings.png Binary files differnew file mode 100644 index 00000000000..f7c5bc44367 --- /dev/null +++ b/doc/administration/img/housekeeping_settings.png diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md new file mode 100644 index 00000000000..483060395dd --- /dev/null +++ b/doc/administration/restart_gitlab.md @@ -0,0 +1,145 @@ +# How to restart GitLab + +Depending on how you installed GitLab, there are different methods to restart +its service(s). + +If you want the TL;DR versions, jump to: + +- [Omnibus GitLab restart](#omnibus-gitlab-restart) +- [Omnibus GitLab reconfigure](#omnibus-gitlab-reconfigure) +- [Source installation restart](#installations-from-source) + +## Omnibus installations + +If you have used the [Omnibus packages][omnibus-dl] to install GitLab, then +you should already have `gitlab-ctl` in your `PATH`. + +`gitlab-ctl` interacts with the Omnibus packages and can be used to restart the +GitLab Rails application (Unicorn) as well as the other components, like: + +- GitLab Workhorse +- Sidekiq +- PostgreSQL (if you are using the bundled one) +- NGINX (if you are using the bundled one) +- Redis (if you are using the bundled one) +- [Mailroom][] +- Logrotate + +### Omnibus GitLab restart + +There may be times in the documentation where you will be asked to _restart_ +GitLab. In that case, you need to run the following command: + +```bash +sudo gitlab-ctl restart +``` + +The output should be similar to this: + +``` +ok: run: gitlab-workhorse: (pid 11291) 1s +ok: run: logrotate: (pid 11299) 0s +ok: run: mailroom: (pid 11306) 0s +ok: run: nginx: (pid 11309) 0s +ok: run: postgresql: (pid 11316) 1s +ok: run: redis: (pid 11325) 0s +ok: run: sidekiq: (pid 11331) 1s +ok: run: unicorn: (pid 11338) 0s +``` + +To restart a component separately, you can append its service name to the +`restart` command. For example, to restart **only** NGINX you would run: + +```bash +sudo gitlab-ctl restart nginx +``` + +To check the status of GitLab services, run: + +```bash +sudo gitlab-ctl status +``` + +Notice that all services say `ok: run`. + +Sometimes, components time out during the restart and sometimes they get stuck. +In that case, you can use `gitlab-ctl kill <service>` to send the `SIGKILL` +signal to the service, for example `sidekiq`. After that, a restart should +perform fine. + +As a last resort, you can try to +[reconfigure GitLab](#omnibus-gitlab-reconfigure) instead. + +### Omnibus GitLab reconfigure + +There may be times in the documentation where you will be asked to _reconfigure_ +GitLab. Remember that this method applies only for the Omnibus packages. + +Reconfigure Omnibus GitLab with: + +```bash +sudo gitlab-ctl reconfigure +``` + +Reconfiguring GitLab should occur in the event that something in its +configuration (`/etc/gitlab/gitlab.rb`) has changed. + +When you run this command, [Chef], the underlying configuration management +application that powers Omnibus GitLab, will make sure that all directories, +permissions, services, etc., are in place and in the same shape that they were +initially shipped. + +It will also restart GitLab components where needed, if any of their +configuration files have changed. + +If you manually edit any files in `/var/opt/gitlab` that are managed by Chef, +running reconfigure will revert the changes AND restart the services that +depend on those files. + +## Installations from source + +If you have followed the official installation guide to [install GitLab from +source][install], run the following command to restart GitLab: + +``` +sudo service gitlab restart +``` + +The output should be similar to this: + +``` +Shutting down GitLab Unicorn +Shutting down GitLab Sidekiq +Shutting down GitLab Workhorse +Shutting down GitLab MailRoom +... +GitLab is not running. +Starting GitLab Unicorn +Starting GitLab Sidekiq +Starting GitLab Workhorse +Starting GitLab MailRoom +... +The GitLab Unicorn web server with pid 28059 is running. +The GitLab Sidekiq job dispatcher with pid 28176 is running. +The GitLab Workhorse with pid 28122 is running. +The GitLab MailRoom email processor with pid 28114 is running. +GitLab and all its components are up and running. +``` + +This should restart Unicorn, Sidekiq, GitLab Workhorse and [Mailroom][] +(if enabled). The init service file that does all the magic can be found on +your server in `/etc/init.d/gitlab`. + +--- + +If you are using other init systems, like systemd, you can check the +[GitLab Recipes][gl-recipes] repository for some unofficial services. These are +**not** officially supported so use them at your own risk. + + +[omnibus-dl]: https://about.gitlab.com/downloads/ "Download the Omnibus packages" +[install]: ../install/installation.md "Documentation to install GitLab from source" +[mailroom]: ../incoming_email/README.md "Used for replying by email in GitLab issues and merge requests" +[chef]: https://www.chef.io/chef/ "Chef official website" +[src-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab "GitLab init service file" +[gl-recipes]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/init "GitLab Recipes repository" diff --git a/doc/api/README.md b/doc/api/README.md index 2fa177ff4dd..9f3ad126320 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,7 +1,13 @@ # GitLab API +Automate GitLab via a simple and powerful API. All definitions can be found +under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). + ## Resources +Documentation for various API resources can be found separately in the +following locations: + - [Users](users.md) - [Session](session.md) - [Projects](projects.md) including setting Webhooks @@ -27,16 +33,15 @@ - [Build triggers](build_triggers.md) - [Build Variables](build_variables.md) -## Clients - -Find API Clients for GitLab [on our website](https://about.gitlab.com/applications/#api-clients). -You can use [GitLab as an OAuth2 client](oauth2.md) to make API calls. +## Authentication -## Introduction +All API requests require authentication. You need to pass a `private_token` +parameter via query string or header. If passed as a header, the header name +must be `PRIVATE-TOKEN` (uppercase and with a dash instead of an underscore). +You can find or reset your private token in your account page (`/profile/account`). -All API requests require authentication. You need to pass a `private_token` parameter by URL or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile. - -If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401: +If `private_token` is invalid or omitted, then an error message will be +returned with status code `401`: ```json { @@ -44,71 +49,83 @@ If no, or an invalid, `private_token` is provided then an error message will be } ``` -API requests should be prefixed with `api` and the API version. The API version is defined in `lib/api.rb`. +API requests should be prefixed with `api` and the API version. The API version +is defined in [`lib/api.rb`][lib-api-url]. Example of a valid API request: -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U +```shell +GET https://gitlab.example.com/api/v3/projects?private_token=9koXpg98eAheJpvBs5tK ``` -Example for a valid API request using curl and authentication via header: +Example of a valid API request using cURL and authentication via header: -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects" +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" ``` -The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL. +The API uses JSON to serialize data. You don't need to specify `.json` at the +end of an API URL. ## Authentication with OAuth2 token -Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter. +Instead of the `private_token` you can transmit the OAuth2 access token as a +header or as a parameter. -### OAuth2 token (as a parameter) +Example of OAuth2 token as a parameter: -``` -curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN +```shell +curl https://gitlab.example.com/api/v3/user?access_token=OAUTH-TOKEN ``` -### OAuth2 token (as a header) +Example of OAuth2 token as a header: -``` -curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user +```shell +curl -H "Authorization: Bearer OAUTH-TOKEN" https://example.com/api/v3/user ``` Read more about [GitLab as an OAuth2 client](oauth2.md). ## Status codes -The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong, e.g. status code `400 Bad Request` is returned if a required attribute is missing from the request. The following list gives an overview of how the API functions generally behave. - -API request types: - -- `GET` requests access one or more resources and return the result as JSON -- `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON -- `GET`, `PUT` and `DELETE` return `200 OK` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON -- `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not. - -The following list shows the possible return codes for API requests. - -Return values: - -- `200 OK` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON -- `201 Created` - The `POST` request was successful and the resource is returned as JSON -- `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given -- `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above -- `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project -- `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found -- `405 Method Not Allowed` - The request is not supported -- `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists -- `422 Unprocessable` - The entity could not be processed -- `500 Server Error` - While handling the request something went wrong on the server side +The API is designed to return different status codes according to context and +action. This way, if a request results in an error, the caller is able to get +insight into what went wrong. + +The following table gives an overview of how the API functions generally behave. + +| Request type | Description | +| ------------ | ----------- | +| `GET` | Access one or more resources and return the result as JSON. | +| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | +| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. | +| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. | + +The following table shows the possible return codes for API requests. + +| Return values | Description | +| ------------- | ----------- | +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. | +| `201 Created` | The `POST` request was successful and the resource is returned as JSON. | +| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | +| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. | +| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. | +| `405 Method Not Allowed` | The request is not supported. | +| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. | +| `422 Unprocessable` | The entity could not be processed. | +| `500 Server Error` | While handling the request something went wrong server-side. | ## Sudo -All API requests support performing an api call as if you were another user, if your private token is for an administration account. You need to pass `sudo` parameter by URL or header with an id or username of the user you want to perform the operation as. If passed as header, the header name must be "SUDO" (capitals). +All API requests support performing an API call as if you were another user, +provided your private token is from an administrator account. You need to pass +the `sudo` parameter either via query string or a header with an ID/username of +the user you want to perform the operation as. If passed as a header, the +header name must be `SUDO` (uppercase). -If a non administrative `private_token` is provided then an error message will be returned with status code 403: +If a non administrative `private_token` is provided, then an error message will +be returned with status code `403`: ```json { @@ -116,7 +133,8 @@ If a non administrative `private_token` is provided then an error message will b } ``` -If the sudo user id or username cannot be found then an error message will be returned with status code 404: +If the sudo user ID or username cannot be found, an error message will be +returned with status code `404`: ```json { @@ -124,94 +142,181 @@ If the sudo user id or username cannot be found then an error message will be re } ``` -Example of a valid API with sudo request: +--- + +Example of a valid API call and a request using cURL with sudo request, +providing a username: +```shell +GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=username ``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username + +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: username" "https://gitlab.example.com/api/v3/projects" ``` +Example of a valid API call and a request using cURL with sudo request, +providing an ID: + +```shell +GET /projects?private_token=9koXpg98eAheJpvBs5tK&sudo=23 ``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23 + +```shell +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "SUDO: 23" "https://gitlab.example.com/api/v3/projects" ``` -Example for a valid API request with sudo using curl and authentication via header: +## Pagination + +Sometimes the returned result will span across many pages. When listing +resources you can pass the following parameters: +| Parameter | Description | +| --------- | ----------- | +| `page` | Page number (default: `1`) | +| `per_page`| Number of items to list per page (default: `20`, max: `100`) | + +In the example below, we list 50 [namespaces](namespaces.md) per page. + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/namespaces?per_page=50 ``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "http://example.com/api/v3/projects" + +### Pagination Link header + +[Link headers](http://www.w3.org/wiki/LinkHeader) are sent back with each +response. They have `rel` set to prev/next/first/last and contain the relevant +URL. Please use these links instead of generating your own URLs. + +In the cURL example below, we limit the output to 3 items per page (`per_page=3`) +and we request the second page (`page=2`) of [comments](notes.md) of the issue +with ID `8` which belongs to the project with ID `8`: + +```bash +curl -I -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/8/issues/8/notes?per_page=3&page=2 ``` +The response will then be: + ``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects" +HTTP/1.1 200 OK +Cache-Control: no-cache +Content-Length: 1103 +Content-Type: application/json +Date: Mon, 18 Jan 2016 09:43:18 GMT +Link: <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v3/projects/8/issues/8/notes?page=3&per_page=3>; rel="last" +Status: 200 OK +Vary: Origin +X-Next-Page: 3 +X-Page: 2 +X-Per-Page: 3 +X-Prev-Page: 1 +X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86 +X-Runtime: 0.108688 +X-Total: 8 +X-Total-Pages: 3 ``` -## Pagination +### Other pagination headers -When listing resources you can pass the following parameters: +Additional pagination headers are also sent back. -- `page` (default: `1`) - page number -- `per_page` (default: `20`, max: `100`) - number of items to list per page +| Header | Description | +| ------ | ----------- | +| `X-Total` | The total number of items | +| `X-Total-Pages` | The total number of pages | +| `X-Per-Page` | The number of items per page | +| `X-Page` | The index of the current page (starting at 1) | +| `X-Next-Page` | The index of the next page | +| `X-Prev-Page` | The index of the previous page | -[Link headers](http://www.w3.org/wiki/LinkHeader) are send back with each response. These have `rel` prev/next/first/last and contain the relevant URL. Please use these instead of generating your own URLs. +## `id` vs `iid` -## id vs iid +When you work with the API, you may notice two similar fields in API entities: +`id` and `iid`. The main difference between them is scope. -When you work with API you may notice two similar fields in api entities: id and iid. The main difference between them is scope. Example: +For example, an issue might have `id: 46` and `iid: 5`. -Issue: +| Parameter | Description | +| --------- | ----------- | +| `id` | Is unique across all issues and is used for any API call | +| `iid` | Is unique only in scope of a single project. When you browse issues or merge requests with the Web UI, you see the `iid` | - id: 46 - iid: 5 +That means that if you want to get an issue via the API you should use the `id`: -- id - is unique across all issues. It's used for any api call. -- iid - is unique only in scope of a single project. When you browse issues or merge requests with Web UI, you see iid. +```bash +GET /projects/42/issues/:id +``` -So if you want to get issue with api you use `http://host/api/v3/.../issues/:id.json`. But when you want to create a link to web page - use `http:://host/project/issues/:iid.json` +On the other hand, if you want to create a link to a web page you should use +the `iid`: + +```bash +GET /projects/42/issues/:iid +``` ## Data validation and error reporting -When working with the API you may encounter validation errors. In such case, the API will answer with an HTTP `400` status. +When working with the API you may encounter validation errors, in which case +the API will answer with an HTTP `400` status. + Such errors appear in two cases: -* A required attribute of the API request is missing, e.g. the title of an issue is not given -* An attribute did not pass the validation, e.g. user bio is too long +- A required attribute of the API request is missing, e.g., the title of an + issue is not given +- An attribute did not pass the validation, e.g., user bio is too long When an attribute is missing, you will get something like: - HTTP/1.1 400 Bad Request - Content-Type: application/json - - { - "message":"400 (Bad request) \"title\" not given" - } - -When a validation error occurs, error messages will be different. They will hold all details of validation errors: +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message":"400 (Bad request) \"title\" not given" +} +``` - HTTP/1.1 400 Bad Request - Content-Type: application/json +When a validation error occurs, error messages will be different. They will +hold all details of validation errors: - { - "message": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } +``` +HTTP/1.1 400 Bad Request +Content-Type: application/json +{ + "message": { + "bio": [ + "is too long (maximum is 255 characters)" + ] } +} +``` -This makes error messages more machine-readable. The format can be described as follow: +This makes error messages more machine-readable. The format can be described as +follows: - { - "message": { +```json +{ + "message": { + "<property-name>": [ + "<error-message>", + "<error-message>", + ... + ], + "<embed-entity>": { "<property-name>": [ "<error-message>", "<error-message>", ... ], - "<embed-entity>": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - } } } +} +``` + +## Clients + +There are many unofficial GitLab API Clients for most of the popular +programming languages. Visit the [GitLab website] for a complete list. + +[GitLab website]: https://about.gitlab.com/applications/#api-clients "Clients using the GitLab API" +[lib-api-url]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api/api.rb diff --git a/doc/api/branches.md b/doc/api/branches.md index 6a9c10c8520..abc4732c395 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -8,13 +8,21 @@ Get a list of repository branches from a project, sorted by name alphabetically. GET /projects/:id/repository/branches ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | -- `id` (required) - The ID of a project +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches +``` + +Example response: ```json [ { + "name": "master", + "protected": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -27,10 +35,9 @@ Parameters: "parent_ids": [ "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] - }, - "name": "master", - "protected": true - } + } + }, + ... ] ``` @@ -42,13 +49,21 @@ Get a single project repository branch. GET /projects/:id/repository/branches/:branch ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master +``` + +Example response: ```json { + "name": "master", + "protected": true, "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -61,25 +76,30 @@ Parameters: "parent_ids": [ "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] - }, - "name": "master", - "protected": true + } } ``` ## Protect repository branch -Protects a single project repository branch. This is an idempotent function, protecting an already -protected repository branch still returns a `200 OK` status code. +Protects a single project repository branch. This is an idempotent function, +protecting an already protected repository branch still returns a `200 OK` +status code. ``` PUT /projects/:id/repository/branches/:branch/protect ``` -Parameters: +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/protect +``` -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | + +Example response: ```json { @@ -103,17 +123,24 @@ Parameters: ## Unprotect repository branch -Unprotects a single project repository branch. This is an idempotent function, unprotecting an already -unprotected repository branch still returns a `200 OK` status code. +Unprotects a single project repository branch. This is an idempotent function, +unprotecting an already unprotected repository branch still returns a `200 OK` +status code. ``` PUT /projects/:id/repository/branches/:branch/unprotect ``` -Parameters: +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/repository/branches/master/unprotect +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +Example response: ```json { @@ -141,11 +168,17 @@ Parameters: POST /projects/:id/repository/branches ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch_name` | string | yes | The name of the branch | +| `ref` | string | yes | The branch name or commit SHA to create branch from | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches?branch_name=newbranch&ref=master" +``` -- `id` (required) - The ID of a project -- `branch_name` (required) - The name of the branch -- `ref` (required) - Create branch from commit SHA or existing branch +Example response: ```json { @@ -162,12 +195,13 @@ Parameters: "4ad91d3c1144c406e50c7b33bae684bd6837faf8" ] }, - "name": "master", + "name": "newbranch", "protected": false } ``` -It return 200 if succeed or 400 if failed with error message explaining reason. +It returns `200` if it succeeds or `400` if failed with an error message +explaining the reason. ## Delete repository branch @@ -175,18 +209,22 @@ It return 200 if succeed or 400 if failed with error message explaining reason. DELETE /projects/:id/repository/branches/:branch ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `branch` | string | yes | The name of the branch | -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch +It returns `200` if it succeeds, `404` if the branch to be deleted does not exist +or `400` for other reasons. In case of an error, an explaining message is provided. -It return 200 if succeed, 404 if the branch to be deleted does not exist -or 400 for other reasons. In case of an error, an explaining message is provided. +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/branches/newbranch" +``` -Success response: +Example response: ```json { - "branch_name": "my-removed-branch" + "branch_name": "newbranch" } ``` diff --git a/doc/api/builds.md b/doc/api/builds.md index ecb50754c88..6e64d096644 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -18,7 +18,7 @@ GET /projects/:id/builds ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds" ``` ### Example of response @@ -123,7 +123,7 @@ GET /projects/:id/repository/commits/:sha/builds ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds" ``` ### Example of response @@ -213,7 +213,7 @@ GET /projects/:id/builds/:build_id ### Example of request ``` -curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8" +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8" ``` ### Example of response @@ -277,7 +277,7 @@ POST /projects/:id/builds/:build_id/cancel ### Example of request ``` -curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel" ``` ### Example of response @@ -327,7 +327,7 @@ POST /projects/:id/builds/:build_id/retry ### Example of request ``` -curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry" ``` ### Example of response diff --git a/doc/api/commits.md b/doc/api/commits.md index 93d62b751e6..e4d436b8e52 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -8,10 +8,16 @@ Get a list of repository commits in a project. GET /projects/:id/repository/commits ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits" +``` -- `id` (required) - The ID of a project -- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch +Example response: ```json [ @@ -48,8 +54,16 @@ GET /projects/:id/repository/commits/:sha Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The commit hash or name of a repository branch or tag +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `sha` | string | yes | The commit hash or name of a repository branch or tag | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master +``` + +Example response: ```json { @@ -79,8 +93,16 @@ GET /projects/:id/repository/commits/:sha/diff Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The name of a repository branch or tag or if not given the default branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `sha` | string | yes | The commit hash or name of a repository branch or tag | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/diff" +``` + +Example response: ```json [ @@ -107,8 +129,16 @@ GET /projects/:id/repository/commits/:sha/comments Parameters: -- `id` (required) - The ID of a project -- `sha` (required) - The name of a repository branch or tag or if not given the default branch +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `sha` | string | yes | The commit hash or name of a repository branch or tag | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits/master/comments" +``` + +Example response: ```json [ @@ -128,39 +158,65 @@ Parameters: ## Post comment to commit -Adds a comment to a commit. Optionally you can post comments on a specific line of a commit. Therefor both `path`, `line_new` and `line_old` are required. +Adds a comment to a commit. + +In order to post a comment in a particular line of a particular file, you must +specify the full commit SHA, the `path`, the `line` and `line_type` should be +`new`. + +The comment will be added at the end of the last commit if at least one of the +cases below is valid: + +- the `sha` is instead a branch or a tag and the `line` or `path` are invalid +- the `line` number is invalid (does not exist) +- the `path` is invalid (does not exist) + +In any of the above cases, the response of `line`, `line_type` and `path` is +set to `null`. ``` POST /projects/:id/repository/commits/:sha/comments ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `sha` | string | yes | The commit SHA or name of a repository branch or tag | +| `note` | string | yes | The text of the comment | +| `path` | string | no | The file path relative to the repository | +| `line` | integer | no | The line number where the comment should be placed | +| `line_type` | string | no | The line type. Takes `new` or `old` as arguments | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "note=Nice picture man\!" -F "path=dudeism.md" -F "line=11" -F "line_type=new" https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments +``` -- `id` (required) - The ID of a project -- `sha` (required) - The name of a repository branch or tag or if not given the default branch -- `note` (required) - Text of comment -- `path` (optional) - The file path -- `line` (optional) - The line number -- `line_type` (optional) - The line type (new or old) +Example response: ```json { - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - }, - "note": "text1", - "path": "example.rb", - "line": 5, - "line_type": "new" + "author" : { + "web_url" : "https://gitlab.example.com/u/thedude", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "username" : "thedude", + "state" : "active", + "name" : "Jeff Lebowski", + "id" : 28 + }, + "created_at" : "2016-01-19T09:44:55.600Z", + "line_type" : "new", + "path" : "dudeism.md", + "line" : 11, + "note" : "Nice picture man!" } ``` -## Get the status of a commit +## Commit status + +Since GitLab 8.1, this is the new commit status API. The documentation in +[ci/api/commits](../ci/api/commits.md) is deprecated. + +### Get the status of a commit Get the statuses of a commit in a project. @@ -168,75 +224,116 @@ Get the statuses of a commit in a project. GET /projects/:id/repository/commits/:sha/statuses ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project +| `sha` | string | yes | The commit SHA +| `ref_name`| string | no | The name of a repository branch or tag or, if not given, the default branch +| `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test` +| `name` | string | no | Filter by [job name](../ci/yaml/README.md#jobs), e.g., `bundler:audit` +| `all` | boolean | no | Return all statuses, not only the latest ones + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses +``` -- `id` (required) - The ID of a project -- `sha` (required) - The commit SHA -- `ref` (optional) - Filter by ref name, it can be branch or tag -- `stage` (optional) - Filter by stage -- `name` (optional) - Filer by status name, eg. jenkins -- `all` (optional) - The flag to return all statuses, not only latest ones +Example response: ```json [ - { - "id": 13, - "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", - "ref": "test", - "status": "success", - "name": "ci/jenkins", - "target_url": "http://jenkins/project/url", - "description": "Jenkins success", - "created_at": "2015-10-12T09:47:16.250Z", - "started_at": "2015-10-12T09:47:16.250Z", - "finished_at": "2015-10-12T09:47:16.262Z", - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - } - } + ... + + { + "status" : "pending", + "created_at" : "2016-01-19T08:40:25.934Z", + "started_at" : null, + "name" : "bundler:audit", + "allow_failure" : true, + "author" : { + "username" : "thedude", + "state" : "active", + "web_url" : "https://gitlab.example.com/u/thedude", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "id" : 28, + "name" : "Jeff Lebowski" + }, + "description" : null, + "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8", + "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/91", + "finished_at" : null, + "id" : 91, + "ref" : "master" + }, + { + "started_at" : null, + "name" : "flay", + "allow_failure" : false, + "status" : "pending", + "created_at" : "2016-01-19T08:40:25.832Z", + "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/builds/90", + "id" : 90, + "finished_at" : null, + "ref" : "master", + "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8", + "author" : { + "id" : 28, + "name" : "Jeff Lebowski", + "username" : "thedude", + "web_url" : "https://gitlab.example.com/u/thedude", + "state" : "active", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png" + }, + "description" : null + }, + + ... ] ``` -## Post the status to commit +### Post the build status to a commit -Adds or updates a status of a commit. +Adds or updates a build status of a commit. ``` POST /projects/:id/statuses/:sha ``` -- `id` (required) - The ID of a project -- `sha` (required) - The commit SHA -- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled -- `ref` (optional) - The ref (branch or tag) to which the status refers -- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default" -- `target_url` (optional) - The target URL to associate with this status -- `description` (optional) - The short description of the status +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project +| `sha` | string | yes | The commit SHA +| `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` +| `ref` | string | no | The `ref` (branch or tag) to which the status refers +| `name` or `context` | string | no | The label to differentiate this status from the status of other systems. Default value is `default` +| `target_url` | string | no | The target URL to associate with this status +| `description` | string | no | The short description of the status + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success" +``` + +Example response: ```json { - "id": 13, - "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27", - "ref": "test", - "status": "success", - "name": "ci/jenkins", - "target_url": "http://jenkins/project/url", - "description": "Jenkins success", - "created_at": "2015-10-12T09:47:16.250Z", - "started_at": "2015-10-12T09:47:16.250Z", - "finished_at": "2015-10-12T09:47:16.262Z", - "author": { - "id": 1, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - } + "author" : { + "web_url" : "https://gitlab.example.com/u/thedude", + "name" : "Jeff Lebowski", + "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png", + "username" : "thedude", + "state" : "active", + "id" : 28 + }, + "name" : "default", + "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8", + "status" : "success", + "description" : null, + "id" : 93, + "target_url" : null, + "ref" : null, + "started_at" : null, + "created_at" : "2016-01-19T09:05:50.355Z", + "allow_failure" : false, + "finished_at" : "2016-01-19T09:05:50.365Z" } ``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index e4492fc609c..9da1fe22e61 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -8,9 +8,15 @@ Get a list of a project's deploy keys. GET /projects/:id/keys ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys" +``` -- `id` (required) - The ID of the project +Example response: ```json [ @@ -39,8 +45,16 @@ GET /projects/:id/keys/:key_id Parameters: -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `key_id` | integer | yes | The ID of the deploy key | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/11" +``` + +Example response: ```json { @@ -54,17 +68,34 @@ Parameters: ## Add deploy key Creates a new deploy key for a project. -If deploy key already exists in another project - it will be joined to project but only if original one was is accessible by same user + +If the deploy key already exists in another project, it will be joined to current +project only if original one was is accessible by the same user. ``` POST /projects/:id/keys ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `title` | string | yes | New deploy key's title | +| `key` | string | yes | New deploy key | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"title": "My deploy key", "key": "ssh-rsa AAAA..."}' "https://gitlab.example.com/api/v3/projects/5/keys/" +``` -- `id` (required) - The ID of the project -- `title` (required) - New deploy key's title -- `key` (required) - New deploy key +Example response: + +```json +{ + "key" : "ssh-rsa AAAA...", + "id" : 12, + "title" : "My deploy key", + "created_at" : "2015-08-29T12:44:31.550Z" +} +``` ## Delete deploy key @@ -74,7 +105,26 @@ Delete a deploy key from a project DELETE /projects/:id/keys/:key_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `key_id` | integer | yes | The ID of the deploy key | + +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/keys/13" +``` -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key +Example response: + +```json +{ + "updated_at" : "2015-08-29T12:50:57.259Z", + "key" : "ssh-rsa AAAA...", + "public" : false, + "title" : "My deploy key", + "user_id" : null, + "created_at" : "2015-08-29T12:50:57.259Z", + "fingerprint" : "6a:33:1f:74:51:c0:39:81:79:ec:7a:31:f8:40:20:43", + "id" : 13 +} +``` diff --git a/doc/api/groups.md b/doc/api/groups.md index 808675d8605..d47e79ba47f 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -33,6 +33,7 @@ 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
diff --git a/doc/api/issues.md b/doc/api/issues.md index d407bc35d79..9e704648b25 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,9 +1,20 @@ # Issues +Every API call to issues must be authenticated. + +If a user is not a member of a project and the project is private, a `GET` +request on that project will result to a `404` status code. + +## Issues pagination + +By default, `GET` requests return 20 results at a time because the API results +are paginated. + +Read more on [pagination](README.md#pagination). + ## List issues -Get all issues created by authenticated user. This function takes pagination parameters -`page` and `per_page` to restrict the list of issues. +Get all issues created by the authenticated user. ``` GET /issues @@ -14,81 +25,65 @@ GET /issues?labels=foo,bar GET /issues?labels=foo,bar&state=opened ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `state` | string | no | Return all issues or just those that are `opened` or `closed`| +| `labels` | string | no | Comma-separated list of label names | +| `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` | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/issues +``` -- `state` (optional) - Return `all` issues or just those that are `opened` or `closed` -- `labels` (optional) - Comma-separated list of label names -- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` +Example response: ```json [ - { - "id": 43, - "iid": 3, - "project_id": 8, - "title": "4xx/5xx pages", - "description": "", - "labels": [], - "milestone": null, - "assignee": null, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "closed", - "updated_at": "2012-07-02T17:53:12Z", - "created_at": "2012-07-02T17:53:12Z" - }, - { - "id": 42, - "iid": 4, - "project_id": 8, - "title": "Add user settings", - "description": "", - "labels": [ - "feature" - ], - "milestone": { - "id": 1, - "title": "v1.0", - "description": "", - "due_date": "2012-07-20", - "state": "reopened", - "updated_at": "2012-07-04T13:42:48Z", - "created_at": "2012-07-04T13:42:48Z" - }, - "assignee": { - "id": 2, - "username": "jack_smith", - "email": "jack@example.com", - "name": "Jack Smith", - "state": "active", - "created_at": "2012-05-23T08:01:01Z" - }, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "opened", - "updated_at": "2012-07-12T13:43:19Z", - "created_at": "2012-06-28T12:58:06Z" - } + { + "state" : "opened", + "description" : "Ratione dolores corrupti mollitia soluta quia.", + "author" : { + "state" : "active", + "id" : 18, + "web_url" : "https://gitlab.example.com/u/eileen.lowe", + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "username" : "eileen.lowe" + }, + "milestone" : { + "project_id" : 1, + "description" : "Ducimus nam enim ex consequatur cumque ratione.", + "state" : "closed", + "due_date" : null, + "iid" : 2, + "created_at" : "2016-01-04T15:31:39.996Z", + "title" : "v4.0", + "id" : 17, + "updated_at" : "2016-01-04T15:31:39.996Z" + }, + "project_id" : 1, + "assignee" : { + "state" : "active", + "id" : 1, + "name" : "Administrator", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root" + }, + "updated_at" : "2016-01-04T15:31:51.081Z", + "id" : 76, + "title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.", + "created_at" : "2016-01-04T15:31:51.081Z", + "iid" : 6, + "labels" : [] + }, ] ``` ## List project issues -Get a list of project issues. This function accepts pagination parameters `page` and `per_page` -to return the list of project issues. +Get a list of a project's issues. ``` GET /projects/:id/issues @@ -102,67 +97,123 @@ GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iid=42 ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `iid` | integer | no | Return the issue 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 | +| `milestone` | string| no | The milestone title | +| `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` | + + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues +``` + +Example response: -- `id` (required) - The ID of a project -- `iid` (optional) - Return the issue having the given `iid` -- `state` (optional) - Return `all` issues or just those that are `opened` or `closed` -- `labels` (optional) - Comma-separated list of label names -- `milestone` (optional) - Milestone title -- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` +```json +[ + { + "project_id" : 4, + "milestone" : { + "due_date" : null, + "project_id" : 4, + "state" : "closed", + "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid" : 3, + "id" : 11, + "title" : "v3.0", + "created_at" : "2016-01-04T15:31:39.788Z", + "updated_at" : "2016-01-04T15:31:39.788Z" + }, + "author" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "state" : "closed", + "iid" : 1, + "assignee" : { + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/u/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }, + "labels" : [], + "id" : 41, + "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at" : "2016-01-04T15:31:46.176Z", + "created_at" : "2016-01-04T15:31:46.176Z" + } +] +``` ## Single issue -Gets a single project issue. +Get a single project issue. ``` GET /projects/:id/issues/:issue_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id`| integer | yes | The ID of a project's issue | -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/41 +``` + +Example response: ```json { - "id": 42, - "iid": 3, - "project_id": 8, - "title": "Add user settings", - "description": "", - "labels": [ - "feature" - ], - "milestone": { - "id": 1, - "title": "v1.0", - "description": "", - "due_date": "2012-07-20", - "state": "closed", - "updated_at": "2012-07-04T13:42:48Z", - "created_at": "2012-07-04T13:42:48Z" - }, - "assignee": { - "id": 2, - "username": "jack_smith", - "email": "jack@example.com", - "name": "Jack Smith", - "state": "active", - "created_at": "2012-05-23T08:01:01Z" - }, - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "state": "opened", - "updated_at": "2012-07-12T13:43:19Z", - "created_at": "2012-06-28T12:58:06Z" + "project_id" : 4, + "milestone" : { + "due_date" : null, + "project_id" : 4, + "state" : "closed", + "description" : "Rerum est voluptatem provident consequuntur molestias similique ipsum dolor.", + "iid" : 3, + "id" : 11, + "title" : "v3.0", + "created_at" : "2016-01-04T15:31:39.788Z", + "updated_at" : "2016-01-04T15:31:39.788Z" + }, + "author" : { + "state" : "active", + "web_url" : "https://gitlab.example.com/u/root", + "avatar_url" : null, + "username" : "root", + "id" : 1, + "name" : "Administrator" + }, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "state" : "closed", + "iid" : 1, + "assignee" : { + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/u/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }, + "labels" : [], + "id" : 41, + "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", + "updated_at" : "2016-01-04T15:31:46.176Z", + "created_at" : "2016-01-04T15:31:46.176Z" } ``` @@ -170,57 +221,122 @@ Parameters: Creates a new project issue. +If the operation is successful, a status code of `200` and the newly-created +issue is returned. If an error occurs, an error number and a message explaining +the reason is returned. + ``` POST /projects/:id/issues ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues?title=Issues%20with%20auth&labels=bug +``` -- `id` (required) - The ID of a project -- `title` (required) - The title of an issue -- `description` (optional) - The description of an issue -- `assignee_id` (optional) - The ID of a user to assign issue -- `milestone_id` (optional) - The ID of a milestone to assign issue -- `labels` (optional) - Comma-separated label names for an issue +Example response: -If the operation is successful, 200 and the newly created issue is returned. -If an error occurs, an error number and a message explaining the reason is returned. +```json +{ + "project_id" : 4, + "id" : 84, + "created_at" : "2016-01-07T12:44:33.959Z", + "iid" : 14, + "title" : "Issues with auth", + "state" : "opened", + "assignee" : null, + "labels" : [ + "bug" + ], + "author" : { + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "state" : "active", + "web_url" : "https://gitlab.example.com/u/eileen.lowe", + "id" : 18, + "username" : "eileen.lowe" + }, + "description" : null, + "updated_at" : "2016-01-07T12:44:33.959Z", + "milestone" : null +} +``` ## Edit issue -Updates an existing project issue. This function is also used to mark an issue as closed. +Updates an existing project issue. This call is also used to mark an issue as +closed. + +If the operation is successful, a code of `200` and the updated issue is +returned. If an error occurs, an error number and a message explaining the +reason is returned. ``` PUT /projects/:id/issues/:issue_id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_id` | integer | yes | The ID of a project's issue | +| `title` | string | no | The title of an issue | +| `description` | string | no | The description of an issue | +| `assignee_id` | integer | no | The ID of a user to assign the issue to | +| `milestone_id` | integer | no | The ID of a milestone to assign the issue to | +| `labels` | string | no | Comma-separated label names for an issue | +| `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/4/issues/85?state_event=close +``` -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project's issue -- `title` (optional) - The title of an issue -- `description` (optional) - The description of an issue -- `assignee_id` (optional) - The ID of a user to assign issue -- `milestone_id` (optional) - The ID of a milestone to assign issue -- `labels` (optional) - Comma-separated label names for an issue -- `state_event` (optional) - The state event of an issue ('close' to close issue and 'reopen' to reopen it) +Example response: -If the operation is successful, 200 and the updated issue is returned. -If an error occurs, an error number and a message explaining the reason is returned. +```json +{ + "created_at" : "2016-01-07T12:46:01.410Z", + "author" : { + "name" : "Alexandra Bashirian", + "avatar_url" : null, + "username" : "eileen.lowe", + "id" : 18, + "state" : "active", + "web_url" : "https://gitlab.example.com/u/eileen.lowe" + }, + "state" : "closed", + "title" : "Issues with auth", + "project_id" : 4, + "description" : null, + "updated_at" : "2016-01-07T12:55:16.213Z", + "iid" : 15, + "labels" : [ + "bug" + ], + "id" : 85, + "assignee" : null, + "milestone" : null +} +``` ## Delete existing issue (**Deprecated**) -The function is deprecated and returns a `405 Method Not Allowed` error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with parameter `state_event` set to `close`. +This call is deprecated and returns a `405 Method Not Allowed` error if called. +An issue gets now closed and is done by calling +`PUT /projects/:id/issues/:issue_id` with the parameter `state_event` set to +`close`. See [edit issue](#edit-issue) for more details. ``` DELETE /projects/:id/issues/:issue_id ``` -Parameters: - -- `id` (required) - The project ID -- `issue_id` (required) - The ID of the issue - ## Comments on issues -Comments are done via the notes resource. +Comments are done via the [notes](notes.md) resource. diff --git a/doc/api/labels.md b/doc/api/labels.md index de41f35d284..6496ffe9fd1 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -2,83 +2,153 @@ ## List labels -Get all labels for given project. +Get all labels for a given project. ``` GET /projects/:id/labels ``` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/1/labels +``` + +Example response: + ```json [ - { - "name": "Awesome", - "color": "#DD10AA" - }, - { - "name": "Documentation", - "color": "#1E80DD" - }, - { - "name": "Feature", - "color": "#11FF22" - }, - { - "name": "Bug", - "color": "#EE1122" - } + { + "name" : "bug", + "color" : "#d9534f" + }, + { + "color" : "#d9534f", + "name" : "confirmed" + }, + { + "name" : "critical", + "color" : "#d9534f" + }, + { + "color" : "#428bca", + "name" : "discussion" + }, + { + "name" : "documentation", + "color" : "#f0ad4e" + }, + { + "color" : "#5cb85c", + "name" : "enhancement" + }, + { + "color" : "#428bca", + "name" : "suggestion" + }, + { + "color" : "#f0ad4e", + "name" : "support" + } ] ``` ## Create a new label -Creates a new label for given repository with given name and color. +Creates a new label for the given repository with the given name and color. + +It returns 200 if the label was successfully created, 400 for wrong parameters +and 409 if the label already exists. ``` POST /projects/:id/labels ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the label | +| `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign | + +```bash +curl --data "name=feature&color=#5843AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" +``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the label -- `color` (required) - Color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) +Example response: -It returns 200 and the newly created label, if the operation succeeds. -If the label already exists, 409 and an error message is returned. -If label parameters are invalid, 400 and an explaining error message is returned. +```json +{ + "name" : "feature", + "color" : "#5843AD" +} +``` ## Delete a label -Deletes a label given by its name. +Deletes a label with a given name. + +It returns 200 if the label was successfully deleted, 400 for wrong parameters +and 404 if the label does not exist. +In case of an error, an additional error message is returned. ``` DELETE /projects/:id/labels ``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the label to be deleted +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the label | -It returns 200 if the label successfully was deleted, 400 for wrong parameters -and 404 if the label does not exist. -In case of an error, additionally an error message is returned. +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels?name=bug" +``` + +Example response: + +```json +{ + "title" : "feature", + "color" : "#5843AD", + "updated_at" : "2015-11-03T21:22:30.737Z", + "template" : false, + "project_id" : 1, + "created_at" : "2015-11-03T21:22:30.737Z", + "id" : 9 +} +``` ## Edit an existing label -Updates an existing label with new name or now color. At least one parameter +Updates an existing label with new name or new color. At least one parameter is required, to update the label. +It returns 200 if the label was successfully deleted, 400 for wrong parameters +and 404 if the label does not exist. +In case of an error, an additional error message is returned. + ``` PUT /projects/:id/labels ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | +| `name` | string | yes | The name of the existing label | +| `new_name` | string | yes if `color` if not provided | The new name of the label | +| `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign | + +```bash +curl -X PUT --data "name=documentation&new_name=docs&color=#8E44AD" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" +``` -- `id` (required) - The ID of a project -- `name` (required) - The name of the existing label -- `new_name` (optional) - The new name of the label -- `color` (optional) - New color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) +Example response: -On success, this method returns 200 with the updated label. -If required parameters are missing or parameters are invalid, 400 is returned. -If the label to be updated is missing, 404 is returned. -In case of an error, additionally an error message is returned. +```json +{ + "color" : "#8E44AD", + "name" : "docs" +} +``` diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 8bc0a67067a..85ed31320b9 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -60,7 +60,7 @@ Parameters: Shows information about a single merge request. ``` -GET /projects/:id/merge_request/:merge_request_id +GET /projects/:id/merge_requests/:merge_request_id ``` Parameters: @@ -105,7 +105,7 @@ Parameters: Get a list of merge request commits. ``` -GET /projects/:id/merge_request/:merge_request_id/commits +GET /projects/:id/merge_requests/:merge_request_id/commits ``` Parameters: @@ -142,7 +142,7 @@ Parameters: Shows information about the merge request including its files and changes. ``` -GET /projects/:id/merge_request/:merge_request_id/changes +GET /projects/:id/merge_requests/:merge_request_id/changes ``` Parameters: @@ -264,7 +264,7 @@ If an error occurs, an error number and a message explaining the reason is retur Updates an existing merge request. You can change the target branch, title, or even close the MR. ``` -PUT /projects/:id/merge_request/:merge_request_id +PUT /projects/:id/merge_requests/:merge_request_id ``` Parameters: @@ -323,7 +323,7 @@ If merge request is already merged or closed - you get 405 and error message 'Me If you don't have permissions to accept this merge request - you'll get a 401 ``` -PUT /projects/:id/merge_request/:merge_request_id/merge +PUT /projects/:id/merge_requests/:merge_request_id/merge ``` Parameters: @@ -373,7 +373,7 @@ If the merge request is already merged or closed - you get 405 and error message In case the merge request is not set to be merged when the build succeeds, you'll also get a 406 error. ``` -PUT /projects/:id/merge_request/:merge_request_id/cancel_merge_when_build_succeeds +PUT /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_build_succeeds ``` Parameters: @@ -409,66 +409,6 @@ Parameters: } ``` -## Post comment to MR - -Adds a comment to a merge request. - -``` -POST /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request -- `note` (required) - Text of comment - -```json -{ - "note": "text1" -} -``` - -## Get the comments on a MR - -Gets all the comments associated with a merge request. - -``` -GET /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request - -```json -[ - { - "note": "this is the 1st comment on the 2merge merge request", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - }, - { - "note": "Status changed to closed", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - } -] -``` - ## Comments on merge requets -Comments are done via the notes resource. +Comments are done via the [notes](notes.md) resource. diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 7b3238441f6..42d9ce3d391 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,13 +1,29 @@ # Namespaces +Usernames and groupnames fall under a special category called namespaces. + +For users and groups supported API calls see the [users](users.md) and +[groups](groups.md) documentation respectively. + +[Pagination](README.md#pagination) is used. + ## List namespaces -Get a list of namespaces. (As user: my namespaces, as admin: all namespaces) +Get a list of the namespaces of the authenticated user. If the user is an +administrator, a list of all namespaces in the GitLab instance is shown. ``` GET /namespaces ``` +Example request: + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces +``` + +Example response: + ```json [ { @@ -23,22 +39,32 @@ GET /namespaces ] ``` -You can search for namespaces by name or path, see below. - ## Search for namespace -Get all namespaces that match your string in their name or path. +Get all namespaces that match a string in their name or path. ``` GET /namespaces?search=foobar ``` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `search` | string | no | Returns a list of namespaces the user is authorized to see based on the search criteria | + +Example request: + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/namespaces?search=twitter +``` + +Example response: + ```json [ { - "id": 1, - "path": "user1", - "kind": "user" + "id": 4, + "path": "twitter", + "kind": "group" } ] ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index 241229221db..3f372c955d2 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -29,6 +29,7 @@ GET /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 @@ -152,6 +153,7 @@ GET /projects/owned 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 @@ -167,6 +169,7 @@ GET /projects/starred 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 @@ -182,6 +185,7 @@ GET /projects/all 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 diff --git a/doc/api/settings.md b/doc/api/settings.md index 96867c67915..001de76c7af 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,67 +1,77 @@ # Application settings -This API allows you to read and modify GitLab instance application settings. +These API calls allow you to read and modify GitLab instance application +settings as appear in `/admin/application_settings`. You have to be an +administrator in order to perform this action. +## Get current application settings -## Get current application settings: +List the current application settings of the GitLab instance. ``` GET /application/settings ``` +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings +``` + +Example response: + ```json { - "id": 1, - "default_projects_limit": 10, - "signup_enabled": true, - "signin_enabled": true, - "gravatar_enabled": true, - "sign_in_text": "", - "created_at": "2015-06-12T15:51:55.432Z", - "updated_at": "2015-06-30T13:22:42.210Z", - "home_page_url": "", - "default_branch_protection": 2, - "twitter_sharing_enabled": true, - "restricted_visibility_levels": [], - "max_attachment_size": 10, - "session_expire_delay": 10080, - "default_project_visibility": 0, - "default_snippet_visibility": 0, - "restricted_signup_domains": [], - "user_oauth_applications": true, - "after_sign_out_path": "" + "default_projects_limit" : 10, + "signup_enabled" : true, + "id" : 1, + "default_branch_protection" : 2, + "restricted_visibility_levels" : [], + "signin_enabled" : true, + "twitter_sharing_enabled" : true, + "after_sign_out_path" : null, + "max_attachment_size" : 10, + "user_oauth_applications" : true, + "updated_at" : "2016-01-04T15:44:55.176Z", + "session_expire_delay" : 10080, + "home_page_url" : null, + "default_snippet_visibility" : 0, + "restricted_signup_domains" : [], + "created_at" : "2016-01-04T15:44:55.176Z", + "default_project_visibility" : 0, + "gravatar_enabled" : true, + "sign_in_text" : null } ``` -## Change application settings: - - +## Change application settings ``` PUT /application/settings ``` -Parameters: - -- `default_projects_limit` - project limit per user -- `signup_enabled` - enable registration -- `signin_enabled` - enable login via GitLab account -- `gravatar_enabled` - enable gravatar -- `sign_in_text` - text on login page -- `home_page_url` - redirect to this URL when not logged in -- `default_branch_protection` - determine if developers can push to master -- `twitter_sharing_enabled` - allow users to share project creation in twitter -- `restricted_visibility_levels` - restrict certain visibility levels -- `max_attachment_size` - limit attachment size -- `session_expire_delay` - session lifetime -- `default_project_visibility` - what visibility level new project receives -- `default_snippet_visibility` - what visibility level new snippet receives -- `restricted_signup_domains` - force people to use only corporate emails for signup -- `user_oauth_applications` - allow users to create oauth applications -- `after_sign_out_path` - where redirect user after logout +| Attribute | Type | Required | Description | +| --------- | ---- | :------: | ----------- | +| `default_projects_limit` | integer | no | Project limit per user. Default is `10` | +| `signup_enabled` | boolean | no | Enable registration. Default is `true`. | +| `signin_enabled` | boolean | no | Enable login via a GitLab account. Default is `true`. | +| `gravatar_enabled` | boolean | no | Enable Gravatar | +| `sign_in_text` | string | no | Text on login page | +| `home_page_url` | string | no | Redirect to this URL when not logged in | +| `default_branch_protection` | integer | no | Determine if developers can push to master. Can take `0` _(not protected, both developers and masters can push new commits, force push or delete the branch)_, `1` _(partially protected, developers can push new commits, but cannot force push or delete the branch, masters can do anything)_ or `2` _(fully protected, developers cannot push new commits, force push or delete the branch, masters can do anything)_ as a parameter. Default is `1`. | +| `twitter_sharing_enabled` | boolean | no | Allow users to share project creation on Twitter | +| `restricted_visibility_levels` | array of integers | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is null which means there is no restriction. | +| `max_attachment_size` | integer | no | Limit attachment size in MB | +| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | +| `default_project_visibility` | integer | no | What visibility level new projects receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.| +| `default_snippet_visibility` | integer | no | What visibility level new snippets receive. Can take `0` _(Private)_, `1` _(Internal)_ and `2` _(Public)_ as a parameter. Default is `0`.| +| `restricted_signup_domains` | array of strings | no | Force people to use only corporate emails for sign-up. Default is null, meaning there is no restriction. | +| `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider | +| `after_sign_out_path` | string | no | Where to redirect users after logout | -All parameters are optional. You can send only one that you want to change. +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/application/settings?signup_enabled=false&default_project_visibility=1 +``` +Example response: ```json { @@ -79,7 +89,7 @@ All parameters are optional. You can send only one that you want to change. "restricted_visibility_levels": [], "max_attachment_size": 10, "session_expire_delay": 10080, - "default_project_visibility": 0, + "default_project_visibility": 1, "default_snippet_visibility": 0, "restricted_signup_domains": [], "user_oauth_applications": true, diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index f9637d8a6c4..dc036d7e27f 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,40 +1,71 @@ # System hooks -All methods require admin authorization. +All methods require administrator authorization. -The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks). +The URL endpoint of the system hooks can also be configured using the UI in +the admin area under **Hooks** (`/admin/hooks`). + +Read more about [system hooks](../system_hooks/system_hooks.md). ## List system hooks -Get list of system hooks +Get a list of all system hooks. + +--- ``` GET /hooks ``` -Parameters: +Example request: + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks +``` -- **none** +Example response: ```json [ - { - "id": 3, - "url": "http://example.com/hook", - "created_at": "2013-10-02T10:15:31Z" - } + { + "id" : 1, + "url" : "https://gitlab.example.com/hook", + "created_at" : "2015-11-04T20:07:35.874Z" + } ] ``` -## Add new system hook hook +## Add new system hook + +Add a new system hook. + +--- ``` POST /hooks ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `url` | string | yes | The hook URL | + +Example request: + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/hooks?url=https://gitlab.example.com/hook" +``` + +Example response: -- `url` (required) - The hook URL +```json +[ + { + "id" : 2, + "url" : "https://gitlab.example.com/hook", + "created_at" : "2015-11-04T20:07:35.874Z" + } +] +``` ## Test system hook @@ -42,29 +73,68 @@ Parameters: GET /hooks/:id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the hook | -- `id` (required) - The ID of hook +Example request: + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 +``` + +Example response: ```json { - "event_name": "project_create", - "name": "Ruby", - "path": "ruby", - "project_id": 1, - "owner_name": "Someone", - "owner_email": "example@gitlabhq.com" + "project_id" : 1, + "owner_email" : "example@gitlabhq.com", + "owner_name" : "Someone", + "name" : "Ruby", + "path" : "ruby", + "event_name" : "project_create" } ``` ## Delete system hook -Deletes a system hook. This is an idempotent API function and returns `200 OK` even if the hook is not available. If the hook is deleted it is also returned as JSON. +Deletes a system hook. This is an idempotent API function and returns `200 OK` +even if the hook is not available. + +If the hook is deleted, a JSON object is returned. An error is raised if the +hook is not found. + +--- ``` DELETE /hooks/:id ``` -Parameters: +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the hook | + +Example request: -- `id` (required) - The ID of hook +```bash +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/hooks/2 +``` + +Example response: + +```json +{ + "note_events" : false, + "project_id" : null, + "enable_ssl_verification" : true, + "url" : "https://gitlab.example.com/hook", + "updated_at" : "2015-11-04T20:12:15.931Z", + "issues_events" : false, + "merge_requests_events" : false, + "created_at" : "2015-11-04T20:12:15.931Z", + "service_id" : null, + "id" : 2, + "push_events" : true, + "tag_push_events" : false +} +``` diff --git a/doc/ci/README.md b/doc/ci/README.md index 4cdd2e1ad33..5886829be51 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -12,6 +12,7 @@ * [Using Variables](variables/README.md) * [Using SSH keys](ssh_keys/README.md) * [Triggering builds through the API](triggers/README.md) +* [Build artifacts](build_artifacts/README.md) ### Languages diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md index 3b5008ccdb4..018ca22dbbd 100644 --- a/doc/ci/api/builds.md +++ b/doc/ci/api/builds.md @@ -18,18 +18,62 @@ Returns: ```json { - "id" : 79, - "commands" : "", - "path" : "", - "ref" : "", - "sha" : "", - "project_id" : 6, - "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", - "before_sha" : "" + "id": 48584, + "ref": "0.1.1", + "tag": true, + "sha": "d63117656af6ff57d99e50cc270f854691f335ad", + "status": "success", + "name": "pages", + "token": "9dd60b4f1a439d1765357446c1084c", + "stage": "test", + "project_id": 479, + "project_name": "test", + "commands": "echo commands", + "repo_url": "http://gitlab-ci-token:token@gitlab.example/group/test.git", + "before_sha": "0000000000000000000000000000000000000000", + "allow_git_fetch": false, + "options": { + "image": "docker:image", + "artifacts": { + "paths": [ + "public" + ] + }, + "cache": { + "paths": [ + "vendor" + ] + } + }, + "timeout": 3600, + "variables": [ + { + "key": "CI_BUILD_TAG", + "value": "0.1.1", + "public": true + } + ], + "depends_on_builds": [ + { + "id": 48584, + "ref": "0.1.1", + "tag": true, + "sha": "d63117656af6ff57d99e50cc270f854691f335ad", + "status": "success", + "name": "build", + "token": "9dd60b4f1a439d1765357446c1084c", + "stage": "build", + "project_id": 479, + "project_name": "test", + "artifacts_file": { + "filename": "artifacts.zip", + "size": 0 + } + } + ] } ``` - ### Update details of an existing build PUT /ci/builds/:id diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md index 4df7afc6c52..871de7abcce 100644 --- a/doc/ci/api/commits.md +++ b/doc/ci/api/commits.md @@ -1,5 +1,12 @@ # Commits API +**DEPRECATED** + +Since GitLab 8.1, there is a new commit status API. Please see the [revised +documentation](../../api/commits.md#commit-status). + +--- + __Authentication is done by GitLab CI project token__ ## Commits diff --git a/doc/ci/build_artifacts/README.md b/doc/ci/build_artifacts/README.md new file mode 100644 index 00000000000..71db5aa5dc8 --- /dev/null +++ b/doc/ci/build_artifacts/README.md @@ -0,0 +1,176 @@ +# Introduction to build artifacts + +Artifacts is a list of files and directories which are attached to a build +after it completes successfully. + +Since GitLab 8.2 and [GitLab Runner] 0.7.0, build artifacts that are created by +GitLab Runner are uploaded to GitLab and are downloadable as a single archive +(`tar.gz`) using the GitLab UI. + +Starting from GitLab 8.4 and GitLab Runner 1.0, the artifacts archive format +changed to `ZIP`, and it is now possible to browse its contents, with the added +ability of downloading the files separately. + +**Note:** +The artifacts browser will be available only for new artifacts that are sent +to GitLab using GitLab Runner version 1.0 and up. It will not be possible to +browse old artifacts already uploaded to GitLab. + +## Enabling build artifacts + +_If you are searching for ways to use artifacts, jump to +[Defining artifacts in `.gitlab-ci.yml`](#defining-artifacts-in-gitlab-ciyml)._ + +The artifacts feature is enabled by default in all GitLab installations. +To disable it site-wide, follow the steps below. + +--- + +**In Omnibus installations:** + +1. Edit `/etc/gitlab/gitlab.rb` and add the following line: + + ```ruby + gitlab_rails['artifacts_enabled'] = false + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**In installations from source:** + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: + + ```yaml + artifacts: + enabled: false + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + +## Defining artifacts in `.gitlab-ci.yml` + +A simple example of using the artifacts definition in `.gitlab-ci.yml` would be +the following: + +```yaml +pdf: + script: xelatex mycv.tex + artifacts: + paths: + - mycv.pdf +``` + +A job named `pdf` calls the `xelatex` command in order to build a pdf file from +the latex source file `mycv.tex`. We then define the `artifacts` paths which in +turn are defined with the `paths` keyword. All paths to files and directories +are relative to the repository that was cloned during the build. + +For more examples on artifacts, follow the +[separate artifacts yaml documentation](../yaml/README.md#artifacts). + +## Storing build artifacts + +After a successful build, GitLab Runner uploads an archive containing the build +artifacts to GitLab. + +To change the location where the artifacts are stored, follow the steps below. + +--- + +**In Omnibus installations:** + +_The artifacts are stored by default in +`/var/opt/gitlab/gitlab-rails/shared/artifacts`._ + +1. To change the storage path for example to `/mnt/storage/artifacts`, edit + `/etc/gitlab/gitlab.rb` and add the following line: + + ```ruby + gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts" + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**In installations from source:** + +_The artifacts are stored by default in +`/home/git/gitlab/shared/artifacts`._ + +1. To change the storage path for example to `/mnt/storage/artifacts`, edit + `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: + + ```yaml + artifacts: + enabled: true + path: /mnt/storage/artifacts + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + +## Browsing build artifacts + +When GitLab receives an artifacts archive, an archive metadata file is also +generated. This metadata file describes all the entries that are located in the +artifacts archive itself. The metadata file is in a binary format, with +additional GZIP compression. + +GitLab does not extract the artifacts archive in order to save space, memory +and disk I/O. It instead inspects the metadata file which contains all the +relevant information. This is especially important when there is a lot of +artifacts, or an archive is a very large file. + +--- + +After a successful build, if you visit the build's specific page, you can see +that there are two buttons. + +One is for downloading the artifacts archive and the other for browsing its +contents. + + + +--- + +The archive browser shows the name and the actual file size of each file in the +archive. If your artifacts contained directories, then you are also able to +browse inside them. + +Below you can see an image of three different file formats, as well as two +directories. + + + +--- + +## Downloading build artifacts + +If you need to download the whole archive, there are buttons in various places +inside GitLab that make that possible. + +1. While on the builds page, you can see the download icon for each build's + artifacts archive in the right corner + +1. While inside a specific build, you are presented with a download button + along with the one that browses the archive + +1. And finally, when browsing an archive you can see the download button at + the top right corner + +--- + +Note that GitLab does not extract the entire artifacts archive to send just a +single file to the user. + +When clicking on a specific file, [GitLab Workhorse] extracts it from the +archive and the download begins. + +This implementation saves space, memory and disk I/O. + +[gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner "GitLab Runner repository" +[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation" +[restart gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation" +[gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository" diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser.png b/doc/ci/build_artifacts/img/build_artifacts_browser.png Binary files differnew file mode 100644 index 00000000000..73ed4eeb927 --- /dev/null +++ b/doc/ci/build_artifacts/img/build_artifacts_browser.png diff --git a/doc/ci/build_artifacts/img/build_artifacts_browser_button.png b/doc/ci/build_artifacts/img/build_artifacts_browser_button.png Binary files differnew file mode 100644 index 00000000000..f5d15bc3e7d --- /dev/null +++ b/doc/ci/build_artifacts/img/build_artifacts_browser_button.png diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index e52e1547461..c1bb47e4291 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -56,12 +56,12 @@ gitlab-ci-multi-runner register \ --non-interactive \ --url "https://gitlab.com/ci/" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ - --description "ruby-2.1" \ + --description "ruby-2.2" \ --executor "docker" \ - --docker-image ruby:2.1 \ + --docker-image ruby:2.2 \ --docker-postgres latest ``` -With the command above, you create a runner that uses [ruby:2.1](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database. +With the command above, you create a runner that uses [ruby:2.2](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database. To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password. diff --git a/doc/ci/languages/php.md b/doc/ci/languages/php.md index dacb67fa3ff..77f9fae5bb6 100644 --- a/doc/ci/languages/php.md +++ b/doc/ci/languages/php.md @@ -12,7 +12,7 @@ configuration from the developer. To overcome this we will be using the official [PHP docker image][php-hub] that can be found in Docker Hub. This will allow us to test PHP projects against different versions of PHP. -However, not everything is plug 'n' play, you still need to onfigure some +However, not everything is plug 'n' play, you still need to configure some things manually. As with every build, you need to create a valid `.gitlab-ci.yml` describing the diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index b99ea25a3fe..862cacda586 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -56,7 +56,7 @@ export CI_SERVER_VERSION="" ``` ### YAML-defined variables -**This feature requires GitLab Runner 0.5.0 or higher** +**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 build environment. The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fd0d49de4e4..4d280297dbb 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -33,7 +33,7 @@ The YAML syntax allows for using more complex job specifications than in the above example: ```yaml -image: ruby:2.1 +image: ruby:2.2 services: - postgres @@ -135,10 +135,9 @@ thus allowing to fine tune them. ### cache `cache` is used to specify a list of files and directories which should be -cached between builds. Caches are stored according to the branch/ref and the -job name. They are not currently shared between different job names or between -branches/refs, which means that caching will benefit you if you push subsequent -commits to an existing feature branch. +cached between builds. + +**By default the caching is enabled per-job and per-branch.** If `cache` is defined outside the scope of the jobs, it means it is set globally and all jobs will use its definition. @@ -152,6 +151,64 @@ cache: - binaries/ ``` +#### cache:key + +_**Note:** Introduced in GitLab Runner v1.0.0._ + +The `key` directive allows you to define the affinity of caching +between jobs, allowing to have a single cache for all jobs, +cache per-job, cache per-branch or any other way you deem proper. + +This allows you to fine tune caching, allowing you to cache data between +different jobs or even different branches. + +The `cache:key` variable can use any of the [predefined variables](../variables/README.md). + +--- + +**Example configurations** + +To enable per-job caching: + +```yaml +cache: + key: "$CI_BUILD_NAME" + untracked: true +``` + +To enable per-branch caching: + +```yaml +cache: + key: "$CI_BUILD_REF_NAME" + untracked: true +``` + +To enable per-job and per-branch caching: + +```yaml +cache: + key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME" + untracked: true +``` + +To enable per-branch and per-stage caching: + +```yaml +cache: + key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME" + untracked: true +``` + +If you use **Windows Batch** to run your shell scripts you need to replace +`$` with `%`: + +```yaml +cache: + key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%" + untracked: true +``` + ## Jobs `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job diff --git a/doc/development/ci_setup.md b/doc/development/ci_setup.md index f9b48868182..05db30b4a7e 100644 --- a/doc/development/ci_setup.md +++ b/doc/development/ci_setup.md @@ -26,7 +26,7 @@ We use [these build scripts](https://gitlab.com/gitlab-org/gitlab-ci/blob/master # Build configuration on [Semaphore](https://semaphoreapp.com/gitlabhq/gitlabhq/) for testing the [GitHub.com repo](https://github.com/gitlabhq/gitlabhq) - Language: Ruby -- Ruby version: 2.1.2 +- Ruby version: 2.2.4 - database.yml: pg Build commands diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index 0bd32b78201..caaa4032db2 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -103,6 +103,23 @@ Inside the document: `_**Note:** This feature was introduced in GitLab EE 8.3_`. Otherwise, leave this mention out +## References + +- **GitLab Restart:** + There are many cases that a restart/reconfigure of GitLab is required. To + avoid duplication, link to the special document that can be found in + [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will + read like: + + ``` + Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) + for the changes to take effect. + ``` + If the document you are editing resides in a place other than the GitLab CE/EE + `doc/` directory, instead of the relative link, use the full path: + `http://doc.gitlab.com/ce/administration/restart_gitlab.html`. + Replace `reconfigure` with `restart` where appropriate. + ## API Here is a list of must-have items. Use them in the exact order that appears @@ -229,3 +246,4 @@ curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -d "restricted_signup_domai [cURL]: http://curl.haxx.se/ "cURL website" [single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html [gfm]: http://doc.gitlab.com/ce/markdown/markdown.html#newlines "GitLab flavored markdown documentation" +[doc-restart]: ../administration/restart_gitlab.md "GitLab restart documentation" diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md index 513ad69ec26..e51ff5a5de2 100644 --- a/doc/install/database_mysql.md +++ b/doc/install/database_mysql.md @@ -8,7 +8,7 @@ We do not recommend using MySQL due to various issues. For example, case [(in)se # Install the database packages sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev - + # Ensure you have MySQL version 5.5.14 or later mysql --version @@ -31,7 +31,7 @@ We do not recommend using MySQL due to various issues. For example, case [(in)se # Ensure you can use the InnoDB engine which is necessary to support long indexes # If this fails, check your MySQL config files (e.g. `/etc/mysql/*.cnf`, `/etc/mysql/conf.d/*`) for the setting "innodb = off" mysql> SET storage_engine=INNODB; - + # Create the GitLab production database mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_unicode_ci`; @@ -52,3 +52,25 @@ We do not recommend using MySQL due to various issues. For example, case [(in)se mysql> \q # You are done installing the database and can go back to the rest of the installation. + +## MySQL strings limits + +After installation or upgrade, remember to run the `add_limits_mysql` Rake task: + +``` +bundle exec rake add_limits_mysql +``` + +The `text` type in MySQL has a different size limit than the `text` type in +PostgreSQL. In MySQL `text` columns are limited to ~65kB, whereas in PostgreSQL +`text` columns are limited up to ~1GB! + +The `add_limits_mysql` Rake task converts some important `text` columns in the +GitLab database to `longtext` columns, which can persist values of up to 4GB +(sometimes less if the value contains multibyte characters). + +Details can be found in the [PostgreSQL][postgres-text-type] and +[MySQL][mysql-text-types] manuals. + +[postgres-text-type]: http://www.postgresql.org/docs/9.1/static/datatype-character.html +[mysql-text-types]: http://dev.mysql.com/doc/refman/5.7/en/string-type-overview.html diff --git a/doc/install/installation.md b/doc/install/installation.md index 00030729a4b..2cc2dbef41b 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -107,18 +107,25 @@ Then select 'Internet Site' and press enter to confirm the hostname. ## 2. Ruby -The use of Ruby version managers such as [RVM](https://rvm.io/), [rbenv](https://github.com/sstephenson/rbenv) or [chruby](https://github.com/postmodern/chruby) with GitLab in production frequently leads to hard to diagnose problems. For example, GitLab Shell is called from OpenSSH and having a version manager can prevent pushing and pulling over SSH. Version managers are not supported and we strongly advise everyone to follow the instructions below to use a system Ruby. +_**Note:** The current supported Ruby versions are 2.1.x and 2.2.x. Ruby 2.3 is +currently not supported._ -Remove the old Ruby 1.8 if present +The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab +in production, frequently leads to hard to diagnose problems. For example, +GitLab Shell is called from OpenSSH, and having a version manager can prevent +pushing and pulling over SSH. Version managers are not supported and we strongly +advise everyone to follow the instructions below to use a system Ruby. + +Remove the old Ruby 1.8 if present: sudo apt-get remove ruby1.8 Download Ruby and compile it: mkdir /tmp/ruby && cd /tmp/ruby - curl -O --progress https://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.7.tar.gz - echo 'e2e195a4a58133e3ad33b955c829bb536fa3c075 ruby-2.1.7.tar.gz' | shasum -c - && tar xzf ruby-2.1.7.tar.gz - cd ruby-2.1.7 + curl -O --progress https://cache.ruby-lang.org/pub/ruby/2.2/ruby-2.2.4.tar.gz + echo 'e2e195a4a58133e3ad33b955c829bb536fa3c075 ruby-2.2.4.tar.gz' | shasum -c - && tar xzf ruby-2.2.4.tar.gz + cd ruby-2.2.4 ./configure --disable-install-rdoc make sudo make install @@ -348,7 +355,7 @@ GitLab Shell is an SSH access and repository management software developed speci 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 0.5.4 + sudo -u git -H git checkout 0.6.2 sudo -u git -H make ### Initialize Database and Activate Advanced Features @@ -555,3 +562,7 @@ this is likely due to an outdated Nginx or Apache configuration, or a missing or misconfigured gitlab-workhorse instance. Double-check that you've [installed Go](#3-go), [installed gitlab-workhorse](#install-gitlab-workhorse), and correctly [configured Nginx](#site-configuration). + +[RVM]: https://rvm.io/ "RVM Homepage" +[rbenv]: https://github.com/sstephenson/rbenv "rbenv on GitHub" +[chruby]: https://github.com/postmodern/chruby "chruby on GitHub" diff --git a/doc/install/requirements.md b/doc/install/requirements.md index c0ccdd37458..006dae8ca9a 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -32,15 +32,17 @@ Please consider using a virtual machine to run GitLab. ## Ruby versions -GitLab requires Ruby (MRI) 2.1 +GitLab requires Ruby (MRI) 2.1.x or 2.2.x and currently does not work with version 2.3. + You will have to use the standard MRI implementation of Ruby. -We love [JRuby](http://jruby.org/) and [Rubinius](http://rubini.us/) but GitLab needs several Gems that have native extensions. +We love [JRuby](http://jruby.org/) and [Rubinius](http://rubini.us/) but GitLab +needs several Gems that have native extensions. ## Hardware requirements ### Storage -The necessary hard drive space largely depends on the size of the repos you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repos combined take up. +The necessary hard drive space largely depends on the size of the repos you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repos combined take up. If you want to be flexible about growing your hard drive space in the future consider mounting it using LVM so you can add more hard drives when you need them. @@ -109,4 +111,4 @@ On a very active server (10,000 active users) the Sidekiq process can use 1GB+ o - Firefox (Latest released version and [latest ESR version](https://www.mozilla.org/en-US/firefox/organizations/)) - Safari 7+ (known problem: required fields in html5 do not work) - Opera (Latest released version) -- Internet Explorer (IE) 10+ but please make sure that you have the `Compatibility View` mode disabled.
\ No newline at end of file +- Internet Explorer (IE) 10+ but please make sure that you have the `Compatibility View` mode disabled. diff --git a/doc/integration/README.md b/doc/integration/README.md index 5edac746c7b..83116bc8370 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -5,10 +5,10 @@ trackers and external authentication. See the documentation below for details on how to configure these services. -- [Jira](jira.md) Integrate with the JIRA issue tracker +- [Jira](../project_services/jira.md) Integrate with the JIRA issue tracker - [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. - [LDAP](ldap.md) Set up sign in via LDAP -- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab, and Google via OAuth. +- [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd and Azure - [SAML](saml.md) Configure GitLab as a SAML 2.0 Service Provider - [CAS](cas.md) Configure GitLab to sign in using CAS - [Slack](slack.md) Integrate with the Slack chat service diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 3543a67dd49..a2d7e922aad 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -19,7 +19,7 @@ To enable an external issue tracker you must configure the appropriate **Service Visit the links below for details: - [Redmine](../project_services/redmine.md) -- [Jira](jira.md) +- [Jira](../project_services/jira.md) ### Service Template diff --git a/doc/integration/facebook.md b/doc/integration/facebook.md index bc1f1673086..77bb75cbfca 100644 --- a/doc/integration/facebook.md +++ b/doc/integration/facebook.md @@ -19,7 +19,7 @@ something else descriptive. 1. Enter the address of your GitLab installation at the bottom of the package -  +  1. Choose "Next" @@ -29,7 +29,7 @@ something else descriptive. 1. Fill in a contact email for your app -  +  1. Choose "Save Changes" @@ -45,7 +45,7 @@ something else descriptive. 1. You should now see an app key and app secret (see screenshot). Keep this page open as you continue configuration. -  +  1. On your GitLab server, open the configuration file. diff --git a/doc/integration/github.md b/doc/integration/github.md index a789d2c814f..886784a27c9 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -22,7 +22,7 @@ GitHub will generate an application ID and secret key for you to use. 1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). Keep this page open as you continue configuration. -  +  1. On your GitLab server, open the configuration file. diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md index 80e3c0142a0..b215cc7c609 100644 --- a/doc/integration/gitlab.md +++ b/doc/integration/gitlab.md @@ -28,7 +28,7 @@ GitLab.com will generate an application ID and secret key for you to use. 1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). Keep this page open as you continue configuration. -  +  1. On your GitLab server, open the configuration file. diff --git a/doc/integration/gmail_action_buttons_for_gitlab.md b/doc/integration/gmail_action_buttons_for_gitlab.md index de45f25ad62..05a91d9bef9 100644 --- a/doc/integration/gmail_action_buttons_for_gitlab.md +++ b/doc/integration/gmail_action_buttons_for_gitlab.md @@ -4,7 +4,7 @@ GitLab supports [Google actions in email](https://developers.google.com/gmail/ma If correctly setup, emails that require an action will be marked in Gmail. - + To get this functioning, you need to be registered with Google. [See how to register with Google in this document.](https://developers.google.com/gmail/markup/registering-with-google) diff --git a/doc/integration/google.md b/doc/integration/google.md index 91e9b2495cc..f9a20dd840d 100644 --- a/doc/integration/google.md +++ b/doc/integration/google.md @@ -25,7 +25,7 @@ To enable the Google OAuth2 OmniAuth provider you must register your application - Application type: "Web Application" - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' -1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration.  +1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration.  1. On your GitLab server, open the configuration file. diff --git a/doc/integration/facebook_api_keys.png b/doc/integration/img/facebook_api_keys.png Binary files differindex d6c44ac0f11..d6c44ac0f11 100644 --- a/doc/integration/facebook_api_keys.png +++ b/doc/integration/img/facebook_api_keys.png diff --git a/doc/integration/facebook_app_settings.png b/doc/integration/img/facebook_app_settings.png Binary files differindex 30dd21e198a..30dd21e198a 100644 --- a/doc/integration/facebook_app_settings.png +++ b/doc/integration/img/facebook_app_settings.png diff --git a/doc/integration/facebook_website_url.png b/doc/integration/img/facebook_website_url.png Binary files differindex dc3088bb2fa..dc3088bb2fa 100644 --- a/doc/integration/facebook_website_url.png +++ b/doc/integration/img/facebook_website_url.png diff --git a/doc/integration/github_app.png b/doc/integration/img/github_app.png Binary files differindex d890345ced9..d890345ced9 100644 --- a/doc/integration/github_app.png +++ b/doc/integration/img/github_app.png diff --git a/doc/integration/gitlab_app.png b/doc/integration/img/gitlab_app.png Binary files differindex 3f9391a821b..3f9391a821b 100644 --- a/doc/integration/gitlab_app.png +++ b/doc/integration/img/gitlab_app.png diff --git a/doc/integration/gmail_actions_button.png b/doc/integration/img/gmail_action_buttons_for_gitlab.png Binary files differindex b08f54d137b..b08f54d137b 100644 --- a/doc/integration/gmail_actions_button.png +++ b/doc/integration/img/gmail_action_buttons_for_gitlab.png diff --git a/doc/integration/google_app.png b/doc/integration/img/google_app.png Binary files differindex 5a62ad35009..5a62ad35009 100644 --- a/doc/integration/google_app.png +++ b/doc/integration/img/google_app.png diff --git a/doc/integration/oauth_provider/admin_application.png b/doc/integration/img/oauth_provider_admin_application.png Binary files differindex a5f34512aa8..a5f34512aa8 100644 --- a/doc/integration/oauth_provider/admin_application.png +++ b/doc/integration/img/oauth_provider_admin_application.png diff --git a/doc/integration/oauth_provider/application_form.png b/doc/integration/img/oauth_provider_application_form.png Binary files differindex ae135db2627..ae135db2627 100644 --- a/doc/integration/oauth_provider/application_form.png +++ b/doc/integration/img/oauth_provider_application_form.png diff --git a/doc/integration/oauth_provider/authorized_application.png b/doc/integration/img/oauth_provider_authorized_application.png Binary files differindex d3ce05be9cc..d3ce05be9cc 100644 --- a/doc/integration/oauth_provider/authorized_application.png +++ b/doc/integration/img/oauth_provider_authorized_application.png diff --git a/doc/integration/oauth_provider/user_wide_applications.png b/doc/integration/img/oauth_provider_user_wide_applications.png Binary files differindex 719e1974068..719e1974068 100644 --- a/doc/integration/oauth_provider/user_wide_applications.png +++ b/doc/integration/img/oauth_provider_user_wide_applications.png diff --git a/doc/integration/twitter_app_api_keys.png b/doc/integration/img/twitter_app_api_keys.png Binary files differindex 1076337172a..1076337172a 100644 --- a/doc/integration/twitter_app_api_keys.png +++ b/doc/integration/img/twitter_app_api_keys.png diff --git a/doc/integration/twitter_app_details.png b/doc/integration/img/twitter_app_details.png Binary files differindex b95e8af8a74..b95e8af8a74 100644 --- a/doc/integration/twitter_app_details.png +++ b/doc/integration/img/twitter_app_details.png diff --git a/doc/integration/jira-integration-points.png b/doc/integration/jira-integration-points.png Binary files differdeleted file mode 100644 index 0692a7b458a..00000000000 --- a/doc/integration/jira-integration-points.png +++ /dev/null diff --git a/doc/integration/jira.md b/doc/integration/jira.md index de574d53410..78aa6634116 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -1,149 +1,3 @@ -# GitLab Jira integration +# GitLab JIRA integration -GitLab can be configured to interact with Jira. Configuration happens via -username and password. Connecting to a Jira server via CAS is not possible. - -Each project can be configured to connect to a different Jira instance, see the -[configuration](#configuration) section. If you have one Jira instance you can -pre-fill the settings page with a default template. To configure the template -see the [Services Templates][services-templates] document. - -Once the project is connected to Jira, you can reference and close the issues -in Jira directly from GitLab. - -## Table of Contents - -* [Referencing Jira Issues from GitLab](#referencing-jira-issues) -* [Closing Jira Issues from GitLab](#closing-jira-issues) -* [Configuration](#configuration) - -### Referencing Jira Issues - -When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issue in GitLab will automatically add a comment in Jira issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, eg. `PROJECT-7`, will add a comment in Jira issue in the -format: - -``` - USER mentioned this issue in LINK_TO_THE_MENTION -``` - -* `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -* `LINK_TO_THE_MENTION` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -Can be commit or merge request. - - - ---- - -### Closing Jira Issues - -Jira issues can be closed directly from GitLab by using trigger words, eg. -`Resolves PROJECT-1`, `Closes PROJECT-1` or `Fixes PROJECT-1`, in commits and -merge requests. When a commit which contains the trigger word in the commit -message is pushed, GitLab will add a comment in the mentioned Jira issue. - -For example, for project named `PROJECT` in Jira, we implemented a new feature -and created a merge request in GitLab. - -This feature was requested in Jira issue `PROJECT-7`. Merge request in GitLab -contains the improvement and in merge request description we say that this -merge request `Closes PROJECT-7` issue. - -Once this merge request is merged, the Jira issue will be automatically closed -with a link to the commit that resolved the issue. - - - ---- - - - ---- - -## Configuration - -### Configuring JIRA - -We need to create a user in JIRA which will have access to all projects that -need to integrate with GitLab. Login to your JIRA instance as admin and under -Administration go to User Management and create a new user. - -As an example, we'll create a user named `gitlab` and add it to `jira-developers` -group. - -**It is important that the user `gitlab` has write-access to projects in JIRA** - -### Configuring GitLab - -JIRA configuration in GitLab is done via a project's **Services**. - -#### GitLab 7.8 and up with JIRA v6.x - -See next section. - -#### GitLab 7.8 and up - -_The currently supported JIRA versions are v6.x and v7.x._ - -To enable JIRA integration in a project, navigate to the project's -**Settings > Services > JIRA**. - -Fill in the required details on the page as described in the table below. - -| Field | Description | -| ----- | ----------- | -| `description` | A name for the issue tracker (to differentiate between instances, for instance). | -| `project url` | The URL to the JIRA project which is being linked to this GitLab project. | -| `issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. | -| `new issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project. | -| `api url` | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`, i.e. `https://jira.example.com/rest/api/2`. | -| `username` | The username of the user created in [configuring JIRA step](#configuring-jira). | -| `password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `Jira issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). By default, this ID is `2` (in the example image, this is `2` as well) | - -After saving the configuration, your GitLab project will be able to interact -with the linked JIRA project. - - - ---- - -#### GitLab 6.x-7.7 with JIRA v6.x - -_**Note:** GitLab versions 7.8 and up contain various integration improvements. -We strongly recommend upgrading._ - -In `gitlab.yml` enable the JIRA issue tracker section by -[uncommenting these lines][jira-gitlab-yml]. This will make sure that all -issues within GitLab are pointing to the JIRA issue tracker. - -After you set this, you will be able to close issues in JIRA by a commit in -GitLab. - -Go to your project's **Settings** page and fill in the project name for the -JIRA project: - - - ---- - -You can also enable the JIRA service that will allow you to interact with JIRA -issues. Go to the **Settings > Services > JIRA** and: - -1. Tick the active check box to enable the service -1. Supply the URL to JIRA server, for example http://jira.example.com -1. Supply the username of a user we created under `Configuring JIRA` section, - for example `gitlab` -1. Supply the password of the user -1. Optional: supply the JIRA API version, default is version `2` -1. Optional: supply the JIRA issue transition ID (issue transition to closed). - This is dependent on JIRA settings, default is `2` -1. Hit save - - - - -[services-templates]: ../project_services/services_templates.md -[jira-gitlab-yml]: https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115 +This document was moved under [project_services/jira](../project_services/jira.md). diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 192c321f712..dbe5a175c82 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -15,16 +15,16 @@ GitLab has two ways to add new OAuth2 application to an instance, you can add ap ### Adding application through profile Go to your profile section 'Application' and press button 'New Application' - + After this you will see application form, where "Name" is arbitrary name, "Redirect URI" is URL in your app where users will be sent after authorization on GitLab.com. - + ### Authorized application Every application you authorized will be shown in your "Authorized application" sections. - + At any time you can revoke access just clicking button "Revoke" @@ -32,4 +32,4 @@ At any time you can revoke access just clicking button "Revoke" If you want to create application that does not belong to certain user you can create it from admin area -
\ No newline at end of file + diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index e9e17eb4165..8e6627b2be5 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -9,6 +9,23 @@ Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if - [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) - [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) +## Supported Providers + +This is a list of the current supported OmniAuth providers. Before proceeding +on each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +- [GitHub](github.md) +- [Bitbucket](bitbucket.md) +- [GitLab.com](gitlab.md) +- [Google](google.md) +- [Facebook](facebook.md) +- [Twitter](twitter.md) +- [Shibboleth](shibboleth.md) +- [SAML](saml.md) +- [Crowd](crowd.md) +- [Azure](azure.md) + ## Initial OmniAuth Configuration Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. @@ -67,19 +84,6 @@ If you want to change these settings: Now we can choose one or more of the Supported Providers below to continue configuration. -## Supported Providers - -- [GitHub](github.md) -- [Bitbucket](bitbucket.md) -- [GitLab.com](gitlab.md) -- [Google](google.md) -- [Facebook](facebook.md) -- [Twitter](twitter.md) -- [Shibboleth](shibboleth.md) -- [SAML](saml.md) -- [Crowd](crowd.md) -- [Azure](azure.md) - ## Enable OmniAuth for an Existing User Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 1632e42f701..8841dbdb7c6 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -78,6 +78,18 @@ On the sign in page there should now be a SAML button below the regular sign in ## Troubleshooting -If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, this likely indicates that GitLab could not get the email address for the SAML user. +If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, +this likely indicates that GitLab could not get the email address for the SAML user. -Make sure the IdP provides a claim containing the user's email address, using claim name 'email' or 'mail'. The email will be used to automatically generate the GitLab username.
\ No newline at end of file +Make sure the IdP provides a claim containing the user's email address, using claim name +'email' or 'mail'. The email will be used to automatically generate the GitLab username. + +If after signing in into your SAML server you are redirected back to the sign in page and +no error is displayed, check your `production.log` file. It will most likely contain the +message `Can't verify CSRF token authenticity`. This means that there is an error during +the SAML request, but this error never reaches GitLab due to the CSRF check. + +To bypass this you can add `skip_before_action :verify_authenticity_token` to the +`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab, +where it can then be seen in the usual logs, or as a flash message in the login +screen.
\ No newline at end of file diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 84f1d74c058..ecbe0d3e887 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -6,15 +6,17 @@ To enable Slack integration you must create an Incoming WebHooks integration on 1. [Sign in to Slack](https://slack.com/signin) -1. Select **Configure Integrations** from the dropdown next to your team name. +1. Select **Apps & Custom Integrations** from the dropdown next to your team name. -1. Select the **All Services** tab +1. Click the **Configure** link (right-upper corner). -1. Click **Add** next to Incoming Webhooks +1. Select the **Custom integrations** tab. -1. Pick Incoming WebHooks +1. Click the **Incoming WebHooks** row. -1. Choose the channel name you want to send notifications to +1. Click the **Add configuration** button. + +1. Choose the channel name you want to send notifications to. 1. Click **Add Incoming WebHooks Integration** - Optional step; You can change bot's name and avatar by clicking modifying the bot name or avatar under **Integration Settings**. diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md index 52ed4a22339..4769f26b259 100644 --- a/doc/integration/twitter.md +++ b/doc/integration/twitter.md @@ -14,7 +14,7 @@ To enable the Twitter OmniAuth provider you must register your application with - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' - Agree to the "Developer Agreement". -  +  1. Select "Create your Twitter application." 1. Select the "Settings" tab. @@ -27,7 +27,7 @@ To enable the Twitter OmniAuth provider you must register your application with 1. You should now see an API key and API secret (see screenshot). Keep this page open as you continue configuration. -  +  1. On your GitLab server, open the configuration file. @@ -76,4 +76,4 @@ To enable the Twitter OmniAuth provider you must register your application with 1. Restart GitLab for the changes to take effect. -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in.
\ No newline at end of file +On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md index bc8e7d155e7..83c77742b19 100644 --- a/doc/markdown/markdown.md +++ b/doc/markdown/markdown.md @@ -88,6 +88,9 @@ GFM will autolink almost any URL you copy and paste into your text. ## Code and Syntax Highlighting +_GitLab uses the [rouge ruby library][rouge] for syntax highlighting. For a +list of supported languages visit the rouge website._ + Blocks of code are either fenced by lines with three back-ticks <code>```</code>, or are indented with four spaces. Only the fenced code blocks support syntax highlighting. ```no-highlight @@ -585,3 +588,5 @@ By including colons in the header row, you can align the text within that column - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). - The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. - [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown. + +[rouge]: http://rouge.jneen.net/ "Rouge website" diff --git a/doc/monitoring/performance/gitlab_configuration.md b/doc/monitoring/performance/gitlab_configuration.md new file mode 100644 index 00000000000..b856e7935a3 --- /dev/null +++ b/doc/monitoring/performance/gitlab_configuration.md @@ -0,0 +1,39 @@ +# GitLab Configuration + +GitLab Performance Monitoring is disabled by default. To enable it and change any of its +settings, navigate to the Admin area in **Settings > Metrics** +(`/admin/application_settings`). + +The minimum required settings you need to set are the InfluxDB host and port. +Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the +changes. + +--- + + + +--- + +Finally, a restart of all GitLab processes is required for the changes to take +effect: + +```bash +# For Omnibus installations +sudo gitlab-ctl restart + +# For installations from source +sudo service gitlab restart +``` + +## Pending Migrations + +When any migrations are pending, the metrics are disabled until the migrations +have been performed. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [InfluxDB Configuration](influxdb_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) diff --git a/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png b/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png Binary files differnew file mode 100644 index 00000000000..14d82b6ac98 --- /dev/null +++ b/doc/monitoring/performance/img/metrics_gitlab_configuration_settings.png diff --git a/doc/monitoring/performance/influxdb_configuration.md b/doc/monitoring/performance/influxdb_configuration.md new file mode 100644 index 00000000000..3a2b598b78f --- /dev/null +++ b/doc/monitoring/performance/influxdb_configuration.md @@ -0,0 +1,192 @@ +# InfluxDB Configuration + +The default settings provided by [InfluxDB] are not sufficient for a high traffic +GitLab environment. The settings discussed in this document are based on the +settings GitLab uses for GitLab.com, depending on your own needs you may need to +further adjust them. + +If you are intending to run InfluxDB on the same server as GitLab, make sure +you have plenty of RAM since InfluxDB can use quite a bit depending on traffic. + +Unless you are going with a budget setup, it's advised to run it separately. + +## Requirements + +- InfluxDB 0.9.5 or newer +- A fairly modern version of Linux +- At least 4GB of RAM +- At least 10GB of storage for InfluxDB data + +Note that the RAM and storage requirements can differ greatly depending on the +amount of data received/stored. To limit the amount of stored data users can +look into [InfluxDB Retention Policies][influxdb-retention]. + +## Installation + +Installing InfluxDB is out of the scope of this document. Please refer to the +[InfluxDB documentation]. + +## InfluxDB Server Settings + +Since InfluxDB has many settings that users may wish to customize themselves +(e.g. what port to run InfluxDB on), we'll only cover the essentials. + +The configuration file in question is usually located at +`/etc/influxdb/influxdb.conf`. Whenever you make a change in this file, +InfluxDB needs to be restarted. + +### Storage Engine + +InfluxDB comes with different storage engines and as of InfluxDB 0.9.5 a new +storage engine is available, called [TSM Tree]. All users **must** use the new +`tsm1` storage engine as this [will be the default engine][tsm1-commit] in +upcoming InfluxDB releases. + +Make sure you have the following in your configuration file: + +``` +[data] + dir = "/var/lib/influxdb/data" + engine = "tsm1" +``` + +### Admin Panel + +Production environments should have the InfluxDB admin panel **disabled**. This +feature can be disabled by adding the following to your InfluxDB configuration +file: + +``` +[admin] + enabled = false +``` + +### HTTP + +HTTP is required when using the [InfluxDB CLI] or other tools such as Grafana, +thus it should be enabled. When enabling make sure to _also_ enable +authentication: + +``` +[http] + enabled = true + auth-enabled = true +``` + +_**Note:** Before you enable authentication, you might want to [create an +admin user](#create-a-new-admin-user)._ + +### UDP + +GitLab writes data to InfluxDB via UDP and thus this must be enabled. Enabling +UDP can be done using the following settings: + +``` +[[udp]] + enabled = true + bind-address = ":8089" + database = "gitlab" + batch-size = 1000 + batch-pending = 5 + batch-timeout = "1s" + read-buffer = 209715200 +``` + +This does the following: + +1. Enable UDP and bind it to port 8089 for all addresses. +2. Store any data received in the "gitlab" database. +3. Define a batch of points to be 1000 points in size and allow a maximum of + 5 batches _or_ flush them automatically after 1 second. +4. Define a UDP read buffer size of 200 MB. + +One of the most important settings here is the UDP read buffer size as if this +value is set too low, packets will be dropped. You must also make sure the OS +buffer size is set to the same value, the default value is almost never enough. + +To set the OS buffer size to 200 MB, on Linux you can run the following command: + +```bash +sysctl -w net.core.rmem_max=209715200 +``` + +To make this permanent, add the following to `/etc/sysctl.conf` and restart the +server: + +```bash +net.core.rmem_max=209715200 +``` + +It is **very important** to make sure the buffer sizes are large enough to +handle all data sent to InfluxDB as otherwise you _will_ lose data. The above +buffer sizes are based on the traffic for GitLab.com. Depending on the amount of +traffic, users may be able to use a smaller buffer size, but we highly recommend +using _at least_ 100 MB. + +When enabling UDP, users should take care to not expose the port to the public, +as doing so will allow anybody to write data into your InfluxDB database (as +[InfluxDB's UDP protocol][udp] doesn't support authentication). We recommend either +whitelisting the allowed IP addresses/ranges, or setting up a VLAN and only +allowing traffic from members of said VLAN. + +## Create a new admin user + +If you want to [enable authentication](#http), you might want to [create an +admin user][influx-admin]: + +``` +influx -execute "CREATE USER jeff WITH PASSWORD '1234' WITH ALL PRIVILEGES" +``` + +## Create the `gitlab` database + +Once you get InfluxDB up and running, you need to create a database for GitLab. +Make sure you have changed the [storage engine](#storage-engine) to `tsm1` +before creating a database. + +_**Note:** If you [created an admin user](#create-a-new-admin-user) and enabled +[HTTP authentication](#http), remember to append the username (`-username <username>`) +and password (`-password <password>`) you set earlier to the commands below._ + +Run the following command to create a database named `gitlab`: + +```bash +influx -execute 'CREATE DATABASE gitlab' +``` + +The name **must** be `gitlab`, do not use any other name. + +Next, make sure that the database was successfully created: + +```bash +influx -execute 'SHOW DATABASES' +``` + +The output should be similar to: + +``` +name: databases +--------------- +name +_internal +gitlab +``` + +That's it! Now your GitLab instance should send data to InfluxDB. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) + +[influxdb-retention]: https://docs.influxdata.com/influxdb/v0.9/query_language/database_management/#retention-policy-management +[influxdb documentation]: https://docs.influxdata.com/influxdb/v0.9/ +[influxdb cli]: https://docs.influxdata.com/influxdb/v0.9/tools/shell/ +[udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ +[influxdb]: https://influxdata.com/time-series-platform/influxdb/ +[tsm tree]: https://influxdata.com/blog/new-storage-engine-time-structured-merge-tree/ +[tsm1-commit]: https://github.com/influxdata/influxdb/commit/15d723dc77651bac83e09e2b1c94be480966cb0d +[influx-admin]: https://docs.influxdata.com/influxdb/v0.9/administration/authentication_and_authorization/#create-a-new-admin-user diff --git a/doc/monitoring/performance/influxdb_schema.md b/doc/monitoring/performance/influxdb_schema.md new file mode 100644 index 00000000000..a5a8aebd2d1 --- /dev/null +++ b/doc/monitoring/performance/influxdb_schema.md @@ -0,0 +1,87 @@ +# InfluxDB Schema + +The following measurements are currently stored in InfluxDB: + +- `PROCESS_file_descriptors` +- `PROCESS_gc_statistics` +- `PROCESS_memory_usage` +- `PROCESS_method_calls` +- `PROCESS_object_counts` +- `PROCESS_transactions` +- `PROCESS_views` + +Here, `PROCESS` is replaced with either `rails` or `sidekiq` depending on the +process type. In all series, any form of duration is stored in milliseconds. + +## PROCESS_file_descriptors + +This measurement contains the number of open file descriptors over time. The +value field `value` contains the number of descriptors. + +## PROCESS_gc_statistics + +This measurement contains Ruby garbage collection statistics such as the amount +of minor/major GC runs (relative to the last sampling interval), the time spent +in garbage collection cycles, and all fields/values returned by `GC.stat`. + +## PROCESS_memory_usage + +This measurement contains the process' memory usage (in bytes) over time. The +value field `value` contains the number of bytes. + +## PROCESS_method_calls + +This measurement contains the methods called during a transaction along with +their duration, and a name of the transaction action that invoked the method (if +available). The method call duration is stored in the value field `duration`, +while the method name is stored in the tag `method`. The tag `action` contains +the full name of the transaction action. Both the `method` and `action` fields +are in the following format: + +``` +ClassName#method_name +``` + +For example, a method called by the `show` method in the `UsersController` class +would have `action` set to `UsersController#show`. + +## PROCESS_object_counts + +This measurement is used to store retained Ruby objects (per class) and the +amount of retained objects. The number of objects is stored in the `count` value +field while the class name is stored in the `type` tag. + +## PROCESS_transactions + +This measurement is used to store basic transaction details such as the time it +took to complete a transaction, how much time was spent in SQL queries, etc. The +following value fields are available: + +| Value | Description | +| ----- | ----------- | +| `duration` | The total duration of the transaction | +| `allocated_memory` | The amount of bytes allocated while the transaction was running. This value is only reliable when using single-threaded application servers | +| `method_duration` | The total time spent in method calls | +| `sql_duration` | The total time spent in SQL queries | +| `view_duration` | The total time spent in views | + +## PROCESS_views + +This measurement is used to store view rendering timings for a transaction. The +following value fields are available: + +| Value | Description | +| ----- | ----------- | +| `duration` | The rendering time of the view | +| `view` | The path of the view, relative to the application's root directory | + +The `action` tag contains the action name of the transaction that rendered the +view. + +--- + +Read more on: + +- [Introduction to GitLab Performance Monitoring](introduction.md) +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Configuration](influxdb_configuration.md) diff --git a/doc/monitoring/performance/introduction.md b/doc/monitoring/performance/introduction.md new file mode 100644 index 00000000000..f2460d31302 --- /dev/null +++ b/doc/monitoring/performance/introduction.md @@ -0,0 +1,64 @@ +# GitLab Performance Monitoring + +GitLab comes with its own application performance measuring system as of GitLab +8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the +Community and Enterprise editions. + +Apart from this introduction, you are advised to read through the following +documents in order to understand and properly configure GitLab Performance Monitoring: + +- [GitLab Configuration](gitlab_configuration.md) +- [InfluxDB Configuration](influxdb_configuration.md) +- [InfluxDB Schema](influxdb_schema.md) + +## Introduction to GitLab Performance Monitoring + +GitLab Performance Monitoring makes it possible to measure a wide variety of statistics +including (but not limited to): + +- The time it took to complete a transaction (a web request or Sidekiq job). +- The time spent in running SQL queries and rendering HAML views. +- The time spent executing (instrumented) Ruby methods. +- Ruby object allocations, and retained objects in particular. +- System statistics such as the process' memory usage and open file descriptors. +- Ruby garbage collection statistics. + +Metrics data is written to [InfluxDB][influxdb] over [UDP][influxdb-udp]. Stored +data can be visualized using [Grafana][grafana] or any other application that +supports reading data from InfluxDB. Alternatively data can be queried using the +InfluxDB CLI. + +## Metric Types + +Two types of metrics are collected: + +1. Transaction specific metrics. +1. Sampled metrics, collected at a certain interval in a separate thread. + +### Transaction Metrics + +Transaction metrics are metrics that can be associated with a single +transaction. This includes statistics such as the transaction duration, timings +of any executed SQL queries, time spent rendering HAML views, etc. These metrics +are collected for every Rack request and Sidekiq job processed. + +### Sampled Metrics + +Sampled metrics are metrics that can't be associated with a single transaction. +Examples include garbage collection statistics and retained Ruby objects. These +metrics are collected at a regular interval. This interval is made up out of two +parts: + +1. A user defined interval. +1. A randomly generated offset added on top of the interval, the same offset + can't be used twice in a row. + +The actual interval can be anywhere between a half of the defined interval and a +half above the interval. For example, for a user defined interval of 15 seconds +the actual interval can be anywhere between 7.5 and 22.5. The interval is +re-generated for every sampling run instead of being generated once and re-used +for the duration of the process' lifetime. + +[influxdb]: https://influxdata.com/time-series-platform/influxdb/ +[influxdb-udp]: https://docs.influxdata.com/influxdb/v0.9/write_protocols/udp/ +[grafana]: http://grafana.org/ diff --git a/doc/profile/preferences.md b/doc/profile/preferences.md index f17bbe8f2aa..073b8797508 100644 --- a/doc/profile/preferences.md +++ b/doc/profile/preferences.md @@ -12,6 +12,9 @@ The default is **Charcoal**. ## Syntax highlighting theme +_GitLab uses the [rouge ruby library][rouge] for syntax highlighting. For a +list of supported languages visit the rouge website._ + Changing this setting allows the user to customize the theme used when viewing syntax highlighted code on the site. @@ -36,3 +39,5 @@ The default is **Your Projects**. It allows user to choose what content he or she want to see on project page. The default is **Readme**. + +[rouge]: http://rouge.jneen.net/ "Rouge website" diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png Binary files differnew file mode 100644 index 00000000000..85e54861b3e --- /dev/null +++ b/doc/project_services/img/jira_add_gitlab_commit_message.png diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png Binary files differnew file mode 100644 index 00000000000..e4576433889 --- /dev/null +++ b/doc/project_services/img/jira_add_user_to_group.png diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png Binary files differnew file mode 100644 index 00000000000..edaa1326058 --- /dev/null +++ b/doc/project_services/img/jira_create_new_group.png diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png Binary files differnew file mode 100644 index 00000000000..9e518ad7843 --- /dev/null +++ b/doc/project_services/img/jira_create_new_group_name.png diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png Binary files differnew file mode 100644 index 00000000000..57e433dd818 --- /dev/null +++ b/doc/project_services/img/jira_create_new_user.png diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png Binary files differnew file mode 100644 index 00000000000..47716ca6d0e --- /dev/null +++ b/doc/project_services/img/jira_group_access.png diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png Binary files differnew file mode 100644 index 00000000000..cabec1ae137 --- /dev/null +++ b/doc/project_services/img/jira_issue_closed.png diff --git a/doc/integration/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png Binary files differindex 15739a22dc7..15739a22dc7 100644 --- a/doc/integration/img/jira_issue_reference.png +++ b/doc/project_services/img/jira_issue_reference.png diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png Binary files differnew file mode 100644 index 00000000000..28e17be3a84 --- /dev/null +++ b/doc/project_services/img/jira_issues_workflow.png diff --git a/doc/integration/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png Binary files differindex 1e78daf105f..1e78daf105f 100644 --- a/doc/integration/img/jira_merge_request_close.png +++ b/doc/project_services/img/jira_merge_request_close.png diff --git a/doc/integration/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png Binary files differindex 5986fdb63fb..5986fdb63fb 100644 --- a/doc/integration/img/jira_project_name.png +++ b/doc/project_services/img/jira_project_name.png diff --git a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png Binary files differnew file mode 100644 index 00000000000..0149181dc86 --- /dev/null +++ b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png diff --git a/doc/integration/img/jira_service.png b/doc/project_services/img/jira_service.png Binary files differindex 1f6628c4371..1f6628c4371 100644 --- a/doc/integration/img/jira_service.png +++ b/doc/project_services/img/jira_service.png diff --git a/doc/integration/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png Binary files differindex 67dfc6144c4..67dfc6144c4 100644 --- a/doc/integration/img/jira_service_close_issue.png +++ b/doc/project_services/img/jira_service_close_issue.png diff --git a/doc/integration/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png Binary files differindex 2b37eda3520..2b37eda3520 100644 --- a/doc/integration/img/jira_service_page.png +++ b/doc/project_services/img/jira_service_page.png diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png Binary files differnew file mode 100644 index 00000000000..e935d9362aa --- /dev/null +++ b/doc/project_services/img/jira_submit_gitlab_merge_request.png diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png Binary files differnew file mode 100644 index 00000000000..2745916972c --- /dev/null +++ b/doc/project_services/img/jira_user_management_link.png diff --git a/doc/integration/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png Binary files differindex 8635a32eb68..8635a32eb68 100644 --- a/doc/integration/img/jira_workflow_screenshot.png +++ b/doc/project_services/img/jira_workflow_screenshot.png diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md new file mode 100644 index 00000000000..d6b2e7f521b --- /dev/null +++ b/doc/project_services/jira.md @@ -0,0 +1,212 @@ +# GitLab JIRA integration + +GitLab can be configured to interact with [JIRA Core] either using an +on-premises instance or the SaaS solution that Atlassian offers. Configuration +happens via username and password on a per-project basis. Connecting to a JIRA +server via CAS is not possible. + +Each project can be configured to connect to a different JIRA instance or, in +case you have a single JIRA instance, you can pre-fill the JIRA service +settings page in GitLab with a default template. To configure the JIRA template, +see the [Services Templates documentation][services-templates]. + +Once the GitLab project is connected to JIRA, you can reference and close the +issues in JIRA directly from GitLab's merge requests. + +## Configuration + +The configuration consists of two parts: + +- [JIRA configuration](#configuring-jira) +- [GitLab configuration](#configuring-gitlab) + +### Configuring JIRA + +First things first, we need to create a user in JIRA which will have access to +all projects that need to integrate with GitLab. + +We have split this stage in steps so it is easier to follow. + +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** to create a new user. + +  + + --- + +1. The next step is to create a new user (e.g., `gitlab`) who has write access + to projects in JIRA. Enter the user's name and a _valid_ e-mail address + since JIRA sends a verification e-mail to set-up the password. + _**Note:** JIRA creates the username automatically by using the e-mail + prefix. You can change it later if you want._ + +  + + --- + +1. Now, let's create a `gitlab-developers` group which will have write access + to projects in JIRA. Go to the **Groups** tab and select **Create group**. + +  + + --- + + Give it an optional description and hit **Create group**. + +  + + --- + +1. Give the newly-created group write access by going to + **Application access > View configuration** and adding the `gitlab-developers` + group to JIRA Core. + +  + + --- + +1. Add the `gitlab` user to the `gitlab-developers` group by going to + **Users > GitLab user > Add group** and selecting the `gitlab-developers` + group from the dropdown menu. Notice that the group says _Access_ which is + what we aim for. + +  + +--- + +The JIRA configuration is over. Write down the new JIRA username and its +password as they will be needed when configuring GitLab in the next section. + +### Configuring GitLab + +_**Note:** The currently supported JIRA versions are v6.x and v7.x. and GitLab +7.8 or higher is required._ + +--- + +Assuming you [have already configured JIRA](#configuring-jira), now it's time +to configure GitLab. + +JIRA configuration in GitLab is done via a project's +[**Services**](../project_services/project_services.md). + +To enable JIRA integration in a project, navigate to the project's +**Settings > Services > JIRA**. + +Fill in the required details on the page, as described in the table below. + +| Setting | Description | +| ------- | ----------- | +| `Description` | A name for the issue tracker (to differentiate between instances, for example). | +| `Project url` | The URL to the JIRA project which is being linked to this GitLab project. It is of the form: `https://<jira_host_url>/issues/?jql=project=<jira_project>`. | +| `Issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. It is of the form: `https://<jira_host_url>/browse/:id`. Leave `:id` as-is, it gets replaced by GitLab at runtime. | +| `New issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project, and it is of the form: `https://<jira_host_url>/secure/CreateIssue.jspa` | +| `Api url` | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`. It is of the form: `https://<jira_host_url>/rest/api/2`. | +| `Username` | The username of the user created in [configuring JIRA step](#configuring-jira). | +| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | +| `JIRA issue transition` | This setting is very important to set up correctly. It is the ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot](img/jira_issues_workflow.png)). By default, this ID is set to `2` | + +After saving the configuration, your GitLab project will be able to interact +with the linked JIRA project. + + + +--- + +## JIRA issues + +By now you should have [configured JIRA](#configuring-jira) and enabled the +[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close JIRA issues by just mentioning their +ID in GitLab commits and merge requests. + +### Referencing JIRA Issues + +If you reference a JIRA issue, e.g., `GITLAB-1`, in a commit comment, a link +which points back to JIRA is created. + +The same works for comments in merge requests as well. + + + +--- + +The mentioning action is two-fold, so a comment with a JIRA issue in GitLab +will automatically add a comment in that particular JIRA issue with the link +back to GitLab. + + + + +--- + +The comment on the JIRA issue is of the form: + +> USER mentioned this issue in LINK_TO_THE_MENTION + +Where: + +| Format | Description | +| ------ | ----------- | +| `USER` | A user that mentioned the issue. This is the link to the user profile in GitLab. | +| `LINK_TO_THE_MENTION` | Link to the origin of mention with a name of the entity where JIRA issue was mentioned. Can be commit or merge request. | + +### Closing JIRA issues + +JIRA issues can be closed directly from GitLab by using trigger words in +commits and merge requests. When a commit which contains the trigger word +followed by the JIRA issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned JIRA issue and immediately close it (provided +the transition ID was set up correctly). + +There are currently three trigger words, and you can use either one to achieve +the same goal: + +- `Resolves GITLAB-1` +- `Closes GITLAB-1` +- `Fixes GITLAB-1` + +where `GITLAB-1` the issue ID of the JIRA project. + +### JIRA issue closing example + +Let's say for example that we submitted a bug fix and created a merge request +in GitLab. The workflow would be something like this: + +1. Create a new branch +1. Fix the bug +1. Commit the changes and push branch to GitLab +1. Open a new merge request and reference the JIRA issue including one of the + trigger words, e.g.: `Fixes GITLAB-1`, in the description +1. Submit the merge request +1. Ask someone to review +1. Merge the merge request +1. The JIRA issue is automatically closed + +--- + +In the following screenshot you can see what the link references to the JIRA +issue look like. + + + +--- + +Once this merge request is merged, the JIRA issue will be automatically closed +with a link to the commit that resolved the issue. + + + +--- + +You can see from the above image that there are four references to GitLab: + +- The first is from a comment in a specific commit +- The second is from the JIRA issue reference in the merge request description +- The third is from the actual commit that solved the issue +- And the fourth is from the commit that the merge request created + +[services-templates]: ../project_services/services_templates.md "Services templates documentation" +[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website" diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index e3403127723..55db3e4f2f3 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -22,7 +22,7 @@ further configuration instructions and details. Contributions are welcome. | Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | -| JIRA | Jira issue tracker | +| [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/security/README.md b/doc/security/README.md index f34c792d005..be1abb88c3d 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -7,4 +7,4 @@ - [Reset your root password](reset_root_password.md) - [User File Uploads](user_file_uploads.md) - [How we manage the CRIME vulnerability](crime_vulnerability.md) -- [Enforce Two-Factor authentication](two_factor_authentication.md) +- [Enforce Two-factor authentication](two_factor_authentication.md) diff --git a/doc/security/img/two_factor_authentication_settings.png b/doc/security/img/two_factor_authentication_settings.png Binary files differnew file mode 100644 index 00000000000..aa51ce030bb --- /dev/null +++ b/doc/security/img/two_factor_authentication_settings.png diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 4e25a1fdc3f..8365bdb7b1b 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -20,7 +20,13 @@ In the Admin area under **Settings** (`/admin/application_settings`), look for the "Sign-in Restrictions" area, where you can configure both. If you want 2FA enforcement to take effect on next login, change the grace -period to `0` +period to `0`. + +--- + + + +--- ## Disabling 2FA for everyone @@ -28,11 +34,12 @@ There may be some special situations where you want to disable 2FA for everyone even when forced 2FA is disabled. There is a rake task for that: ``` -# use this command if you've installed GitLab with the Omnibus package +# Omnibus installations sudo gitlab-rake gitlab:two_factor:disable_for_all_users -# if you've installed GitLab from source +# Installations from source sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_ENV=production ``` -**IMPORTANT: this is a permanent and irreversible action. Users will have to reactivate 2FA from scratch if they want to use it again.** +**IMPORTANT: this is a permanent and irreversible action. Users will have to + reactivate 2FA from scratch if they want to use it again.** diff --git a/doc/update/8.3-to-8.4.md b/doc/update/8.3-to-8.4.md index 1cbeab3eca3..616b1f58b65 100644 --- a/doc/update/8.3-to-8.4.md +++ b/doc/update/8.3-to-8.4.md @@ -37,7 +37,7 @@ sudo -u git -H git checkout 8-4-stable-ee ```bash cd /home/git/gitlab-shell sudo -u git -H git fetch --all -sudo -u git -H git checkout v2.6.9 +sudo -u git -H git checkout v2.6.10 ``` ### 5. Update gitlab-workhorse @@ -48,7 +48,7 @@ which should already be on your system from GitLab 8.1. ```bash cd /home/git/gitlab-workhorse sudo -u git -H git fetch --all -sudo -u git -H git checkout 0.5.4 +sudo -u git -H git checkout 0.6.2 sudo -u git -H make ``` @@ -104,10 +104,7 @@ via [/etc/default/gitlab]. #### Init script -We updated the init script for GitLab in order to pass new -configuration options to gitlab-workhorse. We let gitlab-workhorse -connect to the Rails application via a Unix domain socket and we tell -it where the 'public' directory of GitLab is. +We updated the init script for GitLab in order to set a specific PATH for gitlab-workhorse. ``` cd /home/git/gitlab diff --git a/doc/update/README.md b/doc/update/README.md index 0472537eeb5..109d5de3fa2 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -14,3 +14,4 @@ Depending on the installation method and your GitLab version, there are multiple ## Miscellaneous - [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating your database from MySQL to PostgreSQL. +- [MySQL installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/database_mysql.md) contains additional information about configuring GitLab to work with a MySQL database. diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md index 6420d65cf1b..c29037e89c2 100644 --- a/doc/web_hooks/web_hooks.md +++ b/doc/web_hooks/web_hooks.md @@ -56,7 +56,7 @@ X-Gitlab-Event: Push Hook "author": { "name": "Jordi Mallach", "email": "jordi@softcatala.org" - } + }, "added": ["CHANGELOG"], "modified": ["app/controller/application.rb"], "removed": [] diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 3651b55f438..bf62ab41053 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -6,6 +6,7 @@ - [GitLab Flow](gitlab_flow.md) - [Groups](groups.md) - [Keyboard shortcuts](shortcuts.md) +- [File finder](file_finder.md) - [Labels](labels.md) - [Notification emails](notifications.md) - [Project Features](project_features.md) diff --git a/doc/workflow/file_finder.md b/doc/workflow/file_finder.md new file mode 100644 index 00000000000..b69ae663272 --- /dev/null +++ b/doc/workflow/file_finder.md @@ -0,0 +1,46 @@ +# File finder + +_**Note:** This feature was [introduced][gh-9889] in GitLab 8.4._ + +--- + +The file finder feature allows you to quickly shortcut your way when you are +searching for a file in a repository using the GitLab UI. + +You can find the **Find File** button when in the **Files** section of a +project. + + + +--- + +For those who prefer to keep their fingers on the keyboard, there is a +[shortcut button](shortcuts.md) as well, which you can invoke from _anywhere_ +in a project. + +Press `t` to launch the File search function when in **Issues**, +**Merge requests**, **Milestones**, even the project's settings. + +Start typing what you are searching for and watch the magic happen. With the +up/down arrows, you go up and down the results, with `Esc` you close the search +and go back to **Files**. + +## How it works + +The File finder feature is powered by the [Fuzzy filter] library. + +It implements a fuzzy search with highlight, and tries to provide intuitive +results by recognizing patterns that people use while searching. + +For example, consider the [GitLab CE repository][ce] and that we want to open +the `app/controllers/admin/deploy_keys_controller.rb` file. + +Using fuzzy search, we start by typing letters that get us closer to the file. + +**Protip:** To narrow down your search, include `/` in your search terms. + + + +[gh-9889]: https://github.com/gitlabhq/gitlabhq/pull/9889 "File finder pull request" +[fuzzy filter]: https://github.com/jeancroy/fuzzaldrin-plus "fuzzaldrin-plus on GitHub" +[ce]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master "GitLab CE repository" diff --git a/doc/workflow/forking/fork_button.png b/doc/workflow/forking/fork_button.png Binary files differdeleted file mode 100644 index def4266476a..00000000000 --- a/doc/workflow/forking/fork_button.png +++ /dev/null diff --git a/doc/workflow/forking/groups.png b/doc/workflow/forking/groups.png Binary files differdeleted file mode 100644 index 3ac64b3c8e7..00000000000 --- a/doc/workflow/forking/groups.png +++ /dev/null diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md index 8edf7c6ab3d..217a4a4012f 100644 --- a/doc/workflow/forking_workflow.md +++ b/doc/workflow/forking_workflow.md @@ -1,36 +1,59 @@ # Project forking workflow -Forking a project to your own namespace is useful if you have no write access to the project you want to contribute -to. If you do have write access or can request it we recommend working together in the same repository since it is simpler. -See our **[GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/)** article for more information about using -branches to work together. +Forking a project to your own namespace is useful if you have no write +access to the project you want to contribute to. If you do have write +access or can request it, we recommend working together in the same +repository since it is simpler. See our [GitLab Flow](gitlab_flow.md) +document more information about using branches to work together. ## Creating a fork -In order to create a fork of a project, all you need to do is click on the fork button located on the top right side -of the screen, close to the project's URL and right next to the stars button. +Forking a project is in most cases a two-step process. - -Once you do that you'll be presented with a screen where you can choose the namespace to fork to. Only namespaces -(groups and your own namespace) where you have write access to, will be shown. Click on the namespace to create your -fork there. +1. Click on the fork button located in the middle of the page or a project's + home page right next to the stars button. - +  -After the forking is done, you can start working on the newly created repository. There you will have full -[Owner](../permissions/permissions.md) access, so you can set it up as you please. + --- + +1. Once you do that, you'll be presented with a screen where you can choose + the namespace to fork to. Only namespaces (groups and your own + namespace) where you have write access to, will be shown. Click on the + namespace to create your fork there. + +  + + --- + + **Note:** + If the namespace you chose to fork the project to has another project with + the same path name, you will be presented with a warning that the forking + could not be completed. Try to resolve the error and repeat the forking + process. + +  + + --- + +After the forking is done, you can start working on the newly created +repository. There, you will have full [Owner](../permissions/permissions.md) +access, so you can set it up as you please. ## Merging upstream -Once you are ready to send your code back to the main project, you need to create a merge request. Choose your forked -project's main branch as the source and the original project's main branch as the destination and create the merge request. +Once you are ready to send your code back to the main project, you need +to create a merge request. Choose your forked project's main branch as +the source and the original project's main branch as the destination and +create the [merge request](merge_requests.md).  -You can then assign the merge request to someone to have them review your changes. Upon pressing the 'Accept Merge Request' -button, your changes will be added to the repository and branch you're merging into. +You can then assign the merge request to someone to have them review +your changes. Upon pressing the 'Accept Merge Request' button, your +changes will be added to the repository and branch you're merging into.  - +[gitlab flow]: https://about.gitlab.com/2014/09/29/gitlab-flow/ "GitLab Flow blog post" diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md index 8965e5b3654..be32f0c720b 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -152,9 +152,10 @@ The name of this branch should start with the issue number, for example '15-requ When you are done or want to discuss the code you open a merge request. This is an online place to discuss the change and review the code. -Creating a branch is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch. -If you create the merge request but do not assign it to anyone it is a 'work-in-process' merge request. +Opening a merge request is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch. +If you open the merge request but do not assign it to anyone it is a 'Work In Progress' merge request. These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet. +_Pro tip:_ Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready. When the author thinks the code is ready the merge request is assigned to reviewer. The reviewer presses the merge button when they think the code is ready for inclusion in the master branch. @@ -185,7 +186,7 @@ If you have an issue that spans across multiple repositories, the best thing is  -With git you can use an interactive rebase (rebase -i) to squash multiple commits into one and reorder them. +With git you can use an interactive rebase (`rebase -i`) to squash multiple commits into one and reorder them. This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. However you should never rebase commits you have pushed to a remote server. Somebody can have referred to the commits or cherry-picked them. diff --git a/doc/workflow/img/file_finder_find_button.png b/doc/workflow/img/file_finder_find_button.png Binary files differnew file mode 100644 index 00000000000..c5005d0d7ca --- /dev/null +++ b/doc/workflow/img/file_finder_find_button.png diff --git a/doc/workflow/img/file_finder_find_file.png b/doc/workflow/img/file_finder_find_file.png Binary files differnew file mode 100644 index 00000000000..58500f4c163 --- /dev/null +++ b/doc/workflow/img/file_finder_find_file.png diff --git a/doc/workflow/img/forking_workflow_choose_namespace.png b/doc/workflow/img/forking_workflow_choose_namespace.png Binary files differnew file mode 100644 index 00000000000..eefe5769554 --- /dev/null +++ b/doc/workflow/img/forking_workflow_choose_namespace.png diff --git a/doc/workflow/img/forking_workflow_fork_button.png b/doc/workflow/img/forking_workflow_fork_button.png Binary files differnew file mode 100644 index 00000000000..49e68d33e89 --- /dev/null +++ b/doc/workflow/img/forking_workflow_fork_button.png diff --git a/doc/workflow/img/forking_workflow_path_taken_error.png b/doc/workflow/img/forking_workflow_path_taken_error.png Binary files differnew file mode 100644 index 00000000000..7a3139506fe --- /dev/null +++ b/doc/workflow/img/forking_workflow_path_taken_error.png diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md index 77fb7ea7cd6..f693f430a42 100644 --- a/doc/workflow/importing/import_projects_from_github.md +++ b/doc/workflow/importing/import_projects_from_github.md @@ -5,11 +5,15 @@ enable the [GitHub integration][gh-import] in your GitLab instance._ At its current state, GitHub importer can import:
-- the repository description
-- the git repository data
-- the issues
-- the pull requests
-- the wiki pages
+- the repository description (introduced in GitLab 7.7)
+- the git repository data (introduced in GitLab 7.7)
+- the issues (introduced in GitLab 7.7)
+- the pull requests (introduced in GitLab 8.4)
+- the wiki pages (introduced in GitLab 8.4)
+
+It is not yet possible to import your labels, milestones and cross-repository
+pull requests (those from forks). We are working on improving this in the near
+future.
The importer page is visible when you [create a new project][new-project].
Click on the **GitHub** link and you will be redirected to GitHub for
@@ -35,12 +39,6 @@ The importer will create any new namespaces if they don't exist or in the case the namespace is taken, the project will be imported on the user's
namespace.
-### Note
-
-When you import your projects from GitHub, it is not possible to keep your
-labels, milestones, and cross-repository pull requests. We are working on
-improving this in the near future.
-
[gh-import]: ../../integration/github.md "GitHub integration"
[ee-gh]: http://doc.gitlab.com/ee/integration/github.html "GitHub integration for GitLab EE"
[new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"
diff --git a/doc/workflow/protected_branches.md b/doc/workflow/protected_branches.md index 0adf9f8e3e8..fdf9a8d391c 100644 --- a/doc/workflow/protected_branches.md +++ b/doc/workflow/protected_branches.md @@ -1,6 +1,6 @@ # Protected branches -Permission in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. +Permissions in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. To prevent people from messing with history or pushing code without review, we've created protected branches. |
