Skip to content

Groups

Description of JSON object structures

Structure describing a "Group"

Field Type Description
id String Unique group UUID
alias String Group alias
title String Group name
description String Group description
fullTraversalPath String Full group path, for example owner/group/subgroup
ownerAlias String Group owner alias
ownerAliasType String Group owner type: USER or GROUP
isPrivate Boolean Group privacy

Structure describing a "Merge request approval rule"

Field Type Description
uuid String Unique rule UUID
name String Rule name
branchType String Branch type
targetBranch String Target branch. Required when branchType = DEFAULT
minimalApprovals Integer Minimum number of approvals
allowedApproversUuid Array(String) UUIDs of users who can approve merge requests

Structure describing a "Branch type for an approval rule"

Value Description
ALL_BRANCHES All branches
ALL_PROTECTED_BRANCHES All protected branches
DEFAULT Default branch or targetBranch

Structure describing a "Merge request squash setting"

Value Description
REQUIRE Squash is required
ENCOURAGE Squash is recommended
ALLOW Squash is allowed
DO_NOT_ALLOW Squash is prohibited

Structure describing a "Merge method"

Value Description
MERGE_COMMIT Creating a merge commit
MERGE_COMMIT_WITH_SEMI_LINEAR_HISTORY Merge commit with semi-linear history
FAST_FORWARD_MERGE Fast-forward merge
REBASE Merge via rebase

Structure describing "Merge request message templates"

Field Type Description
mergeCommitMessage String Merge commit message template
squashCommitMessage String Squash commit message template
mergeRequestDescriptionTemplate String Merge request description template
canEditMergeCommitMessage Boolean Whether editing the merge commit message is allowed

Structure describing "Merge request approval settings"

Field Type Description
canOverrideApprovals Boolean Allow overriding approval settings at the project level
preventAuthorApproving Boolean Prevent the request author from approving it
preventCommitterApproving Boolean Prevent the committer from approving the request
removeApprovalsOnPush Boolean Reset approvals on a new push
checkCiCdStatus Boolean Consider CI/CD status when merging
mergeRequestPipelineStatusCheckEnabled Boolean Check merge request pipeline status
branchPipelineStatusCheckEnabled Boolean Check branch pipeline status
mergeResultPipelineStatusCheckEnabled Boolean Check merge result pipeline status
editMergedMergeRequest Boolean Allow editing a merged merge request
enableRemoveSourceBranchByDefault Boolean Delete the source branch by default
removeApprovalsOnChangingTargetBranch Boolean Reset approvals when the target branch changes

Structure describing a "CI/CD variable"

Field Type Description
id String Unique variable UUID
key String Variable name
value String Variable value
mask Boolean Whether to mask the variable value in logs
variableType String Variable type: VARIABLE_TYPE or FILE_TYPE
environmentScope String Environment to which the variable applies

Structure describing "Pipeline lifetime settings"

Field Type Description
lifetime Integer Pipeline lifetime. Value must be > 0
enabled Boolean Whether the lifetime limit is enabled

Structure describing a "Group runner"

Field Type Description
id String Unique runner UUID
name String Runner name
description String Runner description
tags Array(String) Runner tags
ownerType String Runner owner type, GROUP for a group

Structure describing a "Branch protection rule"

Field Type Description
id String Unique rule UUID
branchTemplate String Pattern for the branch name to which protection applies
allowedToPush String Access level for editing files in the branch
allowedToMerge String Access level for merging into the branch
allowForcePush Boolean Whether push --force is allowed
codeOwnerApprovalRequired Boolean Whether code owner approval is required
autoMergeByDefault Boolean Enable auto-merge by default
priority Integer Rule priority

Structure describing an "Access level"

Value Description
NO_ONE No one
ADMINS Administrators
DEVELOPER Developers and above

Structure describing a "Tag protection rule"

Field Type Description
uuid String Unique rule UUID
tagTemplate String Pattern for the tag name to which protection applies
allowToCreate String Access level for creating tags

Structure describing a "Group member role"

Value Description
GUEST Guest
REPORTER Reporter
DEVELOPER Developer
ADMIN Administrator

Group methods

Learn about group functionality here

Get a list of all groups

GET /group

The request returns a list of all groups accessible to the current user. You can configure the number of items displayed per page

Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example title,asc

Responses

STATUS 200 - Group list was returned successfully.

STATUS 403 - Access denied.

Get a list of all my groups

GET /group/my

The request returns a list of groups owned by the current user. You can configure the number of items displayed per page

Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page

