Skip to main content

Setup backend


Port's self-service actions support a variety of backends that can be triggered when a user invokes an action.

Here is the basic backend model:



Executing a self-service action involves the following steps:

  1. The action is triggered in Port - the trigger can either be a user executing an action via the UI, or an automation triggering an action via Port's API.
  2. Port generates the event payload - the payload includes metadata about the invoked action and its inputs.
  3. The payload is sent to your backend - the backend can be a URL, a dedicated Kafka topic or one of your CI/CD workflows/pipelines.
  4. Your backend receives the payload and handles the request - depending on the action, your backend might open a PR, create a cloud resource, provision a new environment, or perform any other logic you would like.
  5. Your backend updates Port on the status of the execution - You can enrich the action run object in Port by adding logs, attaching links to other workflows or pipelines that help fullfil the request and add a final success/fail status once the action is complete.

Define the backend

The action's backend is defined under the Backend tab of the action creation form in Port's UI:



Depending on the backend you choose, you will need to provide different configuration parameters.
See the list of supported backends below for more information.

Supported backends

JSON structure

The action's backend is defined under the invocationMethod object:

{
"identifier": "unique_id",
"title": "Title",
"userInputs": {
"properties": {
"property1": {
"type": "string",
"title": "Property title",
"default": "default value"
}
}
},
"invocationMethod": {
"type": "WEBHOOK",
"url": "https://example.com"
},
"trigger": "CREATE",
"description": "Action description"
}

Invocation method structure fields

FieldTypeDescriptionExample values
typestringDefines the backend of the action.WEBHOOK, KAFKA, GITHUB or GITLAB
agentbooleanDefines whether to use Port Agent for execution or not.
Can only be used if type is set to WEBHOOK or GITLAB.
true or false
urlstringDefines the webhook URL to which Port will send the action via an HTTP POST request.
Can only be used if type is set to WEBHOOK.
https://example.com
orgstringThe GitHub organization name.
Can only be used if type is set to GITHUB.
port-labs
repostringThe GitHub repository name.
Can only be used if type is set to GITHUB.
port-docs
workflowstringDefines the GitHub workflow ID to run (You can also pass the workflow file name as a string).
Can only be used if type is set to GITHUB.
workflow.yml
omitPayloadbooleanA flag to control whether to add the port_payload JSON string to the GitHub/GitLab workflow trigger payload (default: false).
Can only be used if type is set to GITHUB or GITLAB.
false
omitUserInputsbooleanA flag to control whether to send the user inputs of the action as isolated parameters to the GitHub/GitLab workflow (default: false). When disabled, you can still get the user inputs from the port_payload (unless omitted too).
Can only be used if type is set to GITHUB or GITLAB.
false
reportWorkflowStatusbooleanA flag to control whether to automatically update the Port run object status (SUCCESS/FAILURE) at the end of the workflow (default: true).
Can be added only if type is set to GITHUB.
defaultRefstringThe default ref (branch/tag name) we want the action to use.
defaultRef can be overriden dynamically, by adding ref as user input.
Can only be used if type is set to GITLAB.
projectNamestringThe GitLab project name.
Can only be used if type is set to GITLAB.
port
groupNamestringThe GitLab group name.
Can only be used if type is set to GITLAB.
port-labs

Next step

Once the backend is set up, the action is ready to be used.
Optionally, you can configure permissions and/or manual approval for your actions to control who is allowed to execute them.