Skip to main content

Run a deployment for a service

In the following guide, you are going to build a self-service action in Port, that executes a GitLab pipeline behind the scenes.

The GitLab pipeline in this example, will run a new deployment and report back the action run status and the deployment entity to Port.



Create a GitLab pipeline​

First, we need to set up a GitLab pipeline for our CI/CD flow.

You can use this example of using Port's API from GitLab CI/CD:

Click here to see the code
stages: # List of stages for jobs, and their order of execution
- save-port-data
- deploy
- report-deployment
- send-logs
- update-status

save-port-data: # Example - get the Port API access token and RunId
stage: save-port-data
- apt-get -qq update
- apt-get install -y jq
- |
accessToken=$(curl -X POST \
-H 'Content-Type: application/json' \
-d '{"clientId": "'"$PORT_CLIENT_ID"'", "clientSecret": "'"$PORT_CLIENT_SECRET"'"}' \
-s '' | jq -r '.accessToken')
echo "ACCESS_TOKEN=$accessToken" >> data.env
runId=$(cat $TRIGGER_PAYLOAD | jq -r '.port_payload.context.runId')
echo "RUN_ID=$runId" >> data.env
dotenv: data.env

stage: deploy
- echo "Deploying application..."
## Enter your deploy logic here

report-deployment: # Example - create a deployment entity
stage: report-deployment
- |
curl --location --request POST "" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '{
"identifier": "'"$service-$environment"'",
"properties": {"jobUrl":"'"$CI_JOB_URL"'","imageTag":"latest"},
"relations": {}

send-logs: # Example - send Logs of the action run to Port
stage: send-logs
- |
curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"message": "this is a log test message example"}' \

update-status: # Example - update the Action run status as success
stage: update-status
image: curlimages/curl:latest
- |
curl -X PATCH \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{"status":"SUCCESS", "message": {"run_status": "GitLab CI/CD Run completed successfully!"}}' \

In order to trigger GitLab Pipelines through the Port agent, you'll need to create a GitLab Pipeline trigger token.

You can trigger pipelines accross multiple GitLab projects, as long as you have a trigger token with the required permissions.

Trigger tokens are loaded to the Port agent as environment variables.

Create a Blueprint​

Let’s configure a new blueprint, named Deployment, its base structure is:

"identifier": "deployment",
"title": "Deployment",
"icon": "Deployment",
"schema": {
"properties": {
"jobUrl": {
"type": "string",
"format": "url",
"title": "Job URL"
"deployingUser": {
"type": "string",
"title": "Deploying User"
"imageTag": {
"type": "string",
"title": "Image Tag"
"commitSha": {
"type": "string",
"title": "Commit SHA"
"required": []
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}

Create a Port action​

Now let’s configure a self-service action. Add a CREATE action that will be triggered every time a developer wants to initiate a new deployment for a service.

Here is the JSON of the action:

"identifier": "runGitLabPipline",
"title": "Trigger Gitlab Pipeline",
"icon": "DeployedAt",
"userInputs": {
"properties": {
"ref": {
"type": "string",
"title": "Ref"
"pipelineVariable1": {
"type": "string",
"title": "First Pipeline Variable "
"pipelineVariable2": {
"type": "string",
"title": "Second Pipeline Variable"
"invocationMethod": {
"type": "GITLAB",
"projectName": "project",
"groupName": "group",
"defaultRef": "main",
"agent": true,
"omitPayload": false,
"omitUserInputs": false
"trigger": "CREATE",
"description": "Trigger a GitLab Pipeline through the Port Agent",
"requiredApproval": false

Invocation method properties​

FieldTypeDescriptionExample values
typestringDefines the self-service action destination typeGITLAB
agentbooleanDefines whether to use Port Agent for execution or not.must be true in GitLab action type
projectNamestringDefines the GitLab project nameport
groupNamestringDefines the GitLab group nameport-labs
defaultRefstringThe default ref (branch / tag name) we want the action to use.
defaultRef can be overriden dynamically,
by adding ref as user input.
If not set, the agent triggers main branch
omitPayloadbooleanFlag to control whether to add port_payload JSON string to the GitLab pipeline trigger payload (default: false). If set to true, the payload will not be sent as part of the body.true or false
omitUserInputsbooleanFlag to control whether to send the user inputs of the Port action as GitLab CI/CD variables to the GitLab pipeline.
By default, the user inputs are passed as variables (default: false).
When disabled, you can still get the user inputs from the port_payload (unless omitted too).
true or false