Creating a tag is a bit complicated, but if you just follow the API docs, everything should be fine. Note that the docs APIs say :
Note that creating a tag object does not create the link that makes the tag in Git. If you want to create an annotated tag in Git, you must make this call to create the tag object, and then create the refs / tags / [tag] link. If you want to create an easy tag, you just need to create a link - this call will be superfluous.
So, before you continue creating the tag, you need to know what type of tag you want to create - annotated or lightweight . In principle, an annotated tag is the same as a lightweight tag, but also contains a tag message, information about the tag’s author, and the date and time the tag was created. A light tag is just a named pointer to a specific commit in your story.
So, what the API documents basically say: if you want to create an annotated tag, you have to make 2 API calls, and if you want to create an easy tag, you only need to make 1 call. So, I will give an example of creating an annotated tag with two API calls, and if you want to create an easy tag, just skip the first API call and go to the second.
To create an annotated tag, you must:
Step 1
Create a tag object using the tag API . The API docs are a bit unclear here how parameters should be passed. There is no example message that needs to be sent to the server. So, create a file called tag_object_req.json on your local drive and put the following JSON document in it:
{ "tag": "v0.0.1", "object": "c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b", "message": "creating a tag", "tagger": { "name": "Ivan Zuzak", "email": "izuzak@gmail.com", "date": "2012-06-17T14:53:35-07:00" }, "type": "commit" }
Obviously, you need to replace the information in the document to reflect your situation. The meaning of the parameters is described in the API docs here .
After you save the file, you can make an API call using curl to create a 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 cause curl to output all HTTP headers, the -X POST part means that an HTTP POST request should be made, -d @tag_object_req.json indicates which file will be used as the content (body) of the POST request, --header "Content-Type:application/json" indicates the type of request medium (JSON message), and -u izuzak indicates your username for authorization (and curl will ask for your password when the request is made).
The response you receive should be an HTTP 201 Created response, with a JSON message, structured as follows:
{ "sha": "e6d9fb6b9a13cab11923345e2400d5cf8df97267", "url": "https://api.github.com/repos/izuzak/test/git/tags/e6d9fb6b9a13cab11923345e2400d5cf8df97267", "tagger": { "name": "Ivan Zuzak", "email": "izuzak@gmail.com", "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 proceeding, pay attention to the sha attribute of the newly created object ( e6d9fb6b9a13cab11923345e2400d5cf8df97267 ), because you will use this value in the next step.
Step 2
Create a tag link using the link API . The API docs are much clearer about what the request should look like. So, first you need to create another file on disk called tag_ref_req.json and put this content inside:
{ "ref": "refs/tags/v0.0.1", "sha": "e6d9fb6b9a13cab11923345e2400d5cf8df97267" }
However, note that the sha value in this JSON depends on the type of tag being created. If you create an annotated tag, the sha value is the same value that you received in the previous step - the sha of the tag object ( e6d9fb6b9a13cab11923345e2400d5cf8df97267 ). However, if you create a lightweight tag, the sha value is the sha of the commit object that you put with the tag because you did not create the tag object. In my case, in step 1, you can see that the commit object that I am posting is c5f8759ffd808d4a57ea36c63960f3e2cc6fcc2b , and this will, of course, in your case, if you create an easy tag.
So, after creating this file and defining the step and tag name, you can make the API request in the same 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"
Please note that we are now making a https://api.github.com/repos/izuzak/test/git/refs request with the second file as content.
The response should again be an HTTP 201 Created response, and the body will be a JSON document that looks 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 go to your project on GitHub and go to the "Switch branches / tags" section and see your tag there.
Hope this helps!