Get the protected branch rule list¶

GET /api/v5/repos/{owner}/{repo}/protect_branches

Retrieves the protected branch rule list of the specified repository, returning each rule's branch name, update time, the users allowed to push and merge, and the push and merge permission toggles for each role (developers, committers, administrators, and so on).

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

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
`view`	query	string	No	Query view mode (such as `simple`)
`match`	query	string	No	Match keyword
`search`	query	string	No	Search keyword, at most 100 characters
`page`	query	integer	No	Page number; must be a positive integer
`per_page`	query	integer	No	Number of items per page; must be a positive integer

Response parameters¶

The response body is an array of protected branch rule objects. Each object describes one protected branch rule and its per-role push/merge permission toggles.

Field	Type	Always returned	Nullable	Description
`name`	string	Yes	No	Protected branch name
`updated_at`	string	Yes	Yes	Rule update time
`push_users`	object[]	Yes	Yes	Users allowed to push
`merge_users`	object[]	Yes	Yes	Users allowed to merge
`merged`	boolean	Yes	No	Whether it is merged
`developers_can_push`	boolean	Yes	No	Whether developers can push
`developers_can_merge`	boolean	Yes	No	Whether developers can merge
`committer_can_push`	boolean	Yes	No	Whether committers can push
`committer_can_merge`	boolean	Yes	No	Whether committers can merge
`master_can_push`	boolean	Yes	No	Whether repository administrators (Master) can push
`master_can_merge`	boolean	Yes	No	Whether repository administrators (Master) can merge
`maintainer_can_push`	boolean	Yes	No	Whether maintainers can push
`maintainer_can_merge`	boolean	Yes	No	Whether maintainers can merge
`owner_can_push`	boolean	Yes	No	Whether the repository owner can push
`owner_can_merge`	boolean	Yes	No	Whether the repository owner can merge
`no_one_can_push`	boolean	Yes	No	Whether pushing is forbidden for everyone
`no_one_can_merge`	boolean	Yes	No	Whether merging is forbidden for everyone

push_users object

Field	Type	Always returned	Nullable	Description
`push_users.state`	string	Yes	Yes	User state
`push_users.avatar_url`	string	Yes	Yes	URL of the user's avatar
`push_users.avatar_path`	string	Yes	Yes	Path of the user's avatar
`push_users.name`	string	Yes	Yes	User name
`push_users.email`	string	Yes	Yes	User email
`push_users.name_cn`	string	Yes	Yes	User's Chinese name
`push_users.web_url`	string	Yes	Yes	URL of the user's profile page
`push_users.nick_name`	string	Yes	Yes	User nickname
`push_users.tenant_name`	string	Yes	Yes	Tenant name
`push_users.is_codeowner`	boolean	Yes	Yes	Whether the user is a code owner
`push_users.user_id`	integer	Yes	Yes	User ID
`push_users.is_member`	boolean	Yes	Yes	Whether the user is a repository member
`push_users.enterprise_name`	string	Yes	Yes	Name of the enterprise the user belongs to

merge_users object

The elements of merge_users have the same structure as push_users, with the field prefix changed to merge_users..

Error response¶

This endpoint returns an error response when the caller is unauthenticated or unauthorized; error response field names follow what the backend actually returns.

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

403 Access forbidden

{
  "error": "forbidden",
  "message": "No permission to access the protected branch rules of this repository"
}

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`401`	Authentication required (Requires authentication)
`403`	Access forbidden (Forbidden)
`404`	Repository or resource does not exist (Not Found)

Request example¶

Parameter notes¶

The example is consistent with the rest of this page and can be used as-is: access_token is required; owner is the namespace address path of the repository and repo is the repository path.

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.

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/protect_branches?access_token=<token>' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browsers)
const owner = '<owner>';
const repo = '<repo>';
const token = '<token>';

const response = await fetch(
  `https://api.atomgit.com/api/v5/repos/${owner}/${repo}/protect_branches?access_token=${token}`,
  {
    headers: {
      "Accept": "application/json",
    },
  }
);

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

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

Python¶

import requests

owner = '<owner>'
repo = '<repo>'
token = '<token>'

resp = requests.get(
    f"https://api.atomgit.com/api/v5/repos/{owner}/{repo}/protect_branches",
    params={"access_token": token},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

[
  {
    "name": "main",
    "updated_at": "2024-09-18T10:15:48.471+08:00",
    "push_users": [],
    "merge_users": [],
    "merged": false,
    "developers_can_push": false,
    "developers_can_merge": false,
    "committer_can_push": false,
    "committer_can_merge": false,
    "master_can_push": true,
    "master_can_merge": true,
    "maintainer_can_push": true,
    "maintainer_can_merge": true,
    "owner_can_push": true,
    "owner_can_merge": true,
    "no_one_can_push": false,
    "no_one_can_merge": false
  }
]

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`403`	Access forbidden; no permission
`404`	Request path does not exist
`405`	Request method 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