Skip to content
Drydock
ConfigurationActions & NotificationsGitHub Dispatch

GitHub Dispatch

The githubdispatch trigger asks a GitHub repository to rebuild a locally built image when its upstream base image has a newer tag.

The githubdispatch trigger sends a repository_dispatch event to a GitHub repository so a workflow can rebuild a locally built image when its upstream base image has a newer tag. GitHub Enterprise Server 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_GITHUBDISPATCH_{trigger_name}_REPOSITORY🔴The repository to dispatch toowner/repo
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_TOKEN🔴A token that can create repository dispatch events (a fine-grained token with Contents write, or a classic token with repo scope)
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_EVENTTYPE⚪The event_type your workflow listens forAny stringdrydock-base-image-update
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_URL⚪The GitHub API base URL, for GitHub Enterprise Serverhttp or https URL, for example https://ghe.example.com/api/v3https://api.github.com
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_BASEIMAGEONLY⚪Only fire for a base image update of a locally built imagetrue, falsetrue
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_PROXY⚪The HTTP proxyValid http or https proxy URL
DD_NOTIFICATION_GITHUBDISPATCH_{trigger_name}_INSECURE⚪Skip TLS certificate verification, for a GitHub Enterprise Server with a private CAtrue, falsefalse
This trigger also supports the common configuration variables. Its message templates are not used: the request carries the structured payload 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 GitHub error message. The token never appears in logs or in the configuration API.

Request

POST {URL}/repos/{owner}/{repo}/dispatches
Accept: application/vnd.github+json
Authorization: Bearer <token>
X-GitHub-Api-Version: 2022-11-28

A single update and a batch use the same shape. A single update sends a containers array of one. A batch sends one dispatch for all qualifying containers.

{
  "event_type": "drydock-base-image-update",
  "client_payload": {
    "source": "drydock",
    "event": "base-image-update",
    "count": 1,
    "containers": [
      {
        "name": "web",
        "image": "acme/web",
        "localTag": "1.24.0",
        "baseImage": "library/nginx",
        "currentBaseTag": "1.24.0",
        "newBaseTag": "1.25.0",
        "currentBaseDigest": "sha256:aaa...",
        "newBaseDigest": "sha256:bbb...",
        "updateKind": { "kind": "tag", "baseImage": true, "semverDiff": "minor" }
      }
    ]
  }
}
FieldDescription
nameContainer name
imageThe locally built image name
localTagThe tag of the local image
baseImageThe upstream base from dd.registry.lookup.image
currentBaseTag / newBaseTagThe base tag the build tracks and the newer tag found
currentBaseDigest / newBaseDigestDigests, when known
updateKindkind, baseImage (true for a base image update) and semverDiff

GitHub accepts at most 10 top-level client_payload properties and about 64 KB, so the context sits under containers.

Examples

Rebuild when the base image changes

services:
  drydock:
    image: codeswhat/drydock:latest
    ...
    environment:
      - DD_NOTIFICATION_GITHUBDISPATCH_REBUILD_REPOSITORY=acme/web-image
      - DD_NOTIFICATION_GITHUBDISPATCH_REBUILD_TOKEN=github_pat_xxx

The workflow in acme/web-image:

on:
  repository_dispatch:
    types: [drydock-base-image-update]
jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo '${{ toJson(github.event.client_payload) }}'