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:
- 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.
- Port generates the event payload - the payload includes metadata about the invoked action and its inputs.
- 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.
- 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.
- 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
🗃️ Webhook Actions
5 items
🗃️ GitHub Workflow Actions
2 items
🗃️ GitLab Pipelines Actions
2 items
🗃️ Jenkins Pipeline Actions
1 items
🗃️ Azure Pipeline Actions
1 items
📄️ Cloud Build Pipeline Trigger
In this guide, you will learn how to trigger your Cloud Build Pipelines from Port, using Webhook Actions.
📄️ Terraform Cloud Actions
Port's Terraform Cloud Action can trigger
📄️ Circle CI Actions
Port's Circle CI Action can trigger
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
Field | Type | Description | Example values |
---|---|---|---|
type | string | Defines the backend of the action. | WEBHOOK , KAFKA , GITHUB or GITLAB |
agent | boolean | Defines whether to use Port Agent for execution or not. Can only be used if type is set to WEBHOOK or GITLAB . | true or false |
url | string | Defines 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 |
org | string | The GitHub organization name. Can only be used if type is set to GITHUB . | port-labs |
repo | string | The GitHub repository name. Can only be used if type is set to GITHUB . | port-docs |
workflow | string | Defines 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 |
omitPayload | boolean | A 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 |
omitUserInputs | boolean | A 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 |
reportWorkflowStatus | boolean | A 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 . | |
defaultRef | string | The 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 . | |
projectName | string | The GitLab project name. Can only be used if type is set to GITLAB . | port |
groupName | string | The 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.