Responses

STATUS 200 - Group list was returned successfully.

STATUS 403 - Access denied.

Get a list of all groups the user belongs to

GET /group/shared

The request returns a list of groups in which the current user is a member. You can configure the number of items displayed per page

Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page

Responses

STATUS 200 - Group list was returned successfully.

STATUS 403 - Access denied.

Create a group

POST /group

The request creates and returns a group or subgroup

To create a subgroup, specify the full parent group path in ownerAlias and set ownerAliasType to GROUP

Request

Supported JSON format

POST request body structure:

Parameter Type Description
ownerAlias String Owner alias: username if ownerAliasType = USER, or full group path if GROUP (required parameter)
ownerAliasType String Owner type: USER or GROUP (required parameter)
alias String Group alias (required parameter)
title String Group name (required parameter)
description String Group description
isPrivate Boolean Group privacy. Defaults to true

JSON object example

{
    "ownerAlias": "USER",
    "ownerAliasType": "USER",
    "alias": "g-new",
    "title": "Новая группа",
    "description": "",
    "isPrivate": true
}

Responses

STATUS 200 - The group was created and returned successfully. The fullTraversalPath field contains the full path of the created group.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a group by its full path

GET /group/{groupPath}/-/overview

The request returns a group by its full path

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Group was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Transfer a group

POST /group/transfer

The request transfers a group to another owner. The new full group path is returned in fullTraversalPath

Request

Supported JSON format

POST request body structure:

Parameter Type Description
ownerAlias String Username or full path of the group to which the group is transferred (required parameter)
groupAlias String Full path of the transferred group (required parameter)

JSON object example

{
    "ownerAlias": "USER",
    "groupAlias": "owner/group/subgroup"
}

Responses

STATUS 200 - The group was transferred successfully. The fullTraversalPath field contains the new full group path.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Group import settings methods

The methods in this section are available only for the root group.

Get group import settings

GET /group/{groupPath}/-/setting/import

The request returns group import settings

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Group import settings were returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit group import settings

POST /group/{groupPath}/-/setting/import

The request changes group import settings

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
allowImportBranchProtection Boolean Allow importing branch protection rules
allowImportEnvironmentProtection Boolean Allow importing environment protection rules
allowImportTagProtection Boolean Allow importing tag protection rules
allowImportMrApprovalConfigAndRules Boolean Allow importing merge request approval settings and rules
allowImportPipelineLifetimeSetting Boolean Allow importing pipeline lifetime settings

All request parameters are optional.

JSON object example

{
    "allowImportBranchProtection": true
}

Responses

STATUS 200 - Group import settings were updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Merge request methods

The methods in this section are available only for the root group.

Create a merge request approval rule

POST /group/{groupPath}/-/merge-request/approval/rule/create

The request creates and returns a merge request approval rule

Only a group member can be an approver.

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
name String Rule name (required parameter)
branchType String Branch type (required parameter)
targetBranch String Target branch. Required when branchType = DEFAULT
minimalApprovals Integer Minimum number of approvals (required parameter)
allowedApproversUuid Array(String) UUIDs of users who can approve the request (required parameter)

JSON object example

{
    "name": "rule-1",
    "branchType": "ALL_BRANCHES",
    "minimalApprovals": 1,
    "allowedApproversUuid": [
        "8473a25a-aaaa-aaaa-aaaa-3e5c9e0a4b51"
    ]
}

Responses

STATUS 200 - Approval rule was created and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of approval rules

GET /group/{groupPath}/-/merge-request/approval/rule

The request returns a list of merge request approval rules. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example name,asc

Responses

STATUS 200 - Approval rule list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get an approval rule by UUID

GET /group/{groupPath}/-/merge-request/approval/rule/{approvalRuleUuid}

The request returns an approval rule by its UUID

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
approvalRuleUuid String Approval rule UUID

Responses

STATUS 200 - Approval rule was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit an approval rule

PATCH /group/{groupPath}/-/merge-request/approval/rule/edit

The request modifies and returns a merge request approval rule by its UUID

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
uuid String Rule UUID (required parameter)
name String New rule name
targetBranch String New target branch
branchType String New branch type
minimalApprovals Integer New minimum number of approvals
allowedApproversUuid Array(String) New list of UUIDs of users who can approve the request

All parameters except uuid are optional.

JSON object example

{
    "uuid": "5a4b4b4e-aaaa-aaaa-aaaa-2d0c7e0f3f11",
    "name": "rule-edited"
}

Responses

