Actions are a Deckhouse Development Portal mechanism for running operations in external infrastructure systems and services. For example, actions can:
- create projects, variables, branches, tags, releases, and merge requests in GitLab;
- create resources in Kubernetes and retrieve them;
- create secrets in Deckhouse Stronghold and HashiCorp Vault, as well as clients in Keycloak;
- create projects in SonarQube, products and engagements in DefectDojo, projects in CodeScoring, and repositories, roles, users, and privileges in Nexus Repository;
- create topics and ACLs in Apache Kafka;
- perform helper actions for debugging and controlling process execution (for example, Debug and Wait).
An action can be linked to one or more resources. Once linked, it can be run for any entity of those resources.
Action configuration
Basic information
When creating or editing an action, specify the basic information:
| Field | Required | Description |
|---|---|---|
| Name | Yes | Arbitrary name of the action |
| Identifier | Yes | Action identifier. Generated automatically from the name |
| Resource | No | One or more resources for which the action will be available to run |
| Icon | No | Icon displayed on the action card |
| Owner | No | User account responsible for the action’s configuration and operation |
| Owner team | No | Team responsible for the action’s configuration and operation |
| Tags | No | Tags used to classify and search for actions |
| Description | No | Description in Markdown. Displayed when running the action or a process that contains it |
Request configuration
Action type
An action can be of the following types:
- “Built-in (BuiltIn)” — the action’s execution logic is defined within the portal. For built-in actions, you must select one of the preconfigured backends.
- “Webhook” — the action’s execution logic is fully configured by the user.
Restart parameters
If an action fails, the portal can automatically retry it. Configure retries in the “Restart parameters” section:
| Field | Description |
|---|---|
| Max retries | How many times to retry execution after a failure. 0 means a single attempt with no retries |
| Base delay (s) | Delay in seconds before the first retry. The pause doubles before each subsequent attempt (exponential backoff) |
Request body format
For webhook actions, you can choose the format used to send the request body:
- JSON (default) — the request body is sent in JSON format with the
Content-Type: application/jsonheader. - “Form URL Encoded” — the request body is sent in
application/x-www-form-urlencodedformat.
When “Form URL Encoded” is selected, the request body must contain only flat key-value pairs. Nested structures and arrays are not supported in this format.
If the request body is empty, the webhook sends the request without a body and without the Content-Type header. Use this for GET and DELETE requests.
If the external system returns an error response code, the response body is saved in the action response: JSON as an object, anything else in the raw_body field. The action error text has the form unexpected status code: <CODE>, response: <RESPONSE_BODY>; the response body is truncated to 8192 bytes.
Example:
token: {{ .credentials.token }}Verbose logging
For webhook actions, you can enable the “Verbose logging” option that logs all HTTP request and response details:
- request URL;
- HTTP method;
- HTTP headers (including tokens);
- request body;
- response status code;
- response HTTP headers;
- response body.
When this option is enabled, all this data is written to the action run log. When it is disabled, logging works in standard mode.
Enabling verbose logging may result in sensitive information (tokens, passwords, etc.) being written to the logs. Use this option with caution and only when needed for debugging.
Request body
Each action sends an HTTP request to a built-in backend or to a webhook backend URL. The request usually includes a request body (body) that describes what exactly will be sent. The request body is defined in YAML.
Parameter values from the user form can be substituted into the request body using Go template templates.
Example:
project_id: {{ .property.project_id }}With this request body, the expression {{ .property.project_id }} is replaced with the value of the project_id parameter that the user entered in the action’s launch form.
For built-in actions, the “Request body” parameter is part of the action configuration, and a configuration example is available.
User form
Parameters
The “User form” section specifies the parameters that the user can fill in when launching the action. Property types are described in the Properties section.
The following options are available for each parameter:
- “Editable” — allows the parameter value to be changed when launching the action. If this option is disabled, the value cannot be changed.
- “Required” — requires a value to be specified when launching the action.
- “Hidden” — the parameter is not displayed in the user form when launching the action.
Each parameter can have a default value that is pre-filled in the form when the action is launched.
Set a default value for non-editable and hidden parameters: the user cannot change them when launching the action.
The parameter description is shown when launching the action by clicking the “info” icon. Providing a description makes the parameter’s purpose easier to understand and reduces the risk of errors when launching the action.
Parameter values can use Go template template functions. For example, the expression {{ .entity.name }} in a parameter value means that when the action is launched, the name of the entity it is running for will be substituted.
Property conditions
Parameters can be automatically hidden or shown in the user form depending on the value of a Boolean-type parameter. This is configured in the “Property conditions” section, where you define rules for showing or hiding selected parameters.
Update
Templating contexts
All updates are performed only after the action completes successfully. The following templating contexts are available in Go templates:
| Context | Description | Example |
|---|---|---|
.property | Values from the user form | {{ .property.repo }} |
.response | Parsed action response (JSON) | {{ .response.id }} |
.entity | Parameters of the catalog entity for which the action is run | {{ .entity.slug }} |
.workflow | Workflow parameters | {{ .workflow.branch }} |
.process | Process parameters | {{ .process.releaseId }} |
.global | Global variables (variable set identifier, then key) | {{ .global.myGroup.apiUrl }} |
.team | Variables of the team selected at launch | {{ .team.token }} |
.store | Variables from the process store | {{ .store.myKey }} |
.context | Process launch context, for example data of the environment selected on the home page | {{ .context.environment.slug }} |
Entity parameter update
To enable property update, turn on the switch in the “Entity property updates” section header. The portal then applies the update rules and writes the values to the entity’s parameters.
| Field | Description |
|---|---|
| Source | Go template for the value |
| Entity parameter | Identifier of the entity parameter in the catalog |
For example, when the “Create GitLab project” action is run, the response (response) will contain the specification of the created project:
{
"id": "1",
"...": "..."
}If you need to immediately populate the entity’s repository_id parameter after creating a project in GitLab, specify the following update rule:
- Source:
{{ .response.id }}. - Entity parameter:
repository_id.
Entity creation
To enable entity creation, turn on the switch in the “Creating entities” section header. The portal then automatically creates new entities in the selected resources according to the specified rules. Rules are defined separately for each resource.
| Field | Description |
|---|---|
| Owner is the run initiator | The user who launched the action becomes the owner of created entities. If the initiator is unknown (a run by an automation or a webhook), the owner from the “Owner of created entities” field is used |
| Owner of created entities | Assigned as the owner of all entities the action creates in the catalog |
| Owning team of created entities | Assigned as the owner team of all entities the action creates in the catalog |
| Resource | Catalog resource in which the entity will be created |
| Source (identifier) | Go template for the identifier of the entity being created |
| Source (name) | Go template for the name of the entity being created |
| Additional rules | Mapping of a Go template value to an entity parameter |
The identifier and name are required for each rule group. If a resource already has an entity with the same identifier, creation is skipped.
For example, when the “Create GitLab project” action is run, the response may contain:
{
"id": "42",
"name": "my-project",
"...": "..."
}To create an entity in the “GitLab projects” resource after the action completes successfully, specify the following rules:
- Resource: “GitLab projects”.
- Source (identifier):
{{ .response.id }}. - Source (name):
{{ .response.name }}.
If needed, add additional rules to populate entity parameters, for example map {{ .response.path }} to the path parameter.
Entity deletion
To enable entity deletion, turn on the switch in the “Deleting entities” section header. The portal then automatically deletes entities in the selected resources according to the specified rules. Rules are defined separately for each resource.
| Field | Description |
|---|---|
| Resource | Catalog resource that contains the entity to delete |
| Source | Go template for the entity identifier (for example, {{ .response.id }}) |
If the resource has no entity with the resulting identifier, deletion is skipped.
For example, when the “Delete GitLab project” action is run, the response may contain:
{
"id": "42",
"...": "..."
}To delete the entity in the “GitLab projects” resource after the action completes successfully, specify the following rules:
- Resource: “GitLab projects”.
- Source:
{{ .response.id }}.
Entity relation creation
To enable relation creation, turn on the switch in the “Creating relations for the entity” section header. The portal then automatically creates new relations for the selected entity according to the specified rules. The set of rules is defined separately for each resource.
| Field | Description |
|---|---|
| Resource | Either of the two resources involved in the required resource relation: the list of relations in which the selected resource is specified as the parent or the child is loaded based on the selected resource. You can choose the resource of the entity for which the action is running, or the resource on the other side of the relation — the list will contain the same relation if both resources are part of it |
| Relation | The catalog resource relation: it defines the parent and child resources and entity roles when creating the relation. The selected relation determines which side the launch entity is on and which of the fields below specifies the identifier of the second entity from the action’s response |
| Parent entity identifier | Go template for the identifier of the parent entity in the catalog |
| Child entity identifier | Go template for the identifier of the child entity in the catalog |
Entity relation deletion
To enable relation deletion, turn on the switch in the “Deleting relations for the entity” section header. The portal then automatically deletes relations for the selected entity according to the specified rules. The set of rules is defined separately for each resource.
| Field | Description |
|---|---|
| Resource | Either of the two resources involved in the required resource relation: the list of relations in which the selected resource is specified as the parent or the child is loaded based on the selected resource. You can choose the resource of the entity for which the action is running, or the resource on the other side of the relation — the list will contain the same relation if both resources are part of it |
| Relation | The catalog resource relation: it defines the parent and child resources and entity roles when deleting the relation. The selected relation determines which side the launch entity is on and which of the fields below specifies the identifier of the second entity from the action’s response |
| Parent entity identifier | Go template for the identifier of the parent entity in the catalog |
| Child entity identifier | Go template for the identifier of the child entity in the catalog |
If no matching relation exists, deletion is skipped.
User credentials update
To enable user credentials update, turn on the switch in the “Updating user credentials” section header. The action then automatically updates the user’s credentials according to the specified rules.
| Field | Description |
|---|---|
| Source | Go template for the value |
| Credentials type | Type of credentials to be updated |
For example, when running an action that returns a new API key in its response:
{
"apiKey": "new-api-key-12345",
"...": "..."
}To update the credentials, specify the following rules:
- Source:
{{ .response.apiKey }}. - Credentials type: select the type of credentials to be updated.
By default, credentials are updated for the user who launched the action (the initiator). To update the credentials of a different user, enable the “Update credentials for specific user” option and select the user in the “User for credentials update” field.
Process store update
Rules from the “Updating process store” section only apply when the action is run as part of a process: after the action completes successfully, values are written to the run’s store according to the specified rules, in list order.
| Field | Description |
|---|---|
| Condition | An optional Go template; if empty, the rule always applies. Rendering result: true, false, 1, or 0 |
| Operation | Write string, Write JSON, Append string, Append JSON, Merge JSON (shallow), Delete |
| Target | Dot-path in the store without a leading dot, e.g. deploy.job_id or notification.items |
| Source | Go template for the value |
Other actions and process elements read this data via {{ .store.<path> }}. Inside a loop, the {{ .store._loop.* }} context is available in templates.
If there are no rules (the list is empty), nothing is written to the store when the action runs as part of a process.
For a detailed description of operations, rule examples, iterating over a collection, and viewing the store, see Process store.
Datasource synchronization
Datasource synchronization after an action brings the object that the action created or deleted in the external system into the catalog without waiting for the scheduled synchronization.
To enable synchronization, turn on the switch in the “Datasource synchronization” section header and select datasources in the “Datasources” field. Select the datasources that load the object created or deleted by the action into the catalog. If the switch is on, select at least one datasource.
Synchronization starts after the action completes successfully and the update rules are applied. Synchronization runs in the background: the action does not wait for it to finish and does not fail if synchronization fails. Deleted datasources are skipped.
Security
Execution conditions
The action will only run if the entity’s status matches one of the selected values in the status field. If no restrictions are set, this condition does not apply.
Masking action fields
For each action, you can enable masking of fields that may contain sensitive information.
If this option is enabled, the following will be hidden in the action’s run records:
- values of all filled-in parameters;
- request body (
body); - response (
response) generated as a result of execution.
Temporary response
For each action, you can enable the “Temporary response” option. It restricts access to the action’s execution result and hides it from other users.
If this option is enabled, after the action completes successfully, the response:
- is stored as temporary and displayed only to the user who launched the action;
- is removed from the regular response field so that it is not accessible to other users.
Other users will see only an encrypted placeholder instead of the response content.
The action’s initiator can delete the temporary response manually.
The temporary response is available only to the action’s initiator. Other users cannot view its contents and cannot delete it.
Approval
You can enable mandatory approval for an action and specify the number of approvers required. In this case, the action will not run until the specified number of approvals has been received from the designated users.
The current number of approvals and the list of users whose approval is expected are displayed in the action run table for the corresponding entity.
If approval is required from a specific user, they will receive a notification in the web interface.
Approval notifications
When approval is enabled, you can enable notifications and specify how they are sent. If sending to a URL is selected, specify the webhook address, optionally disable the server’s TLS certificate verification, and add additional HTTP request headers.
Authorization
Use external service
Select the external services for which the action can be run. If multiple external services are added, a specific service can be selected when launching the action.
URL and HTTP headers
Specify the address to which the request will be sent and the HTTP headers.
Headers support Go templates in the form {{ .credentials.<credentials type identifier> }} for substituting user credentials.
Select account for execution
By default, external infrastructure services are accessed using the credentials of the user who launched the action. To run the action on behalf of a specific account, enable the “Select account for execution” option and select the account in the “Account for execution” field.
For actions launched as automation events, specifying the account to run as is mandatory.
Credentials
For built-in actions, the portal predefines the set of required credentials. Their identifiers are loaded when the built-in backend is selected. For each identifier, you must select the type of credentials to be used.
For webhook actions, credentials can be accessed in the request body using the {{ .credentials.<credentials type identifier> }} construct.
HTTP method
For webhook actions, the HTTP method of the outgoing request is specified.
Action runs
Action run records
Each time an action is run, a record is created containing the initiator, execution status, and a detailed log. Run records for each entity are available on the entity’s card, on the “Action runs” tab. If the action requires approval, it is handled on the same tab.
A run record can be deleted, or the action can be re-run. Re-running creates a new record.
Run logging
For each action run, a record containing the full execution log is created in the database.
The actions.logging.enabled module parameter controls whether run logs are output to stdout: when set to true, logs are output; when set to false (default), they are not.
Set the parameter in the settings section of ModuleConfig development-platform or in the Deckhouse Platform web interface.
Records with the full run log are created in the database regardless of the value of actions.logging.enabled.
Action run statuses
For each action run, a record with a status is created. Possible statuses:
Created— the record has been created, but the action has not been run yet.Unapproved— the action is awaiting approval.Running— the action is running.Failed— the action finished with an error.Update failed— the action completed, but updating the entity’s parameters failed.Success— the action completed successfully.Retrying— the action finished with an error and is being retried.Warning— the action completed, but part of the operations failed. For example, the CreateGitlabProjectVariables action could not create some of the variables.Declined— the action was not run because the entity status does not match the execution conditions.Skipped— the action was not run because it was disabled in the process launch configuration.Canceled— the run was canceled by a user or because the process was stopped.