Update docs to markdown style guide.

parent de1a7aa7
......@@ -24,16 +24,11 @@ Issues and merge requests should be in English and contain appropriate language
To get support for your particular problem please use the channels as detailed in the [getting help section of the readme](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/README.md#getting-help). Professional [support subscriptions](http://www.gitlab.com/subscription/) and [consulting services](http://www.gitlab.com/consultancy/) are available from [GitLab.com](http://www.gitlab.com/).
The [issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues) is only for obvious errors in the latest [stable or development release of GitLab](MAINTENANCE.md).
If something is wrong but it is not a regression compared to older versions of GitLab please do not open an issue but a feature request.
When submitting an issue please conform to the issue submission guidelines listed below.
Not all issues will be addressed and your issue is more likely to be addressed if you submit a merge request which partially or fully addresses the issue.
The [issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues) is only for obvious errors in the latest [stable or development release of GitLab](MAINTENANCE.md). If something is wrong but it is not a regression compared to older versions of GitLab please do not open an issue but a feature request. When submitting an issue please conform to the issue submission guidelines listed below. Not all issues will be addressed and your issue is more likely to be addressed if you submit a merge request which partially or fully addresses the issue.
Issues can be filed either at [gitlab.com](https://gitlab.com/gitlab-org/gitlab-ce/issues) or [github.com](https://github.com/gitlabhq/gitlabhq/issues).
Do not use the issue tracker for feature requests.
We have a specific [feature request forum](http://feedback.gitlab.com) for this purpose.
Please keep feature requests as small and simple as possible, complex ones might be edited to make them small and simple.
Do not use the issue tracker for feature requests. We have a specific [feature request forum](http://feedback.gitlab.com) for this purpose. Please keep feature requests as small and simple as possible, complex ones might be edited to make them small and simple.
Please send a merge request with a tested solution or a merge request with a failing test instead of opening an issue if you can. If you're unsure where to post, post to the [mailing list](https://groups.google.com/forum/#!forum/gitlabhq) or [Stack Overflow](http://stackoverflow.com/questions/tagged/gitlab) first. There are a lot of helpful GitLab users there who may be able to help you quickly. If your particular issue turns out to be a bug, it will find its way from there.
......@@ -42,16 +37,16 @@ Please send a merge request with a tested solution or a merge request with a fai
**[Search the issues](https://gitlab.com/gitlab-org/gitlab-ce/issues)** for similar entries before submitting your own, there's a good chance somebody else had the same issue. Show your support with `:+1:` and/or join the discussion. Please submit issues in the following format (as the first post):
1. **Summary:** Summarize your issue in one sentence (what goes wrong, what did you expect to happen)
2. **Steps to reproduce:** How can we reproduce the issue, preferably on the [GitLab development virtual machine with vagrant](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/doc/development.md) (start your issue with: `vagrant destroy && vagrant up && vagrant ssh`)
3. **Expected behavior:** Describe your issue in detail
4. **Observed behavior**
5. **Relevant logs and/or screenshots:** Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
6. **Output of checks**
1. **Steps to reproduce:** How can we reproduce the issue, preferably on the [GitLab development virtual machine with vagrant](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/doc/development.md) (start your issue with: `vagrant destroy && vagrant up && vagrant ssh`)
1. **Expected behavior:** Describe your issue in detail
1. **Observed behavior**
1. **Relevant logs and/or screenshots:** Please use code blocks (\`\`\`) to format console output, logs, and code as it's very hard to read otherwise.
1. **Output of checks**
* Results of GitLab [Application Check](doc/install/installation.md#check-application-status) (`sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production`); we will only investigate if the tests are passing
* Version of GitLab you are running; we will only investigate issues in the latest stable and development releases as per the [maintenance policy](MAINTENANCE.md)
* Add the last commit sha1 of the GitLab version you used to replicate the issue (obtainable from the help page)
* Describe your setup (use relevant parts from `sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production`)
7. **Possible fixes**: If you can, link to the line of code that might be responsible for the problem
1. **Possible fixes**: If you can, link to the line of code that might be responsible for the problem
## Merge requests
......@@ -87,10 +82,10 @@ For examples of feedback on merge requests please look at already [closed merge
**Please format your merge request description as follows:**
1. What does this MR do?
2. Are there points in the code the reviewer needs to double check?
3. Why was this MR needed?
4. What are the relevant issue numbers / [Feature requests](http://feedback.gitlab.com/)?
5. Screenshots (If appropiate)
1. Are there points in the code the reviewer needs to double check?
1. Why was this MR needed?
1. What are the relevant issue numbers / [Feature requests](http://feedback.gitlab.com/)?
1. Screenshots (If appropiate)
## Contribution acceptance criteria
......@@ -106,6 +101,7 @@ For examples of feedback on merge requests please look at already [closed merge
1. It conforms to the following style guides
## Style guides
1. [Ruby](https://github.com/bbatsov/ruby-style-guide)
1. [Rails](https://github.com/bbatsov/rails-style-guide)
1. [Formatting](https://github.com/thoughtbot/guides/tree/master/style#formatting)
......
# GitLab Maintenance Policy
GitLab is a fast moving and evolving project. We currently don't have the
resources to support many releases concurrently. We support exactly one stable
release at any given time.
GitLab is a fast moving and evolving project. We currently don't have the resources to support many releases concurrently. We support exactly one stable release at any given time.
GitLab follows the [Semantic Versioning](http://semver.org/) for its releases:
`(Major).(Minor).(Patch)`.
GitLab follows the [Semantic Versioning](http://semver.org/) for its releases: `(Major).(Minor).(Patch)`.
* **Major version**: Whenever there is something significant or any backwards
incompatible changes are introduced to the public API.
* **Minor version**: When new, backwards compatible functionality is introduced
to the public API or a minor feature is introduced, or when a set of smaller
features is rolled out.
* **Patch number**: When backwards compatible bug fixes are introduced that fix
incorrect behavior.
- **Major version**: Whenever there is something significant or any backwards incompatible changes are introduced to the public API.
- **Minor version**: When new, backwards compatible functionality is introduced to the public API or a minor feature is introduced, or when a set of smaller features is rolled out.
- **Patch number**: When backwards compatible bug fixes are introduced that fix incorrect behavior.
The current stable release will receive security patches and bug fixes
(eg. `5.0` -> `5.0.1`). Feature releases will mark the next supported stable
release where the minor version is increased numerically by increments of one
(eg. `5.0 -> 5.1`).
The current stable release will receive security patches and bug fixes (eg. `5.0` -> `5.0.1`). Feature releases will mark the next supported stable release where the minor version is increased numerically by increments of one (eg. `5.0 -> 5.1`).
We encourage everyone to run the latest stable release to ensure that you can easily upgrade to the most secure and feature rich GitLab experience. In order to make sure you can easily run the most recent stable release, we are working hard to keep the update process simple and reliable.
......
......@@ -24,9 +24,9 @@ Below we describe the contributing process to GitLab for two reasons. So that co
## Priorities of the issue team
1. Mentioning people (critical)
2. Workflow labels (normal)
3. Functional labels (minor)
4. Assigning issues (avoid if possible)
1. Workflow labels (normal)
1. Functional labels (minor)
1. Assigning issues (avoid if possible)
## Mentioning people
......@@ -36,11 +36,11 @@ The most important thing is making sure valid issues receive feedback from the d
Workflow labels are purposely not very detailed since that would be hard to keep updated as you would need to reevaluate them after every comment. We optionally use functional labels on demand when want to group related issues to get an overview (for example all issues related to RVM, to tackle them in one go) and to add details to the issue.
- _Awaiting feedback_: Feedback pending from the reporter
- _Awaiting confirmation of fix_: The issue should already be solved in **master** (generally you can avoid this workflow item and just close the issue right away)
- _Attached MR_: There is a MR attached and the discussion should happen there
- We need to let issues stay in sync with the MR's. We can do this with a "Closing #XXXX" or "Fixes #XXXX" comment in the MR. We can't close the issue when there is a merge request because sometimes a MR is not good and we just close the MR, then the issue must stay.
- _Awaiting developer action/feedback_: Issue needs to be fixed or clarified by a developer
- *Awaiting feedback*: Feedback pending from the reporter
- *Awaiting confirmation of fix*: The issue should already be solved in **master** (generally you can avoid this workflow item and just close the issue right away)
- *Attached MR*: There is a MR attached and the discussion should happen there
- We need to let issues stay in sync with the MR's. We can do this with a "Closing #XXXX" or "Fixes #XXXX" comment in the MR. We can't close the issue when there is a merge request because sometimes a MR is not good and we just close the MR, then the issue must stay.
- *Awaiting developer action/feedback*: Issue needs to be fixed or clarified by a developer
## Functional labels
......@@ -51,12 +51,13 @@ These labels describe what development specialities are involved such as: Postgr
If an issue is complex and needs the attention of a specific person, assignment is a good option but assigning issues might discourage other people from contributing to that issue. We need all the contributions we can get so this should never be discouraged. Also, an assigned person might not have time for a few weeks, so others should feel free to takeover.
## Label colors
- Light orange `#fef2c0`: workflow labels for issue team members (awaiting feedback, awaiting confirmation of fix)
- Bright orange `#eb6420`: workflow labels for core team members (attached MR, awaiting developer action/feedback)
- Light blue `#82C5FF`: functional labels
- Green labels `#009800`: issues that can generally be ignored. For example, issues given the following labels normally can be closed immediately:
- Feature request (see copy & paste response: [Feature requests](#feature-requests))
- Support (see copy & paste response: [Support requests and configuration questions](#support-requests-and-configuration-questions)
- Light orange `#fef2c0`: workflow labels for issue team members (awaiting feedback, awaiting confirmation of fix)
- Bright orange `#eb6420`: workflow labels for core team members (attached MR, awaiting developer action/feedback)
- Light blue `#82C5FF`: functional labels
- Green labels `#009800`: issues that can generally be ignored. For example, issues given the following labels normally can be closed immediately:
- Feature request (see copy & paste response: [Feature requests](#feature-requests))
- Support (see copy & paste response: [Support requests and configuration questions](#support-requests-and-configuration-questions)
## Be kind
......@@ -102,8 +103,4 @@ This merge request has been closed because a request for more information has no
### Accepting merge requests
Is there a request on [the feature request forum](http://feedback.gitlab.com/forums/176466-general) that is similar to this?
If so, can you make a comment with a link to it?
Please be aware that new functionality that is not marked [accepting merge/pull requests](http://feedback.gitlab.com/forums/176466-general/status/796455) on the forum might not make it into GitLab.
You might be asked to make changes and even after implementing them your feature might still be declined.
If you want to reduce the chance of this happening please have a discussion in the forum first.
Is there a request on [the feature request forum](http://feedback.gitlab.com/forums/176466-general) that is similar to this? If so, can you make a comment with a link to it? Please be aware that new functionality that is not marked [accepting merge/pull requests](http://feedback.gitlab.com/forums/176466-general/status/796455) on the forum might not make it into GitLab. You might be asked to make changes and even after implementing them your feature might still be declined. If you want to reduce the chance of this happening please have a discussion in the forum first.
## GitLab: self hosted Git management software
# GitLab
## Self hosted Git management software
![logo](https://gitlab.com/gitlab-org/gitlab-ce/raw/master/public/gitlab_logo.png)
![animated-screenshots](https://gist.github.com/fnkr/2f9badd56bfe0ed04ee7/raw/4f48806fbae97f556c2f78d8c2d299c04500cb0d/compiled.gif)
### Gitlab is open source software to collaborate on code
## Open source software to collaborate on code
* Manage git repositories with fine grained access controls that keep your code secure
* Perform code reviews and enhance collaboration with merge requests
* Each project can also have an issue tracker and a wiki
* Used by more than 100,000 organizations, GitLab is the most popular solution to manage git repositories on-premises
* Completely free and open source (MIT Expat license)
* Powered by Ruby on Rails
- Manage Git repositories with fine grained access controls that keep your code secure
- Perform code reviews and enhance collaboration with merge requests
- Each project can also have an issue tracker and a wiki
- Used by more than 100,000 organizations, GitLab is the most popular solution to manage Git repositories on-premises
- Completely free and open source (MIT Expat license)
- Powered by Ruby on Rails
### Canonical source
## Canonical source
* The source of GitLab Community Edition is [hosted on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ce/) and there are mirrors to make [contributing](CONTRIBUTING.md) as easy as possible.
- The source of GitLab Community Edition is [hosted on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ce/) and there are mirrors to make [contributing](CONTRIBUTING.md) as easy as possible.
### Code status
## Code status
* [![build status](https://ci.gitlab.org/projects/1/status.png?ref=master)](https://ci.gitlab.org/projects/1?ref=master) on ci.gitlab.org (master branch)
- [![build status](https://ci.gitlab.org/projects/1/status.png?ref=master)](https://ci.gitlab.org/projects/1?ref=master) on ci.gitlab.org (master branch)
* [![Code Climate](https://codeclimate.com/github/gitlabhq/gitlabhq.png)](https://codeclimate.com/github/gitlabhq/gitlabhq)
- [![Code Climate](https://codeclimate.com/github/gitlabhq/gitlabhq.png)](https://codeclimate.com/github/gitlabhq/gitlabhq)
* [![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlabhq/badge.png?branch=master)](https://coveralls.io/r/gitlabhq/gitlabhq)
- [![Coverage Status](https://coveralls.io/repos/gitlabhq/gitlabhq/badge.png?branch=master)](https://coveralls.io/r/gitlabhq/gitlabhq)
* [![PullReview stats](https://www.pullreview.com/gitlab/gitlab-org/gitlab-ce/badges/master.svg?)](https://www.pullreview.com/gitlab.gitlab.com/gitlab-org/gitlab-ce/reviews/master)
- [![PullReview stats](https://www.pullreview.com/gitlab/gitlab-org/gitlab-ce/badges/master.svg?)](https://www.pullreview.com/gitlab.gitlab.com/gitlab-org/gitlab-ce/reviews/master)
### Resources
* [www.gitlab.com](https://www.gitlab.com/) includes information about [subscriptions](https://www.gitlab.com/subscription/), [consultancy](https://www.gitlab.com/consultancy/), the [community](https://www.gitlab.com/community/) and the [hosted GitLab.com](https://www.gitlab.com/gitlab-com/).
- [www.gitlab.com](https://www.gitlab.com/) includes information about [subscriptions](https://www.gitlab.com/subscription/), [consultancy](https://www.gitlab.com/consultancy/), the [community](https://www.gitlab.com/community/) and the [hosted GitLab.com](https://www.gitlab.com/gitlab-com/).
* [GitLab Enterprise Edition](https://www.gitlab.com/gitlab-ee/) offers additional features aimed at larger organizations.
- [GitLab Enterprise Edition](https://www.gitlab.com/gitlab-ee/) offers additional features aimed at larger organizations.
* [GitLab CI](https://www.gitlab.com/gitlab-ci/) is a continuous integration (CI) server that is easy to integrate with GitLab.
- [GitLab CI](https://www.gitlab.com/gitlab-ci/) is a continuous integration (CI) server that is easy to integrate with GitLab.
* Unofficial third-party [iPhone app](http://gitlabcontrol.com/), [Android app](https://play.google.com/store/apps/details?id=com.bd.gitlab&hl=en), [command line client](https://github.com/drewblessing/gitlab-cli), [Ruby API wrapper](https://github.com/NARKOZ/gitlab) and [Chrome app](https://chrome.google.com/webstore/detail/chrome-gitlab-notifier/eageapgbnjicdjjihgclpclilenjbobi) for GitLab.
- Unofficial third-party [iPhone app](http://gitlabcontrol.com/), [Android app](https://play.google.com/store/apps/details?id=com.bd.gitlab&hl=en), [command line client](https://github.com/drewblessing/gitlab-cli), [Ruby API wrapper](https://github.com/NARKOZ/gitlab) and [Chrome app](https://chrome.google.com/webstore/detail/chrome-gitlab-notifier/eageapgbnjicdjjihgclpclilenjbobi) for GitLab.
### Requirements
## Requirements
* Ubuntu/Debian/CentOS/RHEL**
* ruby 2.0+
* git 1.7.10+
* redis 2.0+
* MySQL or PostgreSQL
- Ubuntu/Debian/CentOS/RHEL**
- ruby 2.0+
- git 1.7.10+
- redis 2.0+
- MySQL or PostgreSQL
** More details are in the [requirements doc](doc/install/requirements.md)
** More details are in the [requirements doc](doc/install/requirements.md).
### Installation
## Installation
Please see [the installation page on the GitLab website](https://www.gitlab.com/installation/).
......@@ -59,22 +61,21 @@ Since 2011 a minor or major version of GitLab is released on the 22nd of every m
For updating the the Omnibus installation please see the [update documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/update.md). For manual installations there is an [upgrader script](doc/update/upgrader.md) and there are [upgrade guides](doc/update).
### Run in production mode
## Run in production mode
The Installation guide contains instructions on how to download an init script and run it automatically on boot. You can also start the init script manually:
sudo service gitlab start
or by directly calling the script
or by directly calling the script:
sudo /etc/init.d/gitlab start
Please login with root / 5iveL!fe
Please login with `root` / `5iveL!fe`.
### Install a development environment
We recommend setting up your development environment with [the cookbook](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/README.md#installation).
If you do not use the cookbook you might need to copy the example development unicorn configuration file
We recommend setting up your development environment with [the cookbook](https://gitlab.com/gitlab-org/cookbook-gitlab/blob/master/README.md#installation). If you do not use the cookbook you might need to copy the example development unicorn configuration file
cp config/unicorn.rb.example.development config/unicorn.rb
......@@ -84,36 +85,35 @@ Start it with [Foreman](https://github.com/ddollar/foreman)
bundle exec foreman start -p 3000
or start each component separately
or start each component separately:
bundle exec rails s
bin/background_jobs start
And surf to [localhost:3000](http://localhost:3000/) and login with root / 5iveL!fe
And surf to [localhost:3000](http://localhost:3000/) and login with `root` / `5iveL!fe`.
### Run the tests
## Run the tests
* Run all tests
- Run all tests:
bundle exec rake test
* [RSpec](http://rspec.info/) unit and functional tests
All RSpec tests: bundle exec rake spec
- [RSpec](http://rspec.info/) unit and functional tests.
Single RSpec file: bundle exec rspec spec/controllers/commit_controller_spec.rb
All RSpec tests: `bundle exec rake spec`
* [Spinach](https://github.com/codegram/spinach) integration tests
Single RSpec file: `bundle exec rspec spec/controllers/commit_controller_spec.rb`
All Spinach tests: bundle exec rake spinach
- [Spinach](https://github.com/codegram/spinach) integration tests.
Single Spinach test: bundle exec spinach features/project/issues/milestones.feature
All Spinach tests: `bundle exec rake spinach`
Single Spinach test: `bundle exec spinach features/project/issues/milestones.feature`
### Documentation
## Documentation
All documentation can be found on [doc.gitlab.com/ce/](http://doc.gitlab.com/ce/).
### Getting help
## Getting help
Please see [Getting help for GitLab](https://www.gitlab.com/getting-help/) on our website for the many options to get help.
**User documentation**
# Documentation
+ [API](api/README.md) Explore how you can access GitLab via a simple and powerful API.
+ [Markdown](markdown/markdown.md) Learn what you can do with GitLab's advanced formatting system.
+ [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do.
+ [Public access](public_access/public_access.md) Learn how you can allow public and internal access to a project.
+ [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) Learn how to use Git and GitLab together.
## User documentation
**Administrator documentation**
- [API](api/README.md) Explore how you can access GitLab via a simple and powerful API.
- [Markdown](markdown/markdown.md) Learn what you can do with GitLab's advanced formatting system.
- [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do.
- [Public access](public_access/public_access.md) Learn how you can allow public and internal access to a project.
- [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) Learn how to use Git and GitLab together.
+ [Install](install/README.md) Requirements, directory structures and manual installation.
+ [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter.
+ [Raketasks](raketasks/README.md) Explore what GitLab has in store for you to make administration easier.
+ [System hooks](system_hooks/system_hooks.md) Let GitLab notify you when certain management tasks need to be carried out.
+ [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.
## Administrator documentation
**Contributor documentation**
- [Install](install/README.md) Requirements, directory structures and manual installation.
- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, LDAP and Twitter.
- [Raketasks](raketasks/README.md) Explore what GitLab has in store for you to make administration easier.
- [System hooks](system_hooks/system_hooks.md) Let GitLab notify you when certain management tasks need to be carried out.
- [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.
+ [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.
## 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.
......@@ -2,31 +2,31 @@
## 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)
+ [Milestones](milestones.md)
+ [Notes](notes.md) (comments)
+ [Deploy Keys](deploy_keys.md)
+ [System Hooks](system_hooks.md)
+ [Groups](groups.md)
- [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)
- [Milestones](milestones.md)
- [Notes](notes.md) (comments)
- [Deploy Keys](deploy_keys.md)
- [System Hooks](system_hooks.md)
- [Groups](groups.md)
## Clients
+ [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP
+ [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com)
+ [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby
+ [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python
+ [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java
+ [node-gitlab](https://github.com/moul/node-gitlab) - Node.js
+ [NGitLab](https://github.com/Scooletz/NGitLab) - .NET
- [php-gitlab-api](https://github.com/m4tthumphrey/php-gitlab-api) - PHP
- [Laravel API Wrapper for GitLab CE](https://github.com/adamgoose/gitlab) - PHP / [Laravel](http://laravel.com)
- [Ruby Wrapper](https://github.com/NARKOZ/gitlab) - Ruby
- [python-gitlab](https://github.com/Itxaka/python-gitlab) - Python
- [java-gitlab-api](https://github.com/timols/java-gitlab-api) - Java
- [node-gitlab](https://github.com/moul/node-gitlab) - Node.js
- [NGitLab](https://github.com/Scooletz/NGitLab) - .NET
## Introduction
......@@ -54,41 +54,35 @@ 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.
## 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.
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.
- `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
* `500 Server Error` - While handling the request something went wrong on the server side
- `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
- `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:
......@@ -112,16 +106,17 @@ 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"
```
......@@ -130,24 +125,21 @@ curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" --header "SUDO: 23" "http://
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
- `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.
[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 entites: id and iid.
The main difference between them is scope. Example:
When you work with API you may notice two similar fields in api entites: id and iid. The main difference between them is scope. Example:
Issue:
Issue
id: 46
iid: 5
id: 46
iid: 5
* id - is uniq across all Issues table. It used for any api calls.
* iid - is uniq only in scope of single project. When you browse issues or merge requests with Web UI - you see iid.
- id - is uniq across all Issues table. It used for any api calls.
- iid - is uniq only in scope of 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`
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`
......@@ -10,7 +10,7 @@ GET /projects/:id/repository/branches
Parameters:
+ `id` (required) - The ID of a project
- `id` (required) - The ID of a project
```json
[
......@@ -52,8 +52,8 @@ GET /projects/:id/repository/branches/:branch
Parameters:
+ `id` (required) - The ID of a project
+ `branch` (required) - The name of the branch
- `id` (required) - The ID of a project
- `branch` (required) - The name of the branch
```json
{
......@@ -82,7 +82,6 @@ Parameters:
}
```
## Protect repository branch
Protects a single project repository branch. This is an idempotent function, protecting an already
......@@ -94,8 +93,8 @@ PUT /projects/:id/repository/branches/:branch/protect
Parameters:
+ `id` (required) - The ID of a project
+ `branch` (required) - The name of the branch
- `id` (required) - The ID of a project
- `branch` (required) - The name of the branch
```json
{
......@@ -124,7 +123,6 @@ Parameters:
}
```
## Unprotect repository branch
Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
......@@ -136,8 +134,8 @@ PUT /projects/:id/repository/branches/:branch/unprotect
Parameters:
+ `id` (required) - The ID of a project
+ `branch` (required) - The name of the branch
- `id` (required) - The ID of a project
- `branch` (required) - The name of the branch
```json
{
......@@ -168,16 +166,15 @@ Parameters:
## 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
- `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
{
......
......@@ -10,8 +10,8 @@ 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
- `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
[
......@@ -44,8 +44,8 @@ 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
- `id` (required) - The ID of a project
- `sha` (required) - The commit hash or name of a repository branch or tag
```json
{
......@@ -63,7 +63,6 @@ Parameters:
}
```
## Get the diff of a commit
Get the diff of a commit in a project.
......@@ -74,8 +73,8 @@ 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
- `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
[
......@@ -91,5 +90,3 @@ Parameters:
}
]
```
# Deploy Keys
### List deploy keys
## List deploy keys
Get a list of a project's deploy keys.
......@@ -10,7 +10,7 @@ GET /projects/:id/keys
Parameters:
+ `id` (required) - The ID of the project
- `id` (required) - The ID of the project
```json
[
......@@ -29,8 +29,7 @@ Parameters:
]
```
### Single deploy key
## Single deploy key
Get a single key.
......@@ -40,8 +39,8 @@ GET /projects/:id/keys/:key_id
Parameters:
+ `id` (required) - The ID of the project
+ `key_id` (required) - The ID of the deploy key
- `id` (required) - The ID of the project
- `key_id` (required) - The ID of the deploy key
```json
{
......@@ -52,8 +51,7 @@ Parameters:
}
```
### Add deploy key
## 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
......@@ -64,12 +62,11 @@ POST /projects/:id/keys
Parameters:
+ `id` (required) - The ID of the project
+ `title` (required) - New deploy key's title
+ `key` (required) - New deploy key
- `id` (required) - The ID of the project
- `title` (required) - New deploy key's title
- `key` (required) - New deploy key
### Delete deploy key
## Delete deploy key
Delete a deploy key from a project
......@@ -79,6 +76,5 @@ DELETE /projects/:id/keys/:key_id
Parameters:
+ `id` (required) - The ID of the project
+ `key_id` (required) - The ID of the deploy key
- `id` (required) - The ID of the project
- `key_id` (required) - The ID of the deploy key
......@@ -73,7 +73,6 @@ GET /issues
]
```
## List project issues