STATUS 200 - Approval rule was updated and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Delete a merge request approval rule

DELETE /group/{groupPath}/-/merge-request/approval/rule/{approvalRuleUuid}

The request deletes a merge request approval rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
approvalRuleUuid String Approval rule UUID

Responses

STATUS 200 - Approval rule was deleted successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get merge request squash settings

GET /group/{groupPath}/-/merge-request/merge-request-squash

The request returns the merge request squash setting

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Squash setting was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit merge request squash settings

PATCH /group/{groupPath}/-/merge-request/merge-request-squash/edit

The request changes the merge request squash setting

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
mergeRequestSquashSetting String Squash setting (required parameter)

JSON object example

{
    "mergeRequestSquashSetting": "REQUIRE"
}

Responses

STATUS 200 - Squash setting was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get merge method

GET /group/{groupPath}/-/merge-request/merge-request-method-type

The request returns the merge request merge method

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Merge method was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit merge method

PATCH /group/{groupPath}/-/merge-request/merge-request-method-type/edit

The request changes the merge request merge method

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
mergedRequestMethodType String Merge method (required parameter)

JSON object example

{
    "mergedRequestMethodType": "FAST_FORWARD_MERGE"
}

Responses

STATUS 200 - Merge method was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get merge request message templates

GET /group/{groupPath}/-/merge-request/merge-request-template

The request returns merge request message templates

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Message templates were returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit merge request message templates

PATCH /group/{groupPath}/-/merge-request/merge-request-template/edit

The request changes merge request message templates

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
mergeCommitMessage String Merge commit message template
squashCommitMessage String Squash commit message template
mergeRequestDescriptionTemplate String Merge request description template
canEditMergeCommitMessage Boolean Whether editing the merge commit message is allowed

All request parameters are optional. The templates support %{source_branch} and %{target_branch} substitutions.

JSON object example

{
    "mergeCommitMessage": "Merge '%{source_branch}' into '%{target_branch}'"
}

Responses

STATUS 200 - Message templates were updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get merge request approval settings

GET /group/{groupPath}/-/merge-request/approval/configuration

The request returns merge request approval settings

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Approval settings were returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit merge request approval settings

PATCH /group/{groupPath}/-/merge-request/approval/configuration/edit

The request changes merge request approval settings

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
canOverrideApprovals Boolean Allow overriding approval settings at the project level
preventAuthorApproving Boolean Prevent the request author from approving it
preventCommitterApproving Boolean Prevent the committer from approving the request
removeApprovalsOnPush Boolean Reset approvals on a new push
checkCiCdStatus Boolean Consider CI/CD status when merging
mergeRequestPipelineStatusCheckEnabled Boolean Check merge request pipeline status
branchPipelineStatusCheckEnabled Boolean Check branch pipeline status
mergeResultPipelineStatusCheckEnabled Boolean Check merge result pipeline status
editMergedMergeRequest Boolean Allow editing a merged merge request
enableRemoveSourceBranchByDefault Boolean Delete the source branch by default
removeApprovalsOnChangingTargetBranch Boolean Reset approvals when the target branch changes

All request parameters are optional.

JSON object example

{
    "checkCiCdStatus": true
}

Responses

STATUS 200 - Approval settings were updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Apply merge request settings to group projects

POST /group/{groupPath}/-/merge-request/apply-settings-to-projects

The request applies group merge request settings to group projects

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Merge request settings were applied to group projects successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

CI/CD methods

Create CI/CD variables

POST /group/{groupPath}/-/cicd/variable

The request creates and returns group CI/CD variables

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
ciCdVariablesToAdd Array(CiCdVariable) List of variables to create (required parameter)

Variable fields:

Parameter Type Description
key String Variable name (required parameter)
value String Variable value (required parameter)
mask Boolean Whether to mask the variable value in logs. Defaults to false
variableType String Variable type: VARIABLE_TYPE (default) or FILE_TYPE
environmentScope String Environment to which the variable applies

JSON object example

{
    "ciCdVariablesToAdd": [
        {
            "key": "VAR_1",
            "value": "1"
        }
    ]
}

Responses

STATUS 200 - CI/CD variables were created and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of CI/CD variables

GET /group/{groupPath}/-/cicd/variable

The request returns a list of group CI/CD variables. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example key,asc

Responses

STATUS 200 - CI/CD variable list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit CI/CD variables

PUT /group/{groupPath}/-/cicd/variable

The request changes group CI/CD variables

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PUT request body structure:

