Skip to content

Agents

Description of the JSON object structure for registration information

Field Type Description
id String Model ID for agent registration
registrationUrl String URL for agent registration
registrationToken String Token for agent registration
Description of the JSON object structure for agent
Field Type Description
id String Agent ID
description String Agent description
connectedAt Boolean Agent connection date in ISO format
active String Active agent true or not false
name String Agent name
platform String Agent platform
architecture String Agent architecture
ipAddress String IP address for which the agent is registered
tags Object Object containing a list of tags. The agent will only work for the specified tags
ownerType String Agent owner type. Possible values: PROJECT - project level, COMPANY - company level, GLOBAL - instance level
ownerId Integer Agent owner ID
runUntagged Boolean Can this agent pick jobs without tags true or not false
locked Boolean Agent is locked true or not false. A locked agent cannot be attached to other projects
maxTimeoutInSec Integer Maximum job waiting time in seconds
protected Boolean Agent works only on protected branches true or not false

Description of the JSON object structure for job

Field Type Description
id String Job ID
localId Integer Local job ID
finishedAt Date Completion time
startedAt Date Start time
name String Job name
stageName String Stage name to which the job is attached
tag Boolean Is the job attached to a tag true or not false
ref String Specifies the ref for which the pipeline was run - branch or tag
artifactsExpireAt Date Date when the artifact will expire
status String Job status
pipelineLocalId Integer Local pipeline ID
erasedAt Depricated Deprecated parameter. Returns null by default

Methods for project agents

Method to get registration information for a project agent

GET /project/{ownerAlias}/{projectAlias}/runners/registration-info

The request returns the required information for registering an agent at the project level - URL and token.

You can register an agent at the project level only in self-hosted versions.

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "1",
    "registrationUrl": "http://localhost:8080/-/runner/registration",
    "registrationToken": "12889f05-aaaa-aaaa-aaaa-d8089fa5ad75"
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get the list of project agents

GET /project/{ownerAlias}/{projectAlias}/runners

