diff options
| author | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-03-18 14:31:33 +0200 |
|---|---|---|
| committer | Achilleas Pipinellis <axilleas@axilleas.me> | 2016-03-18 14:31:33 +0200 |
| commit | 4d3e8ceea562683a8ee3a87a45ece6c476558446 (patch) | |
| tree | a83c195a72ac7e32edb4888e733792302c13505f /doc | |
| parent | 11dda8db29a4843026464c0a61f65ada20646e3b (diff) | |
| parent | dadd28e317ace1e3d3a2a02926eb352832b97f08 (diff) | |
| download | gitlab-ce-4d3e8ceea562683a8ee3a87a45ece6c476558446.tar.gz | |
Merge branch 'master' into docs_select_version_to_install
Diffstat (limited to 'doc')
236 files changed, 7354 insertions, 1818 deletions
diff --git a/doc/README.md b/doc/README.md index d9ef5051e3a..08d0a6a5bfb 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,62 +3,32 @@ ## User documentation - [API](api/README.md) Automate GitLab via a simple and powerful API. +- [CI](ci/README.md) - [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab. - [GitLab Basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab. - [Importing to GitLab](workflow/importing/README.md). - [Markdown](markdown/markdown.md) GitLab's advanced formatting system. - [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab -- [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do. +- [Permissions](permissions/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do. - [Profile Settings](profile/README.md) - [Project Services](project_services/project_services.md) Integrate a project with external services, such as CI and chat. - [Public access](public_access/public_access.md) Learn how you can allow public and internal access to projects. - [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects. -- [Web hooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project. +- [Webhooks](web_hooks/web_hooks.md) Let GitLab notify you when new code has been pushed to your project. - [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN. -## CI Documentation - -- [Quick Start](ci/quick_start/README.md) -- [Configuring project (.gitlab-ci.yml)](ci/yaml/README.md) -- [Configuring runner](ci/runners/README.md) -- [Configuring deployment](ci/deployment/README.md) -- [Using Docker Images](ci/docker/using_docker_images.md) -- [Using Docker Build](ci/docker/using_docker_build.md) -- [Using Variables](ci/variables/README.md) -- [Using SSH keys](ci/ssh_keys/README.md) -- [User permissions](ci/permissions/README.md) -- [API](ci/api/README.md) -- [Triggering builds through the API](ci/triggers/README.md) - -### CI Languages - -- [Testing PHP](ci/languages/php.md) - -### CI Services - -- [Using MySQL](ci/services/mysql.md) -- [Using PostgreSQL](ci/services/postgres.md) -- [Using Redis](ci/services/redis.md) -- [Using Other Services](ci/docker/using_docker_images.md#how-to-use-other-images-as-services) - -### CI Examples - -- [Test and deploy Ruby applications to Heroku](ci/examples/test-and-deploy-ruby-application-to-heroku.md) -- [Test and deploy Python applications to Heroku](ci/examples/test-and-deploy-python-application-to-heroku.md) -- [Test Clojure applications](ci/examples/test-clojure-application.md) -- Help your favorite programming language and GitLab by sending a merge request with a guide for that language. - ## Administrator documentation -- [Custom git hooks](hooks/custom_hooks.md) Custom git hooks (on the filesystem) for when web hooks aren't enough. +- [Custom git hooks](hooks/custom_hooks.md) Custom git hooks (on the filesystem) for when webhooks 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. - [Log system](logs/logs.md) Log system. -- [Environmental Variables](administration/environment_variables.md) to configure GitLab. +- [Environment Variables](administration/environment_variables.md) to configure GitLab. - [Operations](operations/README.md) Keeping GitLab up and running -- [Raketasks](raketasks/README.md) Backups, maintenance, automatic web hook setup and the importing of projects. +- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects. - [Security](security/README.md) Learn what you can do to further secure your GitLab instance. - [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed. - [Update](update/README.md) Update guides to upgrade your installation. @@ -66,9 +36,13 @@ - [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 +- [Documentation styleguide](development/doc_styleguide.md) Use this styleguide if you are + contributing to documentation. - [Development](development/README.md) Explains the architecture and the guidelines for shell commands. - [Legal](legal/README.md) Contributor license agreements. - [Release](release/README.md) How to make the monthly and security releases. diff --git a/doc/administration/enviroment_variables.md b/doc/administration/enviroment_variables.md deleted file mode 100644 index 7d8f9d29eef..00000000000 --- a/doc/administration/enviroment_variables.md +++ /dev/null @@ -1,48 +0,0 @@ -# Environment Variables - -## Introduction - -Commonly people configure GitLab via the gitlab.rb configuration file in the Omnibus package. - -But if you prefer to use environment variables we allow that too. - -## Supported environment variables - -Variable | Type | Explanation --------- | ---- | ----------- -GITLAB_ROOT_PASSWORD | string | sets the password for the `root` user on installation -GITLAB_HOST | url | hostname of the GitLab server includes http or https -RAILS_ENV | production / development / staging / test | Rails environment -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 - -## Complete database variables - -As explained in the [Heroku documentation](https://devcenter.heroku.com/articles/rails-database-connection-behavior) the DATABASE_URL doesn't let you set: - -- adapter -- database -- username -- password -- host -- port - -To do so please `cp config/database.yml.env config/database.yml` and use the following variables: - -Variable | Default ---- | --- -GITLAB_DATABASE_ADAPTER | postgresql -GITLAB_DATABASE_ENCODING | unicode -GITLAB_DATABASE_DATABASE | gitlab_#{ENV['RAILS_ENV'] -GITLAB_DATABASE_POOL | 10 -GITLAB_DATABASE_USERNAME | root -GITLAB_DATABASE_PASSWORD | -GITLAB_DATABASE_HOST | localhost -GITLAB_DATABASE_PORT | 5432 - -## Other variables - -We welcome merge requests to make more settings configurable via variables. -Please stick to the naming scheme "GITLAB_#{name 1_settings.rb in upper case}". diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md new file mode 100644 index 00000000000..43ab153d76d --- /dev/null +++ b/doc/administration/environment_variables.md @@ -0,0 +1,61 @@ +# Environment Variables + +GitLab exposes certain environment variables which can be used to override +their defaults values. + +People usually configure GitLab via `/etc/gitlab/gitlab.rb` for Omnibus +installations, or `gitlab.yml` for installations from source. + +Below you will find the supported environment variables which you can use to +override certain values. + +## Supported environment variables + +Variable | Type | Description +-------- | ---- | ----------- +`GITLAB_ROOT_PASSWORD` | string | Sets the password for the `root` user on installation +`GITLAB_HOST` | string | The full URL of the GitLab server (including `http://` or `https://`) +`RAILS_ENV` | string | The Rails environment; can be one of `production`, `development`, `staging` or `test` +`DATABASE_URL` | string | The database URL; is of the form: `postgresql://localhost/blog_development` +`GITLAB_EMAIL_FROM` | string | The e-mail address used in the "From" field in e-mails sent by GitLab +`GITLAB_EMAIL_DISPLAY_NAME` | string | The name used in the "From" field in e-mails sent by GitLab +`GITLAB_EMAIL_REPLY_TO` | string | The e-mail address used in the "Reply-To" field in e-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 + +The recommended way of specifying your database connection information is to set +the `DATABASE_URL` environment variable. This variable only holds connection +information (`adapter`, `database`, `username`, `password`, `host` and `port`), +but not behavior information (`encoding`, `pool`). If you don't want to use +`DATABASE_URL` and/or want to set database behavior information, you will have +to either: + +- copy our template file: `cp config/database.yml.env config/database.yml`, or +- set a value for some `GITLAB_DATABASE_XXX` variables + +The list of `GITLAB_DATABASE_XXX` variables that you can set is: + +Variable | Default value | Overridden by `DATABASE_URL`? +-------- | ------------- | ----------------------------- +`GITLAB_DATABASE_ADAPTER` | `postgresql` (for MySQL use `mysql2`) | Yes +`GITLAB_DATABASE_DATABASE` | `gitlab_#{ENV['RAILS_ENV']` | Yes +`GITLAB_DATABASE_USERNAME` | `root` | Yes +`GITLAB_DATABASE_PASSWORD` | None | Yes +`GITLAB_DATABASE_HOST` | `localhost` | Yes +`GITLAB_DATABASE_PORT` | `5432` | Yes +`GITLAB_DATABASE_ENCODING` | `unicode` | No +`GITLAB_DATABASE_POOL` | `10` | No + +## Adding more variables + +We welcome merge requests to make more settings configurable via variables. +Please make changes in the `config/initializers/1_settings.rb` file and stick +to the naming scheme `GITLAB_#{name in 1_settings.rb in upper case}`. + +## Omnibus configuration + +It's possible to preconfigure the GitLab docker image by adding the environment +variable `GITLAB_OMNIBUS_CONFIG` to the `docker run` command. +For more information see the ['preconfigure-docker-container' section in the Omnibus documentation](http://doc.gitlab.com/omnibus/docker/#preconfigure-docker-container). 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 25a31b235cc..7629ef294ac 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 @@ -23,17 +29,20 @@ - [Namespaces](namespaces.md) - [Settings](settings.md) - [Keys](keys.md) +- [Builds](builds.md) +- [Build triggers](build_triggers.md) +- [Build Variables](build_variables.md) +- [Runners](runners.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 { @@ -41,71 +50,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 { @@ -113,7 +134,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 { @@ -121,94 +143,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/build_triggers.md b/doc/api/build_triggers.md new file mode 100644 index 00000000000..4a12e962b62 --- /dev/null +++ b/doc/api/build_triggers.md @@ -0,0 +1,108 @@ +# Build triggers + +You can read more about [triggering builds through the API](../ci/triggers/README.md). + +## List project triggers + +Get a list of project's build triggers. + +``` +GET /projects/:id/triggers +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +``` +curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" +``` + +```json +[ + { + "created_at": "2015-12-23T16:24:34.716Z", + "deleted_at": null, + "last_used": "2016-01-04T15:41:21.986Z", + "token": "fbdb730c2fbdb095a0862dbd8ab88b", + "updated_at": "2015-12-23T16:24:34.716Z" + }, + { + "created_at": "2015-12-23T16:25:56.760Z", + "deleted_at": null, + "last_used": null, + "token": "7b9148c158980bbd9bcea92c17522d", + "updated_at": "2015-12-23T16:25:56.760Z" + } +] +``` + +## Get trigger details + +Get details of project's build trigger. + +``` +GET /projects/:id/triggers/:token +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|--------------------------| +| `id` | integer | yes | The ID of a project | +| `token` | string | yes | The `token` of a trigger | + +``` +curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" +``` + +```json +{ + "created_at": "2015-12-23T16:25:56.760Z", + "deleted_at": null, + "last_used": null, + "token": "7b9148c158980bbd9bcea92c17522d", + "updated_at": "2015-12-23T16:25:56.760Z" +} +``` + +## Create a project trigger + +Create a build trigger for a project. + +``` +POST /projects/:id/triggers +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|--------------------------| +| `id` | integer | yes | The ID of a project | + +``` +curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers" +``` + +```json +{ + "created_at": "2016-01-07T09:53:58.235Z", + "deleted_at": null, + "last_used": null, + "token": "6d056f63e50fe6f8c5f8f4aa10edb7", + "updated_at": "2016-01-07T09:53:58.235Z" +} +``` + +## Remove a project trigger + +Remove a project's build trigger. + +``` +DELETE /projects/:id/triggers/:token +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|--------------------------| +| `id` | integer | yes | The ID of a project | +| `token` | string | yes | The `token` of a project | + +``` +curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/triggers/7b9148c158980bbd9bcea92c17522d" +``` diff --git a/doc/api/build_variables.md b/doc/api/build_variables.md new file mode 100644 index 00000000000..b96f1bdac8a --- /dev/null +++ b/doc/api/build_variables.md @@ -0,0 +1,128 @@ +# Build Variables + +## List project variables + +Get list of a project's build variables. + +``` +GET /projects/:id/variables +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +``` +curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" +``` + +```json +[ + { + "key": "TEST_VARIABLE_1", + "value": "TEST_1" + }, + { + "key": "TEST_VARIABLE_2", + "value": "TEST_2" + } +] +``` + +## Show variable details + +Get the details of a project's specific build variable. + +``` +GET /projects/:id/variables/:key +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|-----------------------| +| `id` | integer | yes | The ID of a project | +| `key` | string | yes | The `key` of a variable | + +``` +curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/TEST_VARIABLE_1" +``` + +```json +{ + "key": "TEST_VARIABLE_1", + "value": "TEST_1" +} +``` + +## Create variable + +Create a new build variable. + +``` +POST /projects/:id/variables +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|-----------------------| +| `id` | integer | yes | The ID of a project | +| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | +| `value` | string | yes | The `value` of a variable | + +``` +curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables" -F "key=NEW_VARIABLE" -F "value=new value" +``` + +```json +{ + "key": "NEW_VARIABLE", + "value": "new value" +} +``` + +## Update variable + +Update a project's build variable. + +``` +PUT /projects/:id/variables/:key +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|-------------------------| +| `id` | integer | yes | The ID of a project | +| `key` | string | yes | The `key` of a variable | +| `value` | string | yes | The `value` of a variable | + +``` +curl -X PUT -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/NEW_VARIABLE" -F "value=updated value" +``` + +```json +{ + "key": "NEW_VARIABLE", + "value": "updated value" +} +``` + +## Remove variable + +Remove a project's build variable. + +``` +DELETE /projects/:id/variables/:key +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|-------------------------| +| `id` | integer | yes | The ID of a project | +| `key` | string | yes | The `key` of a variable | + +``` +curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/variables/VARIABLE_1" +``` + +```json +{ + "key": "VARIABLE_1", + "value": "VALUE_1" +} +``` diff --git a/doc/api/builds.md b/doc/api/builds.md new file mode 100644 index 00000000000..4c0a47d1ea0 --- /dev/null +++ b/doc/api/builds.md @@ -0,0 +1,421 @@ +# Builds API + +## List project builds + +Get a list of builds in a project. + +``` +GET /projects/:id/builds +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `scope` | string **or** array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds" +``` + +Example of response + +```json +[ + { + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2015-12-24T15:51:21.802Z", + "artifacts_file": { + "filename": "artifacts.zip", + "size": 1000 + }, + "finished_at": "2015-12-24T17:54:27.895Z", + "id": 7, + "name": "teaspoon", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": "2015-12-24T17:54:27.722Z", + "status": "failed", + "tag": false, + "user": { + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "bio": null, + "created_at": "2015-12-21T13:14:24.077Z", + "id": 1, + "is_admin": true, + "linkedin": "", + "name": "Administrator", + "skype": "", + "state": "active", + "twitter": "", + "username": "root", + "web_url": "http://gitlab.dev/u/root", + "website_url": "" + } + }, + { + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2015-12-24T15:51:21.727Z", + "artifacts_file": null, + "finished_at": "2015-12-24T17:54:24.921Z", + "id": 6, + "name": "spinach:other", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": "2015-12-24T17:54:24.729Z", + "status": "failed", + "tag": false, + "user": { + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "bio": null, + "created_at": "2015-12-21T13:14:24.077Z", + "id": 1, + "is_admin": true, + "linkedin": "", + "name": "Administrator", + "skype": "", + "state": "active", + "twitter": "", + "username": "root", + "web_url": "http://gitlab.dev/u/root", + "website_url": "" + } + } +] +``` + +## List commit builds + +Get a list of builds for specific commit in a project. + +``` +GET /projects/:id/repository/commits/:sha/builds +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `sha` | string | yes | The SHA id of a commit | +| `scope` | string **or** array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds" +``` + +Example of response + +```json +[ + { + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2016-01-11T10:13:33.506Z", + "artifacts_file": null, + "finished_at": "2016-01-11T10:14:09.526Z", + "id": 69, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": null, + "status": "canceled", + "tag": false, + "user": null + }, + { + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2015-12-24T15:51:21.957Z", + "artifacts_file": null, + "finished_at": "2015-12-24T17:54:33.913Z", + "id": 9, + "name": "brakeman", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": "2015-12-24T17:54:33.727Z", + "status": "failed", + "tag": false, + "user": { + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "bio": null, + "created_at": "2015-12-21T13:14:24.077Z", + "id": 1, + "is_admin": true, + "linkedin": "", + "name": "Administrator", + "skype": "", + "state": "active", + "twitter": "", + "username": "root", + "web_url": "http://gitlab.dev/u/root", + "website_url": "" + } + } +] +``` + +## Get a single build + +Get a single build of a project + +``` +GET /projects/:id/builds/:build_id +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8" +``` + +Example of response + +```json +{ + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2015-12-24T15:51:21.880Z", + "artifacts_file": null, + "finished_at": "2015-12-24T17:54:31.198Z", + "id": 8, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": "2015-12-24T17:54:30.733Z", + "status": "failed", + "tag": false, + "user": { + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "bio": null, + "created_at": "2015-12-21T13:14:24.077Z", + "id": 1, + "is_admin": true, + "linkedin": "", + "name": "Administrator", + "skype": "", + "state": "active", + "twitter": "", + "username": "root", + "web_url": "http://gitlab.dev/u/root", + "website_url": "" + } +} +``` + +## Get build artifacts + +> [Introduced][ce-2893] in GitLab 8.5 + +Get build artifacts of a project + +``` +GET /projects/:id/builds/:build_id/artifacts +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8/artifacts" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 200 | Serves the artifacts file | +| 404 | Build not found or no artifacts | + +[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 + +## Cancel a build + +Cancel a single build of a project + +``` +POST /projects/:id/builds/:build_id/cancel +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel" +``` + +Example of response + +```json +{ + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2016-01-11T10:13:33.506Z", + "artifacts_file": null, + "finished_at": "2016-01-11T10:14:09.526Z", + "id": 69, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": null, + "status": "canceled", + "tag": false, + "user": null +} +``` + +## Retry a build + +Retry a single build of a project + +``` +POST /projects/:id/builds/:build_id/retry +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry" +``` + +Example of response + +```json +{ + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "created_at": "2016-01-11T10:13:33.506Z", + "artifacts_file": null, + "finished_at": null, + "id": 69, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "started_at": null, + "status": "pending", + "tag": false, + "user": null +} +``` + +## Erase a build + +Erase a single build of a project (remove build artifacts and a build trace) + +``` +POST /projects/:id/builds/:build_id/erase +``` + +Parameters + +| Attribute | Type | required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +Example of request + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/erase" +``` + +Example of response + +```json +{ + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "download_url": null, + "id": 69, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "created_at": "2016-01-11T10:13:33.506Z", + "started_at": "2016-01-11T10:13:33.506Z", + "finished_at": "2016-01-11T10:15:10.506Z", + "status": "failed", + "tag": false, + "user": null +} +``` diff --git a/doc/api/commits.md b/doc/api/commits.md index 93d62b751e6..6341440c58b 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,64 @@ 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. + +### Get the status of a commit Get the statuses of a commit in a project. @@ -168,75 +223,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_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md index 1a5a458905e..3ad836f51b5 100644 --- a/doc/api/deploy_key_multiple_projects.md +++ b/doc/api/deploy_key_multiple_projects.md @@ -1,25 +1,29 @@ # Adding deploy keys to multiple projects -If you want to easily add the same deploy key to multiple projects in the same group, this can be achieved quite easily with the API. +If you want to easily add the same deploy key to multiple projects in the same +group, this can be achieved quite easily with the API. -First, find the ID of the projects you're interested in, by either listing all projects: +First, find the ID of the projects you're interested in, by either listing all +projects: ``` -curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/projects +curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/projects ``` -Or finding the id of a group and then listing all projects in that group: +Or finding the ID of a group and then listing all projects in that group: ``` -curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/groups +curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/groups # For group 1234: -curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/groups/1234 +curl -H 'PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK' https://gitlab.example.com/api/v3/groups/1234 ``` With those IDs, add the same deploy key to all: + ``` for project_id in 321 456 987; do - curl -X POST --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' --header 'PRIVATE-TOKEN: abcdef' https://gitlab.com/api/v3/projects/${project_id}/keys + curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" \ + --data '{"title": "my key", "key": "ssh-rsa AAAA..."}' https://gitlab.example.com/api/v3/projects/${project_id}/keys done ``` 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..5c527d55481 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -2,7 +2,7 @@ ## List merge requests -Get all merge requests for this project. +Get all merge requests for this project. The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, or `merged`) or all of them (`all`). The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests. @@ -49,8 +49,24 @@ Parameters: "state": "active", "created_at": "2012-04-29T08:46:00Z" }, + "source_project_id": "2", + "target_project_id": "3", + "labels": [ ], "description":"fixed login page css paddings", - "work_in_progress": false + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 3, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ] ``` @@ -60,7 +76,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: @@ -95,8 +111,24 @@ Parameters: "state": "active", "created_at": "2012-04-29T08:46:00Z" }, + "source_project_id": "2", + "target_project_id": "3", + "labels": [ ], "description":"fixed login page css paddings", - "work_in_progress": false + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 3, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ``` @@ -105,7 +137,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 +174,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: @@ -156,8 +188,6 @@ Parameters: "iid": 1, "project_id": 4, "title": "Blanditiis beatae suscipit hic assumenda et molestias nisi asperiores repellat et.", - "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.", - "work_in_progress": false, "state": "reopened", "created_at": "2015-02-02T19:49:39.159Z", "updated_at": "2015-02-02T20:08:49.959Z", @@ -182,6 +212,8 @@ Parameters: "source_project_id": 4, "target_project_id": 4, "labels": [ ], + "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.", + "work_in_progress": false, "milestone": { "id": 5, "iid": 1, @@ -193,6 +225,8 @@ Parameters: "updated_at": "2015-02-02T19:49:26.013Z", "due_date": null }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged", "changes": [ { "old_path": "VERSION", @@ -225,6 +259,7 @@ Parameters: - `description` (optional) - Description of MR - `target_project_id` (optional) - The target project (numeric id) - `labels` (optional) - Labels for MR as a comma-separated list +- `milestone_id` (optional) - Milestone ID ```json { @@ -252,7 +287,24 @@ Parameters: "state": "active", "created_at": "2012-04-29T08:46:00Z" }, - "description":"fixed login page css paddings" + "source_project_id": 4, + "target_project_id": 4, + "labels": [ ], + "description":"fixed login page css paddings", + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 4, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ``` @@ -264,7 +316,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: @@ -277,6 +329,7 @@ Parameters: - `description` - Description of MR - `state_event` - New state (close|reopen|merge) - `labels` (optional) - Labels for MR as a comma-separated list +- `milestone_id` (optional) - Milestone ID ```json { @@ -284,7 +337,6 @@ Parameters: "target_branch": "master", "project_id": 3, "title": "test1", - "description": "description1", "state": "opened", "upvotes": 0, "downvotes": 0, @@ -303,7 +355,25 @@ Parameters: "name": "Administrator", "state": "active", "created_at": "2012-04-29T08:46:00Z" - } + }, + "source_project_id": 4, + "target_project_id": 4, + "labels": [ ], + "description": "description1", + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 4, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ``` @@ -323,7 +393,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: @@ -359,7 +429,25 @@ Parameters: "name": "Administrator", "state": "active", "created_at": "2012-04-29T08:46:00Z" - } + }, + "source_project_id": 4, + "target_project_id": 4, + "labels": [ ], + "description":"fixed login page css paddings", + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 4, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ``` @@ -373,7 +461,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: @@ -387,7 +475,7 @@ Parameters: "source_branch": "test1", "project_id": 3, "title": "test1", - "state": "merged", + "state": "opened", "upvotes": 0, "downvotes": 0, "author": { @@ -405,70 +493,90 @@ Parameters: "name": "Administrator", "state": "active", "created_at": "2012-04-29T08:46:00Z" - } + }, + "source_project_id": 4, + "target_project_id": 4, + "labels": [ ], + "description":"fixed login page css paddings", + "work_in_progress": false, + "milestone": { + "id": 5, + "iid": 1, + "project_id": 4, + "title": "v2.0", + "description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.", + "state": "closed", + "created_at": "2015-02-02T19:49:26.013Z", + "updated_at": "2015-02-02T19:49:26.013Z", + "due_date": null + }, + "merge_when_build_succeeds": true, + "merge_status": "can_be_merged" } ``` -## Post comment to MR +## Comments on merge requests -Adds a comment to a merge request. +Comments are done via the [notes](notes.md) resource. -``` -POST /projects/:id/merge_request/:merge_request_id/comments -``` +## List issues that will close on merge -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request -- `note` (required) - Text of comment +Get all the issues that would be closed by merging the provided merge request. -```json -{ - "note": "text1" -} +``` +GET /projects/:id/merge_requests/:merge_request_id/closes_issues ``` -## Get the comments on a MR - -Gets all the comments associated with a merge request. +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `merge_request_id` | integer | yes | The ID of the merge request | +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/76/merge_requests/1/closes_issues ``` -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 +Example response: ```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" - } - } + { + "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" : [] + }, ] ``` - -## Comments on merge requets - -Comments are done via the notes 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 0ca81ffd49e..3703f4b327a 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 @@ -76,7 +77,12 @@ Parameters: "updated_at": "2013-09-30T13: 46: 02Z" }, "archived": false, - "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png" + "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png", + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8547b1dc37721d05889db52fa2f02", + "public_builds": true }, { "id": 6, @@ -129,7 +135,12 @@ Parameters: } }, "archived": false, - "avatar_url": null + "avatar_url": null, + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8547b1dc37721d05889db52fa2f02", + "public_builds": true } ] ``` @@ -145,6 +156,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 @@ -160,6 +172,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 @@ -175,6 +188,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 @@ -244,7 +258,11 @@ Parameters: } }, "archived": false, - "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png" + "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b" } ``` @@ -409,6 +427,7 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) +- `public_builds` (optional) ### Create project for user @@ -431,6 +450,7 @@ Parameters: - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) - `import_url` (optional) +- `public_builds` (optional) ### Edit project @@ -454,6 +474,7 @@ Parameters: - `snippets_enabled` (optional) - `public` (optional) - if `true` same as setting visibility_level = 20 - `visibility_level` (optional) +- `public_builds` (optional) On success, method returns 200 with the updated project. If parameters are invalid, 400 is returned. @@ -482,6 +503,34 @@ Parameters: - `id` (required) - The ID of a project +## Uploads + +### Upload a file + +Uploads a file to the specified project to be used in an issue or merge request description, or a comment. + +``` +POST /projects/:id/uploads +``` + +Parameters: + +- `id` (required) - The ID of the project +- `file` (required) - The file to be uploaded + +```json +{ + "alt": "dk", + "url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png", + "is_image": true, + "markdown": "" +} +``` + +**Note**: The returned `url` is relative to the project path. +In Markdown contexts, the link is automatically expanded when the format in `markdown` is used. + + ## Team members ### List project team members @@ -570,6 +619,20 @@ Revoking team membership for a user who is not currently a team member is consid Please note that the returned JSON currently differs slightly. Thus you should not rely on the returned JSON structure. +### Share project with group + +Allow to share project with group. + +``` +POST /projects/:id/share +``` + +Parameters: + +- `id` (required) - The ID of a project +- `group_id` (required) - The ID of a group +- `group_access` (required) - Level of permissions for sharing + ## Hooks Also called Project Hooks and Webhooks. diff --git a/doc/api/runners.md b/doc/api/runners.md new file mode 100644 index 00000000000..cc6c6b7cb2f --- /dev/null +++ b/doc/api/runners.md @@ -0,0 +1,322 @@ +# Runners API + +> [Introduced][ce-2640] in GitLab 8.5 + +[ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640 + +## List owned runners + +Get a list of specific runners available to the user. + +``` +GET /runners +GET /runners?scope=active +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `scope` | string | no | The scope of specific runners to show, one of: `active`, `paused`, `online`; showing all runners if none provided | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners" +``` + +Example response: + +```json +[ + { + "active": true, + "description": "test-1-20150125", + "id": 6, + "is_shared": false, + "name": null + }, + { + "active": true, + "description": "test-2-20150125", + "id": 8, + "is_shared": false, + "name": null + } +] +``` + +## List all runners + +Get a list of all runners in the GitLab instance (specific and shared). Access +is restricted to users with `admin` privileges. + +``` +GET /runners/all +GET /runners/all?scope=online +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `scope` | string | no | The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`; showing all runners if none provided | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/all" +``` + +Example response: + +```json +[ + { + "active": true, + "description": "shared-runner-1", + "id": 1, + "is_shared": true, + "name": null + }, + { + "active": true, + "description": "shared-runner-2", + "id": 3, + "is_shared": true, + "name": null + }, + { + "active": true, + "description": "test-1-20150125", + "id": 6, + "is_shared": false, + "name": null + }, + { + "active": true, + "description": "test-2-20150125", + "id": 8, + "is_shared": false, + "name": null + } +] +``` + +## Get runner's details + +Get details of a runner. + +``` +GET /runners/:id +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a runner | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6" +``` + +Example response: + +```json +{ + "active": true, + "architecture": null, + "description": "test-1-20150125", + "id": 6, + "is_shared": false, + "contacted_at": "2016-01-25T16:39:48.066Z", + "name": null, + "platform": null, + "projects": [ + { + "id": 1, + "name": "GitLab Community Edition", + "name_with_namespace": "GitLab.org / GitLab Community Edition", + "path": "gitlab-ce", + "path_with_namespace": "gitlab-org/gitlab-ce" + } + ], + "token": "205086a8e3b9a2b818ffac9b89d102", + "revision": null, + "tag_list": [ + "ruby", + "mysql" + ], + "version": null +} +``` + +## Update runner's details + +Update details of a runner. + +``` +PUT /runners/:id +``` + +| Attribute | Type | Required | Description | +|---------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a runner | +| `description` | string | no | The description of a runner | +| `active` | boolean | no | The state of a runner; can be set to `true` or `false` | +| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | + +``` +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6" -F "description=test-1-20150125-test" -F "tag_list=ruby,mysql,tag1,tag2" +``` + +Example response: + +```json +{ + "active": true, + "architecture": null, + "description": "test-1-20150125-test", + "id": 6, + "is_shared": false, + "contacted_at": "2016-01-25T16:39:48.066Z", + "name": null, + "platform": null, + "projects": [ + { + "id": 1, + "name": "GitLab Community Edition", + "name_with_namespace": "GitLab.org / GitLab Community Edition", + "path": "gitlab-ce", + "path_with_namespace": "gitlab-org/gitlab-ce" + } + ], + "token": "205086a8e3b9a2b818ffac9b89d102", + "revision": null, + "tag_list": [ + "ruby", + "mysql", + "tag1", + "tag2" + ], + "version": null +} +``` + +## Remove a runner + +Remove a runner. + +``` +DELETE /runners/:id +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a runner | + +``` +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6" +``` + +Example response: + +```json +{ + "active": true, + "description": "test-1-20150125-test", + "id": 6, + "is_shared": false, + "name": null, +} +``` + +## List project's runners + +List all runners (specific and shared) available in the project. Shared runners +are listed if at least one shared runner is defined **and** shared runners +usage is enabled in the project's settings. + +``` +GET /projects/:id/runners +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners" +``` + +Example response: + +```json +[ + { + "active": true, + "description": "test-2-20150125", + "id": 8, + "is_shared": false, + "name": null + }, + { + "active": true, + "description": "development_runner", + "id": 5, + "is_shared": true, + "name": null + } +] +``` + +## Enable a runner in project + +Enable an available specific runner in the project. + +``` +POST /projects/:id/runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `runner_id` | integer | yes | The ID of a runner | + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners" -F "runner_id=9" +``` + +Example response: + +```json +{ + "active": true, + "description": "test-2016-02-01", + "id": 9, + "is_shared": false, + "name": null +} +``` + +## Disable a runner from project + +Disable a specific runner from the project. It works only if the project isn't +the only project associated with the specified runner. If so, an error is +returned. Use the [Remove a runner](#remove-a-runner) call instead. + +``` +DELETE /projects/:id/runners/:runner_id +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `runner_id` | integer | yes | The ID of a runner | + +``` +curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners/9" +``` + +Example response: + +```json +{ + "active": true, + "description": "test-2016-02-01", + "id": 9, + "is_shared": false, + "name": null +} +``` diff --git a/doc/api/session.md b/doc/api/session.md index 47c1c8a7a49..71e93d0bb0a 100644 --- a/doc/api/session.md +++ b/doc/api/session.md @@ -1,39 +1,47 @@ # Session -Login to get private token +You can login with both GitLab and LDAP credentials in order to obtain the +private token. ``` POST /session ``` -Parameters: +| Attribute | Type | Required | Description | +| ---------- | ------- | -------- | -------- | +| `login` | string | yes | The username of the user| +| `email` | string | yes if login is not provided | The email of the user | +| `password` | string | yes | The password of the user | -- `login` (required) - The login of user -- `email` (required if login missing) - The email of user -- `password` (required) - Valid password - -**You can login with both GitLab and LDAP credentials now** +```bash +curl -X POST "https://gitlab.example.com/api/v3/session?login=john_smith&password=strongpassw0rd" +``` +Example response: ```json { - "id": 1, - "username": "john_smith", - "email": "john@example.com", "name": "John Smith", - "private_token": "dd34asd13as", - "blocked": false, - "created_at": "2012-05-23T08:00:58Z", + "username": "john_smith", + "id": 32, + "state": "active", + "avatar_url": null, + "created_at": "2015-01-29T21:07:19.440Z", + "is_admin": true, "bio": null, "skype": "", "linkedin": "", "twitter": "", "website_url": "", - "dark_scheme": false, + "email": "john@example.com", "theme_id": 1, - "is_admin": false, + "color_scheme_id": 1, + "projects_limit": 10, + "current_sign_in_at": "2015-07-07T07:10:58.392Z", + "identities": [], "can_create_group": true, - "can_create_team": true, - "can_create_project": true + "can_create_project": true, + "two_factor_enabled": false, + "private_token": "9koXpg98eAheJpvBs5tK" } ``` 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/api/tags.md b/doc/api/tags.md index 085d387e824..17d12e9cc62 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -83,6 +83,26 @@ it will contain the annotation. It returns 200 if the operation succeed. In case of an error, 405 with an explaining error message is returned. +## Delete a tag + +Deletes a tag of a repository with given name. On success, this API method +returns 200 with the name of the deleted tag. If the tag does not exist, the +API returns 404. + +``` +DELETE /projects/:id/repository/tags/:tag_name +``` + +Parameters: + +- `id` (required) - The ID of a project +- `tag_name` (required) - The name of a tag + +```json +{ + "tag_name": "v4.3.0" +} +``` ## Create a new release diff --git a/doc/api/users.md b/doc/api/users.md index 66d2fd52526..383e7c76ab0 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -123,6 +123,13 @@ Parameters: "name": "John Smith", "state": "active", "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", + "created_at": "2012-05-23T08:00:58Z", + "is_admin": false, + "bio": null, + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "" } ``` @@ -144,6 +151,8 @@ Parameters: "name": "John Smith", "state": "active", "created_at": "2012-05-23T08:00:58Z", + "confirmed_at": "2012-05-23T08:00:58Z", + "last_sign_in_at": "2015-03-23T08:00:58Z", "bio": null, "skype": "", "linkedin": "", @@ -185,6 +194,7 @@ Parameters: - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false - `confirm` (optional) - Require confirmation - true (default) or false +- `external` (optional) - Flags the user as external - true or false(default) ## User modification @@ -210,6 +220,7 @@ Parameters: - `bio` - User's biography - `admin` (optional) - User is admin - true or false (default) - `can_create_group` (optional) - User can create groups - true or false +- `external` (optional) - Flags the user as external - true or false(default) Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would be more appropriate, @@ -551,7 +562,8 @@ Parameters: - `uid` (required) - id of specified user -Will return `200 OK` on success, or `404 User Not Found` is user cannot be found. +Will return `200 OK` on success, `404 User Not Found` is user cannot be found or +`403 Forbidden` when trying to block an already blocked user by LDAP synchronization. ## Unblock user @@ -565,4 +577,5 @@ Parameters: - `uid` (required) - id of specified user -Will return `200 OK` on success, or `404 User Not Found` is user cannot be found. +Will return `200 OK` on success, `404 User Not Found` is user cannot be found or +`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization. diff --git a/doc/ci/README.md b/doc/ci/README.md index a1f5513d88e..4abc45bf9bb 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,37 +1,18 @@ ## GitLab CI Documentation -### User documentation - -* [Quick Start](quick_start/README.md) -* [Configuring project (.gitlab-ci.yml)](yaml/README.md) -* [Configuring runner](runners/README.md) -* [Configuring deployment](deployment/README.md) -* [Using Docker Images](docker/using_docker_images.md) -* [Using Docker Build](docker/using_docker_build.md) -* [Using Variables](variables/README.md) -* [Using SSH keys](ssh_keys/README.md) -* [Triggering builds through the API](triggers/README.md) - -### Languages - -* [Testing PHP](languages/php.md) - -### Services - -* [Using MySQL](services/mysql.md) -* [Using PostgreSQL](services/postgres.md) -* [Using Redis](services/redis.md) -* [Using Other Services](docker/using_docker_images.md#how-to-use-other-images-as-services) - -### Examples - -+ [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) -+ [Test and deploy Ruby applications to Heroku](examples/test-and-deploy-ruby-application-to-heroku.md) -+ [Test and deploy Python applications to Heroku](examples/test-and-deploy-python-application-to-heroku.md) -+ [Test Clojure applications](examples/test-clojure-application.md) -+ Help your favorite programming language and GitLab by sending a merge request with a guide for that language. - -### Administrator documentation - -* [User permissions](permissions/README.md) -* [API](api/README.md) +### CI User documentation + +- [Get started with GitLab CI](quick_start/README.md) +- [CI examples for various languages](examples/README.md) +- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) +- [Learn how `.gitlab-ci.yml` works](yaml/README.md) +- [Configure a Runner, the application that runs your builds](runners/README.md) +- [Use Docker images with GitLab Runner](docker/using_docker_images.md) +- [Use CI to build Docker images](docker/using_docker_build.md) +- [Use variables in your `.gitlab-ci.yml`](variables/README.md) +- [Use SSH keys in your build environment](ssh_keys/README.md) +- [Trigger builds through the API](triggers/README.md) +- [Build artifacts](build_artifacts/README.md) +- [User permissions](permissions/README.md) +- [API](api/README.md) +- [CI services (linked docker containers)](services/README.md) diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md index cf9710ede57..aea808007fc 100644 --- a/doc/ci/api/README.md +++ b/doc/ci/api/README.md @@ -1,86 +1,22 @@ # GitLab CI API -## Resources - -- [Projects](projects.md) -- [Runners](runners.md) -- [Commits](commits.md) -- [Builds](builds.md) - - -## Authentication - -GitLab CI API uses different types of authentication depends on what API you use. -Each API document has section with information about authentication you need to use. - -GitLab CI API has 4 authentication methods: - -* GitLab user token & GitLab url -* GitLab CI project token -* GitLab CI runners registration token -* GitLab CI runner token - - -### Authentication #1: GitLab user token & GitLab url - -Authentication is done by -sending the `private-token` of a valid user and the `url` of an -authorized GitLab instance via a query string along with the API -request: - - GET http://gitlab.example.com/ci/api/v1/projects?private_token=QVy1PB7sTxfy4pqfZM1U&url=http://demo.gitlab.com/ +## Purpose -If preferred, you may instead send the `private-token` as a header in -your request: +Main purpose of GitLab CI API is to provide necessary data and context for +GitLab CI Runners. - curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://gitlab.example.com/ci/api/v1/projects?url=http://demo.gitlab.com/" +For consumer API take a look at this [documentation](../../api/README.md) where +you will find all relevant information. +## API Prefix -### Authentication #2: GitLab CI project token +Current CI API prefix is `/ci/api/v1`. -Each project in GitLab CI has it own token. -It can be used to get project commits and builds information. -You can use project token only for certain project. +You need to prepend this prefix to all examples in this documentation, like: -### Authentication #3: GitLab CI runners registration token + GET /ci/api/v1/builds/:id/artifacts -This token is not persisted and is generated on each application start. -It can be used only for registering new runners in system. You can find it on -GitLab CI Runners web page https://gitlab-ci.example.com/admin/runners - -### Authentication #4: GitLab CI runner token - -Every GitLab CI runner has it own token that allow it to receive and update -GitLab CI builds. This token exists of internal purposes and should be used only -by runners - -## JSON - -All API requests are serialized using JSON. You don't need to specify -`.json` at the end of API URL. - -## 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: +## Resources -- `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 +- [Builds](builds.md) +- [Runners](runners.md) diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md index 3b5008ccdb4..d100e261178 100644 --- a/doc/ci/api/builds.md +++ b/doc/ci/api/builds.md @@ -1,41 +1,73 @@ # Builds API -This API used by runners to receive and update builds. +API used by runners to receive and update builds. -__Authentication is done by runner token__ +_**Note:** This API is intended to be used only by Runners as their own +communication channel. For the consumer API see the +[Builds API](../../api/builds.md)._ + +## Authentication + +This API uses two types of authentication: + +1. Unique runner's token + + Token assigned to runner after it has been registered. + +2. Using build authorization token + + This is project's CI token that can be found in Continuous Integration + project settings. + + Build authorization token can be passed as a parameter or a value of + `BUILD-TOKEN` header. This method are interchangeable. ## Builds ### Runs oldest pending build by runner - POST /ci/builds/register + POST /ci/api/v1/builds/register Parameters: - * `token` (required) - The unique token of runner - -Returns: - -```json -{ - "id" : 79, - "commands" : "", - "path" : "", - "ref" : "", - "sha" : "", - "project_id" : 6, - "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", - "before_sha" : "" -} -``` + * `token` (required) - Unique runner token ### Update details of an existing build - PUT /ci/builds/:id + PUT /ci/api/v1/builds/:id Parameters: * `id` (required) - The ID of a project + * `token` (required) - Unique runner token * `state` (optional) - The state of a build * `trace` (optional) - The trace of a build + +### Upload artifacts to build + + POST /ci/api/v1/builds/:id/artifacts + +Parameters: + + * `id` (required) - The ID of a build + * `token` (required) - The build authorization token + * `file` (required) - Artifacts file + +### Download the artifacts file from build + + GET /ci/api/v1/builds/:id/artifacts + +Parameters: + + * `id` (required) - The ID of a build + * `token` (required) - The build authorization token + +### Remove the artifacts file from build + + DELETE /ci/api/v1/builds/:id/artifacts + +Parameters: + + * ` id` (required) - The ID of a build + * `token` (required) - The build authorization token diff --git a/doc/ci/api/commits.md b/doc/ci/api/commits.md deleted file mode 100644 index 4df7afc6c52..00000000000 --- a/doc/ci/api/commits.md +++ /dev/null @@ -1,101 +0,0 @@ -# Commits API - -__Authentication is done by GitLab CI project token__ - -## Commits - -### Retrieve all commits per project - -Get list of commits per project - - GET /ci/commits - -Parameters: - - * `project_id` (required) - The ID of a project - * `project_token` (requires) - Project token - * `page` (optional) - * `per_page` (optional) - items per request (default is 20) - -Returns: - -```json -[{ - "id": 3, - "ref": "master", - "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf", - "project_id": 2, - "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898", - "created_at": "2014-11-05T09:46:35.247Z", - "status": "success", - "finished_at": "2014-11-05T09:46:44.254Z", - "duration": 5.062692165374756, - "git_commit_message": "wow\n", - "git_author_name": "Administrator", - "git_author_email": "admin@example.com", - "builds": [{ - "id": 7, - "project_id": 2, - "ref": "master", - "status": "success", - "finished_at": "2014-11-05T09:46:44.254Z", - "created_at": "2014-11-05T09:46:35.259Z", - "updated_at": "2014-11-05T09:46:44.255Z", - "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf", - "started_at": "2014-11-05T09:46:39.192Z", - "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898", - "runner_id": 1, - "coverage": null, - "commit_id": 3 - }] -}] -``` - -### Create commit - -Inform GitLab CI about new commit you want it to build. - -__If commit already exists in GitLab CI it will not be created__ - - - POST /ci/commits - -Parameters: - - * `project_id` (required) - The ID of a project - * `project_token` (requires) - Project token - * `data` (required) - Push data. For example see comment in `lib/api/commits.rb` - -Returns: - -```json -{ - "id": 3, - "ref": "master", - "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf", - "project_id": 2, - "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898", - "created_at": "2014-11-05T09:46:35.247Z", - "status": "success", - "finished_at": "2014-11-05T09:46:44.254Z", - "duration": 5.062692165374756, - "git_commit_message": "wow\n", - "git_author_name": "Administrator", - "git_author_email": "admin@example.com", - "builds": [{ - "id": 7, - "project_id": 2, - "ref": "master", - "status": "success", - "finished_at": "2014-11-05T09:46:44.254Z", - "created_at": "2014-11-05T09:46:35.259Z", - "updated_at": "2014-11-05T09:46:44.255Z", - "sha": "65617dfc36761baa1f46a7006f2a88916f7f56cf", - "started_at": "2014-11-05T09:46:39.192Z", - "before_sha": "96906f2bceb04c7323f8514aa5ad8cb1313e2898", - "runner_id": 1, - "coverage": null, - "commit_id": 3 - }] -} -``` diff --git a/doc/ci/api/projects.md b/doc/ci/api/projects.md deleted file mode 100644 index 74a4c64d000..00000000000 --- a/doc/ci/api/projects.md +++ /dev/null @@ -1,149 +0,0 @@ -# Projects API - -This API is intended to aid in the setup and configuration of -projects on GitLab CI. - -__Authentication is done by GitLab user token & GitLab url__ - -## Projects - -### List Authorized Projects - -Lists all projects that the authenticated user has access to. - -``` -GET /ci/projects -``` - -Returns: - -```json - [ - { - "id" : 271, - "name" : "gitlabhq", - "timeout" : 1800, - "token" : "iPWx6WM4lhHNedGfBpPJNP", - "default_ref" : "master", - "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell", - "path" : "gitlab/gitlab-shell", - "always_build" : false, - "polling_interval" : null, - "public" : false, - "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", - "gitlab_id" : 3 - }, - { - "id" : 272, - "name" : "gitlab-ci", - "timeout" : 1800, - "token" : "iPWx6WM4lhHNedGfBpPJNP", - "default_ref" : "master", - "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell", - "path" : "gitlab/gitlab-shell", - "always_build" : false, - "polling_interval" : null, - "public" : false, - "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", - "gitlab_id" : 4 - } -] -``` - -### List Owned Projects - -Lists all projects that the authenticated user owns. - -``` -GET /ci/projects/owned -``` - -Returns: - -```json -[ - { - "id" : 272, - "name" : "gitlab-ci", - "timeout" : 1800, - "token" : "iPWx6WM4lhHNedGfBpPJNP", - "default_ref" : "master", - "gitlab_url" : "http://demo.gitlabhq.com/gitlab/gitlab-shell", - "path" : "gitlab/gitlab-shell", - "always_build" : false, - "polling_interval" : null, - "public" : false, - "ssh_url_to_repo" : "git@demo.gitlab.com:gitlab/gitlab-shell.git", - "gitlab_id" : 4 - } -] -``` - -### Single Project - -Returns information about a single project for which the user is -authorized. - - GET /ci/projects/:id - -Parameters: - - * `id` (required) - The ID of the GitLab CI project - -### Create Project - -Creates a GitLab CI project using GitLab project details. - - POST /ci/projects - -Parameters: - - * `name` (required) - The name of the project - * `gitlab_id` (required) - The ID of the project on the GitLab instance - * `default_ref` (optional) - The branch to run on (default to `master`) - -### Update Project - -Updates a GitLab CI project using GitLab project details that the -authenticated user has access to. - - PUT /ci/projects/:id - -Parameters: - - * `name` - The name of the project - * `default_ref` - The branch to run on (default to `master`) - -### Remove Project - -Removes a GitLab CI project that the authenticated user has access to. - - DELETE /ci/projects/:id - -Parameters: - - * `id` (required) - The ID of the GitLab CI project - -### Link Project to Runner - -Links a runner to a project so that it can make builds (only via -authorized user). - - POST /ci/projects/:id/runners/:runner_id - -Parameters: - - * `id` (required) - The ID of the GitLab CI project - * `runner_id` (required) - The ID of the GitLab CI runner - -### Remove Project from Runner - -Removes a runner from a project so that it can not make builds (only -via authorized user). - - DELETE /ci/projects/:id/runners/:runner_id - -Parameters: - - * `id` (required) - The ID of the GitLab CI project - * `runner_id` (required) - The ID of the GitLab CI runner
\ No newline at end of file diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md index c383dc4bcc9..2f01da4bd76 100644 --- a/doc/ci/api/runners.md +++ b/doc/ci/api/runners.md @@ -1,77 +1,46 @@ # Runners API -## Runners +API used by runners to register and delete themselves. -### Retrieve all runners +_**Note:** This API is intended to be used only by Runners as their own +communication channel. For the consumer API see the +[new Runners API](../../api/runners.md)._ -__Authentication is done by GitLab user token & GitLab url__ +## Authentication -Used to get information about all runners registered on the GitLab CI -instance. +This API uses two types of authentication: - GET /ci/runners +1. Unique runner's token -Returns: + Token assigned to runner after it has been registered. -```json -[ - { - "id" : 85, - "token" : "12b68e90394084703135" - }, - { - "id" : 86, - "token" : "76bf894e969364709864" - }, -] -``` +2. Using runners' registration token -### Register a new runner + This is a token that can be found in project's settings. + It can be also found in Admin area » Runners settings. + + There are two types of tokens you can pass - shared runner registration + token or project specific registration token. +## Runners -__Authentication is done with a Shared runner registration token or a project Specific runner registration token__ +### Register a new runner Used to make GitLab CI aware of available runners. - POST /ci/runners/register + POST /ci/api/v1/runners/register Parameters: - * `token` (required) - The registration token. It is 2 types of token you can pass here. - -1. Shared runner registration token -2. Project specific registration token + * `token` (required) - Registration token -Returns: - -```json -{ - "id" : 85, - "token" : "12b68e90394084703135" -} -``` ### Delete a runner +Used to remove runner. -__Authentication is done by runner token__ - -Used to removing runners. - - DELETE /ci/runners/delete + DELETE /ci/api/v1/runners/delete Parameters: - * `token` (required) - The runner token. - -Returns: - -```json -{ - "id" : 1, - "token" : "d14963981a428f70121777e50643d1", - "created_at" : "2015-02-26T11:39:39.232Z", - "updated_at" : "2015-02-26T11:39:39.232Z", - "description" : "awesome runner" -} -```
\ No newline at end of file + * `token` (required) - Unique runner token 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/deployment/README.md b/doc/ci/deployment/README.md index ffd841ca9e7..7d91ce6710f 100644 --- a/doc/ci/deployment/README.md +++ b/doc/ci/deployment/README.md @@ -89,7 +89,7 @@ We also use two secure variables: In GitLab CI 7.12 a new feature was introduced: Secure Variables. Secure Variables can added by going to `Project > Variables > Add Variable`. **This feature requires `gitlab-runner` with version equal or greater than 0.4.0.** -The variables that are defined in the project settings are send along with the build script to the runner. +The variables that are defined in the project settings are sent along with the build script to the runner. The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml. It is also important that secret's value is hidden in the build log. diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 31458d61674..bd748f1b986 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -174,7 +174,7 @@ The alias hostname for the service is made from the image name following these rules: 1. Everything after `:` is stripped -2. Backslash (`/`) is replaced with double underscores (`__`) +2. Slash (`/`) is replaced with double underscores (`__`) ## Configuring services @@ -270,7 +270,7 @@ This will forcefully (`-f`) remove the `build` container, the two service containers as well as all volumes (`-v`) that were created with the container creation. -[Docker Fundamentals]: https://docs.docker.com/engine/introduction/understanding-docker/ +[Docker Fundamentals]: https://docs.docker.com/engine/understanding-docker/ [hub]: https://hub.docker.com/ [linking-containers]: https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/ [tutum/wordpress]: https://registry.hub.docker.com/u/tutum/wordpress/ diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md new file mode 100644 index 00000000000..c10f82054e2 --- /dev/null +++ b/doc/ci/enable_or_disable_ci.md @@ -0,0 +1,70 @@ +## Enable or disable GitLab CI + +_To effectively use GitLab CI, you need a valid [`.gitlab-ci.yml`](yaml/README.md) +file present at the root directory of your project and a +[runner](runners/README.md) properly set up. You can read our +[quick start guide](quick_start/README.md) to get you started._ + +If you are using an external CI server like Jenkins or Drone CI, it is advised +to disable GitLab CI in order to not have any conflicts with the commits status +API. + +--- + +As of GitLab 8.2, GitLab CI is mainly exposed via the `/builds` page of a +project. Disabling GitLab CI in a project does not delete any previous builds. +In fact, the `/builds` page can still be accessed, although it's hidden from +the left sidebar menu. + +GitLab CI is enabled by default on new installations and can be disabled either +individually under each project's settings, or site-wide by modifying the +settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations +respectively. + +### Per-project user setting + +The setting to enable or disable GitLab CI can be found with the name **Builds** +under the **Features** area of a project's settings along with **Issues**, +**Merge Requests**, **Wiki** and **Snippets**. Select or deselect the checkbox +and hit **Save** for the settings to take effect. + + + +--- + +### Site-wide administrator setting + +You can disable GitLab CI site-wide, by modifying the settings in `gitlab.yml` +and `gitlab.rb` for source and Omnibus installations respectively. + +Two things to note: + +1. Disabling GitLab CI, will affect only newly-created projects. Projects that + had it enabled prior to this modification, will work as before. +1. Even if you disable GitLab CI, users will still be able to enable it in the + project's settings. + +--- + +For installations from source, open `gitlab.yml` with your editor and set +`builds` to `false`: + +```yaml +## Default project features settings +default_projects_features: + issues: true + merge_requests: true + wiki: true + snippets: false + builds: false +``` + +Save the file and restart GitLab: `sudo service gitlab restart`. + +For Omnibus installations, edit `/etc/gitlab/gitlab.rb` and add the line: + +``` +gitlab_rails['gitlab_default_projects_features_builds'] = false +``` + +Save the file and reconfigure GitLab: `sudo gitlab-ctl reconfigure`. diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 1cf41aea391..cc059dc4376 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -1,5 +1,15 @@ -# Build script examples +# CI Examples -+ [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md) -+ [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md) -+ [Test a Clojure application](test-clojure-application.md) +- [Testing a PHP application](php.md) +- [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md) +- [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md) +- [Test a Clojure application](test-clojure-application.md) +- [Using `dpl` as deployment tool](deployment/README.md) +- Help your favorite programming language and GitLab by sending a merge request + with a guide for that language. + +## Outside the documentation + +- [Blost post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) +- [Repo's with examples for various languages](https://gitlab.com/groups/gitlab-examples) +- [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) diff --git a/doc/ci/languages/php.md b/doc/ci/examples/php.md index dacb67fa3ff..aeadd6a448e 100644 --- a/doc/ci/languages/php.md +++ b/doc/ci/examples/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 @@ -97,7 +97,7 @@ image: php:5.6 before_script: # Install dependencies -- ci/docker_install.sh > /dev/null +- bash ci/docker_install.sh > /dev/null test:app: script: @@ -112,7 +112,7 @@ with a different docker image version and the runner will do the rest: ```yaml before_script: # Install dependencies -- ci/docker_install.sh > /dev/null +- bash ci/docker_install.sh > /dev/null # We test PHP5.6 test:5.6: 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..f5645d586ae 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 @@ -1,5 +1,5 @@ ## Test and Deploy a ruby application -This example will guide you how to run tests in your Ruby application and deploy it automatiacally as Heroku application. +This example will guide you how to run tests in your Ruby application and deploy it automatically as Heroku application. You can checkout the example [source](https://gitlab.com/ayufan/ruby-getting-started) and check [CI status](https://gitlab.com/ayufan/ruby-getting-started/builds?scope=all). @@ -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/img/features_settings.png b/doc/ci/img/features_settings.png Binary files differnew file mode 100644 index 00000000000..17aba5d14d8 --- /dev/null +++ b/doc/ci/img/features_settings.png diff --git a/doc/ci/languages/README.md b/doc/ci/languages/README.md deleted file mode 100644 index 54b2343e08b..00000000000 --- a/doc/ci/languages/README.md +++ /dev/null @@ -1,7 +0,0 @@ -### Languages - -This is a list of languages you can test with GitLab CI. Each section has -comprehensive documentation and comes with a test repository hosted on -GitLab.com - -+ [Testing PHP](php.md) diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index a9b36139de9..9aba4326e11 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -1,25 +1,47 @@ # Quick Start -Starting from version 8.0, GitLab Continuous Integration (CI) is fully -integrated into GitLab itself and is enabled by default on all projects. +>**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI) +is fully integrated into GitLab itself and is [enabled] by default on all +projects. -This guide assumes that you: +The TL;DR version of how GitLab CI works is the following. -- have a working GitLab instance of version 8.0 or higher or are using - [GitLab.com](https://gitlab.com/users/sign_in) -- have a project in GitLab that you would like to use CI for +--- + +GitLab offers a [continuous integration][ci] service. If you +[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, +and configure your GitLab project to use a [Runner], then each merge request or +push triggers a build. + +The `.gitlab-ci.yml` file tells the GitLab runner what do to. By default it +runs three [stages]: `build`, `test`, and `deploy`. -In brief, the steps needed to have a working CI can be summed up to: +If everything runs OK (no non-zero return values), you'll get a nice green +checkmark associated with the pushed commit or merge request. This makes it +easy to see whether a merge request will cause any of the tests to fail before +you even look at the code. -1. Create a new project -1. Add `.gitlab-ci.yml` to the git repository and push to GitLab +Most projects only use GitLab's CI service to run the test suite so that +developers get immediate feedback if they broke something. + +So in brief, the steps needed to have a working CI can be summed up to: + +1. Add `.gitlab-ci.yml` to the root directory of your repository 1. Configure a Runner -From there on, on every push to your git repository the build will be +From there on, on every push to your Git repository, the build will be automagically started by the Runner and will appear under the project's `/builds` page. -Now, let's break it down to pieces and work on solving the GitLab CI puzzle. +--- + +This guide assumes that you: + +- have a working GitLab instance of version 8.0 or higher or are using + [GitLab.com](https://gitlab.com/users/sign_in) +- have a project in GitLab that you would like to use CI for + +Let's break it down to pieces and work on solving the GitLab CI puzzle. ## Creating a `.gitlab-ci.yml` file @@ -36,13 +58,13 @@ file and start builds on _Runners_ according to the contents of the file, for that commit. Because `.gitlab-ci.yml` is in the repository, it is version controlled, -old versions still build succesfully, forks can easily make use of CI, +old versions still build successfully, forks can easily make use of CI, branches can have separate builds and you have a single source of truth for CI. You can read more about the reasons why we are using `.gitlab-ci.yml` [in our blog about it][blog-ci]. **Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file -so you have to pay extra attention to the identation. Always use spaces, not +so you have to pay extra attention to the indentation. Always use spaces, not tabs. ### Creating a simple `.gitlab-ci.yml` file @@ -124,7 +146,7 @@ In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`. A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers. GitLab and the Runners communicate through an API, so the only needed requirement is that the machine on which the -Runner is configured to has Internet access. +Runner is configured to have Internet access. A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects it's called a _Shared Runner_. @@ -168,7 +190,7 @@ To enable **Shared Runners** you have to go to your project's ## Seeing the status of your build -After configuring the Runner succesfully, you should see the status of your +After configuring the Runner successfully, you should see the status of your last commit change from _pending_ to either _running_, _success_ or _failed_. You can view all builds, by going to the **Builds** page in your project. @@ -184,14 +206,35 @@ you expected. You are also able to view the status of any commit in the various pages in GitLab, such as **Commits** and **Merge Requests**. -## Next steps +## Enabling build emails + +If you want to receive e-mail notifications about the result status of the +builds, you should explicitly enable the **Builds Emails** service under your +project's settings. + +For more information read the [Builds emails service documentation] +(../../project_services/builds_emails.md). + +## Builds badge + +You can access a builds badge image using following link: + +``` +http://example.gitlab.com/namespace/project/badges/branch/build.svg +``` Awesome! You started using CI in GitLab! -Next you can look into doing more with the CI. Many people are using GitLab -to package, containerize, test and deploy software. +## Examples -Visit our various languages examples at <https://gitlab.com/groups/gitlab-examples>. +Visit the [examples README][examples] to see a list of examples using GitLab +CI with various languages. [runner-install]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tree/master#installation [blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ +[examples]: ../examples/README.md +[ci]: https://about.gitlab.com/gitlab-ci/ +[yaml]: ../yaml/README.md +[runner]: ../runners/README.md +[enabled]: ../enable_or_disable_ci.md +[stages]: ../yaml/README.md#stages diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 68dcfe23ffb..295d953db11 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -62,8 +62,9 @@ Now simply register the runner as any runner: sudo gitlab-runner register ``` -Note that you will have to enable `Allows shared runners` for each project -that you want to make use of a shared runner. This is by default `off`. +Shared runners are enabled by default as of GitLab 8.2, but can be disabled with the +`DISABLE SHARED RUNNERS` button. Previous versions of GitLab defaulted shared runners to +disabled. ## Registering a Specific Runner diff --git a/doc/ci/services/README.md b/doc/ci/services/README.md index 1ebb0a4a250..4b79461d55c 100644 --- a/doc/ci/services/README.md +++ b/doc/ci/services/README.md @@ -1,9 +1,9 @@ ## GitLab CI Services -GitLab CI uses the `services` keyword to define what docker containers should be -linked with your base image. Below is a list of examples you may use. +GitLab CI uses the `services` keyword to define what docker containers should +be linked with your base image. Below is a list of examples you may use. -+ [Using MySQL](mysql.md) -+ [Using PostgreSQL](postgres.md) -+ [Using Redis](redis.md) -+ [Using Other Services](../docker/using_docker_images.md#how-to-use-other-images-as-services) +- [Using MySQL](mysql.md) +- [Using PostgreSQL](postgres.md) +- [Using Redis](redis.md) +- [Using Other Services](../docker/using_docker_images.md#how-to-use-other-images-as-services) diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index b99ea25a3fe..b0e53cbc261 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -16,7 +16,7 @@ The API_TOKEN will take the Secure Variable value: `SECURE`. ### Predefined variables (Environment Variables) | Variable | Runner | Description | -|-------------------------|-------------| +|-------------------------|-----|--------| | **CI** | 0.4 | Mark that build is executed in CI environment | | **GITLAB_CI** | all | Mark that build is executed in GitLab CI environment | | **CI_SERVER** | all | Mark that build is executed in CI environment | @@ -30,7 +30,7 @@ The API_TOKEN will take the Secure Variable value: `SECURE`. | **CI_BUILD_REF_NAME** | all | The branch or tag name for which project is built | | **CI_BUILD_ID** | all | The unique id of the current build that GitLab CI uses internally | | **CI_BUILD_REPO** | all | The URL to clone the Git repository | -| **CI_BUILD_TRIGGERED** | 0.5 | The flag to indicate that build was triggered | +| **CI_BUILD_TRIGGERED** | 0.5 | The flag to indicate that build was [triggered] | | **CI_PROJECT_ID** | all | The unique id of the current project that GitLab CI uses internally | | **CI_PROJECT_DIR** | all | The full path where the repository is cloned and where the build is ran | @@ -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. @@ -77,9 +77,12 @@ More information about Docker integration can be found in [Using Docker Images]( GitLab CI allows you to define per-project **Secure Variables** that are set in build environment. The secure variables are stored out of the repository (the `.gitlab-ci.yml`). -These variables are securely stored in GitLab CI database and are hidden in the build log. +The variables are securely passed to GitLab Runner and are available in build environment. It's desired method to use them for storing passwords, secret keys or whatever you want. +**The value of the variable can be shown in build log if explicitly asked to do so.** +If your project is public or internal you can make the builds private. + Secure Variables can added by going to `Project > Variables > Add Variable`. They will be available for all subsequent builds. @@ -101,3 +104,5 @@ job_name: script: - export ``` + +[triggered]: ../triggers/README.md diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index fd0d49de4e4..a9b79bbdb1b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -116,7 +116,8 @@ Alias for [stages](#stages). ### variables -_**Note:** Introduced in GitLab Runner v0.5.0._ +>**Note:** +Introduced in GitLab Runner v0.5.0. GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment. The variables are stored in the git repository and are meant to @@ -134,22 +135,123 @@ thus allowing to fine tune them. ### cache +>**Note:** +Introduced in GitLab Runner v0.7.0. + `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. -To cache all git untracked files and files in `binaries`: +Cache all files in `binaries` and `.config`: + +```yaml +rspec: + script: test + cache: + paths: + - binaries/ + - .config +``` + +Cache all Git untracked files: + +```yaml +rspec: + script: test + cache: + untracked: true +``` + +Cache all Git untracked files and files in `binaries`: + +```yaml +rspec: + script: test + cache: + untracked: true + paths: + - binaries/ +``` + +Locally defined cache overwrites globally defined options. This will cache only +`binaries/`: ```yaml cache: - untracked: true paths: - - binaries/ + - my/files + +rspec: + script: test + cache: + paths: + - binaries/ +``` + +The cache is provided on best effort basis, so don't expect that cache will be +always present. For implementation details please check GitLab Runner. + +#### 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 @@ -177,13 +279,14 @@ job_name: | Keyword | Required | Description | |---------------|----------|-------------| | script | yes | Defines a shell script which is executed by runner | -| stage | no (default: `test`) | Defines a build stage | +| stage | no | Defines a build stage (default: `test`) | | type | no | Alias for `stage` | | only | no | Defines a list of git refs for which build is created | | except | no | Defines a list of git refs for which build is not created | | tags | no | Defines a list of tags which are used to select runner | | allow_failure | no | Allow build to fail. Failed build doesn't contribute to commit status | | when | no | Define when to run build. Can be `on_success`, `on_failure` or `always` | +| dependencies | no | Define other builds that a build depends on so that you can pass artifacts between them| | artifacts | no | Define list build artifacts | | cache | no | Define list of files that should be cached between subsequent runs | @@ -336,11 +439,18 @@ The above script will: ### artifacts -_**Note:** Introduced in GitLab Runner v0.7.0. Also, the Windows shell executor - does not currently support artifact uploads._ +>**Notes:** +> +> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. +> - Windows support was added in GitLab Runner v.1.0.0. +> - Currently not all executors are supported. +> - Build artifacts are only collected for successful builds. `artifacts` is used to specify list of files and directories which should be -attached to build after success. Below are some examples. +attached to build after success. To pass artifacts between different builds, +see [dependencies](#dependencies). + +Below are some examples. Send all files in `binaries` and `.config`: @@ -351,14 +461,14 @@ artifacts: - .config ``` -Send all git untracked files: +Send all Git untracked files: ```yaml artifacts: untracked: true ``` -Send all git untracked files and files in `binaries`: +Send all Git untracked files and files in `binaries`: ```yaml artifacts: @@ -367,64 +477,299 @@ artifacts: - binaries/ ``` -The artifacts will be send after a successful build success to GitLab, and will -be accessible in the GitLab UI to download. +You may want to create artifacts only for tagged releases to avoid filling the +build server storage with temporary build artifacts. -### cache +Create artifacts only for tags (`default-job` will not create artifacts): -_**Note:** Introduced in GitLab Runner v0.7.0._ +```yaml +default-job: + script: + - mvn test -U + except: + - tags + +release-job: + script: + - mvn package -U + artifacts: + paths: + - target/*.war + only: + - tags +``` -`cache` is used to specify list of files and directories which should be cached -between builds. Below are some examples: +The artifacts will be sent to GitLab after a successful build and will +be available for download in the GitLab UI. -Cache all files in `binaries` and `.config`: +#### artifacts:name + +>**Note:** +Introduced in GitLab 8.6 and GitLab Runner v1.1.0. + +The `name` directive allows you to define the name of the created artifacts +archive. That way, you can have a unique name of every archive which could be +useful when you'd like to download the archive from GitLab. The `artifacts:name` +variable can make use of any of the [predefined variables](../variables/README.md). + +--- + +**Example configurations** + +To create an archive with a name of the current build: ```yaml -rspec: - script: test - cache: - paths: - - binaries/ - - .config +job: + artifacts: + name: "$CI_BUILD_NAME" ``` -Cache all git untracked files: +To create an archive with a name of the current branch or tag including only +the files that are untracked by Git: ```yaml -rspec: - script: test - cache: +job: + artifacts: + name: "$CI_BUILD_REF_NAME" + untracked: true +``` + +To create an archive with a name of the current build and the current branch or +tag including only the files that are untracked by Git: + +```yaml +job: + artifacts: + name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}" untracked: true ``` -Cache all git untracked files and files in `binaries`: +To create an archive with a name of the current [stage](#stages) and branch name: ```yaml -rspec: - script: test - cache: +job: + artifacts: + name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}" untracked: true - paths: - - binaries/ ``` -Locally defined cache overwrites globally defined options. This will cache only -`binaries/`: +--- + +If you use **Windows Batch** to run your shell scripts you need to replace +`$` with `%`: ```yaml -cache: - paths: - - my/files +job: + artifacts: + name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%" + untracked: true +``` -rspec: - script: test - cache: +### dependencies + +>**Note:** +Introduced in GitLab 8.6 and GitLab Runner v1.1.1. + +This feature should be used in conjunction with [`artifacts`](#artifacts) and +allows you to define the artifacts to pass between different builds. + +Note that `artifacts` from previous [stages](#stages) are passed by default. + +To use this feature, define `dependencies` in context of the job and pass +a list of all previous builds from which the artifacts should be downloaded. +You can only define builds from stages that are executed before the current one. +An error will be shown if you define builds from the current stage or next ones. + +--- + +In the following example, we define two jobs with artifacts, `build:osx` and +`build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` +will be downloaded and extracted in the context of the build. The same happens +for `test:linux` and artifacts from `build:linux`. + +The job `deploy` will download artifacts from all previous builds because of +the [stage](#stages) precedence: + +```yaml +build:osx: + stage: build + script: make build:osx + artifacts: + paths: + - binaries/ + +build:linux: + stage: build + script: make build:linux + artifacts: paths: - binaries/ + +test:osx: + stage: test + script: make test:osx + dependencies: + - build:osx + +test:linux: + stage: test + script: make test:linux + dependencies: + - build:linux + +deploy: + stage: deploy + script: make deploy ``` -The cache is provided on best effort basis, so don't expect that cache will be -always present. For implementation details please check GitLab Runner. +## Hidden jobs + +>**Note:** +Introduced in GitLab 8.6 and GitLab Runner v1.1.1. + +Jobs that start with a dot (`.`) will be not processed by GitLab CI. You can +use this feature to ignore jobs, or use the +[special YAML features](#special-yaml-features) and transform the hidden jobs +into templates. + +In the following example, `.job_name` will be ignored: + +```yaml +.job_name: + script: + - rake spec +``` + +## Special YAML features + +It's possible to use special YAML features like anchors (`&`), aliases (`*`) +and map merging (`<<`), which will allow you to greatly reduce the complexity +of `.gitlab-ci.yml`. + +Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). + +### Anchors + +>**Note:** +Introduced in GitLab 8.6 and GitLab Runner v1.1.1. + +YAML also has a handy feature called 'anchors', which let you easily duplicate +content across your document. Anchors can be used to duplicate/inherit +properties, and is a perfect example to be used with [hidden jobs](#hidden-jobs) +to provide templates for your jobs. + +The following example uses anchors and map merging. It will create two jobs, +`test1` and `test2`, that will inherit the parameters of `.job_template`, each +having their own custom `script` defined: + +```yaml +.job_template: &job_definition # Hidden job that defines an anchor named 'job_definition' + image: ruby:2.1 + services: + - postgres + - redis + +test1: + <<: *job_definition # Merge the contents of the 'job_definition' alias + script: + - test1 project + +test2: + <<: *job_definition # Merge the contents of the 'job_definition' alias + script: + - test2 project +``` + +`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the +given hash into the current one", and `*` includes the named anchor +(`job_definition` again). The expanded version looks like this: + +```yaml +.job_template: + image: ruby:2.1 + services: + - postgres + - redis + +test1: + image: ruby:2.1 + services: + - postgres + - redis + script: + - test1 project + +test2: + image: ruby:2.1 + services: + - postgres + - redis + script: + - test2 project +``` + +Let's see another one example. This time we will use anchors to define two sets +of services. This will create two jobs, `test:postgres` and `test:mysql`, that +will share the `script` directive defined in `.job_template`, and the `services` +directive defined in `.postgres_services` and `.mysql_services` respectively: + +```yaml +.job_template: &job_definition + script: + - test project + +.postgres_services: + services: &postgres_definition + - postgres + - ruby + +.mysql_services: + services: &mysql_definition + - mysql + - ruby + +test:postgres: + << *job_definition + services: *postgres_definition + +test:mysql: + << *job_definition + services: *mysql_definition +``` + +The expanded version looks like this: + +```yaml +.job_template: + script: + - test project + +.postgres_services: + services: + - postgres + - ruby + +.mysql_services: + services: + - mysql + - ruby + +test:postgres: + script: + - test project + services: + - postgres + - ruby + +test:mysql: + script: + - test project + services: + - mysql + - ruby +``` + +You can see that the hidden jobs are conveniently used as templates. ## Validate the .gitlab-ci.yml @@ -435,3 +780,10 @@ You can find the link under `/ci/lint` of your gitlab instance. If your commit message contains `[ci skip]`, the commit will be created but the builds will be skipped. + +## Examples + +Visit the [examples README][examples] to see a list of examples using GitLab +CI with various languages. + +[examples]: ../examples/README.md diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md new file mode 100644 index 00000000000..d4d9f5f7b5e --- /dev/null +++ b/doc/customization/branded_login_page.md @@ -0,0 +1,19 @@ +# Changing the appearance of the login page + +GitLab Community Edition offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page. + +By default, the page shows the GitLab logo and description. + + + +## Changing the appearance of the login page + +Navigate to the **Admin** area and go to the **Appearance** page. + +Fill in the required details like Title, Description and upload the company logo. + + + +After saving the page, your GitLab login page will have the details you filled in: + + diff --git a/doc/customization/branded_login_page/appearance.png b/doc/customization/branded_login_page/appearance.png Binary files differnew file mode 100644 index 00000000000..6bce1f0a287 --- /dev/null +++ b/doc/customization/branded_login_page/appearance.png diff --git a/doc/customization/branded_login_page/custom_sign_in.png b/doc/customization/branded_login_page/custom_sign_in.png Binary files differnew file mode 100644 index 00000000000..d6020b029a2 --- /dev/null +++ b/doc/customization/branded_login_page/custom_sign_in.png diff --git a/doc/customization/branded_login_page/default_login_page.png b/doc/customization/branded_login_page/default_login_page.png Binary files differnew file mode 100644 index 00000000000..795c7954d8e --- /dev/null +++ b/doc/customization/branded_login_page/default_login_page.png diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index 00edfc97ed9..194b8e00299 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -16,7 +16,7 @@ Here, `%{issue_ref}` is a complex regular expression defined inside GitLab, that For example: ``` -git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes group/otherproject#2). This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23." +git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes group/otherproject#22). This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23." ``` will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does not match the pattern. It also works with multiline commit messages. diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md index e993230bb88..a0cb234bea0 100644 --- a/doc/customization/welcome_message.md +++ b/doc/customization/welcome_message.md @@ -1,12 +1,12 @@ -# Customize the complete sign-in page (GitLab Enterprise Edition only) +# Customize the complete sign-in page -Please see [Branded login page](http://doc.gitlab.com/ee/customization/branded_login_page.html) +Please see [Branded login page](branded_login_page.md) # Add a welcome message to the sign-in page (GitLab Community Edition) It is possible to add a markdown-formatted welcome message to your GitLab sign-in page. Users of GitLab Enterprise Edition should use the [branded login -page feature](/ee/customization/branded_login_page.html) instead. +page feature](branded_login_page.md) instead. The welcome message (extra_sign_in_text) can now be set/changed in the Admin UI. -Admin area > Settings
\ No newline at end of file +Admin area > Settings diff --git a/doc/development/README.md b/doc/development/README.md index d5bf166ad32..1b281809afc 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -1,11 +1,12 @@ # Development - [Architecture](architecture.md) of GitLab -- [Shell commands](shell_commands.md) in the GitLab codebase -- [Rake tasks](rake_tasks.md) for development - [CI setup](ci_setup.md) for testing GitLab +- [Gotchas](gotchas.md) to avoid +- [How to dump production data to staging](db_dump.md) +- [Migration Style Guide](migration_style_guide.md) for creating safe migrations +- [Rake tasks](rake_tasks.md) for development +- [Shell commands](shell_commands.md) in the GitLab codebase - [Sidekiq debugging](sidekiq_debugging.md) +- [SQL guidelines](sql.md) for SQL guidelines - [UI guide](ui_guide.md) for building GitLab with existing css styles and elements -- [Migration Style Guide](migration_style_guide.md) for creating safe migrations -- [How to dump production data to staging](dump_db.md) -- [Benchmarking](benchmarking.md) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 6101a71a8de..12e33406cb6 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -42,7 +42,7 @@ Gitlab-shell communicates with Sidekiq via the “communication board” (Redis) ## System Layout -When referring to ~git in the pictures it means the home directory of the git user which is typically /home/git. +When referring to `~git` in the pictures it means the home directory of the git user which is typically /home/git. GitLab is primarily installed within the `/home/git` user home directory as `git` user. Within the home directory is where the gitlabhq server software resides as well as the repositories (though the repository location is configurable). diff --git a/doc/development/benchmarking.md b/doc/development/benchmarking.md deleted file mode 100644 index 88e18ee95f9..00000000000 --- a/doc/development/benchmarking.md +++ /dev/null @@ -1,69 +0,0 @@ -# Benchmarking - -GitLab CE comes with a set of benchmarks that are executed for every build. This -makes it easier to measure performance of certain components over time. - -Benchmarks are written as RSpec tests using a few extra helpers. To write a -benchmark, first tag the top-level `describe`: - -```ruby -describe MaruTheCat, benchmark: true do - -end -``` - -This ensures the benchmark is executed separately from other test collections. -It also exposes the various RSpec matchers used for writing benchmarks to the -test group. - -Next, lets write the actual benchmark: - -```ruby -describe MaruTheCat, benchmark: true do - let(:maru) { MaruTheChat.new } - - describe '#jump_in_box' do - benchmark_subject { maru.jump_in_box } - - it { is_expected.to iterate_per_second(9000) } - end -end -``` - -Here `benchmark_subject` is a small wrapper around RSpec's `subject` method that -makes it easier to specify the subject of a benchmark. Using RSpec's regular -`subject` would require us to write the following instead: - -```ruby -subject { -> { maru.jump_in_box } } -``` - -The `iterate_per_second` matcher defines the amount of times per second a -subject should be executed. The higher the amount of iterations the better. - -By default the allowed standard deviation is a maximum of 30%. This can be -adjusted by chaining the `with_maximum_stddev` on the `iterate_per_second` -matcher: - -```ruby -it { is_expected.to iterate_per_second(9000).with_maximum_stddev(50) } -``` - -This can be useful if the code in question depends on external resources of -which the performance can vary a lot (e.g. physical HDDs, network calls, etc). -However, in most cases 30% should be enough so only change this when really -needed. - -## Benchmarks Location - -Benchmarks should be stored in `spec/benchmarks` and should follow the regular -Rails specs structure. That is, model benchmarks go in `spec/benchmark/models`, -benchmarks for code in the `lib` directory go in `spec/benchmarks/lib`, etc. - -## Underlying Technology - -The benchmark setup uses [benchmark-ips][benchmark-ips] which takes care of the -heavy lifting such as warming up code, calculating iterations, standard -deviation, etc. - -[benchmark-ips]: https://github.com/evanphx/benchmark-ips diff --git a/doc/development/ci_setup.md b/doc/development/ci_setup.md index f9b48868182..6776d9b083f 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.1.8 - database.yml: pg Build commands diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md new file mode 100644 index 00000000000..187ec9e7b75 --- /dev/null +++ b/doc/development/doc_styleguide.md @@ -0,0 +1,270 @@ +# Documentation styleguide + +This styleguide recommends best practices to improve documentation and to keep +it organized and easy to find. + +## Naming + +- When creating a new document and it has more than one word in its name, + make sure to use underscores instead of spaces or dashes (`-`). For example, + a proper naming would be `import_projects_from_github.md`. The same rule + applies to images. + +## Text + +- Split up long lines, this makes it much easier to review and edit. Only + double line breaks are shown as a full line break in [GitLab markdown][gfm]. + 80-100 characters is a good line length +- Make sure that the documentation is added in the correct directory and that + there's a link to it somewhere useful +- Do not duplicate information +- Be brief and clear +- Unless there's a logical reason not to, add documents in alphabetical order +- Write in US English +- Use [single spaces][] instead of double spaces + +## Formatting + +- Use dashes (`-`) for unordered lists instead of asterisks (`*`) +- Use the number one (`1`) for ordered lists +- Use underscores (`_`) to mark a word or text in italics +- Use double asterisks (`**`) to mark a word or text in bold +- When using lists, prefer not to end each item with a period. You can use + them if there are multiple sentences, just keep the last sentence without + a period + +## Headings + +- Add only one H1 title in each document, by adding `#` at the beginning of + it (when using markdown). For subheadings, use `##`, `###` and so on +- Avoid putting numbers in headings. Numbers shift, hence documentation anchor + links shift too, which eventually leads to dead links. If you think it is + compelling to add numbers in headings, make sure to at least discuss it with + someone in the Merge Request +- When introducing a new document, be careful for the headings to be + grammatically and syntactically correct. It is advised to mention one or all + of the following GitLab members for a review: `@axil`, `@rspeicher`, + `@dblessing`, `@ashleys`, `@nearlythere`. This is to ensure that no document + with wrong heading is going live without an audit, thus preventing dead links + and redirection issues when corrected +- Leave exactly one newline after a heading + +## Links + +- If a link makes the paragraph to span across multiple lines, do not use + the regular Markdown approach: `[Text](https://example.com)`. Instead use + `[Text][identifier]` and at the very bottom of the document add: + `[identifier]: https://example.com`. This is another way to create Markdown + links which keeps the document clear and concise. Bonus points if you also + add an alternative text: `[identifier]: https://example.com "Alternative text"` + that appears when hovering your mouse on a link + +## Images + +- Place images in a separate directory named `img/` in the same directory where + the `.md` document that you're working on is located. Always prepend their + names with the name of the document that they will be included in. For + example, if there is a document called `twitter.md`, then a valid image name + could be `twitter_login_screen.png`. +- Images should have a specific, non-generic name that will differentiate them. +- Keep all file names in lower case. +- Consider using PNG images instead of JPEG. + +Inside the document: + +- The Markdown way of using an image inside a document is: + `` +- Always use a proper description for what the image is about. That way, when a + browser fails to show the image, this text will be used as an alternative + description +- If there are consecutive images with little text between them, always add + three dashes (`---`) between the image and the text to create a horizontal + line for better clarity +- If a heading is placed right after an image, always add three dashes (`---`) + between the image and the heading + +## Notes + +- Notes should be quoted with the word `Note:` being bold. Use this form: + + ``` + >**Note:** + This is something to note. + ``` + + which renders to: + + >**Note:** + This is something to note. + + If the note spans across multiple lines it's OK to split the line. + +## New features + +- Every piece of documentation that comes with a new feature should declare the + GitLab version that feature got introduced. Right below the heading add a + note: `_**Note:** This feature was introduced in GitLab 8.3_` +- If possible every feature should have a link to the MR that introduced it. + The above note would be then transformed to: + `_**Note:** This feature was [introduced][ce-1242] in GitLab 8.3_`, where + the [link identifier](#links) is named after the repository (CE) and the MR + number +- If the feature is only in GitLab EE, don't forget to mention it, like: + `_**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. + +## Installation guide + +- **Ruby:** + In [step 2 of the installation guide](../install/installation.md#2-ruby), + we install Ruby from source. Whenever there is a new version that needs to + be updated, remember to change it throughout the codeblock and also replace + the sha256sum (it can be found in the [downloads page][ruby-dl] of the Ruby + website). + +[ruby-dl]: https://www.ruby-lang.org/en/downloads/ "Ruby download website" + +## API + +Here is a list of must-have items. Use them in the exact order that appears +on this document. Further explanation is given below. + +- Every method must have the REST API request. For example: + + ``` + GET /projects/:id/repository/branches + ``` + +- Every method must have a detailed + [description of the parameters](#method-description). +- Every method must have a cURL example. +- Every method must have a response body (in JSON format). + +### Method description + +Use the following table headers to describe the methods. Attributes should +always be in code blocks using backticks (`). + +``` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +``` + +Rendered example: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `user` | string | yes | The GitLab username | + +### cURL commands + +- Use `https://gitlab.example.com/api/v3/` as an endpoint. +- Wherever needed use this private token: `9koXpg98eAheJpvBs5tK`. +- Always put the request first. `GET` is the default so you don't have to + include it. +- Use double quotes to the URL when it includes additional parameters. +- Prefer to use examples using the private token and don't pass data of + username and password. + +| Methods | Description | +| ------- | ----------- | +| `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed | +| `-X POST` | Use this method when creating new objects | +| `-X PUT` | Use this method when updating existing objects | +| `-X DELETE` | Use this method when removing existing objects | + +### cURL Examples + +Below is a set of [cURL][] examples that you can use in the API documentation. + +#### Simple cURL command + +Get the details of a group: + +```bash +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/groups/gitlab-org +``` + +#### cURL example with parameters passed in the URL + +Create a new project under the authenticated user's namespace: + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects?name=foo" +``` + +#### Post data using cURL's --data + +Instead of using `-X POST` and appending the parameters to the URI, you can use +cURL's `--data` option. The example below will create a new project `foo` under +the authenticated user's namespace. + +```bash +curl --data "name=foo" -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects" +``` + +#### Post data using JSON content + +_**Note:** In this example we create a new group. Watch carefully the single +and double quotes._ + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -H "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v3/groups +``` + +#### Post data using form-data + +Instead of using JSON or urlencode you can use multipart/form-data which +properly handles data encoding: + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "title=ssh-key" -F "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v3/users/25/keys +``` + +The above example is run by and administrator and will add an SSH public key +titled ssh-key to user's account which has an id of 25. + +#### Escape special characters + +Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended +to escape them when possible. In the example below we create a new issue which +contains spaces in its title. Observe how spaces are escaped using the `%20` +ASCII code. + +```bash +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/42/issues?title=Hello%20Dude" +``` + +Use `%2F` for slashes (`/`). + +#### Pass arrays to API calls + +The GitLab API sometimes accepts arrays of strings or integers. For example, to +restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and +`example.net`, you would do something like this: + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -d "restricted_signup_domains[]=*.example.com" -d "restricted_signup_domains[]=example.net" https://gitlab.example.com/api/v3/application/settings +``` + +[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/development/gotchas.md b/doc/development/gotchas.md new file mode 100644 index 00000000000..21078c8d6f9 --- /dev/null +++ b/doc/development/gotchas.md @@ -0,0 +1,103 @@ +# Gotchas + +The purpose of this guide is to document potential "gotchas" that contributors +might encounter or should avoid during development of GitLab CE and EE. + +## Don't `describe` symbols + +Consider the following model spec: + +```ruby +require 'rails_helper' + +describe User do + describe :to_param do + it 'converts the username to a param' do + user = described_class.new(username: 'John Smith') + + expect(user.to_param).to eq 'john-smith' + end + end +end +``` + +When run, this spec doesn't do what we might expect: + +```sh +spec/models/user_spec.rb|6 error| Failure/Error: u = described_class.new NoMethodError: undefined method `new' for :to_param:Symbol +``` + +### Solution + +Except for the top-level `describe` block, always provide a String argument to +`describe`. + +## Don't `rescue Exception` + +See ["Why is it bad style to `rescue Exception => e` in Ruby?"][Exception]. + +_**Note:** This rule is [enforced automatically by +Rubocop](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/.rubocop.yml#L911-914)._ + +[Exception]: http://stackoverflow.com/q/10048173/223897 + +## Don't use inline CoffeeScript in views + +Using the inline `:coffee` or `:coffeescript` Haml filters comes with a +performance overhead. + +_**Note:** We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-5-stable/config/initializers/haml.rb) +in an initializer._ + +### Further reading + +- Pull Request: [Replace CoffeeScript block into JavaScript in Views](https://git.io/vztMu) +- Stack Overflow: [Performance implications of using :coffescript filter inside HAML templates?](http://stackoverflow.com/a/17571242/223897) + +## ID-based CSS selectors need to be a bit more specific + +Normally, because HTML `id` attributes need to be unique to the page, it's +perfectly fine to write some JavaScript like the following: + +```javascript +$('#js-my-selector').hide(); +``` + +However, there's a feature of GitLab's Markdown processing that [automatically +adds anchors to header elements][ToC Processing], with the `id` attribute being +automatically generated based on the content of the header. + +Unfortunately, this feature makes it possible for user-generated content to +create a header element with the same `id` attribute we're using in our +selector, potentially breaking the JavaScript behavior. A user could break the +above example with the following Markdown: + +```markdown +## JS My Selector +``` + +Which gets converted to the following HTML: + +```html +<h2> + <a id="js-my-selector" class="anchor" href="#js-my-selector" aria-hidden="true"></a> + JS My Selector +</h2> +``` + +[ToC Processing]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/lib/banzai/filter/table_of_contents_filter.rb#L31-37 + +### Solution + +The current recommended fix for this is to make our selectors slightly more +specific: + +```javascript +$('div#js-my-selector').hide(); +``` + +### Further reading + +- Issue: [Merge request ToC anchor conflicts with tabs](https://gitlab.com/gitlab-org/gitlab-ce/issues/3908) +- Merge Request: [Make tab target selectors less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2023) +- Merge Request: [Make cross-project reference's clipboard target less naive](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2024) diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 4fa1961fde9..28dedf3978c 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -8,12 +8,14 @@ In addition, having to take a server offline for a an upgrade small or big is a big burden for most organizations. For this reason it is important that your migrations are written carefully, can be applied online and adhere to the style guide below. +It's advised to have offline migrations only in major GitLab releases. + When writing your migrations, also consider that databases might have stale data or inconsistencies and guard for that. Try to make as little assumptions as possible about the state of the database. Please don't depend on GitLab specific code since it can change in future versions. -If needed copy-paste GitLab code into the migration to make make it forward compatible. +If needed copy-paste GitLab code into the migration to make it forward compatible. ## Comments in the migration @@ -33,6 +35,8 @@ It is always preferable to have a migration run online. If you expect the migrat to take particularly long (for instance, if it loops through all notes), this is valuable information to add. +If you don't provide the information it means that a migration is safe to run online. + ### Reversibility Your migration should be reversible. This is very important, as it should @@ -85,4 +89,4 @@ select_all("SELECT name, COUNT(id) as cnt FROM tags GROUP BY name HAVING COUNT(i execute("UPDATE taggings SET tag_id = #{origin_tag_id} WHERE tag_id IN(#{duplicate_ids.join(",")})") execute("DELETE FROM tags WHERE id IN(#{duplicate_ids.join(",")})") end -``` +```
\ No newline at end of file diff --git a/doc/development/scss_styleguide.md b/doc/development/scss_styleguide.md new file mode 100644 index 00000000000..6c48c25448b --- /dev/null +++ b/doc/development/scss_styleguide.md @@ -0,0 +1,194 @@ +# SCSS styleguide + +This style guide recommends best practices for SCSS to make styles easy to read, +easy to maintain, and performant for the end-user. + +## Rules + +### Naming + +CSS classes should use the `lowercase-hyphenated` format rather than +`snake_case` or `camelCase`. + +```scss +// Bad +.class_name { + color: #fff; +} + +// Bad +.className { + color: #fff; +} + +// Good +.class-name { + color: #fff; +} +``` + +### Formatting + +You should always use a space before a brace, braces should be on the same +line, each property should each get its own line, and there should be a space +between the property and its value. + +```scss +// Bad +.container-item { + width: 100px; height: 100px; + margin-top: 0; +} + +// Bad +.container-item +{ + width: 100px; + height: 100px; + margin-top: 0; +} + +// Bad +.container-item{ + width:100px; + height:100px; + margin-top:0; +} + +// Good +.container-item { + width: 100px; + height: 100px; + margin-top: 0; +} +``` + +Note that there is an exception for single-line rulesets, although these are +not typically recommended. + +```scss +p { margin: 0; padding: 0; } +``` + +### Colors + +HEX (hexadecimal) colors short-form should use shortform where possible, and +should use lower case letters to differenciate between letters and numbers, e. +g. `#E3E3E3` vs. `#e3e3e3`. + +```scss +// Bad +p { + color: #ffffff; +} + +// Bad +p { + color: #FFFFFF; +} + +// Good +p { + color: #fff; +} +``` + +### Indentation + +Indentation should always use two spaces for each indentation level. + +```scss +// Bad, four spaces +p { + color: #f00; +} + +// Good +p { + color: #f00; +} +``` + +### Semicolons + +Always include semicolons after every property. When the stylesheets are +minified, the semicolons will be removed automatically. + +```scss +// Bad +.container-item { + width: 100px; + height: 100px +} + +// Good +.container-item { + width: 100px; + height: 100px; +} +``` + +### Shorthand + +The shorthand form should be used for properties that support it. + +```scss +// Bad +margin: 10px 15px 10px 15px; +padding: 10px 10px 10px 10px; + +// Good +margin: 10px 15px; +padding: 10px; +``` + +### Zero Units + +Omit length units on zero values, they're unnecessary and not including them +is slightly more performant. + +```scss +// Bad +.item-with-padding { + padding: 0px; +} + +// Good +.item-with-padding { + padding: 0; +} +``` + +### Selectors with a `js-` Prefix +Do not use any selector prefixed with `js-` for styling purposes. These +selectors are intended for use only with JavaScript to allow for removal or +renaming without breaking styling. + +## Linting + +We use [SCSS Lint][scss-lint] to check for style guide conformity. It uses the +ruleset in `.scss-lint.yml`, which is located in the home directory of the +project. + +To check if any warnings will be produced by your changes, you can run `rake +scss_lint` in the GitLab directory. SCSS Lint will also run in GitLab CI to +catch any warnings. + +If the Rake task is throwing warnings you don't understand, SCSS Lint's +documentation includes [a full list of their linters][scss-lint-documentation]. + +### Fixing issues + +If you want to automate changing a large portion of the codebase to conform to +the SCSS style guide, you can use [CSSComb][csscomb]. First install +[Node][node] and [NPM][npm], then run `npm install csscomb -g` to install +CSSComb globally (system-wide). Run it in the GitLab directory with +`csscomb app/assets/stylesheets` to automatically fix issues with CSS/SCSS. + +Note that this won't fix every problem, but it should fix a majority. + +[csscomb]: https://github.com/csscomb/csscomb.js +[node]: https://github.com/nodejs/node +[npm]: https://www.npmjs.com/ +[scss-lint]: https://github.com/brigade/scss-lint +[scss-lint-documentation]: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md diff --git a/doc/development/sql.md b/doc/development/sql.md new file mode 100644 index 00000000000..23fd7604957 --- /dev/null +++ b/doc/development/sql.md @@ -0,0 +1,219 @@ +# SQL Query Guidelines + +This document describes various guidelines to follow when writing SQL queries, +either using ActiveRecord/Arel or raw SQL queries. + +## Using LIKE Statements + +The most common way to search for data is using the `LIKE` statement. For +example, to get all issues with a title starting with "WIP:" you'd write the +following query: + +```sql +SELECT * +FROM issues +WHERE title LIKE 'WIP:%'; +``` + +On PostgreSQL the `LIKE` statement is case-sensitive. On MySQL this depends on +the case-sensitivity of the collation, which is usually case-insensitive. To +perform a case-insensitive `LIKE` on PostgreSQL you have to use `ILIKE` instead. +This statement in turn isn't supported on MySQL. + +To work around this problem you should write `LIKE` queries using Arel instead +of raw SQL fragments as Arel automatically uses `ILIKE` on PostgreSQL and `LIKE` +on MySQL. This means that instead of this: + +```ruby +Issue.where('title LIKE ?', 'WIP:%') +``` + +You'd write this instead: + +```ruby +Issue.where(Issue.arel_table[:title].matches('WIP:%')) +``` + +Here `matches` generates the correct `LIKE` / `ILIKE` statement depending on the +database being used. + +If you need to chain multiple `OR` conditions you can also do this using Arel: + +```ruby +table = Issue.arel_table + +Issue.where(table[:title].matches('WIP:%').or(table[:foo].matches('WIP:%'))) +``` + +For PostgreSQL this produces: + +```sql +SELECT * +FROM issues +WHERE (title ILIKE 'WIP:%' OR foo ILIKE 'WIP:%') +``` + +In turn for MySQL this produces: + +```sql +SELECT * +FROM issues +WHERE (title LIKE 'WIP:%' OR foo LIKE 'WIP:%') +``` + +## LIKE & Indexes + +Neither PostgreSQL nor MySQL use any indexes when using `LIKE` / `ILIKE` with a +wildcard at the start. For example, this will not use any indexes: + +```sql +SELECT * +FROM issues +WHERE title ILIKE '%WIP:%'; +``` + +Because the value for `ILIKE` starts with a wildcard the database is not able to +use an index as it doesn't know where to start scanning the indexes. + +MySQL provides no known solution to this problem. Luckily PostgreSQL _does_ +provide a solution: trigram GIN indexes. These indexes can be created as +follows: + +```sql +CREATE INDEX [CONCURRENTLY] index_name_here +ON table_name +USING GIN(column_name gin_trgm_ops); +``` + +The key here is the `GIN(column_name gin_trgm_ops)` part. This creates a [GIN +index][gin-index] with the operator class set to `gin_trgm_ops`. These indexes +_can_ be used by `ILIKE` / `LIKE` and can lead to greatly improved performance. +One downside of these indexes is that they can easily get quite large (depending +on the amount of data indexed). + +To keep naming of these indexes consistent please use the following naming +pattern: + + index_TABLE_on_COLUMN_trigram + +For example, a GIN/trigram index for `issues.title` would be called +`index_issues_on_title_trigram`. + +Due to these indexes taking quite some time to be built they should be built +concurrently. This can be done by using `CREATE INDEX CONCURRENTLY` instead of +just `CREATE INDEX`. Concurrent indexes can _not_ be created inside a +transaction. Transactions for migrations can be disabled using the following +pattern: + +```ruby +class MigrationName < ActiveRecord::Migration + disable_ddl_transaction! +end +``` + +For example: + +```ruby +class AddUsersLowerUsernameEmailIndexes < ActiveRecord::Migration + disable_ddl_transaction! + + def up + return unless Gitlab::Database.postgresql? + + execute 'CREATE INDEX CONCURRENTLY index_on_users_lower_username ON users (LOWER(username));' + execute 'CREATE INDEX CONCURRENTLY index_on_users_lower_email ON users (LOWER(email));' + end + + def down + return unless Gitlab::Database.postgresql? + + remove_index :users, :index_on_users_lower_username + remove_index :users, :index_on_users_lower_email + end +end +``` + +## Plucking IDs + +This can't be stressed enough: **never** use ActiveRecord's `pluck` to pluck a +set of values into memory only to use them as an argument for another query. For +example, this will make the database **very** sad: + +```ruby +projects = Project.all.pluck(:id) + +MergeRequest.where(source_project_id: projects) +``` + +Instead you can just use sub-queries which perform far better: + +```ruby +MergeRequest.where(source_project_id: Project.all.select(:id)) +``` + +The _only_ time you should use `pluck` is when you actually need to operate on +the values in Ruby itself (e.g. write them to a file). In almost all other cases +you should ask yourself "Can I not just use a sub-query?". + +## Use UNIONs + +UNIONs aren't very commonly used in most Rails applications but they're very +powerful and useful. In most applications queries tend to use a lot of JOINs to +get related data or data based on certain criteria, but JOIN performance can +quickly deteriorate as the data involved grows. + +For example, if you want to get a list of projects where the name contains a +value _or_ the name of the namespace contains a value most people would write +the following query: + +```sql +SELECT * +FROM projects +JOIN namespaces ON namespaces.id = projects.namespace_id +WHERE projects.name ILIKE '%gitlab%' +OR namespaces.name ILIKE '%gitlab%'; +``` + +Using a large database this query can easily take around 800 milliseconds to +run. Using a UNION we'd write the following instead: + +```sql +SELECT projects.* +FROM projects +WHERE projects.name ILIKE '%gitlab%' + +UNION + +SELECT projects.* +FROM projects +JOIN namespaces ON namespaces.id = projects.namespace_id +WHERE namespaces.name ILIKE '%gitlab%'; +``` + +This query in turn only takes around 15 milliseconds to complete while returning +the exact same records. + +This doesn't mean you should start using UNIONs everywhere, but it's something +to keep in mind when using lots of JOINs in a query and filtering out records +based on the joined data. + +GitLab comes with a `Gitlab::SQL::Union` class that can be used to build a UNION +of multiple `ActiveRecord::Relation` objects. You can use this class as +follows: + +```ruby +union = Gitlab::SQL::Union.new([projects, more_projects, ...]) + +Project.from("(#{union.to_sql}) projects") +``` + +## Ordering by Creation Date + +When ordering records based on the time they were created you can simply order +by the `id` column instead of ordering by `created_at`. Because IDs are always +unique and incremented in the order that rows are created this will produce the +exact same results. This also means there's no need to add an index on +`created_at` to ensure consistent performance as `id` is already indexed by +default. + +[gin-index]: http://www.postgresql.org/docs/current/static/gin.html diff --git a/doc/gitlab-basics/basicsimages/compare_braches.png b/doc/gitlab-basics/basicsimages/compare_branches.png Binary files differindex 7eebaed9075..7eebaed9075 100644 --- a/doc/gitlab-basics/basicsimages/compare_braches.png +++ b/doc/gitlab-basics/basicsimages/compare_branches.png diff --git a/doc/hooks/custom_hooks.md b/doc/hooks/custom_hooks.md index 0f2665a3bf7..dcdf49d3379 100644 --- a/doc/hooks/custom_hooks.md +++ b/doc/hooks/custom_hooks.md @@ -2,7 +2,7 @@ **Note: Custom git hooks must be configured on the filesystem of the GitLab server. Only GitLab server administrators will be able to complete these tasks. -Please explore webhooks as an option if you do not have filesystem access. For a user configurable Git Hooks interface, please see [GitLab Enterprise Edition Git Hooks](http://doc.gitlab.com/ee/git_hooks/git_hooks.html).** +Please explore [webhooks](../web_hooks/web_hooks.md) as an option if you do not have filesystem access. For a user configurable Git Hooks interface, please see [GitLab Enterprise Edition Git Hooks](http://doc.gitlab.com/ee/git_hooks/git_hooks.html).** Git natively supports hooks that are executed on different actions. Examples of server-side git hooks include pre-receive, post-receive, and update. diff --git a/doc/incoming_email/README.md b/doc/incoming_email/README.md index 86d205ba7a5..4cfb8402943 100644 --- a/doc/incoming_email/README.md +++ b/doc/incoming_email/README.md @@ -74,10 +74,11 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow [these As mentioned, the part after `+` in the address is ignored, and any email sent here will end up in the mailbox for `incoming@gitlab.example.com`/`gitlab-incoming@gmail.com`. -1. Reconfigure GitLab for the changes to take effect: +1. Reconfigure GitLab and restart mailroom for the changes to take effect: ```sh sudo gitlab-ctl reconfigure + sudo gitlab-ctl restart mailroom ``` 1. Verify that everything is configured correctly: diff --git a/doc/incoming_email/postfix.md b/doc/incoming_email/postfix.md index 18bf3db1744..787d21f7f8f 100644 --- a/doc/incoming_email/postfix.md +++ b/doc/incoming_email/postfix.md @@ -84,7 +84,12 @@ The instructions make the assumption that you will be using the email address `i quit ``` - (Note: The `.` is a literal period on its own line) + _**Note:** The `.` is a literal period on its own line._ + + _**Note:** If you receive an error after entering `rcpt to: incoming@localhost` + then your Postfix `my_network` configuration is not correct. The error will + say 'Temporary lookup failure'. See + [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._ 1. Check if the `incoming` user received the email: @@ -131,7 +136,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo 1. Test the new setup: 1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_. - 2. Check if the `incoming` user received the email: + 1. Check if the `incoming` user received the email: ```sh su - incoming @@ -152,6 +157,12 @@ Courier, which we will install later to add IMAP authentication, requires mailbo q ``` + _**Note:** If `mail` returns an error `Maildir: Is a directory` then your + version of `mail` doesn't support Maildir style mailboxes. Install + `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then, + try the above steps again, substituting `heirloom-mailx` for the `mail` + command._ + 1. Log out of the `incoming` account and go back to being `root`: ```sh 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 81edd8da2b8..c567846f624 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -22,7 +22,7 @@ If the highest number stable branch is unclear please check the [GitLab Blog](ht This guide is long because it covers many cases and includes all commands you need, this is [one of the few installation scripts that actually works out of the box](https://twitter.com/robinvdvleuten/status/424163226532986880). -This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [doc/install/requirements.md](./requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/). +This installation guide was created for and tested on **Debian/Ubuntu** operating systems. Please read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS we recommend using the [Omnibus packages](https://about.gitlab.com/downloads/). This is the official installation guide to set up a production server. To set up a **development installation** or for many other installation options please see [the installation section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#installation). @@ -76,7 +76,7 @@ Make sure you have the right version of Git installed # Install Git sudo apt-get install -y git-core - # Make sure Git is version 1.7.10 or higher, for example 1.7.12 or 2.0.0 + # Make sure Git is version 2.7.4 or higher git --version Is the system packaged Git too old? Remove it and compile from source. @@ -89,8 +89,9 @@ Is the system packaged Git too old? Remove it and compile from source. # Download and compile from source cd /tmp - curl -L --progress https://www.kernel.org/pub/software/scm/git/git-2.4.3.tar.gz | tar xz - cd git-2.4.3/ + curl -O --progress https://www.kernel.org/pub/software/scm/git/git-2.7.4.tar.gz + echo '7104c4f5d948a75b499a954524cb281fe30c6649d8abe20982936f75ec1f275b git-2.7.4.tar.gz' | shasum -a256 -c - && tar -xzf git-2.7.4.tar.gz + cd git-2.7.4/ ./configure make prefix=/usr/local all @@ -107,18 +108,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 version is 2.1.x. Ruby 2.2 and 2.3 are +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.1/ruby-2.1.8.tar.gz + echo 'c7e50159357afd87b13dc5eaf4ac486a70011149 ruby-2.1.8.tar.gz' | shasum -c - && tar xzf ruby-2.1.8.tar.gz + cd ruby-2.1.8 ./configure --disable-install-rdoc make sudo make install @@ -135,11 +143,11 @@ gitlab-workhorse we need a Go compiler. The instructions below assume you use 64-bit Linux. You can find downloads for other platforms at the [Go download page](https://golang.org/dl). - curl -O --progress https://storage.googleapis.com/golang/go1.5.1.linux-amd64.tar.gz - echo '46eecd290d8803887dec718c691cc243f2175fe0 go1.5.1.linux-amd64.tar.gz' | shasum -c - && \ - sudo tar -C /usr/local -xzf go1.5.1.linux-amd64.tar.gz + curl -O --progress https://storage.googleapis.com/golang/go1.5.3.linux-amd64.tar.gz + echo '43afe0c5017e502630b1aea4d44b8a7f059bf60d7f29dfd58db454d4e4e0ae53 go1.5.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.5.3.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ - rm go1.5.1.linux-amd64.tar.gz + rm go1.5.3.linux-amd64.tar.gz ## 4. System Users @@ -154,18 +162,11 @@ We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](da # Install the database packages sudo apt-get install -y postgresql postgresql-client libpq-dev - # Login to PostgreSQL - sudo -u postgres psql -d template1 - # Create a user for GitLab - # Do not type the 'template1=#', this is part of the prompt - template1=# CREATE USER git CREATEDB; + sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" # Create the GitLab production database & grant all privileges on database - template1=# CREATE DATABASE gitlabhq_production OWNER git; - - # Quit the database session - template1=# \q + sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;" # Try connecting to the new database with the new user sudo -u git -H psql -d gitlabhq_production @@ -175,25 +176,20 @@ We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](da ## 6. Redis -As of this writing, most Debian/Ubuntu distributions ship with Redis 2.2 or -2.4. GitLab requires at least Redis 2.8. - -Ubuntu users [can use a PPA](https://launchpad.net/~chris-lea/+archive/ubuntu/redis-server) -to install a recent version of Redis. +GitLab requires at least Redis 2.8. -The following instructions cover building and installing Redis from scratch: +If you are using Debian 8 or Ubuntu 14.04 and up, then you can simply install +Redis 2.8 with: ```sh -# Build Redis -wget http://download.redis.io/releases/redis-2.8.23.tar.gz -tar xzf redis-2.8.23.tar.gz -cd redis-2.8.23 -make +sudo apt-get install redis-server +``` -# Install Redis -cd utils -sudo ./install_server.sh +If you are using Debian 7 or Ubuntu 12.04, follow the special documentation +on [an alternate Redis installation](redis.md). Once done, follow the rest of +the guide here. +``` # Configure redis to use sockets sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig @@ -217,7 +213,7 @@ if [ -d /etc/tmpfiles.d ]; then fi # Activate the changes to redis.conf -sudo service redis_6379 start +sudo service redis-server restart # Add git to the redis group sudo usermod -aG redis git @@ -231,9 +227,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-3-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 8-6-stable gitlab -**Note:** You can change `8-3-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `8-6-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -260,8 +256,12 @@ sudo usermod -aG redis git sudo chmod -R u+rwX tmp/pids/ sudo chmod -R u+rwX tmp/sockets/ - # Make sure GitLab can write to the public/uploads/ directory - sudo chmod -R u+rwX public/uploads + # Create the public/uploads/ directory + sudo -u git -H mkdir public/uploads/ + + # Make sure only the GitLab user has access to the public/uploads/ directory + # now that files in public/uploads are served by gitlab-workhorse + sudo chmod 0700 public/uploads # Change the permissions of the directory where CI build traces are stored sudo chmod -R u+rwX builds/ @@ -348,7 +348,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.1 + sudo -u git -H git checkout 0.6.5 sudo -u git -H make ### Initialize Database and Activate Advanced Features @@ -363,9 +363,9 @@ GitLab Shell is an SSH access and repository management software developed speci # When done you see 'Administrator account created:' -**Note:** You can set the Administrator/root password by supplying it in environmental variable `GITLAB_ROOT_PASSWORD` as seen below. If you don't set the password (and it is set to the default one) please wait with exposing GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login you'll be forced to change the default password. +**Note:** You can set the Administrator/root password and e-mail by supplying them in environmental variables, `GITLAB_ROOT_PASSWORD` and `GITLAB_ROOT_EMAIL` respectively, as seen below. If you don't set the password (and it is set to the default one) please wait with exposing GitLab to the public internet until the installation is done and you've logged into the server the first time. During the first login you'll be forced to change the default password. - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword + sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword GITLAB_ROOT_EMAIL=youremail ### Secure secrets.yml @@ -461,12 +461,15 @@ NOTE: Supply `SANITIZE=true` environment variable to `gitlab:check` to omit proj ### Initial Login -Visit YOUR_SERVER in your web browser for your first GitLab login. The setup has created a default admin account for you. You can use it to log in: +Visit YOUR_SERVER in your web browser for your first GitLab login. - root - 5iveL!fe +If you didn't [provide a root password during setup](#initialize-database-and-activate-advanced-features), +you'll be redirected to a password reset screen to provide the password for the +initial administrator account. Enter your desired password and you'll be +redirected back to the login screen. -**Important Note:** On login you'll be prompted to change the password. +The default account's username is **root**. Provide the password you created +earlier and login. After login you can change the username if you wish. **Enjoy!** @@ -474,6 +477,11 @@ You can use `sudo service gitlab start` and `sudo service gitlab stop` to start ## Advanced Setup Tips +### Relative URL support + +See the [Relative URL documentation](relative_url.md) for more information on +how to configure GitLab with a relative URL. + ### Using HTTPS To use GitLab with HTTPS: @@ -552,6 +560,10 @@ Apart from the always supported markdown style there are other rich text files t If you see this message when attempting to clone a repository hosted by GitLab, this is likely due to an outdated Nginx or Apache configuration, or a missing or -misconfigured `gitlab-git-http-server` instance. Double-check that you've -[installed Go](#3-go), [installed gitlab-git-http-server](#install-gitlab-git-http-server), +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/redis.md b/doc/install/redis.md new file mode 100644 index 00000000000..4075e6283d0 --- /dev/null +++ b/doc/install/redis.md @@ -0,0 +1,60 @@ +# Install Redis on old distributions + +GitLab requires at least Redis 2.8. The following guide is for Debian 7 and +Ubuntu 12.04. If you are using Debian 8 or Ubuntu 14.04 and up, follow the +[installation guide](installation.md). + +## Install Redis 2.8 in Debian 7 + +Redis 2.8 is included in the Debian Wheezy [backports] repository. + +1. Edit `/etc/apt/sources.list` and add the following line: + + ``` + deb http://http.debian.net/debian wheezy-backports main + ``` + +1. Update the repositories: + + ``` + sudo apt-get update + ``` + +1. Install `redis-server`: + + ``` + sudo apt-get -t wheezy-backports install redis-server + ``` + +1. Follow the rest of the [installation guide](installation.md). + +## Install Redis 2.8 in Ubuntu 12.04 + +We will [use a PPA](https://launchpad.net/~chris-lea/+archive/ubuntu/redis-server) +to install a recent version of Redis. + +1. Install the PPA repository: + + ``` + sudo add-apt-repository ppa:chris-lea/redis-server + ``` + + Your system will now fetch the PPA's key. This enables your Ubuntu system to + verify that the packages in the PPA have not been interfered with since they + were built. + +1. Update the repositories: + + ``` + sudo apt-get update + ``` + +1. Install `redis-server`: + + ``` + sudo apt-get install redis-server + ``` + +1. Follow the rest of the [installation guide](installation.md). + +[backports]: http://backports.debian.org/Instructions/ "Debian backports website" diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md new file mode 100644 index 00000000000..0245febfcd8 --- /dev/null +++ b/doc/install/relative_url.md @@ -0,0 +1,136 @@ +## Install GitLab under a relative URL + +_**Note:** +This document describes how to run GitLab under a relative URL for installations +from source. If you are using an Omnibus package, +[the steps are different][omnibus-rel]. Use this guide along with the +[installation guide](installation.md) if you are installing GitLab for the +first time._ + +--- + +While it is recommended to install GitLab on its own (sub)domain, sometimes +this is not possible due to a variety of reasons. In that case, GitLab can also +be installed under a relative URL, for example `https://example.com/gitlab`. + +There is no limit to how deeply nested the relative URL can be. For example you +could serve GitLab under `/foo/bar/gitlab/git` without any issues. + +Note that by changing the URL on an existing GitLab installation, all remote +URLs will change, so you'll have to manually edit them in any local repository +that points to your GitLab instance. + +--- + +The TL;DR list of configuration files that you need to change in order to +serve GitLab under a relative URL is: + +- `/home/git/gitlab/config/initializers/relative_url.rb` +- `/home/git/gitlab/config/gitlab.yml` +- `/home/git/gitlab/config/unicorn.rb` +- `/home/git/gitlab-shell/config.yml` +- `/etc/default/gitlab` + +After all the changes you need to recompile the assets and [restart GitLab]. + +### Relative URL requirements + +If you configure GitLab with a relative URL, the assets (JavaScript, CSS, fonts, +images, etc.) will need to be recompiled, which is a task which consumes a lot +of CPU and memory resources. To avoid out-of-memory errors, you should have at +least 2GB of RAM available on your system, while we recommend 4GB RAM, and 4 or +8 CPU cores. + +See the [requirements](requirements.md) document for more information. + +### Enable relative URL in GitLab + +_**Note:** +Do not make any changes to your web server configuration file regarding +relative URL. The relative URL support is implemented by GitLab Workhorse._ + +--- + +Before following the steps below to enable relative URL in GitLab, some +assumptions are made: + +- GitLab is served under `/gitlab` +- The directory under which GitLab is installed is `/home/git/` + +Make sure to follow all steps below: + +1. (Optional) If you run short on resources, you can temporarily free up some + memory by shutting down the GitLab service with the following command: + + ```shell + sudo service gitlab stop + ``` + +1. Create `/home/git/gitlab/config/initializers/relative_url.rb` + + ```shell + cp /home/git/gitlab/config/initializers/relative_url.rb.sample \ + /home/git/gitlab/config/initializers/relative_url.rb + ``` + + and change the following line: + + ```ruby + config.relative_url_root = "/gitlab" + ``` + +1. Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the + following line: + + ```yaml + relative_url_root: /gitlab + ``` + +1. Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the + following line: + + ```ruby + ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab" + ``` + +1. Edit `/home/git/gitlab-shell/config.yml` and append the relative path to + the following line: + + ```yaml + gitlab_url: http://127.0.0.1/gitlab + ``` + +1. Make sure you have copied the supplied init script and the defaults file + as stated in the [installation guide](installation.md#install-init-script). + Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the + `-authBackend` setting to read like: + + ```shell + -authBackend http://127.0.0.1:8080/gitlab + ``` + + **Note:** + If you are using a custom init script, make sure to edit the above + gitlab-workhorse setting as needed. + +1. After all the above changes recompile the assets. This is an important task + and will take some time to complete depending on the server resources: + + ``` + cd /home/git/gitlab + sudo -u git -H bundle exec rake assets:clean assets:precompile RAILS_ENV=production + ``` + +1. [Restart GitLab][] for the changes to take effect. + +### Disable relative URL in GitLab + +To disable the relative URL: + +1. Remove `/home/git/gitlab/config/initializers/relative_url.rb` + +1. Follow the same as above starting from 2. and set up the + GitLab URL to one that doesn't contain a relative path. + +[omnibus-rel]: http://doc.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to setup relative URL in Omnibus GitLab" +[restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab" diff --git a/doc/install/requirements.md b/doc/install/requirements.md index c0ccdd37458..03cb08dd1f1 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -22,7 +22,7 @@ For the installations options please see [the installation page on the GitLab we - FreeBSD On the above unsupported distributions is still possible to install GitLab yourself. -Please see the [installation from source guide](https://github.com/gitlabhq/gitlabhq/blob/master/doc/install/installation.md) and the [unofficial installation guides](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Unofficial-Installation-Guides) on the public wiki for more information. +Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information. ### Non-Unix operating systems such as Windows @@ -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 and currently does not work with versions 2.2 or 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. @@ -64,9 +66,9 @@ If you have enough RAM memory and a recent CPU the speed of GitLab is mainly lim You need at least 2GB of addressable memory (RAM + swap) to install and use GitLab! With less memory GitLab will give strange errors during the reconfigure run and 500 errors during usage. -- 512MB RAM + 1.5GB of swap is the absolute minimum but we strongly **advise against** this amount of memory. See the unicorn worker section below for more advise. -- 1GB RAM + 1GB swap supports up to 100 users but it will be slow -- **2GB RAM** is the **recommended** memory size and supports up to 100 users +- 512MB RAM + 1.5GB of swap is the absolute minimum but we strongly **advise against** this amount of memory. See the unicorn worker section below for more advice. +- 1GB RAM + 1GB swap supports up to 100 users but it will be very slow +- **2GB RAM** is the **recommended** memory size for all installations and supports up to 100 users - 4GB RAM supports up to 1,000 users - 8GB RAM supports up to 2,000 users - 16GB RAM supports up to 4,000 users @@ -95,6 +97,17 @@ To change the Unicorn workers when you have the Omnibus package please see [the If you want to run the database separately expect a size of about 1 MB per user. +### PostgreSQL Requirements + +Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every +GitLab database. This extension can be enabled (using a PostgreSQL super user) +by running the following query for every database: + + CREATE EXTENSION pg_trgm; + +On some systems you may need to install an additional package (e.g. +`postgresql-contrib`) for this extension to become available. + ## Redis and Sidekiq Redis stores all user sessions and the background task queue. @@ -109,4 +122,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 2a9f76533b7..7c8f785a61f 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -1,27 +1,72 @@ # GitLab Integration -GitLab integrates with multiple third-party services to allow external issue trackers and external authentication. +GitLab integrates with multiple third-party services to allow external issue +trackers and external authentication. See the documentation below for details on how to configure these services. -- [Jira](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 - [OAuth2 provider](oauth_provider.md) OAuth2 application creation - [Gmail actions buttons](gmail_action_buttons_for_gitlab.md) Adds GitLab actions to messages - [reCAPTCHA](recaptcha.md) Configure GitLab to use Google reCAPTCHA for new users +- [Akismet](akismet.md) Configure Akismet to stop spam -GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html) and [advanced Jenkins support](http://doc.gitlab.com/ee/integration/jenkins.html). +GitLab Enterprise Edition contains [advanced Jenkins support][jenkins]. ## Project services -Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, Pivotal Tracker, and Slack are available in the form of a Project Service. -You can find these within GitLab in the Services page under Project Settings if you are at least a master on the project. -Project Services are a bit like plugins in that they allow a lot of freedom in adding functionality to GitLab, for example there is also a service that can send an email every time someone pushes new commits. -Because GitLab is open source we can ship with the code and tests for all plugins. -This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. -For an overview of what projects services are available without logging in please see the [project_services directory](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services). +Integration with services such as Campfire, Flowdock, Gemnasium, HipChat, +Pivotal Tracker, and Slack are available in the form of a [Project Service][]. +You can find these within GitLab in the Services page under Project Settings if +you are at least a master on the project. +Project Services are a bit like plugins in that they allow a lot of freedom in +adding functionality to GitLab. For example there is also a service that can +send an email every time someone pushes new commits. + +Because GitLab is open source we can ship with the code and tests for all +plugins. This allows the community to keep the plugins up to date so that they +always work in newer GitLab versions. + +For an overview of what projects services are available without logging in, +please see the [project_services directory][projects-code]. + +[jenkins]: http://doc.gitlab.com/ee/integration/jenkins.html +[Project Service]: ../project_services/project_services.md +[projects-code]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/models/project_services + +## SSL certificate errors + +When trying to integrate GitLab with services that are using self-signed certificates, +it is very likely that SSL certificate errors will occur on different parts of the +application, most likely Sidekiq. There are 2 approaches you can take to solve this: + +1. Add the root certificate to the trusted chain of the OS. +1. If using Omnibus, you can add the certificate to GitLab's trusted certificates. + +**OS main trusted chain** + +This [resource](http://kb.kerio.com/product/kerio-connect/server-configuration/ssl-certificates/adding-trusted-root-certificates-to-the-server-1605.html) +has all the information you need to add a certificate to the main trusted chain. + +This [answer](http://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) +at SuperUser also has relevant information. + +**Omnibus Trusted Chain** + +It is enough to concatenate the certificate to the main trusted certificate: + +```bash +cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem +``` + +After that restart GitLab with: + +```bash +sudo gitlab-ctl restart +``` diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md new file mode 100644 index 00000000000..5cc09bd536d --- /dev/null +++ b/doc/integration/akismet.md @@ -0,0 +1,30 @@ +# Akismet + +GitLab leverages [Akismet](http://akismet.com) to protect against spam. Currently +GitLab uses Akismet to prevent users who are not members of a project from +creating spam via the GitLab API. Detected spam will be rejected, and +an entry in the "Spam Log" section in the Admin page will be created. + +Privacy note: GitLab submits the user's IP and user agent to Akismet. Note that +adding a user to a project will disable the Akismet check and prevent this +from happening. + +## Configuration + +To use Akismet: + +1. Go to the URL: https://akismet.com/account/ + +2. Sign-in or create a new account. + +3. Click on "Show" to reveal the API key. + +4. Go to Applications Settings on Admin Area (`admin/application_settings`) + +5. Check the `Enable Akismet` checkbox + +6. Fill in the API key from step 3. + +7. Save the configuration. + + diff --git a/doc/integration/auth0.md b/doc/integration/auth0.md new file mode 100644 index 00000000000..e5247082a89 --- /dev/null +++ b/doc/integration/auth0.md @@ -0,0 +1,89 @@ +# Auth0 OmniAuth Provider + +To enable the Auth0 OmniAuth provider, you must create an Auth0 account, and an +application. + +1. Sign in to the [Auth0 Console](https://manage.auth0.com). If you need to +create an account, you can do so at the same link. + +1. Select "New App/API". + +1. Provide the Application Name ('GitLab' works fine). + +1. Once created, you should see the Quick Start options. Disregard them and +select 'Settings' above the Quick Start options. + +1. At the top of the Settings screen, you should see your Domain, Client ID and +Client Secret. Take note of these as you'll need to put them in the +configuration file. For example: + - Domain: `test1234.auth0.com` + - Client ID: `t6X8L2465bNePWLOvt9yi41i` + - Client Secret: `KbveM3nqfjwCbrhaUy_gDu2dss8TIlHIdzlyf33pB7dEK5u_NyQdp65O_o02hXs2` + +1. Fill in the Allowed Callback URLs: + - http://`YOUR_GITLAB_URL`/users/auth/auth0/callback (or) + - https://`YOUR_GITLAB_URL`/users/auth/auth0/callback + +1. Fill in the Allowed Origins (CORS): + - http://`YOUR_GITLAB_URL` (or) + - https://`YOUR_GITLAB_URL` + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "auth0", + "args" => { client_id: 'YOUR_AUTH0_CLIENT_ID'', + client_secret: 'YOUR_AUTH0_CLIENT_SECRET', + namespace: 'YOUR_AUTH0_DOMAIN' + } + } + ] + ``` + + For installations from source: + + ```yaml + - { name: 'auth0', + args: { + client_id: 'YOUR_AUTH0_CLIENT_ID', + client_secret: 'YOUR_AUTH0_CLIENT_SECRET', + namespace: 'YOUR_AUTH0_DOMAIN' + } + } + ``` + +1. Change `YOUR_AUTH0_CLIENT_ID` to the client ID from the Auth0 Console page +from step 5. + +1. Change `YOUR_AUTH0_CLIENT_SECRET` to the client secret from the Auth0 Console +page from step 5. + +1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md) +for the changes to take effect. + +On the sign in page there should now be an Auth0 icon below the regular sign in +form. Click the icon to begin the authentication process. Auth0 will ask the +user to sign in and authorize the GitLab application. If everything goes well +the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/azure.md b/doc/integration/azure.md new file mode 100644 index 00000000000..48dddf7df44 --- /dev/null +++ b/doc/integration/azure.md @@ -0,0 +1,83 @@ +# Microsoft Azure OAuth2 OmniAuth Provider + +To enable the Microsoft Azure OAuth2 OmniAuth provider you must register your application with Azure. Azure will generate a client ID and secret key for you to use. + +1. Sign in to the [Azure Management Portal](https://manage.windowsazure.com>). + +1. Select "Active Directory" on the left and choose the directory you want to use to register GitLab. + +1. Select "Applications" at the top bar and click the "Add" button the bottom. + +1. Select "Add an application my organization is developing". + +1. Provide the project information and click the "Next" button. + - Name: 'GitLab' works just fine here. + - Type: 'WEB APPLICATION AND/OR WEB API' + +1. On the "App properties" page enter the needed URI's and click the "Complete" button. + - SIGN-IN URL: Enter the URL of your GitLab installation (e.g 'https://gitlab.mycompany.com/') + - APP ID URI: Enter the endpoint URL for Microsoft to use, just has to be unique (e.g 'https://mycompany.onmicrosoft.com/gitlab') + +1. Select "Configure" in the top menu. + +1. Add a "Reply URL" pointing to the Azure OAuth callback of your GitLab installation (e.g. https://gitlab.mycompany.com/users/auth/azure_oauth2/callback). + +1. Create a "Client secret" by selecting a duration, the secret will be generated as soon as you click the "Save" button in the bottom menu.. + +1. Note the "CLIENT ID" and the "CLIENT SECRET". + +1. Select "View endpoints" from the bottom menu. + +1. You will see lots of endpoint URLs in the form 'https://login.microsoftonline.com/TENANT ID/...', note down the TENANT ID part of one of those endpoints. + +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. + +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "azure_oauth2", + "args" => { + "client_id" => "CLIENT ID", + "client_secret" => "CLIENT SECRET", + "tenant_id" => "TENANT ID", + } + } + ] + ``` + + For installations from source: + + ``` + - { name: 'azure_oauth2', + args: { client_id: "CLIENT ID", + client_secret: "CLIENT SECRET", + tenant_id: "TENANT ID" } } + ``` + +1. Replace 'CLIENT ID', 'CLIENT SECRET' and 'TENANT ID' with the values you got above. + +1. Save the configuration file. + +1. Restart GitLab for the changes to take effect. + +On the sign in page there should now be a Microsoft icon below the regular sign in form. Click the icon to begin the authentication process. Microsoft will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md index 3e660cfba1e..a2d7e922aad 100644 --- a/doc/integration/external-issue-tracker.md +++ b/doc/integration/external-issue-tracker.md @@ -1,44 +1,30 @@ # External issue tracker -GitLab has a great issue tracker but you can also use an external issue tracker such as Jira, Bugzilla or Redmine. You can configure issue trackers per GitLab project. For instance, if you configure Jira it allows you to do the following: +GitLab has a great issue tracker but you can also use an external one such as +Jira or Redmine. Issue trackers are configurable per GitLab project and allow +you to do the following: -- the 'Issues' link on the GitLab project pages takes you to the appropriate Jira issue index; -- clicking 'New issue' on the project dashboard creates a new Jira issue; -- To reference Jira issue PROJECT-1234 in comments, use syntax PROJECT-1234. Commit messages get turned into HTML links to the corresponding Jira issue. - - - -GitLab Enterprise Edition contains [advanced JIRA support](http://doc.gitlab.com/ee/integration/jira.html). +- the **Issues** link on the GitLab project pages takes you to the appropriate + issue index of the external tracker +- clicking **New issue** on the project dashboard creates a new issue on the + external tracker ## Configuration -### Project Service +The configuration is done via a project's **Services**. -You can enable an external issue tracker per project. As an example, we will configure `Redmine` for project named gitlab-ci. - -Fill in the required details on the page: +### Project Service - +To enable an external issue tracker you must configure the appropriate **Service**. +Visit the links below for details: -* `description` A name for the issue tracker (to differentiate between instances, for example). -* `project_url` The URL to the project in Redmine which is being linked to this GitLab project. -* `issues_url` The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the url. This id is used by GitLab as a placeholder to replace the issue number. -* `new_issue_url` This is the URL to create a new issue in Redmine for the project linked to this GitLab project. +- [Redmine](../project_services/redmine.md) +- [Jira](../project_services/jira.md) ### Service Template -It is necessary to configure the external issue tracker per project, because project specific details are needed for the integration with GitLab. -The admin can add a service template that sets a default for each project. This makes it much easier to configure individual projects. - -In GitLab Admin section, navigate to `Service Templates` and choose the service template you want to create: - - - -After the template is created, the template details will be pre-filled on the project service page. - -NOTE: For each project, you will still need to configure the issue tracking URLs by replacing `:issues_tracker_id` in the above screenshot -with the ID used by your external issue tracker. Prior to GitLab v7.8, this ID was configured in the project settings, and GitLab would automatically -update the URL configured in `gitlab.yml`. This behavior is now depecated, and all issue tracker URLs must be configured directly -within the project's Services settings. +To save you the hassle from configuring each project's service individually, +GitLab provides the ability to set Service Templates which can then be +overridden in each project's settings. -Support to add your commits to the Jira ticket automatically is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jira.html). +Read more on [Services Templates](../project_services/services_templates.md). 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/img/akismet_settings.png b/doc/integration/img/akismet_settings.png Binary files differnew file mode 100644 index 00000000000..ccdd3adb1c5 --- /dev/null +++ b/doc/integration/img/akismet_settings.png 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/img/oauth_provider_admin_application.png b/doc/integration/img/oauth_provider_admin_application.png Binary files differnew file mode 100644 index 00000000000..a2d8e14c120 --- /dev/null +++ b/doc/integration/img/oauth_provider_admin_application.png diff --git a/doc/integration/img/oauth_provider_application_form.png b/doc/integration/img/oauth_provider_application_form.png Binary files differnew file mode 100644 index 00000000000..3a676b22393 --- /dev/null +++ b/doc/integration/img/oauth_provider_application_form.png diff --git a/doc/integration/img/oauth_provider_application_id_secret.png b/doc/integration/img/oauth_provider_application_id_secret.png Binary files differnew file mode 100644 index 00000000000..6d68df001af --- /dev/null +++ b/doc/integration/img/oauth_provider_application_id_secret.png diff --git a/doc/integration/img/oauth_provider_authorized_application.png b/doc/integration/img/oauth_provider_authorized_application.png Binary files differnew file mode 100644 index 00000000000..efc3b807d71 --- /dev/null +++ b/doc/integration/img/oauth_provider_authorized_application.png diff --git a/doc/integration/img/oauth_provider_user_wide_applications.png b/doc/integration/img/oauth_provider_user_wide_applications.png Binary files differnew file mode 100644 index 00000000000..45ad8a6d468 --- /dev/null +++ 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 624601d0fac..78aa6634116 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -1,113 +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, configuration is explained [here](#configuration). -If you have one Jira instance you can pre-fill the settings page with a default template. To configure the template [see external issue tracker document](external-issue-tracker.md#service-template)). - -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, 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 - -### GitLab 7.8 EE and up with JIRA v6.x - -To enable JIRA integration in a project, navigate to the project Settings page and go to Services. Here you will find JIRA. - -Fill in the required details on the page: - - - -* `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](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 7.8 and up contain various integration improvements. We strongly recommend upgrading.** - - -In `gitlab.yml` enable [JIRA issue tracker section by uncommenting the lines](https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115). -This will make sure that all issues within GitLab are pointing to the JIRA issue tracker. - -We can also enable JIRA service that will allow us to interact with JIRA issues. - -For example, we can close issues in JIRA by a commit in GitLab. - -Go to project settings page and fill in the project name for the JIRA project: - - - -Next, go to the services page and find JIRA. - - - -1. Tick the active check box to enable the service. -1. Supply the url to JIRA server, for example http://jira.sample -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 -1. Optional: supply the JIRA issue transition ID (issue transition to closed). This is dependant on JIRA settings, default is 2 -1. Save - -Now we should be able to interact with JIRA issues. +This document was moved under [project_services/jira](../project_services/jira.md). diff --git a/doc/integration/jira_service_page.png b/doc/integration/jira_service_page.png Binary files differdeleted file mode 100644 index 69ec44e826f..00000000000 --- a/doc/integration/jira_service_page.png +++ /dev/null diff --git a/doc/integration/ldap.md b/doc/integration/ldap.md index 845f588f913..cf1f98492ea 100644 --- a/doc/integration/ldap.md +++ b/doc/integration/ldap.md @@ -48,6 +48,11 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' password: '_the_password_of_the_bind_user' + # Set a timeout, in seconds, for LDAP queries. This helps avoid blocking + # a request if the LDAP server becomes unresponsive. + # A value of 0 means there is no timeout. + timeout: 10 + # This setting specifies if LDAP server is Active Directory LDAP server. # For non AD servers it skips the AD specific queries. # If your LDAP server is not AD, set this to false. @@ -199,3 +204,25 @@ When setting `method: ssl`, the underlying authentication method used by `omniauth-ldap` is `simple_tls`. This method establishes TLS encryption with the LDAP server before any LDAP-protocol data is exchanged but no validation of the LDAP server's SSL certificate is performed. + +## Troubleshooting + +### Invalid credentials when logging in + +Make sure the user you are binding with has enough permissions to read the user's +tree and traverse it. + +Also make sure that the `user_filter` is not blocking otherwise valid users. + +To make sure that the LDAP settings are correct and GitLab can see your users, +execute the following command: + + +```bash +# For Omnibus installations +sudo gitlab-rake gitlab:ldap:check + +# For installations from source +sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production +``` + diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 192c321f712..5f8bb57365c 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,35 +1,80 @@ -## GitLab as OAuth2 authentication service provider +# GitLab as OAuth2 authentication service provider -This document is about using GitLab as an OAuth authentication service provider to sign into other services. -If you want to use other OAuth authentication service providers to sign into GitLab please see the [OAuth2 client documentation](../api/oauth2.md) +This document is about using GitLab as an OAuth authentication service provider +to sign in to other services. -OAuth2 provides client applications a 'secure delegated access' to server resources on behalf of a resource owner. Or you can allow users to sign in to your application with their GitLab.com account. -In fact OAuth allows to issue access token to third-party clients by an authorization server, -with the approval of the resource owner, or end-user. -Mostly, OAuth2 is using for SSO (Single sign-on). But you can find a lot of different usages for this functionality. -For example, our feature 'GitLab Importer' is using OAuth protocol to give an access to repositories without sharing user credentials to GitLab.com account. -Also GitLab.com application can be used for authentication to your GitLab instance if needed [GitLab OmniAuth](gitlab.md). +If you want to use other OAuth authentication service providers to sign in to +GitLab, please see the [OAuth2 client documentation](../api/oauth2.md). -GitLab has two ways to add new OAuth2 application to an instance, you can add application as regular user and through admin area. So GitLab actually can have an instance-wide and a user-wide applications. There is no defferences between them except the different permission levels. +## Introduction to OAuth -### Adding application through profile -Go to your profile section 'Application' and press button 'New Application' +[OAuth] provides to client applications a 'secure delegated access' to server +resources on behalf of a resource owner. In fact, OAuth allows an authorization +server to issue access tokens to third-party clients with the approval of the +resource owner, or the end-user. - +OAuth is mostly used as a Single Sign-On service (SSO), but you can find a +lot of different uses for this functionality. For example, you can allow users +to sign in to your application with their GitLab.com account, or GitLab.com +can be used for authentication to your GitLab instance +(see [GitLab OmniAuth](gitlab.md)). -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. +The 'GitLab Importer' feature is also using the OAuth protocol to give access +to repositories without sharing user credentials to your GitLab.com account. - +--- -### Authorized application -Every application you authorized will be shown in your "Authorized application" sections. +GitLab supports two ways of adding a new OAuth2 application to an instance. You +can either add an application as a regular user or add it in the admin area. +What this means is that GitLab can actually have instance-wide and a user-wide +applications. There is no difference between them except for the different +permission levels they are set (user/admin). - +## Adding an application through the profile -At any time you can revoke access just clicking button "Revoke" +In order to add a new application via your profile, navigate to +**Profile Settings > Applications** and select **New Application**. -### OAuth applications in admin area + -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 +In the application form, enter a **Name** (arbitrary), and make sure to set up +correctly the **Redirect URI** which is the URL where users will be sent after +they authorize with GitLab. + + + +--- + +When you hit **Submit** you will be provided with the application ID and +the application secret which you can then use with your application that +connects to GitLab. + + + +--- + +## OAuth applications in the admin area + +To create an application that does not belong to a certain user, you can create +it from the admin area. + + + +--- + +## Authorized applications + +Every application you authorized to use your GitLab credentials will be shown +in the **Authorized applications** section under **Profile Settings > Applications**. + + + +--- + +As you can see, the default scope `api` is used, which is the only scope that +GitLab supports so far. At any time you can revoke any access by just clicking +**Revoke**. + +[oauth]: http://oauth.net/2/ "OAuth website" diff --git a/doc/integration/oauth_provider/admin_application.png b/doc/integration/oauth_provider/admin_application.png Binary files differdeleted file mode 100644 index a5f34512aa8..00000000000 --- a/doc/integration/oauth_provider/admin_application.png +++ /dev/null diff --git a/doc/integration/oauth_provider/application_form.png b/doc/integration/oauth_provider/application_form.png Binary files differdeleted file mode 100644 index ae135db2627..00000000000 --- a/doc/integration/oauth_provider/application_form.png +++ /dev/null diff --git a/doc/integration/oauth_provider/authorized_application.png b/doc/integration/oauth_provider/authorized_application.png Binary files differdeleted file mode 100644 index d3ce05be9cc..00000000000 --- a/doc/integration/oauth_provider/authorized_application.png +++ /dev/null diff --git a/doc/integration/oauth_provider/user_wide_applications.png b/doc/integration/oauth_provider/user_wide_applications.png Binary files differdeleted file mode 100644 index 719e1974068..00000000000 --- a/doc/integration/oauth_provider/user_wide_applications.png +++ /dev/null diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index f2b1721fc03..25f35988305 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -1,27 +1,56 @@ # OmniAuth -GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. +GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and +other popular services. -Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms. +Configuring OmniAuth does not prevent standard GitLab authentication or LDAP +(if configured) from continuing to work. Users can choose to sign in using any +of the configured mechanisms. - [Initial OmniAuth Configuration](#initial-omniauth-configuration) - [Supported Providers](#supported-providers) - [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) - [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) +## Supported Providers + +This is a list of the current supported OmniAuth providers. Before proceeding +on each provider's documentation, make sure to first read this document as it +contains some settings that are common for all providers. + +- [GitHub](github.md) +- [Bitbucket](bitbucket.md) +- [GitLab.com](gitlab.md) +- [Google](google.md) +- [Facebook](facebook.md) +- [Twitter](twitter.md) +- [Shibboleth](shibboleth.md) +- [SAML](saml.md) +- [Crowd](crowd.md) +- [Azure](azure.md) +- [Auth0](auth0.md) + ## Initial OmniAuth Configuration -Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. +Before configuring individual OmniAuth providers there are a few global settings +that are in common for all providers that we need to consider. - Omniauth needs to be enabled, see details below for example. -- `allow_single_sign_on` defaults to `false`. If `false` users must be created manually or they will not be able to -sign in via OmniAuth. -- `block_auto_created_users` defaults to `true`. If `true` auto created users will be blocked by default and will -have to be unblocked by an administrator before they are able to sign in. -- **Note:** If you set `allow_single_sign_on` to `true` and `block_auto_created_users` to `false` please be aware -that any user on the Internet will be able to successfully sign in to your GitLab without administrative approval. - -If you want to change these settings: +- `allow_single_sign_on` allows you to specify the providers you want to allow to + automatically create an account. It defaults to `false`. If `false` users must + be created manually or they will not be able to sign in via OmniAuth. +- `block_auto_created_users` defaults to `true`. If `true` auto created users will + be blocked by default and will have to be unblocked by an administrator before + they are able to sign in. + +>**Note:** +If you set `block_auto_created_users` to `false`, make sure to only +define providers under `allow_single_sign_on` that you are able to control, like +SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on +the Internet will be able to successfully sign in to your GitLab without +administrative approval. + +To change these settings: * **For omnibus package** @@ -31,11 +60,16 @@ If you want to change these settings: sudo editor /etc/gitlab/gitlab.rb ``` - and change + and change: - ``` + ```ruby gitlab_rails['omniauth_enabled'] = true - gitlab_rails['omniauth_allow_single_sign_on'] = false + + # CAUTION! + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. + # User accounts will be created automatically when authentication was successful. + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'twitter'] gitlab_rails['omniauth_block_auto_created_users'] = true ``` @@ -49,55 +83,57 @@ If you want to change these settings: sudo -u git -H editor config/gitlab.yml ``` - and change the following section + and change the following section: - ``` + ```yaml ## OmniAuth settings omniauth: # Allow login via Twitter, Google, etc. using OmniAuth providers enabled: true # CAUTION! - # This allows users to login without having a user account first (default: false). + # This allows users to login without having a user account first. Define the allowed providers + # using an array, e.g. ["saml", "twitter"], or as true/false to allow all providers or none. # User accounts will be created automatically when authentication was successful. - allow_single_sign_on: false + allow_single_sign_on: ["saml", "twitter"] + # Locks down those users until they have been cleared by the admin (default: true). block_auto_created_users: true ``` -Now we can choose one or more of the Supported Providers 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) +Now we can choose one or more of the Supported Providers listed above to continue +the configuration process. ## Enable OmniAuth for an Existing User -Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. +Existing users can enable OmniAuth for specific providers after the account is +created. For example, if the user originally signed in with LDAP, an OmniAuth +provider such as Twitter can be enabled. Follow the steps below to enable an +OmniAuth provider for an existing user. 1. Sign in normally - whether standard sign in, LDAP, or another OmniAuth provider. 1. Go to profile settings (the silhouette icon in the top right corner). 1. Select the "Account" tab. 1. Under "Connected Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. +1. The user will be redirected to the provider. Once the user authorized GitLab + they will be redirected back to GitLab. The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. ## Using Custom Omniauth Providers -GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships with a few providers preinstalled (e.g. LDAP, GitHub, Twitter). But sometimes that is not enough and you need to integrate with other authentication solutions. For these cases you can use the Omniauth provider. +>**Note:** +The following information only applies for installations from source. + +GitLab uses [Omniauth](http://www.omniauth.org/) for authentication and already ships +with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that +is not enough and you need to integrate with other authentication solutions. For +these cases you can use the Omniauth provider. ### Steps -These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. +These steps are fairly general and you will need to figure out the exact details +from the Omniauth provider's documentation. - Stop GitLab: @@ -123,8 +159,12 @@ These steps are fairly general and you will need to figure out the exact details ### Examples -If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. +If you have successfully set up a provider that is not shipped with GitLab itself, +please let us know. -You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls by sharing your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). +You can help others by reporting successful configurations and probably share a +few insights or provide warnings for common errors or pitfalls by sharing your +experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). -While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. +While we can't officially support every possible authentication mechanism out there, +we'd like to at least help those with specific needs. diff --git a/doc/integration/redmine_configuration.png b/doc/integration/redmine_configuration.png Binary files differdeleted file mode 100644 index 6b145363229..00000000000 --- a/doc/integration/redmine_configuration.png +++ /dev/null diff --git a/doc/integration/redmine_service_template.png b/doc/integration/redmine_service_template.png Binary files differdeleted file mode 100644 index 1159eb5b964..00000000000 --- a/doc/integration/redmine_service_template.png +++ /dev/null diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 1632e42f701..1c3dc707f6d 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,10 +1,14 @@ # SAML OmniAuth Provider -GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as Microsoft ADFS to authenticate users. +GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows +GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP) such as +Microsoft ADFS to authenticate users. -First configure SAML 2.0 support in GitLab, then register the GitLab application in your SAML IdP: +First configure SAML 2.0 support in GitLab, then register the GitLab application +in your SAML IdP: -1. Make sure GitLab is configured with HTTPS. See [Using HTTPS](../install/installation.md#using-https) for instructions. +1. Make sure GitLab is configured with HTTPS. + See [Using HTTPS](../install/installation.md#using-https) for instructions. 1. On your GitLab server, open the configuration file. @@ -22,7 +26,40 @@ First configure SAML 2.0 support in GitLab, then register the GitLab application sudo -u git -H editor config/gitlab.yml ``` -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. To allow your users to use SAML to sign up without having to manually create + an account first, don't forget to add the following values to your configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] + gitlab_rails['omniauth_block_auto_created_users'] = false + ``` + + For installations from source: + + ```yaml + allow_single_sign_on: ["saml"] + block_auto_created_users: false + ``` + +1. You can also automatically link SAML users with existing GitLab users if their + email addresses match by adding the following setting: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_auto_link_saml_user'] = true + ``` + + For installations from source: + + ```yaml + auto_link_saml_user: true + ``` 1. Add the provider configuration: @@ -31,15 +68,15 @@ First configure SAML 2.0 support in GitLab, then register the GitLab application ```ruby gitlab_rails['omniauth_providers'] = [ { - "name" => "saml", - args: { + name: 'saml', + args: { assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' }, - "label" => "Company Login" # optional label for SAML login button, defaults to "Saml" + label: 'Company Login' # optional label for SAML login button, defaults to "Saml" } ] ``` @@ -47,37 +84,155 @@ First configure SAML 2.0 support in GitLab, then register the GitLab application For installations from source: ```yaml - - { name: 'saml', - args: { - assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', - idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', - idp_sso_target_url: 'https://login.example.com/idp', - issuer: 'https://gitlab.example.com', - name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' - } } + - { + name: 'saml', + args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' + }, + label: 'Company Login' # optional label for SAML login button, defaults to "Saml" + } ``` -1. Change the value for 'assertion_consumer_service_url' to match the HTTPS endpoint of GitLab (append 'users/auth/saml/callback' to the HTTPS URL of your GitLab installation to generate the correct value). +1. Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint + of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab + installation to generate the correct value). -1. Change the values of 'idp_cert_fingerprint', 'idp_sso_target_url', 'name_identifier_format' to match your IdP. Check [the omniauth-saml documentation](https://github.com/PracticallyGreen/omniauth-saml) for details on these options. +1. Change the values of `idp_cert_fingerprint`, `idp_sso_target_url`, + `name_identifier_format` to match your IdP. Check + [the omniauth-saml documentation](https://github.com/omniauth/omniauth-saml) + for details on these options. -1. Change the value of 'issuer' to a unique name, which will identify the application to the IdP. +1. Change the value of `issuer` to a unique name, which will identify the application + to the IdP. 1. Restart GitLab for the changes to take effect. -1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified in 'issuer'. +1. Register the GitLab SP in your SAML 2.0 IdP, using the application name specified + in `issuer`. -To ease configuration, most IdP accept a metadata URL for the application to provide configuration information to the IdP. To build the metadata URL for GitLab, append 'users/auth/saml/metadata' to the HTTPS URL of your GitLab installation, for instance: +To ease configuration, most IdP accept a metadata URL for the application to provide +configuration information to the IdP. To build the metadata URL for GitLab, append +`users/auth/saml/metadata` to the HTTPS URL of your GitLab installation, for instance: ``` https://gitlab.example.com/users/auth/saml/metadata ``` -At a minimum the IdP *must* provide a claim containing the user's email address, using claim name 'email' or 'mail'. The email will be used to automatically generate the GitLab username. GitLab will also use claims with name 'name', 'first_name', 'last_name' (see [the omniauth-saml gem](https://github.com/PracticallyGreen/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) for supported claims). - -On the sign in page there should now be a SAML button below the regular sign in form. Click the icon to begin the authentication process. If everything goes well the user will be returned to GitLab and will be signed in. +At a minimum the IdP *must* provide a claim containing the user's email address, using +claim name `email` or `mail`. The email will be used to automatically generate the GitLab +username. GitLab will also use claims with name `name`, `first_name`, `last_name` +(see [the omniauth-saml gem](https://github.com/omniauth/omniauth-saml/blob/master/lib/omniauth/strategies/saml.rb) +for supported claims). + +On the sign in page there should now be a SAML button below the regular sign in form. +Click the icon to begin the authentication process. If everything goes well the user +will be returned to GitLab and will be signed in. + +## Customization + +### `attribute_statements` + +>**Note:** +This setting is only available on GitLab 8.6 and above. +This setting should only be used to map attributes that are part of the +OmniAuth info hash schema. + +`attribute_statements` is used to map Attribute Names in a SAMLResponse to entries +in the OmniAuth [info hash](https://github.com/intridea/omniauth/wiki/Auth-Hash-Schema#schema-10-and-later). + +For example, if your SAMLResponse contains an Attribute called 'EmailAddress', +specify `{ email: ['EmailAddress'] }` to map the Attribute to the +corresponding key in the info hash. URI-named Attributes are also supported, e.g. +`{ email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }`. + +This setting allows you tell GitLab where to look for certain attributes required +to create an account. Like mentioned above, if your IdP sends the user's email +address as `EmailAddress` instead of `email`, let GitLab know by setting it on +your configuration: + +```yaml +args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', + attribute_statements: { email: ['EmailAddress'] } +} +``` + +### `allowed_clock_drift` + +The clock of the Identity Provider may drift slightly ahead of your system clocks. +To allow for a small amount of clock drift you can use `allowed_clock_drift` within +your settings. Its value must be given in a number (and/or fraction) of seconds. +The value given is added to the current time at which the response is validated. + +```yaml +args: { + assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', + idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', + idp_sso_target_url: 'https://login.example.com/idp', + issuer: 'https://gitlab.example.com', + name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient', + attribute_statements: { email: ['EmailAddress'] }, + allowed_clock_drift: 1 # for one second clock drift +} +``` ## Troubleshooting -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. +### 500 error after login + +If you see a "500 error" in GitLab when you are redirected back from the SAML sign in page, +this likely indicates that GitLab could not get the email address for the SAML user. + +Make sure the IdP provides a claim containing the user's email address, using claim name +`email` or `mail`. + +### Redirect back to login screen with no evident error + +If after signing in into your SAML server you are redirected back to the sign in page and +no error is displayed, check your `production.log` file. It will most likely contain the +message `Can't verify CSRF token authenticity`. This means that there is an error during +the SAML request, but this error never reaches GitLab due to the CSRF check. + +To bypass this you can add `skip_before_action :verify_authenticity_token` to the +`omniauth_callbacks_controller.rb` file. This will allow the error to hit GitLab, +where it can then be seen in the usual logs, or as a flash message in the login +screen. + +### Invalid audience + +This error means that the IdP doesn't recognize GitLab as a valid sender and +receiver of SAML requests. Make sure to add the GitLab callback URL to the approved +audiences of the IdP server. + +### Missing claims + +The IdP server needs to pass certain information in order for GitLab to either +create an account, or match the login information to an existing account. `email` +is the minimum amount of information that needs to be passed. If the IdP server +is not providing this information, all SAML requests will fail. + +Make sure this information is provided. + +### Key validation error, Digest mismatch or Fingerprint mismatch + +These errors all come from a similar place, the SAML certificate. SAML requests +need to be validated using a fingerprint, a certificate or a validator. + +For this you need take the following into account: + +- If no certificate is provided in the settings, a fingerprint or fingerprint + validator needs to be provided and the response from the server must contain + a certificate (`<ds:KeyInfo><ds:X509Data><ds:X509Certificate>`) +- If a certificate is provided in the settings, it is no longer necessary for + the request to contain one. In this case the fingerprint or fingerprint + validators are optional -Make sure 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 that one of the above described scenarios is valid, or the requests will +fail with one of the mentioned errors.
\ No newline at end of file diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 6258e5f1030..a0be3dd4e5c 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -1,8 +1,8 @@ # Shibboleth OmniAuth Provider -This documentation is for enabling shibboleth with gitlab-omnibus package. +This documentation is for enabling shibboleth with omnibus-gitlab package. -In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in gitlab-omnibus package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. +In order to enable Shibboleth support in gitlab we need to use Apache instead of Nginx (It may be possible to use Nginx, however I did not found way to easily configure Nginx that is bundled in omnibus-gitlab package). Apache uses mod_shib2 module for shibboleth authentication and can pass attributes as headers to omniauth-shibboleth provider. To enable the Shibboleth OmniAuth provider you must: diff --git a/doc/integration/slack.md b/doc/integration/slack.md index 84f1d74c058..f6ba80f46d5 100644 --- a/doc/integration/slack.md +++ b/doc/integration/slack.md @@ -2,19 +2,13 @@ ## On Slack -To enable Slack integration you must create an Incoming WebHooks integration on Slack; +To enable Slack integration you must create an Incoming WebHooks integration on Slack: 1. [Sign in to Slack](https://slack.com/signin) -1. Select **Configure Integrations** from the dropdown next to your team name. +1. Visit [Incoming WebHooks](https://my.slack.com/services/new/incoming-webhook/) -1. Select the **All Services** tab - -1. Click **Add** next to Incoming Webhooks - -1. Pick Incoming WebHooks - -1. Choose the channel name you want to send notifications to +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/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md index f97c252fd7c..59803aea080 100644 --- a/doc/legal/individual_contributor_license_agreement.md +++ b/doc/legal/individual_contributor_license_agreement.md @@ -18,7 +18,7 @@ You accept and agree to the following terms and conditions for Your present and 6. You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON- INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. -7. Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [[]named here]". +7. Should You wish to submit work that is not Your original creation, You may submit it to GitLab B.V. separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which you are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [insert_name_here]". 8. You agree to notify GitLab B.V. of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect. diff --git a/doc/markdown/img/logo.png b/doc/markdown/img/logo.png Binary files differnew file mode 100644 index 00000000000..7da5f23ed9b --- /dev/null +++ b/doc/markdown/img/logo.png diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md index bc8e7d155e7..e6eb1cf3819 100644 --- a/doc/markdown/markdown.md +++ b/doc/markdown/markdown.md @@ -29,6 +29,8 @@ ## GitLab Flavored Markdown (GFM) +_GitLab uses the [Redcarpet Ruby library][redcarpet] for Markdown processing._ + For GitLab we developed something we call "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. You can use GFM in @@ -88,6 +90,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 @@ -204,6 +209,7 @@ GFM also recognizes certain cross-project references: | `namespace/project$123` | snippet | | `namespace/project@9ba12248` | specific commit | | `namespace/project@9ba12248...b19a04f5` | commit range comparison | +| `namespace/project~"Some label"` | issues with given label | ## Task Lists @@ -421,24 +427,24 @@ will point the link to `wikis/style` when the link is inside of a wiki markdown Here's our logo (hover to see the title text): Inline-style: -  +  Reference-style: ![alt text1][logo] - [logo]: assets/logo-white.png + [logo]: img/logo.png Here's our logo: Inline-style: - + Reference-style: ![alt text][logo] -[logo]: /assets/logo-white.png +[logo]: img/logo.png ## Blockquotes @@ -585,3 +591,6 @@ 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" +[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet 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/permissions/permissions.md b/doc/permissions/permissions.md index 1be78ac1823..3d375e47c8e 100644 --- a/doc/permissions/permissions.md +++ b/doc/permissions/permissions.md @@ -6,7 +6,7 @@ If a user is both in a project group and in the project itself, the highest perm If a user is a GitLab administrator they receive all permissions. -On public projects the Guest role is not enforced. +On public and internal projects the Guest role is not enforced. All users will be able to create issues, leave comments, and pull or download the project code. To add or import a user, you can follow the [project users and members @@ -18,11 +18,15 @@ documentation](../workflow/add-user/add-user.md). |---------------------------------------|---------|------------|-------------|----------|--------| | Create new issue | ✓ | ✓ | ✓ | ✓ | ✓ | | Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| See a list of builds | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| See a build log | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | +| Download and browse build artifacts | ✓ [^1] | ✓ | ✓ | ✓ | ✓ | | Pull project code | | ✓ | ✓ | ✓ | ✓ | | Download project | | ✓ | ✓ | ✓ | ✓ | | Create code snippets | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage labels | | ✓ | ✓ | ✓ | ✓ | +| See a commit status | | ✓ | ✓ | ✓ | ✓ | | Manage merge requests | | | ✓ | ✓ | ✓ | | Create new merge request | | | ✓ | ✓ | ✓ | | Create new branches | | | ✓ | ✓ | ✓ | @@ -31,6 +35,8 @@ documentation](../workflow/add-user/add-user.md). | Remove non-protected branches | | | ✓ | ✓ | ✓ | | Add tags | | | ✓ | ✓ | ✓ | | Write a wiki | | | ✓ | ✓ | ✓ | +| Cancel and retry builds | | | ✓ | ✓ | ✓ | +| Create or update commit status | | | ✓ | ✓ | ✓ | | Create new milestones | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | @@ -40,12 +46,17 @@ documentation](../workflow/add-user/add-user.md). | Edit project | | | | ✓ | ✓ | | Add deploy keys to project | | | | ✓ | ✓ | | Configure project hooks | | | | ✓ | ✓ | +| Manage runners | | | | ✓ | ✓ | +| Manage build triggers | | | | ✓ | ✓ | +| Manage variables | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Remove project | | | | | ✓ | | Force push to protected branches | | | | | | | Remove protected branches | | | | | | +[^1]: If **Allow guest to access builds** is enabled in CI settings + ## Group In order for a group to appear as public and be browsable, it must contain at @@ -60,3 +71,24 @@ Any user can remove themselves from a group, unless they are the last Owner of t | Create project in group | | | | ✓ | ✓ | | Manage group members | | | | | ✓ | | Remove group | | | | | ✓ | + +## External Users + +In cases where it is desired that a user has access only to some internal or +private projects, there is the option of creating **External Users**. This +feature may be useful when for example a contractor is working on a given +project and should only have access to that project. + +External users can only access projects to which they are explicitly granted +access, thus hiding all other internal or private ones from them. Access can be +granted by adding the user as member to the project or group. + +They will, like usual users, receive a role in the project or group with all +the abilities that are mentioned in the table above. They cannot however create +groups or projects, and they have the same access as logged out users in all +other cases. + +An administrator can flag a user as external [through the API](../api/users.md) +or by checking the checkbox on the admin panel. As an administrator, navigate +to **Admin > Users** to create a new user or edit an existing one. There, you +will find the option to flag the user as external. diff --git a/doc/profile/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/builds_emails.md b/doc/project_services/builds_emails.md new file mode 100644 index 00000000000..af0b1a287c7 --- /dev/null +++ b/doc/project_services/builds_emails.md @@ -0,0 +1,16 @@ +## Enabling build emails + +To receive e-mail notifications about the result status of your builds, visit +your project's **Settings > Services > Builds emails** and activate the service. + +In the _Recipients_ area, provide a list of e-mails separated by comma. + +Check the _Add pusher_ checkbox if you want the committer to also receive +e-mail notifications about each build's status. + +If you enable the _Notify only broken builds_ option, e-mail notifications will +be sent only for failed builds. + +--- + + diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png Binary files differnew file mode 100644 index 00000000000..e604dd73ffa --- /dev/null +++ b/doc/project_services/img/builds_emails_service.png 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/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png Binary files differindex 15739a22dc7..15739a22dc7 100644 --- a/doc/integration/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/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png Binary files differnew file mode 100644 index 00000000000..1e78daf105f --- /dev/null +++ b/doc/project_services/img/jira_merge_request_close.png diff --git a/doc/integration/jira_project_name.png b/doc/project_services/img/jira_project_name.png Binary files differindex 5986fdb63fb..5986fdb63fb 100644 --- a/doc/integration/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/jira_service.png b/doc/project_services/img/jira_service.png Binary files differindex 1f6628c4371..1f6628c4371 100644 --- a/doc/integration/jira_service.png +++ b/doc/project_services/img/jira_service.png diff --git a/doc/integration/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png Binary files differindex 67dfc6144c4..67dfc6144c4 100644 --- a/doc/integration/jira_service_close_issue.png +++ b/doc/project_services/img/jira_service_close_issue.png diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png Binary files differnew file mode 100644 index 00000000000..2b37eda3520 --- /dev/null +++ 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/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png Binary files differindex 8635a32eb68..8635a32eb68 100644 --- a/doc/integration/jira_workflow_screenshot.png +++ b/doc/project_services/img/jira_workflow_screenshot.png diff --git a/doc/project_services/img/redmine_configuration.png b/doc/project_services/img/redmine_configuration.png Binary files differnew file mode 100644 index 00000000000..d14e526ad33 --- /dev/null +++ b/doc/project_services/img/redmine_configuration.png diff --git a/doc/project_services/img/services_templates_redmine_example.png b/doc/project_services/img/services_templates_redmine_example.png Binary files differnew file mode 100644 index 00000000000..384d057fc8e --- /dev/null +++ b/doc/project_services/img/services_templates_redmine_example.png diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md new file mode 100644 index 00000000000..27170c1eb19 --- /dev/null +++ b/doc/project_services/jira.md @@ -0,0 +1,234 @@ +# GitLab JIRA integration + +_**Note:** +Full JIRA integration was previously exclusive to GitLab Enterprise Edition. +With [GitLab 8.3 forward][8_3_post], this feature in now [backported][jira-ce] +to GitLab Community Edition as well._ + +--- + +GitLab can be configured to interact with [JIRA Core] either using an +on-premises instance or the SaaS solution that Atlassian offers. Configuration +happens via username and password on a per-project basis. Connecting to a JIRA +server via CAS is not possible. + +Each project can be configured to connect to a different JIRA instance or, in +case you have a single JIRA instance, you can pre-fill the JIRA service +settings page in GitLab with a default template. To configure the JIRA template, +see the [Services Templates documentation][services-templates]. + +Once the GitLab project is connected to JIRA, you can reference and close the +issues in JIRA directly from GitLab's merge requests. + +## Configuration + +The configuration consists of two parts: + +- [JIRA configuration](#configuring-jira) +- [GitLab configuration](#configuring-gitlab) + +### Configuring JIRA + +First things first, we need to create a user in JIRA which will have access to +all projects that need to integrate with GitLab. + +We have split this stage in steps so it is easier to follow. + +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** to create a new user. + +  + + --- + +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" +[jira-ce]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2146 "MR - Backport JIRA service" +[8_3_post]: https://about.gitlab.com/2015/12/22/gitlab-8-3-released/ "GitLab 8.3 release post" + +## Troubleshooting + +### GitLab is unable to comment on a ticket + +Make sure that the user you set up for GitLab to communicate with JIRA has the +correct access permission to post comments on a ticket and to also transition the +ticket, if you'd like GitLab to also take care of closing them. + +### GitLab is unable to close a ticket + +Make sure the the `Transition ID` you set within the JIRA settings matches the +one your project needs to close a ticket. diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 03937d20728..3fea2cff0b9 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -1,20 +1,37 @@ # Project Services - -__Project integrations with external services for continuous integration and more.__ + +Project services allow you to integrate GitLab with other applications. Below +is list of the currently supported ones. Click on the service links to see +further configuration instructions and details. Contributions are welcome. ## Services -- Assembla -- [Atlassian Bamboo CI](bamboo.md) An Atlassian product for continuous integration. -- Build box -- Campfire -- Emails on push -- Flowdock -- Gemnasium -- GitLab CI -- [HipChat](hipchat.md) An Atlassian product for private group chat and instant messaging. -- [Irker](irker.md) An IRC gateway to receive messages on repository updates. -- Pivotal Tracker -- Pushover -- Slack -- TeamCity +| Service | Description | +| ------- | ----------- | +| Asana | Asana - Teamwork without email | +| Assembla | Project Management Software (Source Commits Endpoint) | +| [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | +| Buildkite | Continuous integration and deployments | +| [Builds emails](builds_emails.md) | Email the builds status to a list of recipients | +| Campfire | Simple web-based real-time group chat | +| Custom Issue Tracker | Custom issue tracker | +| Drone CI | Continuous Integration platform built on Docker, written in Go | +| Emails on push | Email the commits and diff of each push to a list of recipients | +| External Wiki | Replaces the link to the internal wiki with a link to an external wiki | +| Flowdock | Flowdock is a collaboration web app for technical teams | +| Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | +| [HipChat](hipchat.md) | Private group chat and IM | +| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | +| [JIRA](jira.md) | JIRA issue tracker | +| JetBrains TeamCity CI | A continuous integration and build server | +| PivotalTracker | Project Management Software (Source Commits Endpoint) | +| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | +| [Redmine](redmine.md) | Redmine issue tracker | +| Slack | A team communication tool for the 21st century | + +## Services Templates + +Services templates is a way to set some predefined values in the Service of +your liking which will then be pre-filled on each project's Service. + +Read more about [Services Templates in this document](services_templates.md). diff --git a/doc/project_services/redmine.md b/doc/project_services/redmine.md new file mode 100644 index 00000000000..b9830ea7c38 --- /dev/null +++ b/doc/project_services/redmine.md @@ -0,0 +1,21 @@ +# Redmine Service + +Go to your project's **Settings > Services > Redmine** and fill in the required +details as described in the table below. + +| Field | Description | +| ----- | ----------- | +| `description` | A name for the issue tracker (to differentiate between instances, for example) | +| `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | +| `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | +| `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project | + +Once you have configured and enabled Redmine: + +- the **Issues** link on the GitLab project pages takes you to the appropriate + Redmine issue index +- clicking **New issue** on the project dashboard creates a new Redmine issue + +As an example, below is a configuration for a project named gitlab-ci. + + diff --git a/doc/project_services/services_templates.md b/doc/project_services/services_templates.md new file mode 100644 index 00000000000..be6d13b6d2b --- /dev/null +++ b/doc/project_services/services_templates.md @@ -0,0 +1,25 @@ +# Services Templates + +A GitLab administrator can add a service template that sets a default for each +project. This makes it much easier to configure individual projects. + +After the template is created, the template details will be pre-filled on a +project's Service page. + +## Enable a Service template + +In GitLab's Admin area, navigate to **Service Templates** and choose the +service template you wish to create. + +For example, in the image below you can see Redmine. + + + +--- + +**NOTE:** For each project, you will still need to configure the issue tracking +URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used +by your external issue tracker. Prior to GitLab v7.8, this ID was configured in +the project settings, and GitLab would automatically update the URL configured +in `gitlab.yml`. This behavior is now deprecated and all issue tracker URLs +must be configured directly within the project's **Services** settings. diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index cc8a22cd003..6be954ad68b 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -6,6 +6,6 @@ - [Features](features.md) - [Maintenance](maintenance.md) and self-checks - [User management](user_management.md) -- [Web hooks](web_hooks.md) +- [Webhooks](web_hooks.md) - [Import](import.md) of git repositories in bulk - [Rebuild authorized_keys file](http://doc.gitlab.com/ce/raketasks/maintenance.html#rebuild-authorized_keys-file) task for administrators diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index cdd6652b7b0..f6d1234ac4a 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -18,8 +18,6 @@ for two-factor authentication. If you restore a GitLab backup without restoring the database encryption key, users who have two-factor authentication enabled will lose access to your GitLab server. -If you are interested in GitLab CI backup please follow to the [CI backup documentation](https://gitlab.com/gitlab-org/gitlab-ci/blob/master/doc/raketasks/backup_restore.md)* - ``` # use this command if you've installed GitLab with the Omnibus package sudo gitlab-rake gitlab:backup:create diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md index 5a8b94af9b4..2ebf7c48f4e 100644 --- a/doc/raketasks/web_hooks.md +++ b/doc/raketasks/web_hooks.md @@ -1,41 +1,41 @@ -# Web hooks +# Webhooks -## Add a web hook for **ALL** projects: +## Add a webhook for **ALL** projects: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" # source installations bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" RAILS_ENV=production -## Add a web hook for projects in a given **NAMESPACE**: +## Add a webhook for projects in a given **NAMESPACE**: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme # source installations bundle exec rake gitlab:web_hook:add URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production -## Remove a web hook from **ALL** projects using: +## Remove a webhook from **ALL** projects using: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" # source installations bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" RAILS_ENV=production -## Remove a web hook from projects in a given **NAMESPACE**: +## Remove a webhook from projects in a given **NAMESPACE**: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme # source installations bundle exec rake gitlab:web_hook:rm URL="http://example.com/hook" NAMESPACE=acme RAILS_ENV=production -## List **ALL** web hooks: +## List **ALL** webhooks: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:list # source installations bundle exec rake gitlab:web_hook:list RAILS_ENV=production -## List the web hooks from projects in a given **NAMESPACE**: +## List the webhooks from projects in a given **NAMESPACE**: # omnibus-gitlab sudo gitlab-rake gitlab:web_hook:list NAMESPACE=/ diff --git a/doc/release/patch.md b/doc/release/patch.md index 3022e375aca..1c921439156 100644 --- a/doc/release/patch.md +++ b/doc/release/patch.md @@ -24,7 +24,7 @@ Use the following template: - Picked into respective `stable` branches: - [ ] Merge `x-y-stable` into `x-y-stable-ee` - [ ] release-tools: `x.y.z` -- gitlab-omnibus +- omnibus-gitlab - [ ] `x.y.z+ee.0` - [ ] `x.y.z+ce.0` - [ ] Deploy diff --git a/doc/release/security.md b/doc/release/security.md index b1a62b333e6..118c016ba4f 100644 --- a/doc/release/security.md +++ b/doc/release/security.md @@ -15,7 +15,7 @@ Please report suspected security vulnerabilities in private to <support@gitlab.c 1. Verify that the issue can be reproduced 1. Acknowledge the issue to the researcher that disclosed it 1. Inform the release manager that there needs to be a security release -1. Do the steps from [patch release document](doc/release/patch.md), starting with "Create an issue on private GitLab development server" +1. Do the steps from [patch release document](../release/patch.md), starting with "Create an issue on private GitLab development server" 1. The MR with the security fix should get a 'security' label and be assigned to the release manager 1. Build the package for GitLab.com and do a deploy 1. Build the package for ci.gitLab.com and do a deploy diff --git a/doc/security/README.md b/doc/security/README.md index f34c792d005..4cd0fdd4094 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -2,9 +2,9 @@ - [Password length limits](password_length_limits.md) - [Rack attack](rack_attack.md) -- [Web Hooks and insecure internal web services](webhooks.md) +- [Webhooks and insecure internal web services](webhooks.md) - [Information exclusivity](information_exclusivity.md) - [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..c8499380c18 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -6,7 +6,7 @@ password to login, they'll be prompted for a code generated by an application on their phone. You can read more about it here: -[Two-factor Authentication (2FA)](doc/profile/two_factor_authentication.md) +[Two-factor Authentication (2FA)](../profile/two_factor_authentication.md) ## Enabling 2FA @@ -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/security/webhooks.md b/doc/security/webhooks.md index 1e9d33e87c3..bb46aebf4b5 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,13 +1,13 @@ -# Web Hooks and insecure internal web services +# Webhooks and insecure internal web services -If you have non-GitLab web services running on your GitLab server or within its local network, these may be vulnerable to exploitation via Web Hooks. +If you have non-GitLab web services running on your GitLab server or within its local network, these may be vulnerable to exploitation via Webhooks. -With [Web Hooks](../web_hooks/web_hooks.md), you and your project masters and owners can set up URLs to be triggered when specific things happen to projects. Normally, these requests are sent to external web services specifically set up for this purpose, that process the request and its attached data in some appropriate way. +With [Webhooks](../web_hooks/web_hooks.md), you and your project masters and owners can set up URLs to be triggered when specific things happen to projects. Normally, these requests are sent to external web services specifically set up for this purpose, that process the request and its attached data in some appropriate way. -Things get hairy, however, when a Web Hook is set up with a URL that doesn't point to an external, but to an internal service, that may do something completely unintended when the web hook is triggered and the POST request is sent. +Things get hairy, however, when a Webhook is set up with a URL that doesn't point to an external, but to an internal service, that may do something completely unintended when the webhook is triggered and the POST request is sent. -Because Web Hook requests are made by the GitLab server itself, these have complete access to everything running on the server (http://localhost:123) or within the server's local network (http://192.168.1.12:345), even if these services are otherwise protected and inaccessible from the outside world. +Because Webhook requests are made by the GitLab server itself, these have complete access to everything running on the server (http://localhost:123) or within the server's local network (http://192.168.1.12:345), even if these services are otherwise protected and inaccessible from the outside world. -If a web service does not require authentication, Web Hooks can be used to trigger destructive commands by getting the GitLab server to make POST requests to endpoints like "http://localhost:123/some-resource/delete". +If a web service does not require authentication, Webhooks can be used to trigger destructive commands by getting the GitLab server to make POST requests to endpoints like "http://localhost:123/some-resource/delete". To prevent this type of exploitation from happening, make sure that you are aware of every web service GitLab could potentially have access to, and that all of these are set up to require authentication for every potentially destructive command. Enabling authentication but leaving a default password is not enough.
\ No newline at end of file diff --git a/doc/ssh/README.md b/doc/ssh/README.md index fe5b45dd432..a1198e5878f 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -5,11 +5,17 @@ An SSH key allows you to establish a secure connection between your computer and GitLab. Before generating an SSH key in your shell, check if your system already has one by running the following command: + +**Windows Command Line:** +```bash +type %userprofile%\.ssh\id_rsa.pub +``` +**GNU/Linux/Mac/PowerShell:** ```bash cat ~/.ssh/id_rsa.pub ``` -If you see a long string starting with `ssh-rsa` or `ssh-dsa`, you can skip the `ssh-keygen` step. +If you see a long string starting with `ssh-rsa`, you can skip the `ssh-keygen` step. Note: It is a best practice to use a password for an SSH key, but it is not required and you can skip creating a password by pressing enter. Note that @@ -20,24 +26,36 @@ To generate a new SSH key, use the following command: ssh-keygen -t rsa -C "$your_email" ``` This command will prompt you for a location and filename to store the key -pair and for a password. When prompted for the location and filename, you -can press enter to use the default. +pair and for a password. When prompted for the location and filename, just +press enter to use the default. If you use a different name, the key will not +be used automatically. Use the command below to show your public key: + +**Windows Command Line:** +```bash +type %userprofile%\.ssh\id_rsa.pub +``` +**GNU/Linux/Mac/PowerShell:** ```bash cat ~/.ssh/id_rsa.pub ``` Copy-paste the key to the 'My SSH Keys' section under the 'SSH' tab in your -user profile. Please copy the complete key starting with `ssh-` and ending +user profile. Please copy the complete key starting with `ssh-rsa` and ending with your username and host. -To copy your public key to the clipboard, use code below. Depending on your +To copy your public key to the clipboard, use the code below. Depending on your OS you'll need to use a different command: -**Windows:** +**Windows Command Line:** +```bash +type %userprofile%\.ssh\id_rsa.pub | clip +``` + +**Windows PowerShell:** ```bash -clip < ~/.ssh/id_rsa.pub +cat ~/.ssh/id_rsa.pub | clip ``` **Mac:** diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 5cb05b13b3e..612376e3a49 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -1,6 +1,6 @@ # System hooks -Your GitLab instance can perform HTTP POST requests on the following events: `project_create`, `project_destroy`, `user_add_to_team`, `user_remove_from_team`, `user_create`, `user_destroy`, `key_create`, `key_destroy`, `group_create`, `group_destroy`, `user_add_to_group` and `user_remove_from_group`. +Your GitLab instance can perform HTTP POST requests on the following events: `project_create`, `project_destroy`, `project_rename`, `project_transfer`, `user_add_to_team`, `user_remove_from_team`, `user_create`, `user_destroy`, `key_create`, `key_destroy`, `group_create`, `group_destroy`, `user_add_to_group` and `user_remove_from_group`. System hooks can be used, e.g. for logging or changing information in a LDAP server. @@ -17,6 +17,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:54Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "project_create", "name": "StoreCloud", "owner_email": "johnsmith@gmail.com", @@ -33,6 +34,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:58Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "project_destroy", "name": "Underscore", "owner_email": "johnsmith@gmail.com", @@ -44,11 +46,48 @@ X-Gitlab-Event: System Hook } ``` +**Project renamed:** + +```json +{ + "created_at": "2012-07-21T07:30:58Z", + "updated_at": "2012-07-21T07:38:22Z", + "event_name": "project_rename", + "name": "Underscore", + "path": "underscore", + "path_with_namespace": "jsmith/underscore", + "project_id": 73, + "owner_name": "John Smith", + "owner_email": "johnsmith@gmail.com", + "project_visibility": "internal", + "old_path_with_namespace": "jsmith/overscore", +} +``` + +**Project transferred:** + +```json +{ + "created_at": "2012-07-21T07:30:58Z", + "updated_at": "2012-07-21T07:38:22Z", + "event_name": "project_transfer", + "name": "Underscore", + "path": "underscore", + "path_with_namespace": "scores/underscore", + "project_id": 73, + "owner_name": "John Smith", + "owner_email": "johnsmith@gmail.com", + "project_visibility": "internal", + "old_path_with_namespace": "jsmith/overscore", +} +``` + **New Team Member:** ```json { "created_at": "2012-07-21T07:30:56Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_add_to_team", "project_access": "Master", "project_id": 74, @@ -57,6 +96,7 @@ X-Gitlab-Event: System Hook "project_path_with_namespace": "jsmith/storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", + "user_username": "johnsmith", "user_id": 41, "project_visibility": "private", } @@ -67,6 +107,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:56Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_remove_from_team", "project_access": "Master", "project_id": 74, @@ -75,6 +116,7 @@ X-Gitlab-Event: System Hook "project_path_with_namespace": "jsmith/storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", + "user_username": "johnsmith", "user_id": 41, "project_visibility": "private", } @@ -85,9 +127,11 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:44:07Z", + "updated_at": "2012-07-21T07:38:22Z", "email": "js@gitlabhq.com", "event_name": "user_create", "name": "John Smith", + "username": "js", "user_id": 41 } ``` @@ -97,9 +141,11 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:44:07Z", + "updated_at": "2012-07-21T07:38:22Z", "email": "js@gitlabhq.com", "event_name": "user_destroy", "name": "John Smith", + "username": "js", "user_id": 41 } ``` @@ -110,6 +156,7 @@ X-Gitlab-Event: System Hook { "event_name": "key_create", "created_at": "2014-08-18 18:45:16 UTC", + "updated_at": "2012-07-21T07:38:22Z", "username": "root", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost", "id": 4 @@ -122,6 +169,7 @@ X-Gitlab-Event: System Hook { "event_name": "key_destroy", "created_at": "2014-08-18 18:45:16 UTC", + "updated_at": "2012-07-21T07:38:22Z", "username": "root", "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost", "id": 4 @@ -133,6 +181,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:54Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_create", "name": "StoreCloud", "owner_email": "johnsmith@gmail.com", @@ -147,6 +196,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:54Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_destroy", "name": "StoreCloud", "owner_email": "johnsmith@gmail.com", @@ -161,6 +211,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:56Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_add_to_group", "group_access": "Master", "group_id": 78, @@ -168,6 +219,7 @@ X-Gitlab-Event: System Hook "group_path": "storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", + "user_username": "johnsmith", "user_id": 41 } ``` @@ -176,6 +228,7 @@ X-Gitlab-Event: System Hook ```json { "created_at": "2012-07-21T07:30:56Z", + "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_remove_from_group", "group_access": "Master", "group_id": 78, @@ -183,6 +236,7 @@ X-Gitlab-Event: System Hook "group_path": "storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", + "user_username": "johnsmith", "user_id": 41 } ``` diff --git a/doc/update/6.x-or-7.x-to-7.14.md b/doc/update/6.x-or-7.x-to-7.14.md index 4516a102084..c45fc9340ea 100644 --- a/doc/update/6.x-or-7.x-to-7.14.md +++ b/doc/update/6.x-or-7.x-to-7.14.md @@ -14,6 +14,12 @@ possible to edit the label text and color. The characters `?`, `&` and `,` are no longer allowed however so those will be removed from your tags during the database migrations for GitLab 7.2. +## Stash changes + +If you [deleted the vendors folder during your original installation](https://github.com/gitlabhq/gitlabhq/issues/4883#issuecomment-31108431), [you will get an error](https://gitlab.com/gitlab-org/gitlab-ce/issues/1494) when you attempt to rebuild the assets in step 7. To avoid this, stash the changes in your GitLab working copy before starting: + + git stash + ## 0. Stop server sudo service gitlab stop diff --git a/doc/update/8.2-to-8.3.md b/doc/update/8.2-to-8.3.md index e028975d4ee..9f5c6c4dc84 100644 --- a/doc/update/8.2-to-8.3.md +++ b/doc/update/8.2-to-8.3.md @@ -87,7 +87,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.1 +sudo -u git -H git checkout 0.5.4 sudo -u git -H make ``` diff --git a/doc/update/8.3-to-8.4.md b/doc/update/8.3-to-8.4.md new file mode 100644 index 00000000000..269deec7a9c --- /dev/null +++ b/doc/update/8.3-to-8.4.md @@ -0,0 +1,124 @@ +# From 8.3 to 8.4 + +### 1. Stop server + + sudo service gitlab stop + +### 2. Backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Get latest code + +```bash +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +sudo -u git -H git checkout 8-4-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +sudo -u git -H git checkout 8-4-stable-ee +``` + +### 4. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell +sudo -u git -H git fetch --all +sudo -u git -H git checkout v2.6.10 +``` + +### 5. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires [Go 1.5](https://golang.org/dl) +which should already be on your system from GitLab 8.1. + +```bash +cd /home/git/gitlab-workhorse +sudo -u git -H git fetch --all +sudo -u git -H git checkout 0.6.2 +sudo -u git -H make +``` + +### 6. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache +sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production + +``` + +### 7. Update configuration files + +#### New configuration options for `gitlab.yml` + +There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +git diff origin/8-3-stable:config/gitlab.yml.example origin/8-4-stable:config/gitlab.yml.example +``` + +#### Init script + +We updated the init script for GitLab in order to set a specific PATH for gitlab-workhorse. + +``` +cd /home/git/gitlab +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +### 8. Start application + + sudo service gitlab start + sudo service nginx restart + +### 9. Check application status + +Check if GitLab and its environment are configured correctly: + + sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production + +To make sure you didn't miss anything run a more thorough check: + + sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (8.3) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 8.2 to 8.3](8.2-to-8.3.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. diff --git a/doc/update/8.4-to-8.5.md b/doc/update/8.4-to-8.5.md new file mode 100644 index 00000000000..0a9cb5683e7 --- /dev/null +++ b/doc/update/8.4-to-8.5.md @@ -0,0 +1,145 @@ +# From 8.4 to 8.5 + +### 1. Stop server + + sudo service gitlab stop + +### 2. Backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Get latest code + +```bash +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +sudo -u git -H git checkout 8-5-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +sudo -u git -H git checkout 8-5-stable-ee +``` + +### 4. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell +sudo -u git -H git fetch --all +sudo -u git -H git checkout v2.6.10 +``` + +### 5. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires +[Go 1.5](https://golang.org/dl) which should already be on your system from +GitLab 8.1. + +```bash +cd /home/git/gitlab-workhorse +sudo -u git -H git fetch --all +sudo -u git -H git checkout 0.6.4 +sudo -u git -H make +``` + +### 6. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache +sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production + +``` + +### 7. Update configuration files + +#### New configuration options for `gitlab.yml` + +There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +git diff origin/8-4-stable:config/gitlab.yml.example origin/8-5-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +# For HTTPS configurations +git diff origin/8-4-stable:lib/support/nginx/gitlab-ssl origin/8-5-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/8-4-stable:lib/support/nginx/gitlab origin/8-5-stable:lib/support/nginx/gitlab +``` + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-5-stable/lib/support/init.d/gitlab.default.example#L37 + +#### Init script + +Ensure you're still up-to-date with the latest init script changes: + + sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab + +### 8. Start application + + sudo service gitlab start + sudo service nginx restart + +### 9. Check application status + +Check if GitLab and its environment are configured correctly: + + sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production + +To make sure you didn't miss anything run a more thorough check: + + sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (8.4) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 8.3 to 8.4](8.3-to-8.4.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. diff --git a/doc/update/8.5-to-8.6.md b/doc/update/8.5-to-8.6.md new file mode 100644 index 00000000000..024f6e8a433 --- /dev/null +++ b/doc/update/8.5-to-8.6.md @@ -0,0 +1,164 @@ +# From 8.5 to 8.6 + +### 1. Stop server + + sudo service gitlab stop + +### 2. Backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Get latest code + +```bash +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +sudo -u git -H git checkout 8-6-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +sudo -u git -H git checkout 8-6-stable-ee +``` + +### 4. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell +sudo -u git -H git fetch --all +sudo -u git -H git checkout v2.6.11 +``` + +### 5. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires +[Go 1.5](https://golang.org/dl) which should already be on your system from +GitLab 8.1. + +```bash +cd /home/git/gitlab-workhorse +sudo -u git -H git fetch --all +sudo -u git -H git checkout 0.6.5 +sudo -u git -H make +``` + +### 6. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache +sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production + +``` + +### 7. Update configuration files + +#### New configuration options for `gitlab.yml` + +There are new configuration options available for [`gitlab.yml`](config/gitlab.yml.example). View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +git diff origin/8-5-stable:config/gitlab.yml.example origin/8-6-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +# For HTTPS configurations +git diff origin/8-5-stable:lib/support/nginx/gitlab-ssl origin/8-6-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/8-5-stable:lib/support/nginx/gitlab origin/8-6-stable:lib/support/nginx/gitlab +``` + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-6-stable/lib/support/init.d/gitlab.default.example#L37 + +#### Init script + +Ensure you're still up-to-date with the latest init script changes: + + sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab + +### 8. Updates for PostgreSQL Users + +Starting with 8.6 users using GitLab in combination with PostgreSQL are required +to have the `pg_trgm` extension enabled for all GitLab databases. If you're +using GitLab's Omnibus packages there's nothing you'll need to do manually as +this extension is enabled automatically. Users who install GitLab without using +Omnibus (e.g. by building from source) have to enable this extension manually. +To enable this extension run the following SQL command as a PostgreSQL super +user for _every_ GitLab database: + +```sql +CREATE EXTENSION IF NOT EXISTS pg_trgm; +``` + +Certain operating systems might require the installation of extra packages for +this extension to be available. For example, users using Ubuntu will have to +install the `postgresql-contrib` package in order for this extension to be +available. + +### 9. Start application + + sudo service gitlab start + sudo service nginx restart + +### 10. Check application status + +Check if GitLab and its environment are configured correctly: + + sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production + +To make sure you didn't miss anything run a more thorough check: + + sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (8.5) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 8.4 to 8.5](8.4-to-8.5.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. diff --git a/doc/update/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/update/patch_versions.md b/doc/update/patch_versions.md index c19ee49f9e0..f446ed0a35b 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -48,6 +48,7 @@ sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -b v`ca cd /home/git/gitlab-workhorse sudo -u git -H git fetch sudo -u git -H git checkout `cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` -b `cat /home/git/gitlab/GITLAB_WORKHORSE_VERSION` +sudo -u git -H make ``` ### 5. Install libs, migrations, etc. @@ -61,7 +62,13 @@ sudo -u git -H bundle install --without development test mysql --deployment # MySQL sudo -u git -H bundle install --without development test postgres --deployment +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production ``` diff --git a/doc/update/upgrader.md b/doc/update/upgrader.md index fd0327686b1..5fa39ef1b0a 100644 --- a/doc/update/upgrader.md +++ b/doc/update/upgrader.md @@ -4,7 +4,7 @@ Although deprecated, if someone wants to make this script into a gem or otherwise improve it merge requests are welcome. -*Make sure you view this [upgrade guide from the 'master' branch](../../../master/doc/update/upgrader.md) for the most up to date instructions.* +*Make sure you view this [upgrade guide from the 'master' branch](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/upgrader.md) for the most up to date instructions.* GitLab Upgrader - a ruby script that allows you easily upgrade GitLab to latest minor version. diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md index 6420d65cf1b..afdf1a682e2 100644 --- a/doc/web_hooks/web_hooks.md +++ b/doc/web_hooks/web_hooks.md @@ -1,18 +1,25 @@ -# Web hooks +# Webhooks -Project web hooks allow you to trigger an URL if new code is pushed or a new issue is created. +_**Note:** +Starting from GitLab 8.5:_ -You can configure web hooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the web hook URL. +- _the `repository` key is deprecated in favor of the `project` key_ +- _the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key_ +- _the `project.http_url` key is deprecated in favor of the `project.git_http_url` key_ -Web hooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. +Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created. + +You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL. + +Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server. ## SSL Verification -By default, the SSL certificate of the webhook endpoint is verified based on -an internal list of Certificate Authorities, +By default, the SSL certificate of the webhook endpoint is verified based on +an internal list of Certificate Authorities, which means the certificate cannot be self-signed. -You can turn this off in the web hook settings in your GitLab projects. +You can turn this off in the webhook settings in your GitLab projects.  @@ -37,8 +44,25 @@ X-Gitlab-Event: Push Hook "user_id": 4, "user_name": "John Smith", "user_email": "john@example.com", + "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", "project_id": 15, - "repository": { + "project":{ + "name":"Diaspora", + "description":"", + "web_url":"http://example.com/mike/diaspora", + "avatar_url":null, + "git_ssh_url":"git@example.com:mike/diaspora.git", + "git_http_url":"http://example.com/mike/diaspora.git", + "namespace":"Mike", + "visibility_level":0, + "path_with_namespace":"mike/diaspora", + "default_branch":"master", + "homepage":"http://example.com/mike/diaspora", + "url":"git@example.com:mike/diasporadiaspora.git", + "ssh_url":"git@example.com:mike/diaspora.git", + "http_url":"http://example.com/mike/diaspora.git" + }, + "repository":{ "name": "Diaspora", "url": "git@example.com:mike/diasporadiaspora.git", "description": "", @@ -56,7 +80,7 @@ X-Gitlab-Event: Push Hook "author": { "name": "Jordi Mallach", "email": "jordi@softcatala.org" - } + }, "added": ["CHANGELOG"], "modified": ["app/controller/application.rb"], "removed": [] @@ -76,7 +100,6 @@ X-Gitlab-Event: Push Hook } ], "total_commits_count": 4 - } ``` @@ -101,8 +124,25 @@ X-Gitlab-Event: Tag Push Hook "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", "user_id": 1, "user_name": "John Smith", + "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", "project_id": 1, - "repository": { + "project":{ + "name":"Example", + "description":"", + "web_url":"http://example.com/jsmith/example", + "avatar_url":null, + "git_ssh_url":"git@example.com:jsmith/example.git", + "git_http_url":"http://example.com/jsmith/example.git", + "namespace":"Jsmith", + "visibility_level":0, + "path_with_namespace":"jsmith/example", + "default_branch":"master", + "homepage":"http://example.com/jsmith/example", + "url":"git@example.com:jsmith/example.git", + "ssh_url":"git@example.com:jsmith/example.git", + "http_url":"http://example.com/jsmith/example.git" + }, + "repository":{ "name": "jsmith", "url": "ssh://git@example.com/jsmith/example.git", "description": "", @@ -136,7 +176,23 @@ X-Gitlab-Event: Issue Hook "username": "root", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" }, - "repository": { + "project":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "repository":{ "name": "Gitlab Test", "url": "http://example.com/gitlabhq/gitlab-test.git", "description": "Aut reprehenderit ut est.", @@ -158,6 +214,11 @@ X-Gitlab-Event: Issue Hook "iid": 23, "url": "http://example.com/diaspora/issues/23", "action": "open" + }, + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" } } ``` @@ -193,9 +254,25 @@ X-Gitlab-Event: Note Hook "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" }, "project_id": 5, - "repository": { + "project":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlabhq/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "git_http_url":"http://example.com/gitlabhq/gitlab-test.git", + "namespace":"GitlabHQ", + "visibility_level":20, + "path_with_namespace":"gitlabhq/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlabhq/gitlab-test", + "url":"http://example.com/gitlabhq/gitlab-test.git", + "ssh_url":"git@example.com:gitlabhq/gitlab-test.git", + "http_url":"http://example.com/gitlabhq/gitlab-test.git" + }, + "repository":{ "name": "Gitlab Test", - "url": "http://localhost/gitlab-org/gitlab-test.git", + "url": "http://example.com/gitlab-org/gitlab-test.git", "description": "Aut reprehenderit ut est.", "homepage": "http://example.com/gitlab-org/gitlab-test" }, @@ -256,9 +333,25 @@ X-Gitlab-Event: Note Hook "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" }, "project_id": 5, - "repository": { + "project":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ "name": "Gitlab Test", - "url": "http://example.com/gitlab-org/gitlab-test.git", + "url": "http://localhost/gitlab-org/gitlab-test.git", "description": "Aut reprehenderit ut est.", "homepage": "http://example.com/gitlab-org/gitlab-test" }, @@ -296,21 +389,37 @@ X-Gitlab-Event: Note Hook "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.", "position": 0, "locked_at": null, - "source": { - "name": "Gitlab Test", - "ssh_url": "git@example.com:gitlab-org/gitlab-test.git", - "http_url": "http://example.com/gitlab-org/gitlab-test.git", - "web_url": "http://example.com/gitlab-org/gitlab-test", - "namespace": "Gitlab Org", - "visibility_level": 10 + "source":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" }, "target": { - "name": "Gitlab Test", - "ssh_url": "git@example.com:gitlab-org/gitlab-test.git", - "http_url": "http://example.com/gitlab-org/gitlab-test.git", - "web_url": "http://example.com/gitlab-org/gitlab-test", - "namespace": "Gitlab Org", - "visibility_level": 10 + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" }, "last_commit": { "id": "562e173be03b8ff2efb05345d12df18815438a4b", @@ -322,7 +431,12 @@ X-Gitlab-Event: Note Hook "email": "john@example.com" } }, - "work_in_progress": false + "work_in_progress": false, + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } } } ``` @@ -346,11 +460,27 @@ X-Gitlab-Event: Note Hook "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" }, "project_id": 5, - "repository": { - "name": "Gitlab Test", - "url": "http://example.com/gitlab-org/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlab-org/gitlab-test" + "project":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ + "name":"diaspora", + "url":"git@example.com:mike/diasporadiaspora.git", + "description":"", + "homepage":"http://example.com/mike/diaspora" }, "object_attributes": { "id": 1241, @@ -388,7 +518,6 @@ X-Gitlab-Event: Note Hook ### Comment on code snippet - **Request header**: ``` @@ -397,7 +526,7 @@ X-Gitlab-Event: Note Hook **Request body:** -``` +```json { "object_kind": "note", "user": { @@ -406,11 +535,27 @@ X-Gitlab-Event: Note Hook "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" }, "project_id": 5, - "repository": { - "name": "Gitlab Test", - "url": "http://example.com/gitlab-org/gitlab-test.git", - "description": "Aut reprehenderit ut est.", - "homepage": "http://example.com/gitlab-org/gitlab-test" + "project":{ + "name":"Gitlab Test", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/gitlab-org/gitlab-test", + "avatar_url":null, + "git_ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "git_http_url":"http://example.com/gitlab-org/gitlab-test.git", + "namespace":"Gitlab Org", + "visibility_level":10, + "path_with_namespace":"gitlab-org/gitlab-test", + "default_branch":"master", + "homepage":"http://example.com/gitlab-org/gitlab-test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "ssh_url":"git@example.com:gitlab-org/gitlab-test.git", + "http_url":"http://example.com/gitlab-org/gitlab-test.git" + }, + "repository":{ + "name":"Gitlab Test", + "url":"http://example.com/gitlab-org/gitlab-test.git", + "description":"Aut reprehenderit ut est.", + "homepage":"http://example.com/gitlab-org/gitlab-test" }, "object_attributes": { "id": 1245, @@ -482,21 +627,37 @@ X-Gitlab-Event: Merge Request Hook "target_project_id": 14, "iid": 1, "description": "", - "source": { - "name": "awesome_project", - "ssh_url": "ssh://git@example.com/awesome_space/awesome_project.git", - "http_url": "http://example.com/awesome_space/awesome_project.git", - "web_url": "http://example.com/awesome_space/awesome_project", - "visibility_level": 20, - "namespace": "awesome_space" + "source":{ + "name":"Awesome Project", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/awesome_space/awesome_project", + "avatar_url":null, + "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", + "git_http_url":"http://example.com/awesome_space/awesome_project.git", + "namespace":"Awesome Space", + "visibility_level":20, + "path_with_namespace":"awesome_space/awesome_project", + "default_branch":"master", + "homepage":"http://example.com/awesome_space/awesome_project", + "url":"http://example.com/awesome_space/awesome_project.git", + "ssh_url":"git@example.com:awesome_space/awesome_project.git", + "http_url":"http://example.com/awesome_space/awesome_project.git" }, "target": { - "name": "awesome_project", - "ssh_url": "ssh://git@example.com/awesome_space/awesome_project.git", - "http_url": "http://example.com/awesome_space/awesome_project.git", - "web_url": "http://example.com/awesome_space/awesome_project", - "visibility_level": 20, - "namespace": "awesome_space" + "name":"Awesome Project", + "description":"Aut reprehenderit ut est.", + "web_url":"http://example.com/awesome_space/awesome_project", + "avatar_url":null, + "git_ssh_url":"git@example.com:awesome_space/awesome_project.git", + "git_http_url":"http://example.com/awesome_space/awesome_project.git", + "namespace":"Awesome Space", + "visibility_level":20, + "path_with_namespace":"awesome_space/awesome_project", + "default_branch":"master", + "homepage":"http://example.com/awesome_space/awesome_project", + "url":"http://example.com/awesome_space/awesome_project.git", + "ssh_url":"git@example.com:awesome_space/awesome_project.git", + "http_url":"http://example.com/awesome_space/awesome_project.git" }, "last_commit": { "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", @@ -510,7 +671,12 @@ X-Gitlab-Event: Merge Request Hook }, "work_in_progress": false, "url": "http://example.com/diaspora/merge_requests/1", - "action": "open" + "action": "open", + "assignee": { + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + } } } ``` diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 3651b55f438..25893f948ea 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -6,17 +6,22 @@ - [GitLab Flow](gitlab_flow.md) - [Groups](groups.md) - [Keyboard shortcuts](shortcuts.md) +- [File finder](file_finder.md) - [Labels](labels.md) - [Notification emails](notifications.md) - [Project Features](project_features.md) - [Project forking workflow](forking_workflow.md) - [Project users](add-user/add-user.md) - [Protected branches](protected_branches.md) +- [Sharing a project with a group](share_with_group.md) +- [Share projects with other groups](share_projects_with_other_groups.md) - [Web Editor](web_editor.md) - [Releases](releases.md) - [Milestones](milestones.md) - [Merge Requests](merge_requests.md) +- [Revert changes](revert_changes.md) - ["Work In Progress" Merge Requests](wip_merge_requests.md) - [Merge When Build Succeeds](merge_when_build_succeeds.md) - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md) - [Importing from SVN, GitHub, BitBucket, etc](importing/README.md) +- [Todos](todos.md) diff --git a/doc/workflow/add-user/add-user.md b/doc/workflow/add-user/add-user.md index 8c9b4f72631..fffa0aba57f 100644 --- a/doc/workflow/add-user/add-user.md +++ b/doc/workflow/add-user/add-user.md @@ -1,25 +1,89 @@ # Project users -You can manage the groups and users and their access levels in all of your projects. You can also personalize the access level you give each user, per project. +You can manage the groups and users and their access levels in all of your +projects. You can also personalize the access level you give each user, +per-project. -Here's how to add or import users to your projects. - -You should have 'master' or 'owner' permissions to add or import a new user +You should have `master` or `owner` permissions to add or import a new user to your project. -To add or import a user, go to your project and click on "Members" on the left side of your screen: +The first step to add or import a user, go to your project and click on +**Members** on the left side of your screen. + + + +--- + +## Add a user + +Right next to **People**, start typing the name or username of the user you +want to add. + + + +--- + +Select the user and the [permission level](../../permissions/permissions.md) +that you'd like to give the user. Note that you can select more than one user. + + + +--- + +Once done, hit **Add users to project** and they will be immediately added to +your project with the permissions you gave them above. + + + +--- + +From there on, you can either remove an existing user or change their access +level to the project. + +## Import users from another project + +You can import another project's users in your own project by hitting the +**Import members** button on the upper right corner of the **Members** menu. + +In the dropdown menu, you can see only the projects you are Master on. + + + +--- + +Select the one you want and hit **Import project members**. A flash message +notifying you that the import was successful will appear, and the new members +are now in the project's members list. Notice that the permissions that they +had on the project you imported from are retained. + + + +--- + +## Invite people using their e-mail address + +If a user you want to give access to doesn't have an account on your GitLab +instance, you can invite them just by typing their e-mail address in the +user search field. + + + +--- - +As you can imagine, you can mix inviting multiple people and adding existing +GitLab users to the project. -Select "Add members" or "Import members" on the right side of your screen: + - +--- -If you are adding a user, select the user and the [permission level](doc/permissions/permissions.md) that you'd like to -give the user: +Once done, hit **Add users to project** and watch that there is a new member +with the e-mail address we used above. From there on, you can resend the +invitation, change their access level or even delete them. - + -If you are importing a user, follow the steps to select the project where you'd like to import the user from: +--- - +Once the user accepts the invitation, they will be prompted to create a new +GitLab account using the same e-mail address the invitation was sent to. diff --git a/doc/workflow/add-user/images/add-members.png b/doc/workflow/add-user/images/add-members.png Binary files differdeleted file mode 100644 index 2805c5764a5..00000000000 --- a/doc/workflow/add-user/images/add-members.png +++ /dev/null diff --git a/doc/workflow/add-user/images/new-member.png b/doc/workflow/add-user/images/new-member.png Binary files differdeleted file mode 100644 index d500daea56e..00000000000 --- a/doc/workflow/add-user/images/new-member.png +++ /dev/null diff --git a/doc/workflow/add-user/images/select-project.png b/doc/workflow/add-user/images/select-project.png Binary files differdeleted file mode 100644 index dd3844edff8..00000000000 --- a/doc/workflow/add-user/images/select-project.png +++ /dev/null diff --git a/doc/workflow/add-user/img/add_new_user_to_project_settings.png b/doc/workflow/add-user/img/add_new_user_to_project_settings.png Binary files differnew file mode 100644 index 00000000000..3da18cdae53 --- /dev/null +++ b/doc/workflow/add-user/img/add_new_user_to_project_settings.png diff --git a/doc/workflow/add-user/img/add_user_email_accept.png b/doc/workflow/add-user/img/add_user_email_accept.png Binary files differnew file mode 100644 index 00000000000..910affc9659 --- /dev/null +++ b/doc/workflow/add-user/img/add_user_email_accept.png diff --git a/doc/workflow/add-user/img/add_user_email_ready.png b/doc/workflow/add-user/img/add_user_email_ready.png Binary files differnew file mode 100644 index 00000000000..5f02ce89b3e --- /dev/null +++ b/doc/workflow/add-user/img/add_user_email_ready.png diff --git a/doc/workflow/add-user/img/add_user_email_search.png b/doc/workflow/add-user/img/add_user_email_search.png Binary files differnew file mode 100644 index 00000000000..140979fbe13 --- /dev/null +++ b/doc/workflow/add-user/img/add_user_email_search.png diff --git a/doc/workflow/add-user/img/add_user_give_permissions.png b/doc/workflow/add-user/img/add_user_give_permissions.png Binary files differnew file mode 100644 index 00000000000..8ef9156c8d5 --- /dev/null +++ b/doc/workflow/add-user/img/add_user_give_permissions.png diff --git a/doc/workflow/add-user/img/add_user_import_members_from_another_project.png b/doc/workflow/add-user/img/add_user_import_members_from_another_project.png Binary files differnew file mode 100644 index 00000000000..5770d5cf0c4 --- /dev/null +++ b/doc/workflow/add-user/img/add_user_import_members_from_another_project.png diff --git a/doc/workflow/add-user/img/add_user_imported_members.png b/doc/workflow/add-user/img/add_user_imported_members.png Binary files differnew file mode 100644 index 00000000000..dea4b3f40ad --- /dev/null +++ b/doc/workflow/add-user/img/add_user_imported_members.png diff --git a/doc/workflow/add-user/img/add_user_list_members.png b/doc/workflow/add-user/img/add_user_list_members.png Binary files differnew file mode 100644 index 00000000000..7daa6ca7d9e --- /dev/null +++ b/doc/workflow/add-user/img/add_user_list_members.png diff --git a/doc/workflow/add-user/images/members.png b/doc/workflow/add-user/img/add_user_members_menu.png Binary files differindex f1797b95f67..f1797b95f67 100644 --- a/doc/workflow/add-user/images/members.png +++ b/doc/workflow/add-user/img/add_user_members_menu.png diff --git a/doc/workflow/add-user/img/add_user_search_people.png b/doc/workflow/add-user/img/add_user_search_people.png Binary files differnew file mode 100644 index 00000000000..5ac10ce80d4 --- /dev/null +++ b/doc/workflow/add-user/img/add_user_search_people.png 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..1b354bcc0f1 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -16,7 +16,7 @@ It offers a simple, transparent and effective way to work with git.  When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues. -Most version control systems have only step, committing from the working copy to a shared server. +Most version control systems have only one step, committing from the working copy to a shared server. In git you add files from the working copy to the staging area. After that you commit them to the local repo. The third step is pushing to a shared remote repository. After getting used to these three steps the branching model becomes the challenge. @@ -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,13 +186,16 @@ 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. +In GitLab EE and .com you can also [rebase before merge](http://doc.gitlab.com/ee/workflow/rebase_before_merge.html) from the web interface. This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. However you should never rebase commits you have pushed to a remote server. Somebody can have referred to the commits or cherry-picked them. When you rebase you change the identifier (SHA-1) of the commit and this is confusing. If you do that the same change will be known under multiple identifiers and this can cause much confusion. If people already reviewed your code it will be hard for them to review only the improvements you made since then if you have rebased everything into one commit. +Another reasons not to rebase is that you lose authorship information, maybe someone created a merge request, another person pushed a commit on there to improve it and a third one merged it. +In this case rebasing all the commits into one prevent the other authors from being properly attributed and sharing part of the [git blame](https://git-scm.com/docs/git-blame). People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on. This will lead to many commits per change which makes the history harder to understand. @@ -220,13 +224,11 @@ You can reuse recorded resolutions (rerere) sometimes, but without rebasing you There has to be a better way to avoid many merge commits. The way to prevent creating many merge commits is to not frequently merge master into the feature branch. -We'll discuss the three reasons to merge in master: leveraging code, solving merge conflicts and long running branches. +We'll discuss the three reasons to merge in master: leveraging code, merge conflicts, and long running branches. If you need to leverage some code that was introduced in master after you created the feature branch you can sometimes solve this by just cherry-picking a commit. If your feature branch has a merge conflict, creating a merge commit is a normal way of solving this. -You should aim to prevent merge conflicts where they are likely to occur. -One example is the CHANGELOG file where each significant change in the codebase is documented under a version header. -Instead of everyone adding their change at the bottom of the list for the current version it is better to randomly insert it in the current list for that version. -This it is likely that multiple feature branches that add to the CHANGELOG can be merged before a conflict occurs. +You can prevent some merge conflicts by using [gitattributes](http://git-scm.com/docs/gitattributes) for files that can be in a random order. +For example in GitLab our changelog file is specified in .gitattributes as `CHANGELOG merge=union` so that there are fewer merge conflicts in it. The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project. Martin Fowler, in [his article about feature branches](http://martinfowler.com/bliki/FeatureBranch.html) talks about this Continuous Integration (CI). At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. diff --git a/doc/workflow/groups/max_access_level.png b/doc/workflow/groups/max_access_level.png Binary files differnew file mode 100644 index 00000000000..71106a8a5a0 --- /dev/null +++ b/doc/workflow/groups/max_access_level.png diff --git a/doc/workflow/groups/other_group_sees_shared_project.png b/doc/workflow/groups/other_group_sees_shared_project.png Binary files differnew file mode 100644 index 00000000000..cbf2c3c1fdc --- /dev/null +++ b/doc/workflow/groups/other_group_sees_shared_project.png diff --git a/doc/workflow/groups/share_project_with_groups.png b/doc/workflow/groups/share_project_with_groups.png Binary files differnew file mode 100644 index 00000000000..a5dbc89fe90 --- /dev/null +++ b/doc/workflow/groups/share_project_with_groups.png 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/img/revert_changes_commit.png b/doc/workflow/img/revert_changes_commit.png Binary files differnew file mode 100644 index 00000000000..d84211e20db --- /dev/null +++ b/doc/workflow/img/revert_changes_commit.png diff --git a/doc/workflow/img/revert_changes_commit_modal.png b/doc/workflow/img/revert_changes_commit_modal.png Binary files differnew file mode 100644 index 00000000000..e94d151a2af --- /dev/null +++ b/doc/workflow/img/revert_changes_commit_modal.png diff --git a/doc/workflow/img/revert_changes_mr.png b/doc/workflow/img/revert_changes_mr.png Binary files differnew file mode 100644 index 00000000000..7adad88463b --- /dev/null +++ b/doc/workflow/img/revert_changes_mr.png diff --git a/doc/workflow/img/revert_changes_mr_modal.png b/doc/workflow/img/revert_changes_mr_modal.png Binary files differnew file mode 100644 index 00000000000..9da78f84828 --- /dev/null +++ b/doc/workflow/img/revert_changes_mr_modal.png diff --git a/doc/workflow/img/todos_icon.png b/doc/workflow/img/todos_icon.png Binary files differnew file mode 100644 index 00000000000..879b3b51c21 --- /dev/null +++ b/doc/workflow/img/todos_icon.png diff --git a/doc/workflow/img/todos_index.png b/doc/workflow/img/todos_index.png Binary files differnew file mode 100644 index 00000000000..4ee18dd1285 --- /dev/null +++ b/doc/workflow/img/todos_index.png diff --git a/doc/workflow/img/web_editor_new_branch_dropdown.png b/doc/workflow/img/web_editor_new_branch_dropdown.png Binary files differnew file mode 100644 index 00000000000..009e4b05adf --- /dev/null +++ b/doc/workflow/img/web_editor_new_branch_dropdown.png diff --git a/doc/workflow/img/web_editor_new_branch_page.png b/doc/workflow/img/web_editor_new_branch_page.png Binary files differnew file mode 100644 index 00000000000..dd6cfc6e7bb --- /dev/null +++ b/doc/workflow/img/web_editor_new_branch_page.png diff --git a/doc/workflow/img/web_editor_new_directory_dialog.png b/doc/workflow/img/web_editor_new_directory_dialog.png Binary files differnew file mode 100644 index 00000000000..2c76f84f395 --- /dev/null +++ b/doc/workflow/img/web_editor_new_directory_dialog.png diff --git a/doc/workflow/img/web_editor_new_directory_dropdown.png b/doc/workflow/img/web_editor_new_directory_dropdown.png Binary files differnew file mode 100644 index 00000000000..cedf46aedfd --- /dev/null +++ b/doc/workflow/img/web_editor_new_directory_dropdown.png diff --git a/doc/workflow/img/web_editor_new_file_dropdown.png b/doc/workflow/img/web_editor_new_file_dropdown.png Binary files differnew file mode 100644 index 00000000000..6e884f6504d --- /dev/null +++ b/doc/workflow/img/web_editor_new_file_dropdown.png diff --git a/doc/workflow/img/web_editor_new_file_editor.png b/doc/workflow/img/web_editor_new_file_editor.png Binary files differnew file mode 100644 index 00000000000..c76473bcfa7 --- /dev/null +++ b/doc/workflow/img/web_editor_new_file_editor.png diff --git a/doc/workflow/img/web_editor_new_push_widget.png b/doc/workflow/img/web_editor_new_push_widget.png Binary files differnew file mode 100644 index 00000000000..a2108735741 --- /dev/null +++ b/doc/workflow/img/web_editor_new_push_widget.png diff --git a/doc/workflow/img/web_editor_new_tag_dropdown.png b/doc/workflow/img/web_editor_new_tag_dropdown.png Binary files differnew file mode 100644 index 00000000000..263dd635b95 --- /dev/null +++ b/doc/workflow/img/web_editor_new_tag_dropdown.png diff --git a/doc/workflow/img/web_editor_new_tag_page.png b/doc/workflow/img/web_editor_new_tag_page.png Binary files differnew file mode 100644 index 00000000000..64d7cd11ed1 --- /dev/null +++ b/doc/workflow/img/web_editor_new_tag_page.png diff --git a/doc/workflow/img/web_editor_start_new_merge_request.png b/doc/workflow/img/web_editor_start_new_merge_request.png Binary files differnew file mode 100644 index 00000000000..be12a151cac --- /dev/null +++ b/doc/workflow/img/web_editor_start_new_merge_request.png diff --git a/doc/workflow/img/web_editor_upload_file_dialog.png b/doc/workflow/img/web_editor_upload_file_dialog.png Binary files differnew file mode 100644 index 00000000000..6dd2207bca0 --- /dev/null +++ b/doc/workflow/img/web_editor_upload_file_dialog.png diff --git a/doc/workflow/img/web_editor_upload_file_dropdown.png b/doc/workflow/img/web_editor_upload_file_dropdown.png Binary files differnew file mode 100644 index 00000000000..bf6528701b0 --- /dev/null +++ b/doc/workflow/img/web_editor_upload_file_dropdown.png diff --git a/doc/workflow/importing/github_importer/importer.png b/doc/workflow/importing/github_importer/importer.png Binary files differdeleted file mode 100644 index 57636717571..00000000000 --- a/doc/workflow/importing/github_importer/importer.png +++ /dev/null diff --git a/doc/workflow/importing/github_importer/new_project_page.png b/doc/workflow/importing/github_importer/new_project_page.png Binary files differdeleted file mode 100644 index 002f22d81d7..00000000000 --- a/doc/workflow/importing/github_importer/new_project_page.png +++ /dev/null diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/workflow/importing/img/import_projects_from_github_importer.png Binary files differnew file mode 100644 index 00000000000..f744dc06f81 --- /dev/null +++ b/doc/workflow/importing/img/import_projects_from_github_importer.png diff --git a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png Binary files differnew file mode 100644 index 00000000000..86be35acb37 --- /dev/null +++ b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png diff --git a/doc/workflow/importing/import_projects_from_bitbucket.md b/doc/workflow/importing/import_projects_from_bitbucket.md index 1e9825e2e10..520c4216295 100644 --- a/doc/workflow/importing/import_projects_from_bitbucket.md +++ b/doc/workflow/importing/import_projects_from_bitbucket.md @@ -1,6 +1,6 @@ # Import your project from Bitbucket to GitLab
-It takes just a few steps to import your existing Bitbucket projects to GitLab. But keep in mind that it is possible only if Bitbucket support is enabled on your GitLab instance. You can read more about Bitbucket support [here](doc/integration/bitbucket.md).
+It takes just a few steps to import your existing Bitbucket projects to GitLab. But keep in mind that it is possible only if Bitbucket support is enabled on your GitLab instance. You can read more about Bitbucket support [here](../../integration/bitbucket.md).
* Sign in to GitLab.com and go to your dashboard
diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md index 2d77c6d1172..f693f430a42 100644 --- a/doc/workflow/importing/import_projects_from_github.md +++ b/doc/workflow/importing/import_projects_from_github.md @@ -1,20 +1,44 @@ # Import your project from GitHub to GitLab
-It takes just a couple of steps to import your existing GitHub projects to GitLab. Keep in mind that it is possible only if
-GitHub support is enabled on your GitLab instance. You can read more about GitHub support [here](http://doc.gitlab.com/ce/integration/github.html)
+_**Note:** In order to enable the GitHub import setting, you should first
+enable the [GitHub integration][gh-import] in your GitLab instance._
-If you want to import from a GitHub Enterprise instance, you need to use GitLab Enterprise; please see the [EE docs for the GitHub integration](http://doc.gitlab.com/ee/integration/github.html).
+At its current state, GitHub importer can import:
-* Sign in to GitLab.com and go to your dashboard.
-* To get to the importer page, you need to go to the "New project" page.
+- 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.
-* Click on the "Import project from GitHub" link and you will be redirected to GitHub for permission to access your projects. After accepting, you'll be automatically redirected to the importer.
+The importer page is visible when you [create a new project][new-project].
+Click on the **GitHub** link and you will be redirected to GitHub for
+permission to access your projects. After accepting, you'll be automatically
+redirected to the importer.
-
+
-* To import a project, you can simple click "Add". The importer will import your repository and issues. Once the importer is done, a new GitLab project will be created with your imported data.
+---
-### Note
-When you import your projects from GitHub, it is not possible to keep your labels and milestones. We are working on improving this in the near future.
+While at the GitHub importer page, you can see the import statuses of your
+GitHub projects. Those that are being imported will show a _started_ status,
+those already imported will be green, whereas those that are not yet imported
+have an **Import** button on the right side of the table. If you want, you can
+import all your GitHub projects in one go by hitting **Import all projects**
+in the upper left corner.
+
+
+
+---
+
+The importer will create any new namespaces if they don't exist or in the
+case the namespace is taken, the project will be imported on the user's
+namespace.
+
+[gh-import]: ../../integration/github.md "GitHub integration"
+[ee-gh]: http://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/importing/migrating_from_svn.md b/doc/workflow/importing/migrating_from_svn.md index b355a91b5a6..4828bb5dce6 100644 --- a/doc/workflow/importing/migrating_from_svn.md +++ b/doc/workflow/importing/migrating_from_svn.md @@ -69,6 +69,7 @@ branches and tags. ```bash git remote add origin git@gitlab.com:<group>/<project>.git git push --all origin +git push --tags origin ``` ## Contribute to this guide diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md index 5076b2697a3..36cb9da2380 100644 --- a/doc/workflow/lfs/lfs_administration.md +++ b/doc/workflow/lfs/lfs_administration.md @@ -9,7 +9,8 @@ Documentation on how to use Git LFS are under [Managing large binary files with ## Configuration -Git LFS objects can be large in size. By default, they are stored on the server GitLab is installed on. +Git LFS objects can be large in size. By default, they are stored on the server +GitLab is installed on. There are two configuration options to help GitLab server administrators: @@ -37,5 +38,8 @@ In `config/gitlab.yml`: ## Known limitations -* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) is not supported +* Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets) + is not supported * Currently, removing LFS objects from GitLab Git LFS storage is not supported +* LFS authentications via SSH is not supported for the time being +* Only compatible with the GitLFS client versions 1.1.0 or 1.0.2. diff --git a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md index b59e92cb317..ba91685a20b 100644 --- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md +++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md @@ -1,17 +1,21 @@ # Git LFS -Managing large files such as audio, video and graphics files has always been one of the shortcomings of Git. -The general recommendation is to not have Git repositories larger than 1GB to preserve performance. +Managing large files such as audio, video and graphics files has always been one +of the shortcomings of Git. The general recommendation is to not have Git repositories +larger than 1GB to preserve performance. -GitLab already supports [managing large files with git annex](http://doc.gitlab.com/ee/workflow/git_annex.html) (EE only), however in certain -environments it is not always convenient to use different commands to differentiate between the large files and regular ones. +GitLab already supports [managing large files with git annex](http://doc.gitlab.com/ee/workflow/git_annex.html) +(EE only), however in certain environments it is not always convenient to use +different commands to differentiate between the large files and regular ones. -Git LFS makes this simpler for the end user by removing the requirement to learn new commands. +Git LFS makes this simpler for the end user by removing the requirement to +learn new commands. ## How it works -Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication to authorize client requests. -Once the request is authorized, Git LFS client receives instructions from where to fetch or where to push the large file. +Git LFS client talks with the GitLab server over HTTPS. It uses HTTP Basic Authentication +to authorize client requests. Once the request is authorized, Git LFS client receives +instructions from where to fetch or where to push the large file. ## GitLab server configuration @@ -24,15 +28,19 @@ Documentation for GitLab instance administrators is under [LFS administration do ## Known limitations -* Git LFS v1 original API is not supported since it was deprecated early in LFS development +* Git LFS v1 original API is not supported since it was deprecated early in LFS + development * When SSH is set as a remote, Git LFS objects still go through HTTPS -* Any Git LFS request will ask for HTTPS credentials to be provided so good Git credentials store is recommended -* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have to add the URL to Git config manually (see #troubleshooting) +* Any Git LFS request will ask for HTTPS credentials to be provided so good Git + credentials store is recommended +* Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have + to add the URL to Git config manually (see #troubleshooting) ## Using Git LFS -Lets take a look at the workflow when you need to check large files into your Git repository with Git LFS: -For example, if you want to upload a very large file and check it into your Git repository: +Lets take a look at the workflow when you need to check large files into your Git +repository with Git LFS. For example, if you want to upload a very large file and +check it into your Git repository: ```bash git clone git@gitlab.example.com:group/project.git @@ -40,7 +48,8 @@ git lfs init # initialize the Git LFS project project git lfs track "*.iso" # select the file extensions that you want to treat as large files ``` -Once a certain file extension is marked for tracking as a LFS object you can use Git as usual without having to redo the command to track a file with the same extension: +Once a certain file extension is marked for tracking as a LFS object you can use +Git as usual without having to redo the command to track a file with the same extension: ```bash cp ~/tmp/debian.iso ./ # copy a large file into the current directory @@ -49,13 +58,17 @@ git commit -am "Added Debian iso" # commit the file meta data git push origin master # sync the git repo and large file to the GitLab server ``` -Cloning the repository works the same as before. Git automatically detects the LFS-tracked files and clones them via HTTP. If you performed the git clone command with a SSH URL, you have to enter your GitLab credentials for HTTP authentication. +Cloning the repository works the same as before. Git automatically detects the +LFS-tracked files and clones them via HTTP. If you performed the git clone +command with a SSH URL, you have to enter your GitLab credentials for HTTP +authentication. ```bash git clone git@gitlab.example.com:group/project.git ``` -If you already cloned the repository and you want to get the latest LFS object that are on the remote repository, eg. from branch `master`: +If you already cloned the repository and you want to get the latest LFS object +that are on the remote repository, eg. from branch `master`: ```bash git lfs fetch master @@ -73,8 +86,8 @@ Check if you have permissions to push to the project or fetch from the project. * Project is not allowed to access the LFS object -LFS object you are trying to push to the project or fetch from the project is not available to the project anymore. -Probably the object was removed from the server. +LFS object you are trying to push to the project or fetch from the project is not +available to the project anymore. Probably the object was removed from the server. * Local git repository is using deprecated LFS API @@ -89,16 +102,26 @@ git lfs logs last If the status `error 501` is shown, it is because: -* Git LFS support is not enabled on the GitLab server. Check with your GitLab administrator why Git LFS is not enabled on the server. See [LFS administration documentation](lfs_administration.md) for instructions on how to enable LFS support. +* Git LFS support is not enabled on the GitLab server. Check with your GitLab + administrator why Git LFS is not enabled on the server. See + [LFS administration documentation](lfs_administration.md) for instructions + on how to enable LFS support. -* Git LFS client version is not supported by GitLab server. Check your Git LFS version with `git lfs version`. Check the Git config of the project for traces of deprecated API with `git lfs -l`. If `batch = false` is set in the config, remove the line and try to update your Git LFS client. Only version 1.0.1 and newer are supported. +* Git LFS client version is not supported by GitLab server. Check your Git LFS + version with `git lfs version`. Check the Git config of the project for traces + of deprecated API with `git lfs -l`. If `batch = false` is set in the config, + remove the line and try to update your Git LFS client. Only version 1.0.1 and + newer are supported. ### getsockopt: connection refused -If you push a LFS object to a project and you receive an error similar to: `Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`, -the LFS client is trying to reach GitLab through HTTPS. However, your GitLab instance is being served on HTTP. +If you push a LFS object to a project and you receive an error similar to: +`Post <URL>/info/lfs/objects/batch: dial tcp IP: getsockopt: connection refused`, +the LFS client is trying to reach GitLab through HTTPS. However, your GitLab +instance is being served on HTTP. -This behaviour is caused by Git LFS using HTTPS connections by default when a `lfsurl` is not set in the Git config. +This behaviour is caused by Git LFS using HTTPS connections by default when a +`lfsurl` is not set in the Git config. To prevent this from happening, set the lfs url in project Git config: @@ -109,18 +132,24 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs/o ### Credentials are always required when pushing an object -Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing the LFS object on every push for every object, user HTTPS credentials are required. +Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing +the LFS object on every push for every object, user HTTPS credentials are required. -By default, Git has support for remembering the credentials for each repository you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials). +By default, Git has support for remembering the credentials for each repository +you use. This is described in [Git credentials man pages](https://git-scm.com/docs/gitcredentials). -For example, you can tell Git to remember the password for a period of time in which you expect to push the objects: +For example, you can tell Git to remember the password for a period of time in +which you expect to push the objects: ```bash git config --global credential.helper 'cache --timeout=3600' ``` -This will remember the credentials for an hour after which Git operations will require re-authentication. +This will remember the credentials for an hour after which Git operations will +require re-authentication. -If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases). +If you are using OS X you can use `osxkeychain` to store and encrypt your credentials. +For Windows, you can use `wincred` or Microsoft's [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases). -More details about various methods of storing the user credentials can be found on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
\ No newline at end of file +More details about various methods of storing the user credentials can be found +on [Git Credential Storage documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage).
\ No newline at end of file diff --git a/doc/workflow/protected_branches.md b/doc/workflow/protected_branches.md index 0adf9f8e3e8..d854ec1e025 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. @@ -12,7 +12,7 @@ A protected branch does three simple things: You can make any branch a protected branch. GitLab makes the master branch a protected branch by default. -To protect a branch, user needs to have at least a Master permission level, see [permissions document](doc/permissions/permissions.md). +To protect a branch, user needs to have at least a Master permission level, see [permissions document](../permissions/permissions.md).  diff --git a/doc/workflow/revert_changes.md b/doc/workflow/revert_changes.md new file mode 100644 index 00000000000..399366b0cdc --- /dev/null +++ b/doc/workflow/revert_changes.md @@ -0,0 +1,64 @@ +# Reverting changes + +_**Note:** This feature was [introduced][ce-1990] in GitLab 8.5._ + +--- + +GitLab implements Git's powerful feature to [revert any commit][git-revert] +with introducing a **Revert** button in Merge Requests and commit details. + +## Reverting a Merge Request + +_**Note:** The **Revert** button will only be available for Merge Requests +created since GitLab 8.5. However, you can still revert a Merge Request +by reverting the merge commit from the list of Commits page._ + +After the Merge Request has been merged, a **Revert** button will be available +to revert the changes introduced by that Merge Request: + + + +--- + +You can revert the changes directly into the selected branch or you can opt to +create a new Merge Request with the revert changes: + + + +--- + +After the Merge Request has been reverted, the **Revert** button will not be +available anymore. + +## Reverting a Commit + +You can revert a Commit from the Commit details page: + + + +--- + +Similar to reverting a Merge Request, you can opt to revert the changes +directly into the target branch or create a new Merge Request to revert the +changes: + + + +--- + +After the Commit has been reverted, the **Revert** button will not be available +anymore. + +Please note that when reverting merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line. + +Here is a quick example to revert a merge commit using the second parent as the +mainline: + +```bash +git revert -m 2 7a39eb0 +``` + +[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request" +[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation" diff --git a/doc/workflow/share_projects_with_other_groups.md b/doc/workflow/share_projects_with_other_groups.md new file mode 100644 index 00000000000..4c59f59c587 --- /dev/null +++ b/doc/workflow/share_projects_with_other_groups.md @@ -0,0 +1,30 @@ +# Share Projects with other Groups + +In GitLab Enterprise Edition you can share projects with other groups. +This makes it possible to add a group of users to a project with a single action. + +## Groups as collections of users + +In GitLab Community Edition groups are used primarily to [create collections of projects](groups.md). +In GitLab Enterprise Edition you can also take advantage of the fact that groups define collections of _users_, namely the group members. + +## Sharing a project with a group of users + +The primary mechanism to give a group of users, say 'Engineering', access to a project, say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project Acme'. +But what if 'Project Acme' already belongs to another group, say 'Open Source'? +This is where the (Enterprise Edition only) group sharing feature can be of use. + +To share 'Project Acme' with the 'Engineering' group, go to the project settings page for 'Project Acme' and use the left navigation menu to go to the 'Groups' section. + + + +Now you can add the 'Engineering' group with the maximum access level of your choice. +After sharing 'Project Acme' with 'Engineering', the project is listed on the group dashboard. + + + +## Maximum access level + + + +In the screenshot above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Master' or 'Owner') will only have 'Developer' access to 'Project Acme'. diff --git a/doc/workflow/share_with_group.md b/doc/workflow/share_with_group.md new file mode 100644 index 00000000000..3b7690973cb --- /dev/null +++ b/doc/workflow/share_with_group.md @@ -0,0 +1,13 @@ +# Sharing a project with a group + +If you want to share a single project in a group with another group, +you can do so easily. By setting the permission you can quickly +give a select group of users access to a project in a restricted manner. + +In a project go to the project settings -> groups. + +Now you can select a group that you want to share this project with and with +which maximum access level. Users in that group are able to access this project +with their set group access level, up to the maximum level that you've set. + + diff --git a/doc/workflow/share_with_group.png b/doc/workflow/share_with_group.png Binary files differnew file mode 100644 index 00000000000..a0ca6f14552 --- /dev/null +++ b/doc/workflow/share_with_group.png diff --git a/doc/workflow/shortcuts.png b/doc/workflow/shortcuts.png Binary files differindex 68756ed1f98..83e562d6929 100644 --- a/doc/workflow/shortcuts.png +++ b/doc/workflow/shortcuts.png diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md new file mode 100644 index 00000000000..5f440fdafdd --- /dev/null +++ b/doc/workflow/todos.md @@ -0,0 +1,73 @@ +# GitLab ToDos + +>**Note:** This feature was [introduced][ce-2817] in GitLab 8.5. + +When you log into GitLab, you normally want to see where you should spend your +time and take some action, or what you need to keep an eye on. All without the +mess of a huge pile of e-mail notifications. GitLab is where you do your work, +so being able to get started quickly is very important. + +Todos is a chronological list of to-dos that are waiting for your input, all +in a simple dashboard. + + + +--- + +You can access quickly your Todos dashboard by clicking the round gray icon +next to the search bar in the upper right corner. + + + +## What triggers a Todo + +A Todo appears in your Todos dashboard when: + +- an issue or merge request is assigned to you +- you are `@mentioned` in an issue or merge request, be it the description of + the issue/merge request or in a comment + +>**Note:** Commenting on a commit will _not_ trigger a Todo. + +## How a Todo is marked as Done + +Any action to the corresponding issue or merge request will mark your Todo as +**Done**. This action can include: + +- changing the assignee +- changing the milestone +- adding/removing a label +- commenting on the issue + +In case where you think no action is needed, you can manually mark the todo as +done by clicking the corresponding **Done** button, and it will disappear from +your Todos list. If you want to mark all your Todos as done, just click on the +**Mark all as done** button. + +--- + +In order for a Todo to be marked as done, the action must be coming from you. +So, if you close the related issue or merge the merge request yourself, and you +had a Todo for that, it will automatically get marked as done. On the other +hand, if someone else closes, merges or takes action on the issue or merge +request, your Todo will remain pending. This makes sense because you may need +to give attention to an issue even if it has been resolved. + +There is just one Todo per issue or merge request, so mentioning a user a +hundred times in an issue will only trigger one Todo. + +## Filtering your Todos + +In general, there are four kinds of filters you can use on your Todos +dashboard: + +| Filter | Description | +| ------ | ----------- | +| Project | Filter by project | +| Author | Filter by the author that triggered the Todo | +| Type | Filter by issue or merge request | +| Action | Filter by the action that triggered the Todo (Assigned or Mentioned)| + +You can choose more than one filters at the same time. + +[ce-2817]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2817 diff --git a/doc/workflow/web_editor.md b/doc/workflow/web_editor.md index 7fc8f96b9ec..4a451d98953 100644 --- a/doc/workflow/web_editor.md +++ b/doc/workflow/web_editor.md @@ -1,26 +1,120 @@ # GitLab Web Editor -In GitLab you can create new files and edit existing files using our web editor. -This is especially useful if you don't have access to a command line or you just want to do a quick fix. -You can easily access the web editor, depending on the context. -Let's start from newly created project. +Sometimes it's easier to make quick changes directly from the GitLab interface +than to clone the project and use the Git command line tool. In this feature +highlight we look at how you can create a new file, directory, branch or +tag from the file browser. All of these actions are available from a single +dropdown menu. -Click on `Add a file` -to create the first file and open it in the web editor. +## Create a file - +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New file** from the dropdown. -Fill in a file name, some content, a commit message, branch name and press the commit button. -The file will be saved to the repository. + - +--- -You can edit any text file in a repository by pressing the edit button, when -viewing the file. +Enter a file name in the **File name** box. Then, add file content in the editor +area. Add a descriptive commit message and choose a branch. The branch field +will default to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox will appear allowing you to start a new merge +request after you commit the changes. - +When you are satisfied with your new file, click **Commit Changes** at the bottom. -Editing a file is almost the same as creating a new file, -with as addition the ability to preview your changes in a separate tab. Also you can save your change to another branch by filling out field `branch` + - +## Upload a file + +The ability to create a file is great when the content is text. However, this +doesn't work well for binary data such as images, PDFs or other file types. In +this case you need to upload a file. + +From a project's files page, click the '+' button to the right of the branch +selector. Choose **Upload file** from the dropdown. + + + +--- + +Once the upload dialog pops up there are two ways to upload your file. Either +drag and drop a file on the pop up or use the **click to upload** link. A file +preview will appear once you have selected a file to upload. + +Enter a commit message, choose a branch, and click **Upload file** when you are +ready. + + + +## Create a directory + +To keep files in the repository organized it is often helpful to create a new +directory. + +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New directory** from the dropdown. + + + +--- + +In the new directory dialog enter a directory name, a commit message and choose +the target branch. Click **Create directory** to finish. + + + +## Create a new branch + +If you want to make changes to several files before creating a new merge +request, you can create a new branch up front. From a project's files page, +choose **New branch** from the dropdown. + + + +--- + +Enter a new **Branch name**. Optionally, change the **Create from** field +to choose which branch, tag or commit SHA this new branch will originate from. +This field will autocomplete if you start typing an existing branch or tag. +Click **Create branch** and you will be returned to the file browser on this new +branch. + + + +--- + +You can now make changes to any files, as needed. When you're ready to merge +the changes back to master you can use the widget at the top of the screen. +This widget only appears for a period of time after you create the branch or +modify files. + + + +## Create a new tag + +Tags are useful for marking major milestones such as production releases, +release candidates, and more. You can create a tag from a branch or a commit +SHA. From a project's files page, choose **New tag** from the dropdown. + + + +--- + +Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you +would like to create this new tag. You can optionally add a message and +release notes. The release notes section supports markdown format and you can +also upload an attachment. Click **Create tag** and you will be taken to the tag +list page. + + + +## Tips + +When creating or uploading a new file, or creating a new directory, you can +trigger a new merge request rather than committing directly to master. Enter +a new branch name in the **Target branch** field. You will notice a checkbox +appear that is labeled **Start a new merge request with these changes**. After +you commit the changes you will be taken to a new merge request form. + + diff --git a/doc/workflow/web_editor/edit_file.png b/doc/workflow/web_editor/edit_file.png Binary files differdeleted file mode 100644 index f480c69ac3e..00000000000 --- a/doc/workflow/web_editor/edit_file.png +++ /dev/null diff --git a/doc/workflow/web_editor/empty_project.png b/doc/workflow/web_editor/empty_project.png Binary files differdeleted file mode 100644 index 6a049f6beaf..00000000000 --- a/doc/workflow/web_editor/empty_project.png +++ /dev/null diff --git a/doc/workflow/web_editor/new_file.png b/doc/workflow/web_editor/new_file.png Binary files differdeleted file mode 100644 index 55ebd9e0257..00000000000 --- a/doc/workflow/web_editor/new_file.png +++ /dev/null diff --git a/doc/workflow/web_editor/show_file.png b/doc/workflow/web_editor/show_file.png Binary files differdeleted file mode 100644 index 9cafcb55109..00000000000 --- a/doc/workflow/web_editor/show_file.png +++ /dev/null |