Parameter Type Description
ciCdVariablesToUpdate Array(CiCdVariable) List of variables to update (required parameter)

Variable fields:

Parameter Type Description
id String Variable UUID (required parameter)
key String Variable name (required parameter)
value String Variable value (required parameter)
mask Boolean Whether to mask the variable value in logs (required parameter)
variableType String Variable type: VARIABLE_TYPE or FILE_TYPE (required parameter)
environmentScope String Environment to which the variable applies

All fields except environmentScope are required.

JSON object example

{
    "ciCdVariablesToUpdate": [
        {
            "id": "5a4b4b4e-aaaa-aaaa-aaaa-2d0c7e0f3f11",
            "key": "VAR_1",
            "value": "2",
            "mask": false,
            "variableType": "VARIABLE_TYPE"
        }
    ]
}

Responses

STATUS 200 - CI/CD variables were updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Delete a CI/CD variable

DELETE /group/{groupPath}/-/cicd/variable/{variableUuid}

The request deletes a group CI/CD variable

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
variableUuid String CI/CD variable UUID

Responses

STATUS 200 - CI/CD variable was deleted successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get pipeline lifetime settings

GET /group/{groupPath}/-/cicd/pipeline-lifetime

The request returns group pipeline lifetime settings

This method is available only for the root group.

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Pipeline lifetime settings were returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit pipeline lifetime settings

PATCH /group/{groupPath}/-/cicd/pipeline-lifetime/edit

The request changes group pipeline lifetime settings

This method is available only for the root group.

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
lifetime Integer Pipeline lifetime. Value must be greater than 0
enabled Boolean Whether the lifetime limit is enabled

All request parameters are optional.

JSON object example

{
    "lifetime": 30
}

Responses

STATUS 200 - Pipeline lifetime settings were updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Apply pipeline lifetime settings to group projects

POST /group/{groupPath}/-/cicd/apply-settings-to-projects

The request applies group pipeline lifetime settings to group projects

This method is available only for the root group.

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Pipeline lifetime settings were applied to group projects successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Runner methods

A group runner cannot be created through the REST API. Register it using registrationUrl and registrationToken obtained from Get runner registration information.

Get runner registration information

GET /group/{groupPath}/-/runners/registration-info

The request returns the URL and token for group runner registration

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Runner registration information was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Reset the runner registration token

POST /group/{groupPath}/-/runners/reset-registration-token

The request resets the group runner registration token and returns a new value

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Runner registration token was reset successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of group runners

GET /group/{groupPath}/-/runners

The request returns a list of group runners. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page

Responses

STATUS 200 - Group runner list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a runner by UUID

GET /group/{groupPath}/-/runners/{runnerUuid}

The request returns a group runner by its UUID

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
runnerUuid String Runner UUID

Responses

STATUS 200 - Runner was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of runner jobs

GET /group/{groupPath}/-/runners/{runnerUuid}/jobs

The request returns a list of jobs for a group runner

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
runnerUuid String Runner UUID
Query parameter Type Description
jobStatus String Job status. The value must match the status name exactly, in uppercase (for example, SUCCESS); success is not accepted

Responses

STATUS 200 - Runner job list was returned successfully.

STATUS 400 - Invalid value of the parameter jobStatus.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of group runner jobs

GET /group/{groupPath}/-/runners/all/jobs

The request returns a list of jobs for all group runners

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
jobStatus String Job status. The value must match the status name exactly, in uppercase (for example, SUCCESS); success is not accepted

Responses

STATUS 200 - Group runner job list was returned successfully.

STATUS 400 - Invalid value of the parameter jobStatus.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit a runner

PATCH /group/{groupPath}/-/runners/{runnerUuid}/edit

The request modifies and returns a group runner

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
runnerUuid String Runner UUID

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
name String Runner name
description String Runner description
tags Array(String) Runner tags

All request parameters are optional.

JSON object example

{
    "name": "runner",
    "description": "Описание агента",
    "tags": [
        "tag"
    ]
}

Responses

STATUS 200 - Runner was updated and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Stop a runner

POST /group/{groupPath}/-/runners/{runnerUuid}/shutdown

The request stops a group runner

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
runnerUuid String Runner UUID

Responses

STATUS 200 - Runner shutdown command was sent successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Delete a runner

DELETE /group/{groupPath}/-/runners/{runnerUuid}

The request deletes a group runner

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
runnerUuid String Runner UUID

Responses

STATUS 200 - Runner was deleted successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Branch protection methods

The methods in this section are available only for the root group.