The request returns a list of agents for the specified project, with the ability to configure pagination

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineRunnerModelList": [
            {
                "id": "c5c48d5f-aaaa-aaaa-aaaa-01aa12228f2d",
                "description": "Agent description",
                "connectedAt": "2024-06-17T09:06:37.966851",
                "active": true,
                "name": "The Lord of the Eagles",
                "platform": "Linux",
                "architecture": "amd64",
                "ipAddress": "127.0.0.1",
                "tags": [
                    "3.2.1",
                    "3.2.2",
                    "3.2.3"
                ],
                "ownerType": "PROJECT",
                "ownerId": 84,
                "runUntagged": false,
                "locked": false,
                "maxTimeoutInSec": 100,
                "protected": true
            }
        ]
    },
    "page": {
        "size": 10,
        "totalElements": 1,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get a project agent by UUID

GET /project/{ownerAlias}/{projectAlias}/runners/{runnerUuid}

The request returns information about the agent with the specified UUID registered to the project

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias
runnerUuid String Agent UUID

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "c5c48d5f-aaaa-aaaa-aaaa-01aa12228f2d",
    "description": "Agent description",
    "connectedAt": "2024-06-17T09:06:37.966851",
    "active": true,
    "name": "The Lord of the Eagles",
    "platform": "Linux",
    "architecture": "amd64",
    "ipAddress": "127.0.0.1",
    "tags": [
        "3.2.1",
        "3.2.2",
        "3.2.3"
    ],
    "ownerType": "PROJECT",
    "ownerId": 84,
    "runUntagged": false,
    "locked": false,
    "maxTimeoutInSec": 100,
    "protected": true
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get jobs of all project agents

GET /project/{ownerAlias}/{projectAlias}/runners/all/jobs?jobStatus

The request returns information about jobs completed by all agents of the project

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineJobModelList": [
            {
                "id": "c0f4ce7a-aaaa-aaaa-aaaa-f75d22415acc",
                "localId": 2,
                "finishedAt": "2024-06-21T11:38:15.229604Z",
                "startedAt": null,
                "name": "job 1",
                "stageName": "test",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 2
            },
            {
                "id": "9bd6e1c7-aaaa-aaaa-aaaa-384e89f5e770",
                "localId": 205,
                "finishedAt": "2024-06-21T11:38:35.449307Z",
                "startedAt": null,
                "name": "job 2",
                "stageName": "build",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 36
            }
        ]
    },
    "page": {
        "size": 2,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get jobs of a project agent by UUID

GET /project/{ownerAlias}/{projectAlias}/runners/{runnerUuid}/jobs?jobStatus

The request returns information about jobs completed by the agent with the specified UUID in the project

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias
runnerUuid String Agent UUID

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineJobModelList": [
            {
                "id": "c0f4ce7a-aaaa-aaaa-aaaa-f75d22415acc",
                "localId": 2,
                "finishedAt": "2024-06-21T11:38:15.229604Z",
                "startedAt": null,
                "name": "job 1",
                "stageName": "test",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 2
            },
            {
                "id": "9bd6e1c7-aaaa-aaaa-aaaa-384e89f5e770",
                "localId": 205,
                "finishedAt": "2024-06-21T11:38:35.449307Z",
                "startedAt": null,
                "name": "job 2",
                "stageName": "build",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 36
            }
        ]
    },
    "page": {
        "size": 2,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to shutdown a project agent

POST /project/{ownerAlias}/{projectAlias}/runners/{runnerUuid}/shutdown

The request disables the agent with the specified UUID registered to the project

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias
runnerUuid String Agent UUID

Responses

STATUS 200 - Agent disabled.

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to edit a project agent

POST /project/{ownerAlias}/{projectAlias}/runners/{runnerUuid}/edit

The request edits the agent with the specified UUID registered to the project and returns its information

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias
runnerUuid String Agent UUID

Request

Supported JSON format

POST request body structure:

Parameter Type Description
name String Agent name
description String Agent description
isActive Boolean Active agent true or not false
maxTimeoutInSec Integer Maximum job waiting time in seconds
tags Object Object containing a list of tags. The agent will only work for the specified tags
runUntagged Boolean Can this agent pick jobs without tags true or not false
isLocked Boolean Agent is locked true or not false. A locked agent cannot be attached to other projects
isProtected Boolean Agent works only on protected branches true or not false

Example JSON object

{
    "name": "The Lord of the Eagles",
    "description": "Agent description",
    "isActive": true,
    "maxTimeoutInSec": 100,
    "ipAddress": "127.0.0.1",
    "tags": ["3.2.1","3.2.2", "3.2.3"],
    "runUntagged": false,
    "isLocked": false,
    "isProtected": true
}

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "c5c48d5f-aaaa-aaaa-aaaa-01aa12228f2d",
    "description": "Agent description",
    "connectedAt": "2024-06-17T09:06:37.966851",
    "active": true,
    "name": "The Lord of the Eagles",
    "platform": "Linux",
    "architecture": "amd64",
    "ipAddress": "127.0.0.1",
    "tags": [
        "3.2.1",
        "3.2.2",
        "3.2.3"
    ],
    "ownerType": "PROJECT",
    "ownerId": 84,
    "runUntagged": false,
    "locked": false,
    "maxTimeoutInSec": 100,
    "protected": true
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to delete a project agent by UUID

DELETE /project/{ownerAlias}/{projectAlias}/runners/{runnerUuid}

The request deletes the agent with the specified UUID registered to the project

Path variable Type Description
ownerAlias String Project owner alias
projectAlias String Project alias
runnerUuid String Agent UUID

Responses

STATUS 200 - Agent deleted.

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Methods for company agents

Method to get registration information for a company agent

GET /company/{companyAlias}/runners/registration-info

The request returns the required information for registering an agent at the company level - URL and token.

Path variable Type Description
companyAlias String Company alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "1",
    "registrationUrl": "http://localhost:8080/-/runner/registration",
    "registrationToken": "12889f05-aaaa-aaaa-aaaa-d8089fa5ad75"
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get the list of company agents

GET /company/{companyAlias}/runners

The request returns a list of agents for the specified company, with the ability to configure pagination

Path variable Type Description
companyAlias String Company alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineRunnerModelList": [
            {
                "id": "74af2044-aaaa-aaaa-aaaa-47d0ef20639a",
                "description": "Agent description",
                "connectedAt": "2024-06-03T08:37:21.33104",
                "active": true,
                "name": "Gloin",
                "platform": "Linux",
                "architecture": "amd64",
                "ipAddress": "127.0.0.1",
                "tags": [
                    "4.4",
                    "4.5",
                    "4.6"
                ],
                "ownerType": "COMPANY",
                "ownerId": 4,
                "runUntagged": false,
                "locked": false,
                "maxTimeoutInSec": 100,
                "protected": true
            }
        ]
    },
    "page": {
        "size": 10,
        "totalElements": 1,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get a company agent by UUID

GET /company/{companyAlias}/runners/{runnerUuid}

The request returns information about the agent with the specified UUID registered to the company

Path variable Type Description
companyAlias String Company alias
runnerUuid String Agent UUID

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "74af2044-aaaa-aaaa-aaaa-47d0ef20639a",
    "description": "Agent description",
    "connectedAt": "2024-06-03T08:37:21.33104",
    "active": true,
    "name": "Gloin",
    "platform": "Linux",
    "architecture": "amd64",
    "ipAddress": "127.0.0.1",
    "tags": [
        "4.4",
        "4.5",
        "4.6"
    ],
    "ownerType": "COMPANY",
    "ownerId": 4,
    "runUntagged": false,
    "locked": false,
    "maxTimeoutInSec": 100,
    "protected": true
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get jobs of all company agents

GET /company/{companyAlias}/runners/all/jobs?jobStatus

The request returns information about jobs completed by all agents of the company

Path variable Type Description
companyAlias String Company alias

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineJobModelList": [
            {
                "id": "c0f4ce7a-aaaa-aaaa-aaaa-f75d22415acc",
                "localId": 2,
                "finishedAt": "2024-06-21T11:38:15.229604Z",
                "startedAt": null,
                "name": "job 1",
                "stageName": "test",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 2
            },
            {
                "id": "9bd6e1c7-aaaa-aaaa-aaaa-384e89f5e770",
                "localId": 205,
                "finishedAt": "2024-06-21T11:38:35.449307Z",
                "startedAt": null,
                "name": "job 2",
                "stageName": "build",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 36
            }
        ]
    },
    "page": {
        "size": 2,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to get jobs of a company agent by UUID

GET /company/{companyAlias}/runners/{runnerUuid}/jobs?jobStatus

The request returns information about jobs completed by the agent with the specified UUID in the company

Path variable Type Description
companyAlias String Company alias
runnerUuid String Agent UUID

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "_embedded": {
        "restPipelineJobModelList": [
            {
                "id": "c0f4ce7a-aaaa-aaaa-aaaa-f75d22415acc",
                "localId": 2,
                "finishedAt": "2024-06-21T11:38:15.229604Z",
                "startedAt": null,
                "name": "job 1",
                "stageName": "test",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 2
            },
            {
                "id": "9bd6e1c7-aaaa-aaaa-aaaa-384e89f5e770",
                "localId": 205,
                "finishedAt": "2024-06-21T11:38:35.449307Z",
                "startedAt": null,
                "name": "job 2",
                "stageName": "build",
                "tag": false,
                "ref": "master",
                "erasedAt": null,
                "artifactsExpireAt": null,
                "status": "SUCCESS",
                "pipelineLocalId": 36
            }
        ]
    },
    "page": {
        "size": 2,
        "totalElements": 2,
        "totalPages": 1,
        "number": 0
    }
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to shutdown a company agent

POST /company/{companyAlias}/runners/{runnerUuid}/shutdown

The request disables the agent with the specified UUID registered to the company

Path variable Type Description
companyAlias String Company alias
runnerUuid String Agent UUID

Responses

STATUS 200 - Agent disabled.

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to edit a company agent

POST /company/{companyAlias}/runners/{runnerUuid}/edit

The request edits the agent with the specified UUID registered to the company and returns its information

Path variable Type Description
companyAlias String Company alias
runnerUuid String Agent UUID

Request

Supported JSON format

POST request body structure:

Parameter Type Description
name String Agent name
description String Agent description
isActive Boolean Active agent true or not false
maxTimeoutInSec Integer Maximum job waiting time in seconds
ipAddress String IP address for which the agent is registered
tags Object Object containing a list of tags. The agent will only work for the specified tags
runUntagged Boolean Can this agent pick jobs without tags true or not false
isLocked Boolean Agent is locked true or not false. A locked agent cannot be attached to other projects
isProtected Boolean Agent works only on protected branches true or not false

Example JSON object

{
    "name": "Gloin",
    "description": "Agent description",
    "isActive": true,
    "maxTimeoutInSec": 100,
    "ipAddress": "127.0.0.1",
    "tags": ["4.4","4.5", "4.6"],
    "runUntagged": false,
    "isLocked": false,
    "isProtected": true
}

Responses

STATUS 200 - example JSON:

Example response 
    
{
    "id": "74af2044-aaaa-aaaa-aaaa-47d0ef20639a",
    "description": "Agent description",
    "connectedAt": "2024-06-03T08:37:21.33104",
    "active": true,
    "name": "Gloin",
    "platform": "Linux",
    "architecture": "amd64",
    "ipAddress": "127.0.0.1",
    "tags": [
        "4.4",
        "4.5",
        "4.6"
    ],
    "ownerType": "COMPANY",
    "ownerId": 4,
    "runUntagged": false,
    "locked": false,
    "maxTimeoutInSec": 100,
    "protected": true
}

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Method to delete a company agent by UUID

DELETE /company/{companyAlias}/runners/{runnerUuid}

The request deletes the agent with the specified UUID registered to the company

Path variable Type Description
companyAlias String Company alias
runnerUuid String Agent UUID

Responses

STATUS 200 - Agent deleted.

STATUS 403 - No access rights.

STATUS 404 - Data not found.

Automated translation!

This page was translated using automatic translation tools. The text may contain inaccuracies.