diff options
Diffstat (limited to 'doc')
199 files changed, 0 insertions, 13512 deletions
diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 4e00dceac2b..00000000000 --- a/doc/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# Documentation - -## User documentation - -- [API](api/README.md) Automate GitLab via a simple and powerful API. -- [Markdown](markdown/markdown.md) GitLab's advanced formatting system. -- [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do. -- [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. -- [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN. -- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab. - -## Administrator documentation - -- [Install](install/README.md) Requirements, directory structures and installation from source. -- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter. -- [Raketasks](raketasks/README.md) Backups, maintenance, automatic web hook setup and the importing of projects. -- [Custom git hooks](hooks/custom_hooks.md) Custom git hooks (on the filesystem) for when web hooks aren't enough. -- [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed. -- [Security](security/README.md) Learn what you can do to further secure your GitLab instance. -- [Update](update/README.md) Update guides to upgrade your installation. -- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page. -- [Issue closing](customization/issue_closing.md) Customize how to close an issue from commit messages. -- [Libravatar](customization/libravatar.md) Use Libravatar for user avatars. -- [Operations](operations/README.md) Keeping GitLab up and running -- [Log system](logs/logs.md) Log system - -## Contributor 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/api/README.md b/doc/api/README.md deleted file mode 100644 index dec530d0b81..00000000000 --- a/doc/api/README.md +++ /dev/null @@ -1,209 +0,0 @@ -# GitLab API - -## Resources - -- [Users](users.md) -- [Session](session.md) -- [Projects](projects.md) -- [Project Snippets](project_snippets.md) -- [Repositories](repositories.md) -- [Repository Files](repository_files.md) -- [Commits](commits.md) -- [Branches](branches.md) -- [Merge Requests](merge_requests.md) -- [Issues](issues.md) -- [Labels](labels.md) -- [Milestones](milestones.md) -- [Notes](notes.md) (comments) -- [Deploy Keys](deploy_keys.md) -- [System Hooks](system_hooks.md) -- [Groups](groups.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. - -## Introduction - -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: - -```json -{ - "message": "401 Unauthorized" -} -``` - -API requests should be prefixed with `api` and the API version. The API version is defined in `lib/api.rb`. - -Example of a valid API request: - -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U -``` - -Example for a valid API request using curl and authentication via header: - -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://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. - -## Authentication with OAuth2 token - -Instead of the private_token you can transmit the OAuth2 access token as a header or as a parameter. - -### OAuth2 token (as a parameter) - -``` -curl https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN -``` - -### OAuth2 token (as a header) - -``` -curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/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 - -## 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). - -If a non administrative `private_token` is provided then an error message will be returned with status code 403: - -```json -{ - "message": "403 Forbidden: Must be admin to use sudo" -} -``` - -If the sudo user id or username cannot be found then an error message will be returned with status code 404: - -```json -{ - "message": "404 Not Found: No user id or username for: <id/username>" -} -``` - -Example of a valid API with sudo request: - -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=username -``` - -``` -GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U&sudo=23 -``` - -Example for a valid API request with sudo using curl and authentication via header: - -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: username" "http://example.com/api/v3/projects" -``` - -``` -curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://example.com/api/v3/projects" -``` - -## Pagination - -When listing resources you can pass the following parameters: - -- `page` (default: `1`) - page number -- `per_page` (default: `20`, max: `100`) - number of items to list per 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 - -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: - -Issue: - - id: 46 - iid: 5 - -- 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. - -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` - -## 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. -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 - -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": { - "bio": [ - "is too long (maximum is 255 characters)" - ] - } - } - -This makes error messages more machine-readable. The format can be described as follow: - - { - "message": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - "<embed-entity>": { - "<property-name>": [ - "<error-message>", - "<error-message>", - ... - ], - } - } - } diff --git a/doc/api/branches.md b/doc/api/branches.md deleted file mode 100644 index 6a9c10c8520..00000000000 --- a/doc/api/branches.md +++ /dev/null @@ -1,192 +0,0 @@ -# Branches - -## List repository branches - -Get a list of repository branches from a project, sorted by name alphabetically. - -``` -GET /projects/:id/repository/branches -``` - -Parameters: - -- `id` (required) - The ID of a project - -```json -[ - { - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "protected": true - } -] -``` - -## Get single repository branch - -Get a single project repository branch. - -``` -GET /projects/:id/repository/branches/:branch -``` - -Parameters: - -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch - -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "message": "add projects API", - "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. - -``` -PUT /projects/:id/repository/branches/:branch/protect -``` - -Parameters: - -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch - -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "protected": true -} -``` - -## 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. - -``` -PUT /projects/:id/repository/branches/:branch/unprotect -``` - -Parameters: - -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch - -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "protected": false -} -``` - -## Create repository branch - -``` -POST /projects/:id/repository/branches -``` - -Parameters: - -- `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 - -```json -{ - "commit": { - "author_email": "john@example.com", - "author_name": "John Smith", - "authored_date": "2012-06-27T05:51:39-07:00", - "committed_date": "2012-06-28T03:44:20-07:00", - "committer_email": "john@example.com", - "committer_name": "John Smith", - "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c", - "message": "add projects API", - "parent_ids": [ - "4ad91d3c1144c406e50c7b33bae684bd6837faf8" - ] - }, - "name": "master", - "protected": false -} -``` - -It return 200 if succeed or 400 if failed with error message explaining reason. - -## Delete repository branch - -``` -DELETE /projects/:id/repository/branches/:branch -``` - -Parameters: - -- `id` (required) - The ID of a project -- `branch` (required) - The name of the branch - -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. - -Success response: - -```json -{ - "branch_name": "my-removed-branch" -} -``` diff --git a/doc/api/commits.md b/doc/api/commits.md deleted file mode 100644 index eb8d6a43592..00000000000 --- a/doc/api/commits.md +++ /dev/null @@ -1,158 +0,0 @@ -# Commits API - -## List repository commits - -Get a list of repository commits in a project. - -``` -GET /projects/:id/repository/commits -``` - -Parameters: - -- `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 - -```json -[ - { - "id": "ed899a2f4b50b4370feeea94676502b42383c746", - "short_id": "ed899a2f4b5", - "title": "Replace sanitize with escape once", - "author_name": "Dmitriy Zaporozhets", - "author_email": "dzaporozhets@sphereconsultinginc.com", - "created_at": "2012-09-20T11:50:22+03:00", - "message": "Replace sanitize with escape once" - }, - { - "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6", - "short_id": "6104942438c", - "title": "Sanitize for network graph", - "author_name": "randx", - "author_email": "dmitriy.zaporozhets@gmail.com", - "created_at": "2012-09-20T09:06:12+03:00", - "message": "Sanitize for network graph" - } -] -``` - -## Get a single commit - -Get a specific commit identified by the commit hash or name of a branch or tag. - -``` -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 - -```json -{ - "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6", - "short_id": "6104942438c", - "title": "Sanitize for network graph", - "author_name": "randx", - "author_email": "dmitriy.zaporozhets@gmail.com", - "created_at": "2012-09-20T09:06:12+03:00", - "message": "Sanitize for network graph", - "committed_date": "2012-09-20T09:06:12+03:00", - "authored_date": "2012-09-20T09:06:12+03:00", - "parent_ids": [ - "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba" - ] -} -``` - -## Get the diff of a commit - -Get the diff of a commit in a project. - -``` -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 - -```json -[ - { - "diff": "--- a/doc/update/5.4-to-6.0.md\n+++ b/doc/update/5.4-to-6.0.md\n@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files", - "new_path": "doc/update/5.4-to-6.0.md", - "old_path": "doc/update/5.4-to-6.0.md", - "a_mode": null, - "b_mode": "100644", - "new_file": false, - "renamed_file": false, - "deleted_file": false - } -] -``` - -## Get the comments of a commit - -Get the comments of a commit in a project. - -``` -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 - -```json -[ - { - "note": "this code is really nice", - "author": { - "id": 11, - "username": "admin", - "email": "admin@local.host", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - } -] -``` - -## 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. - -``` -POST /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 -- `note` (required) - Text of comment -- `path` (optional) - The file path -- `line` (optional) - The line number -- `line_type` (optional) - The line type (new or old) - -```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" -} -``` diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md deleted file mode 100644 index 1a5a458905e..00000000000 --- a/doc/api/deploy_key_multiple_projects.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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. - -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 -``` - -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 - -# For group 1234: -curl --header 'PRIVATE-TOKEN: abcdef' https://gitlab.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 -done -``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md deleted file mode 100644 index e4492fc609c..00000000000 --- a/doc/api/deploy_keys.md +++ /dev/null @@ -1,80 +0,0 @@ -# Deploy Keys - -## List deploy keys - -Get a list of a project's deploy keys. - -``` -GET /projects/:id/keys -``` - -Parameters: - -- `id` (required) - The ID of the project - -```json -[ - { - "id": 1, - "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2013-10-02T10:12:29Z" - }, - { - "id": 3, - "title": "Another Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2013-10-02T11:12:29Z" - } -] -``` - -## Single deploy key - -Get a single key. - -``` -GET /projects/:id/keys/:key_id -``` - -Parameters: - -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key - -```json -{ - "id": 1, - "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2013-10-02T10:12:29Z" -} -``` - -## 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 - -``` -POST /projects/:id/keys -``` - -Parameters: - -- `id` (required) - The ID of the project -- `title` (required) - New deploy key's title -- `key` (required) - New deploy key - -## Delete deploy key - -Delete a deploy key from a project - -``` -DELETE /projects/:id/keys/:key_id -``` - -Parameters: - -- `id` (required) - The ID of the project -- `key_id` (required) - The ID of the deploy key diff --git a/doc/api/groups.md b/doc/api/groups.md deleted file mode 100644 index b5a4b05ccaf..00000000000 --- a/doc/api/groups.md +++ /dev/null @@ -1,178 +0,0 @@ -# Groups - -## List project groups - -Get a list of groups. (As user: my groups, as admin: all groups) - -``` -GET /groups -``` - -```json -[ - { - "id": 1, - "name": "Foobar Group", - "path": "foo-bar", - "description": "An interesting group" - } -] -``` - -You can search for groups by name or path, see below. - -## Details of a group - -Get all details of a group. - -``` -GET /groups/:id -``` - -Parameters: - -- `id` (required) - The ID or path of a group - -## New group - -Creates a new project group. Available only for admin. - -``` -POST /groups -``` - -Parameters: - -- `name` (required) - The name of the group -- `path` (required) - The path of the group -- `description` (optional) - The group's description - -## Transfer project to group - -Transfer a project to the Group namespace. Available only for admin - -``` -POST /groups/:id/projects/:project_id -``` - -Parameters: - -- `id` (required) - The ID or path of a group -- `project_id` (required) - The ID of a project - -## Remove group - -Removes group with all projects inside. - -``` -DELETE /groups/:id -``` - -Parameters: - -- `id` (required) - The ID or path of a user group - -## Search for group - -Get all groups that match your string in their name or path. - -``` -GET /groups?search=foobar -``` - -```json -[ - { - "id": 1, - "name": "Foobar Group", - "path": "foo-bar", - "description": "An interesting group" - } -] -``` - -## Group members - -**Group access levels** - -The group access levels are defined in the `Gitlab::Access` module. Currently, these levels are recognized: - -``` -GUEST = 10 -REPORTER = 20 -DEVELOPER = 30 -MASTER = 40 -OWNER = 50 -``` - -### List group members - -Get a list of group members viewable by the authenticated user. - -``` -GET /groups/:id/members -``` - -```json -[ - { - "id": 1, - "username": "raymond_smith", - "email": "ray@smith.org", - "name": "Raymond Smith", - "state": "active", - "created_at": "2012-10-22T14:13:35Z", - "access_level": 30 - }, - { - "id": 2, - "username": "john_doe", - "email": "joh@doe.org", - "name": "John Doe", - "state": "active", - "created_at": "2012-10-22T14:13:35Z", - "access_level": 30 - } -] -``` - -### Add group member - -Adds a user to the list of group members. - -``` -POST /groups/:id/members -``` - -Parameters: - -- `id` (required) - The ID or path of a group -- `user_id` (required) - The ID of a user to add -- `access_level` (required) - Project access level - -### Edit group team member - -Updates a group team member to a specified access level. - -``` -PUT /groups/:id/members/:user_id -``` - -Parameters: - -- `id` (required) - The ID of a group -- `user_id` (required) - The ID of a group member -- `access_level` (required) - Project access level - -### Remove user team member - -Removes user from user team. - -``` -DELETE /groups/:id/members/:user_id -``` - -Parameters: - -- `id` (required) - The ID or path of a user group -- `user_id` (required) - The ID of a group member diff --git a/doc/api/issues.md b/doc/api/issues.md deleted file mode 100644 index a7dd8b74c35..00000000000 --- a/doc/api/issues.md +++ /dev/null @@ -1,224 +0,0 @@ -# Issues - -## 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 /issues -GET /issues?state=opened -GET /issues?state=closed -GET /issues?labels=foo -GET /issues?labels=foo,bar -GET /issues?labels=foo,bar&state=opened -``` - -Parameters: - -- `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` - -```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" - } -] -``` - -## 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 /projects/:id/issues -GET /projects/:id/issues?state=opened -GET /projects/:id/issues?state=closed -GET /projects/:id/issues?labels=foo -GET /projects/:id/issues?labels=foo,bar -GET /projects/:id/issues?labels=foo,bar&state=opened -GET /projects/:id/issues?milestone=1.0.0 -GET /projects/:id/issues?milestone=1.0.0&state=opened -``` - -Parameters: - -- `id` (required) - The ID of a project -- `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` - -## Single issue - -Gets a single project issue. - -``` -GET /projects/:id/issues/:issue_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue - -```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" -} -``` - -## New issue - -Creates a new project issue. - -``` -POST /projects/:id/issues -``` - -Parameters: - -- `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 - -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. - -## Edit issue - -Updates an existing project issue. This function is also used to mark an issue as closed. - -``` -PUT /projects/:id/issues/:issue_id -``` - -Parameters: - -- `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) - -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. - -## 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`. - -``` -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. diff --git a/doc/api/labels.md b/doc/api/labels.md deleted file mode 100644 index de41f35d284..00000000000 --- a/doc/api/labels.md +++ /dev/null @@ -1,84 +0,0 @@ -# Labels - -## List labels - -Get all labels for given project. - -``` -GET /projects/:id/labels -``` - -```json -[ - { - "name": "Awesome", - "color": "#DD10AA" - }, - { - "name": "Documentation", - "color": "#1E80DD" - }, - { - "name": "Feature", - "color": "#11FF22" - }, - { - "name": "Bug", - "color": "#EE1122" - } -] -``` - -## Create a new label - -Creates a new label for given repository with given name and color. - -``` -POST /projects/:id/labels -``` - -Parameters: - -- `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) - -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. - -## Delete a label - -Deletes a label given by its name. - -``` -DELETE /projects/:id/labels -``` - -- `id` (required) - The ID of a project -- `name` (required) - The name of the label to be deleted - -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. - -## Edit an existing label - -Updates an existing label with new name or now color. At least one parameter -is required, to update the label. - -``` -PUT /projects/:id/labels -``` - -Parameters: - -- `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) - -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. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md deleted file mode 100644 index 6a272539e45..00000000000 --- a/doc/api/merge_requests.md +++ /dev/null @@ -1,393 +0,0 @@ -# Merge requests - -## List merge requests - -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. - -``` -GET /projects/:id/merge_requests -GET /projects/:id/merge_requests?state=opened -GET /projects/:id/merge_requests?state=all -``` - -Parameters: - -- `id` (required) - The ID of a project -- `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed` -- `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 -[ - { - "id": 1, - "iid": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 3, - "title": "test1", - "state": "opened", - "upvotes": 0, - "downvotes": 0, - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "assignee": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "description":"fixed login page css paddings" - } -] -``` - -## Get single MR - -Shows information about a single merge request. - -``` -GET /projects/:id/merge_request/:merge_request_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of MR - -```json -{ - "id": 1, - "iid": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 3, - "title": "test1", - "state": "merged", - "upvotes": 0, - "downvotes": 0, - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "assignee": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "description":"fixed login page css paddings" -} -``` - -## Get single MR changes - -Shows information about the merge request including its files and changes - -``` -GET /projects/:id/merge_request/:merge_request_id/changes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of MR - -```json -{ - "id": 21, - "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.", - "state": "reopened", - "created_at": "2015-02-02T19:49:39.159Z", - "updated_at": "2015-02-02T20:08:49.959Z", - "target_branch": "secret_token", - "source_branch": "version-1-9", - "upvotes": 0, - "downvotes": 0, - "author": { - "name": "Chad Hamill", - "username": "jarrett", - "id": 5, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon" - }, - "assignee": { - "name": "Administrator", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon" - }, - "source_project_id": 4, - "target_project_id": 4, - "labels": [ ], - "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 - }, - "files": [ - { - "old_path": "VERSION", - "new_path": "VERSION", - "a_mode": "100644", - "b_mode": "100644", - "diff": "--- a/VERSION\ +++ b/VERSION\ @@ -1 +1 @@\ -1.9.7\ +1.9.8", - "new_file": false, - "renamed_file": false, - "deleted_file": false - } - ] -} -``` - -## Create MR - -Creates a new merge request. - -``` -POST /projects/:id/merge_requests -``` - -Parameters: - -- `id` (required) - The ID of a project -- `source_branch` (required) - The source branch -- `target_branch` (required) - The target branch -- `assignee_id` (optional) - Assignee user ID -- `title` (required) - Title of MR -- `description` (optional) - Description of MR -- `target_project_id` (optional) - The target project (numeric id) - -```json -{ - "id": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 3, - "title": "test1", - "state": "opened", - "upvotes": 0, - "downvotes": 0, - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "assignee": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "description":"fixed login page css paddings" -} -``` - -If the operation is successful, 200 and the newly created merge request is returned. -If an error occurs, an error number and a message explaining the reason is returned. - -## Update MR - -Updates an existing merge request. You can change branches, title, or even close the MR. - -``` -PUT /projects/:id/merge_request/:merge_request_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of MR -- `source_branch` - The source branch -- `target_branch` - The target branch -- `assignee_id` - Assignee user ID -- `title` - Title of MR -- `description` - Description of MR -- `state_event` - New state (close|reopen|merge) - -```json -{ - "id": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 3, - "title": "test1", - "description": "description1", - "state": "opened", - "upvotes": 0, - "downvotes": 0, - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "assignee": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - } -} -``` - -If the operation is successful, 200 and the updated merge request is returned. -If an error occurs, an error number and a message explaining the reason is returned. - -## Accept MR - -Merge changes submitted with MR using this API. - -If merge success you get `200 OK`. - -If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged' - -If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed' - -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 -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of MR -- `merge_commit_message` (optional) - Custom merge commit message - -```json -{ - "id": 1, - "target_branch": "master", - "source_branch": "test1", - "project_id": 3, - "title": "test1", - "state": "merged", - "upvotes": 0, - "downvotes": 0, - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - }, - "assignee": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2012-04-29T08:46:00Z" - } -} -``` - -## Post comment to MR - -Adds a comment to a merge request. - -``` -POST /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request -- `note` (required) - Text of comment - -```json -{ - "author": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "blocked": false, - "created_at": "2012-04-29T08:46:00Z" - }, - "note": "text1" -} -``` - -## Get the comments on a MR - -Gets all the comments associated with a merge request. - -``` -GET /projects/:id/merge_request/:merge_request_id/comments -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - ID of merge request - -```json -[ - { - "note": "this is the 1st comment on the 2merge merge request", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - }, - { - "note": "Status changed to closed", - "author": { - "id": 11, - "username": "admin", - "email": "admin@example.com", - "name": "Administrator", - "state": "active", - "created_at": "2014-03-06T08:17:35.000Z" - } - } -] -``` - -## Comments on issues - -Comments are done via the notes resource. diff --git a/doc/api/milestones.md b/doc/api/milestones.md deleted file mode 100644 index d48b3bcce8a..00000000000 --- a/doc/api/milestones.md +++ /dev/null @@ -1,87 +0,0 @@ -# Milestones - -## List project milestones - -Returns a list of project milestones. - -``` -GET /projects/:id/milestones -``` - -```json -[ - { - "id": 12, - "iid": 3, - "project_id": 16, - "title": "10.0", - "description": "Version", - "due_date": "2013-11-29", - "state": "active", - "updated_at": "2013-10-02T09:24:18Z", - "created_at": "2013-10-02T09:24:18Z" - } -] -``` - -Parameters: - -- `id` (required) - The ID of a project - -## Get single milestone - -Gets a single project milestone. - -``` -GET /projects/:id/milestones/:milestone_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `milestone_id` (required) - The ID of a project milestone - -## Create new milestone - -Creates a new project milestone. - -``` -POST /projects/:id/milestones -``` - -Parameters: - -- `id` (required) - The ID of a project -- `title` (required) - The title of an milestone -- `description` (optional) - The description of the milestone -- `due_date` (optional) - The due date of the milestone - -## Edit milestone - -Updates an existing project milestone. - -``` -PUT /projects/:id/milestones/:milestone_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `milestone_id` (required) - The ID of a project milestone -- `title` (optional) - The title of a milestone -- `description` (optional) - The description of a milestone -- `due_date` (optional) - The due date of the milestone -- `state_event` (optional) - The state event of the milestone (close|activate) - -## Get all issues assigned to a single milestone - -Gets all issues assigned to a single project milestone. - -``` -GET /projects/:id/milestones/:milestone_id/issues -``` - -Parameters: - -- `id` (required) - The ID of a project -- `milestone_id` (required) - The ID of a project milestone diff --git a/doc/api/notes.md b/doc/api/notes.md deleted file mode 100644 index ee2f9fa0eac..00000000000 --- a/doc/api/notes.md +++ /dev/null @@ -1,246 +0,0 @@ -# Notes - -Notes are comments on snippets, issues or merge requests. - -## Issues - -### List project issue notes - -Gets a list of all notes for a single issue. - -``` -GET /projects/:id/issues/:issue_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue - -```json -[ - { - "id": 302, - "body": "Status changed to closed", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z" - }, - "created_at": "2013-10-02T09:22:45Z" - }, - { - "id": 305, - "body": "Text of the comment\r\n", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z" - }, - "created_at": "2013-10-02T09:56:03Z" - } -] -``` - -### Get single issue note - -Returns a single note for a specific project issue - -``` -GET /projects/:id/issues/:issue_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of a project issue -- `note_id` (required) - The ID of an issue note - -### Create new issue note - -Creates a new note to a single project issue. - -``` -POST /projects/:id/issues/:issue_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue -- `body` (required) - The content of a note - -### Modify existing issue note - -Modify existing note of an issue. - -``` -PUT /projects/:id/issues/:issue_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `issue_id` (required) - The ID of an issue -- `note_id` (required) - The ID of a note -- `body` (required) - The content of a note - -## Snippets - -### List all snippet notes - -Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet. - -``` -GET /projects/:id/snippets/:snippet_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project snippet - -### Get single snippet note - -Returns a single note for a given snippet. - -``` -GET /projects/:id/snippets/:snippet_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project snippet -- `note_id` (required) - The ID of an snippet note - -```json -{ - "id": 52, - "title": "Snippet", - "file_name": "snippet.rb", - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z" - }, - "expires_at": null, - "updated_at": "2013-10-02T07:34:20Z", - "created_at": "2013-10-02T07:34:20Z" -} -``` - -### Create new snippet note - -Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet. - -``` -POST /projects/:id/snippets/:snippet_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a snippet -- `body` (required) - The content of a note - -### Modify existing snippet note - -Modify existing note of a snippet. - -``` -PUT /projects/:id/snippets/:snippet_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a snippet -- `note_id` (required) - The ID of a note -- `body` (required) - The content of a note - -## Merge Requests - -### List all merge request notes - -Gets a list of all notes for a single merge request. - -``` -GET /projects/:id/merge_requests/:merge_request_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request - -### Get single merge request note - -Returns a single note for a given merge request. - -``` -GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a project merge request -- `note_id` (required) - The ID of a merge request note - -```json -{ - "id": 301, - "body": "Comment for MR", - "attachment": null, - "author": { - "id": 1, - "username": "pipin", - "email": "admin@example.com", - "name": "Pip", - "state": "active", - "created_at": "2013-09-30T13:46:01Z" - }, - "created_at": "2013-10-02T08:57:14Z" -} -``` - -### Create new merge request note - -Creates a new note for a single merge request. - -``` -POST /projects/:id/merge_requests/:merge_request_id/notes -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request -- `body` (required) - The content of a note - -### Modify existing merge request note - -Modify existing note of a merge request. - -``` -PUT /projects/:id/merge_requests/:merge_request_id/notes/:note_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `merge_request_id` (required) - The ID of a merge request -- `note_id` (required) - The ID of a note -- `body` (required) - The content of a note diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md deleted file mode 100644 index d416a826f79..00000000000 --- a/doc/api/oauth2.md +++ /dev/null @@ -1,102 +0,0 @@ -# GitLab as an OAuth2 client - -This document is about using other OAuth authentication service providers to sign into GitLab. -If you want GitLab to be an OAuth authentication service provider to sign into other services please see the [Oauth2 provider documentation](../integration/oauth_provider.md). - -OAuth2 is a protocol that enables us to authenticate a user without requiring them to give their password. - -Before using the OAuth2 you should create an application in user's account. Each application gets a unique App ID and App Secret parameters. You should not share these. - -This functionality is based on [doorkeeper gem](https://github.com/doorkeeper-gem/doorkeeper) - -## Web Application Flow - -This flow is using for authentication from third-party web sites and is probably used the most. -It basically consists of an exchange of an authorization token for an access token. For more detailed info, check out the [RFC spec here](http://tools.ietf.org/html/rfc6749#section-4.1) - -This flow consists from 3 steps. - -### 1. Registering the client - -Create an application in user's account profile. - -### 2. Requesting authorization - -To request the authorization token, you should visit the `/oauth/authorize` endpoint. You can do that by visiting manually the URL: - -``` -http://localhost:3000/oauth/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&response_type=code -``` - -Where REDIRECT_URI is the URL in your app where users will be sent after authorization. - -### 3. Requesting the access token - -To request the access token, you should use the returned code and exchange it for an access token. To do that you can use any HTTP client. In this case, I used rest-client: - -``` -parameters = 'client_id=APP_ID&client_secret=APP_SECRET&code=RETURNED_CODE&grant_type=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI' -RestClient.post 'http://localhost:3000/oauth/token', parameters - -# The response will be -{ - "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54", - "token_type": "bearer", - "expires_in": 7200, - "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1" -} -``` - -You can now make requests to the API with the access token returned. - -### Use the access token to access the API - -The access token allows you to make requests to the API on a behalf of a user. - -``` -GET https://localhost:3000/api/v3/user?access_token=OAUTH-TOKEN -``` - -Or you can put the token to the Authorization header: - -``` -curl -H "Authorization: Bearer OAUTH-TOKEN" https://localhost:3000/api/v3/user -``` - -## Resource Owner Password Credentials - -In this flow, a token is requested in exchange for the resource owner credentials (username and password). -The credentials should only be used when there is a high degree of trust between the resource owner and the client (e.g. the -client is part of the device operating system or a highly privileged application), and when other authorization grant types are not -available (such as an authorization code). - -Even though this grant type requires direct client access to the resource owner credentials, the resource owner credentials are used -for a single request and are exchanged for an access token. This grant type can eliminate the need for the client to store the -resource owner credentials for future use, by exchanging the credentials with a long-lived access token or refresh token. -You can do POST request to `/oauth/token` with parameters: - -``` -{ - "grant_type" : "password", - "username" : "user@example.com", - "password" : "sekret" -} -``` - -Then, you'll receive the access token back in the response: - -``` -{ - "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa", - "token_type": "bearer", - "expires_in": 7200 -} -``` - -For testing you can use the oauth2 ruby gem: - -``` -client = OAuth2::Client.new('the_client_id', 'the_client_secret', :site => "http://example.com") -access_token = client.password.get_token('user@example.com', 'sekret') -puts access_token.token -``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md deleted file mode 100644 index 50e134847c0..00000000000 --- a/doc/api/project_snippets.md +++ /dev/null @@ -1,103 +0,0 @@ -# Project snippets - -## List snippets - -Get a list of project snippets. - -``` -GET /projects/:id/snippets -``` - -Parameters: - -- `id` (required) - The ID of a project - -## Single snippet - -Get a single project snippet. - -``` -GET /projects/:id/snippets/:snippet_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project's snippet - -```json -{ - "id": 1, - "title": "test", - "file_name": "add.rb", - "author": { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z" - }, - "expires_at": null, - "updated_at": "2012-06-28T10:52:04Z", - "created_at": "2012-06-28T10:52:04Z" -} -``` - -## Create new snippet - -Creates a new project snippet. The user must have permission to create new snippets. - -``` -POST /projects/:id/snippets -``` - -Parameters: - -- `id` (required) - The ID of a project -- `title` (required) - The title of a snippet -- `file_name` (required) - The name of a snippet file -- `code` (required) - The content of a snippet - -## Update snippet - -Updates an existing project snippet. The user must have permission to change an existing snippet. - -``` -PUT /projects/:id/snippets/:snippet_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project's snippet -- `title` (optional) - The title of a snippet -- `file_name` (optional) - The name of a snippet file -- `code` (optional) - The content of a snippet - -## Delete snippet - -Deletes an existing project snippet. This is an idempotent function and deleting a non-existent -snippet still returns a `200 OK` status code. - -``` -DELETE /projects/:id/snippets/:snippet_id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project's snippet - -## Snippet content - -Returns the raw project snippet as plain text. - -``` -GET /projects/:id/snippets/:snippet_id/raw -``` - -Parameters: - -- `id` (required) - The ID of a project -- `snippet_id` (required) - The ID of a project's snippet diff --git a/doc/api/projects.md b/doc/api/projects.md deleted file mode 100644 index 971fe96fb8e..00000000000 --- a/doc/api/projects.md +++ /dev/null @@ -1,713 +0,0 @@ -# Projects - - -### Project visibility level - -Project in GitLab has be either private, internal or public. -You can determine it by `visibility_level` field in project. - -Constants for project visibility levels are next: - -* Private. `visibility_level` is `0`. - Project access must be granted explicitly for each user. - -* Internal. `visibility_level` is `10`. - The project can be cloned by any logged in user. - -* Public. `visibility_level` is `20`. - The project can be cloned without any authentication. - - -## List projects - -Get a list of projects accessible by the authenticated user. - -``` -GET /projects -``` - -Parameters: - -- `archived` (optional) - if passed, limit by archived status -- `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 - -```json -[ - { - "id": 4, - "description": null, - "default_branch": "master", - "public": false, - "visibility_level": 0, - "ssh_url_to_repo": "git@example.com:diaspora/diaspora-client.git", - "http_url_to_repo": "http://example.com/diaspora/diaspora-client.git", - "web_url": "http://example.com/diaspora/diaspora-client", - "tag_list": [ - "example", - "disapora client" - ], - "owner": { - "id": 3, - "name": "Diaspora", - "created_at": "2013-09-30T13: 46: 02Z" - }, - "name": "Diaspora Client", - "name_with_namespace": "Diaspora / Diaspora Client", - "path": "diaspora-client", - "path_with_namespace": "diaspora/diaspora-client", - "issues_enabled": true, - "merge_requests_enabled": true, - "wiki_enabled": true, - "snippets_enabled": false, - "created_at": "2013-09-30T13: 46: 02Z", - "last_activity_at": "2013-09-30T13: 46: 02Z", - "creator_id": 3, - "namespace": { - "created_at": "2013-09-30T13: 46: 02Z", - "description": "", - "id": 3, - "name": "Diaspora", - "owner_id": 1, - "path": "diaspora", - "updated_at": "2013-09-30T13: 46: 02Z" - }, - "archived": false, - "avatar_url": "http://example.com/uploads/project/avatar/4/uploads/avatar.png" - }, - { - "id": 6, - "description": null, - "default_branch": "master", - "public": false, - "visibility_level": 0, - "ssh_url_to_repo": "git@example.com:brightbox/puppet.git", - "http_url_to_repo": "http://example.com/brightbox/puppet.git", - "web_url": "http://example.com/brightbox/puppet", - "tag_list": [ - "example", - "puppet" - ], - "owner": { - "id": 4, - "name": "Brightbox", - "created_at": "2013-09-30T13:46:02Z" - }, - "name": "Puppet", - "name_with_namespace": "Brightbox / Puppet", - "path": "puppet", - "path_with_namespace": "brightbox/puppet", - "issues_enabled": true, - "merge_requests_enabled": true, - "wiki_enabled": true, - "snippets_enabled": false, - "created_at": "2013-09-30T13:46:02Z", - "last_activity_at": "2013-09-30T13:46:02Z", - "creator_id": 3, - "namespace": { - "created_at": "2013-09-30T13:46:02Z", - "description": "", - "id": 4, - "name": "Brightbox", - "owner_id": 1, - "path": "brightbox", - "updated_at": "2013-09-30T13:46:02Z" - }, - "archived": false, - "avatar_url": null - } -] -``` - -### List owned projects - -Get a list of projects which are owned by the authenticated user. - -``` -GET /projects/owned -``` - -Parameters: - -- `archived` (optional) - if passed, limit by archived status -- `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 - -### List ALL projects - -Get a list of all GitLab projects (admin only). - -``` -GET /projects/all -``` - -Parameters: - -- `archived` (optional) - if passed, limit by archived status -- `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 - -### Get single project - -Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user. -If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`). - -``` -GET /projects/:id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - -```json -{ - "id": 3, - "description": null, - "default_branch": "master", - "public": false, - "visibility_level": 0, - "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git", - "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git", - "web_url": "http://example.com/diaspora/diaspora-project-site", - "tag_list": [ - "example", - "disapora project" - ], - "owner": { - "id": 3, - "name": "Diaspora", - "created_at": "2013-09-30T13: 46: 02Z" - }, - "name": "Diaspora Project Site", - "name_with_namespace": "Diaspora / Diaspora Project Site", - "path": "diaspora-project-site", - "path_with_namespace": "diaspora/diaspora-project-site", - "issues_enabled": true, - "merge_requests_enabled": true, - "wiki_enabled": true, - "snippets_enabled": false, - "created_at": "2013-09-30T13: 46: 02Z", - "last_activity_at": "2013-09-30T13: 46: 02Z", - "creator_id": 3, - "namespace": { - "created_at": "2013-09-30T13: 46: 02Z", - "description": "", - "id": 3, - "name": "Diaspora", - "owner_id": 1, - "path": "diaspora", - "updated_at": "2013-09-30T13: 46: 02Z" - }, - "permissions": { - "project_access": { - "access_level": 10, - "notification_level": 3 - }, - "group_access": { - "access_level": 50, - "notification_level": 3 - } - }, - "archived": false, - "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png" -} -``` - -### Get project events - -Get the events for the specified project. -Sorted from newest to latest - -``` -GET /projects/:id/events -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - -```json -[ - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 830, - "target_type": "Issue", - "author_id": 1, - "author_username": "john", - "data": null, - "target_title": "Public project search field" - }, - { - "title": null, - "project_id": 15, - "action_name": "opened", - "target_id": null, - "target_type": null, - "author_id": 1, - "author_username": "john", - "data": { - "before": "50d4420237a9de7be1304607147aec22e4a14af7", - "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "ref": "refs/heads/master", - "user_id": 1, - "user_name": "Dmitriy Zaporozhets", - "repository": { - "name": "gitlabhq", - "url": "git@dev.gitlab.org:gitlab/gitlabhq.git", - "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.", - "homepage": "https://dev.gitlab.org/gitlab/gitlabhq" - }, - "commits": [ - { - "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "message": "Add simple search to projects in public area", - "timestamp": "2013-05-13T18:18:08+00:00", - "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "author": { - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com" - } - } - ], - "total_commits_count": 1 - }, - "target_title": null - }, - { - "title": null, - "project_id": 15, - "action_name": "closed", - "target_id": 840, - "target_type": "Issue", - "author_id": 1, - "author_username": "john", - "data": null, - "target_title": "Finish & merge Code search PR" - } -] -``` - -### Create project - -Creates a new project owned by the authenticated user. - -``` -POST /projects -``` - -Parameters: - -- `name` (required) - new project name -- `path` (optional) - custom repository name for new project. By default generated based on name -- `namespace_id` (optional) - namespace for the new project (defaults to user) -- `description` (optional) - short project description -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) -- `import_url` (optional) - -### Create project for user - -Creates a new project owned by the specified user. Available only for admins. - -``` -POST /projects/user/:user_id -``` - -Parameters: - -- `user_id` (required) - user_id of owner -- `name` (required) - new project name -- `description` (optional) - short project description -- `default_branch` (optional) - 'master' by default -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) -- `import_url` (optional) - -### Edit project - -Updates an existing project - -``` -PUT /projects/:id -``` - -Parameters: - -- `id` (required) - The ID of a project -- `name` (optional) - project name -- `path` (optional) - repository name for project -- `description` (optional) - short project description -- `default_branch` (optional) -- `issues_enabled` (optional) -- `merge_requests_enabled` (optional) -- `wiki_enabled` (optional) -- `snippets_enabled` (optional) -- `public` (optional) - if `true` same as setting visibility_level = 20 -- `visibility_level` (optional) - -On success, method returns 200 with the updated project. If parameters are -invalid, 400 is returned. - -### Fork project - -Forks a project into the user namespace of the authenticated user. - -``` -POST /projects/fork/:id -``` - -Parameters: - -- `id` (required) - The ID of the project to be forked - -### Remove project - -Removes a project including all associated resources (issues, merge requests etc.) - -``` -DELETE /projects/:id -``` - -Parameters: - -- `id` (required) - The ID of a project - -## Team members - -### List project team members - -Get a list of a project's team members. - -``` -GET /projects/:id/members -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `query` (optional) - Query string to search for members - -### Get project team member - -Gets a project team member. - -``` -GET /projects/:id/members/:user_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `user_id` (required) - The ID of a user - -```json -{ - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z", - "access_level": 40 -} -``` - -### Add project team member - -Adds a user to a project team. This is an idempotent method and can be called multiple times -with the same parameters. Adding team membership to a user that is already a member does not -affect the existing membership. - -``` -POST /projects/:id/members -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `user_id` (required) - The ID of a user to add -- `access_level` (required) - Project access level - -### Edit project team member - -Updates a project team member to a specified access level. - -``` -PUT /projects/:id/members/:user_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `user_id` (required) - The ID of a team member -- `access_level` (required) - Project access level - -### Remove project team member - -Removes a user from a project team. - -``` -DELETE /projects/:id/members/:user_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `user_id` (required) - The ID of a team member - -This method is idempotent and can be called multiple times with the same parameters. -Revoking team membership for a user who is not currently a team member is considered success. -Please note that the returned JSON currently differs slightly. Thus you should not -rely on the returned JSON structure. - -## Hooks - -### List project hooks - -Get a list of project hooks. - -``` -GET /projects/:id/hooks -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - -### Get project hook - -Get a specific hook for a project. - -``` -GET /projects/:id/hooks/:hook_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of a project hook - -```json -{ - "id": 1, - "url": "http://example.com/hook", - "project_id": 3, - "push_events": "true", - "issues_events": "true", - "merge_requests_events": "true", - "created_at": "2012-10-12T17:04:47Z" -} -``` - -### Add project hook - -Adds a hook to a specified project. - -``` -POST /projects/:id/hooks -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `url` (required) - The hook URL -- `push_events` - Trigger hook on push events -- `issues_events` - Trigger hook on issues events -- `merge_requests_events` - Trigger hook on merge_requests events -- `tag_push_events` - Trigger hook on push_tag events - -### Edit project hook - -Edits a hook for a specified project. - -``` -PUT /projects/:id/hooks/:hook_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of a project hook -- `url` (required) - The hook URL -- `push_events` - Trigger hook on push events -- `issues_events` - Trigger hook on issues events -- `merge_requests_events` - Trigger hook on merge_requests events -- `tag_push_events` - Trigger hook on push_tag events - -### Delete project hook - -Removes a hook from a project. This is an idempotent method and can be called multiple times. -Either the hook is available or not. - -``` -DELETE /projects/:id/hooks/:hook_id -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `hook_id` (required) - The ID of hook to delete - -Note the JSON response differs if the hook is available or not. If the project hook -is available before it is returned in the JSON response or an empty response is returned. - -## Branches - -### List branches - -Lists all branches of a project. - -``` -GET /projects/:id/repository/branches -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project - -```json -[ - { - "name": "async", - "commit": { - "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca", - "parents": [ - { - "id": "3f94fc7c85061973edc9906ae170cc269b07ca55" - } - ], - "tree": "c68537c6534a02cc2b176ca1549f4ffa190b58ee", - "message": "give Caolan credit where it's due (up top)", - "author": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "committer": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "authored_date": "2010-12-08T21:28:50+00:00", - "committed_date": "2010-12-08T21:28:50+00:00" - }, - "protected": false - }, - { - "name": "gh-pages", - "commit": { - "id": "101c10a60019fe870d21868835f65c25d64968fc", - "parents": [ - { - "id": "9c15d2e26945a665131af5d7b6d30a06ba338aaa" - } - ], - "tree": "fb5cc9d45da3014b17a876ad539976a0fb9b352a", - "message": "Underscore.js 1.5.2", - "author": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "committer": { - "name": "Jeremy Ashkenas", - "email": "jashkenas@example.com" - }, - "authored_date": "2013-09-07T12: 58: 21+00: 00", - "committed_date": "2013-09-07T12: 58: 21+00: 00" - }, - "protected": false - } -] -``` - -### List single branch - -Lists a specific branch of a project. - -``` -GET /projects/:id/repository/branches/:branch -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. - -### Protect single branch - -Protects a single branch of a project. - -``` -PUT /projects/:id/repository/branches/:branch/protect -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. - -### Unprotect single branch - -Unprotects a single branch of a project. - -``` -PUT /projects/:id/repository/branches/:branch/unprotect -``` - -Parameters: - -- `id` (required) - The ID or NAMESPACE/PROJECT_NAME of a project -- `branch` (required) - The name of the branch. - -## Admin fork relation - -Allows modification of the forked relationship between existing projects. Available only for admins. - -### Create a forked from/to relation between existing projects. - -``` -POST /projects/:id/fork/:forked_from_id -``` - -Parameters: - -- `id` (required) - The ID of the project -- `forked_from_id:` (required) - The ID of the project that was forked from - -### Delete an existing forked from relationship - -``` -DELETE /projects/:id/fork -``` - -Parameter: - -- `id` (required) - The ID of the project - -## Search for projects by name - -Search for projects by name which are accessible to the authenticated user. - -``` -GET /projects/search/:query -``` - -Parameters: - -- `query` (required) - A string contained in the project name -- `per_page` (optional) - number of projects to return per page -- `page` (optional) - the page to retrieve -- `order_by` (optional) - Return requests ordered by `id`, `name`, `created_at` or `last_activity_at` fields -- `sort` (optional) - Return requests sorted in `asc` or `desc` order diff --git a/doc/api/repositories.md b/doc/api/repositories.md deleted file mode 100644 index 33167453802..00000000000 --- a/doc/api/repositories.md +++ /dev/null @@ -1,252 +0,0 @@ -# Repositories - -## List project repository tags - -Get a list of repository tags from a project, sorted by name in reverse alphabetical order. - -``` -GET /projects/:id/repository/tags -``` - -Parameters: - -- `id` (required) - The ID of a project - -```json -[ - { - "commit": { - "author_name": "John Smith", - "author_email": "john@example.com", - "authored_date": "2012-05-28T04:42:42-07:00", - "committed_date": "2012-05-28T04:42:42-07:00", - "committer_name": "Jack Smith", - "committer_email": "jack@example.com", - "id": "2695effb5807a22ff3d138d593fd856244e155e7", - "message": "Initial commit", - "parents_ids": [ - "2a4b78934375d7f53875269ffd4f45fd83a84ebe" - ] - }, - "name": "v1.0.0", - "message": null - } -] -``` - -## Create a new tag - -Creates new tag in the repository that points to the supplied ref. - -``` -POST /projects/:id/repository/tags -``` - -Parameters: - -- `id` (required) - The ID of a project -- `tag_name` (required) - The name of a tag -- `ref` (required) - Create tag using commit SHA, another tag name, or branch name. -- `message` (optional) - Creates annotated tag. - -```json -{ - "commit": { - "author_name": "John Smith", - "author_email": "john@example.com", - "authored_date": "2012-05-28T04:42:42-07:00", - "committed_date": "2012-05-28T04:42:42-07:00", - "committer_name": "Jack Smith", - "committer_email": "jack@example.com", - "id": "2695effb5807a22ff3d138d593fd856244e155e7", - "message": "Initial commit", - "parents_ids": [ - "2a4b78934375d7f53875269ffd4f45fd83a84ebe" - ] - }, - "name": "v1.0.0", - "message": null -} -``` -The message will be `nil` when creating a lightweight tag otherwise -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. - -## List repository tree - -Get a list of repository files and directories in a project. - -``` -GET /projects/:id/repository/tree -``` - -Parameters: - -- `id` (required) - The ID of a project -- `path` (optional) - The path inside repository. Used to get contend of subdirectories -- `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch - -```json -[ - { - "name": "assets", - "type": "tree", - "mode": "040000", - "id": "6229c43a7e16fcc7e95f923f8ddadb8281d9c6c6" - }, - { - "name": "contexts", - "type": "tree", - "mode": "040000", - "id": "faf1cdf33feadc7973118ca42d35f1e62977e91f" - }, - { - "name": "controllers", - "type": "tree", - "mode": "040000", - "id": "95633e8d258bf3dfba3a5268fb8440d263218d74" - }, - { - "name": "Rakefile", - "type": "blob", - "mode": "100644", - "id": "35b2f05cbb4566b71b34554cf184a9d0bd9d46d6" - }, - { - "name": "VERSION", - "type": "blob", - "mode": "100644", - "id": "803e4a4f3727286c3093c63870c2b6524d30ec4f" - }, - { - "name": "config.ru", - "type": "blob", - "mode": "100644", - "id": "dfd2d862237323aa599be31b473d70a8a817943b" - } -] -``` - -## Raw file content - -Get the raw file contents for a file by commit SHA and path. - -``` -GET /projects/:id/repository/blobs/:sha -``` - -Parameters: - -- `id` (required) - The ID of a project -- `sha` (required) - The commit or branch name -- `filepath` (required) - The path the file - -## Raw blob content - -Get the raw file contents for a blob by blob SHA. - -``` -GET /projects/:id/repository/raw_blobs/:sha -``` - -Parameters: - -- `id` (required) - The ID of a project -- `sha` (required) - The blob SHA - -## Get file archive - -Get an archive of the repository - -``` -GET /projects/:id/repository/archive -``` - -Parameters: - -- `id` (required) - The ID of a project -- `sha` (optional) - The commit SHA to download defaults to the tip of the default branch - -## Compare branches, tags or commits - -``` -GET /projects/:id/repository/compare -``` - -Parameters: - -- `id` (required) - The ID of a project -- `from` (required) - the commit SHA or branch name -- `to` (required) - the commit SHA or branch name - -``` -GET /projects/:id/repository/compare?from=master&to=feature -``` - -Response: - -```json - -{ - "commit": { - "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1", - "short_id": "12d65c8dd2b", - "title": "JS fix", - "author_name": "Dmitriy Zaporozhets", - "author_email": "dmitriy.zaporozhets@gmail.com", - "created_at": "2014-02-27T10:27:00+02:00" - }, - "commits": [{ - "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1", - "short_id": "12d65c8dd2b", - "title": "JS fix", - "author_name": "Dmitriy Zaporozhets", - "author_email": "dmitriy.zaporozhets@gmail.com", - "created_at": "2014-02-27T10:27:00+02:00" - }], - "diffs": [{ - "old_path": "files/js/application.js", - "new_path": "files/js/application.js", - "a_mode": null, - "b_mode": "100644", - "diff": "--- a/files/js/application.js\n+++ b/files/js/application.js\n@@ -24,8 +24,10 @@\n //= require g.raphael-min\n //= require g.bar-min\n //= require branch-graph\n-//= require highlightjs.min\n-//= require ace/ace\n //= require_tree .\n //= require d3\n //= require underscore\n+\n+function fix() { \n+ alert(\"Fixed\")\n+}", - "new_file": false, - "renamed_file": false, - "deleted_file": false - }], - "compare_timeout": false, - "compare_same_ref": false -} -``` - -## Contributors - -Get repository contributors list - -``` -GET /projects/:id/repository/contributors -``` - -Parameters: - -- `id` (required) - The ID of a project - -Response: - -``` -[{ - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com", - "commits": 117, - "additions": 2097, - "deletions": 517 -}, { - "name": "Jacob Vosmaer", - "email": "contact@jacobvosmaer.nl", - "commits": 33, - "additions": 338, - "deletions": 244 -}] -``` diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md deleted file mode 100644 index 25311b07107..00000000000 --- a/doc/api/repository_files.md +++ /dev/null @@ -1,109 +0,0 @@ -# Repository files - -**CRUD for repository files** - -**Create, read, update and delete repository files using this API** - -## Get file from repository - -Allows you to receive information about file in repository like name, size, content. Note that file content is Base64 encoded. - -``` -GET /projects/:id/repository/files -``` - -Example response: - -```json -{ - "file_name": "key.rb", - "file_path": "app/models/key.rb", - "size": 1476, - "encoding": "base64", - "content": "IyA9PSBTY2hlbWEgSW5mb3...", - "ref": "master", - "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83", - "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50" -} -``` - -Parameters: - -- `file_path` (required) - Full path to new file. Ex. lib/class.rb -- `ref` (required) - The name of branch, tag or commit - -## Create new file in repository - -``` -POST /projects/:id/repository/files -``` - -Example response: - -```json -{ - "file_name": "app/project.rb", - "branch_name": "master" -} -``` - -Parameters: - -- `file_path` (required) - Full path to new file. Ex. lib/class.rb -- `branch_name` (required) - The name of branch -- `encoding` (optional) - 'text' or 'base64'. Text is default. -- `content` (required) - File content -- `commit_message` (required) - Commit message - -## Update existing file in repository - -``` -PUT /projects/:id/repository/files -``` - -Example response: - -```json -{ - "file_name": "app/project.rb", - "branch_name": "master" -} -``` - -Parameters: - -- `file_path` (required) - Full path to file. Ex. lib/class.rb -- `branch_name` (required) - The name of branch -- `encoding` (optional) - 'text' or 'base64'. Text is default. -- `content` (required) - New file content -- `commit_message` (required) - Commit message - -If the commit fails for any reason we return a 400 error with a non-specific -error message. Possible causes for a failed commit include: -- the `file_path` contained `/../` (attempted directory traversal); -- the new file contents were identical to the current file contents, i.e. the - user tried to make an empty commit; -- the branch was updated by a Git push while the file edit was in progress. - -Currently gitlab-shell has a boolean return code, preventing GitLab from specifying the error. - -## Delete existing file in repository - -``` -DELETE /projects/:id/repository/files -``` - -Example response: - -```json -{ - "file_name": "app/project.rb", - "branch_name": "master" -} -``` - -Parameters: - -- `file_path` (required) - Full path to file. Ex. lib/class.rb -- `branch_name` (required) - The name of branch -- `commit_message` (required) - Commit message diff --git a/doc/api/services.md b/doc/api/services.md deleted file mode 100644 index cbf767d1b25..00000000000 --- a/doc/api/services.md +++ /dev/null @@ -1,46 +0,0 @@ -# Services - -## GitLab CI - -### Edit GitLab CI service - -Set GitLab CI service for a project. - -``` -PUT /projects/:id/services/gitlab-ci -``` - -Parameters: - -- `token` (required) - CI project token -- `project_url` (required) - CI project URL - -### Delete GitLab CI service - -Delete GitLab CI service settings for a project. - -``` -DELETE /projects/:id/services/gitlab-ci -``` - -## HipChat - -### Edit HipChat service - -Set HipChat service for project. - -``` -PUT /projects/:id/services/hipchat -``` -Parameters: - -- `token` (required) - HipChat token -- `room` (required) - HipChat room name - -### Delete HipChat service - -Delete HipChat service for a project. - -``` -DELETE /projects/:id/services/hipchat -``` diff --git a/doc/api/session.md b/doc/api/session.md deleted file mode 100644 index 47c1c8a7a49..00000000000 --- a/doc/api/session.md +++ /dev/null @@ -1,39 +0,0 @@ -# Session - -Login to get private token - -``` -POST /session -``` - -Parameters: - -- `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** - - -```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", - "bio": null, - "skype": "", - "linkedin": "", - "twitter": "", - "website_url": "", - "dark_scheme": false, - "theme_id": 1, - "is_admin": false, - "can_create_group": true, - "can_create_team": true, - "can_create_project": true -} -``` diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md deleted file mode 100644 index f9637d8a6c4..00000000000 --- a/doc/api/system_hooks.md +++ /dev/null @@ -1,70 +0,0 @@ -# System hooks - -All methods require admin authorization. - -The URL endpoint of the system hooks can be configured in [the admin area under hooks](/admin/hooks). - -## List system hooks - -Get list of system hooks - -``` -GET /hooks -``` - -Parameters: - -- **none** - -```json -[ - { - "id": 3, - "url": "http://example.com/hook", - "created_at": "2013-10-02T10:15:31Z" - } -] -``` - -## Add new system hook hook - -``` -POST /hooks -``` - -Parameters: - -- `url` (required) - The hook URL - -## Test system hook - -``` -GET /hooks/:id -``` - -Parameters: - -- `id` (required) - The ID of hook - -```json -{ - "event_name": "project_create", - "name": "Ruby", - "path": "ruby", - "project_id": 1, - "owner_name": "Someone", - "owner_email": "example@gitlabhq.com" -} -``` - -## 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. - -``` -DELETE /hooks/:id -``` - -Parameters: - -- `id` (required) - The ID of hook diff --git a/doc/api/users.md b/doc/api/users.md deleted file mode 100644 index a8b7685b503..00000000000 --- a/doc/api/users.md +++ /dev/null @@ -1,394 +0,0 @@ -# Users - -## List users - -Get a list of users. - -This function takes pagination parameters `page` and `per_page` to restrict the list of users. - -### For normal users - -``` -GET /users -``` - -```json -[ - { - "id": 1, - "username": "john_smith", - "name": "John Smith", - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", - }, - { - "id": 2, - "username": "jack_smith", - "name": "Jack Smith", - "state": "blocked", - "avatar_url": "http://gravatar.com/../e32131cd8.jpeg", - } -] -``` - -### For admins - -``` -GET /users -``` - -```json -[ - { - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z", - "bio": null, - "skype": "", - "linkedin": "", - "twitter": "", - "website_url": "", - "extern_uid": "john.smith", - "provider": "provider_name", - "theme_id": 1, - "color_scheme_id": 2, - "is_admin": false, - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", - "can_create_group": true - }, - { - "id": 2, - "username": "jack_smith", - "email": "jack@example.com", - "name": "Jack Smith", - "state": "blocked", - "created_at": "2012-05-23T08:01:01Z", - "bio": null, - "skype": "", - "linkedin": "", - "twitter": "", - "website_url": "", - "extern_uid": "jack.smith", - "provider": "provider_name", - "theme_id": 1, - "color_scheme_id": 3, - "is_admin": false, - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", - "can_create_group": true, - "can_create_project": true, - "projects_limit": 100 - } -] -``` - -You can search for users by email or username with: `/users?search=John` - -Also see `def search query` in `app/models/user.rb`. - -## Single user - -Get a single user. - -### For user - -``` -GET /users/:id -``` - -Parameters: - -- `id` (required) - The ID of a user - -```json -{ - "id": 1, - "username": "john_smith", - "name": "John Smith", - "state": "active", - "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", -} -``` - -### For admin - -``` -GET /users/:id -``` - -Parameters: - -- `id` (required) - The ID of a user - -```json -{ - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "state": "active", - "created_at": "2012-05-23T08:00:58Z", - "bio": null, - "skype": "", - "linkedin": "", - "twitter": "", - "website_url": "", - "extern_uid": "john.smith", - "provider": "provider_name", - "theme_id": 1, - "color_scheme_id": 2, - "is_admin": false, - "can_create_group": true, - "can_create_project": true, - "projects_limit": 100 -} -``` - -## User creation - -Creates a new user. Note only administrators can create new users. - -``` -POST /users -``` - -Parameters: - -- `email` (required) - Email -- `password` (required) - Password -- `username` (required) - Username -- `name` (required) - Name -- `skype` (optional) - Skype ID -- `linkedin` (optional) - LinkedIn -- `twitter` (optional) - Twitter account -- `website_url` (optional) - Website URL -- `projects_limit` (optional) - Number of projects user can create -- `extern_uid` (optional) - External UID -- `provider` (optional) - External provider name -- `bio` (optional) - User's biography -- `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 - -## User modification - -Modifies an existing user. Only administrators can change attributes of a user. - -``` -PUT /users/:id -``` - -Parameters: - -- `email` - Email -- `username` - Username -- `name` - Name -- `password` - Password -- `skype` - Skype ID -- `linkedin` - LinkedIn -- `twitter` - Twitter account -- `website_url` - Website URL -- `projects_limit` - Limit projects each user can create -- `extern_uid` - External UID -- `provider` - External provider name -- `bio` - User's biography -- `admin` (optional) - User is admin - true or false (default) -- `can_create_group` (optional) - User can create groups - true or false - -Note, at the moment this method does only return a 404 error, -even in cases where a 409 (Conflict) would be more appropriate, -e.g. when renaming the email address to some existing one. - -## User deletion - -Deletes a user. Available only for administrators. -This is an idempotent function, calling this function for a non-existent user id -still returns a status code `200 OK`. -The JSON response differs if the user was actually deleted or not. -In the former the user is returned and in the latter not. - -``` -DELETE /users/:id -``` - -Parameters: - -- `id` (required) - The ID of the user - -## Current user - -Gets currently authenticated user. - -``` -GET /user -``` - -```json -{ - "id": 1, - "username": "john_smith", - "email": "john@example.com", - "name": "John Smith", - "private_token": "dd34asd13as", - "state": "active", - "created_at": "2012-05-23T08:00:58Z", - "bio": null, - "skype": "", - "linkedin": "", - "twitter": "", - "website_url": "", - "theme_id": 1, - "color_scheme_id": 2, - "is_admin": false, - "can_create_group": true, - "can_create_project": true, - "projects_limit": 100 -} -``` - -## List SSH keys - -Get a list of currently authenticated user's SSH keys. - -``` -GET /user/keys -``` - -```json -[ - { - "id": 1, - "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2014-08-01T14:47:39.080Z" - }, - { - "id": 3, - "title": "Another Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2014-08-01T14:47:39.080Z" - } -] -``` - -Parameters: - -- **none** - -## List SSH keys for user - -Get a list of a specified user's SSH keys. Available only for admin - -``` -GET /users/:uid/keys -``` - -Parameters: - -- `uid` (required) - id of specified user - -## Single SSH key - -Get a single key. - -``` -GET /user/keys/:id -``` - -Parameters: - -- `id` (required) - The ID of an SSH key - -```json -{ - "id": 1, - "title": "Public key", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", - "created_at": "2014-08-01T14:47:39.080Z" -} -``` - -## Add SSH key - -Creates a new key owned by the currently authenticated user. - -``` -POST /user/keys -``` - -Parameters: - -- `title` (required) - new SSH Key's title -- `key` (required) - new SSH key - -```json -{ - "created_at": "2015-01-21T17:44:33.512Z", - "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call", - "title": "ABC", - "id": 4 -} -``` - -Will return created key with status `201 Created` on success. If an -error occurs a `400 Bad Request` is returned with a message explaining the error: - -```json -{ - "message": { - "fingerprint": [ - "has already been taken" - ], - "key": [ - "has already been taken" - ] - } -} -``` - -## Add SSH key for user - -Create new key owned by specified user. Available only for admin - -``` -POST /users/:id/keys -``` - -Parameters: - -- `id` (required) - id of specified user -- `title` (required) - new SSH Key's title -- `key` (required) - new SSH key - -Will return created key with status `201 Created` on success, or `404 Not found` on fail. - -## Delete SSH key for current user - -Deletes key owned by currently authenticated user. -This is an idempotent function and calling it on a key that is already deleted -or not available results in `200 OK`. - -``` -DELETE /user/keys/:id -``` - -Parameters: - -- `id` (required) - SSH key ID - -## Delete SSH key for given user - -Deletes key owned by a specified user. Available only for admin. - -``` -DELETE /users/:uid/keys/:id -``` - -Parameters: - -- `uid` (required) - id of specified user -- `id` (required) - SSH key ID - -Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found. diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md deleted file mode 100644 index aa65a082a53..00000000000 --- a/doc/customization/issue_closing.md +++ /dev/null @@ -1,36 +0,0 @@ -# Issue closing pattern - -If a commit message matches the regular expression below, all issues referenced from -the matched text will be closed. This happens when the commit is pushed or merged -into the default branch of a project. - -When not specified, the default issue_closing_pattern as shown below will be used: - -```bash -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?#\d+(?:(?:, *| +and +)?))+) -``` - -For example: - -``` -git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes #22). This commit is also related to #17 and fixes #18, #19 and #23." -``` - -will close `#20`, `#21`, `#22`, `#18`, `#19` and `#23`, but `#17` won't be closed -as it does not match the pattern. It also works with multiline commit messages. - -Tip: you can test this closing pattern at [http://rubular.com][1]. Use this site -to test your own patterns. - -## Change the pattern - -For Omnibus installs you can change the default pattern in `/etc/gitlab/gitlab.rb`: - -``` -issue_closing_pattern: '((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?#\d+(?:(?:, *| +and +)?))+)' -``` - -For manual installs you can customize the pattern in [gitlab.yml][0]. - -[0]: https://gitlab.com/gitlab-org/gitlab-ce/blob/40c3675372320febf5264061c9bcd63db2dfd13c/config/gitlab.yml.example#L65 -[1]: http://rubular.com/r/Xmbexed1OJ diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md deleted file mode 100644 index ee57fdc6590..00000000000 --- a/doc/customization/libravatar.md +++ /dev/null @@ -1,69 +0,0 @@ -# Use Libravatar service with GitLab - -GitLab by default supports [Gravatar](gravatar.com) avatar service. -Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is -[heavily based on gravatar](http://wiki.libravatar.org/api/). - -This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server. - -# Configuration - -In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set -the configuration options as follows: - -## For HTTP - -```yml - gravatar: - enabled: true - # gravatar URLs: possible placeholders: %{hash} %{size} %{email} - plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -## For HTTPS - -```yml - gravatar: - enabled: true - # gravatar URLs: possible placeholders: %{hash} %{size} %{email} - ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -## Self-hosted - -If you are [running your own libravatar service](http://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration -but the important part is to provide the same placeholders so GitLab can parse the URL correctly. - -For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is - -`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` - - -## Omnibus-gitlab example - -In `/etc/gitlab/gitlab.rb`: - -#### For http - -```ruby -gitlab_rails['gravatar_enabled'] = true -gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - -#### For https - -```ruby -gitlab_rails['gravatar_enabled'] = true -gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" -``` - - -Run `sudo gitlab-ctl reconfigure` for changes to take effect. - - -## Default URL for missing images - -[Libravatar supports different sets](http://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service. - -In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set. -For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md deleted file mode 100644 index 6c141d1fb7a..00000000000 --- a/doc/customization/welcome_message.md +++ /dev/null @@ -1,38 +0,0 @@ -# Customize the complete sign-in page (GitLab Enterprise Edition only) - -Please see [Branded login page](http://doc.gitlab.com/ee/customization/branded_login_page.html) - -# 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. - -## Omnibus-gitlab example - -In `/etc/gitlab/gitlab.rb`: - -```ruby -gitlab_rails['extra_sign_in_text'] = <<'EOS' -# ACME GitLab -Welcome to the [ACME](http://www.example.com) GitLab server! -EOS -``` - -Run `sudo gitlab-ctl reconfigure` for changes to take effect. - -## Installation from source - -In `/home/git/gitlab/config/gitlab.yml`: - -```yaml -# snip -production: - # snip - extra: - sign_in_text: | - # ACME GitLab - Welcome to the [ACME](http://www.example.com) GitLab server! -``` - -Run `sudo service gitlab reload` for the change to take effect. diff --git a/doc/development/README.md b/doc/development/README.md deleted file mode 100644 index d5d264be19d..00000000000 --- a/doc/development/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# 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 -- [Sidekiq debugging](sidekiq_debugging.md) -- [UI guide](ui_guide.md) for building GitLab with existing css styles and elements diff --git a/doc/development/architecture.md b/doc/development/architecture.md deleted file mode 100644 index 541af487bb1..00000000000 --- a/doc/development/architecture.md +++ /dev/null @@ -1,188 +0,0 @@ -# GitLab Architecture Overview - -## Software delivery - -There are two editions of GitLab: [Enterprise Edition](https://about.gitlab.com/gitlab-ee/) (EE) and [Community Edition](https://about.gitlab.com/gitlab-ce/) (CE). GitLab CE is delivered via git from the [gitlabhq repository](https://gitlab.com/gitlab-org/gitlab-ce/tree/master). New versions of GitLab are released in stable branches and the master branch is for bleeding edge development. - -EE releases are available not long after CE releases. To obtain the GitLab EE there is a [repository at gitlab.com](https://gitlab.com/subscribers/gitlab-ee). For more information about the release process see the section 'New versions and upgrading' in the readme. - -Both EE and CE require an add-on component called gitlab-shell. It is obtained from the [gitlab-shell repository](https://gitlab.com/gitlab-org/gitlab-shell/tree/master). New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical. - -## Physical office analogy - -You can imagine GitLab as a physical office. - -**The repositories** are the goods GitLab handling. -They can be stored in a warehouse. -This can be either a hard disk, or something more complex, such as a NFS filesystem; - -**Nginx** acts like the front-desk. -Users come to Nginx and request actions to be done by workers in the office; - -**The database** is a series of metal file cabinets with information on: - - The goods in the warehouse (metadata, issues, merge requests etc); - - The users coming to the front desk (permissions) - -**Redis** is a communication board with “cubby holes” that can contain tasks for office workers; - -**Sidekiq** is a worker that primarily handles sending out emails. -It takes tasks from the Redis communication board; - -**A Unicorn worker** is a worker that handles quick/mundane tasks. -They work with the communication board (Redis). -Their job description: - - check permissions by checking the user session stored in a Redis “cubby hole”; - - make tasks for Sidekiq; - - fetch stuff from the warehouse or move things around in there; - -**Gitlab-shell** is a third kind of worker that takes orders from a fax machine (SSH) instead of the front desk (HTTP). -Gitlab-shell communicates with Sidekiq via the “communication board” (Redis), and asks quick questions of the Unicorn workers either directly or via the front desk. - -**GitLab Enterprise Edition (the application)** is the collection of processes and business practices that the office is run by. - -## System Layout - -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). - -The bare repositories are located in `/home/git/repositories`. GitLab is a ruby on rails application so the particulars of the inner workings can be learned by studying how a ruby on rails application works. - -To serve repositories over SSH there's an add-on application called gitlab-shell which is installed in `/home/git/gitlab-shell`. - -### Components - - - -A typical install of GitLab will be on GNU/Linux. It uses Nginx or Apache as a web front end to proxypass the Unicorn web server. By default, communication between Unicorn and the front end is via a Unix domain socket but forwarding requests via TCP is also supported. The web front end accesses `/home/git/gitlab/public` bypassing the Unicorn server to serve static pages, uploads (e.g. avatar images or attachments), and precompiled assets. GitLab serves web pages and a [GitLab API](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/api) using the Unicorn web server. It uses Sidekiq as a job queue which, in turn, uses redis as a non-persistent database backend for job information, meta data, and incoming jobs. - -The GitLab web app uses MySQL or PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository. `/home/git/gitlab-satellites` keeps checked out repositories when performing actions such as a merge request, editing files in the web interface, etc. - -The satellite repository is used by the web interface for editing repositories and the wiki which is also a git repository. When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving git objects. - -The add-on component gitlab-shell serves repositories over SSH. It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited. gitlab-shell accesses the bare repositories directly to serve git objects and communicates with redis to submit jobs to Sidekiq for GitLab to process. gitlab-shell queries the GitLab API to determine authorization and access. - -### Installation Folder Summary - -To summarize here's the [directory structure of the `git` user home directory](../install/structure.md). - -### Processes - - ps aux | grep '^git' - -GitLab has several components to operate. As a system user (i.e. any user that is not the `git` user) it requires a persistent database (MySQL/PostreSQL) and redis database. It also uses Apache httpd or Nginx to proxypass Unicorn. As the `git` user it starts Sidekiq and Unicorn (a simple ruby HTTP server running on port `8080` by default). Under the GitLab user there are normally 4 processes: `unicorn_rails master` (1 process), `unicorn_rails worker` (2 processes), `sidekiq` (1 process). - -### Repository access - -Repositories get accessed via HTTP or SSH. HTTP cloning/push/pull utilizes the GitLab API and SSH cloning is handled by gitlab-shell (previously explained). - -## Troubleshooting - -See the README for more information. - -### Init scripts of the services - -The GitLab init script starts and stops Unicorn and Sidekiq. - -``` -/etc/init.d/gitlab -Usage: service gitlab {start|stop|restart|reload|status} -``` - -Redis (key-value store/non-persistent database) - -``` -/etc/init.d/redis -Usage: /etc/init.d/redis {start|stop|status|restart|condrestart|try-restart} -``` - -SSH daemon - -``` -/etc/init.d/sshd -Usage: /etc/init.d/sshd {start|stop|restart|reload|force-reload|condrestart|try-restart|status} -``` - -Web server (one of the following) - -``` -/etc/init.d/httpd -Usage: httpd {start|stop|restart|condrestart|try-restart|force-reload|reload|status|fullstatus|graceful|help|configtest} - -$ /etc/init.d/nginx -Usage: nginx {start|stop|restart|reload|force-reload|status|configtest} -``` - -Persistent database (one of the following) - -``` -/etc/init.d/mysqld -Usage: /etc/init.d/mysqld {start|stop|status|restart|condrestart|try-restart|reload|force-reload} - -$ /etc/init.d/postgresql -Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [version ..] -``` - -### Log locations of the services - -Note: `/home/git/` is shorthand for `/home/git`. - -gitlabhq (includes Unicorn and Sidekiq logs) - -- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `githost.log`, `satellites.log`, and `unicorn.stderr.log` normally. - -gitlab-shell - -- `/home/git/gitlab-shell/gitlab-shell.log` - -ssh - -- `/var/log/auth.log` auth log (on Ubuntu). -- `/var/log/secure` auth log (on RHEL). - -nginx - -- `/var/log/nginx/` contains error and access logs. - -Apache httpd - -- [Explanation of Apache logs](http://httpd.apache.org/docs/2.2/logs.html). -- `/var/log/apache2/` contains error and output logs (on Ubuntu). -- `/var/log/httpd/` contains error and output logs (on RHEL). - -redis - -- `/var/log/redis/redis.log` there are also log-rotated logs there. - -PostgreSQL - -- `/var/log/postgresql/*` - -MySQL - -- `/var/log/mysql/*` -- `/var/log/mysql.*` - -### GitLab specific config files - -GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced config files include: - -- `gitlab.yml` - GitLab configuration. -- `unicorn.rb` - Unicorn web server settings. -- `database.yml` - Database connection settings. - -gitlab-shell has a configuration file at `/home/git/gitlab-shell/config.yml`. - -### Maintenance Tasks - -[GitLab](https://gitlab.com/gitlab-org/gitlab-ce/tree/master) provides rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance rake tasks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/raketasks/maintenance.md). -In a nutshell, do the following: - -``` -sudo -i -u git -cd gitlab -bundle exec rake gitlab:env:info RAILS_ENV=production -bundle exec rake gitlab:check RAILS_ENV=production -``` - -Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While the sudo commands provided by gitlabhq work in Ubuntu they do not always work in RHEL. diff --git a/doc/development/ci_setup.md b/doc/development/ci_setup.md deleted file mode 100644 index f9b48868182..00000000000 --- a/doc/development/ci_setup.md +++ /dev/null @@ -1,46 +0,0 @@ -# CI setup - -This document describes what services we use for testing GitLab and GitLab CI. - -We currently use three CI services to test GitLab: - -1. GitLab CI on [GitHost.io](https://gitlab-ce.githost.io/projects/4/) for the [GitLab.com repo](https://gitlab.com/gitlab-org/gitlab-ce) -2. GitLab CI at ci.gitlab.org to test the private GitLab B.V. repo at dev.gitlab.org -3. [Semephore](https://semaphoreapp.com/gitlabhq/gitlabhq/) for [GitHub.com repo](https://github.com/gitlabhq/gitlabhq) - -| Software @ configuration being tested | GitLab CI (ci.gitlab.org) | GitLab CI (GitHost.io) | Semaphore | -|---------------------------------------|---------------------------|---------------------------------------------------------------------------|-----------| -| GitLab CE @ MySQL | ✓ | ✓ [Core team can trigger builds](https://gitlab-ce.githost.io/projects/4) | | -| GitLab CE @ PostgreSQL | | | ✓ [Core team can trigger builds](https://semaphoreapp.com/gitlabhq/gitlabhq/branches/master) | -| GitLab EE @ MySQL | ✓ | | | -| GitLab CI @ MySQL | ✓ | | | -| GitLab CI @ PostgreSQL | | | ✓ | -| GitLab CI Runner | ✓ | | ✓ | -| GitLab Shell | ✓ | | ✓ | -| GitLab Shell | ✓ | | ✓ | - -Core team has access to trigger builds if needed for GitLab CE. - -We use [these build scripts](https://gitlab.com/gitlab-org/gitlab-ci/blob/master/doc/examples/build_script_gitlab_ce.md) for testing with GitLab CI. - -# 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 -- database.yml: pg - -Build commands - -```bash -sudo apt-get install cmake libicu-dev -y (Setup) -bundle install --deployment --path vendor/bundle (Setup) -cp config/gitlab.yml.example config/gitlab.yml (Setup) -bundle exec rake db:create (Setup) -bundle exec rake spinach (Thread #1) -bundle exec rake spec (thread #2) -bundle exec rake rubocop (thread #3) -bundle exec rake brakeman (thread #4) -bundle exec rake jasmine:ci (thread #5) -``` - -Use rubygems mirror. diff --git a/doc/development/gitlab_diagram_overview.odg b/doc/development/gitlab_diagram_overview.odg Binary files differdeleted file mode 100644 index 9bfc7313ff4..00000000000 --- a/doc/development/gitlab_diagram_overview.odg +++ /dev/null diff --git a/doc/development/gitlab_diagram_overview.png b/doc/development/gitlab_diagram_overview.png Binary files differdeleted file mode 100644 index d9b9eed3d8f..00000000000 --- a/doc/development/gitlab_diagram_overview.png +++ /dev/null diff --git a/doc/development/omnibus.md b/doc/development/omnibus.md deleted file mode 100644 index 0ba354d28a2..00000000000 --- a/doc/development/omnibus.md +++ /dev/null @@ -1,32 +0,0 @@ -# What you should know about omnibus packages - -Most users install GitLab using our omnibus packages. As a developer it can be -good to know how the omnibus packages differ from what you have on your laptop -when you are coding. - -## Files are owned by root by default - -All the files in the Rails tree (`app/`, `config/` etc.) are owned by 'root' in -omnibus installations. This makes the installation simpler and it provides -extra security. The omnibus reconfigure script contains commands that give -write access to the 'git' user only where needed. - -For example, the 'git' user is allowed to write in the `log/` directory, in -`public/uploads`, and they are allowed to rewrite the `db/schema.rb` file. - -In other cases, the reconfigure script tricks GitLab into not trying to write a -file. For instance, GitLab will generate a `.secret` file if it cannot find one -and write it to the Rails root. In the omnibus packages, reconfigure writes the -`.secret` file first, so that GitLab never tries to write it. - -## Code, data and logs are in separate directories - -The omnibus design separates code (read-only, under `/opt/gitlab`) from data -(read/write, under `/var/opt/gitlab`) and logs (read/write, under -`/var/log/gitlab`). To make this happen the reconfigure script sets custom -paths where it can in GitLab config files, and where there are no path -settings, it uses symlinks. - -For example, `config/gitlab.yml` is treated as data so that file is a symlink. -The same goes for `public/uploads`. The `log/` directory is replaced by omnibus -with a symlink to `/var/log/gitlab/gitlab-rails`. diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md deleted file mode 100644 index 53f8095cb13..00000000000 --- a/doc/development/rake_tasks.md +++ /dev/null @@ -1,29 +0,0 @@ -# Rake tasks for developers - -## Setup db with developer seeds - -Note that if your db user does not have advanced privileges you must create the db manually before running this command. - -``` -bundle exec rake setup -``` - -The `setup` task is a alias for `gitlab:setup`. -This tasks calls `db:setup` to create the database, calls `add_limits_mysql` that adds limits to the database schema in case of a MySQL database and fianlly it calls `db:seed_fu` to seed the database. -Note: `db:setup` calls `db:seed` but this does nothing. - -## Run tests - -This runs all test suites present in GitLab. - -``` -bundle exec rake test -``` - -## Generate searchable docs for source code - -You can find results under the `doc/code` directory. - -``` -bundle exec rake gitlab:generate_docs -``` diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md deleted file mode 100644 index 821027f43fa..00000000000 --- a/doc/development/shell_commands.md +++ /dev/null @@ -1,179 +0,0 @@ -# Guidelines for shell commands in the GitLab codebase - -This document contains guidelines for working with processes and files in the GitLab codebase. -These guidelines are meant to make your code more reliable _and_ secure. - -## References - -- [Google Ruby Security Reviewer's Guide](https://code.google.com/p/ruby-security/wiki/Guide) -- [OWASP Command Injection](https://www.owasp.org/index.php/Command_Injection) -- [Ruby on Rails Security Guide Command Line Injection](http://guides.rubyonrails.org/security.html#command-line-injection) - -## Use File and FileUtils instead of shell commands - -Sometimes we invoke basic Unix commands via the shell when there is also a Ruby API for doing it. Use the Ruby API if it exists. <http://www.ruby-doc.org/stdlib-2.0.0/libdoc/fileutils/rdoc/FileUtils.html#module-FileUtils-label-Module+Functions> - -```ruby -# Wrong -system "mkdir -p tmp/special/directory" -# Better (separate tokens) -system *%W(mkdir -p tmp/special/directory) -# Best (do not use a shell command) -FileUtils.mkdir_p "tmp/special/directory" - -# Wrong -contents = `cat #{filename}` -# Correct -contents = File.read(filename) - -# Sometimes a shell command is just the best solution. The example below has no -# user input, and is hard to implement correctly in Ruby: delete all files and -# directories older than 120 minutes under /some/path, but not /some/path -# itself. -Gitlab::Popen.popen(%W(find /some/path -not -path /some/path -mmin +120 -delete)) -``` - -This coding style could have prevented CVE-2013-4490. - -## Bypass the shell by splitting commands into separate tokens - -When we pass shell commands as a single string to Ruby, Ruby will let `/bin/sh` evaluate the entire string. Essentially, we are asking the shell to evaluate a one-line script. This creates a risk for shell injection attacks. It is better to split the shell command into tokens ourselves. Sometimes we use the scripting capabilities of the shell to change the working directory or set environment variables. All of this can also be achieved securely straight from Ruby - -```ruby -# Wrong -system "cd /home/git/gitlab && bundle exec rake db:#{something} RAILS_ENV=production" -# Correct -system({'RAILS_ENV' => 'production'}, *%W(bundle exec rake db:#{something}), chdir: '/home/git/gitlab') - -# Wrong -system "touch #{myfile}" -# Better -system "touch", myfile -# Best (do not run a shell command at all) -FileUtils.touch myfile -``` - -This coding style could have prevented CVE-2013-4546. - -## Separate options from arguments with -- - -Make the difference between options and arguments clear to the argument parsers of system commands with `--`. This is supported by many but not all Unix commands. - -To understand what `--` does, consider the problem below. - -``` -# Example -$ echo hello > -l -$ cat -l -cat: illegal option -- l -usage: cat [-benstuv] [file ...] -``` - -In the example above, the argument parser of `cat` assumes that `-l` is an option. The solution in the example above is to make it clear to `cat` that `-l` is really an argument, not an option. Many Unix command line tools follow the convention of separating options from arguments with `--`. - -``` -# Example (continued) -$ cat -- -l -hello -``` - -In the GitLab codebase, we avoid the option/argument ambiguity by _always_ using `--`. - -```ruby -# Wrong -system(*%W(git branch -d #{branch_name})) -# Correct -system(*%W(git branch -d -- #{branch_name})) -``` - -This coding style could have prevented CVE-2013-4582. - -## Do not use the backticks - -Capturing the output of shell commands with backticks reads nicely, but you are forced to pass the command as one string to the shell. We explained above that this is unsafe. In the main GitLab codebase, the solution is to use `Gitlab::Popen.popen` instead. - -```ruby -# Wrong -logs = `cd #{repo_dir} && git log` -# Correct -logs, exit_status = Gitlab::Popen.popen(%W(git log), repo_dir) - -# Wrong -user = `whoami` -# Correct -user, exit_status = Gitlab::Popen.popen(%W(whoami)) -``` - -In other repositories, such as gitlab-shell you can also use `IO.popen`. - -```ruby -# Safe IO.popen example -logs = IO.popen(%W(git log), chdir: repo_dir) { |p| p.read } -``` - -Note that unlike `Gitlab::Popen.popen`, `IO.popen` does not capture standard error. - -## Avoid user input at the start of path strings - -Various methods for opening and reading files in Ruby can be used to read the -standard output of a process instead of a file. The following two commands do -roughly the same: - -``` -`touch /tmp/pawned-by-backticks` -File.read('|touch /tmp/pawned-by-file-read') -``` - -The key is to open a 'file' whose name starts with a `|`. -Affected methods include Kernel#open, File::read, File::open, IO::open and IO::read. - -You can protect against this behavior of 'open' and 'read' by ensuring that an -attacker cannot control the start of the filename string you are opening. For -instance, the following is sufficient to protect against accidentally starting -a shell command with `|`: - -``` -# we assume repo_path is not controlled by the attacker (user) -path = File.join(repo_path, user_input) -# path cannot start with '|' now. -File.read(path) -``` - -If you have to use user input a relative path, prefix `./` to the path. - -Prefixing user-supplied paths also offers extra protection against paths -starting with `-` (see the discussion about using `--` above). - -## Guard against path traversal - -Path traversal is a security where the program (GitLab) tries to restrict user -access to a certain directory on disk, but the user manages to open a file -outside that directory by taking advantage of the `../` path notation. - -``` -# Suppose the user gave us a path and they are trying to trick us -user_input = '../other-repo.git/other-file' - -# We look up the repo path somewhere -repo_path = 'repositories/user-repo.git' - -# The intention of the code below is to open a file under repo_path, but -# because the user used '..' she can 'break out' into -# 'repositories/other-repo.git' -full_path = File.join(repo_path, user_input) -File.open(full_path) do # Oops! -``` - -A good way to protect against this is to compare the full path with its -'absolute path' according to Ruby's `File.absolute_path`. - -``` -full_path = File.join(repo_path, user_input) -if full_path != File.absolute_path(full_path) - raise "Invalid path: #{full_path.inspect}" -end - -File.open(full_path) do # Etc. -``` - -A check like this could have avoided CVE-2013-4583. diff --git a/doc/development/sidekiq_debugging.md b/doc/development/sidekiq_debugging.md deleted file mode 100644 index cea11e5f126..00000000000 --- a/doc/development/sidekiq_debugging.md +++ /dev/null @@ -1,14 +0,0 @@ -# Sidekiq debugging - -## Log arguments to Sidekiq jobs - -If you want to see what arguments are being passed to Sidekiq jobs you can set -the SIDEKIQ_LOG_ARGUMENTS environment variable. - -``` -SIDEKIQ_LOG_ARGUMENTS=1 bundle exec foreman start -``` - -It is not recommend to enable this setting in production because some Sidekiq -jobs (such as sending a password reset email) take secret arguments (for -example the password reset token). diff --git a/doc/development/ui_guide.md b/doc/development/ui_guide.md deleted file mode 100644 index 2f01defc11d..00000000000 --- a/doc/development/ui_guide.md +++ /dev/null @@ -1,12 +0,0 @@ -# UI Guide for building GitLab - -## Best practices for creating new pages in GitLab - -TODO: write some best practices when develop GitLab features. - -## GitLab UI development kit - -We created a page inside GitLab where you can check commonly used html and css elements. - -When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples -you can use during GitLab development. diff --git a/doc/hooks/custom_hooks.md b/doc/hooks/custom_hooks.md deleted file mode 100644 index f7d4f3de68b..00000000000 --- a/doc/hooks/custom_hooks.md +++ /dev/null @@ -1,41 +0,0 @@ -# Custom Git Hooks - -**Note: Custom git hooks must be configured on the filesystem of the GitLab -server. Only GitLab server administrators will be able to complete these tasks. -Please explore webhooks as an option if you do not have filesystem access.** - -Git natively supports hooks that are executed on different actions. -Examples of server-side git hooks include pre-receive, post-receive, and update. -See -[Git SCM Server-Side Hooks](http://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#Server-Side-Hooks) -for more information about each hook type. - -As of gitlab-shell version 2.2.0 (which requires GitLab 7.5+), GitLab -administrators can add custom git hooks to any GitLab project. - -## Setup - -Normally, git hooks are placed in the repository or project's `hooks` directory. -GitLab creates a symlink from each project's `hooks` directory to the -gitlab-shell `hooks` directory for ease of maintenance between gitlab-shell -upgrades. As such, custom hooks are implemented a little differently. Behavior -is exactly the same once the hook is created, though. Follow these steps to -set up a custom hook. - -1. Pick a project that needs a custom git hook. -1. On the GitLab server, navigate to the project's repository directory. -For an installation from source the path is usually -`/home/git/repositories/<group>/<project>.git`. For Omnibus installs the path is -usually `/var/opt/gitlab/git-data/repositories/<group>/<project>.git`. -1. Create a new directory in this location called `custom_hooks`. -1. Inside the new `custom_hooks` directory, create a file with a name matching -the hook type. For a pre-receive hook the file name should be `pre-receive` with -no extension. -1. Make the hook file executable and make sure it's owned by git. -1. Write the code to make the git hook function as expected. Hooks can be -in any language. Ensure the 'shebang' at the top properly reflects the language -type. For example, if the script is in Ruby the shebang will probably be -`#!/usr/bin/env ruby`. - -That's it! Assuming the hook code is properly implemented the hook will fire -as appropriate. diff --git a/doc/install/README.md b/doc/install/README.md deleted file mode 100644 index 239f5f301ec..00000000000 --- a/doc/install/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Installation - -- [Installation](installation.md) -- [Requirements](requirements.md) -- [Structure](structure.md) -- [Database MySQL](database_mysql.md) diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md deleted file mode 100644 index 362c492d0ac..00000000000 --- a/doc/install/database_mysql.md +++ /dev/null @@ -1,54 +0,0 @@ -# Database MySQL - -## Note - -We do not recommend using MySQL due to various issues. For example, case [(in)sensitivity](https://dev.mysql.com/doc/refman/5.0/en/case-sensitivity.html) and [problems](http://bugs.mysql.com/bug.php?id=65830) that [suggested](http://bugs.mysql.com/bug.php?id=50909) [fixes](http://bugs.mysql.com/bug.php?id=65830) [have](http://bugs.mysql.com/bug.php?id=63164). - -## MySQL - - # 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 - - # Pick a MySQL root password (can be anything), type it and press enter - # Retype the MySQL root password and press enter - - # Secure your installation - sudo mysql_secure_installation - - # Login to MySQL - mysql -u root -p - - # Type the MySQL root password - - # Create a user for GitLab - # do not type the 'mysql>', this is part of the prompt - # change $password in the command below to a real password you pick - mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password'; - - # 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`; - - # Grant the GitLab user necessary permissions on the database - mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES ON `gitlabhq_production`.* TO 'git'@'localhost'; - - # Quit the database session - mysql> \q - - # Try connecting to the new database with the new user - sudo -u git -H mysql -u git -p -D gitlabhq_production - - # Type the password you replaced $password with earlier - - # You should now see a 'mysql>' prompt - - # Quit the database session - mysql> \q - - # You are done installing the database and can go back to the rest of the installation. diff --git a/doc/install/installation.md b/doc/install/installation.md deleted file mode 100644 index a61a40ebd16..00000000000 --- a/doc/install/installation.md +++ /dev/null @@ -1,462 +0,0 @@ -# Installation from source - -## Consider the Omnibus package installation - -Since an installation from source is a lot of work and error prone we strongly recommend the fast and reliable [Omnibus package installation](https://about.gitlab.com/downloads/) (deb/rpm). - -## Select Version to Install - -Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md) from the tag (version) of GitLab you would like to install. -In most cases this should be the highest numbered production tag (without rc in it). -You can select the tag in the version dropdown in the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the [GitLab Blog](https://about.gitlab.com/blog/) for installation guide links by version. - -## Important Notes - -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 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). - -The following steps have been known to work. Please **use caution when you deviate** from this guide. Make sure you don't violate any assumptions GitLab makes about its environment. For example many people run into permission problems because they changed the location of directories or run services as the wrong user. - -If you find a bug/error in this guide please **submit a merge request** -following the -[contributing guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md). - -## Overview - -The GitLab installation consists of setting up the following components: - -1. Packages / Dependencies -1. Ruby -1. System Users -1. Database -1. Redis -1. GitLab -1. Nginx - -## 1. Packages / Dependencies - -`sudo` is not installed on Debian by default. Make sure your system is -up-to-date and install it. - - # run as root! - apt-get update -y - apt-get upgrade -y - apt-get install sudo -y - -**Note:** During this installation some files will need to be edited manually. If you are familiar with vim set it as default editor with the commands below. If you are not familiar with vim please skip this and keep using the default editor. - - # Install vim and set as default editor - sudo apt-get install -y vim - sudo update-alternatives --set editor /usr/bin/vim.basic - -Install the required packages (needed to compile Ruby and native extensions to Ruby gems): - - sudo apt-get install -y build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl openssh-server redis-server checkinstall libxml2-dev libxslt-dev libcurl4-openssl-dev libicu-dev logrotate python-docutils pkg-config cmake libkrb5-dev nodejs - -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 - git --version - -Is the system packaged Git too old? Remove it and compile from source. - - # Remove packaged Git - sudo apt-get remove git-core - - # Install dependencies - sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential - - # Download and compile from source - cd /tmp - curl -L --progress https://www.kernel.org/pub/software/scm/git/git-2.1.2.tar.gz | tar xz - cd git-2.1.2/ - ./configure - make prefix=/usr/local all - - # Install into /usr/local/bin - sudo make prefix=/usr/local install - - # When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git - -**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://github.com/gitlabhq/gitlabhq/issues/4866#issuecomment-32726573) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: - - sudo apt-get install -y postfix - -Then select 'Internet Site' and press enter to confirm the hostname. - -## 2. Ruby - -The use of Ruby version managers such as [RVM](http://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. - -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 -L --progress http://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.6.tar.gz | tar xz - cd ruby-2.1.6 - ./configure --disable-install-rdoc - make - sudo make install - -Install the Bundler Gem: - - sudo gem install bundler --no-ri --no-rdoc - -## 3. System Users - -Create a `git` user for GitLab: - - sudo adduser --disabled-login --gecos 'GitLab' git - -## 4. Database - -We recommend using a PostgreSQL database. For MySQL check [MySQL setup guide](database_mysql.md). *Note*: because we need to make use of extensions you need at least pgsql 9.1. - - # 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; - - # Create the GitLab production database & grant all privileges on database - template1=# CREATE DATABASE gitlabhq_production OWNER git; - - # Quit the database session - template1=# \q - - # Try connecting to the new database with the new user - sudo -u git -H psql -d gitlabhq_production - - # Quit the database session - gitlabhq_production> \q - -## 5. Redis - - sudo apt-get install redis-server - - # Configure redis to use sockets - sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig - - # Disable Redis listening on TCP by setting 'port' to 0 - sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf - - # Enable Redis socket for default Debian / Ubuntu path - echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf - # Grant permission to the socket to all members of the redis group - echo 'unixsocketperm 770' | sudo tee -a /etc/redis/redis.conf - - # Create the directory which contains the socket - mkdir /var/run/redis - chown redis:redis /var/run/redis - chmod 755 /var/run/redis - # Persist the directory which contains the socket, if applicable - if [ -d /etc/tmpfiles.d ]; then - echo 'd /var/run/redis 0755 redis redis 10d -' | sudo tee -a /etc/tmpfiles.d/redis.conf - fi - - # Activate the changes to redis.conf - sudo service redis-server restart - - # Add git to the redis group - sudo usermod -aG redis git - -## 6. GitLab - - # We'll install GitLab into home directory of the user "git" - cd /home/git - -### Clone the Source - - # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 7-10-stable gitlab - -**Note:** You can change `7-10-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! - -### Configure It - - # Go to GitLab installation folder - cd /home/git/gitlab - - # Copy the example GitLab config - sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml - - # Update GitLab config file, follow the directions at top of file - sudo -u git -H editor config/gitlab.yml - - # Make sure GitLab can write to the log/ and tmp/ directories - sudo chown -R git log/ - sudo chown -R git tmp/ - sudo chmod -R u+rwX,go-w log/ - sudo chmod -R u+rwX tmp/ - - # Create directory for satellites - sudo -u git -H mkdir /home/git/gitlab-satellites - sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites - - # Make sure GitLab can write to the tmp/pids/ and tmp/sockets/ directories - 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 - - # Copy the example Unicorn config - sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb - - # Find number of cores - nproc - - # Enable cluster mode if you expect to have a high load instance - # Ex. change amount of workers to 3 for 2GB RAM server - # Set the number of workers to at least the number of cores - sudo -u git -H editor config/unicorn.rb - - # Copy the example Rack attack config - sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb - - # Configure Git global settings for git user, useful when editing via web - # Edit user.email according to what is set in gitlab.yml - sudo -u git -H git config --global user.name "GitLab" - sudo -u git -H git config --global user.email "example@example.com" - sudo -u git -H git config --global core.autocrlf input - - # Configure Redis connection settings - sudo -u git -H cp config/resque.yml.example config/resque.yml - - # Change the Redis socket path if you are not using the default Debian / Ubuntu configuration - sudo -u git -H editor config/resque.yml - -**Important Note:** Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. - -**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. - -### Configure GitLab DB Settings - - # PostgreSQL only: - sudo -u git cp config/database.yml.postgresql config/database.yml - - # MySQL only: - sudo -u git cp config/database.yml.mysql config/database.yml - - # MySQL and remote PostgreSQL only: - # Update username/password in config/database.yml. - # You only need to adapt the production settings (first part). - # If you followed the database guide then please do as follows: - # Change 'secure password' with the value you have given to $password - # You can keep the double quotes around the password - sudo -u git -H editor config/database.yml - - # PostgreSQL and MySQL: - # Make config/database.yml readable to git only - sudo -u git -H chmod o-rwx config/database.yml - -### Install Gems - -**Note:** As of bundler 1.5.2, you can invoke `bundle install -jN` (where `N` the number of your processor cores) and enjoy the parallel gems installation with measurable difference in completion time (~60% faster). Check the number of your cores with `nproc`. For more information check this [post](http://robots.thoughtbot.com/parallel-gem-installing-using-bundler). First make sure you have bundler >= 1.5.2 (run `bundle -v`) as it addresses some [issues](https://devcenter.heroku.com/changelog-items/411) that were [fixed](https://github.com/bundler/bundler/pull/2817) in 1.5.2. - - # For PostgreSQL (note, the option says "without ... mysql") - sudo -u git -H bundle install --deployment --without development test mysql aws - - # Or if you use MySQL (note, the option says "without ... postgres") - sudo -u git -H bundle install --deployment --without development test postgres aws - -### Install GitLab Shell - -GitLab Shell is an SSH access and repository management software developed specially for GitLab. - - # Run the installation task for gitlab-shell (replace `REDIS_URL` if needed): - sudo -u git -H bundle exec rake gitlab:shell:install[v2.6.2] REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production - - # By default, the gitlab-shell config is generated from your main GitLab config. - # You can review (and modify) the gitlab-shell config as follows: - sudo -u git -H editor /home/git/gitlab-shell/config.yml - -**Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. - -### Initialize Database and Activate Advanced Features - - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production - - # Type 'yes' to create the database tables. - - # 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. - - sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production GITLAB_ROOT_PASSWORD=yourpassword - -### Install Init Script - -Download the init script (will be `/etc/init.d/gitlab`): - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -And if you are installing with a non-default folder or user copy and edit the defaults file: - - sudo cp lib/support/init.d/gitlab.default.example /etc/default/gitlab - -If you installed GitLab in another directory or as a user other than the default you should change these settings in `/etc/default/gitlab`. Do not edit `/etc/init.d/gitlab` as it will be changed on upgrade. - -Make GitLab start on boot: - - sudo update-rc.d gitlab defaults 21 - -### Setup Logrotate - - sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab - -### 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 - -### Compile Assets - - sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production - -### Start Your GitLab Instance - - sudo service gitlab start - # or - sudo /etc/init.d/gitlab restart - -## 7. Nginx - -**Note:** Nginx is the officially supported web server for GitLab. If you cannot or do not want to use Nginx as your web server, have a look at the [GitLab recipes](https://gitlab.com/gitlab-org/gitlab-recipes/). - -### Installation - - sudo apt-get install -y nginx - -### Site Configuration - -Copy the example site config: - - sudo cp lib/support/nginx/gitlab /etc/nginx/sites-available/gitlab - sudo ln -s /etc/nginx/sites-available/gitlab /etc/nginx/sites-enabled/gitlab - -Make sure to edit the config file to match your setup: - - # Change YOUR_SERVER_FQDN to the fully-qualified - # domain name of your host serving GitLab. - sudo editor /etc/nginx/sites-available/gitlab - -**Note:** If you want to use HTTPS, replace the `gitlab` Nginx config with `gitlab-ssl`. See [Using HTTPS](#using-https) for HTTPS configuration details. - -### Test Configuration - -Validate your `gitlab` or `gitlab-ssl` Nginx config file with the following command: - - sudo nginx -t - -You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` Nginx config file for typos, etc. as indicated in the error message given. - -### Restart - - sudo service nginx restart - -## Done! - -### Double-check Application Status - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations on successfully installing GitLab! - -NOTE: Supply `SANITIZE=true` environment variable to `gitlab:check` to omit project names from the output of the check command. - -### 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: - - root - 5iveL!fe - -**Important Note:** On login you'll be prompted to change the password. - -**Enjoy!** - -You can use `sudo service gitlab start` and `sudo service gitlab stop` to start and stop GitLab. - -## Advanced Setup Tips - -### Using HTTPS - -To use GitLab with HTTPS: - -1. In `gitlab.yml`: - 1. Set the `port` option in section 1 to `443`. - 1. Set the `https` option in section 1 to `true`. -1. In the `config.yml` of gitlab-shell: - 1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`). - 1. Set the certificates using either the `ca_file` or `ca_path` option. -1. Use the `gitlab-ssl` Nginx example config instead of the `gitlab` config. - 1. Update `YOUR_SERVER_FQDN`. - 1. Update `ssl_certificate` and `ssl_certificate_key`. - 1. Review the configuration file and consider applying other security and performance enhancing features. - -Using a self-signed certificate is discouraged but if you must use it follow the normal directions then: - -1. Generate a self-signed SSL certificate: - - ``` - mkdir -p /etc/nginx/ssl/ - cd /etc/nginx/ssl/ - sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key - sudo chmod o-r gitlab.key - ``` -1. In the `config.yml` of gitlab-shell set `self_signed_cert` to `true`. - -### Additional Markup Styles - -Apart from the always supported markdown style there are other rich text files that GitLab can display. But you might have to install a dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. - -### Custom Redis Connection - -If you'd like Resque to connect to a Redis server on a non-standard port or on a different host, you can configure its connection string via the `config/resque.yml` file. - - # example - production: redis://redis.example.tld:6379 - -If you want to connect the Redis server via socket, then use the "unix:" URL scheme and the path to the Redis socket file in the `config/resque.yml` file. - - # example - production: unix:/path/to/redis/socket - -### Custom SSH Connection - -If you are running SSH on a non-standard port, you must change the GitLab user's SSH config. - - # Add to /home/git/.ssh/config - host localhost # Give your setup a name (here: override localhost) - user git # Your remote git user - port 2222 # Your port number - hostname 127.0.0.1; # Your server name or IP - -You also need to change the corresponding options (e.g. `ssh_user`, `ssh_host`, `admin_uri`) in the `config\gitlab.yml` file. - -### LDAP Authentication - -You can configure LDAP authentication in `config/gitlab.yml`. Please restart GitLab after editing this file. - -### Using Custom Omniauth Providers - -See the [omniauth integration document](../integration/omniauth.md) diff --git a/doc/install/requirements.md b/doc/install/requirements.md deleted file mode 100644 index 7a3216dd2d2..00000000000 --- a/doc/install/requirements.md +++ /dev/null @@ -1,109 +0,0 @@ -# Requirements - -## Operating Systems - -### Supported Unix distributions - -- Ubuntu -- Debian -- CentOS -- Red Hat Enterprise Linux (please use the CentOS packages and instructions) -- Scientific Linux (please use the CentOS packages and instructions) -- Oracle Linux (please use the CentOS packages and instructions) - -For the installations options please see [the installation page on the GitLab website](https://about.gitlab.com/installation/). - -### Unsupported Unix distributions - -- OS X -- Arch Linux -- Fedora -- Gentoo -- 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. - -### Non-Unix operating systems such as Windows - -GitLab is developed for Unix operating systems. -GitLab does **not** run on Windows and we have no plans of supporting it in the near future. -Please consider using a virtual machine to run GitLab. - -## Ruby versions - -GitLab requires Ruby (MRI) 2.0 or 2.1 -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. - -## 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 twice as much free space as all your repos combined take up. You need twice the storage because [GitLab satellites](structure.md) contain an extra copy of each repo. - -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. - -Apart from a local hard drive you can also mount a volume that supports the network file system (NFS) protocol. This volume might be located on a file server, a network attached storage (NAS) device, a storage area network (SAN) or on an Amazon Web Services (AWS) Elastic Block Store (EBS) volume. - -If you have enough RAM memory and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) will improve the responsiveness of GitLab. - -### CPU - -- 1 core works supports up to 100 users but the application can be a bit slower due to having all workers and background jobs running on the same core -- **2 cores** is the **recommended** number of cores and supports up to 500 users -- 4 cores supports up to 2,000 users -- 8 cores supports up to 5,000 users -- 16 cores supports up to 10,000 users -- 32 cores supports up to 20,000 users -- 64 cores supports up to 40,000 users - -### Memory - -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 -- **2GB RAM** is the **recommended** memory size and supports up to 500 users -- 4GB RAM supports up to 2,000 users -- 8GB RAM supports up to 5,000 users -- 16GB RAM supports up to 10,000 users -- 32GB RAM supports up to 20,000 users -- 64GB RAM supports up to 40,000 users - -Notice: The 25 workers of Sidekiq will show up as separate processes in your process overview (such as top or htop) but they share the same RAM allocation since Sidekiq is a multithreaded application. - -## Unicorn Workers - -It's possible to increase the amount of unicorn workers and this will usually help for to reduce the response time of the applications and increase the ability to handle parallel requests. - -For most instances we recommend using: CPU cores + 1 = unicorn workers. -So for a machine with 2 cores, 3 unicorn workers is ideal. - -For all machines that have 1GB and up we recommend a minimum of three unicorn workers. -If you have a 512MB machine with a magnetic (non-SSD) swap drive we recommend to configure only one Unicorn worker to prevent excessive swapping. -With one Unicorn worker only git over ssh access will work because the git over HTTP access requires two running workers (one worker to receive the user request and one worker for the authorization check). -If you have a 512MB machine with a SSD drive you can use two Unicorn workers, this will allow HTTP access although it will be slow due to swapping. - -To change the Unicorn workers when you have the Omnibus package please see [the Unicorn settings in the Omnibus GitLab documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.md#unicorn-settings). - -## Database - -If you want to run the database separately, the **recommended** database size is **1 MB per user**. - -## Redis and Sidekiq - -Redis stores all user sessions and the background task queue. -The storage requirements for Redis are minimal, about 25kB per user. -Sidekiq processes the background jobs with a multithreaded process. -This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. -On a very active server (10,000 active users) the Sidekiq process can use 1GB+ of memory. - -## Supported web browsers - -- Chrome (Latest stable version) -- 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) -- IE 10+
\ No newline at end of file diff --git a/doc/install/structure.md b/doc/install/structure.md deleted file mode 100644 index 5c03f073c18..00000000000 --- a/doc/install/structure.md +++ /dev/null @@ -1,21 +0,0 @@ -# GitLab directory structure - -This is the directory structure you will end up with following the instructions in the Installation Guide. - - |-- home - | |-- git - | |-- .ssh - | |-- gitlab - | |-- gitlab-satellites - | |-- gitlab-shell - | |-- repositories - -* `/home/git/.ssh` - contains openssh settings. Specifically the `authorized_keys` file managed by gitlab-shell. -* `/home/git/gitlab` - GitLab core software. -* `/home/git/gitlab-satellites` - checked out repositories for merge requests and file editing from web UI. This can be treated as a temporary files directory. -* `/home/git/gitlab-shell` - Core add-on component of GitLab. Maintains SSH cloning and other functionality. -* `/home/git/repositories` - bare repositories for all projects organized by namespace. This is where the git repositories which are pushed/pulled are maintained for all projects. **This area is critical data for projects. [Keep a backup](../raketasks/backup_restore.md)** - -*Note: the default locations for gitlab-satellites and repositories can be configured in `config/gitlab.yml` of GitLab and `config.yml` of gitlab-shell.* - -To see a more in-depth overview see the [GitLab architecture doc](../development/architecture.md). diff --git a/doc/integration/README.md b/doc/integration/README.md deleted file mode 100644 index 286bd34a0bd..00000000000 --- a/doc/integration/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# GitLab Integration - -GitLab integrates with multiple third-party services to allow external issue trackers and external authentication. - -See the documentation below for details on how to configure these services. - -- [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. -- [Slack](slack.md) Integrate with the Slack chat service -- [OAuth2 provider](oauth_provider.md) OAuth2 application creation -- [Gmail](gitlab_buttons_in_gmail.md) Adds GitLab actions to messages - -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). - -## 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). diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md deleted file mode 100644 index d82e1f8b41b..00000000000 --- a/doc/integration/bitbucket.md +++ /dev/null @@ -1,122 +0,0 @@ -# Integrate your server with Bitbucket - -Import projects from Bitbucket and login to your GitLab instance with your Bitbucket account. - -To enable the Bitbucket OmniAuth provider you must register your application with Bitbucket. -Bitbucket will generate an application ID and secret key for you to use. - -1. Sign in to Bitbucket. - -1. Navigate to your individual user settings or a team's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or a team - that is entirely up to you. - -1. Select "OAuth" in the left menu. - -1. Select "Add consumer". - -1. Provide the required details. - - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - - Application description: Fill this in if you wish. - - URL: The URL to your GitLab installation. 'https://gitlab.company.com' -1. Select "Save". - -1. You should now see a Key and Secret in the list of OAuth customers. - Keep this page open as you continue configuration. - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For instalations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "bitbucket", - "app_id" => "YOUR_KEY", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://bitbucket.org/" - } - ] - ``` - - For installation from source: - - ``` - - { name: 'bitbucket', app_id: 'YOUR_KEY', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the key from the Bitbucket application page from step 7. - -1. Change 'YOUR_APP_SECRET' to the secret from the Bitbucket application page from step 7. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Bitbucket icon below the regular sign in form. -Click the icon to begin the authentication process. Bitbucket will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. - -## Bitbucket project import - -To allow projects to be imported directly into GitLab, Bitbucket requires two extra setup steps compared to GitHub and GitLab.com. - -Bitbucket doesn't allow OAuth applications to clone repositories over HTTPS, and instead requires GitLab to use SSH and identify itself using your GitLab server's SSH key. - -### Step 1: Known hosts - -To allow GitLab to connect to Bitbucket over SSH, you need to add 'bitbucket.org' to your GitLab server's known SSH hosts. Take the following steps to do so: - -1. Manually connect to 'bitbucket.org' over SSH, while logged in as the `git` account that GitLab will use: - - ```sh - ssh git@bitbucket.org - ``` - -1. Verify the RSA key fingerprint you'll see in the response matches the one in the [Bitbucket documentation](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket'spublickeyfingerprints) (the specific IP address doesn't matter): - - ```sh - The authenticity of host 'bitbucket.org (207.223.240.182)' can't be established. - RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40. - Are you sure you want to continue connecting (yes/no)? - ``` - -1. If the fingerprint matches, type `yes` to continue connecting and have 'bitbucket.org' be added to your known hosts. - -1. Your GitLab server is now able to connect to Bitbucket over SSH. Continue to step 2: - -### Step 2: Public key - -To be able to access repositories on Bitbucket, GitLab will automatically register your public key with Bitbucket as a deploy key for the repositories to be imported. Your public key needs to be at `~/.ssh/bitbucket_rsa.pub`, which will expand to `/home/git/.ssh/bitbucket_rsa.pub` in most configurations. - -If you have that file in place, you're all set and should see the "Import projects from Bitbucket" option enabled. If you don't, do the following: - -1. Create a new SSH key: - - ```sh - sudo -u git -H ssh-keygen - ``` - - When asked `Enter file in which to save the key` specify the correct path, eg. `/home/git/.ssh/bitbucket_rsa`. - Make sure to use an **empty passphrase**. - -2. Restart GitLab to allow it to find the new public key. - -You should now see the "Import projects from Bitbucket" option on the New Project page enabled. diff --git a/doc/integration/external-issue-tracker.md b/doc/integration/external-issue-tracker.md deleted file mode 100644 index 96755707dee..00000000000 --- a/doc/integration/external-issue-tracker.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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: - -- 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). - -## Configuration - -### Project Service - -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: - - - -* `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. - -### 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. - -Support to add your commits to the Jira ticket automatically is [available in GitLab EE](http://doc.gitlab.com/ee/integration/jira.html). diff --git a/doc/integration/github.md b/doc/integration/github.md deleted file mode 100644 index b64501c2aaa..00000000000 --- a/doc/integration/github.md +++ /dev/null @@ -1,79 +0,0 @@ -# Integrate your server with GitHub - -Import projects from GitHub and login to your GitLab instance with your GitHub account. - -To enable the GitHub OmniAuth provider you must register your application with GitHub. -GitHub will generate an application ID and secret key for you to use. - -1. Sign in to GitHub. - -1. Navigate to your individual user settings or an organization's settings, depending on how you want the application registered. It does not matter if the application is registered as an individual or an organization - that is entirely up to you. - -1. Select "Applications" in the left menu. - -1. Select "Register new application". - -1. Provide the required details. - - Application name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - - Homepage URL: The URL to your GitLab installation. 'https://gitlab.company.com' - - Application description: Fill this in if you wish. - - Authorization callback URL: 'https://gitlab.company.com/' -1. Select "Register application". - -1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). - Keep this page open as you continue configuration. -  - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For instalations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "github", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "url" => "https://github.com/", - "args" => { "scope" => "user:email" } - } - ] - ``` - - For installation from source: - - ``` - - { name: 'github', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'user:email' } } - ``` - -1. Change 'YOUR_APP_ID' to the client ID from the GitHub application page from step 7. - -1. Change 'YOUR_APP_SECRET' to the client secret from the GitHub application page from step 7. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a GitHub icon below the regular sign in form. -Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/github_app.png b/doc/integration/github_app.png Binary files differdeleted file mode 100644 index d890345ced9..00000000000 --- a/doc/integration/github_app.png +++ /dev/null diff --git a/doc/integration/gitlab.md b/doc/integration/gitlab.md deleted file mode 100644 index 216f1f11a9b..00000000000 --- a/doc/integration/gitlab.md +++ /dev/null @@ -1,84 +0,0 @@ -# Integrate your server with GitLab.com - -Import projects from GitLab.com and login to your GitLab instance with your GitLab.com account. - -To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com. -GitLab.com will generate an application ID and secret key for you to use. - -1. Sign in to GitLab.com - -1. Navigate to your profile settings. - -1. Select "Applications" in the left menu. - -1. Select "New application". - -1. Provide the required details. - - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or something else descriptive. - - Redirect URI: - - ``` - http://your-gitlab.example.com/import/gitlab/callback - http://your-gitlab.example.com/users/auth/gitlab/callback - ``` - - The first link is required for the importer and second for the authorization. - -1. Select "Submit". - -1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). - Keep this page open as you continue configuration. -  - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For instalations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "gitlab", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "scope" => "api" } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'gitlab', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { scope: 'api' } } - ``` - -1. Change 'YOUR_APP_ID' to the Application ID from the GitLab.com application page. - -1. Change 'YOUR_APP_SECRET' to the secret from the GitLab.com application page. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a GitLab.com icon below the regular sign in form. -Click the icon to begin the authentication process. GitLab.com will ask the user to sign in and authorize the GitLab application. -If everything goes well the user will be returned to your GitLab instance and will be signed in. diff --git a/doc/integration/gitlab_actions.png b/doc/integration/gitlab_actions.png Binary files differdeleted file mode 100644 index b08f54d137b..00000000000 --- a/doc/integration/gitlab_actions.png +++ /dev/null diff --git a/doc/integration/gitlab_app.png b/doc/integration/gitlab_app.png Binary files differdeleted file mode 100644 index 3f9391a821b..00000000000 --- a/doc/integration/gitlab_app.png +++ /dev/null diff --git a/doc/integration/gitlab_buttons_in_gmail.md b/doc/integration/gitlab_buttons_in_gmail.md deleted file mode 100644 index a9885cef109..00000000000 --- a/doc/integration/gitlab_buttons_in_gmail.md +++ /dev/null @@ -1,28 +0,0 @@ -# GitLab buttons in Gmail - -GitLab supports [Google actions in email](https://developers.google.com/gmail/markup/actions/actions-overview). - -If correctly setup, emails that require an action will be marked in Gmail. - - - -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) - -To aid the registering with google, GitLab offers a rake task that will send an email to google whitelisting email address from your GitLab server. - -To check what would be sent to the google email address, run the rake task: - -```bash -bundle exec rake gitlab:mail_google_schema_whitelisting RAILS_ENV=production -``` - -**This will not send the email but give you the output of how the mail will look.** - -Copy the output of the rake task to [google email markup tester](https://www.google.com/webmasters/markup-tester/u/0/) and press "Validate". - -If you receive "No errors detected" message from the tester you can send the email using: - -```bash -bundle exec rake gitlab:mail_google_schema_whitelisting RAILS_ENV=production SEND=true -``` diff --git a/doc/integration/google.md b/doc/integration/google.md deleted file mode 100644 index e1c14c7c948..00000000000 --- a/doc/integration/google.md +++ /dev/null @@ -1,89 +0,0 @@ -# Google OAuth2 OmniAuth Provider - -To enable the Google OAuth2 OmniAuth provider you must register your application with Google. Google will generate a client ID and secret key for you to use. - -1. Sign in to the [Google Developers Console](https://console.developers.google.com/) with the Google account you want to use to register GitLab. - -1. Select "Create Project". - -1. Provide the project information - - Project name: 'GitLab' works just fine here. - - Project ID: Must be unique to all Google Developer registered applications. Google provides a randomly generated Project ID by default. You can use the randomly generated ID or choose a new one. -1. Refresh the page. You should now see your new project in the list. Click on the project. - -1. Select "APIs & auth" in the left menu. - -1. Select "APIs" in the submenu. - - Enable `Contacts API` - - Enable `Google+ API` - -1. Select "Credentials" in the submenu. - -1. Select "Create New Client ID". - -1. Fill in the required information - - Application type: "Web Application" - - Authorized JavaScript origins: This isn't really used by GitLab but go ahead and put 'https://gitlab.example.com' here. - - Authorized redirect URI: 'https://gitlab.example.com/users/auth/google_oauth2/callback' -1. Under the heading "Client ID for web application" you should see a Client ID and Client secret (see screenshot). Keep this page open as you continue configuration.  - -1. On your GitLab server, open the configuration file. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For instalations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "google_oauth2", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET", - "args" => { "access_type" => "offline", "approval_prompt" => '' } - } - ] - ``` - - For installations from source: - - ``` - - { name: 'google_oauth2', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET', - args: { access_type: 'offline', approval_prompt: '' } } - ``` - -1. Change 'YOUR_APP_ID' to the client ID from the Google Developer page from step 10. - -1. Change 'YOUR_APP_SECRET' to the client secret from the Google Developer page from step 10. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Google icon below the regular sign in form. Click the icon to begin the authentication process. Google will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. - -## Further Configuration - -This further configuration is not required for Google authentication to function but it is strongly recommended. Taking these steps will increase usability for users by providing a little more recognition and branding. - -At this point, when users first try to authenticate to your GitLab installation with Google they will see a generic application name on the prompt screen. The prompt informs the user that "Project Default Service Account" would like to access their account. "Project Default Service Account" isn't very recognizable and may confuse or cause users to be concerned. This is easily changeable. - -1. Select 'Consent screen' in the left menu. (See steps 1, 4 and 5 above for instructions on how to get here if you closed your window). -1. Scroll down until you find "Product Name". Change the product name to something more descriptive. -1. Add any additional information as you wish - homepage, logo, privacy policy, etc. None of this is required, but it may help your users. diff --git a/doc/integration/google_app.png b/doc/integration/google_app.png Binary files differdeleted file mode 100644 index 5a62ad35009..00000000000 --- a/doc/integration/google_app.png +++ /dev/null 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/ldap.md b/doc/integration/ldap.md deleted file mode 100644 index b67f793c591..00000000000 --- a/doc/integration/ldap.md +++ /dev/null @@ -1,148 +0,0 @@ -# GitLab LDAP integration - -GitLab can be configured to allow your users to sign with their LDAP credentials to integrate with e.g. Active Directory. - -The first time a user signs in with LDAP credentials, GitLab will create a new GitLab user associated with the LDAP Distinguished Name (DN) of the LDAP user. - -GitLab user attributes such as nickname and email will be copied from the LDAP user entry. - -## Configuring GitLab for LDAP integration - -To enable GitLab LDAP integration you need to add your LDAP server settings in `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml`. -In GitLab Enterprise Edition you can have multiple LDAP servers connected to one GitLab server. - -Please note that before version 7.4, GitLab used a different syntax for configuring LDAP integration. -The old LDAP integration syntax still works in GitLab 7.4. -If your `gitlab.rb` or `gitlab.yml` file contains LDAP settings in both the old syntax and the new syntax, only the __old__ syntax will be used by GitLab. - -```ruby -# For omnibus packages -gitlab_rails['ldap_enabled'] = true -gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below -main: # 'main' is the GitLab 'provider ID' of this LDAP server - ## label - # - # A human-friendly name for your LDAP server. It is OK to change the label later, - # for instance if you find out it is too large to fit on the web page. - # - # Example: 'Paris' or 'Acme, Ltd.' - label: 'LDAP' - - host: '_your_ldap_server' - port: 389 - uid: 'sAMAccountName' - method: 'plain' # "tls" or "ssl" or "plain" - bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' - password: '_the_password_of_the_bind_user' - - # 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. - active_directory: true - - # If allow_username_or_email_login is enabled, GitLab will ignore everything - # after the first '@' in the LDAP username submitted by the user on login. - # - # Example: - # - the user enters 'jane.doe@example.com' and 'p@ssw0rd' as LDAP credentials; - # - GitLab queries the LDAP server with 'jane.doe' and 'p@ssw0rd'. - # - # If you are using "uid: 'userPrincipalName'" on ActiveDirectory you need to - # disable this setting, because the userPrincipalName contains an '@'. - allow_username_or_email_login: false - - # To maintain tight control over the number of active users on your GitLab installation, - # enable this setting to keep new users blocked until they have been cleared by the admin - # (default: false). - block_auto_created_users: false - - # Base where we can search for users - # - # Ex. ou=People,dc=gitlab,dc=example - # - base: '' - - # Filter LDAP users - # - # Format: RFC 4515 http://tools.ietf.org/search/rfc4515 - # Ex. (employeeType=developer) - # - # Note: GitLab does not support omniauth-ldap's custom filter syntax. - # - user_filter: '' - -# GitLab EE only: add more LDAP servers -# Choose an ID made of a-z and 0-9 . This ID will be stored in the database -# so that GitLab can remember which LDAP server a user belongs to. -# uswest2: -# label: -# host: -# .... -EOS -``` - -If you are getting 'Connection Refused' errors when trying to connect to the LDAP server please double-check the LDAP `port` and `method` settings used by GitLab. -Common combinations are `method: 'plain'` and `port: 389`, OR `method: 'ssl'` and `port: 636`. - -If you are using a GitLab installation from source you can find the LDAP settings in `/home/git/gitlab/config/gitlab.yml`: - -``` -production: - # snip... - ldap: - enabled: false - servers: - main: # 'main' is the GitLab 'provider ID' of this LDAP server - ## label - # - # A human-friendly name for your LDAP server. It is OK to change the label later, - # for instance if you find out it is too large to fit on the web page. - # - # Example: 'Paris' or 'Acme, Ltd.' - label: 'LDAP' - # snip... -``` - -## Enabling LDAP sign-in for existing GitLab users - -When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then the LDAP DN will be associated with the existing user. - -If the LDAP email attribute is not found in GitLab's database, a new user is created. - -In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their LDAP email address, and then sign into GitLab via their LDAP credentials. - -GitLab recognizes the following LDAP attributes as email addresses: `mail`, `email` and `userPrincipalName`. - -If multiple LDAP email attributes are present, e.g. `mail: foo@bar.com` and `email: foo@example.com`, then the first attribute found wins -- in this case `foo@bar.com`. - -## Using an LDAP filter to limit access to your GitLab server - -If you want to limit all GitLab access to a subset of the LDAP users on your LDAP server you can set up an LDAP user filter. -The filter must comply with [RFC 4515](http://tools.ietf.org/search/rfc4515). - -```ruby -# For omnibus packages; new LDAP server syntax -gitlab_rails['ldap_servers'] = YAML.load <<-EOS -main: - # snip... - user_filter: '(employeeType=developer)' -EOS -``` - -```yaml -# For installations from source; new LDAP server syntax -production: - ldap: - servers: - main: - # snip... - user_filter: '(employeeType=developer)' -``` - -Tip: if you want to limit access to the nested members of an Active Directory group you can use the following syntax: - -``` -(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com) -``` - -Please note that GitLab does not support the custom filter syntax used by omniauth-ldap. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md deleted file mode 100644 index 192c321f712..00000000000 --- a/doc/integration/oauth_provider.md +++ /dev/null @@ -1,35 +0,0 @@ -## 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) - -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). - -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. - -### Adding application through profile -Go to your profile section 'Application' and press button 'New Application' - - - -After this you will see application form, where "Name" is arbitrary name, "Redirect URI" is URL in your app where users will be sent after authorization on GitLab.com. - - - -### Authorized application -Every application you authorized will be shown in your "Authorized application" sections. - - - -At any time you can revoke access just clicking button "Revoke" - -### 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 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 deleted file mode 100644 index 24f7b4bb4b4..00000000000 --- a/doc/integration/omniauth.md +++ /dev/null @@ -1,127 +0,0 @@ -# OmniAuth - -GitLab leverages OmniAuth to allow users to sign in using Twitter, GitHub, and other popular services. - -Configuring OmniAuth does not prevent standard GitLab authentication or LDAP (if configured) from continuing to work. Users can choose to sign in using any of the configured mechanisms. - -- [Initial OmniAuth Configuration](#initial-omniauth-configuration) -- [Supported Providers](#supported-providers) -- [Enable OmniAuth for an Existing User](#enable-omniauth-for-an-existing-user) -- [OmniAuth configuration sample when using Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master#omniauth-google-twitter-github-login) - -## Initial OmniAuth Configuration - -Before configuring individual OmniAuth providers there are a few global settings that are in common for all providers that we need to consider. - -- Omniauth needs to be enabled, see details below for example. -- `allow_single_sign_on` 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: - -* **For omnibus package** - - Open the configuration file: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - and change - - ``` - gitlab_rails['omniauth_enabled'] = true - gitlab_rails['omniauth_allow_single_sign_on'] = false - gitlab_rails['block_auto_created_users'] = true - ``` - -* **For installations from source** - - Open the configuration file: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - - and change the following section - - ``` - ## 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). - # User accounts will be created automatically when authentication was successful. - allow_single_sign_on: false - # 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) -- [Shibboleth](shibboleth.md) -- [Twitter](twitter.md) - -## Enable OmniAuth for an Existing User - -Existing users can enable OmniAuth for specific providers after the account is created. For example, if the user originally signed in with LDAP an OmniAuth provider such as Twitter can be enabled. Follow the steps below to enable an OmniAuth provider for an existing user. - -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 "Social Accounts" select the desired OmniAuth provider, such as Twitter. -1. The user will be redirected to the provider. Once the user authorized GitLab they will be redirected back to GitLab. - -The chosen OmniAuth provider is now active and can be used to sign in to GitLab from then on. - -## 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. - -### Steps - -These steps are fairly general and you will need to figure out the exact details from the Omniauth provider's documentation. - -- Stop GitLab: - - sudo service gitlab stop - -- Add the gem to your [Gemfile](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/Gemfile): - - gem "omniauth-your-auth-provider" - -- If you're using MySQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test postgres --path vendor/bundle --no-deployment - -- If you're using PostgreSQL, install the new Omniauth provider gem by running the following command: - - sudo -u git -H bundle install --without development test mysql --path vendor/bundle --no-deployment - - > These are the same commands you used in the [Install Gems section](#install-gems) with `--path vendor/bundle --no-deployment` instead of `--deployment`. - -- Start GitLab: - - sudo service gitlab start - -### Examples - -If you have successfully set up a provider that is not shipped with GitLab itself, please let us know. - -You can help others by reporting successful configurations and probably share a few insights or provide warnings for common errors or pitfalls by sharing your experience [in the public Wiki](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Custom-omniauth-provider-configurations). - -While we can't officially support every possible authentication mechanism out there, we'd like to at least help those with specific needs. 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/shibboleth.md b/doc/integration/shibboleth.md deleted file mode 100644 index 6258e5f1030..00000000000 --- a/doc/integration/shibboleth.md +++ /dev/null @@ -1,78 +0,0 @@ -# Shibboleth OmniAuth Provider - -This documentation is for enabling shibboleth with gitlab-omnibus 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. - - -To enable the Shibboleth OmniAuth provider you must: - -1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. -Check https://wiki.shibboleth.net/ for more info. - -1. You can find Apache config in gitlab-recipes (https://github.com/gitlabhq/gitlab-recipes/blob/master/web-server/apache/gitlab-ssl.conf) - -Following changes are needed to enable shibboleth: - -protect omniauth-shibboleth callback URL: -``` - <Location /users/auth/shibboleth/callback> - AuthType shibboleth - ShibRequestSetting requireSession 1 - ShibUseHeaders On - require valid-user - </Location> - - Alias /shibboleth-sp /usr/share/shibboleth - <Location /shibboleth-sp> - Satisfy any - </Location> - - <Location /Shibboleth.sso> - SetHandler shib - </Location> -``` -exclude shibboleth URLs from rewriting, add "RewriteCond %{REQUEST_URI} !/Shibboleth.sso" and "RewriteCond %{REQUEST_URI} !/shibboleth-sp", config should look like this: -``` - # Apache equivalent of Nginx try files - RewriteEngine on - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_URI} !/Shibboleth.sso - RewriteCond %{REQUEST_URI} !/shibboleth-sp - RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA] - RequestHeader set X_FORWARDED_PROTO 'https' -``` - -1. Edit /etc/gitlab/gitlab.rb configuration file, your shibboleth attributes should be in form of "HTTP_ATTRIBUTE" and you should addjust them to your need and environment. Add any other configuration you need. - -File should look like this: -``` -external_url 'https://gitlab.example.com' -gitlab_rails['internal_api_url'] = 'https://gitlab.example.com' - -# disable Nginx -nginx['enable'] = false - -gitlab_rails['omniauth_allow_single_sign_on'] = true -gitlab_rails['omniauth_block_auto_created_users'] = false -gitlab_rails['omniauth_enabled'] = true -gitlab_rails['omniauth_providers'] = [ - { - "name" => 'shibboleth', - "args" => { - "shib_session_id_field" => "HTTP_SHIB_SESSION_ID", - "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID", - "uid_field" => 'HTTP_EPPN', - "name_field" => 'HTTP_CN', - "info_fields" => { "email" => 'HTTP_MAIL'} - } - } -] - -``` -1. Save changes and reconfigure gitlab: -``` -sudo gitlab-ctl reconfigure -``` - -On the sign in page there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You will be redirected to IdP server (Depends on your Shibboleth module configuration). If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/slack.md b/doc/integration/slack.md deleted file mode 100644 index 2fd22c513ad..00000000000 --- a/doc/integration/slack.md +++ /dev/null @@ -1,42 +0,0 @@ -# Slack integration - -## On Slack - -To enable Slack integration you must create an Incoming WebHooks integration on Slack; - -1. [Sign in to Slack](https://slack.com/signin) - -1. Select **Configure Integrations** from the dropdown next to your team name. - -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. Click **Add Incoming WebHooks Integration**Add Integrations. - - Optional step; You can change bot's name and avatar by clicking modifying the bot name or avatar under **Integration Settings**. - -1. Copy the **Webhook URL**, we'll need this later for GitLab. - - -## On GitLab - -After Slack is ready we need to setup GitLab. Here are the steps to achieve this. - -1. Sign in to GitLab - -1. Pick the repository you want. - -1. Navigate to Settings -> Services -> Slack - -1. Fill in your Slack details - - - Mark it as active - - Paste in the webhook URL you got from Slack - -Have fun :) - -*P.S. You can set "branch,pushed,Compare changes" as highlight words on your Slack profile settings, so that you can be aware of new commits when somebody pushes them.* diff --git a/doc/integration/twitter.md b/doc/integration/twitter.md deleted file mode 100644 index fe9091ad9a8..00000000000 --- a/doc/integration/twitter.md +++ /dev/null @@ -1,81 +0,0 @@ -# Twitter OAuth2 OmniAuth Provider - -To enable the Twitter OmniAuth provider you must register your application with Twitter. Twitter will generate a client ID and secret key for you to use. - -1. Sign in to [Twitter Developers](https://dev.twitter.com/) area. - -1. Hover over the avatar in the top right corner and select "My applications." - -1. Select "Create new app" - -1. Fill in the application details. - - Name: This can be anything. Consider something like "\<Organization\>'s GitLab" or "\<Your Name\>'s GitLab" or - something else descriptive. - - Description: Create a description. - - Website: The URL to your GitLab installation. 'https://gitlab.example.com' - - Callback URL: 'https://gitlab.example.com/users/auth/twitter/callback' - - Agree to the "Rules of the Road." - -  -1. Select "Create your Twitter application." - -1. Select the "Settings" tab. - -1. Underneath the Callback URL check the box next to "Allow this application to be used to Sign in the Twitter." - -1. Select "Update settings" at the bottom to save changes. - -1. Select the "API Keys" tab. - -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. - - For omnibus package: - - ```sh - sudo editor /etc/gitlab/gitlab.rb - ``` - - For instalations from source: - - ```sh - cd /home/git/gitlab - - sudo -u git -H editor config/gitlab.yml - ``` - -1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. - -1. Add the provider configuration: - - For omnibus package: - - ```ruby - gitlab_rails['omniauth_providers'] = [ - { - "name" => "twitter", - "app_id" => "YOUR_APP_ID", - "app_secret" => "YOUR_APP_SECRET" - } - ] - ``` - - For installations from source: - - ``` - - { name: 'twitter', app_id: 'YOUR_APP_ID', - app_secret: 'YOUR_APP_SECRET' } - ``` - -1. Change 'YOUR_APP_ID' to the API key from Twitter page in step 11. - -1. Change 'YOUR_APP_SECRET' to the API secret from the Twitter page in step 11. - -1. Save the configuration file. - -1. Restart GitLab for the changes to take effect. - -On the sign in page there should now be a Twitter icon below the regular sign in form. Click the icon to begin the authentication process. Twitter will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. diff --git a/doc/integration/twitter_app_api_keys.png b/doc/integration/twitter_app_api_keys.png Binary files differdeleted file mode 100644 index 1076337172a..00000000000 --- a/doc/integration/twitter_app_api_keys.png +++ /dev/null diff --git a/doc/integration/twitter_app_details.png b/doc/integration/twitter_app_details.png Binary files differdeleted file mode 100644 index b95e8af8a74..00000000000 --- a/doc/integration/twitter_app_details.png +++ /dev/null diff --git a/doc/legal/README.md b/doc/legal/README.md deleted file mode 100644 index 56d72ae3859..00000000000 --- a/doc/legal/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Legal - -- [Corporate contributor license agreement](corporate_contributor_license_agreement.md) -- [Individual contributor license agreement](individual_contributor_license_agreement.md) diff --git a/doc/legal/corporate_contributor_license_agreement.md b/doc/legal/corporate_contributor_license_agreement.md deleted file mode 100644 index 13bf15fcf45..00000000000 --- a/doc/legal/corporate_contributor_license_agreement.md +++ /dev/null @@ -1,25 +0,0 @@ -# Corporate contributor license agreement - -You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions. - -1. Definitions. - - "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. - - "Contribution" shall mean the code, documentation or other original works of authorship expressly identified in Schedule B, as well as any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." - -2. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. - -3. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. - -4. You represent that You are legally entitled to grant the above license. You represent further that each employee of the Corporation designated on Schedule A below (or in a subsequent written modification to that Schedule) is authorized to submit Contributions on behalf of the Corporation. - -5. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). - -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]". - -8. It is your responsibility to notify GitLab B.V. when any change is required to the list of designated employees authorized to submit Contributions on behalf of the Corporation, or to the Corporation's Point of Contact with GitLab B.V.. - -This text is licensed under the [Creative Commons Attribution 3.0 License](http://creativecommons.org/licenses/by/3.0/) and the original source is the Google Open Source Programs Office. diff --git a/doc/legal/individual_contributor_license_agreement.md b/doc/legal/individual_contributor_license_agreement.md deleted file mode 100644 index 72b01433dd0..00000000000 --- a/doc/legal/individual_contributor_license_agreement.md +++ /dev/null @@ -1,25 +0,0 @@ -# Individual contributor license agreement - -You accept and agree to the following terms and conditions for Your present and future Contributions submitted to GitLab B.V.. Except for the license granted herein to GitLab B.V. and recipients of software distributed by GitLab B.V., You reserve all right, title, and interest in and to Your Contributions. - -1. Definitions. - - "You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this Agreement with GitLab B.V.. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. - - "Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to GitLab B.V. for inclusion in, or documentation of, any of the products owned or managed by GitLab B.V. (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to GitLab B.V. or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, GitLab B.V. for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." - -2. Grant of Copyright License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. - -3. Grant of Patent License. Subject to the terms and conditions of this Agreement, You hereby grant to GitLab B.V. and to recipients of software distributed by GitLab B.V. a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. - -4. You represent that you are legally entitled to grant the above license. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, that your employer has waived such rights for your Contributions to GitLab B.V., or that your employer has executed a separate Corporate CLA with GitLab B.V.. - -5. You represent that each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions. - -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]". - -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. - -This text is licensed under the [Creative Commons Attribution 3.0 License](http://creativecommons.org/licenses/by/3.0/) and the original source is the Google Open Source Programs Office. diff --git a/doc/logs/logs.md b/doc/logs/logs.md deleted file mode 100644 index ec0109a426f..00000000000 --- a/doc/logs/logs.md +++ /dev/null @@ -1,102 +0,0 @@ -## Log system -GitLab has advanced log system so everything is logging and you can analize your instance using various system log files. -In addition to system log files, GitLab Enterprise Edition comes with Audit Events. Find more about them [in Audit Events documentation](http://doc.gitlab.com/ee/administration/audit_events.html) - -System log files are typically plain text in a standard log file format. This guide talks about how to read and use these system log files. - -#### production.log -This file lives in `/var/log/gitlab/gitlab-rails/production.log` for omnibus package or in `/home/git/gitlab/logs/production.log` for installations from the source. - -This file contains information about all performed requests. You can see url and type of request, IP address and what exactly parts of code were involved to service this particular request. Also you can see all SQL request that have been performed and how much time it took. -This task is more useful for GitLab contributors and developers. Use part of this log file when you are going to report bug. - -``` -Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200 -Processing by Projects::TreeController#show as HTML - Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"} - - ... [CUT OUT] - - amespaces"."created_at" DESC, "namespaces"."id" DESC LIMIT 1[0m [["id", 26]] - [1m[35mCACHE (0.0ms)[0m SELECT "members".* FROM "members" WHERE "members"."source_type" = 'Project' AND "members"."type" IN ('ProjectMember') AND "members"."source_id" = $1 AND "members"."source_type" = $2 AND "members"."user_id" = 1 ORDER BY "members"."created_at" DESC, "members"."id" DESC LIMIT 1 [["source_id", 18], ["source_type", "Project"]] - [1m[36mCACHE (0.0ms)[0m [1mSELECT "members".* FROM "members" WHERE "members"."source_type" = 'Project' AND "members". - [1m[36m (1.4ms)[0m [1mSELECT COUNT(*) FROM "merge_requests" WHERE "merge_requests"."target_project_id" = $1 AND ("merge_requests"."state" IN ('opened','reopened'))[0m [["target_project_id", 18]] - Rendered layouts/nav/_project.html.haml (28.0ms) - Rendered layouts/_collapse_button.html.haml (0.2ms) - Rendered layouts/_flash.html.haml (0.1ms) - Rendered layouts/_page.html.haml (32.9ms) -Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms) -``` -In this example we can see that server processed HTTP request with url `/gitlabhq/yaml_db/tree/master` from IP 168.111.56.1 at 2015-02-12 19:34:53 +0200. Also we can see that request was processed by Projects::TreeController. - -#### application.log -This file lives in `/var/log/gitlab/gitlab-rails/application.log` for omnibus package or in `/home/git/gitlab/logs/application.log` for installations from the source. - -This log file helps you discover events happening in your instance such as user creation, project removing and so on. - -``` -October 06, 2014 11:56: User "Administrator" (admin@example.com) was created -October 06, 2014 11:56: Documentcloud created a new project "Documentcloud / Underscore" -October 06, 2014 11:56: Gitlab Org created a new project "Gitlab Org / Gitlab Ce" -October 07, 2014 11:25: User "Claudie Hodkiewicz" (nasir_stehr@olson.co.uk) was removed -October 07, 2014 11:25: Project "project133" was removed -``` -#### githost.log -This file lives in `/var/log/gitlab/gitlab-rails/githost.log` for omnibus package or in `/home/git/gitlab/logs/githost.log` for installations from the source. - -The GitLab has to interact with git repositories but in some rare cases something can go wrong and in this case you will know what exactly happened. This log file contains all failed requests from GitLab to git repository. In majority of cases this file will be useful for developers only. -``` -December 03, 2014 13:20 -> ERROR -> Command failed [1]: /usr/bin/git --git-dir=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq/.git --work-tree=/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/group184/gitlabhq merge --no-ff -mMerge branch 'feature_conflict' into 'feature' source/feature_conflict - -error: failed to push some refs to '/Users/vsizov/gitlab-development-kit/repositories/gitlabhq/gitlab_git.git' -``` - -#### satellites.log -This file lives in `/var/log/gitlab/gitlab-rails/satellites.log` for omnibus package or in `/home/git/gitlab/logs/satellites.log` for installations from the source. - -In some cases GitLab should perform write actions to git repository, for example when it is needed to merge the merge request or edit a file with online editor. If something went wrong you can look into this file to find out what exactly happened. -``` -October 07, 2014 11:36: Failed to create satellite for Chesley Weimann III / project1817 -October 07, 2014 11:36: PID: 1872: git clone /Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/repositories/conrad6841/gitlabhq.git /Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/gitlab-satellites/conrad6841/gitlabhq -October 07, 2014 11:36: PID: 1872: -> fatal: repository '/Users/vsizov/gitlab-development-kit/gitlab/tmp/tests/repositories/conrad6841/gitlabhq.git' does not exist -``` - -#### sidekiq.log -This file lives in `/var/log/gitlab/gitlab-rails/sidekiq.log` for omnibus package or in `/home/git/gitlab/logs/sidekiq.log` for installations from the source. - -GitLab uses background jobs for processing tasks which can take a long time. All information about processing these jobs are writing down to this file. -``` -2014-06-10T07:55:20Z 2037 TID-tm504 ERROR: /opt/bitnami/apps/discourse/htdocs/vendor/bundle/ruby/1.9.1/gems/redis-3.0.7/lib/redis/client.rb:228:in `read' -2014-06-10T18:18:26Z 14299 TID-55uqo INFO: Booting Sidekiq 3.0.0 with redis options {:url=>"redis://localhost:6379/0", :namespace=>"sidekiq"} -``` - -#### gitlab-shell.log -This file lives in `/var/log/gitlab/gitlab-shell/gitlab-shell.log` for omnibus package or in `/home/git/gitlab-shell/logs/sidekiq.log` for installations from the source. - -gitlab-shell is using by Gitlab for executing git commands and provide ssh access to git repositories. - -``` -I, [2015-02-13T06:17:00.671315 #9291] INFO -- : Adding project root/example.git at </var/opt/gitlab/git-data/repositories/root/dcdcdcdcd.git>. -I, [2015-02-13T06:17:00.679433 #9291] INFO -- : Moving existing hooks directory and simlinking global hooks directory for /var/opt/gitlab/git-data/repositories/root/example.git. -``` - -#### unicorn_stderr.log -This file lives in `/var/log/gitlab/unicorn/unicorn_stderr.log` for omnibus package or in `/home/git/gitlab/logs/unicorn_stderr.log` for installations from the source. - -Unicorn is a high-performance forking Web server which is used for serving GitLab application. You can look at this log, for example, if your application does not respond. This log cantains all information about state of unicorn processes at any given time. - -``` -I, [2015-02-13T06:14:46.680381 #9047] INFO -- : Refreshing Gem list -I, [2015-02-13T06:14:56.931002 #9047] INFO -- : listening on addr=127.0.0.1:8080 fd=12 -I, [2015-02-13T06:14:56.931381 #9047] INFO -- : listening on addr=/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket fd=13 -I, [2015-02-13T06:14:56.936638 #9047] INFO -- : master process ready -I, [2015-02-13T06:14:56.946504 #9092] INFO -- : worker=0 spawned pid=9092 -I, [2015-02-13T06:14:56.946943 #9092] INFO -- : worker=0 ready -I, [2015-02-13T06:14:56.947892 #9094] INFO -- : worker=1 spawned pid=9094 -I, [2015-02-13T06:14:56.948181 #9094] INFO -- : worker=1 ready -W, [2015-02-13T07:16:01.312916 #9094] WARN -- : #<Unicorn::HttpServer:0x0000000208f618>: worker (pid: 9094) exceeds memory limit (320626688 bytes > 247066940 bytes) -W, [2015-02-13T07:16:01.313000 #9094] WARN -- : Unicorn::WorkerKiller send SIGQUIT (pid: 9094) alive: 3621 sec (trial 1) -I, [2015-02-13T07:16:01.530733 #9047] INFO -- : reaped #<Process::Status: pid 9094 exit 0> worker=1 -I, [2015-02-13T07:16:01.534501 #13379] INFO -- : worker=1 spawned pid=13379 -I, [2015-02-13T07:16:01.534848 #13379] INFO -- : worker=1 ready -``` diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md deleted file mode 100644 index 1d5fd4c8b0d..00000000000 --- a/doc/markdown/markdown.md +++ /dev/null @@ -1,532 +0,0 @@ -# Markdown - -## Table of Contents - -**[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)** - -* [Newlines](#newlines) -* [Multiple underscores in words](#multiple-underscores-in-words) -* [URL auto-linking](#url-auto-linking) -* [Code and Syntax Highlighting](#code-and-syntax-highlighting) -* [Emoji](#emoji) -* [Special GitLab references](#special-gitlab-references) -* [Task lists](#task-lists) - -**[Standard Markdown](#standard-markdown)** - -* [Headers](#headers) -* [Emphasis](#emphasis) -* [Lists](#lists) -* [Links](#links) -* [Images](#images) -* [Blockquotes](#blockquotes) -* [Inline HTML](#inline-html) -* [Horizontal Rule](#horizontal-rule) -* [Line Breaks](#line-breaks) -* [Tables](#tables) - -**[References](#references)** - -## GitLab Flavored Markdown (GFM) - -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 - -- commit messages -- comments -- issues -- merge requests -- milestones -- wiki pages - -You can also use other rich text files in GitLab. You might have to install a dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. - -## Newlines - -GFM honors the markdown specification in how [paragraphs and line breaks are handled](http://daringfireball.net/projects/markdown/syntax#p). - -A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. -Line-breaks, or softreturns, are rendered if you end a line with two or more spaces - - Roses are red [followed by two or more spaces] - Violets are blue - - Sugar is sweet - -Roses are red -Violets are blue - -Sugar is sweet - -## Multiple underscores in words - -It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words. - - perform_complicated_task - do_this_and_do_that_and_another_thing - -perform_complicated_task -do_this_and_do_that_and_another_thing - -## URL auto-linking - -GFM will autolink standard URLs you copy and paste into your text. So if you want to link to a URL (instead of a textural link), you can simply put the URL in verbatim and it will be turned into a link to that URL. - - http://www.google.com - -http://www.google.com - -## Code and Syntax Highlighting - -Blocks of code are either fenced by lines with three back-ticks <code>```</code>, or are indented with four spaces. Only the fenced code blocks support syntax highlighting. - -```no-highlight -Inline `code` has `back-ticks around` it. -``` - -Inline `code` has `back-ticks around` it. - -Example: - - ```javascript - var s = "JavaScript syntax highlighting"; - alert(s); - ``` - - ```python - def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s - ``` - - ```ruby - require 'redcarpet' - markdown = Redcarpet.new("Hello World!") - puts markdown.to_html - ``` - - ``` - No language indicated, so no syntax highlighting. - s = "There is no highlighting for this." - But let's throw in a <b>tag</b>. - ``` - -becomes: - -```javascript -var s = "JavaScript syntax highlighting"; -alert(s); -``` - -```python -def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s -``` - -```ruby -require 'redcarpet' -markdown = Redcarpet.new("Hello World!") -puts markdown.to_html -``` - -``` -No language indicated, so no syntax highlighting. -s = "There is no highlighting for this." -But let's throw in a <b>tag</b>. -``` - -## Emoji - - Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - - :zap: You can use emoji anywhere GFM is supported. :v: - - You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - - If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes. - - Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup: - -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - -:zap: You can use emoji anywhere GFM is supported. :v: - -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - -If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes. - -Consult the [Emoji Cheat Sheet](http://emoji.codes) for a list of all supported emoji codes. :thumbsup: - -## Special GitLab References - -GFM recognized special references. - -You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project. - -GFM will turn that reference into a link so you can navigate between them easily. - -GFM will recognize the following: - -- @foo : for specific team members or groups -- @all : for the whole team -- #123 : for issues -- !123 : for merge requests -- $123 : for snippets -- 1234567 : for commits -- \[file\](path/to/file) : for file references - -GFM also recognizes references to commits, issues, and merge requests in other projects: - -- namespace/project#123 : for issues -- namespace/project!123 : for merge requests -- namespace/project@1234567 : for commits - -## Task Lists - -You can add task lists to merge request and issue descriptions to keep track of to-do items. To create a task, add an unordered list to the description in an issue or merge request, formatted like so: - -```no-highlight -* [x] Completed task -* [ ] Unfinished task - * [x] Nested task -``` - -Task lists can only be created in descriptions, not in titles or comments. Task item state can be managed by editing the description's Markdown or by clicking the rendered checkboxes. - -# Standard Markdown - -## Headers - -```no-highlight -# H1 -## H2 -### H3 -#### H4 -##### H5 -###### H6 - -Alternatively, for H1 and H2, an underline-ish style: - -Alt-H1 -====== - -Alt-H2 ------- -``` - -# H1 -## H2 -### H3 -#### H4 -##### H5 -###### H6 - -Alternatively, for H1 and H2, an underline-ish style: - -Alt-H1 -====== - -Alt-H2 ------- - -### Header IDs and links - -All markdown rendered headers automatically get IDs, except for comments. - -On hover a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else. - -The IDs are generated from the content of the header according to the following rules: - -1. remove the heading hashes `#` and process the rest of the line as it would be processed if it were not a header -2. from the result, remove all HTML tags, but keep their inner content -3. convert all characters to lowercase -4. convert all characters except `[a-z0-9_-]` into hyphens `-` -5. transform multiple adjacent hyphens into a single hyphen -6. remove trailing and heading hyphens - -For example: - -``` -###### ..Ab_c-d. e [anchor](URL) .. -``` - -which renders as: - -###### ..Ab_c-d. e [anchor](URL) .. - -will first be converted by step 1) into a string like: - -``` -..Ab_c-d. e <a href="URL">anchor</a> <img src="URL" alt="alt text"/>.. -``` - -After removing the tags in step 2) we get: - -``` -..Ab_c-d. e anchor .. -``` - -And applying all the other steps gives the id: - -``` -ab_c-d-e-anchor -``` - -Note in particular how: - -- for markdown anchors `[text](URL)`, only the `text` is used -- markdown images `` are completely ignored - -## Emphasis - -```no-highlight -Emphasis, aka italics, with *asterisks* or _underscores_. - -Strong emphasis, aka bold, with **asterisks** or __underscores__. - -Combined emphasis with **asterisks and _underscores_**. - -Strikethrough uses two tildes. ~~Scratch this.~~ -``` - -Emphasis, aka italics, with *asterisks* or _underscores_. - -Strong emphasis, aka bold, with **asterisks** or __underscores__. - -Combined emphasis with **asterisks and _underscores_**. - -Strikethrough uses two tildes. ~~Scratch this.~~ - -## Lists - -```no-highlight -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. - - Some text that should be aligned with the above item. - -* Unordered list can use asterisks -- Or minuses -+ Or pluses -``` - -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. - - Some text that should be aligned with the above item. - -* Unordered list can use asterisks -- Or minuses -+ Or pluses - -## Links - -There are two ways to create links, inline-style and reference-style. - - [I'm an inline-style link](https://www.google.com) - - [I'm a reference-style link][Arbitrary case-insensitive reference text] - - [I'm a relative reference to a repository file](LICENSE) - - [You can use numbers for reference-style link definitions][1] - - Or leave it empty and use the [link text itself][] - - Some text to show that the reference links can follow later. - - [arbitrary case-insensitive reference text]: https://www.mozilla.org - [1]: http://slashdot.org - [link text itself]: http://www.reddit.com - -[I'm an inline-style link](https://www.google.com) - -[I'm a reference-style link][Arbitrary case-insensitive reference text] - -[I'm a relative reference to a repository file](LICENSE) - -[You can use numbers for reference-style link definitions][1] - -Or leave it empty and use the [link text itself][] - -Some text to show that the reference links can follow later. - -[arbitrary case-insensitive reference text]: https://www.mozilla.org -[1]: http://slashdot.org -[link text itself]: http://www.reddit.com - -**Note** - -Relative links do not allow referencing project files in a wiki page or wiki page in a project file. The reason for this is that, in GitLab, wiki is always a separate git repository. For example: - -`[I'm a reference-style link][style]` - -will point the link to `wikis/style` when the link is inside of a wiki markdown file. - -## Images - - Here's our logo (hover to see the title text): - - Inline-style: -  - - Reference-style: - ![alt text1][logo] - - [logo]: assets/logo-white.png - -Here's our logo: - -Inline-style: - - - -Reference-style: - -![alt text][logo] - -[logo]: /assets/logo-white.png - -## Blockquotes - -```no-highlight -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. - -Quote break. - -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. -``` - -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. - -Quote break. - -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. - -## Inline HTML - -You can also use raw HTML in your Markdown, and it'll mostly work pretty well. - -See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` whitelist, GitLab allows the `class`, `id`, and `style` attributes. - -```no-highlight -<dl> - <dt>Definition list</dt> - <dd>Is something people use sometimes.</dd> - - <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd> -</dl> -``` - -<dl> - <dt>Definition list</dt> - <dd>Is something people use sometimes.</dd> - - <dt>Markdown in HTML</dt> - <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd> -</dl> - -## Horizontal Rule - -``` -Three or more... - ---- - -Hyphens - -*** - -Asterisks - -___ - -Underscores -``` - -Three or more... - ---- - -Hyphens - -*** - -Asterisks - -___ - -Underscores - -## Line Breaks - -My basic recommendation for learning how line breaks work is to experiment and discover -- hit <Enter> once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend. - -Here are some things to try out: - -``` -Here's a line for us to start with. - -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. - -This line is also a separate paragraph, but... -This line is only separated by a single newline, so it's a separate line in the *same paragraph*. - -This line is also a separate paragraph, and... -This line is on its own line, because the previous line ends with two -spaces. -``` - -Here's a line for us to start with. - -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. - -This line is also begins a separate paragraph, but... -This line is only separated by a single newline, so it's a separate line in the *same paragraph*. - -This line is also a separate paragraph, and... -This line is on its own line, because the previous line ends with two -spaces. - -## Tables - -Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them. - -``` -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | -``` - -Code above produces next output: - -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | - -**Note** - -The row of dashes between the table header and body must have at least three dashes in each column. - -## References - -- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- The [Markdown Syntax Guide](http://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. diff --git a/doc/operations/README.md b/doc/operations/README.md deleted file mode 100644 index f1456c6c8e2..00000000000 --- a/doc/operations/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# GitLab operations - -- [Sidekiq MemoryKiller](sidekiq_memory_killer.md) -- [Cleaning up Redis sessions](cleaning_up_redis_sessions.md) diff --git a/doc/operations/cleaning_up_redis_sessions.md b/doc/operations/cleaning_up_redis_sessions.md deleted file mode 100644 index 93521e976d5..00000000000 --- a/doc/operations/cleaning_up_redis_sessions.md +++ /dev/null @@ -1,52 +0,0 @@ -# Cleaning up stale Redis sessions - -Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis. -Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If -you have been running a large GitLab server (thousands of users) since before -GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis -database after you upgrade to GitLab 7.3. You can also perform a cleanup while -still running GitLab 7.2 or older, but in that case new stale sessions will -start building up again after you clean up. - -In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte -hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with -GitLab 7.3.0, the keys are -prefixed with 'session:gitlab:', so they would look like -'session:gitlab:976aa289e2189b17d7ef525a6702ace9'. Below we describe how to -remove the keys in the old format. - -First we define a shell function with the proper Redis connection details. - -``` -rcli() { - # This example works for Omnibus installations of GitLab 7.3 or newer. For an - # installation from source you will have to change the socket path and the - # path to redis-cli. - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" -} - -# test the new shell function; the response should be PONG -rcli ping -``` - -Now we do a search to see if there are any session keys in the old format for -us to clean up. - -``` -# returns the number of old-format session keys in Redis -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l -``` - -If the number is larger than zero, you can proceed to expire the keys from -Redis. If the number is zero there is nothing to clean up. - -``` -# Tell Redis to expire each matched key after 600 seconds. -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli -# This will print '(integer) 1' for each key that gets expired. -``` - -Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis -background save interval) your Redis database will be compacted. If you are -still using GitLab 7.2, users who are not clicking around in GitLab during the -10 minute expiry window will be signed out of GitLab. diff --git a/doc/operations/sidekiq_memory_killer.md b/doc/operations/sidekiq_memory_killer.md deleted file mode 100644 index 867b01b0d5a..00000000000 --- a/doc/operations/sidekiq_memory_killer.md +++ /dev/null @@ -1,38 +0,0 @@ -# Sidekiq MemoryKiller - -The GitLab Rails application code suffers from memory leaks. For web requests -this problem is made manageable using -[unicorn-worker-killer](https://github.com/kzk/unicorn-worker-killer) which -restarts Unicorn worker processes in between requests when needed. The Sidekiq -MemoryKiller applies the same approach to the Sidekiq processes used by GitLab -to process background jobs. - -Unlike unicorn-worker-killer, which is enabled by default for all GitLab -installations since GitLab 6.4, the Sidekiq MemoryKiller is enabled by default -_only_ for Omnibus packages. The reason for this is that the MemoryKiller -relies on Runit to restart Sidekiq after a memory-induced shutdown and GitLab -installations from source do not all use Runit or an equivalent. - -With the default settings, the MemoryKiller will cause a Sidekiq restart no -more often than once every 15 minutes, with the restart causing about one -minute of delay for incoming background jobs. - -## Configuring the MemoryKiller - -The MemoryKiller is controlled using environment variables. - -- `SIDEKIQ_MEMORY_KILLER_MAX_RSS`: if this variable is set, and its value is - greater than 0, then after each Sidekiq job, the MemoryKiller will check the - RSS of the Sidekiq process that executed the job. If the RSS of the Sidekiq - process (expressed in kilobytes) exceeds SIDEKIQ_MEMORY_KILLER_MAX_RSS, a - delayed shutdown is triggered. The default value for Omnibus packages is set - [in the omnibus-gitlab - repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/attributes/default.rb). -- `SIDEKIQ_MEMORY_KILLER_GRACE_TIME`: defaults 900 seconds (15 minutes). When - a shutdown is triggered, the Sidekiq process will keep working normally for - another 15 minutes. -- `SIDEKIQ_MEMORY_KILLER_SHUTDOWN_WAIT`: defaults to 30 seconds. When the grace - time has expired, the MemoryKiller tells Sidekiq to stop accepting new jobs. - Existing jobs get 30 seconds to finish. After that, the MemoryKiller tells - Sidekiq to shut down, and an external supervision mechanism (e.g. Runit) must - restart Sidekiq. diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md deleted file mode 100644 index 8cfa7f9c876..00000000000 --- a/doc/permissions/permissions.md +++ /dev/null @@ -1,55 +0,0 @@ -# Permissions - -Users have different abilities depending on the access level they have in a particular group or project. - -If a user is both in a project group and in the project itself, the highest permission level is used. - -If a user is a GitLab administrator they receive all permissions. - -## Project - -| Action | Guest | Reporter | Developer | Master | Owner | -|---------------------------------------|---------|------------|-------------|----------|--------| -| Create new issue | âś“ | âś“ | âś“ | âś“ | âś“ | -| Leave comments | âś“ | âś“ | âś“ | âś“ | âś“ | -| Pull project code | | âś“ | âś“ | âś“ | âś“ | -| Download project | | âś“ | âś“ | âś“ | âś“ | -| Create code snippets | | âś“ | âś“ | âś“ | âś“ | -| Create new merge request | | | âś“ | âś“ | âś“ | -| Create new branches | | | âś“ | âś“ | âś“ | -| Push to non-protected branches | | | âś“ | âś“ | âś“ | -| Force push to non-protected branches | | | âś“ | âś“ | âś“ | -| Remove non-protected branches | | | âś“ | âś“ | âś“ | -| Add tags | | | âś“ | âś“ | âś“ | -| Write a wiki | | | âś“ | âś“ | âś“ | -| Manage issue tracker | | | âś“ | âś“ | âś“ | -| Manage labels | | | âś“ | âś“ | âś“ | -| Create new milestones | | | | âś“ | âś“ | -| Add new team members | | | | âś“ | âś“ | -| Push to protected branches | | | | âś“ | âś“ | -| Enable/disable branch protection | | | | âś“ | âś“ | -| Turn on/off prot. branch push for devs| | | | âś“ | âś“ | -| Rewrite/remove git tags | | | | âś“ | âś“ | -| Edit project | | | | âś“ | âś“ | -| Add deploy keys to project | | | | âś“ | âś“ | -| Configure project hooks | | | | âś“ | âś“ | -| Switch visibility level | | | | | âś“ | -| Transfer project to another namespace | | | | | âś“ | -| Remove project | | | | | âś“ | -| Force push to protected branches | | | | | | -| Remove protected branches | | | | | | - -## Group - -In order for a group to appear as public and be browsable, it must contain at -least one public project. - -Any user can remove themselves from a group, unless they are the last Owner of the group. - -| Action | Guest | Reporter | Developer | Master | Owner | -|-------------------------|-------|----------|-----------|--------|-------| -| Browse group | âś“ | âś“ | âś“ | âś“ | âś“ | -| Edit group | | | | | âś“ | -| Create project in group | | | | âś“ | âś“ | -| Manage group members | | | | | âś“ | -| Remove group | | | | | âś“ | diff --git a/doc/project_services/bamboo.md b/doc/project_services/bamboo.md deleted file mode 100644 index 51668128c62..00000000000 --- a/doc/project_services/bamboo.md +++ /dev/null @@ -1,60 +0,0 @@ -# Atlassian Bamboo CI Service - -GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project will trigger a build in Bamboo automatically. -Merge requests will also display CI status showing whether the build is pending, -failed, or completed successfully. It also provides a link to the Bamboo build -page for more information. - -Bamboo doesn't quite provide the same features as a traditional build system when -it comes to accepting webhooks and commit data. There are a few things that -need to be configured in a Bamboo build plan before GitLab can integrate. - -## Setup - -### Complete these steps in Bamboo: - -1. Navigate to a Bamboo build plan and choose 'Configure plan' from the 'Actions' -dropdown. -1. Select the 'Triggers' tab. -1. Click 'Add trigger'. -1. Enter a description such as 'GitLab trigger' -1. Choose 'Repository triggers the build when changes are committed' -1. Check one or more repositories checkboxes -1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a -whitelist of IP addresses that are allowed to trigger Bamboo builds. -1. Save the trigger. -1. In the left pane, select a build stage. If you have multiple build stages -you want to select the last stage that contains the git checkout task. -1. Select the 'Miscellaneous' tab. -1. Under 'Pattern Match Labelling' put '${bamboo.repository.revision.number}' -in the 'Labels' box. -1. Save - -Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo -service in GitLab - -### Complete these steps in GitLab: - -1. Navigate to the project you want to configure to trigger builds. -1. Select 'Settings' in the top navigation. -1. Select 'Services' in the left navigation. -1. Click 'Atlassian Bamboo CI' -1. Select the 'Active' checkbox. -1. Enter the base URL of your Bamboo server. 'https://bamboo.example.com' -1. Enter the build key from your Bamboo build plan. Build keys are a short, -all capital letter, identifier that is unique. It will be something like PR-BLD -1. If necessary, enter username and password for a Bamboo user that has -access to trigger the build plan. Leave these fields blank if you do not require -authentication. -1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' -will actually trigger a build in Bamboo. - -## Troubleshooting - -If builds are not triggered, these are a couple of things to keep in mind. - -1. Ensure you entered the right GitLab IP address in Bamboo under 'Trigger -IP addresses'. -1. Remember that GitLab only triggers builds on push events. A commit via the -web interface will not trigger CI currently. diff --git a/doc/project_services/hipchat.md b/doc/project_services/hipchat.md deleted file mode 100644 index 021a93a288f..00000000000 --- a/doc/project_services/hipchat.md +++ /dev/null @@ -1,54 +0,0 @@ -# Atlassian HipChat - -GitLab provides a way to send HipChat notifications upon a number of events, -such as when a user pushes code, creates a branch or tag, adds a comment, and -creates a merge request. - -## Setup - -GitLab requires the use of a HipChat v2 API token to work. v1 tokens are -not supported at this time. Note the differences between v1 and v2 tokens: - -HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 -token is allowed to send messages to *any* room. - -HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room admin page. By design, these are lightweight tokens that -allow GitLab to send messages only to *one* room. - -### Complete these steps in HipChat: - -1. Go to: https://admin.hipchat.com/admin -1. Click on "Group Admin" -> "Integrations". -1. Find "Build Your Own!" and click "Create". -1. Select the desired room, name the integration "GitLab", and click "Create". -1. In the "Send messages to this room by posting this URL" column, you should -see a URL in the format: - -``` - https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> -``` - -HipChat is now ready to accept messages from GitLab. Next, set up the HipChat -service in GitLab. - -### Complete these steps in GitLab: - -1. Navigate to the project you want to configure for notifications. -1. Select "Settings" in the top navigation. -1. Select "Services" in the left navigation. -1. Click "HipChat". -1. Select the "Active" checkbox. -1. Insert the `token` field from the URL into the `Token` field on the Web page. -1. Insert the `room` field from the URL into the `Room` field on the Web page. -1. Save or optionally click "Test Settings". - -## Troubleshooting - -If you do not see notifications, make sure you are using a HipChat v2 API -token, not a v1 token. - -Note that the v2 token is tied to a specific room. If you want to be able to -specify arbitrary rooms, you can create an API token for a specific user in -HipChat under "Account settings" and "API access". Use the `XXX` value under -`auth_token=XXX`. diff --git a/doc/project_services/irker.md b/doc/project_services/irker.md deleted file mode 100644 index 780a45bca20..00000000000 --- a/doc/project_services/irker.md +++ /dev/null @@ -1,46 +0,0 @@ -# Irker IRC Gateway - -GitLab provides a way to push update messages to an Irker server. When -configured, pushes to a project will trigger the service to send data directly -to the Irker server. - -See the project homepage for further info: http://www.catb.org/esr/irker/ - -## Needed setup - -You will first need an Irker daemon. You can download the Irker code from its -gitorious repository on https://gitorious.org/irker: `git clone -git@gitorious.org:irker/irker.git`. Once you have downloaded the code, you can -run the python script named `irkerd`. This script is the gateway script, it acts -both as an IRC client, for sending messages to an IRC server obviously, and as a -TCP server, for receiving messages from the GitLab service. - -If the Irker server runs on the same machine, you are done. If not, you will -need to follow the firsts steps of the next section. - -## Optional setup - -In the `app/models/project_services/irker_service.rb` file, you can modify some -options in the `initialize_settings` method: -- **server_ip** (defaults to `localhost`): the server IP address where the -`irkerd` daemon runs; -- **server_port** (defaults to `6659`): the server port of the `irkerd` daemon; -- **max_channels** (defaults to `3`): the maximum number of recipients the -client is authorized to join, per project; -- **default_irc_uri** (no default) : if this option is set, it has to be in the -format `irc[s]://domain.name` and will be prepend to each and every channel -provided by the user which is not a full URI. - -If the Irker server and the GitLab application do not run on the same host, you -will **need** to setup at least the **server_ip** option. - -## Note on Irker recipients - -Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you will need to add -`,isnick` avec the channel name, in this form: `Aorimn,isnick`. In this latter -case, `Aorimn` is treated as a nick and no more as a channel name. - -Irker can also join password-protected channels. Users need to append -`?key=thesecretpassword` to the chan name. - diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md deleted file mode 100644 index 03937d20728..00000000000 --- a/doc/project_services/project_services.md +++ /dev/null @@ -1,20 +0,0 @@ -# Project Services - -__Project integrations with external services for continuous integration and more.__ - -## 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 diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md deleted file mode 100644 index bd439f7c6f3..00000000000 --- a/doc/public_access/public_access.md +++ /dev/null @@ -1,44 +0,0 @@ -# Public access - -GitLab allows you to open selected projects to be accessed **publicly** or **internally**. - -Projects with either of these visibility levels will be listed in the [public access directory](/public). - -Internal projects will only be available to authenticated users. - -## Public projects - -Public projects can be cloned **without any** authentication. - -It will also be listed on the [public access directory](/public). - -**Any logged in user** will have [Guest](../permissions/permissions) permissions on the repository. - -## Internal projects - -Internal projects can be cloned by any logged in user. - -It will also be listed on the [public access directory](/public) for logged in users. - -Any logged in user will have [Guest](../permissions/permissions) permissions on the repository. - -## How to change project visibility - -1. Go to your project dashboard -1. Click on the "Edit" tab -1. Change "Visibility Level" - -## Visibility of users - -The public page of users, located at `/u/username` is visible if either: - -- You are logged in. -- You are logged out, and the target user is authorized to (is Guest, Reporter, etc.) at least one public project. - -Otherwise, you will be redirected to the sign in page. - -When visiting the public page of an user, you will only see listed projects which you can view yourself. - -## Restricting the use of public or internal projects - -In the Admin area under Settings you can disable public projects or public and internal projects for the entire GitLab installation to prevent people making code public by accident. The restricted visibility settings do not apply to admin users. diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md deleted file mode 100644 index 770b7a70fe0..00000000000 --- a/doc/raketasks/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Rake tasks - -- [Backup restore](backup_restore.md) -- [Cleanup](cleanup.md) -- [Features](features.md) -- [Maintenance](maintenance.md) and self-checks -- [User management](user_management.md) -- [Web hooks](web_hooks.md) -- [Import](import.md) of git repositories in bulk diff --git a/doc/raketasks/backup_hrz.png b/doc/raketasks/backup_hrz.png Binary files differdeleted file mode 100644 index 03e50df1d76..00000000000 --- a/doc/raketasks/backup_hrz.png +++ /dev/null diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md deleted file mode 100644 index 2e41fad89e7..00000000000 --- a/doc/raketasks/backup_restore.md +++ /dev/null @@ -1,240 +0,0 @@ -# Backup restore - - - -## Create a backup of the GitLab system - -A backup creates an archive file that contains the database, all repositories and all attachments. -This archive will be saved in backup_path (see `config/gitlab.yml`). -The filename will be `[TIMESTAMP]_gitlab_backup.tar`. This timestamp can be used to restore an specific backup. -You can only restore a backup to exactly the same version of GitLab that you created it on, for example 7.2.1. - -``` -# use this command if you've installed GitLab with the Omnibus package -sudo gitlab-rake gitlab:backup:create - -# if you've installed GitLab from source -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -Also you can choose what should be backed up by adding environment variable SKIP. Available options: db, -uploads (attachments), repositories. Use a comma to specify several options at the same time. - -``` -sudo gitlab-rake gitlab:backup:create SKIP=db,uploads -``` - -Example output: - -``` -Dumping database tables: -- Dumping table events... [DONE] -- Dumping table issues... [DONE] -- Dumping table keys... [DONE] -- Dumping table merge_requests... [DONE] -- Dumping table milestones... [DONE] -- Dumping table namespaces... [DONE] -- Dumping table notes... [DONE] -- Dumping table projects... [DONE] -- Dumping table protected_branches... [DONE] -- Dumping table schema_migrations... [DONE] -- Dumping table services... [DONE] -- Dumping table snippets... [DONE] -- Dumping table taggings... [DONE] -- Dumping table tags... [DONE] -- Dumping table users... [DONE] -- Dumping table users_projects... [DONE] -- Dumping table web_hooks... [DONE] -- Dumping table wikis... [DONE] -Dumping repositories: -- Dumping repository abcd... [DONE] -Creating backup archive: $TIMESTAMP_gitlab_backup.tar [DONE] -Deleting tmp directories...[DONE] -Deleting old backups... [SKIPPING] -``` - -## Upload backups to remote (cloud) storage - -Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates. -It uses the [Fog library](http://fog.io/) to perform the upload. -In the example below we use Amazon S3 for storage. -But Fog also lets you use [other storage providers](http://fog.io/storage/). - -For omnibus packages: - -```ruby -gitlab_rails['backup_upload_connection'] = { - 'provider' => 'AWS', - 'region' => 'eu-west-1', - 'aws_access_key_id' => 'AKIAKIAKI', - 'aws_secret_access_key' => 'secret123' -} -gitlab_rails['backup_upload_remote_directory'] = 'my.s3.bucket' -``` - -For installations from source: - -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: AWS - region: eu-west-1 - aws_access_key_id: AKIAKIAKI - aws_secret_access_key: 'secret123' - # The remote 'directory' to store your backups. For S3, this would be the bucket name. - remote_directory: 'my.s3.bucket' -``` - -If you are uploading your backups to S3 you will probably want to create a new -IAM user with restricted access rights. To give the upload user access only for -uploading backups create the following IAM profile, replacing `my.s3.bucket` -with the name of your bucket: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "Stmt1412062044000", - "Effect": "Allow", - "Action": [ - "s3:AbortMultipartUpload", - "s3:GetBucketAcl", - "s3:GetBucketLocation", - "s3:GetObject", - "s3:GetObjectAcl", - "s3:ListBucketMultipartUploads", - "s3:PutObject", - "s3:PutObjectAcl" - ], - "Resource": [ - "arn:aws:s3:::my.s3.bucket/*" - ] - }, - { - "Sid": "Stmt1412062097000", - "Effect": "Allow", - "Action": [ - "s3:GetBucketLocation", - "s3:ListAllMyBuckets" - ], - "Resource": [ - "*" - ] - }, - { - "Sid": "Stmt1412062128000", - "Effect": "Allow", - "Action": [ - "s3:ListBucket" - ], - "Resource": [ - "arn:aws:s3:::my.s3.bucket" - ] - } - ] -} -``` - -## Storing configuration files - -Please be informed that a backup does not store your configuration files. -If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). -If you have a cookbook installation there should be a copy of your configuration in Chef. -If you have an installation from source, please consider backing up your `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). - -## Restore a previously created backup - -You can only restore a backup to exactly the same version of GitLab that you created it on, for example 7.2.1. - -``` -# Omnibus package installation -sudo gitlab-rake gitlab:backup:restore - -# installation from source -bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -Options: - -``` -BACKUP=timestamp_of_backup (required if more than one backup exists) -``` - -Example output: - -``` -Unpacking backup... [DONE] -Restoring database tables: --- create_table("events", {:force=>true}) - -> 0.2231s -[...] -- Loading fixture events...[DONE] -- Loading fixture issues...[DONE] -- Loading fixture keys...[SKIPPING] -- Loading fixture merge_requests...[DONE] -- Loading fixture milestones...[DONE] -- Loading fixture namespaces...[DONE] -- Loading fixture notes...[DONE] -- Loading fixture projects...[DONE] -- Loading fixture protected_branches...[SKIPPING] -- Loading fixture schema_migrations...[DONE] -- Loading fixture services...[SKIPPING] -- Loading fixture snippets...[SKIPPING] -- Loading fixture taggings...[SKIPPING] -- Loading fixture tags...[SKIPPING] -- Loading fixture users...[DONE] -- Loading fixture users_projects...[DONE] -- Loading fixture web_hooks...[SKIPPING] -- Loading fixture wikis...[SKIPPING] -Restoring repositories: -- Restoring repository abcd... [DONE] -Deleting tmp directories...[DONE] -``` - -## Configure cron to make daily backups - -For Omnibus package installations, see https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#scheduling-a-backup . - -For installation from source: -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups -sudo -u git crontab -e # Edit the crontab for the git user -``` - -Add the following lines at the bottom: - -``` -# Create a full backup of the GitLab repositories and SQL database every day at 4am -0 4 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1 -``` - -The `CRON=1` environment setting tells the backup script to suppress all progress output if there are no errors. -This is recommended to reduce cron spam. - -## Alternative backup strategies - -If your GitLab server contains a lot of Git repository data you may find the GitLab backup script to be too slow. -In this case you can consider using filesystem snapshots as part of your backup strategy. - -Example: Amazon EBS - -> A GitLab server using omnibus-gitlab hosted on Amazon AWS. -> An EBS drive containing an ext4 filesystem is mounted at `/var/opt/gitlab`. -> In this case you could make an application backup by taking an EBS snapshot. -> The backup includes all repositories, uploads and Postgres data. - -Example: LVM snapshots + rsync - -> A GitLab server using omnibus-gitlab, with an LVM logical volume mounted at `/var/opt/gitlab`. -> Replicating the `/var/opt/gitlab` directory using rsync would not be reliable because too many files would change while rsync is running. -> Instead of rsync-ing `/var/opt/gitlab`, we create a temporary LVM snapshot, which we mount as a read-only filesystem at `/mnt/gitlab_backup`. -> Now we can have a longer running rsync job which will create a consistent replica on the remote server. -> The replica includes all repositories, uploads and Postgres data. - -If you are running GitLab on a virtualized server you can possibly also create VM snapshots of the entire GitLab server. -It is not uncommon however for a VM snapshot to require you to power down the server, so this approach is probably of limited practical use. diff --git a/doc/raketasks/cleanup.md b/doc/raketasks/cleanup.md deleted file mode 100644 index 96d67f7b5d6..00000000000 --- a/doc/raketasks/cleanup.md +++ /dev/null @@ -1,23 +0,0 @@ -# Cleanup - -## Remove garbage from filesystem. Important! Data loss! - -Remove namespaces(dirs) from `/home/git/repositories` if they don't exist in GitLab database. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:cleanup:dirs - -# installation from source -bundle exec rake gitlab:cleanup:dirs RAILS_ENV=production -``` - -Remove repositories (global only for now) from `/home/git/repositories` if they don't exist in GitLab database. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:cleanup:repos - -# installation from source -bundle exec rake gitlab:cleanup:repos RAILS_ENV=production -``` diff --git a/doc/raketasks/features.md b/doc/raketasks/features.md deleted file mode 100644 index f9a46193547..00000000000 --- a/doc/raketasks/features.md +++ /dev/null @@ -1,20 +0,0 @@ -# Features - -## Enable usernames and namespaces for user projects - -This command will enable the namespaces feature introduced in v4.0. It will move every project in its namespace folder. - -Note: - -- Because the **repository location will change**, you will need to **update all your git URLs** to point to the new location. -- Username can be changed at [Profile / Account](/profile/account) - -**Example:** - -Old path: `git@example.org:myrepo.git` - -New path: `git@example.org:username/myrepo.git` or `git@example.org:groupname/myrepo.git` - -``` -bundle exec rake gitlab:enable_namespaces RAILS_ENV=production -``` diff --git a/doc/raketasks/import.md b/doc/raketasks/import.md deleted file mode 100644 index 8a38937062e..00000000000 --- a/doc/raketasks/import.md +++ /dev/null @@ -1,68 +0,0 @@ -# Import bare repositories into your GitLab instance - -## Notes - -- The owner of the project will be the first admin -- The groups will be created as needed -- The owner of the group will be the first admin -- Existing projects will be skipped - -## How to use - -### Create a new folder inside the git repositories path. This will be the name of the new group. - -- For omnibus-gitlab, it is located at: `/var/opt/gitlab/git-data/repositories` by default, unless you changed -it in the `/etc/gitlab/gitlab.rb` file. -- For installations from source, it is usually located at: `/home/git/repositories` or you can see where -your repositories are located by looking at `config/gitlab.yml` under the `gitlab_shell => repos_path` entry. - -New folder needs to have git user ownership and read/write/execute access for git user and its group: - -``` -sudo -u git mkdir /var/opt/gitlab/git-data/repositories/new_group -``` - -If you are using an installation from source, replace `/var/opt/gitlab/git-data` -with `/home/git`. - -### Copy your bare repositories inside this newly created folder: - -``` -sudo cp -r /old/git/foo.git /var/opt/gitlab/git-data/repositories/new_group/ - -# Do this once when you are done copying git repositories -sudo chown -R git:git /var/opt/gitlab/git-data/repositories/new_group/ -``` - -`foo.git` needs to be owned by the git user and git users group. - -If you are using an installation from source, replace `/var/opt/gitlab/git-data` -with `/home/git`. - -### Run the command below depending on your type of installation: - -#### Omnibus Installation - -``` -$ sudo gitlab-rake gitlab:import:repos -``` - -#### Installation from source - -Before running this command you need to change the directory to where your GitLab installation is located: - -``` -$ cd /home/git/gitlab -$ sudo -u git -H bundle exec rake gitlab:import:repos RAILS_ENV=production -``` - -#### Example output - -``` -Processing abcd.git - * Created abcd (abcd.git) -Processing group/xyz.git - * Created Group group (2) - * Created xyz (group/xyz.git) -[...] -``` diff --git a/doc/raketasks/maintenance.md b/doc/raketasks/maintenance.md deleted file mode 100644 index 41a994f3f68..00000000000 --- a/doc/raketasks/maintenance.md +++ /dev/null @@ -1,178 +0,0 @@ -# Maintenance - -## Gather information about GitLab and the system it runs on - -This command gathers information about your GitLab installation and the System it runs on. These may be useful when asking for help or reporting issues. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:env:info - -# installation from source -bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -Example output: - -``` -System information -System: Debian 7.8 -Current User: git -Using RVM: no -Ruby Version: 2.1.5p273 -Gem Version: 2.4.3 -Bundler Version: 1.7.6 -Rake Version: 10.3.2 -Sidekiq Version: 2.17.8 - -GitLab information -Version: 7.7.1 -Revision: 41ab9e1 -Directory: /home/git/gitlab -DB Adapter: postgresql -URL: https://gitlab.example.com -HTTP Clone URL: https://gitlab.example.com/some-project.git -SSH Clone URL: git@gitlab.example.com:some-project.git -Using LDAP: no -Using Omniauth: no - -GitLab Shell -Version: 2.4.1 -Repositories: /home/git/repositories/ -Hooks: /home/git/gitlab-shell/hooks/ -Git: /usr/bin/git -``` - -## Check GitLab configuration - -Runs the following rake tasks: - -- `gitlab:env:check` -- `gitlab:gitlab_shell:check` -- `gitlab:sidekiq:check` -- `gitlab:app:check` - -It will check that each component was setup according to the installation guide and suggest fixes for issues found. - -You may also have a look at our [Trouble Shooting Guide](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide). - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:check - -# installation from source -bundle exec rake gitlab:check RAILS_ENV=production -``` - -NOTE: Use SANITIZE=true for gitlab:check if you want to omit project names from the output. - -Example output: - -``` -Checking Environment ... - -Git configured for git user? ... yes -Has python2? ... yes -python2 is supported version? ... yes - -Checking Environment ... Finished - -Checking GitLab Shell ... - -GitLab Shell version? ... OK (1.2.0) -Repo base directory exists? ... yes -Repo base directory is a symlink? ... no -Repo base owned by git:git? ... yes -Repo base access is drwxrws---? ... yes -post-receive hook up-to-date? ... yes -post-receive hooks in repos are links: ... yes - -Checking GitLab Shell ... Finished - -Checking Sidekiq ... - -Running? ... yes - -Checking Sidekiq ... Finished - -Checking GitLab ... - -Database config exists? ... yes -Database is SQLite ... no -All migrations up? ... yes -GitLab config exists? ... yes -GitLab config outdated? ... no -Log directory writable? ... yes -Tmp directory writable? ... yes -Init script exists? ... yes -Init script up-to-date? ... yes -Projects have satellites? ... yes -Redis version >= 2.0.0? ... yes - -Checking GitLab ... Finished -``` - -## (Re-)Create satellite repositories - -This will create satellite repositories for all your projects. - -If necessary, remove the `repo_satellites` directory and rerun the commands below. - -``` -sudo -u git -H mkdir -p /home/git/gitlab-satellites -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production -sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites -``` - -## Rebuild authorized_keys file - -In some case it is necessary to rebuild the `authorized_keys` file. - -For Omnibus-packages: -``` -sudo gitlab-rake gitlab:shell:setup -``` - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production -``` - -``` -This will rebuild an authorized_keys file. -You will lose any data stored in authorized_keys file. -Do you want to continue (yes/no)? yes -``` - -## Clear redis cache - -If for some reason the dashboard shows wrong information you might want to -clear Redis' cache. - -For Omnibus-packages: -``` -sudo gitlab-rake cache:clear -``` - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## Precompile the assets - -Sometimes during version upgrades you might end up with some wrong CSS or -missing some icons. In that case, try to precompile the assets again. - -For Omnibus-packages: -``` -sudo gitlab-rake assets:precompile -``` - -For installations from source: -``` -cd /home/git/gitlab -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md deleted file mode 100644 index 80b01ca4043..00000000000 --- a/doc/raketasks/user_management.md +++ /dev/null @@ -1,49 +0,0 @@ -# User management - -## Add user as a developer to all projects - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:user_to_projects[username@domain.tld] - -# installation from source -bundle exec rake gitlab:import:user_to_projects[username@domain.tld] RAILS_ENV=production -``` - -## Add all users to all projects - -Notes: - -- admin users are added as masters - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:all_users_to_all_projects - -# installation from source -bundle exec rake gitlab:import:all_users_to_all_projects RAILS_ENV=production -``` - -## Add user as a developer to all groups - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:user_to_groups[username@domain.tld] - -# installation from source -bundle exec rake gitlab:import:user_to_groups[username@domain.tld] RAILS_ENV=production -``` - -## Add all users to all groups - -Notes: - -- admin users are added as owners so they can add additional users to the group - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:import:all_users_to_all_groups - -# installation from source -bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production -``` diff --git a/doc/raketasks/web_hooks.md b/doc/raketasks/web_hooks.md deleted file mode 100644 index 5a8b94af9b4..00000000000 --- a/doc/raketasks/web_hooks.md +++ /dev/null @@ -1,45 +0,0 @@ -# Web hooks - -## Add a web hook 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**: - - # 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: - - # 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**: - - # 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: - - # 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**: - - # omnibus-gitlab - sudo gitlab-rake gitlab:web_hook:list NAMESPACE=/ - # source installations - bundle exec rake gitlab:web_hook:list NAMESPACE=/ RAILS_ENV=production - -> Note: `/` is the global namespace. diff --git a/doc/release/README.md b/doc/release/README.md deleted file mode 100644 index 1342b90f3b3..00000000000 --- a/doc/release/README.md +++ /dev/null @@ -1,6 +0,0 @@ -GitLab has the following updates: - -- [Monthly release](monthly.md), every month on the 22nd. -- [Patch release](patch.md), if there are serious regressions. -- [Security](security.md), for security problems. -- [Master](master.md), update process for the master branch. diff --git a/doc/release/howto_rc1.md b/doc/release/howto_rc1.md deleted file mode 100644 index 07c703142d4..00000000000 --- a/doc/release/howto_rc1.md +++ /dev/null @@ -1,55 +0,0 @@ -# How to create RC1 - -The RC1 release comes with the task to update the installation and upgrade docs. Be mindful that there might already be merge requests for this on GitLab or GitHub. - -### 1. Update the installation guide - -1. Check if it references the correct branch `x-x-stable` (doesn't exist yet, but that is okay) -1. Check the [GitLab Shell version](/lib/tasks/gitlab/check.rake#L782) -1. Check the [Git version](/lib/tasks/gitlab/check.rake#L794) -1. There might be other changes. Ask around. - -### 2. Create update guides - -[Follow this guide](howto_update_guides.md) to create update guides. - -### 3. Code quality indicators - -Make sure the code quality indicators are green / good. - -- [](http://ci.gitlab.org/projects/1?ref=master) on ci.gitlab.org (master branch) - -- [](https://semaphoreapp.com/gitlabhq/gitlabhq) (master branch) - -- [](https://codeclimate.com/github/gitlabhq/gitlabhq) - -- [](https://gemnasium.com/gitlabhq/gitlabhq) this button can be yellow (small updates are available) but must not be red (a security fix or an important update is available) - -- [](https://coveralls.io/r/gitlabhq/gitlabhq) - -### 4. Run release tool - -**Make sure EE `master` has latest changes from CE `master`** - -Get release tools - -``` -git clone git@dev.gitlab.org:gitlab/release-tools.git -cd release-tools -``` - -Release candidate creates stable branch from master. -So we need to sync master branch between all CE, EE and CI remotes. - -``` -bundle exec rake sync -``` - -Create release candidate and stable branch: - -``` -bundle exec rake release["x.x.0.rc1"] -``` - -Now developers can use master for merging new features. -So you should use stable branch for future code changes related to release. diff --git a/doc/release/howto_update_guides.md b/doc/release/howto_update_guides.md deleted file mode 100644 index 23d0959c33d..00000000000 --- a/doc/release/howto_update_guides.md +++ /dev/null @@ -1,55 +0,0 @@ -# Create update guides - -1. Create: CE update guide from previous version. Like `7.3-to-7.4.md` -1. Create: CE to EE update guide in EE repository for latest version. -1. Update: `6.x-or-7.x-to-7.x.md` to latest version. -1. Create: CI update guide from previous version - -It's best to copy paste the previous guide and make changes where necessary. -The typical steps are listed below with any points you should specifically look at. - -#### 0. Any major changes? - -List any major changes here, so the user is aware of them before starting to upgrade. For instance: - -- Database updates -- Web server changes -- File structure changes - -#### 1. Stop server - -#### 2. Make backup - -#### 3. Do users need to update dependencies like `git`? - -- Check if the [GitLab Shell version](/lib/tasks/gitlab/check.rake#L782) changed since the last release. - -- Check if the [Git version](/lib/tasks/gitlab/check.rake#L794) changed since the last release. - -#### 4. Get latest code - -#### 5. Does GitLab shell need to be updated? - -#### 6. Install libs, migrations, etc. - -#### 7. Any config files updated since last release? - -Check if any of these changed since last release: - -- [lib/support/nginx/gitlab](/lib/support/nginx/gitlab) -- [lib/support/nginx/gitlab-ssl](/lib/support/nginx/gitlab-ssl) -- <https://gitlab.com/gitlab-org/gitlab-shell/commits/master/config.yml.example> -- [config/gitlab.yml.example](/config/gitlab.yml.example) -- [config/unicorn.rb.example](/config/unicorn.rb.example) -- [config/database.yml.mysql](/config/database.yml.mysql) -- [config/database.yml.postgresql](/config/database.yml.postgresql) -- [config/initializers/rack_attack.rb.example](/config/initializers/rack_attack.rb.example) -- [config/resque.yml.example](/config/resque.yml.example) - -#### 8. Need to update init script? - -Check if the `init.d/gitlab` script changed since last release: [lib/support/init.d/gitlab](/lib/support/init.d/gitlab) - -#### 9. Start application - -#### 10. Check application status diff --git a/doc/release/master.md b/doc/release/master.md deleted file mode 100644 index 19070b46a0d..00000000000 --- a/doc/release/master.md +++ /dev/null @@ -1,33 +0,0 @@ -# How to push GitLab CE master branch to all remotes. - -The source code of GitLab is available on multiple servers (with GitLab.com as the canonical source). -Synchronization between the repo's is done by the lead developer if there is no rush. -This happens a few times per workday on average. -If somebody else with access to all repo's wants to do it the instructions are below. -This is just to distribute changes, not to make them. - -## Add this to `.bashrc` or [your dotfiles](https://github.com/dosire/dotfiles/commit/52803ce3ac60d57632164b7713ff0041e86fa26c) - -```bash -gpa () -{ - git push origin ${1:-master} && git push gh ${1:-master} && git push gl ${1:-master} -} -``` - -## Then add remotes to your local repo - -```bash -cd my-gitlab-ce-repo - -git remote add origin git@dev.gitlab.org:gitlab/gitlabhq.git -git remote add gh git@github.com:gitlabhq/gitlabhq.git -git remote add gl git@gitlab.com:gitlab-org/gitlab-ce.git -``` - -## Push to all remotes - -```bash -gpa -``` - diff --git a/doc/release/monthly.md b/doc/release/monthly.md deleted file mode 100644 index cfe01896d8f..00000000000 --- a/doc/release/monthly.md +++ /dev/null @@ -1,212 +0,0 @@ -# Monthly Release - -NOTE: This is a guide used by the GitLab B.V. developers. - -It starts 7 working days before the release. -The release manager doesn't have to perform all the work but must ensure someone is assigned. -The current release manager must schedule the appointment of the next release manager. -The new release manager should create overall issue to track the progress. - -## Release Manager - -A release manager is selected that coordinates all releases the coming month, including the patch releases for previous releases. -The release manager has to make sure all the steps below are done and delegated where necessary. -This person should also make sure this document is kept up to date and issues are created and updated. - -## Take vacations into account - -The time is measured in weekdays to compensate for weekends. -Do everything on time to prevent problems due to rush jobs or too little testing time. -Make sure that you take into account any vacations of maintainers. -If the release is falling behind immediately warn the team. - -## Create an overall issue and follow it - -Create issue for GitLab CE project(internal). Name it "Release x.x.x" for easier searching. -Replace the dates with actual dates based on the number of workdays before the release. -All steps from issue template are explained below - -``` -Xth: (7 working days before the 22nd) - -- [ ] Code freeze -- [ ] Update the CE changelog (#LINK) -- [ ] Update the EE changelog (#LINK) -- [ ] Update the CI changelog (#LINK) -- [ ] Triage the omnibus-gitlab milestone - -Xth: (6 working days before the 22nd) - -- [ ] Merge CE master in to EE master via merge request (#LINK) -- [ ] Determine QA person and notify this person -- [ ] Check the tasks in [how to rc1 guide](howto_rc1.md) and delegate tasks if necessary -- [ ] Create CE, EE, CI RC1 versions (#LINK) - -Xth: (5 working days before the 22nd) - -- [ ] Do QA and fix anything coming out of it (#LINK) -- [ ] Close the omnibus-gitlab milestone -- [ ] Prepare the blog post (#LINK) - -Xth: (4 working days before the 22nd) - -- [ ] Update GitLab.com with rc1 (#LINK) (https://dev.gitlab.org/cookbooks/chef-repo/blob/master/doc/administration.md#deploy-the-package) -- [ ] Update ci.gitLab.com with rc1 (#LINK) (https://dev.gitlab.org/cookbooks/chef-repo/blob/master/doc/administration.md#deploy-the-package) -- [ ] Create regression issues (CE, CI) (#LINK) -- [ ] Tweet about rc1 (#LINK) - -Xth: (3 working days before the 22nd) - -- [ ] Merge CE stable branch into EE stable branch - -Xth: (2 working days before the 22nd) - -- [ ] Check that everyone is mentioned on the blog post (the reviewer should have done this one working day ago) -- [ ] Check that MVP is added to the mvp page (source/mvp/index.html in www-gitlab-com) - -Xth: (1 working day before the 22nd) - -- [ ] Create CE, EE, CI stable versions (#LINK) -- [ ] Create Omnibus tags and build packages -- [ ] Update GitLab.com with the stable version (#LINK) -- [ ] Update ci.gitLab.com with the stable version (#LINK) - -22nd: - -- [ ] Release CE, EE and CI (#LINK) - -``` - -- - - - -## Code Freeze - -Stop merging code in master, except for important bug fixes - -## Update changelog - -Any changes not yet added to the changelog are added by lead developer and in that merge request the complete team is -asked if there is anything missing. - -There are three changelogs that need to be updated: CE, EE and CI. - -## Create RC1 (CE, EE, CI) - -[Follow this How-to guide](howto_rc1.md) to create RC1. - -## Prepare CHANGELOG for next release - -Once the stable branches have been created, update the CHANGELOG in `master` with the upcoming version, usually X.X.X.pre. - -## QA - -Create issue on dev.gitlab.org `gitlab` repository, named "GitLab X.X QA" in order to keep track of the progress. - -Use the omnibus packages created for RC1 of Enterprise Edition using [this guide](https://dev.gitlab.org/gitlab/gitlab-ee/blob/master/doc/release/manual_testing.md). - -**NOTE** Upgrader can only be tested when tags are pushed to all repositories. Do not forget to confirm it is working before releasing. Note that in the issue. - -#### Fix anything coming out of the QA - -Create an issue with description of a problem, if it is quick fix fix it yourself otherwise contact the team for advice. - -**NOTE** If there is a problem that cannot be fixed in a timely manner, reverting the feature is an option! If the feature is reverted, -create an issue about it in order to discuss the next steps after the release. - -## Update GitLab.com with RC1 - -Use the omnibus EE packages created for RC1. -If there are big database migrations consider testing them with the production db on a VM. -Try to deploy in the morning. -It is important to do this as soon as possible, so we can catch any errors before we release the full version. - -## Create a regressions issue - -On [the GitLab CE issue tracker on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ce/issues/) create an issue titled "GitLab X.X regressions" add the following text: - -This is a meta issue to discuss possible regressions in this monthly release and any patch versions. -Please do not raise issues directly in this issue but link to issues that might warrant a patch release. -The decision to create a patch release or not is with the release manager who is assigned to this issue. -The release manager will comment here about the plans for patch releases. - -Assign the issue to the release manager and at mention all members of gitlab core team. If there are any known bugs in the release add them immediately. - -## Tweet about RC1 - -Tweet about the RC release: - -> GitLab x.x.0.rc1 is out. This release candidate is only suitable for testing. Please link regressions issues from LINK_TO_REGRESSION_ISSUE - -## Prepare the blog post - -1. Start with a complete copy of the [release blog template](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/doc/release_blog_template.md) and fill it out. -1. Make sure the blog post contains information about the GitLab CI release. -1. Check the changelog of CE and EE for important changes. -1. Also check the CI changelog -1. Add a proposed tweet text to the blog post WIP MR description. -1. Create a WIP MR for the blog post -1. Ask Dmitriy (or a team member with OS X) to add screenshots to the WIP MR. -1. Decide with core team who will be the MVP user. -1. Create WIP MR for adding MVP to MVP page on website -1. Add a note if there are security fixes: This release fixes an important security issue and we advise everyone to upgrade as soon as possible. -1. Create a merge request on [GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com/tree/master) -1. Assign to one reviewer who will fix spelling issues by editing the branch (either with a git client or by using the online editor) -1. Comment to the reviewer: '@person Please mention the whole team as soon as you are done (3 workdays before release at the latest)' - -## Create CE, EE, CI stable versions - -Get release tools - -``` -git clone git@dev.gitlab.org:gitlab/release-tools.git -cd release-tools -``` - -Bump version, create release tag and push to remotes: - -``` -bundle exec rake release["x.x.0"] -``` - -This will create correct version and tag and push to all CE, EE and CI remotes. - -Update [installation.md](/doc/install/installation.md) to the newest version in master. - - -## Create Omnibus tags and build packages - -Follow the [release doc in the Omnibus repository](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/release.md). -This can happen before tagging because Omnibus uses tags in its own repo and SHA1's to refer to the GitLab codebase. - -## Update GitLab.com with the stable version - -- Deploy the package (should not need downtime because of the small difference with RC1) -- Deploy the package for ci.gitlab.com - -## Release CE, EE and CI - -__1. Publish packages for new release__ - -Update `downloads/index.html` and `downloads/archive/index.html` in `www-gitlab-com` repository. - -__2. Publish blog for new release__ - -Doublecheck the everyone has been mentioned in the blog post. -Merge the [blog merge request](#1-prepare-the-blog-post) in `www-gitlab-com` repository. - -__3. Tweet to blog__ - -Send out a tweet to share the good news with the world. -List the most important features and link to the blog post. - -Proposed tweet "Release of GitLab X.X & CI Y.Y! FEATURE, FEATURE and FEATURE <link-to-blog-post> #gitlab" - -Consider creating a post on Hacker News. - -## Release new AMIs - -[Follow this guide](https://dev.gitlab.org/gitlab/AMI/blob/master/README.md) - -## Create a WIP blogpost for the next release - -Create a WIP blogpost using [release blog template](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/doc/release_blog_template.md). diff --git a/doc/release/patch.md b/doc/release/patch.md deleted file mode 100644 index 4c7b471785f..00000000000 --- a/doc/release/patch.md +++ /dev/null @@ -1,55 +0,0 @@ -# Things to do when doing a patch release - -NOTE: This is a guide for GitLab developers. If you are trying to install GitLab see the latest stable [installation guide](install/installation.md) and if you are trying to upgrade, see the [upgrade guides](update). - -## When to do a patch release - -Do a patch release when there is a critical regression that needs to be addresses before the next monthly release. - -Otherwise include it in the monthly release and note there was a regression fix in the release announcement. - -## Release Procedure - -### Preparation - -1. Verify that the issue can be reproduced -1. Note in the 'GitLab X.X regressions' that you will create a patch -1. Create an issue on private GitLab development server -1. Name the issue "Release X.X.X CE and X.X.X EE", this will make searching easier -1. Fix the issue on a feature branch, do this on the private GitLab development server -1. If it is a security issue, then assign it to the release manager and apply a 'security' label -1. Consider creating and testing workarounds -1. After the branch is merged into master, cherry pick the commit(s) into the current stable branch -1. Make sure that the build has passed and all tests are passing -1. In a separate commit in the master branch update the CHANGELOG -1. For EE, update the CHANGELOG-EE if it is EE specific fix. Otherwise, merge the stable CE branch and add to CHANGELOG-EE "Merge community edition changes for version X.X.X" -1. Merge CE stable branch into EE stable branch - - -### Bump version - -Get release tools - -``` -git clone git@dev.gitlab.org:gitlab/release-tools.git -cd release-tools -``` - -Bump all versions in stable branch, even if the changes affect only EE, CE, or CI. Since all the versions are synced now, -it doesn't make sense to say upgrade CE to 7.2, EE to 7.3 and CI to 7.1. - -Create release tag and push to remotes: - -``` -bundle exec rake release["x.x.x"] -``` - -### Release - -1. [Build new packages with the latest version](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/release.md) -1. Apply the patch to GitLab.com and the private GitLab development server -1. Apply the patch to ci.gitLab.com and the private GitLab CI development server -1. Create and publish a blog post, see [patch release blog template](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/doc/patch_release_blog_template.md) -1. Send tweets about the release from `@gitlab`, tweet should include the most important feature that the release is addressing and link to the blog post -1. Note in the 'GitLab X.X regressions' issue that the patch was published (CE only) -1. [Create new AMIs](https://dev.gitlab.org/gitlab/AMI/blob/master/README.md) diff --git a/doc/release/security.md b/doc/release/security.md deleted file mode 100644 index 60bcfbb6da5..00000000000 --- a/doc/release/security.md +++ /dev/null @@ -1,76 +0,0 @@ -# Things to do when doing an out-of-bound security release - -NOTE: This is a guide for GitLab developers. If you are trying to install GitLab see the latest stable [installation guide](install/installation.md) and if you are trying to upgrade, see the [upgrade guides](update). - -## When to do a security release - -Do a security release when there is a critical issue that needs to be addresses before the next monthly release. Otherwise include it in the monthly release and note there was a security fix in the release announcement. - -## Security vulnerability disclosure - -Please report suspected security vulnerabilities in private to <support@gitlab.com>, also see the [disclosure section on the GitLab.com website](http://about.gitlab.com/disclosure/). Please do NOT create publicly viewable issues for suspected security vulnerabilities. - -## Release Procedure - -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. 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 -1. [Create new AMIs](https://dev.gitlab.org/gitlab/AMI/blob/master/README.md) -1. Create feature branches for the blog post on GitLab.com and link them from the code branch -1. Merge and publish the blog posts -1. Send tweets about the release from `@gitlabhq` -1. Send out an email to [the community google mailing list](https://groups.google.com/forum/#!forum/gitlabhq) -1. Post a signed copy of our complete announcement to [oss-security](http://www.openwall.com/lists/oss-security/) and request a CVE number. CVE is only needed for bugs that allow someone to own the server (Remote Code Execution) or access to code of projects they are not a member of. -1. Add the security researcher to the [Security Researcher Acknowledgments list](http://about.gitlab.com/vulnerability-acknowledgements/) -1. Thank the security researcher in an email for their cooperation -1. Update the blog post and the CHANGELOG when we receive the CVE number - -The timing of the code merge into master should be coordinated in advance. - -After the merge we strive to publish the announcements within 60 minutes. - -## Blog post template - -XXX Security Advisory for GitLab - -A recently discovered critical vulnerability in GitLab allows [unauthenticated API access|remote code execution|unauthorized access to repositories|XXX|PICKSOMETHING]. All users should update GitLab and gitlab-shell immediately. We [have|haven't|XXX|PICKSOMETHING|] heard of this vulnerability being actively exploited. - -### Version affected - -GitLab Community Edition XXX and lower - -GitLab Enterprise Edition XXX and lower - -### Fixed versions - -GitLab Community Edition XXX and up - -GitLab Enterprise Edition XXX and up - -### Impact - -On GitLab installations which use MySQL as their database backend it is possible for an attacker to assume the identity of any existing GitLab user in certain API calls. This attack can be performed by [unauthenticated|authenticated|XXX|PICKSOMETHING] users. - -### Workarounds - -If you are unable to upgrade you should apply the following patch and restart GitLab. - -XXX - -### Credit - -We want to thank XXX of XXX for the responsible disclosure of this vulnerability. - -## Email template - -We just announced a security advisory for GitLab at XXX - -Please contact us at support@gitlab.com if you have any questions. - -## Tweet template - -We just announced a security advisory for GitLab at XXX diff --git a/doc/security/README.md b/doc/security/README.md deleted file mode 100644 index 49dfa6eec76..00000000000 --- a/doc/security/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Security - -- [Password length limits](password_length_limits.md) -- [Rack attack](rack_attack.md) -- [Web Hooks and insecure internal web services](webhooks.md) -- [Information exclusivity](information_exclusivity.md) diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md deleted file mode 100644 index f8e7fc3fd0e..00000000000 --- a/doc/security/information_exclusivity.md +++ /dev/null @@ -1,9 +0,0 @@ -# Information exclusivity - -Git is a distributed version control system (DVCS). -This means that everyone that works with the source code has a local copy of the complete repository. -In GitLab every project member that is not a guest (so reporters, developers and masters) can clone the repository to get a local copy. -After obtaining this local copy the user can upload the full repository anywhere, including another project under their control or another server. -The consequence is that you can't build access controls that prevent the intentional sharing of source code by users that have access to the source code. -This is an inherent feature of a DVCS and all git management systems have this limitation. -Obviously you can take steps to prevent unintentional sharing and information destruction, this is why only some people are allowed to invite others and nobody can force push a protected branch. diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md deleted file mode 100644 index d21b26a43e8..00000000000 --- a/doc/security/password_length_limits.md +++ /dev/null @@ -1,11 +0,0 @@ -# Custom password length limits - -If you want to enforce longer user passwords you can create an extra Devise initializer with the steps below. - -If you do not use the `devise_password_length.rb` initializer the password length is set to a minimum of 8 characters in `config/initializers/devise.rb`. - -```bash -cd /home/git/gitlab -sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb -sudo -u git -H editor config/initializers/devise_password_length.rb # inspect and edit the new password length limits -``` diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md deleted file mode 100644 index 92066997be8..00000000000 --- a/doc/security/rack_attack.md +++ /dev/null @@ -1,25 +0,0 @@ -# Rack attack - -To prevent abusive clients doing damage GitLab uses rack-attack gem. - -If you installed or upgraded GitLab by following the official guides this should be enabled by default. - -If you are missing `config/initializers/rack_attack.rb` the following steps need to be taken in order to enable protection for your GitLab instance: - -1. In config/application.rb find and uncomment the following line: - - config.middleware.use Rack::Attack - -1. Rename `config/initializers/rack_attack.rb.example` to `config/initializers/rack_attack.rb`. - -1. Review the `paths_to_be_protected` and add any other path you need protecting. - -1. Restart GitLab instance. - -By default, user sign-in, user sign-up(if enabled) and user password reset is limited to 6 requests per minute. After trying for 6 times, client will have to wait for the next minute to be able to try again. These settings can be found in `config/initializers/rack_attack.rb` - -If you want more restrictive/relaxed throttle rule change the `limit` or `period` values. For example, more relaxed throttle rule will be if you set limit: 3 and period: 1.second(this will allow 3 requests per second). You can also add other paths to the protected list by adding to `paths_to_be_protected` variable. If you change any of these settings do not forget to restart your GitLab instance. - -In case you find throttling is not enough to protect you against abusive clients, rack-attack gem offers IP whitelisting, blacklisting, Fail2ban style filter and tracking. - -For more information on how to use these options check out [rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md). diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md deleted file mode 100644 index 1e9d33e87c3..00000000000 --- a/doc/security/webhooks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Web Hooks 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. - -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. - -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. - -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. - -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". - -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 deleted file mode 100644 index 0acb15896d3..00000000000 --- a/doc/ssh/README.md +++ /dev/null @@ -1,73 +0,0 @@ -# SSH - -## SSH keys - -An SSH key allows you to establish a secure connection between your -computer and GitLab. - -Before generating an SSH key, check if your system already has one by -running `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. - -To generate a new SSH key, just open your terminal and use code below. The -ssh-keygen command prompts 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. - -It is a best practice to use a password for an SSH key, but it is not -required and you can skip creating a password by pressing enter. Note that -the password you choose here can't be altered or retrieved. - -```bash -ssh-keygen -t rsa -C "$your_email" -``` - -Use the code below to show your public key. - -```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 -with your username and host. - -Use code below to copy your public key to the clipboard. Depending on your -OS you'll need to use a different command: - -**Windows:** -```bash -clip < ~/.ssh/id_rsa.pub -``` - -**Mac:** -```bash -pbcopy < ~/.ssh/id_rsa.pub -``` - -**GNU/Linux (requires xclip):** -```bash -xclip -sel clip < ~/.ssh/id_rsa.pub -``` - -## Deploy keys - -Deploy keys allow read-only access to multiple projects with a single SSH -key. - -This is really useful for cloning repositories to your Continuous -Integration (CI) server. By using deploy keys, you don't have to setup a -dummy user account. - -If you are a project master or owner, you can add a deploy key in the -project settings under the section 'Deploy Keys'. Press the 'New Deploy -Key' button and upload a public SSH key. After this, the machine that uses -the corresponding private key has read-only access to the project. - -You can't add the same deploy key twice with the 'New Deploy Key' option. -If you want to add the same key to another project, please enable it in the -list that says 'Deploy keys from projects available to you'. All the deploy -keys of all the projects you have access to are available. This project -access can happen through being a direct member of the project, or through -a group. See `def accessible_deploy_keys` in `app/models/user.rb` for more -information. diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md deleted file mode 100644 index f9b6d37d840..00000000000 --- a/doc/system_hooks/system_hooks.md +++ /dev/null @@ -1,180 +0,0 @@ -# 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`. - -System hooks can be used, e.g. for logging or changing information in a LDAP server. - -## Hooks request example - -**Project created:** - -```json -{ - "created_at": "2012-07-21T07:30:54Z", - "event_name": "project_create", - "name": "StoreCloud", - "owner_email": "johnsmith@gmail.com", - "owner_name": "John Smith", - "path": "storecloud", - "path_with_namespace": "jsmith/storecloud", - "project_id": 74, - "project_visibility": "private", -} -``` - -**Project destroyed:** - -```json -{ - "created_at": "2012-07-21T07:30:58Z", - "event_name": "project_destroy", - "name": "Underscore", - "owner_email": "johnsmith@gmail.com", - "owner_name": "John Smith", - "path": "underscore", - "path_with_namespace": "jsmith/underscore", - "project_id": 73, - "project_visibility": "internal", -} -``` - -**New Team Member:** - -```json -{ - "created_at": "2012-07-21T07:30:56Z", - "event_name": "user_add_to_team", - "project_access": "Master", - "project_id": 74, - "project_name": "StoreCloud", - "project_path": "storecloud", - "user_email": "johnsmith@gmail.com", - "user_name": "John Smith", - "user_id": 41, - "project_visibility": "private", -} -``` - -**Team Member Removed:** - -```json -{ - "created_at": "2012-07-21T07:30:56Z", - "event_name": "user_remove_from_team", - "project_access": "Master", - "project_id": 74, - "project_name": "StoreCloud", - "project_path": "storecloud", - "user_email": "johnsmith@gmail.com", - "user_name": "John Smith", - "user_id": 41, - "project_visibility": "private", -} -``` - -**User created:** - -```json -{ - "created_at": "2012-07-21T07:44:07Z", - "email": "js@gitlabhq.com", - "event_name": "user_create", - "name": "John Smith", - "user_id": 41 -} -``` - -**User removed:** - -```json -{ - "created_at": "2012-07-21T07:44:07Z", - "email": "js@gitlabhq.com", - "event_name": "user_destroy", - "name": "John Smith", - "user_id": 41 -} -``` - -**Key added** - -```json -{ - "event_name": "key_create", - "created_at": "2014-08-18 18:45:16 UTC", - "username": "root", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost", - "id": 4 -} -``` - -**Key removed** - -```json -{ - "event_name": "key_destroy", - "created_at": "2014-08-18 18:45:16 UTC", - "username": "root", - "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost", - "id": 4 -} -``` - -**Group created:** - -```json -{ - "created_at": "2012-07-21T07:30:54Z", - "event_name": "group_create", - "name": "StoreCloud", - "owner_email": "johnsmith@gmail.com", - "owner_name": "John Smith", - "path": "storecloud", - "group_id": 78 -} -``` - -**Group removed:** - -```json -{ - "created_at": "2012-07-21T07:30:54Z", - "event_name": "group_destroy", - "name": "StoreCloud", - "owner_email": "johnsmith@gmail.com", - "owner_name": "John Smith", - "path": "storecloud", - "group_id": 78 -} -``` - -**New Group Member:** - -```json -{ - "created_at": "2012-07-21T07:30:56Z", - "event_name": "user_add_to_group", - "group_access": "Master", - "group_id": 78, - "group_name": "StoreCloud", - "group_path": "storecloud", - "user_email": "johnsmith@gmail.com", - "user_name": "John Smith", - "user_id": 41 -} -``` -**Group Member Removed:** - -```json -{ - "created_at": "2012-07-21T07:30:56Z", - "event_name": "user_remove_from_group", - "group_access": "Master", - "group_id": 78, - "group_name": "StoreCloud", - "group_path": "storecloud", - "user_email": "johnsmith@gmail.com", - "user_name": "John Smith", - "user_id": 41 -} -``` diff --git a/doc/update/2.6-to-3.0.md b/doc/update/2.6-to-3.0.md deleted file mode 100644 index 4827ef9501a..00000000000 --- a/doc/update/2.6-to-3.0.md +++ /dev/null @@ -1,62 +0,0 @@ -# From 2.6 to 3.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/2.6-to-3.0.md) for the most up to date instructions.* - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Update code & db - - -```bash -# Get latest code -git fetch origin -git checkout v3.0.3 - - -# Install libs -sudo -u gitlab bundle install --without development test postgres - -# update db -sudo -u gitlab bundle exec rake db:migrate RAILS_ENV=production - -# !!! Config should be replaced with a new one. Check it after replace -cp config/gitlab.yml.example config/gitlab.yml - -# update Gitolite hooks - -# Gitolite v2: -sudo cp ./lib/hooks/post-receive /home/git/share/gitolite/hooks/common/post-receive -sudo chown git:git /home/git/share/gitolite/hooks/common/post-receive - -# Gitolite v3: -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive - -# set valid path to hooks in gitlab.yml in git_host section -# like this -git_host: - # Gitolite 2 - hooks_path: /home/git/share/gitolite/hooks - # Gitolite 3 - hooks_path: /home/git/.gitolite/hooks/ - - -# Make some changes to Gitolite config -# For more information visit https://github.com/gitlabhq/gitlabhq/pull/1719 - -# Gitolite v2 -sudo -u git -H sed -i 's/\(GL_GITCONFIG_KEYS\s*=>*\s*\).\{2\}/\\1"\.\*"/g' /home/git/.gitolite.rc - -# gitlite v3 -sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\\1'\.\*'/g" /home/git/.gitolite.rc - - -# Check app status -sudo -u gitlab bundle exec rake gitlab:app:status RAILS_ENV=production - -``` - -## 3. Start all - - sudo service gitlab start diff --git a/doc/update/2.9-to-3.0.md b/doc/update/2.9-to-3.0.md deleted file mode 100644 index f4a997a8c5e..00000000000 --- a/doc/update/2.9-to-3.0.md +++ /dev/null @@ -1,37 +0,0 @@ -# From 2.9 to 3.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/2.9-to-3.0.md) for the most up to date instructions.* - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Follow instructions - -```bash - -# Get latest code -sudo -u gitlab -H git fetch origin -sudo -u gitlab -H git checkout v3.0.3 - -# Install gems -sudo -u gitlab -H bundle install --without development test postgres - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -# Make some changes to gitolite v3 config -# For more information visit https://github.com/gitlabhq/gitlabhq/pull/1719 - -# Gitolite version 3 -sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\\1'\.\*'/g" /home/git/.gitolite.rc - -# If you still use gitolite v2 -sudo -u git -H sed -i 's/\(GL_GITCONFIG_KEYS\s*=>*\s*\).\{2\}/\\1"\.\*"/g' /home/git/.gitolite.rc - -# Check APP Status -sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production -``` - -## 3. Start all - - sudo service gitlab start diff --git a/doc/update/3.0-to-3.1.md b/doc/update/3.0-to-3.1.md deleted file mode 100644 index a30485c42f7..00000000000 --- a/doc/update/3.0-to-3.1.md +++ /dev/null @@ -1,97 +0,0 @@ -# From 3.0 to 3.1 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/3.0-to-3.1.md) for the most up to date instructions.* - -**IMPORTANT!** - -In this release **we moved Resque jobs under own gitlab namespace** - -Despite a lot of advantages it requires from our users to **replace gitolite post-receive hook with new one**. - -Most of projects has post-receive file as symlink to gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to gitolite hook. - -I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout v3.1.0 - -# Install new charlock_holmes -sudo gem install charlock_holmes --version '0.6.9' - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres sqlite - - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Update post-receive hooks - -### Gitolite 3 - -Step 1: Rewrite post-receive hook - -```bash -# Rewrite hook for gitolite 3 -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive -``` - -Step 2: Rewrite hooks in all projects to symlink gitolite hook - -```bash -# 1. Check for valid path -sudo -u gitlab -H vim lib/support/rewrite-hooks.sh - -# 2. Run script -sudo -u git -H lib/support/rewrite-hooks.sh -``` - -### Gitolite v2 - -Step 1: rewrite post-receive hook for gitolite 2 - -``` -sudo cp ./lib/hooks/post-receive /home/git/share/gitolite/hooks/common/post-receive -sudo chown git:git /home/git/share/gitolite/hooks/common/post-receive -``` - -Step 2: Replace symlinks in project to valid place - - #!/bin/bash - src="/home/git/repositories" - for dir in `ls "$src/"` - do - if [ -d "$src/$dir" ]; then - - if [ "$dir" = "gitolite-admin.git" ] - then - continue - fi - - project_hook="$src/$dir/hooks/post-receive" - gitolite_hook="/home/git/share/gitolite/hooks/common/post-receive" - - ln -s -f $gitolite_hook $project_hook - fi - done - -## 4. Check app status - -```bash -# Check APP Status -sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production -``` - -## 5. Start all - - sudo service gitlab start diff --git a/doc/update/3.1-to-4.0.md b/doc/update/3.1-to-4.0.md deleted file mode 100644 index f1ef4df4744..00000000000 --- a/doc/update/3.1-to-4.0.md +++ /dev/null @@ -1,90 +0,0 @@ -# From 3.1 to 4.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/3.1-to-4.0.md) for the most up to date instructions.* - -## Important changes - -- Support for SQLite was dropped -- Support for Gitolite 2 was dropped -- Projects are organized in namespaces -- The GitLab post-receive hook needs to be updated -- The configuration file needs to be updated -- Availability of `python2` executable - -Most of projects has post-receive file as symlink to Gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to Gitolite hook. - -I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you - -## 1. Stop GitLab & Resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash - -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout 4-0-stable - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres - -# Update repos permissions -sudo chmod -R ug+rwXs /home/git/repositories/ -sudo chown -R git:git /home/git/repositories/ - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -# Enable namespaces (**Warning!** All projects in groups will be moved to subdirectories) -sudo -u gitlab -H bundle exec rake gitlab:enable_namespaces RAILS_ENV=production - -``` - -## 3. Update post-receive hooks (Requires Gitolite v3 ) - -Step 1: Rewrite post-receive hook - -```bash -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive -``` - -Step 2: Update project hooks to be symlinks to the Gitolite hook - -```bash -# 1. Check paths in script -sudo -u gitlab -H vim lib/support/rewrite-hooks.sh - -# 2. Run script -sudo -u git -H lib/support/rewrite-hooks.sh -``` - -## 4. Replace config with new one - - # backup old one - sudo -u gitlab -H cp config/gitlab.yml config/gitlab.yml.old - - # copy new one - sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml - - # edit it - sudo -u gitlab -H vim config/gitlab.yml - -## 5. Disable ssh known_host check for own domain - - echo "Host localhost - StrictHostKeyChecking no - UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config - - echo "Host YOUR_DOMAIN_NAME - StrictHostKeyChecking no - UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config - -## 6. Check GitLab's status - - sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production - -## 7. Start GitLab & Resque - - sudo service gitlab start diff --git a/doc/update/4.0-to-4.1.md b/doc/update/4.0-to-4.1.md deleted file mode 100644 index d89d5235917..00000000000 --- a/doc/update/4.0-to-4.1.md +++ /dev/null @@ -1,56 +0,0 @@ -# From 4.0 to 4.1 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/4.0-to-4.1.md) for the most up to date instructions.* - -## Important changes - -- Resque replaced with Sidekiq -- New options for configuration file added -- Init.d script should be updated -- **requires ruby1.9.3-p327** - -## 1. Stop GitLab & Resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash -# Set the working directory -cd /home/gitlab/gitlab/ - -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout 4-1-stable - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Replace init.d script with a new one - -``` -# backup old one -sudo mv /etc/init.d/gitlab /etc/init.d/gitlab.old - -# get new one using sidekiq -sudo curl -L --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/4-1-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab - -``` - -## 4. Check GitLab's status - - sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production - - -## 5. Start GitLab & Sidekiq - - sudo service gitlab start - -## 6. Remove old init.d script - - sudo rm /etc/init.d/gitlab.old diff --git a/doc/update/4.1-to-4.2.md b/doc/update/4.1-to-4.2.md deleted file mode 100644 index 6fe4412ff90..00000000000 --- a/doc/update/4.1-to-4.2.md +++ /dev/null @@ -1,36 +0,0 @@ -# From 4.1 to 4.2 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/4.1-to-4.2.md) for the most up to date instructions.* - -## 1. Stop server & Resque - - sudo service gitlab stop - -## 2. Update code & DB - -```bash - -#Set the working directory -cd /home/gitlab/gitlab/ - -# Get latest code -sudo -u gitlab -H git fetch - -sudo -u gitlab -H git checkout 4-2-stable - -# Install libs -sudo -u gitlab -H bundle install --without development test postgres --deployment - -# update db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Check GitLab's status - -```bash -sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -## 4. Start all - - sudo service gitlab start diff --git a/doc/update/4.2-to-5.0.md b/doc/update/4.2-to-5.0.md deleted file mode 100644 index f9faf65f952..00000000000 --- a/doc/update/4.2-to-5.0.md +++ /dev/null @@ -1,211 +0,0 @@ -# From 4.2 to 5.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/4.2-to-5.0.md) for the most up to date instructions.* - -## Warning - -GitLab 5.0 is affected by critical security vulnerability CVE-2013-4490. - -## Important changes - -- We don't use `gitlab` user any more. Everything will be moved to `git` user -- Self signed SSL certificates are not supported until GitLab 5.1 -- **requires ruby1.9.3** - -## 0. Stop GitLab - - sudo service gitlab stop - -## 1. add bash to git user - -``` -sudo chsh -s /bin/bash git -``` - -## 2. git clone gitlab-shell - -``` -cd /home/git/ -sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git /home/git/gitlab-shell -``` - -## 3. setup gitlab-shell - -```bash -# chmod all repos and files under git -sudo chown git:git -R /home/git/repositories/ - -# login as git -sudo su git -cd /home/git/gitlab-shell -git checkout v1.1.0 - -# copy config -cp config.yml.example config.yml - -# change URL to GitLab instance -# ! make sure the URL ends with '/' like 'https://gitlab.example/' -vim config.yml - -# rewrite hooks -./support/rewrite-hooks.sh - -# check ruby version for git user ( 1.9 required!! ) -# GitLab shell requires system ruby 1.9 -ruby -v - -# exit from git user -exit -``` - -## 4. Copy GitLab instance to git user - -```bash -sudo cp -R /home/gitlab/gitlab /home/git/gitlab -sudo chown git:git -R /home/git/gitlab -sudo rm -rf /home/gitlab/gitlab-satellites - -# if exists -sudo rm /tmp/gitlab.socket -``` - -## 5. Update GitLab to recent version - -```bash -cd /home/git/gitlab - -# backup current config -sudo -u git -H cp config/gitlab.yml config/gitlab.yml.old - -sudo -u git -H git fetch -sudo -u git -H git checkout 5-0-stable - -# replace config with recent one -sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml - -# edit it -sudo -u git -H vim config/gitlab.yml - - -sudo -u git -H bundle install --without development test postgres --deployment -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:shell:build_missing_projects RAILS_ENV=production - -sudo -u git -H mkdir -p /home/git/gitlab-satellites -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# migrate wiki to git -sudo -u git -H bundle exec rake gitlab:wiki:migrate RAILS_ENV=production - - -# check permissions for /home/git/.ssh/ -sudo -u git -H chmod 700 /home/git/.ssh -sudo -u git -H chmod 600 /home/git/.ssh/authorized_keys - -# check permissions for /home/git/gitlab/ -sudo chown -R git /home/git/gitlab/log/ -sudo chown -R git /home/git/gitlab/tmp/ -sudo chmod -R u+rwX /home/git/gitlab/log/ -sudo chmod -R u+rwX /home/git/gitlab/tmp/ -sudo -u git -H mkdir -p /home/git/gitlab/tmp/pids/ -sudo chmod -R u+rwX /home/git/gitlab/tmp/pids - -``` - -## 6. Update init.d script and Nginx config - -```bash -# init.d -sudo rm /etc/init.d/gitlab -sudo curl -L --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/5-0-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab - -# unicorn -sudo -u git -H cp /home/git/gitlab/config/unicorn.rb /home/git/gitlab/config/unicorn.rb.old -sudo -u git -H cp /home/git/gitlab/config/unicorn.rb.example /home/git/gitlab/config/unicorn.rb - -# Nginx -# Replace path from '/home/gitlab/' to '/home/git/' -sudo vim /etc/nginx/sites-enabled/gitlab -sudo service nginx restart - -``` - -## 7. Start GitLab instance - -``` -sudo service gitlab start - -# check if unicorn and sidekiq started -# If not try to logout, also check replaced path from '/home/gitlab/' to '/home/git/' -# in Nginx, unicorn, init.d etc -ps aux | grep unicorn -ps aux | grep sidekiq - -``` - -## 8. Check installation - - -```bash -# In 5-10 seconds lets check gitlab-shell -sudo -u git -H /home/git/gitlab-shell/bin/check - -# Example of success output -# Check GitLab API access: OK -# Check directories and files: -# /home/git/repositories: OK -# /home/git/.ssh/authorized_keys: OK - - -# Now check GitLab instance -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -``` - -## 9. Cleanup - -**If everything works as expected you can cleanup some old things** -Recommend you wait a bit and do a backup before completing the following. - -```bash -# remove GitLab user from system -sudo userdel -r gitlab - -cd /home/git - -# cleanup .profile -## remove text from .profile added during gitolite installation: -## PATH=\$PATH:/home/git/bin -## export PATH -## to see what a clean .profile for new users on your system would look like see /etc/skel/.profile -sudo -u git -H vim .profile - -# remove gitolite -sudo rm -R bin -sudo rm -Rf gitolite -sudo rm -R .gitolite -sudo rm .gitolite.rc -sudo rm -f gitlab.pub -sudo rm projects.list - -# reset tmp folders -sudo service gitlab stop -cd /home/git/gitlab -sudo rm -R tmp -sudo -u git -H mkdir tmp -sudo chmod -R u+rwX tmp/ - -# create directory for pids, make sure GitLab can write to it -sudo -u git -H mkdir tmp/pids/ -sudo chmod -R u+rwX tmp/pids/ - -# if you are already running a newer version of GitLab check that installation guide for other tmp folders you need to create - -# reboot system -sudo reboot - -# login, check that GitLab is running fine -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` diff --git a/doc/update/5.0-to-5.1.md b/doc/update/5.0-to-5.1.md deleted file mode 100644 index 9fbd1f88515..00000000000 --- a/doc/update/5.0-to-5.1.md +++ /dev/null @@ -1,91 +0,0 @@ -# From 5.0 to 5.1 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.0-to-5.1.md) for the most up to date instructions.* - -## Warning - -GitLab 5.1 is affected by critical security vulnerability CVE-2013-4490. - -## Release notes - -- `unicorn` replaced with `puma` -- merge request cached diff will be truncated - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-1-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.3.0 -# replace your old config with the new one -sudo -u git -H mv config.yml config.yml.old -sudo -u git -H cp config.yml.example config.yml -# edit options to match old config -sudo -u git -H vi config.yml -``` - -## 4. Install libs, migrations etc - -```bash -cd /home/git/gitlab -sudo rm tmp/sockets/gitlab.socket -sudo -u git -H cp config/puma.rb.example config/puma.rb - -sudo -u git -H bundle install --without development test postgres --deployment -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_merge_requests RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update init.d script with a new one - -```bash -# init.d -sudo rm /etc/init.d/gitlab -sudo curl -L --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/5-1-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 6. MySQL grant privileges - -Only if you are using MySQL: - -```bash -mysql -u root -p -mysql> GRANT LOCK TABLES ON `gitlabhq_production`.* TO 'gitlab'@'localhost'; -mysql> \q -``` - -## 7. Start application - - sudo service gitlab start - -## 8. Check installation - - -```bash -# In 5-10 seconds lets check gitlab-shell -sudo -u git -H /home/git/gitlab-shell/bin/check - -# Example of success output -# Check GitLab API access: OK -# Check directories and files: -# /home/git/repositories: OK -# /home/git/.ssh/authorized_keys: OK - - -# Now check gitlab instance -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -``` diff --git a/doc/update/5.1-to-5.2.md b/doc/update/5.1-to-5.2.md deleted file mode 100644 index cf9c4e4f770..00000000000 --- a/doc/update/5.1-to-5.2.md +++ /dev/null @@ -1,104 +0,0 @@ -# From 5.1 to 5.2 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.1-to-5.2.md) for the most up to date instructions.* - -## Warning - -GitLab 5.2 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## 0. Backup - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-2-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.4.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example but with your settings. - -## 6. Update Init script - -```bash -cd /home/git/gitlab -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.0 to 5.1](5.0-to-5.1.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 -``` diff --git a/doc/update/5.1-to-5.4.md b/doc/update/5.1-to-5.4.md deleted file mode 100644 index 97a98ede070..00000000000 --- a/doc/update/5.1-to-5.4.md +++ /dev/null @@ -1,100 +0,0 @@ -# From 5.1 to 5.4 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.1-to-5.4.md) for the most up to date instructions.* - -Also works starting from 5.2. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489 -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.2 to 5.3](5.2-to-5.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 -``` diff --git a/doc/update/5.1-to-6.0.md b/doc/update/5.1-to-6.0.md deleted file mode 100644 index a3fdd92bd2f..00000000000 --- a/doc/update/5.1-to-6.0.md +++ /dev/null @@ -1,216 +0,0 @@ -# From 5.1 to 6.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.1-to-6.0.md) for the most up to date instructions.* - -## Warning - -GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## Deprecations - -### Global projects - -The root (global) namespace for projects is deprecated. - -So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote URL. Please make sure you disable sending email when you do a test of the upgrade. - -### Teams - -We introduce group membership in 6.0 as a replacement for teams. - -The old combination of groups and teams was confusing for a lot of people. - -And when the members of a team where changed this wasn't reflected in the project permissions. - -In GitLab 6.0 you will be able to add members to a group with a permission level for each member. - -These group members will have access to the projects in that group. - -Any changes to group members will immediately be reflected in the project permissions. - -You can even have multiple owners for a group, greatly simplifying administration. - -## 0. Backup & prepare for update - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following can help you have a more smooth upgrade. - -### Find projects with invalid project names - -#### MySQL -Login to MySQL: - - mysql -u root -p - -Find projects with invalid names: - -```bash -mysql> use gitlabhq_production; - -# find projects with invalid first char, projects must start with letter -mysql> select name from projects where name REGEXP '^[^A-Za-z]'; - -# find projects with other invalid chars -## names must only contain alphanumeric chars, underscores, spaces, periods, and dashes -mysql> select name from projects where name REGEXP '[^a-zA-Z0-9_ .-]+'; -``` - -If any projects have invalid names try correcting them from the web interface before starting the upgrade. -If correcting them from the web interface fails you can correct them using MySQL: - -```bash -# e.g. replace invalid / with allowed _ -mysql> update projects set name = REPLACE(name,'/','_'); -# repeat for all invalid chars found in project names -``` - -#### PostgreSQL -Make sure all project names start with a letter and only contain alphanumeric chars, underscores, spaces, periods, and dashes (a-zA-Z0-9_ .-). - -### Find other common errors - -``` -cd /home/git/gitlab -# Start rails console -sudo -u git -H bin/rails console production - -# Make sure none of the following rails commands return results - -# All project owners should have an owner: -Project.all.select { |project| project.owner.blank? } - -# Every user should have a namespace: -User.all.select { |u| u.namespace.blank? } - -# Projects in the global namespace should not conflict with projects in the owner namespace: -Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? } -``` - -If any of the above rails commands returned results other than `=> []` try correcting the issue from the web interface. - -If you find projects without an owner (first rails command above), correct it. For MySQL setups: - -```bash -# get your user id -mysql> select id, name from users order by name; - -# set yourself as owner of project -# replace your_user_id with your user id and bad_project_id with the project id from the rails command -mysql> update projects set creator_id=your_user_id where id=bad_project_id; -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 6-0-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install additional packages - -```bash -# For reStructuredText markup language support install required package: -sudo apt-get install python-docutils -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_groups RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_global_projects RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# Clear redis cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production - -# Clear and precompile assets -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production - -#Add dealing with newlines for editor -sudo -u git -H git config --global core.autocrlf input -``` - -## 6. Update config files - -Note: We switched from Puma in GitLab 5.x to unicorn in GitLab 6.0. - -- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/unicorn.rb.example but with your settings. - -## 7. Update Init script - -```bash -cd /home/git/gitlab -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 8. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir -p public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.0 to 5.1](5.0-to-5.1.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 -``` diff --git a/doc/update/5.2-to-5.3.md b/doc/update/5.2-to-5.3.md deleted file mode 100644 index 27613aeda07..00000000000 --- a/doc/update/5.2-to-5.3.md +++ /dev/null @@ -1,86 +0,0 @@ -# From 5.2 to 5.3 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.2-to-5.3.md) for the most up to date instructions.* - -## Warning - -GitLab 5.3 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-3-stable -``` - -## 3. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 4. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example but with your settings. - -## 5. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo curl -L --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5-3-stable/lib/support/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 6. Start application - - sudo service gitlab start - sudo service nginx restart - -## 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.1 to 5.2](5.1-to-5.2.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 -``` diff --git a/doc/update/5.3-to-5.4.md b/doc/update/5.3-to-5.4.md deleted file mode 100644 index 577b9a585ff..00000000000 --- a/doc/update/5.3-to-5.4.md +++ /dev/null @@ -1,90 +0,0 @@ -# From 5.3 to 5.4 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.3-to-5.4.md) for the most up to date instructions.* - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489 -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo curl -L --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5-4-stable/lib/support/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.2 to 5.3](5.2-to-5.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 -``` diff --git a/doc/update/5.4-to-6.0.md b/doc/update/5.4-to-6.0.md deleted file mode 100644 index d9c6d9bfb91..00000000000 --- a/doc/update/5.4-to-6.0.md +++ /dev/null @@ -1,149 +0,0 @@ -# From 5.4 to 6.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/5.4-to-6.0.md) for the most up to date instructions.* - -## Warning - -GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -**You need to follow this guide first, before updating past 6.0, as it contains critical migration steps that are only present -in the `6-0-stable` branch** - -## Deprecations - -### Global projects - -The root (global) namespace for projects is deprecated. - -So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote URL. Please make sure you disable sending email when you do a test of the upgrade. - -### Teams - -We introduce group membership in 6.0 as a replacement for teams. - -The old combination of groups and teams was confusing for a lot of people. - -And when the members of a team where changed this wasn't reflected in the project permissions. - -In GitLab 6.0 you will be able to add members to a group with a permission level for each member. - -These group members will have access to the projects in that group. - -Any changes to group members will immediately be reflected in the project permissions. - -You can even have multiple owners for a group, greatly simplifying administration. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 6-0-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install additional packages - -```bash -# For reStructuredText markup language support install required package: -sudo apt-get install python-docutils -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_groups RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_global_projects RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# Clear redis cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production - -# Clear and precompile assets -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 6. Update config files - -Note: We switched from Puma in GitLab 5.4 to unicorn in GitLab 6.0. - -- Make `/home/git/gitlab/config/gitlab.yml` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example but with your settings. - -## 7. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Troubleshooting - -The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data. - -All project owners should have an owner: - -``` -Project.all.select { |project| project.owner.blank? } -``` - -Every user should have a namespace: - -``` -User.all.select { |u| u.namespace.blank? } -``` - -Projects in the global namespace should not conflict with projects in the owner namespace: - -``` -Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? } -``` diff --git a/doc/update/6.0-to-6.1.md b/doc/update/6.0-to-6.1.md deleted file mode 100644 index c5eba1c01c4..00000000000 --- a/doc/update/6.0-to-6.1.md +++ /dev/null @@ -1,108 +0,0 @@ -# From 6.0 to 6.1 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.0-to-6.1.md) for the most up to date instructions.* - -## Warning - -GitLab 6.1 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -**In 6.1 we remove a lot of deprecated code.** - -**You should update to 6.0 before installing 6.1 so all the necessary conversions are run.** - -## Deprecations - -### Global issue numbers - -In 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their URL. If you use an old issue number URL and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-1-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-1-stable-ee -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_iids RAILS_ENV=production -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. Check application status - -Check if GitLab and its environment are configured correctly: - - cd /home/git/gitlab - 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.4 to 6.0](5.4-to-6.0.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 -``` diff --git a/doc/update/6.1-to-6.2.md b/doc/update/6.1-to-6.2.md deleted file mode 100644 index a534528108a..00000000000 --- a/doc/update/6.1-to-6.2.md +++ /dev/null @@ -1,122 +0,0 @@ -# From 6.1 to 6.2 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.1-to-6.2.md) for the most up to date instructions.* - -**You should update to 6.1 before installing 6.2 so all the necessary conversions are run.** - -## 0. Backup - -It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version). - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-2-stable # Latest version of 6-2-stable addresses CVE-2013-4489 -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-2-stable-ee -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install additional packages - -```bash -# Add support for logrotate for better log file handling -sudo apt-get install logrotate -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## 6. Update config files - -TIP: to see what changed in `gitlab.yml.example` in this release use next command: - -``` -git diff 6-1-stable:config/gitlab.yml.example 6-2-stable:config/gitlab.yml.example -``` - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example but with your settings. - -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example but with your settings. - -- Copy rack attack middleware config: - - ```bash - sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb - ``` - -- Uncomment `config.middleware.use Rack::Attack` in `/home/git/gitlab/config/application.rb` - -- Set up logrotate. - -```bash -sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab -``` - -## 7. Update Init script - -```bash -sudo rm /etc/init.d/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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.0 to 6.1](6.0-to-6.1.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 -``` diff --git a/doc/update/6.2-to-6.3.md b/doc/update/6.2-to-6.3.md deleted file mode 100644 index b08ebde0808..00000000000 --- a/doc/update/6.2-to-6.3.md +++ /dev/null @@ -1,108 +0,0 @@ -# From 6.2 to 6.3 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.2-to-6.3.md) for the most up to date instructions.* - -**Requires version: 6.1 or 6.2.** - -## 0. Backup - -It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-3-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-3-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -The gitlab-shell config changed recently, so check for config file changes and make `/home/git/gitlab-shell/config.yml` the same as <https://github.com/gitlabhq/gitlab-shell/blob/master/config.yml.example> - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL -sudo -u git -H bundle install --without development test mysql --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 -``` - -## 5. Update config files - -TIP: to see what changed in gitlab.yml.example in this release use next command: - -``` -git diff 6-2-stable:config/gitlab.yml.example 6-3-stable:config/gitlab.yml.example -``` - -- Make `/home/git/gitlab/config/gitlab.yml` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example but with your settings. - -```bash -# Copy rack attack middleware config -cd /home/git/gitlab -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb -``` - -## 6. Update Init script - -```bash -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.1 to 6.2](6.1-to-6.2.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 -``` diff --git a/doc/update/6.3-to-6.4.md b/doc/update/6.3-to-6.4.md deleted file mode 100644 index 951d92dfeb5..00000000000 --- a/doc/update/6.3-to-6.4.md +++ /dev/null @@ -1,90 +0,0 @@ -# From 6.3 to 6.4 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.3-to-6.4.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - -```bash -sudo service gitlab stop -```` - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-4-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-4-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -## 6. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -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 with: - -```bash -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.2 to 6.3](6.2-to-6.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 -``` diff --git a/doc/update/6.4-to-6.5.md b/doc/update/6.4-to-6.5.md deleted file mode 100644 index 0dae9a9fe59..00000000000 --- a/doc/update/6.4-to-6.5.md +++ /dev/null @@ -1,96 +0,0 @@ -# From 6.4 to 6.5 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.4-to-6.5.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-5-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.3 to 6.4](6.3-to-6.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/6.5-to-6.6.md b/doc/update/6.5-to-6.6.md deleted file mode 100644 index c24e83eb006..00000000000 --- a/doc/update/6.5-to-6.6.md +++ /dev/null @@ -1,97 +0,0 @@ -# From 6.5 to 6.6 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.5-to-6.6.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-6-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.4 to 6.5](6.4-to-6.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/6.6-to-6.7.md b/doc/update/6.6-to-6.7.md deleted file mode 100644 index b4298c93429..00000000000 --- a/doc/update/6.6-to-6.7.md +++ /dev/null @@ -1,109 +0,0 @@ -# From 6.6 to 6.7 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.6-to-6.7.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-7-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.1 -``` - -## 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -# Update the logrotate configuration (keep logs for 90 days instead of 52 weeks) -sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab - -# Compress existing .log.1 files because we turned off delaycompress in logrotate -sudo -u git -H gzip /home/git/gitlab/log/*.log.1 -sudo -u git -H gzip /home/git/gitlab-shell/gitlab-shell.log.1 - -# Close access to gitlab-satellites for others -sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites - -# Add directory for uploads -sudo -u git -H mkdir -p /home/git/gitlab/public/uploads -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.6) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.5 to 6.6](6.5-to-6.6.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/6.7-to-6.8.md b/doc/update/6.7-to-6.8.md deleted file mode 100644 index 4fb90639f16..00000000000 --- a/doc/update/6.7-to-6.8.md +++ /dev/null @@ -1,122 +0,0 @@ -# From 6.7 to 6.8 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.7-to-6.8.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - -```bash -sudo service gitlab stop -``` - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-8-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.3 -``` - -## 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -# Close access to gitlab-satellites for others -sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites -``` - -## 5. Update config files - -### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 6-7-stable:config/gitlab.yml.example 6-8-stable:config/gitlab.yml.example -``` - -### MySQL? Remove reaping frequency - -If you are using MySQL as a database, remove `reaping_frequency` from you database.yml to prevent crashes. [Relevant commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/5163a8fcb9cfd63435560fda00173b76df2ccc93). - -### HTTPS? Disable gzip - -If you are using HTTPS, disable gzip as in [this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/563fec734912d81cd7caea6fa8ec2b397fb72a9b) to prevent BREACH attacks. - -### Turn on asset compression - -To improve performance, enable gzip asset compression as seen [in this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/8af94ed75505f0253823b9b2d44320fecea5b5fb). - -## 6. Start application - - sudo service gitlab start - sudo service nginx restart - -## 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.7) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.6 to 6.7](6.6-to-6.7.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/6.8-to-6.9.md b/doc/update/6.8-to-6.9.md deleted file mode 100644 index b9b8b63f652..00000000000 --- a/doc/update/6.8-to-6.9.md +++ /dev/null @@ -1,103 +0,0 @@ -# From 6.8 to 6.9 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.8-to-6.9.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-9-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-9-stable-ee -``` - -### 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.4 -``` - -### 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 -``` - -### 5. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 6-8-stable:config/gitlab.yml.example 6-9-stable:config/gitlab.yml.example -``` - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.8) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.7 to 6.8](6.7-to-6.8.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/6.9-to-7.0.md b/doc/update/6.9-to-7.0.md deleted file mode 100644 index 236430b5951..00000000000 --- a/doc/update/6.9-to-7.0.md +++ /dev/null @@ -1,141 +0,0 @@ -# From 6.9 to 7.0 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/6.9-to-7.0.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Update Ruby - -If you are still using Ruby 1.9.3 or below, you will need to update Ruby. -You can check which version you are running with `ruby -v`. - -If you are you running Ruby 2.0.x, you do not need to upgrade ruby, but can consider doing so for performance reasons. - -If you are running Ruby 2.1.1 consider upgrading to 2.1.2, because of the high memory usage of Ruby 2.1.1. - -Install, update dependencies: - -```bash -sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl -``` - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl -L --progress ftp://ftp.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz | tar xz -cd ruby-2.1.2 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-ri --no-rdoc -``` - -### 3. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-0-stable-ee -``` - -### 4. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.6 -``` - -### 5. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff origin/6-9-stable:config/gitlab.yml.example origin/7-0-stable:config/gitlab.yml.example -``` - -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl but with your setting - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.9) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.8 to 6.9](6.8-to-6.9.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/7.0-to-7.1.md b/doc/update/7.0-to-7.1.md deleted file mode 100644 index a4e9be9946e..00000000000 --- a/doc/update/7.0-to-7.1.md +++ /dev/null @@ -1,138 +0,0 @@ -# From 7.0 to 7.1 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/7.0-to-7.1.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Update Ruby - -If you are still using Ruby 1.9.3 or below, you will need to update Ruby. -You can check which version you are running with `ruby -v`. - -If you are you running Ruby 2.0.x, you do not need to upgrade ruby, but can consider doing so for performance reasons. - -If you are running Ruby 2.1.1 consider upgrading to 2.1.2, because of the high memory usage of Ruby 2.1.1. - -Install, update dependencies: - -```bash -sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl -``` - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl -L --progress ftp://ftp.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz | tar xz -cd ruby-2.1.2 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-ri --no-rdoc -``` - -### 3. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-1-stable-ee -``` - -### 4. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.6 -``` - -### 5. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 7-0-stable:config/gitlab.yml.example 7-1-stable:config/gitlab.yml.example -``` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.0) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.9 to 7.0](6.9-to-7.0.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/7.1-to-7.2.md b/doc/update/7.1-to-7.2.md deleted file mode 100644 index 88cb63d7d41..00000000000 --- a/doc/update/7.1-to-7.2.md +++ /dev/null @@ -1,137 +0,0 @@ -# From 7.1 to 7.2 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/7.1-to-7.2.md) for the most up to date instructions.* - -## Editable labels - -In GitLab 7.2 we replace Issue and Merge Request tags with labels, making it -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. - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-2-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.8 -``` - -### 4. Install new system dependencies - -The latest version of the 'rugged' gem requires `pkg-config` and `cmake` to -build its native extensions. - -```bash -sudo apt-get install pkg-config cmake -``` - -### 5. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for `gitlab.yml`. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff 7-1-stable:config/gitlab.yml.example 7-2-stable:config/gitlab.yml.example -``` - -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl but with your setting - -Update rack attack middleware config - -``` -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb -``` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 9. Update OmniAuth configuration - -When using Google omniauth login, changes of the Google account required. -Ensure that `Contacts API` and the `Google+ API` are enabled in the [Google Developers Console](https://console.developers.google.com/). -More details can be found at the [integration documentation](../integration/google.md). - -## Things went south? Revert to previous version (7.1) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.0 to 7.1](7.0-to-7.1.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/7.2-to-7.3.md b/doc/update/7.2-to-7.3.md deleted file mode 100644 index 18f77d6396e..00000000000 --- a/doc/update/7.2-to-7.3.md +++ /dev/null @@ -1,145 +0,0 @@ -# From 7.2 to 7.3 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/7.2-to-7.3.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -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 7-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-3-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.0.1 -``` - -### 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - - -### 5. Configure Redis to use sockets - - # Configure redis to use sockets - sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig - # Disable Redis listening on TCP by setting 'port' to 0 - sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf - # Enable Redis socket for default Debian / Ubuntu path - echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf - # Be sure redis group can write to the socket, enable only if supported (>= redis 2.4.0). - sudo sed -i '/# unixsocketperm/ s/^# unixsocketperm.*/unixsocketperm 0775/' /etc/redis/redis.conf - # Activate the changes to redis.conf - sudo service redis-server restart - # Add git to the redis group - sudo usermod -aG redis git - - # Configure Redis connection settings - sudo -u git -H cp config/resque.yml.example config/resque.yml - # Change the Redis socket path if you are not using the default Debian / Ubuntu configuration - sudo -u git -H editor config/resque.yml - - # Configure gitlab-shell to use Redis sockets - sudo -u git -H sed -i 's|^ # socket.*| socket: /var/run/redis/redis.sock|' /home/git/gitlab-shell/config.yml - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-2-stable:config/gitlab.yml.example origin/7-3-stable:config/gitlab.yml.example -``` - -``` -# Use the default Unicorn socket backlog value of 1024 -sudo -u git -H sed -i 's/:backlog => 64/:backlog => 1024/' config/unicorn.rb -``` - -* HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab-ssl but with your setting - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 9. Update OmniAuth configuration - -When using Google omniauth login, changes of the Google account required. -Ensure that `Contacts API` and the `Google+ API` are enabled in the [Google Developers Console](https://console.developers.google.com/). -More details can be found at the [integration documentation](../integration/google.md). - -## Things went south? Revert to previous version (7.2) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.1 to 7.2](7.1-to-7.2.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/7.3-to-7.4.md b/doc/update/7.3-to-7.4.md deleted file mode 100644 index 53e739c06fb..00000000000 --- a/doc/update/7.3-to-7.4.md +++ /dev/null @@ -1,197 +0,0 @@ -# From 7.3 to 7.4 -*Make sure you view this [upgrade guide from the `master` branch](../../../master/doc/update/7.3-to-7.4.md) for the most up to date instructions.* - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-4-stable-ee -``` - -### 3. Install libs, migrations, etc. - -```bash -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 4. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-3-stable:config/gitlab.yml.example origin/7-4-stable:config/gitlab.yml.example -``` - -#### Change timeout for unicorn - -``` -# set timeout to 60 -sudo -u git -H editor config/unicorn.rb -``` - -#### Change Nginx HTTPS settings - -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/lib/support/nginx/gitlab-ssl but with your setting - -#### MySQL Databases: Update database.yml config file - -* Add `collation: utf8_general_ci` to `config/database.yml` as seen in [config/database.yml.mysql](/config/database.yml.mysql) - -``` -sudo -u git -H editor config/database.yml -``` - -### 5. Start application - - sudo service gitlab start - sudo service nginx restart - -### 6. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - - -### 7. Optional optimizations for GitLab setups with MySQL databases - -Only applies if running MySQL database created with GitLab 6.7 or earlier. If you are not experiencing any issues you may not need the following instructions however following them will bring your database in line with the latest recommended installation configuration and help avoid future issues. Be sure to follow these directions exactly. These directions should be safe for any MySQL instance but to be sure make a current MySQL database backup beforehand. - -``` -# Stop GitLab -sudo service gitlab stop - -# Secure your MySQL installation (added in GitLab 6.2) -sudo mysql_secure_installation - -# Login to MySQL -mysql -u root -p - -# do not type the 'mysql>', this is part of the prompt - -# Convert all tables to use the InnoDB storage engine (added in GitLab 6.8) -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' ENGINE=InnoDB;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `ENGINE` <> 'InnoDB' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# Convert all tables to correct character set -SET foreign_key_checks = 0; -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `TABLE_COLLATION` <> 'utf8_unicode_ci' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# turn foreign key checks back on -SET foreign_key_checks = 1; - -# Find MySQL users -mysql> SELECT user FROM mysql.user WHERE user LIKE '%git%'; - -# If git user exists and gitlab user does not exist -# you are done with the database cleanup tasks -mysql> \q - -# If both users exist skip to Delete gitlab user - -# Create new user for GitLab (changed in GitLab 6.4) -# change $password in the command below to a real password you pick -mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password'; - -# Grant the git user necessary permissions on the database -mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Delete the old gitlab user -mysql> DELETE FROM mysql.user WHERE user='gitlab'; - -# Quit the database session -mysql> \q - -# Try connecting to the new database with the new user -sudo -u git -H mysql -u git -p -D gitlabhq_production - -# Type the password you replaced $password with earlier - -# You should now see a 'mysql>' prompt - -# Quit the database session -mysql> \q - -# Update database configuration details -# See config/database.yml.mysql for latest recommended configuration details -# Remove the reaping_frequency setting line if it exists (removed in GitLab 6.8) -# Set production -> pool: 10 (updated in GitLab 5.3) -# Set production -> username: git -# Set production -> password: the password your replaced $password with earlier -sudo -u git -H editor /home/git/gitlab/config/database.yml - -# Start GitLab -sudo service gitlab start -sudo service nginx restart - -# Run thorough check -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - - -## Things went south? Revert to previous version (7.3) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.2 to 7.3](7.2-to-7.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/7.4-to-7.5.md b/doc/update/7.4-to-7.5.md deleted file mode 100644 index 673eab3c56e..00000000000 --- a/doc/update/7.4-to-7.5.md +++ /dev/null @@ -1,108 +0,0 @@ -# From 7.4 to 7.5 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-5-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.2.0 -``` - -### 4. 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 development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-4-stable:config/gitlab.yml.example origin/7-5-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`](/lib/support/nginx/gitlab) but with your settings -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`](/lib/support/nginx/gitlab-ssl) but with your setting - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.4) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.3 to 7.4](7.3-to-7.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/7.5-to-7.6.md b/doc/update/7.5-to-7.6.md deleted file mode 100644 index 35cd437fdc4..00000000000 --- a/doc/update/7.5-to-7.6.md +++ /dev/null @@ -1,114 +0,0 @@ -# From 7.5 to 7.6 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-6-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.4.0 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config 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 to your current `gitlab.yml`. - -``` -git diff origin/7-5-stable:config/gitlab.yml.example origin/7-6-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`](/lib/support/nginx/gitlab) but with your settings -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`](/lib/support/nginx/gitlab-ssl) but with your setting - -#### Setup time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`](config/application.rb) (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.5) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.4 to 7.5](7.4-to-7.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/7.6-to-7.7.md b/doc/update/7.6-to-7.7.md deleted file mode 100644 index 59243713156..00000000000 --- a/doc/update/7.6-to-7.7.md +++ /dev/null @@ -1,119 +0,0 @@ -# From 7.6 to 7.7 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-7-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.4.2 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config 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 to your current `gitlab.yml`. - -``` -git diff origin/7-6-stable:config/gitlab.yml.example origin/7-7-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`](/lib/support/nginx/gitlab) but with your settings -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`](/lib/support/nginx/gitlab-ssl) but with your setting - -#### Setup time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`](config/application.rb) (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.6) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.5 to 7.6](7.5-to-7.6.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/7.7-to-7.8.md b/doc/update/7.7-to-7.8.md deleted file mode 100644 index 46ca163c1bb..00000000000 --- a/doc/update/7.7-to-7.8.md +++ /dev/null @@ -1,120 +0,0 @@ -# From 7.7 to 7.8 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-8-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.5.4 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config 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 to your current `gitlab.yml`. - -``` -git diff origin/7-7-stable:config/gitlab.yml.example origin/7-8-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`](/lib/support/nginx/gitlab) but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`](/lib/support/nginx/gitlab-ssl) but with your settings. -* A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -#### Setup time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`](config/application.rb) (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.7) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.6 to 7.7](7.6-to-7.7.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/7.8-to-7.9.md b/doc/update/7.8-to-7.9.md deleted file mode 100644 index 28fd433e1c8..00000000000 --- a/doc/update/7.8-to-7.9.md +++ /dev/null @@ -1,120 +0,0 @@ -# From 7.8 to 7.9 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. 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 7-9-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-9-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.0 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install nodejs - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --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 - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config 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 to your current `gitlab.yml`. - -``` -git diff origin/7-8-stable:config/gitlab.yml.example origin/7-9-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -* HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`](/lib/support/nginx/gitlab) but with your settings. -* HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`](/lib/support/nginx/gitlab-ssl) but with your settings. -* A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -#### Setup time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`](config/application.rb) (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.8) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.7 to 7.8](7.7-to-7.8.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 deleted file mode 100644 index 0472537eeb5..00000000000 --- a/doc/update/README.md +++ /dev/null @@ -1,16 +0,0 @@ -Depending on the installation method and your GitLab version, there are multiple update guides. Choose one that fits your needs. - -## Omnibus Packages - -- [Omnibus update guide](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/update.md) contains the steps needed to update a GitLab [package](https://about.gitlab.com/downloads/). - -## Installation from source - -- [The individual upgrade guides](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update) are for those who have installed GitLab from source. -- [The CE to EE update guides](https://gitlab.com/subscribers/gitlab-ee/tree/master/doc/update) are for subscribers of the Enterprise Edition only. The steps are very similar to a version upgrade: stop the server, get the code, update config files for the new functionality, install libs and do migrations, update the init script, start the application and check the application status. -- [Upgrader](upgrader.md) is an automatic ruby script that performs the update for installations from source. -- [Patch versions](patch_versions.md) guide includes the steps needed for a patch version, eg. 6.2.0 to 6.2.1. - -## Miscellaneous - -- [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating your database from MySQL to PostgreSQL. diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md deleted file mode 100644 index 50941db25f6..00000000000 --- a/doc/update/mysql_to_postgresql.md +++ /dev/null @@ -1,116 +0,0 @@ -# Migrating GitLab from MySQL to Postgres -*Make sure you view this [guide from the `master` branch](../../../master/doc/update/mysql_to_postgresql.md) for the most up to date instructions.* - -If you are replacing MySQL with Postgres while keeping GitLab on the same server all you need to do is to export from MySQL, import into Postgres and rebuild the indexes as described below. If you are also moving GitLab to another server, or if you are switching to omnibus-gitlab, you may want to use a GitLab backup file. The second part of this documents explains the procedure to do this. - -## Export from MySQL and import into Postgres - -Use this if you are keeping GitLab on the same server. - -``` -sudo service gitlab stop - -# Update /home/git/gitlab/config/database.yml - -git clone https://github.com/gitlabhq/mysql-postgresql-converter.git -b gitlab -cd mysql-postgresql-converter -mysqldump --compatible=postgresql --default-character-set=utf8 -r databasename.mysql -u root gitlabhq_production -p -python db_converter.py databasename.mysql databasename.psql - -# Import the database dump as the application database user -sudo -u git psql -f databasename.psql -d gitlabhq_production - -# Rebuild indexes (see below) - -# Install gems for PostgreSQL (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -sudo service gitlab start -``` - -## Rebuild indexes - -The lanyrd database converter script does not preserve all indexes, so we have to recreate them ourselves after migrating from MySQL. It is not necessary to shut down GitLab for this process. - -### For non-omnibus installations - -On non-omnibus installations (distributed using Git) we retrieve the index declarations from version control using `git stash`. - -``` -# Clone the database converter on your Postgres-backed GitLab server -cd /tmp -git clone https://github.com/gitlabhq/mysql-postgresql-converter.git -b gitlab - -cd /home/git/gitlab - -# Stash changes to db/schema.rb to make sure we can find the right index statements -sudo -u git -H git stash - -# Generate add_index.rb -ruby /tmp/mysql-postgresql-converter/add_index_statements.rb db/schema.rb > /tmp/mysql-postgresql-converter/add_index.rb - -# Create the indexes -sudo -u git -H bundle exec rails runner -e production 'eval $stdin.read' < /tmp/mysql-postgresql-converter/add_index.rb -``` - -### For omnibus-gitlab installations - -On omnibus-gitlab we need to get the index declarations from a file called `schema.rb.bundled`. For versions older than 6.9, we need to download the file. - -``` -# Clone the database converter on your Postgres-backed GitLab server -cd /tmp -/opt/gitlab/embedded/bin/git clone https://github.com/gitlabhq/mysql-postgresql-converter.git -b gitlab -cd /tmp/mysql-postgresql-converter - -# Download schema.rb.bundled if necessary -test -e /opt/gitlab/embedded/service/gitlab-rails/db/schema.rb.bundled || sudo /opt/gitlab/embedded/bin/curl -o /opt/gitlab/embedded/service/gitlab-rails/db/schema.rb.bundled https://gitlab.com/gitlab-org/gitlab-ce/raw/v6.9.1/db/schema.rb - -# Generate add_index.rb -/opt/gitlab/embedded/bin/ruby add_index_statements.rb /opt/gitlab/embedded/service/gitlab-rails/db/schema.rb.bundled > add_index.rb - -# Create the indexes -/opt/gitlab/bin/gitlab-rails runner 'eval $stdin.read' < add_index.rb -``` - -## Converting a GitLab backup file from MySQL to Postgres -**Note:** Please make sure to have Python 2.7.x (or higher) installed. - -GitLab backup files (`<timestamp>_gitlab_backup.tar`) contain a SQL dump. Using the lanyrd database converter we can replace a MySQL database dump inside the tar file with a Postgres database dump. This can be useful if you are moving to another server. - -``` -# Stop GitLab -sudo service gitlab stop - -# Create the backup -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production - -# Note the filename of the backup that was created. We will call it -# TIMESTAMP_gitlab_backup.tar below. - -# Move the backup file we will convert to its own directory -sudo -u git -H mkdir -p tmp/backups/postgresql -sudo -u git -H mv tmp/backups/TIMESTAMP_gitlab_backup.tar tmp/backups/postgresql/ - -# Create a separate database dump with PostgreSQL compatibility -cd tmp/backups/postgresql -sudo -u git -H mysqldump --compatible=postgresql --default-character-set=utf8 -r gitlabhq_production.mysql -u root gitlabhq_production -p - -# Clone the database converter -sudo -u git -H git clone https://github.com/gitlabhq/mysql-postgresql-converter.git -b gitlab - -# Convert gitlabhq_production.mysql -sudo -u git -H mkdir db -sudo -u git -H python mysql-postgresql-converter/db_converter.py gitlabhq_production.mysql db/database.sql - -# Replace the MySQL dump in TIMESTAMP_gitlab_backup.tar. - -# Warning: if you forget to replace TIMESTAMP below, tar will create a new file -# 'TIMESTAMP_gitlab_backup.tar' without giving an error. - -sudo -u git -H tar rf TIMESTAMP_gitlab_backup.tar db/database.sql - -# Done! TIMESTAMP_gitlab_backup.tar can now be restored into a Postgres GitLab -# installation. Remember to recreate the indexes after the import. -``` diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md deleted file mode 100644 index e29ee2a7b3d..00000000000 --- a/doc/update/patch_versions.md +++ /dev/null @@ -1,70 +0,0 @@ -# Universal update guide for patch versions -*Make sure you view this [upgrade guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/patch_versions.md) from the `master` branch for the most up to date instructions.* - -For example from 6.2.0 to 6.2.1, also see the [semantic versioning specification](http://semver.org/). - -### 0. Backup - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - - sudo service gitlab stop - -### 2. Get latest code for the stable branch - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout LATEST_TAG -``` - -Replace LATEST_TAG with the latest GitLab tag you want to upgrade to, for example `v6.6.3`. - -### 3. Update gitlab-shell to the corresponding version - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -#PostgreSQL -sudo -u git -H bundle install --without development test mysql --deployment - -# MySQL -sudo -u git -H bundle install --without development test postgres --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -### 5. Start application - - sudo service gitlab start - sudo service nginx restart - -### 6. 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 with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! diff --git a/doc/update/upgrader.md b/doc/update/upgrader.md deleted file mode 100644 index f62a53d3340..00000000000 --- a/doc/update/upgrader.md +++ /dev/null @@ -1,76 +0,0 @@ -# GitLab Upgrader -*Make sure you view this [upgrade guide from the `master` branch](../../../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. - -For example it can update your application from 6.4 to latest GitLab 6 version (like 6.6.1). - -You still need to create a backup and manually restart GitLab after running the script but all other operations are done by this upgrade script. - -If you have local changes to your GitLab repository the script will stash them and you need to use `git stash pop` after running the script. - -**GitLab Upgrader is available only for GitLab version 6.4.2 or higher.** - -**This script does NOT update gitlab-shell, it needs manual update. See step 5 below.** - -## 0. Backup - - cd /home/git/gitlab - sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production - -## 1. Stop server - - sudo service gitlab stop - -## 2. Run GitLab upgrade tool - -Note: GitLab 7.9 adds `nodejs` as a dependency. GitLab 7.6 adds `libkrb5-dev` as a dependency (installed by default on Ubuntu and OSX). GitLab 7.2 adds `pkg-config` and `cmake` as dependency. Please check the dependencies in the [installation guide.](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) - - # Starting with GitLab version 7.0 upgrader script has been moved to bin directory - cd /home/git/gitlab - if [ -f bin/upgrade.rb ]; then sudo -u git -H ruby bin/upgrade.rb; else sudo -u git -H ruby script/upgrade.rb; fi - - # to perform a non-interactive install (no user input required) you can add -y - # if [ -f bin/upgrade.rb ]; then sudo -u git -H ruby bin/upgrade.rb -y; else sudo -u git -H ruby script/upgrade.rb -y; fi - -## 3. Start application - - sudo service gitlab start - sudo service nginx restart - -## 4. Check application status - -Check if GitLab and its dependencies are configured correctly: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## 5. Upgrade GitLab Shell - -GitLab Shell might be outdated, running the commands below ensures you're using a compatible version: - -``` -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -``` - -## One line upgrade command - -You've read through the entire guide and probably already did all the steps one by one. - -Here is a one line command with step 1 to 5 for the next time you upgrade: - -```bash -cd /home/git/gitlab; \ - sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production; \ - sudo service gitlab stop; \ - if [ -f bin/upgrade.rb ]; then sudo -u git -H ruby bin/upgrade.rb -y; else sudo -u git -H ruby script/upgrade.rb -y; fi; \ - cd /home/git/gitlab-shell; \ - sudo -u git -H git fetch; \ - sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION`; \ - cd /home/git/gitlab; \ - sudo service gitlab start; \ - sudo service nginx restart; sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` diff --git a/doc/web_hooks/web_hooks.md b/doc/web_hooks/web_hooks.md deleted file mode 100644 index 851f50f5e9a..00000000000 --- a/doc/web_hooks/web_hooks.md +++ /dev/null @@ -1,218 +0,0 @@ -# Web hooks - -Project web hooks allow you to trigger an URL if new code is pushed or a new issue is created. - -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. - -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. - -If you send a web hook to an SSL endpoint [the certificate will not be verified](https://gitlab.com/gitlab-org/gitlab-ce/blob/ccd617e58ea71c42b6b073e692447d0fe3c00be6/app/models/web_hook.rb#L35) since many people use self-signed certificates. - -## Push events - -Triggered when you push to the repository except when pushing tags. - -**Request body:** - -```json -{ - "object_kind": "push", - "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", - "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "ref": "refs/heads/master", - "user_id": 4, - "user_name": "John Smith", - "user_email": "john@example.com", - "project_id": 15, - "repository": { - "name": "Diaspora", - "url": "git@example.com:mike/diasporadiaspora.git", - "description": "", - "homepage": "http://example.com/mike/diaspora", - "git_http_url":"http://example.com/mike/diaspora.git", - "git_ssh_url":"git@example.com:mike/diaspora.git", - "visibility_level":0 - }, - "commits": [ - { - "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", - "message": "Update Catalan translation to e38cb41.", - "timestamp": "2011-12-12T14:27:31+02:00", - "url": "http://example.com/mike/diaspora/commit/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327", - "author": { - "name": "Jordi Mallach", - "email": "jordi@softcatala.org" - } - }, - { - "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "message": "fixed readme", - "timestamp": "2012-01-03T23:36:29+02:00", - "url": "http://example.com/mike/diaspora/commit/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "author": { - "name": "GitLab dev user", - "email": "gitlabdev@dv6700.(none)" - } - } - ], - "total_commits_count": 4 -} -``` - -## Tag events - -Triggered when you create (or delete) tags to the repository. - -**Request body:** - -```json -{ - "object_kind": "tag_push", - "ref": "refs/tags/v1.0.0", - "before": "0000000000000000000000000000000000000000", - "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", - "user_id": 1, - "user_name": "John Smith", - "project_id": 1, - "repository": { - "name": "jsmith", - "url": "ssh://git@example.com/jsmith/example.git", - "description": "", - "homepage": "http://example.com/jsmith/example", - "git_http_url":"http://example.com/jsmith/example.git", - "git_ssh_url":"git@example.com:jsmith/example.git", - "visibility_level":0 - }, - "commits": [], - "total_commits_count": 0 -} -``` - -## Issues events - -Triggered when a new issue is created or an existing issue was updated/closed/reopened. - -**Request body:** - -```json -{ - "object_kind": "issue", - "user": { - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - }, - "object_attributes": { - "id": 301, - "title": "New API: create/update/delete file", - "assignee_id": 51, - "author_id": 51, - "project_id": 14, - "created_at": "2013-12-03T17:15:43Z", - "updated_at": "2013-12-03T17:15:43Z", - "position": 0, - "branch_name": null, - "description": "Create new API for manipulations with repository", - "milestone_id": null, - "state": "opened", - "iid": 23, - "url": "http://example.com/diaspora/issues/23", - "action": "open" - } -} -``` - -## Merge request events - -Triggered when a new merge request is created or an existing merge request was updated/merged/closed. - -**Request body:** - -```json -{ - "object_kind": "merge_request", - "user": { - "name": "Administrator", - "username": "root", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - }, - "object_attributes": { - "id": 99, - "target_branch": "master", - "source_branch": "ms-viewport", - "source_project_id": 14, - "author_id": 51, - "assignee_id": 6, - "title": "MS-Viewport", - "created_at": "2013-12-03T17:23:34Z", - "updated_at": "2013-12-03T17:23:34Z", - "st_commits": null, - "st_diffs": null, - "milestone_id": null, - "state": "opened", - "merge_status": "unchecked", - "target_project_id": 14, - "iid": 1, - "description": "", - "source": { - "name": "awesome_project", - "ssh_url": "ssh://git@example.com/awesome_space/awesome_project.git", - "http_url": "http://example.com/awesome_space/awesome_project.git", - "visibility_level": 20, - "namespace": "awesome_space" - }, - "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", - "visibility_level": 20, - "namespace": "awesome_space" - }, - "last_commit": { - "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "message": "fixed readme", - "timestamp": "2012-01-03T23:36:29+02:00", - "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7", - "author": { - "name": "GitLab dev user", - "email": "gitlabdev@dv6700.(none)" - } - }, - "url": "http://example.com/diaspora/merge_requests/1", - "action": "open" - } -} -``` - -#### Example webhook receiver - -If you want to see GitLab's webhooks in action for testing purposes you can use -a simple echo script running in a console session. - -Save the following file as `print_http_body.rb`. - -```ruby -require 'webrick' - -server = WEBrick::HTTPServer.new(:Port => ARGV.first) -server.mount_proc '/' do |req, res| - puts req.body -end - -trap 'INT' do - server.shutdown -end -server.start -``` - -Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb -8000`. Then add your server as a webhook receiver in GitLab as -`http://my.host:8000/`. - -When you press 'Test Hook' in GitLab, you should see something like this in the console. - -``` -{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>} -example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 -- -> / -``` diff --git a/doc/workflow/README.md b/doc/workflow/README.md deleted file mode 100644 index 7e996dc47d4..00000000000 --- a/doc/workflow/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Workflow - -- [Feature branch workflow](workflow.md) -- [Project forking workflow](forking_workflow.md) -- [Project Features](project_features.md) -- [Authorization for merge requests](authorization_for_merge_requests.md) -- [Groups](groups.md) -- [Labels](labels.md) -- [GitLab Flow](gitlab_flow.md) -- [Notifications](notifications.md) -- [Migrating from SVN to GitLab](migrating_from_svn.md) -- [Project importing from GitHub to GitLab](import_projects_from_github.md) -- [Project importing from GitLab.com to your private GitLab instance](import_projects_from_gitlab_com.md) -- [Protected branches](protected_branches.md) -- [Web Editor](web_editor.md) diff --git a/doc/workflow/authorization_for_merge_requests.md b/doc/workflow/authorization_for_merge_requests.md deleted file mode 100644 index d1d6d94ec11..00000000000 --- a/doc/workflow/authorization_for_merge_requests.md +++ /dev/null @@ -1,40 +0,0 @@ -# Authorization for Merge requests - -There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project. - -## Protected branch flow - -With the protected branch flow everybody works within the same GitLab project. - -The project maintainers get Master access and the regular developers get Developer access. - -The maintainers mark the authoritative branches as 'Protected'. - -The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. - -Only users with Master access can merge changes into a protected branch. - -### Advantages - -- fewer projects means less clutter -- developers need to consider only one remote repository - -### Disadvantages - -- manual setup of protected branch required for each new project - -## Forking workflow - -With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. - -Developers create forks of the authoritative project and push their feature branches to their own forks. - -To get their changes into master they need to create a merge request across forks. - -### Advantages - -- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects - -### Disadvantages - -- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes) diff --git a/doc/workflow/ci_mr.png b/doc/workflow/ci_mr.png Binary files differdeleted file mode 100644 index a577356f8e8..00000000000 --- a/doc/workflow/ci_mr.png +++ /dev/null diff --git a/doc/workflow/close_issue_mr.png b/doc/workflow/close_issue_mr.png Binary files differdeleted file mode 100644 index a136d642e12..00000000000 --- a/doc/workflow/close_issue_mr.png +++ /dev/null diff --git a/doc/workflow/environment_branches.png b/doc/workflow/environment_branches.png Binary files differdeleted file mode 100644 index ee893ced13b..00000000000 --- a/doc/workflow/environment_branches.png +++ /dev/null diff --git a/doc/workflow/forking/branch_select.png b/doc/workflow/forking/branch_select.png Binary files differdeleted file mode 100644 index 275f64d113b..00000000000 --- a/doc/workflow/forking/branch_select.png +++ /dev/null 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/merge_request.png b/doc/workflow/forking/merge_request.png Binary files differdeleted file mode 100644 index 2dc00ed08a1..00000000000 --- a/doc/workflow/forking/merge_request.png +++ /dev/null diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md deleted file mode 100644 index 8edf7c6ab3d..00000000000 --- a/doc/workflow/forking_workflow.md +++ /dev/null @@ -1,36 +0,0 @@ -# Project forking workflow - -Forking a project to your own namespace is useful if you have no write access to the project you want to contribute -to. If you do have write access or can request it we recommend working together in the same repository since it is simpler. -See our **[GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/)** article for 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. - - - -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. - - - -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. - - - -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. - - - - diff --git a/doc/workflow/four_stages.png b/doc/workflow/four_stages.png Binary files differdeleted file mode 100644 index 2f444fc6f79..00000000000 --- a/doc/workflow/four_stages.png +++ /dev/null diff --git a/doc/workflow/git_pull.png b/doc/workflow/git_pull.png Binary files differdeleted file mode 100644 index 7d47064eb14..00000000000 --- a/doc/workflow/git_pull.png +++ /dev/null diff --git a/doc/workflow/gitdashflow.png b/doc/workflow/gitdashflow.png Binary files differdeleted file mode 100644 index f2f091dd10b..00000000000 --- a/doc/workflow/gitdashflow.png +++ /dev/null diff --git a/doc/workflow/github_flow.png b/doc/workflow/github_flow.png Binary files differdeleted file mode 100644 index 88addb623ee..00000000000 --- a/doc/workflow/github_flow.png +++ /dev/null diff --git a/doc/workflow/github_importer/importer.png b/doc/workflow/github_importer/importer.png Binary files differdeleted file mode 100644 index 57636717571..00000000000 --- a/doc/workflow/github_importer/importer.png +++ /dev/null diff --git a/doc/workflow/github_importer/new_project_page.png b/doc/workflow/github_importer/new_project_page.png Binary files differdeleted file mode 100644 index 002f22d81d7..00000000000 --- a/doc/workflow/github_importer/new_project_page.png +++ /dev/null diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md deleted file mode 100644 index 0e87dc74217..00000000000 --- a/doc/workflow/gitlab_flow.md +++ /dev/null @@ -1,316 +0,0 @@ - - -## Introduction - -Version management with git makes branching and merging much easier than older versioning systems such as SVN. -This allows a wide variety of branching strategies and workflows. -Almost all of these are an improvement over the methods used before git. -But many organizations end up with a workflow that is not clearly defined, overly complex or not integrated with issue tracking systems. -Therefore we propose the GitLab flow as clearly defined set of best practices. -It combines [feature driven development](http://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](http://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. - -Organizations coming to git from other version control systems frequently find it hard to develop an effective workflow. -This article describes the GitLab flow that integrates the git workflow with an issue tracking system. -It offers a simple, transparent and effective way to work with git. - - - -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. -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. - - - -Since many organizations new to git have no conventions how to work with it, it can quickly become a mess. -The biggest problem they run into is that many long running branches that each contain part of the changes are around. -People have a hard time figuring out which branch they should develop on or deploy to production. -Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html) -We think there is still room for improvement and will detail a set of practices we call GitLab flow. - -## Git flow and its problems - -[ - -Git flow was one of the first proposals to use git branches and it has gotten a lot of attention. -It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes. -The development happens on the develop branch, moves to a release branch and is finally merged into the master branch. -Git flow is a well defined standard but its complexity introduces two problems. -The first problem is that developers must use the develop branch and not master, master is reserved for code that is released to production. -It is a convention to call your default branch master and to mostly branch from and merge to this. -Since most tools automatically make the master branch the default one and display that one by default it is annoying to have to switch to another one. -The second problem of git flow is the complexity introduced by the hotfix and release branches. -These branches can be a good idea for some organizations but are overkill for the vast majority of them. -Nowadays most organizations practice continuous delivery which means that your default branch can be deployed. -This means that hotfix and release branches can be prevented including all the ceremony they introduce. -An example of this ceremony is the merging back of release branches. -Though specialized tools do exist to solve this, they require documentation and add complexity. -Frequently developers make a mistake and for example changes are only merged into master and not into the develop branch. -The root cause of these errors is that git flow is too complex for most of the use cases. -And doing releases doesn't automatically mean also doing hotfixes. - -## GitHub flow as a simpler alternative - - - - In reaction to git flow a simpler alternative was detailed, [GitHub flow](https://guides.github.com/introduction/flow/index.html). -This flow has only feature branches and a master branch. -This is very simple and clean, many organizations have adopted it with great success. -Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches. -Merging everything into the master branch and deploying often means you minimize the amount of code in 'inventory' which is in line with the lean and continuous delivery best practices. -But this flow still leaves a lot of questions unanswered regarding deployments, environments, releases and integrations with issues. -With GitLab flow we offer additional guidance for these questions. - -## Production branch with GitLab flow - - - -GitHub flow does assume you are able to deploy to production every time you merge a feature branch. -This is possible for SaaS applications but are many cases where this is not possible. -One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass App Store validation. -Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times. -In these cases you can make a production branch that reflects the deployed code. -You can deploy a new version by merging in master to the production branch. -If you need to know what code is in production you can just checkout the production branch to see. -The approximate time of deployment is easily visible as the merge commit in the version control system. -This time is pretty accurate if you automatically deploy your production branch. -If you need a more exact time you can have your deployment script create a tag on each deployment. -This flow prevents the overhead of releasing, tagging and merging that is common to git flow. - -## Environment branches with GitLab flow - - - -It might be a good idea to have an environment that is automatically updated to the master branch. -Only in this case, the name of this environment might differ from the branch name. -Suppose you have a staging environment, a pre-production environment and a production environment. -In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch. -And going live with code happens by merging the pre-production branch into the production branch. -This workflow where commits only flow downstream ensures that everything has been tested on all environments. -If you need to cherry-pick a commit with a hotfix it is common to develop it on a feature branch and merge it into master with a merge request, do not delete the feature branch. -If master is good to go (it should be if you a practicing [continuous delivery](http://martinfowler.com/bliki/ContinuousDelivery.html)) you then merge it to the other branches. -If this is not possible because more manual testing is required you can send merge requests from the feature branch to the downstream branches. -An 'extreme' version of environment branches are setting up an environment for each feature branch as done by [Teatro](http://teatro.io/). - -## Release branches with GitLab flow - - - -Only in case you need to release software to the outside world you need to work with release branches. -In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.). -The stable branch uses master as a starting point and is created as late as possible. -By branching as late as possible you minimize the time you have to apply bug fixes to multiple branches. -After a release branch is announced, only serious bug fixes are included in the release branch. -If possible these bug fixes are first merged into master and then cherry-picked into the release branch. -This way you can't forget to cherry-pick them into master and encounter the same bug on subsequent releases. -This is called an 'upstream first' policy that is also practiced by [Google](http://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](http://www.redhat.com/about/news/archive/2013/5/a-community-for-using-openstack-with-red-hat-rdo). -Every time a bug-fix is included in a release branch the patch version is raised (to comply with [Semantic Versioning](http://semver.org/)) by setting a new tag. -Some projects also have a stable branch that points to the same commit as the latest released branch. -In this flow it is not common to have a production branch (or git flow master branch). - -## Merge/pull requests with GitLab flow - - - -Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. -Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch. -Tools such as GitLab and Gitorious choose the name merge request since that is the final action that is requested of the assignee. -In this article we'll refer to them as merge requests. - -If you work on a feature branch for more than a few hours it is good to share the intermediate result with the rest of the team. -This can be done by creating a merge request without assigning it to anyone, instead you mention people in the description or a comment (/cc @mark @susan). -This means it is not ready to be merged but feedback is welcome. -Your team members can comment on the merge request in general or on specific lines with line comments. -The merge requests serves as a code review tool and no separate tools such as Gerrit and reviewboard should be needed. -If the review reveals shortcomings anyone can commit and push a fix. -Commonly the person to do this is the creator of the merge/pull request. -The diff in the merge/pull requests automatically updates when new commits are pushed on the branch. - -When you feel comfortable with it to be merged you assign it to the person that knows most about the codebase you are changing and mention any other people you would like feedback from. -There is room for more feedback and after the assigned person feels comfortable with the result the branch is merged. -If the assigned person does not feel comfortable they can close the merge request without merging. - -In GitLab it is common to protect the long-lived branches (e.g. the master branch) so that normal developers [can't modify these protected branches](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/permissions/permissions.md). -So if you want to merge it into a protected branch you assign it to someone with master authorizations. - -## Issues with GitLab flow - - - -GitLab flow is a way to make the relation between the code and the issue tracker more transparent. - -Any significant change to the code should start with an issue where the goal is described. -Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small. -In GitLab each change to the codebase starts with an issue in the issue tracking system. -If there is no issue yet it should be created first provided there is significant work involved (more than 1 hour). -For many organizations this will be natural since the issue will have to be estimated for the sprint. -Issue titles should describe the desired state of the system, e.g. "As an administrator I want to remove users without receiving an error" instead of "Admin can't remove users.". - -When you are ready to code you start a branch for the issue from the master branch. -The name of this branch should start with the issue number, for example '15-require-a-password-to-change-it'. - -When you are done or want to discuss the code you open a merge request. -This is an online place to discuss the change and review the code. -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. -These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet. - -When the author thinks the code is ready the merge request is assigned to reviewer. -The reviewer presses the merge button when they think the code is ready for inclusion in the master branch. -In this case the code is merged and a merge commit is generated that makes this event easily visible later on. -Merge requests always create a merge commit even when the commit could be added without one. -This merge strategy is called 'no fast-forward' in git. -After the merge the feature branch is deleted since it is no longer needed, in GitLab this deletion is an option when merging. - -Suppose that a branch is merged but a problem occurs and the issue is reopened. -In this case it is no problem to reuse the same branch name since it was deleted when the branch was merged. -At any time there is at most one branch for every issue. -It is possible that one feature branch solves more than one issue. - -## Linking and closing issues from merge requests - - - -Linking to the issue can happen by mentioning them from commit messages (fixes #14, closes #67, etc.) or from the merge request description. -In GitLab this creates a comment in the issue that the merge requests mentions the issue. -And the merge request shows the linked issues. -These issues are closed once code is merged into the default branch. - -If you only want to make the reference without closing the issue you can also just mention it: "Duck typing is preferred. #12". - -If you have an issue that spans across multiple repositories, the best thing is to create an issue for each repository and link all issues to a parent issue. - -## Squashing commits with rebase - - - -With git you can use an interactive rebase (rebase -i) to squash multiple commits into one and reorder them. -This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. -However you should never rebase commits you have pushed to a remote server. -Somebody can have referred to the commits or cherry-picked them. -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. - -People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on. -This will lead to many commits per change which makes the history harder to understand. -But the advantages of having stable identifiers outweigh this drawback. -And to understand a change in context one can always look at the merge commit that groups all the commits together when the code is merged into the master branch. - -After you merge multiple commits from a feature branch into the master branch this is harder to undo. -If you would have squashed all the commits into one you could have just reverted this commit but as we indicated you should not rebase commits after they are pushed. -Fortunately [reverting a merge made some time ago](http://git-scm.com/blog/2010/03/02/undoing-merges.html) can be done with git. -This however, requires having specific merge commits for the commits your want to revert. -If you revert a merge and you change your mind, revert the revert instead of merging again since git will not allow you to merge the code again otherwise. - -Being able to revert a merge is a good reason always to create a merge commit when you merge manually with the `--no-ff` option. -Git management software will always create a merge commit when you accept a merge request. - -## Do not order commits with rebase - - - -With git you can also rebase your feature branch commits to order them after the commits on the master branch. -This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history. -However, just like with squashing you should never rebase commits you have pushed to a remote server. -This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend. -When using rebase to keep your feature branch updated you [need to resolve similar conflicts again and again](http://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/). -You can reuse recorded resolutions (rerere) sometimes, but with without rebasing you only have to solve the conflicts one time and you’re set. -There has to be a better way to avoid many merge commits. - -The way to prevent creating many merge commits is to not frequently merge master into the feature branch. -We'll discuss the three reasons to merge in master: leveraging code, solving 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. -The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project. -Martin Fowler, in [his article about feature branches](http://martinfowler.com/bliki/FeatureBranch.html) talks about this Continuous Integration (CI). -At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. -That's continuous building, and a Good Thing, but there's no integration, so it's not CI.". -The solution to prevent many merge commits is to keep your feature branches short-lived, the vast majority should take less than one day of work. -If your feature branches commonly take more than a day of work, look into ways to create smaller units of work and/or use [feature toggles](http://martinfowler.com/bliki/FeatureToggle.html). -As for the long running branches that take more than one day there are two strategies. -In a CI strategy you can merge in master at the start of the day to prevent painful merges at a later time. -In a synchronization point strategy you only merge in from well defined points in time, for example a tagged release. -This strategy is [advocated by Linus Torvalds](https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html) because the state of the code at these points is better known. - -In conclusion, we can say that you should try to prevent merge commits, but not eliminate them. -Your codebase should be clean but your history should represent what actually happened. -Developing software happen in small messy steps and it is OK to have your history reflect this. -You can use tools to view the network graphs of commits and understand the messy history that created your code. -If you rebase code the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers. - -## Voting on merge requests - - - -It is common to voice approval or disapproval by using +1 or -1 emoticons. -In GitLab the +1 and -1 are aggregated and shown at the top of the merge request. -As a rule of thumb anything that doesn't have two times more +1's than -1's is suspect and should not be merged yet. - -## Pushing and removing branches - - - -We recommend that people push their feature branches frequently, even when they are not ready for review yet. -By doing this you prevent team members from accidentally starting to work on the same issue. -Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software. -However sometimes one of the two parties forgets to assign someone in the issue tracking software. -After a branch is merged it should be removed from the source control software. -In GitLab and similar systems this is an option when merging. -This ensures that the branch overview in the repository management software shows only work in progress. -This also ensures that when someone reopens the issue a new branch with the same name can be used without problem. -When you reopen an issue you need to create a new merge request. - -## Committing often and with the right message - - - -We recommend to commit early and often. -Each time you have a functioning set of tests and code a commit can be made. -The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version. -This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. -The trick is to use the merge/pull request with multiple commits when your work is ready to share. -The commit message should reflect your intention, not the contents of the commit. -The contents of the commit can be easily seen anyway, the question is why you did it. -An example of a good commit message is: "Combine templates to dry up the user views.". -Some words that are bad commit messages because they don't contain munch information are: change, improve and refactor. -The word fix or fixes is also a red flag, unless it comes after the commit sentence and references an issue number. -To see more information about the formatting of commit messages please see this great [blog post by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). - -## Testing before merging - - - -In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. -Developers had to ensure their code did not break the master branch. -When using GitLab flow developers create their branches from this master branch so it is essential it is green. -Therefore each merge request must be tested before it is accepted. -CI software like Travis and GitLab CI show the build results right in the merge request itself to make this easy. -One drawback is that they are testing the feature branch itself and not the merged result. -What one can do to improve this is to test the merged result itself. -The problem is that the merge result changes every time something is merged into master. -Retesting on every commit to master is computationally expensive and means you are more frequently waiting for test results. -If there are no merge conflicts and the feature branches are short lived the risk is acceptable. -If there are merge conflicts you merge the master branch into the feature branch and the CI server will rerun the tests. -If you have long lived feature branches that last for more than a few days you should make your issues smaller. - -## Merging in other code - - - -When initiating a feature branch, always start with an up to date master to branch off from. -If you know beforehand that your work absolutely depends on another branch you can also branch from there. -If you need to merge in another branch after starting explain the reason in the merge commit. -If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch. -Do not merge in upstream if your code will work and merge cleanly without doing so, Linus even says that [you should never merge in upstream at random points, only at major releases](http://lwn.net/Articles/328438/). -Merging only when needed prevents creating merge commits in your feature branch that later end up littering the master history. - -### References - -- [Sketch file](https://www.dropbox.com/s/58dvsj5votbwrzv/git_flows.sketch?dl=0) with vectors of images in this article -- [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/) diff --git a/doc/workflow/gitlab_flow.png b/doc/workflow/gitlab_flow.png Binary files differdeleted file mode 100644 index 1ea191a672b..00000000000 --- a/doc/workflow/gitlab_flow.png +++ /dev/null diff --git a/doc/workflow/gitlab_importer/importer.png b/doc/workflow/gitlab_importer/importer.png Binary files differdeleted file mode 100644 index d2a286d8cac..00000000000 --- a/doc/workflow/gitlab_importer/importer.png +++ /dev/null diff --git a/doc/workflow/gitlab_importer/new_project_page.png b/doc/workflow/gitlab_importer/new_project_page.png Binary files differdeleted file mode 100644 index 5e239208e1e..00000000000 --- a/doc/workflow/gitlab_importer/new_project_page.png +++ /dev/null diff --git a/doc/workflow/good_commit.png b/doc/workflow/good_commit.png Binary files differdeleted file mode 100644 index 3737a026644..00000000000 --- a/doc/workflow/good_commit.png +++ /dev/null diff --git a/doc/workflow/groups.md b/doc/workflow/groups.md deleted file mode 100644 index 52bf611dc5e..00000000000 --- a/doc/workflow/groups.md +++ /dev/null @@ -1,71 +0,0 @@ -# GitLab Groups - -GitLab groups allow you to group projects into directories and give users to several projects at once. - -When you create a new project in GitLab, the default namespace for the project is the personal namespace associated with your GitLab user. -In this document we will see how to create groups, put projects in groups and manage who can access the projects in a group. - -## Creating groups - -You can create a group by going to the 'Groups' tab of the GitLab dashboard and clicking the 'New group' button. - - - -Next, enter the name (required) and the optional description and group avatar. - - - -When your group has been created you are presented with the group dashboard feed, which will be empty. - - - -You can use the 'New project' button to add a project to the new group. - -## Transferring an existing project into a group - -You can transfer an existing project into a group you own from the project settings page. -First scroll down to the 'Dangerous settings' and click 'Show them to me'. -Now you can pick any of the groups you manage as the new namespace for the group. - - - -GitLab administrators can use the admin interface to move any project to any namespace if needed. - -## Adding users to a group - -One of the benefits of putting multiple projects in one group is that you can give a user to access to all projects in the group with one action. - -Suppose we have a group with two projects. - - - -On the 'Group Members' page we can now add a new user Barry to the group. - - - -Now because Barry is a 'Developer' member of the 'Open Source' group, he automatically gets 'Developer' access to all projects in the 'Open Source' group. - - - -If necessary, you can increase the access level of an individual user for a specific project, by adding them as a Member to the project. - - - -## Managing group memberships via LDAP - -In GitLab Enterprise Edition it is possible to manage GitLab group memberships using LDAP groups. -See [the GitLab Enterprise Edition documentation](http://doc.gitlab.com/ee/integration/ldap.html) for more information. - -## Allowing only admins to create groups - -By default, any GitLab user can create new groups. -This ability can be disabled for individual users from the admin panel. -It is also possible to configure GitLab so that new users default to not being able to create groups: - -``` -# For omnibus-gitlab, put the following in /etc/gitlab/gitlab.rb -gitlab_rails['gitlab_default_can_create_group'] = false - -# For installations from source, uncomment the 'default_can_create_group' -# line in /home/git/gitlab/config/gitlab.yml -``` diff --git a/doc/workflow/groups/add_member_to_group.png b/doc/workflow/groups/add_member_to_group.png Binary files differdeleted file mode 100644 index fa340ce572f..00000000000 --- a/doc/workflow/groups/add_member_to_group.png +++ /dev/null diff --git a/doc/workflow/groups/group_dashboard.png b/doc/workflow/groups/group_dashboard.png Binary files differdeleted file mode 100644 index 7fc9048d74d..00000000000 --- a/doc/workflow/groups/group_dashboard.png +++ /dev/null diff --git a/doc/workflow/groups/group_with_two_projects.png b/doc/workflow/groups/group_with_two_projects.png Binary files differdeleted file mode 100644 index 87242781e4f..00000000000 --- a/doc/workflow/groups/group_with_two_projects.png +++ /dev/null diff --git a/doc/workflow/groups/new_group_button.png b/doc/workflow/groups/new_group_button.png Binary files differdeleted file mode 100644 index 51e82798658..00000000000 --- a/doc/workflow/groups/new_group_button.png +++ /dev/null diff --git a/doc/workflow/groups/new_group_form.png b/doc/workflow/groups/new_group_form.png Binary files differdeleted file mode 100644 index bf992c40bc2..00000000000 --- a/doc/workflow/groups/new_group_form.png +++ /dev/null diff --git a/doc/workflow/groups/override_access_level.png b/doc/workflow/groups/override_access_level.png Binary files differdeleted file mode 100644 index f4225a63679..00000000000 --- a/doc/workflow/groups/override_access_level.png +++ /dev/null diff --git a/doc/workflow/groups/project_members_via_group.png b/doc/workflow/groups/project_members_via_group.png Binary files differdeleted file mode 100644 index b13cb1cfd95..00000000000 --- a/doc/workflow/groups/project_members_via_group.png +++ /dev/null diff --git a/doc/workflow/groups/transfer_project.png b/doc/workflow/groups/transfer_project.png Binary files differdeleted file mode 100644 index 044fe10d073..00000000000 --- a/doc/workflow/groups/transfer_project.png +++ /dev/null diff --git a/doc/workflow/import_projects_from_github.md b/doc/workflow/import_projects_from_github.md deleted file mode 100644 index 8644b4ffc73..00000000000 --- a/doc/workflow/import_projects_from_github.md +++ /dev/null @@ -1,13 +0,0 @@ -# Project importing from GitHub to GitLab - -You can import your existing GitHub projects to GitLab. But 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) -To get to the importer page you need to go to "New project" page. - - - -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. - - - -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.
\ No newline at end of file diff --git a/doc/workflow/import_projects_from_gitlab_com.md b/doc/workflow/import_projects_from_gitlab_com.md deleted file mode 100644 index f4c4e955d46..00000000000 --- a/doc/workflow/import_projects_from_gitlab_com.md +++ /dev/null @@ -1,18 +0,0 @@ -# Project importing from GitLab.com to your private GitLab instance - -You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if -GitLab support is enabled on your GitLab instance. -You can read more about Gitlab support [here](http://doc.gitlab.com/ce/integration/gitlab.html) -To get to the importer page you need to go to "New project" page. - - - -Click on the "Import projects from Gitlab.com" link and you will be redirected to GitLab.com -for permission to access your projects. After accepting, you'll be automatically redirected to the importer. - - - - - -To import a project, you can simple click "Import". The importer will import your repository and issues. -Once the importer is done, a new GitLab project will be created with your imported data.
\ No newline at end of file diff --git a/doc/workflow/labels.md b/doc/workflow/labels.md deleted file mode 100644 index 085b7baf5ce..00000000000 --- a/doc/workflow/labels.md +++ /dev/null @@ -1,16 +0,0 @@ -# Labels - -In GitLab, you can easily tag issues and merge requests. If you have permission level `Developer` or higher, you can manage labels. To create, edit or delete a label, go to a project and then to `Issues` and then `Labels`. - -Here you can create a new label. - - - -You can choose to set a color. - - - -If you want to change an existing label, press edit next to the listed label. -You will be presented with the same form as when creating a new label. - - diff --git a/doc/workflow/labels/label1.png b/doc/workflow/labels/label1.png Binary files differdeleted file mode 100644 index cac661a34c8..00000000000 --- a/doc/workflow/labels/label1.png +++ /dev/null diff --git a/doc/workflow/labels/label2.png b/doc/workflow/labels/label2.png Binary files differdeleted file mode 100644 index 44d9fef86d4..00000000000 --- a/doc/workflow/labels/label2.png +++ /dev/null diff --git a/doc/workflow/labels/label3.png b/doc/workflow/labels/label3.png Binary files differdeleted file mode 100644 index e2fce11b7a4..00000000000 --- a/doc/workflow/labels/label3.png +++ /dev/null diff --git a/doc/workflow/merge_commits.png b/doc/workflow/merge_commits.png Binary files differdeleted file mode 100644 index 757b589d0db..00000000000 --- a/doc/workflow/merge_commits.png +++ /dev/null diff --git a/doc/workflow/merge_request.png b/doc/workflow/merge_request.png Binary files differdeleted file mode 100644 index fde3ff5c854..00000000000 --- a/doc/workflow/merge_request.png +++ /dev/null diff --git a/doc/workflow/messy_flow.png b/doc/workflow/messy_flow.png Binary files differdeleted file mode 100644 index 1addb95ca54..00000000000 --- a/doc/workflow/messy_flow.png +++ /dev/null diff --git a/doc/workflow/migrating_from_svn.md b/doc/workflow/migrating_from_svn.md deleted file mode 100644 index 485db4834e9..00000000000 --- a/doc/workflow/migrating_from_svn.md +++ /dev/null @@ -1,17 +0,0 @@ -# Migrating from SVN to GitLab - -SVN stands for Subversion and is a version control system (VCS). -Git is a distributed version control system. - -There are some major differences between the two, for more information consult your favorite search engine. - -Git has tools for migrating SVN repositories to git, namely `git svn`. You can read more about this at -[git documentation pages](http://git-scm.com/book/en/Git-and-Other-Systems-Git-and-Subversion). - -Apart from the [official git documentation](http://git-scm.com/book/en/Git-and-Other-Systems-Migrating-to-Git) there is also -user created step by step guide for migrating from SVN to GitLab. - -[Benjamin New](https://github.com/leftclickben) wrote [a guide that shows how to do a migration](https://gist.github.com/leftclickben/322b7a3042cbe97ed2af). Mirrors can be found [here](https://gitlab.com/snippets/2168) and [here](https://gist.github.com/maxlazio/f1b593b0d00aa966e9ca). - -## Contribute to this guide -We welcome all contributions that would expand this guide with instructions on how to migrate from SVN and other version control systems. diff --git a/doc/workflow/mr_inline_comments.png b/doc/workflow/mr_inline_comments.png Binary files differdeleted file mode 100644 index e851b95bcef..00000000000 --- a/doc/workflow/mr_inline_comments.png +++ /dev/null diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md deleted file mode 100644 index 17215de677e..00000000000 --- a/doc/workflow/notifications.md +++ /dev/null @@ -1,71 +0,0 @@ -# GitLab Notifications - -GitLab has notifications system in place to notify a user of events important for the workflow. - -## Notification settings - -Under user profile page you can find the notification settings. - - - -Notification settings are divided into three groups: - -* Global Settings -* Group Settings -* Project Settings - -Each of these settings have levels of notification: - -* Disabled - turns off notifications -* Participating - receive notifications from related resources -* Watch - receive notifications from projects or groups user is a member of -* Global - notifications as set at the global settings - -#### Global Settings - -Global Settings are at the bottom of the hierarchy. -Any setting set here will be overridden by a setting at the group or a project level. - -Group or Project settings can use `global` notification setting which will then use -anything that is set at Global Settings. - -#### Group Settings - -Group Settings are taking precedence over Global Settings but are on a level below Project Settings. -This means that you can set a different level of notifications per group while still being able -to have a finer level setting per project. -Organization like this is suitable for users that belong to different groups but don't have the -same need for being notified for every group they are member of. - -#### Project Settings - -Project Settings are at the top level and any setting placed at this level will take precedence of any -other setting. -This is suitable for users that have different needs for notifications per project basis. - -## Notification events - -Below is the table of events users can be notified of: - -| Event | Sent to | Settings level | -|------------------------------|-------------------------------------------------------------------|------------------------------| -| New SSH key added | User | Security email, always sent. | -| New email added | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for omniauth (LDAP)| -| New issue created | Issue assignee [1], project members [2] | [1] not disabled, [2] higher than participating | -| User added to project | User | Sent when user is added to project | -| Project access level changed | User | Sent when user project access level is changed | -| User added to group | User | Sent when user is added to group | -| Project moved | Project members [1] | [1] not disabled | -| Group access level changed | User | Sent when user group access level is changed | -| Close issue | Issue author [1], issue assignee [2], project members [3] | [1] [2] not disabled, [3] higher than participating | -| Reassign issue | New issue assignee [1], old issue assignee [2] | [1] [2] not disabled | -| Reopen issue | Project members [1] | [1] higher than participating | -| New merge request | MR assignee [1] | [1] not disabled | -| Reassign merge request | New MR assignee [1], old MR assignee [2] | [1] [2] not disabled | -| Close merge request | MR author [1], MR assignee [2], project members [3] | [1] [2] not disabled, [3] higher than participating | -| Reopen merge request | Project members [1] | [1] higher than participating | -| Merge merge request | MR author [1], MR assignee [2], project members [3] | [1] [2] not disabled, [3] higher than participating | -| New comment | Mentioned users [1], users participating [2], project members [3] | [1] [2] not disabled, [3] higher than participating | - - diff --git a/doc/workflow/notifications/settings.png b/doc/workflow/notifications/settings.png Binary files differdeleted file mode 100644 index e5b50ee2494..00000000000 --- a/doc/workflow/notifications/settings.png +++ /dev/null diff --git a/doc/workflow/production_branch.png b/doc/workflow/production_branch.png Binary files differdeleted file mode 100644 index 33fb26dd621..00000000000 --- a/doc/workflow/production_branch.png +++ /dev/null diff --git a/doc/workflow/project_features.md b/doc/workflow/project_features.md deleted file mode 100644 index a523b3facbe..00000000000 --- a/doc/workflow/project_features.md +++ /dev/null @@ -1,35 +0,0 @@ -# Project features - -When in a Project -> Settings, you will find Features on the bottom of the page that you can toggle. - -Below you will find a more elaborate explanation of each of these. - -## Issues - -Issues is a really powerful, but lightweight issue tracking system. - -You can make tickets, assign them to people, file them under milestones, order them with labels and have discussion in them. - -They integrate deeply into GitLab and are easily referenced from anywhere by using `#` and the issue number. - -## Merge Requests - -Using a merge request, you can review and discuss code before it is merged in the branch of your code. - -As with issues, it can be assigned; people, issues, etc. can be referenced; milestones attached. - -We see it as an integral part of working together on code and couldn't work without it. - -## Wiki - -This is a separate system for documentation, built right into GitLab. - -It is source controlled and is very convenient if you don't want to keep you documentation in your source code, but you do want to keep it in your GitLab project. - -## Snippets - -Snippets are little bits of code or text. - -This is a nice place to put code or text that is used semi-regularly within the project, but does not belong in source control. - -For example, a specific config file that is used by > the team that is only valid for the people that work on the code. diff --git a/doc/workflow/protected_branches.md b/doc/workflow/protected_branches.md deleted file mode 100644 index 805f7f8d35c..00000000000 --- a/doc/workflow/protected_branches.md +++ /dev/null @@ -1,33 +0,0 @@ -# Protected branches - -Permission in GitLab are fundamentally defined around the idea of having read or write permission to the repository and branches. - -To prevent people from messing with history or pushing code without review, we've created protected branches. - -A protected branch does three simple things: - -* it prevents pushes from everybody except users with Master permission -* it prevents anyone from force pushing to the branch -* it prevents anyone from deleting the branch - -You can make any branch a protected branch. GitLab makes the master branch a protected branch by default. - -To protect a branch, user needs to have at least a Master permission level, see [permissions document](permissions/permissions.md). - - - -Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect. - -Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch. - -Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request. - -However, there are workflows where that is not needed and only protecting from force pushes and branch removal is useful. - -For those workflows, you can allow everyone with write access to push to a protected branch by selecting `Developers can push` check box. - -On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box. - - - - diff --git a/doc/workflow/protected_branches/protected_branches1.png b/doc/workflow/protected_branches/protected_branches1.png Binary files differdeleted file mode 100644 index 5c2a3de5f70..00000000000 --- a/doc/workflow/protected_branches/protected_branches1.png +++ /dev/null diff --git a/doc/workflow/protected_branches/protected_branches2.png b/doc/workflow/protected_branches/protected_branches2.png Binary files differdeleted file mode 100644 index 2dca3541365..00000000000 --- a/doc/workflow/protected_branches/protected_branches2.png +++ /dev/null diff --git a/doc/workflow/rebase.png b/doc/workflow/rebase.png Binary files differdeleted file mode 100644 index ef82c834755..00000000000 --- a/doc/workflow/rebase.png +++ /dev/null diff --git a/doc/workflow/release_branches.png b/doc/workflow/release_branches.png Binary files differdeleted file mode 100644 index da7ae53413a..00000000000 --- a/doc/workflow/release_branches.png +++ /dev/null diff --git a/doc/workflow/remove_checkbox.png b/doc/workflow/remove_checkbox.png Binary files differdeleted file mode 100644 index 3e247d38155..00000000000 --- a/doc/workflow/remove_checkbox.png +++ /dev/null diff --git a/doc/workflow/voting_slider.png b/doc/workflow/voting_slider.png Binary files differdeleted file mode 100644 index 4c660ef9593..00000000000 --- a/doc/workflow/voting_slider.png +++ /dev/null diff --git a/doc/workflow/web_editor.md b/doc/workflow/web_editor.md deleted file mode 100644 index 7fc8f96b9ec..00000000000 --- a/doc/workflow/web_editor.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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. - -Click on `Add a file` -to create the first file and open it in the web editor. - - - -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. - - - -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` - - 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 diff --git a/doc/workflow/workflow.md b/doc/workflow/workflow.md deleted file mode 100644 index f70e41df842..00000000000 --- a/doc/workflow/workflow.md +++ /dev/null @@ -1,31 +0,0 @@ -# Feature branch workflow - -1. Clone project: - - ```bash - git clone git@example.com:project-name.git - ``` - -1. Create branch with your feature: - - ```bash - git checkout -b $feature_name - ``` - -1. Write code. Commit changes: - - ```bash - git commit -am "My feature is ready" - ``` - -1. Push your branch to GitLab: - - ```bash - git push origin $feature_name - ``` - -1. Review your code on commits page. - -1. Create a merge request. - -1. Your team lead will review the code & merge it to the main branch. |
