Skip to content
Drydock
ConfigurationActions & NotificationsGitLab Pipeline

GitLab Pipeline

The gitlabpipeline trigger starts a GitLab pipeline to rebuild a locally built image when its upstream base image has a newer tag.

The gitlabpipeline trigger calls the GitLab pipeline trigger API to start a pipeline that rebuilds a locally built image when its upstream base image has a newer tag. Self-hosted GitLab is supported through URL.

It is a notification trigger, so it uses the DD_NOTIFICATION_* prefix. It never updates a container itself. The Docker and Docker Compose actions refuse to run for a locally built image, so a build is never replaced by the stock upstream image, and this trigger only asks your own pipeline to rebuild.

By default it fires only for a base image update of a locally built image: a container with dd.registry.lookup.image set whose image was built on the host (see local builds). Set BASEIMAGEONLY=false to let it fire for any update that the normal trigger filters allow.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_PROJECT🔴The project to run the pipeline inNumeric project id or the path, for example group/app
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_TOKEN🔴A pipeline trigger token for the project
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_REF⚪The branch or tag to run the pipeline onAny branch or tagmain
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_URL⚪The GitLab base URL, for self-hosted GitLabhttp or https URLhttps://gitlab.com
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_VARIABLES_{name}⚪An extra pipeline variable sent with every request. The name is sent in upper caseAny string
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_BASEIMAGEONLY⚪Only fire for a base image update of a locally built imagetrue, falsetrue
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_PROXY⚪The HTTP proxyValid http or https proxy URL
DD_NOTIFICATION_GITLABPIPELINE_{trigger_name}_INSECURE⚪Skip TLS certificate verification, for a self-hosted GitLab with a private CAtrue, falsefalse
This trigger also supports the common configuration variables. Its message templates are not used: the request carries the pipeline variables below.
Requests have the outbound HTTP timeout (30 seconds by default, DD_OUTBOUND_HTTP_TIMEOUT_MS) and do not follow redirects. A failure or timeout is logged like any other trigger failure with the HTTP status and the GitLab error message. The trigger token and the values of configured variables never appear in logs or in the configuration API.

Request

POST {URL}/api/v4/projects/{project}/trigger/pipeline
Content-Type: application/x-www-form-urlencoded

The form carries token, ref and these pipeline variables. A single update and a batch use the same variables; the per-container ones are only set when the request covers exactly one container.

VariableDescription
DD_EVENTAlways base-image-update
DD_CONTAINER_COUNTNumber of containers in the request
DD_CONTAINER_NAMESComma separated container names
DD_PAYLOADJSON with the full context of every container, shaped like the GitHub Dispatch payload client_payload
DD_CONTAINER_NAMEContainer name (single container)
DD_IMAGEThe locally built image name (single container)
DD_LOCAL_TAGThe tag of the local image (single container)
DD_BASE_IMAGEThe upstream base from dd.registry.lookup.image (single container)
DD_CURRENT_BASE_TAG / DD_NEW_BASE_TAGThe base tag the build tracks and the newer tag found (single container)
DD_CURRENT_BASE_DIGEST / DD_NEW_BASE_DIGESTDigests, when known (single container)

Examples

Rebuild when the base image changes

services:
  drydock:
    image: codeswhat/drydock:latest
    ...
    environment:
      - DD_NOTIFICATION_GITLABPIPELINE_REBUILD_PROJECT=group/web-image
      - DD_NOTIFICATION_GITLABPIPELINE_REBUILD_TOKEN=glptt-xxx
      - DD_NOTIFICATION_GITLABPIPELINE_REBUILD_REF=main

In .gitlab-ci.yml, run the rebuild job for triggered pipelines:

rebuild:
  rules:
    - if: $CI_PIPELINE_SOURCE == "trigger" && $DD_EVENT == "base-image-update"
  script:
    - echo "Rebuilding $DD_CONTAINER_NAME on $DD_BASE_IMAGE:$DD_NEW_BASE_TAG"