Skip to main content


GitLab pipelines can be triggered using Port's execution agent.

Let's install the agent and configure it to trigger GitLab pipelines.


  • Helm must be installed to use the chart. Please refer to Helm's documentation for further details on the installation;
  • The connection credentials to Kafka are provided to you by Port;
  • If you want to trigger a GitLab Pipeline, you need to have a GitLab trigger token.
Trigger Tokens

In order to trigger your GitLab Pipeline you need to provide a GitLab trigger token as an environment variable.

To provide the trigger token to the agent, pass the helm chart an environment variable with a name that is the combination of the GitLab group and GitLab project separated by an underscore (_) , the name is case sensitive.

For example: group_project=token

You can load multiple trigger tokens, for different groups and projects in your GitLab environment.

Installing the agentโ€‹

  1. Add Port's Helm repo by using the following command:
helm repo add port-labs

If you already added this repo earlier, run helm repo update to retrieve the latest versions of the charts. You can then run helm search repo port-labs to see the charts.

  1. Install the port-agent chart by using the following command:
helm install my-port-agent port-labs/port-agent \
--create-namespace --namespace port-agent \
--set env.normal.PORT_ORG_ID=YOUR_ORG_ID \

Self Hosted GitLabโ€‹

If you are using a private GitLab environment, pass the GITLAB_URL environment variable to your Port agent installation:

--set env.normal.GITLAB_URL

Done! Port's execution agent is now running in your environment and will trigger any GitLab pipeline that you have configured.

Control the payloadโ€‹

The Port agent allows you to control the payload that is sent to gitlab api when triggering a pipeline.

By customizing the payload you can control the data that is sent to gitlab and the way the pipeline is triggered.

By default, the Port agent use the this default mapping to trigger gitlab pipelines:

Default Gitlab port agent mapping
"enabled": ".payload.action.invocationMethod.type == \"GITLAB\"",
"url": "(env.GITLAB_URL // \"\") as $baseUrl | (.payload.action.invocationMethod.groupName + \"/\" +.payload.action.invocationMethod.projectName) | @uri as $path | $baseUrl + \"api/v4/projects/\" + $path + \"/trigger/pipeline\"",
"body": {
"ref": " // .payload.action.invocationMethod.defaultRef // \"main\"",
"token": ".payload.action.invocationMethod.groupName as $gitlab_group | .payload.action.invocationMethod.projectName as $gitlab_project | env[($gitlab_group | gsub(\"/\"; \"_\")) + \"_\" + $gitlab_project]",
"variables": ".payload.action.invocationMethod as $invocationMethod | | to_entries | map({(.key): (.value | tostring)}) | add | if $invocationMethod.omitUserInputs then {} else . end",
"port_payload": "if .payload.action.invocationMethod.omitPayload then {} else . end"

You can read more about the payload mapping in the Control the payload mapping page.