GitLab CI/CD Pipelines

The GitLab CI/CD pipeline action allows workflows to trigger pipelines directly using your installed GitLab integration.

Prerequisites

• A GitLab integration installed in your Port organization.
• The GitLab project you want to trigger a pipeline on must have a valid .gitlab-ci.yml.
• Actions processing must be enabled on your integration:
  • Hosted by Port / UI / OAuth installations: actions processing is enabled automatically.
  • Self-hosted (Helm or Docker): actions processing is disabled by default and must be explicitly enabled. See Enable actions processing for self-hosted installations below.
• Your GitLab token must have sufficient scopes to trigger pipelines and manage webhooks:

  • Legacy PAT: the api scope covers everything required.

  • Fine-grained PAT: configure the following resource permissions:

    Fine-grained PAT permissions (click to expand)

    Group and project

    Resource	Permission
    Group	Read
    Project	Read
    Pipeline (CI/CD)	Create
    Webhook (Integrations)	Create, Read

    User

    Resource	Permission
    Project	Read
    Group	Read

Enable actions processing for self-hosted installations

If you installed the GitLab Ocean integration as hosted by Port (via the UI or OAuth), actions processing is enabled automatically and you can skip to Configuration.

For self-hosted deployments (Kubernetes/Helm or Docker), the actions processor is disabled by default. You need to enable it explicitly using the flags below, depending on how you deployed the integration:

Helm

Pass the following flags when installing or upgrading the Helm chart:

helm upgrade --install gitlab-v2-ocean port-labs/port-ocean \
  --set actionsProcessor.enabled=true \
  --set ocean.baseUrl=<YOUR_INTEGRATION_BASE_URL> \
  # ... rest of your values

• actionsProcessor.enabled=true - enables the actions processor so the integration can receive and execute GitLab pipeline trigger requests from Port.
• ocean.baseUrl=<YOUR_INTEGRATION_BASE_URL> - required when reportPipelineStatus is enabled (the default). Port uses this URL to receive webhook events from GitLab and update the action run status in real time. The URL must be reachable from GitLab.

Docker

Add the following environment variables to your Docker run command or docker-compose configuration:

docker run \
  -e OCEAN__FEATURE_FLAGS__ACTIONS_PROCESSOR_ENABLED=true \
  -e OCEAN__INTEGRATION__CONFIG__OCEAN_BASE_URL=<YOUR_INTEGRATION_BASE_URL> \
  # ... rest of your env vars
  ghcr.io/port-labs/port-ocean-gitlab-v2:latest

What is reportPipelineStatus?

By default, Port automatically updates the action/automation run status in Port when the triggered GitLab pipeline finishes. This requires GitLab to send a pipeline webhook event back to the integration. If the integration's base URL is not set, Port cannot receive this callback and the run status will not be updated automatically.

To disable this behavior, set reportPipelineStatus: false in the execution properties of your action node, or turn off the Report pipeline status toggle in the UI.

Configuration

Field	Type	Description
type	"INTEGRATION_ACTION"	Required. Must be "INTEGRATION_ACTION"
installationId	string	Required. Your GitLab integration installation ID
integrationProvider	"gitlab-v2"	Required. Must be "gitlab-v2"
integrationInvocationType	"trigger_pipeline"	Required. Operation type
integrationActionExecutionProperties	object	Required. GitLab-specific configuration

Execution properties

Field	Type	Description
project	string	Required. GitLab project path (e.g., my-group/my-project) or numeric project ID
ref	string	Required. Branch name, tag, or commit SHA to run the pipeline on
pipelineVariables	object	Key-value pairs passed as CI/CD variables to the pipeline
reportPipelineStatus	boolean	Whether to report pipeline completion status back to Port (default: true)

Basic example

Trigger a GitLab pipeline, passing environment and version from the trigger inputs:

