# Create a tag object

From **GitHub v3 REST API**.

`POST /repos/{owner}/{repo}/git/tags`

Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then [create](https://docs.github.com/enterprise-server@3.0/rest/reference/git#create-a-reference) the `refs/tags/[tag]` reference. If you want to create a lightweight tag, you only have to [create](https://docs.github.com/enterprise-server@3.0/rest/reference/git#create-a-reference) the tag reference - this call would be unnecessary.

**Signature verification object**

The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:

| Name | Type | Description |
| ---- | ---- | ----------- |
| `verified` | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified. |
| `reason` | `string` | The reason for verified value. Possible values and their meanings are enumerated in table below. |
| `signature` | `string` | The signature that was extracted from the commit. |
| `payload` | `string` | The value that was signed. |

These are the possible values for `reason` in the `verification` object:

| Value | Description |
| ----- | ----------- |
| `expired_key` | The key that made the signature is expired. |
| `not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
| `gpgverify_error` | There was an error communicating with the signature verification service. |
| `gpgverify_unavailable` | The signature verification service is currently unavailable. |
| `unsigned` | The object does not include a signature. |
| `unknown_signature_type` | A non-PGP signature was found in the commit. |
| `no_user` | No user was associated with the `committer` email address in the commit. |
| `unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on her/his account. |
| `bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. |
| `unknown_key` | The key that made the signature has not been registered with any user's account. |
| `malformed_signature` | There was an error parsing the signature. |
| `invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
| `valid` | None of the above errors applied, so the signature is considered to be verified. |

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

## Request body

- Required: true
### `application/json`

- Type: `object`

```json
{
  "message": "initial version",
  "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
  "tag": "v0.0.1",
  "tagger": {
    "date": "2011-06-17T14:53:35-07:00",
    "email": "octocat@github.com",
    "name": "Monalisa Octocat"
  },
  "type": "commit"
}
```

```json
{"properties":{"message":{"description":"The tag message.","type":"string"},"object":{"description":"The SHA of the git object this is tagging.","type":"string"},"tag":{"description":"The tag's name. This is typically a version (e.g., \"v0.0.1\").","type":"string"},"tagger":{"description":"An object with information about the individual creating the tag.","properties":{"date":{"description":"When this object was tagged. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.","format":"date-time","type":"string"},"email":{"description":"The email of the author of the tag","type":"string"},"name":{"description":"The name of the author of the tag","type":"string"}},"required":["name","email"],"type":"object"},"type":{"description":"The type of the object we're tagging. Normally this is a `commit` but it can also be a `tree` or a `blob`.","enum":["commit","tree","blob"],"type":"string"}},"required":["tag","message","object","type"],"type":"object"}
```

## Responses

### `201`

Response

#### Headers

##### `Location`

- Type: `string`

- Example: `https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac`

### `application/json`

- Type: `object`

Metadata for a Git tag

```json
{
  "message": "initial version",
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "object": {
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "type": "commit",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "tag": "v0.0.1",
  "tagger": {
    "date": "2014-11-07T22:01:45Z",
    "email": "octocat@github.com",
    "name": "Monalisa Octocat"
  },
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "verification": {
    "payload": null,
    "reason": "unsigned",
    "signature": null,
    "verified": false
  }
}
```

```json
{"description":"Metadata for a Git tag","properties":{"message":{"description":"Message describing the purpose of the tag","example":"Initial public release","type":"string"},"node_id":{"example":"MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==","type":"string"},"object":{"properties":{"sha":{"type":"string"},"type":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["sha","type","url"],"type":"object"},"sha":{"example":"940bd336248efae0f9ee5bc7b2d5c985887b16ac","type":"string"},"tag":{"description":"Name of the tag","example":"v0.0.1","type":"string"},"tagger":{"properties":{"date":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}},"required":["date","email","name"],"type":"object"},"url":{"description":"URL for the tag","example":"https://api.github.com/repositories/42/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac","format":"uri","type":"string"},"verification":{"$ref":"#/components/schemas/verification"}},"required":["sha","url","node_id","tagger","object","tag","message"],"title":"Git Tag","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/tags \
  --header 'content-type: application/json' \
  --data '{
  "message": "initial version",
  "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
  "tag": "v0.0.1",
  "tagger": {
    "date": "2011-06-17T14:53:35-07:00",
    "email": "octocat@github.com",
    "name": "Monalisa Octocat"
  },
  "type": "commit"
}'
```