How to tag a Commit in API using curl command

Creating a tag is a bit complicated, but if you just follow the API docs you should be fine. Note that the API docs say:

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 the refs/tags/[tag] reference. If you want to create a lightweight tag, you simply have to create the reference - this call would be unnecessary.

So, before you continue with creating a tag, you should know what kind of tag you want to create -- annotated or lightweight. Basically, an annotated tag is the same as a lightweight, but it also contains a message of the tag, info about the author of the tag, and the date and time when the tag was created. A lightweight tag is just a named pointer to a specific commit in your history.

Ok, so, what the API docs basically say is: if you want to create an annotated tag - you will have to make 2 API calls, and if you want to create a lightweight tag - you will have to make just 1 call. So, I'll give an example of creating an annotated tag with the 2 API calls, and if you want to create a lightweight tag - just skip the first API call and go to the second.

To create an annotated tag, you have to:

Step 1

Create a tag object using the tags API. The API docs are a bit unclear here how the parameters should be passed. What's missing is an example of the message that you need to send to the server. So, create a file called tag_object_req.json on your local disk, and put the following JSON document in it:

{
  "tag": "v0.0.1",
  "object": "c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b",
  "message": "creating a tag",
  "tagger": {
    "name": "Ivan Zuzak",
    "email": "[email protected]",
    "date": "2012-06-17T14:53:35-07:00"
  },
  "type": "commit"
}

Obviously, you have to replace the information in the document to reflect your situation. The meaning of the parameters are described in the API docs here.

After you have saved the file, you can make an API call using curl to create the tag object:

curl -v -X POST -d @tag_object_req.json --header "Content-Type:application/json" -u izuzak "https://api.github.com/repos/izuzak/test/git/tags"

So, the -v part will force curl to output all HTTP headers, the -X POST part means that an HTTP POST request must be made, -d @tag_object_req.json specifies which file will be used as the content (body) of the POST request, --header "Content-Type:application/json" specifies the media type of the request (JSON message), and -u izuzak specifies your username for authorization (and curl will ask you for your password when you make the request).

The response you get should be a 201 Created HTTP response, with the JSON message structured as this:

{
  "sha": "e6d9fb6b9a13cab11923345e2400d5cf8df97267",
  "url": "https://api.github.com/repos/izuzak/test/git/tags/e6d9fb6b9a13cab11923345e2400d5cf8df97267",
  "tagger": {
    "name": "Ivan Zuzak",
    "email": "[email protected]",
    "date": "2012-06-17T21:53:35Z"
  },
  "object": {
    "sha": "c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b",
    "type": "commit",
    "url": "https://api.github.com/repos/izuzak/test/git/commits/c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b"
  },
  "tag": "v0.0.1",
  "message": "creating a tag"
}

Before continuing, notice the sha attribute of the object you just created (e6d9fb6b9a13cab11923345e2400d5cf8df97267) because you will use this value in the next step.

Step 2

Create a tag reference using the references API. The API docs are much clearer here about what the request should look like. So, you first have to create another file on the disk, named tag_ref_req.json, and put this content inside:

{
  "ref": "refs/tags/v0.0.1",
  "sha": "e6d9fb6b9a13cab11923345e2400d5cf8df97267"
}

However, notice that the value of the sha in this JSON depends on the type of tag you are creating. If you are creating an annotated tag, the value of the sha is the same value you got from the previous step - the sha of the tag object (e6d9fb6b9a13cab11923345e2400d5cf8df97267). However, if you are creating a lightweight tag, the value of the sha is the sha of the commit object you are tagging with the tag, because you have not created a tag object. In my case, you can see in step 1 that the commit object I am tagging is c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b, and this will be different in your case of course if you are creating a lightweight tag.

Ok, so after you have created this file and defined the sha and the name of the tag, you can make an API request in a similar way as in the previous step, using curl:

curl -v -X POST -d @tag_ref_req.json --header "Content-Type:application/json" -u izuzak "https://api.github.com/repos/izuzak/test/git/refs"

Notice that we are now making a request to https://api.github.com/repos/izuzak/test/git/refs with the second file as the content.

The response should again be a 201 Created HTTP response, and the body will be a JSON document looking like this:

{
  "ref": "refs/tags/v0.0.1",
  "url": "https://api.github.com/repos/izuzak/test/git/refs/tags/v0.0.1",
  "object": {
    "sha": "e6d9fb6b9a13cab11923345e2400d5cf8df97267",
    "type": "tag",
    "url": "https://api.github.com/repos/izuzak/test/git/tags/e6d9fb6b9a13cab11923345e2400d5cf8df97267"
  }
}

And now you can navigate to your project on GitHub and go to "Switch branches/tags" and see your tag there.

Hope this helps!