Update an action run
PATCH/v1/actions/runs/:run_id
This route allows you to update an action run's details. This can be used to update the run's status & label, and add links to it (e.g. external logs of the job runner).
A run that is waiting for approval can only be approved or declined (using the approval route), or cancelled by setting its status to FAILURE. Only the user who created the run or an approver of the action can cancel it. Any other status change on a waiting run returns a 422 error.
To learn more about action runs, check out the documentation.
Request
Parameters (JSON)
{
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"v1",
"v2"
]
},
"in": "query",
"name": "version",
"required": false,
"description": "Specifies the API version to use. Please use `v2` for the latest version of the API."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "run_id",
"required": true,
"description": "The identifier of the action run."
}
]
}Request body schema (JSON)
{
"title": "Body",
"body": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
]
},
"statusLabel": {
"type": "string",
"description": "A label to describe the status of the action run."
},
"link": {
"description": "One or more links to be displayed in the run's page in Port. For example, a link to the external logs of the job runner.",
"oneOf": [
{
"type": "string",
"title": "string"
},
{
"type": "array",
"title": "array",
"items": {
"type": "string"
}
}
]
},
"message": {
"type": "object",
"deprecated": true
},
"summary": {
"type": "string",
"description": "A summary of the action run, which will be displayed in the run's page in Port."
},
"externalRunId": {
"type": "string",
"description": "The run id of your backend, for example the id that GitHub gives the workflow. This can be used to identify the action run instead of the `run_id`."
}
},
"additionalProperties": false
}
}
}
}
}Responses
- 200
- 401
- 404
- 413
- 422
OK
Default Response
A resource with the provided identifier was not found
Request body is too large (limit is 1MiB)
The json provided does not match the route's schema, or the run is waiting for approval and the requested status change is not allowed (error run_waiting_for_approval)
Responses (JSON)
{
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"enum": [
true
]
},
"run": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"blueprint": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"icon": {
"type": [
"string",
"null"
]
},
"deleted": {
"type": "boolean"
}
},
"required": [
"identifier"
]
},
"entity": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"icon": {
"type": [
"string",
"null"
]
},
"deleted": {
"type": "boolean"
}
},
"required": [
"identifier"
]
},
"action": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"icon": {
"type": [
"string",
"null"
]
},
"deleted": {
"type": "boolean"
}
},
"required": [
"identifier"
]
},
"properties": {
"type": "object"
},
"rawProperties": {
"type": "object"
},
"endedAt": {
"type": "string",
"format": "date-time"
},
"source": {
"type": [
"string",
"object"
]
},
"requiredApproval": {
"type": [
"boolean",
"object"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ALL",
"ANY"
]
}
},
"required": [
"type"
]
},
"status": {
"type": "string"
},
"statusLabel": {
"type": [
"string",
"null"
]
},
"link": {
"type": [
"array",
"string"
],
"items": {
"type": "string"
}
},
"summary": {
"type": "string"
},
"approval": {
"type": [
"object",
"null"
],
"properties": {
"description": {
"type": "string"
},
"userId": {
"type": [
"string",
"null"
]
},
"impersonatedUserId": {
"type": [
"string",
"null"
]
},
"state": {
"type": "string"
}
}
},
"payload": {
"type": [
"object",
"null"
],
"properties": {
"type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"agent": {
"type": "boolean"
},
"synchronized": {
"type": "boolean"
},
"method": {
"type": "string"
},
"headers": {
"type": "object",
"properties": {
"RUN_ID": {
"type": "string"
}
}
},
"body": {
"type": "object",
"properties": {
"port_context": {
"type": "object",
"properties": {
"runId": {
"type": "string"
}
}
}
}
}
}
},
"response": {
"type": [
"string",
"array",
"object"
],
"items": {}
},
"pendingExecution": {
"type": "boolean"
},
"claimedUntil": {
"type": "string",
"format": "date-time"
},
"installationId": {
"type": "string"
},
"createdBy": {
"type": "string"
},
"impersonatedBy": {
"type": "string"
},
"impersonatedUserId": {
"type": "string"
},
"updatedBy": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"action",
"properties",
"requiredApproval",
"source",
"status"
]
}
},
"required": [
"ok"
],
"additionalProperties": false,
"description": "OK"
}
}
}
},
"401": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "A resource with the provided identifier was not found",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error",
"message"
],
"additionalProperties": false,
"description": "A resource with the provided identifier was not found"
}
}
}
},
"413": {
"description": "Request body is too large (limit is 1MiB)",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error"
],
"additionalProperties": false,
"description": "Request body is too large (limit is 1MiB)"
}
}
}
},
"422": {
"description": "The json provided does not match the route's schema, or the run is waiting for approval and the requested status change is not allowed (error `run_waiting_for_approval`)",
"content": {
"application/json": {
"schema": {
"properties": {
"ok": {
"const": false
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"ok",
"error",
"message"
],
"additionalProperties": false,
"description": "The json provided does not match the route's schema, or the run is waiting for approval and the requested status change is not allowed (error `run_waiting_for_approval`)"
}
}
}
}
}
}