Create a project protected tag¶

POST /api/v5/repos/{owner}/{repo}/protected_tags

This endpoint creates a project protected tag in the specified repository. It sets the tag name and the access level allowed to create it, and can also specify custom roles that have creation permission, so as to protect and control permissions for tag creation.

Access token support¶

AtomGit user access token (AtomGit user access tokens)

Anonymous access¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Namespace address to which the repository belongs (address path of the organization or user)
`repo`	path	string	Yes	Repository path (path)
`access_token`	query	string	Yes	User authorization code

Request Body:

The request body is a JSON object and must be sent in the request body with Content-Type: application/json.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "description": "Tag name",
      "type": "string"
    },
    "create_access_level": {
      "description": "Access level allowed to create. Enum: `0` (no one); `10` (Guest, Reporter, Developer, Maintainer, Administrator); `30` (Developer, Maintainer, Administrator); `40` (Maintainer, Administrator). Defaults to `40`",
      "type": "integer",
      "enum": [0, 10, 30, 40],
      "default": 40
    },
    "roles_can": {
      "description": "List of custom role IDs to grant creation permission to",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["name"]
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`name`	string	Yes	No	Tag name
`create_access_level`	integer	Yes	Yes	Access level allowed to create; may be `null`
`create_access_level_desc`	string	Yes	Yes	Text description of the access level; may be `null`

Error responses¶

Callers need to know the shape of an error response in order to write error handling.

400 Invalid parameter

{
  "message": "Tag name is empty"
}

401 Unauthenticated

{
  "message": "Unauthenticated or invalid credentials"
}

404 Tag not found

{
  "message": "'<tag_name>' tag not found"
}

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameter (Bad Request)
`401`	Authentication required (Requires authentication)
`403`	Access forbidden (Forbidden)
`404`	Resource not found (Not Found)

Request example¶

Parameter description¶

Replace <owner> with the namespace address to which the repository belongs (address path of the organization or user);
replace <repo> with the repository path (path);
replace <token> with your AtomGit user access token;
in the request body example, name is the tag name and create_access_level is the access level allowed to create.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/protected_tags?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "v1.0.0",
    "create_access_level": 30,
    "roles_can": ["custom_role_id"]
  }'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/protected_tags?access_token=<token>",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({
      name: "v1.0.0",
      create_access_level: 30,
      roles_can: ["custom_role_id"],
    }),
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/protected_tags",
    params={"access_token": "<token>"},
    headers={"Content-Type": "application/json", "Accept": "application/json"},
    json={"name": "v1.0.0", "create_access_level": 30, "roles_can": ["custom_role_id"]},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "name": "v1.0.0",
  "create_access_level": 30,
  "create_access_level_desc": "Developer, Maintainer, Administrator"
}

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`400`	Invalid parameter or the request could not be parsed
`404`	The request path does not exist, or the resource does not exist
`405`	The request method is not supported
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc