tags.md 6.09 KB
Newer Older
1
# Tags API
2 3 4

## List project repository tags

5 6 7
Get a list of repository tags from a project, sorted by name in reverse
alphabetical order. This endpoint can be accessed without authentication if the
repository is publicly accessible.
8 9 10 11 12 13 14

```
GET /projects/:id/repository/tags
```

Parameters:

haseeb's avatar
haseeb committed
15 16 17 18 19
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string| yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user|
| `order_by` | string | no | Return tags ordered by `name` or `updated` fields. Default is `updated` |
| `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc` |
20 21 22
| `search` | string | no | Return list of tags matching the search criteria |

> Support for `search` was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54401) in GitLab 11.8.
23 24 25 26 27

```json
[
  {
    "commit": {
28 29 30 31 32 33 34 35
      "id": "2695effb5807a22ff3d138d593fd856244e155e7",
      "short_id": "2695effb",
      "title": "Initial commit",
      "created_at": "2017-07-26T11:08:53.000+02:00",
      "parent_ids": [
        "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
      ],
      "message": "Initial commit",
36 37 38 39 40
      "author_name": "John Smith",
      "author_email": "john@example.com",
      "authored_date": "2012-05-28T04:42:42-07:00",
      "committer_name": "Jack Smith",
      "committer_email": "jack@example.com",
41
      "committed_date": "2012-05-28T04:42:42-07:00"
42
    },
43
    "release": {
44
      "tag_name": "1.0.0",
45 46
      "description": "Amazing release. Wow"
    },
47
    "name": "v1.0.0",
48
    "target": "2695effb5807a22ff3d138d593fd856244e155e7",
49 50 51 52 53
    "message": null
  }
]
```

54 55
## Get a single repository tag

56 57
Get a specific repository tag determined by its name. This endpoint can be
accessed without authentication if the repository is publicly accessible.
58 59 60 61 62 63 64 65 66

```
GET /projects/:id/repository/tags/:tag_name
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
67
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
68 69 70
| `tag_name` | string | yes | The name of the tag |

```bash
71
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0
72 73 74 75 76 77 78 79
```

Example Response:

```json
{
  "name": "v5.0.0",
  "message": null,
80
  "target": "60a8ff033665e1207714d6670fcd7b65304ec02f",
81 82
  "commit": {
    "id": "60a8ff033665e1207714d6670fcd7b65304ec02f",
83 84 85
    "short_id": "60a8ff03",
    "title": "Initial commit",
    "created_at": "2017-07-26T11:08:53.000+02:00",
86 87 88
    "parent_ids": [
      "f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"
    ],
89
    "message": "v5.0.0\n",
90 91
    "author_name": "Arthur Verschaeve",
    "author_email": "contact@arthurverschaeve.be",
92
    "authored_date": "2015-02-01T21:56:31.000+01:00",
93
    "committer_name": "Arthur Verschaeve",
94 95
    "committer_email": "contact@arthurverschaeve.be",
    "committed_date": "2015-02-01T21:56:31.000+01:00"
96 97 98 99 100
  },
  "release": null
}
```

101 102
## Create a new tag

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
103
Creates a new tag in the repository that points to the supplied ref.
104 105 106 107 108 109 110

```
POST /projects/:id/repository/tags
```

Parameters:

111
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
112 113 114
- `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.
115
- `release_description` (optional) - Add release notes to the git tag and store it in the GitLab database.
116 117 118 119

```json
{
  "commit": {
120 121 122 123 124 125 126 127
    "id": "2695effb5807a22ff3d138d593fd856244e155e7",
    "short_id": "2695effb",
    "title": "Initial commit",
    "created_at": "2017-07-26T11:08:53.000+02:00",
    "parent_ids": [
      "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
    ],
    "message": "Initial commit",
128 129 130 131 132
    "author_name": "John Smith",
    "author_email": "john@example.com",
    "authored_date": "2012-05-28T04:42:42-07:00",
    "committer_name": "Jack Smith",
    "committer_email": "jack@example.com",
133
    "committed_date": "2012-05-28T04:42:42-07:00"
134
  },
135
  "release": {
136
    "tag_name": "1.0.0",
137 138
    "description": "Amazing release. Wow"
  },
139
  "name": "v1.0.0",
140
  "target": "2695effb5807a22ff3d138d593fd856244e155e7",
141 142 143
  "message": null
}
```
144
The message will be `null` when creating a lightweight tag otherwise
145 146
it will contain the annotation.

147 148 149
The target will contain the tag objects ID when creating annotated tags,
otherwise it will contain the commit ID when creating lightweight tags.

150 151
In case of an error,
status code `405` with an explaining error message is returned.
152

Robert Schilling's avatar
Robert Schilling committed
153 154
## Delete a tag

155
Deletes a tag of a repository with given name.
Robert Schilling's avatar
Robert Schilling committed
156 157 158 159 160 161 162

```
DELETE /projects/:id/repository/tags/:tag_name
```

Parameters:

163
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
Robert Schilling's avatar
Robert Schilling committed
164 165
- `tag_name` (required) - The name of a tag

166
## Create a new release
167

168 169
Add release notes to the existing git tag. If there
already exists a release for the given tag, status code `409` is returned.
170 171

```
172
POST /projects/:id/repository/tags/:tag_name/release
173 174 175 176
```

Parameters:

177
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
178
- `tag_name` (required) - The name of a tag
179 180 181

Request body:

182 183
- `description` (required) - Release notes with markdown support

184 185 186 187 188 189 190 191
```json
{
  "description": "Amazing release. Wow"
}
```

Response:

192 193
```json
{
194
  "tag_name": "1.0.0",
195 196 197
  "description": "Amazing release. Wow"
}
```
198 199 200

## Update a release

201
Updates the release notes of a given release.
202 203 204 205 206 207 208

```
PUT /projects/:id/repository/tags/:tag_name/release
```

Parameters:

209
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
210
- `tag_name` (required) - The name of a tag
211 212 213

Request body:

214 215
- `description` (required) - Release notes with markdown support

216 217 218 219 220 221 222 223
```json
{
  "description": "Amazing release. Wow"
}
```

Response:

224 225 226 227 228
```json
{
  "tag_name": "1.0.0",
  "description": "Amazing release. Wow"
}
229
```