{
  "identifier": "trigger-gitlab-pipeline",
  "title": "Trigger GitLab Pipeline",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "your-installation-id",
    "integrationProvider": "gitlab-v2",
    "integrationInvocationType": "trigger_pipeline",
    "integrationActionExecutionProperties": {
      "project": "my-group/my-project",
      "ref": "{{ .outputs.trigger.branch }}",
      "pipelineVariables": {
        "ENVIRONMENT": "{{ .outputs.trigger.environment }}",
        "VERSION": "{{ .outputs.trigger.version }}"
      }
    }
  }
}

Pipeline variables

Pass CI/CD variables to your pipeline using the pipelineVariables field. Values can be static or dynamically resolved from workflow outputs:

{
  "integrationActionExecutionProperties": {
    "project": "my-group/my-project",
    "ref": "main",
    "pipelineVariables": {
      "ENVIRONMENT": "{{ .outputs.trigger.environment }}",
      "VERSION": "{{ .outputs.trigger.version }}",
      "DRY_RUN": "{{ .outputs.trigger.dryRun | tostring }}"
    }
  }
}

Variables are passed to the pipeline as CI/CD variables and are accessible in your .gitlab-ci.yml as $VARIABLE_NAME.

Status reporting

By default, Port monitors the triggered pipeline and updates the workflow node status when it completes. To opt out:

{
  "integrationActionExecutionProperties": {
    "project": "my-group/my-project",
    "ref": "main",
    "reportPipelineStatus": false
  }
}

When reportPipelineStatus is false, the node completes immediately after the pipeline is triggered, without waiting for the pipeline to finish.

Complete workflow example

A self-service deployment workflow that triggers a GitLab pipeline and updates the service entity on completion:

Workflow example (click to expand)

{
  "identifier": "deploy-with-gitlab",
  "title": "Deploy Service with GitLab CI",
  "icon": "GitLab",
  "description": "Trigger a deployment pipeline using GitLab CI/CD",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Request Deployment",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service"
            },
            "environment": {
              "type": "string",
              "title": "Environment",
              "enum": ["staging", "production"]
            },
            "version": {
              "type": "string",
              "title": "Version",
              "description": "Git tag or commit SHA"
            }
          },
          "required": ["service", "environment", "version"]
        }
      }
    },
    {
      "identifier": "trigger-pipeline",
      "title": "Trigger GitLab Pipeline",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "gitlab-integration-123",
        "integrationProvider": "gitlab-v2",
        "integrationInvocationType": "trigger_pipeline",
        "integrationActionExecutionProperties": {
          "project": "my-group/{{ .outputs.trigger.service }}",
          "ref": "{{ .outputs.trigger.version }}",
          "pipelineVariables": {
            "ENVIRONMENT": "{{ .outputs.trigger.environment }}",
            "VERSION": "{{ .outputs.trigger.version }}"
          },
          "reportPipelineStatus": true
        }
      }
    },
    {
      "identifier": "update-entity",
      "title": "Update Service Status",
      "config": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "service",
        "mapping": {
          "identifier": "{{ .outputs.trigger.service }}",
          "properties": {
            "lastDeployedVersion": "{{ .outputs.trigger.version }}",
            "lastDeployedEnvironment": "{{ .outputs.trigger.environment }}",
            "lastDeployedAt": "{{ now | todateiso8601 }}"
          }
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "trigger-pipeline"
    },
    {
      "sourceIdentifier": "trigger-pipeline",
      "targetIdentifier": "update-entity"
    }
  ]
}

GitLab CI/CD configuration

Your .gitlab-ci.yml can access pipeline variables passed from Port using the standard $VARIABLE_NAME syntax:

Example .gitlab-ci.yml (click to expand)

# .gitlab-ci.yml
stages:
  - deploy

deploy:
  stage: deploy
  script:
    - echo "Deploying version $VERSION to $ENVIRONMENT"
    # Your deployment logic here
  environment:
    name: $ENVIRONMENT
  rules:
    - if: $CI_PIPELINE_SOURCE == "api"
    - if: $CI_PIPELINE_SOURCE == "web"