REST API Endpoints For Git Tags

In Git, tags are used to mark specific commits as important, typically signifying a release. Unlike branches, tags are immutable references, making them perfect for marking stable points in your repository’s history, such as version releases.

Why Use REST API for Git Tags?

Interacting with Git tags via REST APIs allows for easy integration with CI/CD pipelines, automated deployment processes, or custom tooling that requires reading or creating tags programmatically.

Understanding the REST API Endpoints for Git Tags

Here’s a look at the main REST API endpoints provided by popular platforms like GitHub, GitLab, and Bitbucket for working with tags.

1. Listing Tags

To fetch a list of all tags in a repository, you can use the following endpoint:

GitHub:

GET /repos/{owner}/{repo}/tags

Example:

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/username/repository/tags

This request returns a JSON array with information about each tag, including the tag name, commit SHA, and associated URLs.

GitLab:

GET /projects/{id}/repository/tags

Example:

curl --header "PRIVATE-TOKEN: YOUR_GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/your_project_id/repository/tags"

The response contains an array of tag details, such as tag names, message, and commit information.

Bitbucket:

GET /repositories/{workspace}/{repo_slug}/refs/tags

Example:

curl -u username:password \
https://api.bitbucket.org/2.0/repositories/workspace/repo_slug/refs/tags

The response includes metadata about each tag, including the commit hash, tagger details, and more.

2. Fetching a Specific Tag

To retrieve information about a specific tag by its name:

GitHub:

GET /repos/{owner}/{repo}/git/ref/tags/{tag_name}

Example:

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/username/repository/git/ref/tags/v1.0.0

GitLab:

GET /projects/{id}/repository/tags/{tag_name}

Example:

curl --header "PRIVATE-TOKEN: YOUR_GITLAB_TOKEN" \
"https://gitlab.com/api/v4/projects/your_project_id/repository/tags/v1.0.0"

This endpoint fetches details about a specific tag, including the commit SHA and release notes (if available).

3. Creating a New Tag

To create a new tag in your repository, you can make a POST request:

GitHub:

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

Example:

curl -X POST -H "Authorization: token YOUR_GITHUB_TOKEN" \
-d '{
    "tag": "v1.0.0",
    "message": "Release version 1.0.0",
    "object": "commit_sha",
    "type": "commit",
    "tagger": {
        "name": "Your Name",
        "email": "[email protected]",
        "date": "2024-08-22T14:00:00Z"
  }
}' https://api.github.com/repos/username/repository/git/tags

After creating the tag object, you need to create the reference:

POST /repos/{owner}/{repo}/git/refs

Example:

curl -X POST -H "Authorization: token YOUR_GITHUB_TOKEN" \
-d '{
    "ref": "refs/tags/v1.0.0",
    "sha": "commit_sha"
}' https://api.github.com/repos/username/repository/git/refs

GitLab:

POST /projects/{id}/repository/tags

Example:

curl --header "PRIVATE-TOKEN: YOUR_GITLAB_TOKEN" \
-X POST "https://gitlab.com/api/v4/projects/your_project_id/repository/tags" \
-d "tag_name=v1.0.0&ref=main&message=Release version 1.0.0"

Bitbucket:

POST /repositories/{workspace}/{repo_slug}/refs/tags

Example:

curl -X POST -u username:password \
-H "Content-Type: application/json" \
-d '{
    "name": "v1.0.0",
    "target": {
        "hash": "commit_sha"
  }
}' https://api.bitbucket.org/2.0/repositories/workspace/repo_slug/refs/tags

4. Deleting a Tag

To delete a tag programmatically:

GitHub:

DELETE /repos/{owner}/{repo}/git/refs/tags/{tag_name}

Example:

curl -X DELETE -H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/username/repository/git/refs/tags/v1.0.0

GitLab:

DELETE /projects/{id}/repository/tags/{tag_name}

Example:

curl --header "PRIVATE-TOKEN: YOUR_GITLAB_TOKEN" \
-X DELETE "https://gitlab.com/api/v4/projects/your_project_id/repository/tags/v1.0.0"

Bitbucket:

DELETE /repositories/{workspace}/{repo_slug}/refs/tags/{tag_name}

Example:

curl -X DELETE -u username:password \
https://api.bitbucket.org/2.0/repositories/workspace/repo_slug/refs/tags/v1.0.0

Best Practices for Working with Git Tags via REST API

• Use Semantic Versioning: Consistently using semantic versioning (e.g., v1.0.0) makes it easier to manage and automate version control workflows.
• Secure API Requests: Always use tokens (like GitHub's personal access tokens) for secure API requests. Never expose sensitive data in your scripts.
• Automate Tagging in CI/CD: Integrate tag creation and management in your CI/CD pipelines to automate versioning during releases.