Create a branch protection rule

POST /group/{groupPath}/-/branch-protection

The request creates and returns a group branch protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
branchTemplate String Pattern for the branch name to which protection applies (required parameter)
allowedToPush String Access level for editing files in the branch (required parameter)
allowedToMerge String Access level for merging into the branch (required parameter)
allowForcePush Boolean Whether push --force is allowed
codeOwnerApprovalRequired Boolean Whether code owner approval is required
autoMergeByDefault Boolean Enable auto-merge by default
priority Integer Rule priority

JSON object example

{
    "branchTemplate": "main",
    "allowedToPush": "DEVELOPER",
    "allowedToMerge": "DEVELOPER"
}

Responses

STATUS 200 - Branch protection rule was created and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of branch protection rules

GET /group/{groupPath}/-/branch-protection

The request returns a list of group branch protection rules. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example priority,desc

Responses

STATUS 200 - Branch protection rule list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a branch protection rule by UUID

GET /group/{groupPath}/-/branch-protection/{branchProtectionUuid}

The request returns a branch protection rule by its UUID

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
branchProtectionUuid String Branch protection rule UUID

Responses

STATUS 200 - Branch protection rule was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit a branch protection rule

PUT /group/{groupPath}/-/branch-protection/{branchProtectionUuid}

The request modifies a group branch protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
branchProtectionUuid String Branch protection rule UUID

Request

Supported JSON format

PUT request body structure:

Parameter Type Description
allowedToPush String Access level for editing files in the branch
allowedToMerge String Access level for merging into the branch
allowForcePush Boolean Whether push --force is allowed
codeOwnerApprovalRequired Boolean Whether code owner approval is required
autoMergeByDefault Boolean Enable auto-merge by default
priority Integer Rule priority

All request parameters are optional. The branchTemplate field cannot be changed.

JSON object example

{
    "allowedToPush": "ADMINS"
}

Responses

STATUS 200 - Branch protection rule was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Apply branch protection rules to group projects

POST /group/{groupPath}/-/branch-protection/apply-settings-to-projects

The request applies group branch protection rules to group projects

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Branch protection rules were applied to group projects successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Delete a branch protection rule

DELETE /group/{groupPath}/-/branch-protection/{branchProtectionUuid}

The request deletes a group branch protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
branchProtectionUuid String Branch protection rule UUID

Responses

STATUS 200 - Branch protection rule was deleted successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Tag protection methods

The methods in this section are available only for the root group.

Create a tag protection rule

POST /group/{groupPath}/-/tag-protection/create

The request creates and returns a group tag protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
tagTemplate String Pattern for the tag name to which protection applies (required parameter)
allowToCreate String Access level for creating tags (required parameter)

JSON object example

{
    "tagTemplate": "v*",
    "allowToCreate": "DEVELOPER"
}

Responses

STATUS 200 - Tag protection rule was created and returned successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a list of tag protection rules

GET /group/{groupPath}/-/tag-protection

The request returns a list of group tag protection rules. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example tagTemplate,asc

Responses

STATUS 200 - Tag protection rule list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Get a tag protection rule by UUID

GET /group/{groupPath}/-/tag-protection/{tagProtectionUuid}

The request returns a tag protection rule by its UUID

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
tagProtectionUuid String Tag protection rule UUID

Responses

STATUS 200 - Tag protection rule was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Edit a tag protection rule

PUT /group/{groupPath}/-/tag-protection/{tagProtectionUuid}

The request modifies a group tag protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
tagProtectionUuid String Tag protection rule UUID

Request

Supported JSON format

PUT request body structure:

Parameter Type Description
uuid String Rule UUID. The value must match the UUID in the request path (required parameter)
allowToCreate String Access level for creating tags

JSON object example

{
    "uuid": "5a4b4b4e-aaaa-aaaa-aaaa-2d0c7e0f3f11",
    "allowToCreate": "NO_ONE"
}

Responses

STATUS 200 - Tag protection rule was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Apply tag protection rules to group projects

POST /group/{groupPath}/-/tag-protection/apply-settings-to-projects

The request applies group tag protection rules to group projects

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Tag protection rules were applied to group projects successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Delete a tag protection rule

DELETE /group/{groupPath}/-/tag-protection/{tagProtectionUuid}

The request deletes a group tag protection rule

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
tagProtectionUuid String Tag protection rule UUID

Responses

STATUS 200 - Tag protection rule was deleted successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

LDAP methods

Synchronize group members with LDAP

