Project in GitLab can be either private, internal or public.
Project in GitLab can be either private, internal or public.
This is determined by the `visibility` field in the project.
This is determined by the `visibility` field in the project.
...
@@ -16,16 +16,15 @@ Values for the project visibility level are:
...
@@ -16,16 +16,15 @@ Values for the project visibility level are:
*`public`:
*`public`:
The project can be accessed without any authentication.
The project can be accessed without any authentication.
## List projects
## List all projects
Get a list of visible projects for authenticated user. When accessed without authentication, only public projects are returned.
Get a list of all visible projects across GitLab for the authenticated user.
When accessed without authentication, only public projects are returned.
```
```
GET /projects
GET /projects
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `archived` | boolean | no | Limit by archived status |
| `archived` | boolean | no | Limit by archived status |
...
@@ -193,16 +192,15 @@ Parameters:
...
@@ -193,16 +192,15 @@ Parameters:
]
]
```
```
### List a user's projects
## List user projects
Get a list of visible projects for the given user. When accessed without authentication, only public projects are returned.
Get a list of visible projects for the given user. When accessed without
authentication, only public projects are returned.
```
```
GET /users/:user_id/projects
GET /users/:user_id/projects
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `user_id` | string | yes | The ID or username of the user |
| `user_id` | string | yes | The ID or username of the user |
...
@@ -369,7 +367,7 @@ Parameters:
...
@@ -369,7 +367,7 @@ Parameters:
]
]
```
```
### Get single project
## Get single project
Get a specific project. This endpoint can be accessed without authentication if
Get a specific project. This endpoint can be accessed without authentication if
the project is publicly accessible.
the project is publicly accessible.
...
@@ -378,8 +376,6 @@ the project is publicly accessible.
...
@@ -378,8 +376,6 @@ the project is publicly accessible.
GET /projects/:id
GET /projects/:id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -484,17 +480,14 @@ Parameters:
...
@@ -484,17 +480,14 @@ Parameters:
Get the users list of a project.
Get the users list of a project.
```
Parameters:
GET /projects/:id/users
```
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `search` | string | no | Search for specific users |
| `search` | string | no | Search for specific users |
```
GET /projects/:id/users
```
```json
```json
[
[
{
{
...
@@ -516,11 +509,11 @@ GET /projects/:id/users
...
@@ -516,11 +509,11 @@ GET /projects/:id/users
]
]
```
```
### Get project events
## Get project events
Please refer to the [Events API documentation](events.md#list-a-projects-visible-events)
Please refer to the [Events API documentation](events.md#list-a-projects-visible-events).
### Create project
## Create project
Creates a new project owned by the authenticated user.
Creates a new project owned by the authenticated user.
...
@@ -528,8 +521,6 @@ Creates a new project owned by the authenticated user.
...
@@ -528,8 +521,6 @@ Creates a new project owned by the authenticated user.
POST /projects
POST /projects
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
...
@@ -558,7 +549,7 @@ Parameters:
...
@@ -558,7 +549,7 @@ Parameters:
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
### Create project for user
## Create project for user
Creates a new project owned by the specified user. Available only for admins.
Creates a new project owned by the specified user. Available only for admins.
...
@@ -566,8 +557,6 @@ Creates a new project owned by the specified user. Available only for admins.
...
@@ -566,8 +557,6 @@ Creates a new project owned by the specified user. Available only for admins.
POST /projects/user/:user_id
POST /projects/user/:user_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The user ID of the project owner |
| `user_id` | integer | yes | The user ID of the project owner |
...
@@ -596,7 +585,7 @@ Parameters:
...
@@ -596,7 +585,7 @@ Parameters:
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
### Edit project
## Edit project
Updates an existing project.
Updates an existing project.
...
@@ -604,8 +593,6 @@ Updates an existing project.
...
@@ -604,8 +593,6 @@ Updates an existing project.
PUT /projects/:id
PUT /projects/:id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -633,24 +620,24 @@ Parameters:
...
@@ -633,24 +620,24 @@ Parameters:
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
| `approvals_before_merge` | integer | no | How many approvers should approve merge request by default |
### Fork project
## Fork project
Forks a project into the user namespace of the authenticated user or the one provided.
Forks a project into the user namespace of the authenticated user or the one provided.
The forking operation for a project is asynchronous and is completed in a background job. The request will return immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project.
The forking operation for a project is asynchronous and is completed in a
background job. The request will return immediately. To determine whether the
fork of the project has completed, query the `import_status` for the new project.
```
```
POST /projects/:id/fork
POST /projects/:id/fork
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to |
| `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to |
### Star a project
## Star a project
Stars a given project. Returns status code `304` if the project is already starred.
Stars a given project. Returns status code `304` if the project is already starred.
...
@@ -658,8 +645,6 @@ Stars a given project. Returns status code `304` if the project is already starr
...
@@ -658,8 +645,6 @@ Stars a given project. Returns status code `304` if the project is already starr
POST /projects/:id/star
POST /projects/:id/star
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -727,7 +712,7 @@ Example response:
...
@@ -727,7 +712,7 @@ Example response:
}
}
```
```
### Unstar a project
## Unstar a project
Unstars a given project. Returns status code `304` if the project is not starred.
Unstars a given project. Returns status code `304` if the project is not starred.
...
@@ -802,7 +787,7 @@ Example response:
...
@@ -802,7 +787,7 @@ Example response:
}
}
```
```
### Archive a project
## Archive a project
Archives the project if the user is either admin or the project owner of this project. This action is
Archives the project if the user is either admin or the project owner of this project. This action is
idempotent, thus archiving an already archived project will not change the project.
idempotent, thus archiving an already archived project will not change the project.
...
@@ -895,7 +880,7 @@ Example response:
...
@@ -895,7 +880,7 @@ Example response:
}
}
```
```
### Unarchive a project
## Unarchive a project
Unarchives the project if the user is either admin or the project owner of this project. This action is
Unarchives the project if the user is either admin or the project owner of this project. This action is
idempotent, thus unarchiving an non-archived project will not change the project.
idempotent, thus unarchiving an non-archived project will not change the project.
...
@@ -988,7 +973,7 @@ Example response:
...
@@ -988,7 +973,7 @@ Example response:
}
}
```
```
### Remove project
## Remove project
Removes a project including all associated resources (issues, merge requests etc.)
Removes a project including all associated resources (issues, merge requests etc.)
...
@@ -996,15 +981,11 @@ Removes a project including all associated resources (issues, merge requests etc
...
@@ -996,15 +981,11 @@ Removes a project including all associated resources (issues, merge requests etc
DELETE /projects/:id
DELETE /projects/:id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
## Uploads
## Upload a file
### Upload a file
Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
...
@@ -1012,8 +993,6 @@ Uploads a file to the specified project to be used in an issue or merge request
...
@@ -1012,8 +993,6 @@ Uploads a file to the specified project to be used in an issue or merge request
POST /projects/:id/uploads
POST /projects/:id/uploads
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1038,15 +1017,11 @@ Returned object:
...
@@ -1038,15 +1017,11 @@ Returned object:
}
}
```
```
**Note**: The returned `url` is relative to the project path.
>**Note**: The returned `url` is relative to the project path.
In Markdown contexts, the link is automatically expanded when the format in
In Markdown contexts, the link is automatically expanded when the format in
`markdown` is used.
`markdown` is used.
## Project members
## Share project with group
Please consult the [Project Members](members.md) documentation.
### Share project with group
Allow to share project with group.
Allow to share project with group.
...
@@ -1054,8 +1029,6 @@ Allow to share project with group.
...
@@ -1054,8 +1029,6 @@ Allow to share project with group.
POST /projects/:id/share
POST /projects/:id/share
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1063,7 +1036,7 @@ Parameters:
...
@@ -1063,7 +1036,7 @@ Parameters:
| `group_access` | integer | yes | The permissions level to grant the group |
| `group_access` | integer | yes | The permissions level to grant the group |
| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 |
| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 |
### Delete a shared project link within a group
## Delete a shared project link within a group
Unshare the project from the group. Returns `204` and no content on success.
Unshare the project from the group. Returns `204` and no content on success.
...
@@ -1071,8 +1044,6 @@ Unshare the project from the group. Returns `204` and no content on success.
...
@@ -1071,8 +1044,6 @@ Unshare the project from the group. Returns `204` and no content on success.
DELETE /projects/:id/share/:group_id
DELETE /projects/:id/share/:group_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1095,8 +1066,6 @@ Get a list of project hooks.
...
@@ -1095,8 +1066,6 @@ Get a list of project hooks.
GET /projects/:id/hooks
GET /projects/:id/hooks
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1109,8 +1078,6 @@ Get a specific hook for a project.
...
@@ -1109,8 +1078,6 @@ Get a specific hook for a project.
GET /projects/:id/hooks/:hook_id
GET /projects/:id/hooks/:hook_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1142,8 +1109,6 @@ Adds a hook to a specified project.
...
@@ -1142,8 +1109,6 @@ Adds a hook to a specified project.
POST /projects/:id/hooks
POST /projects/:id/hooks
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1167,8 +1132,6 @@ Edits a hook for a specified project.
...
@@ -1167,8 +1132,6 @@ Edits a hook for a specified project.
PUT /projects/:id/hooks/:hook_id
PUT /projects/:id/hooks/:hook_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1194,8 +1157,6 @@ Either the hook is available or not.
...
@@ -1194,8 +1157,6 @@ Either the hook is available or not.
DELETE /projects/:id/hooks/:hook_id
DELETE /projects/:id/hooks/:hook_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1204,126 +1165,16 @@ Parameters:
...
@@ -1204,126 +1165,16 @@ Parameters:
Note the JSON response differs if the hook is available or not. If the project hook
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.
is available before it is returned in the JSON response or an empty response is returned.
## Branches
For more information please consult the [Branches](branches.md) documentation.
### List branches
Lists all branches of a project.
```
GET /projects/:id/repository/branches
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
```json
[
{
"name":"async",
"commit":{
"id":"a2b702edecdf41f07b42653eb1abe30ce98b9fca",
"parent_ids":[
"3f94fc7c85061973edc9906ae170cc269b07ca55"
],
"message":"give Caolan credit where it's due (up top)",
"author_name":"Jeremy Ashkenas",
"author_email":"jashkenas@example.com",
"authored_date":"2010-12-08T21:28:50+00:00",
"committer_name":"Jeremy Ashkenas",
"committer_email":"jashkenas@example.com",
"committed_date":"2010-12-08T21:28:50+00:00"
},
"protected":false,
"developers_can_push":false,
"developers_can_merge":false
},
{
"name":"gh-pages",
"commit":{
"id":"101c10a60019fe870d21868835f65c25d64968fc",
"parent_ids":[
"9c15d2e26945a665131af5d7b6d30a06ba338aaa"
],
"message":"Underscore.js 1.5.2",
"author_name":"Jeremy Ashkenas",
"author_email":"jashkenas@example.com",
"authored_date":"2013-09-07T12:58:21+00:00",
"committer_name":"Jeremy Ashkenas",
"committer_email":"jashkenas@example.com",
"committed_date":"2013-09-07T12:58:21+00:00"
},
"protected":false,
"developers_can_push":false,
"developers_can_merge":false
}
]
```
### Single branch
A specific branch of a project.
```
GET /projects/:id/repository/branches/:branch
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `branch` | string | yes | The name of the branch |
| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
### Protect single branch
Protects a single branch of a project.
```
PUT /projects/:id/repository/branches/:branch/protect
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `branch` | string | yes | The name of the branch |
### Unprotect single branch
Unprotects a single branch of a project.
```
PUT /projects/:id/repository/branches/:branch/unprotect
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `branch` | string | yes | The name of the branch |
## Admin fork relation
## Admin fork relation
Allows modification of the forked relationship between existing projects. Available only for admins.
Allows modification of the forked relationship between existing projects. Available only for admins.
### Create a forked from/to relation between existing projects.
### Create a forked from/to relation between existing projects
```
```
POST /projects/:id/fork/:forked_from_id
POST /projects/:id/fork/:forked_from_id
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1335,8 +1186,6 @@ Parameters:
...
@@ -1335,8 +1186,6 @@ Parameters:
DELETE /projects/:id/fork
DELETE /projects/:id/fork
```
```
Parameter:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
...
@@ -1351,8 +1200,6 @@ accessible.
...
@@ -1351,8 +1200,6 @@ accessible.
GET /projects
GET /projects
```
```
Parameters:
| Attribute | Type | Required | Description |
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| --------- | ---- | -------- | ----------- |
| `search` | string | yes | A string contained in the project name |
| `search` | string | yes | A string contained in the project name |