POST /group/{groupPath}/-/ldap/sync

The request starts synchronization of group members with LDAP

This endpoint is available only if LDAP group synchronization is enabled on the instance (gitflic.leader = true and togglz.features.GITFLIC_LDAP_GROUP_SYNC.enabled = true). Otherwise, it returns 404.

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Group member synchronization with LDAP started.

STATUS 403 - Access denied.

STATUS 404 - Requested data was not found or LDAP synchronization is disabled.

Group member methods

Get a list of group member roles

GET /group/{groupPath}/-/members/roles

The request returns a list of available group member roles

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Group member role list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Group user list

GET /group/{groupPath}/-/members/users

The request returns a list of group users. You can configure the number of items displayed per page

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
Query parameter Type Description
q String User search string
page Integer Page number, starting from 0
size Integer Number of items per page

Responses

STATUS 200 - Group user list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Add a user to a group

POST /group/{groupPath}/-/members/users

The request adds a user to a group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
userUuid String User UUID (required parameter)
role String Member role in the group (required parameter)

JSON object example

{
    "userUuid": "8473a25a-aaaa-aaaa-aaaa-3e5c9e0a4b51",
    "role": "DEVELOPER"
}

Responses

STATUS 200 - User was added to the group successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Change a user role in a group

PATCH /group/{groupPath}/-/members/users/role/edit

The request changes a user’s role in a group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
userUuid String User UUID (required parameter)
role String New member role in the group (required parameter)

JSON object example

{
    "userUuid": "8473a25a-aaaa-aaaa-aaaa-3e5c9e0a4b51",
    "role": "REPORTER"
}

Responses

STATUS 200 - User role in the group was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Remove a user from a group

DELETE /group/{groupPath}/-/members/users/{userUuid}

The request removes a user from a group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
userUuid String User UUID

Responses

STATUS 200 - The user was removed from the group successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

List of group member groups

GET /group/{groupPath}/-/members/groups

The request returns a list of groups that are members of the group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Responses

STATUS 200 - Member group list was returned successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Add a group to another group

POST /group/{groupPath}/-/members/groups

The request adds a group as a member of another group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

POST request body structure:

Parameter Type Description
groupUuid String UUID of the group being added (required parameter)
role String Member role in the group (required parameter)

JSON object example

{
    "groupUuid": "5a4b4b4e-aaaa-aaaa-aaaa-2d0c7e0f3f11",
    "role": "DEVELOPER"
}

Responses

STATUS 200 - Group was added to the group successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Change a group role in a group

PATCH /group/{groupPath}/-/members/groups/role/edit

The request changes the role of a member group within the group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup

Request

Supported JSON format

PATCH request body structure:

Parameter Type Description
groupUuid String Member group UUID (required parameter)
role String New member role in the group (required parameter)

JSON object example

{
    "groupUuid": "5a4b4b4e-aaaa-aaaa-aaaa-2d0c7e0f3f11",
    "role": "GUEST"
}

Responses

STATUS 200 - Group role within the group was updated successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Remove a group from a group

DELETE /group/{groupPath}/-/members/groups/{groupUuid}

The request removes a member group from the group

Request path variable Type Description
groupPath String Full group path, for example owner/group or owner/group/subgroup
groupUuid String Member group UUID

Responses

STATUS 200 - The group was removed from the group successfully.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Administrator methods

Methods in this section require an instance administrator token.

Get a list of groups as an administrator

GET /admin/group

The request returns a list of all groups in the instance. You can configure the number of items displayed per page

Query parameter Type Description
qName String Search string for group name
qOwner String Search string for group owner
isPrivate Boolean Group privacy filter
page Integer Page number, starting from 0
size Integer Number of items per page
sort String Sorting in the format field,direction, for example title,asc

Responses

STATUS 200 - Group list was returned successfully.

STATUS 403 - Access denied.

Add a user to a group as an administrator

POST /admin/group/{groupID}/member/invite

The request adds a user to a group on behalf of the instance administrator

Request path variable Type Description
groupID String Group UUID

Request

Supported JSON format

POST request body structure:

Parameter Type Description
userAlias String User alias (required parameter)
role String Member role in the group (required parameter)

JSON object example

{
    "userAlias": "USER",
    "role": "DEVELOPER"
}

Responses

STATUS 200 - User was added to the group successfully.

STATUS 400 - Invalid request parameters.

STATUS 403 - Access denied.

STATUS 404 - Requested data not found.

Automated translation!

This page has been automatically translated. The text may contain inaccuracies.