Skip to content

Poll Settings

About Polling

Polling is a time-based trigger that checks the repositories for changes to deploy at regular intervals. This method does not require doco-cd to be reachable from the internet but is less efficient and slower than webhooks.

Configuration

Key Type Description Default
POLL_CONFIG list A list/array of poll configurations provided in YAML format (see Poll Settings) Ignored when not specified
POLL_CONFIG_FILE string Path to the file inside the container containing the poll configurations in YAML format (see Poll Settings) Ignored when not specified

For Git sources, poll jobs also honor global source URL rewrites from SOURCE_URL_REWRITES. This is useful when polling should clone through an internal host/port instead of the public URL.

Supported Git transports include HTTP(S), SSH, native Git (git://), and local filesystem repositories.

They must be in the format of a YAML list/array (also called YAML Sequence) and can contain the following settings:

Settings without a default value are required.

Key Type Description Default value
source string Source backend for this poll job. Use git (default) for repositories or oci for OCI artifacts. git
url string Source URL. For source: git, this is the Git clone URL (e.g. https://github.com/kimdre/doco-cd.git or git@github.com:kimdre/doco-cd.git), or a local absolute path mounted into the container (e.g. /local-repos/my-app, equivalent to file:///local-repos/my-app, see Polling Local Filesystem Repositories). For source: oci, this is the full artifact reference (e.g. ghcr.io/myorg/config:main).
reference string Source revision used by deployment configs. For Git this is the branch/tag/ref (e.g. main or refs/heads/main). For OCI, the tag from url is used automatically when present. refs/heads/main
interval integer or string Poll interval (min 10s). Supports integer seconds (e.g. 300), numeric strings treated as seconds (e.g. "300"), and Go duration strings (e.g. "5m", "1m30s"). Set to 0 or "0s" to disable a poll job. Mutually exclusive with schedule. 180s (0 when schedule is set)
schedule string Cron schedule to poll at instead of a fixed interval, e.g. "*/15 * * * *" or "@daily". Evaluated in the timezone of doco-cd (TZ). Mutually exclusive with a non-zero interval. (Ignored when not specified)
target string Similar to the custom target webhook endpoint, used to target a specific deployment config, e.g., target: test -> .doco-cd.test.yaml (Ignored when not specified)
run_once boolean Stop the poll job after the first run. Useful if you only want to do the first initial deployment via the poll job but do all future deployments via webhooks false
watch boolean For local filesystem git sources only: watch the repository for new commits and trigger a poll immediately instead of waiting for interval. Set to false to disable and rely on interval only. Ignored for non-local Git and oci sources and when schedule is set. See Polling Local Filesystem Repositories true
deployments array of Deploy Configs In-line configuration for deployment settings specific to this poll configuration. Overrides the .doco-cd.yml file in the target repository (url) if exists.
See the example below.		 []

For Git sources, Doco-CD accepts http://, https://, ssh://, git://), and file:// URLs, plus absolute local paths.

Cron schedules

Instead of polling every interval, a poll job can poll at the times given by a schedule. It accepts the same schedule formats as scheduled jobs:

poll-config.yaml
- url: https://github.com/example/some-repo.git
  schedule: "0 2 * * *" # every day at 02:00
- url: https://github.com/example/other-repo.git
  schedule: "*/15 8-17 * * 1-5" # every 15 minutes during business hours on weekdays
  • The schedule is evaluated in the timezone of doco-cd, set by the TZ environment variable (default: UTC). Prefix it with CRON_TZ=<timezone> to use another timezone, e.g. "CRON_TZ=America/New_York 0 2 * * *".
  • A scheduled poll job does not poll at startup. The first poll happens at the next scheduled time. Until then, doco-cd does not reconcile the stacks of that repository, e.g. it does not restore a container that died after the restart.
  • schedule and interval are mutually exclusive. When schedule is set, interval defaults to 0.
  • For local filesystem repositories, the repository watcher is disabled when schedule is set, so polls only happen at the scheduled times.
  • run_once ignores schedule and polls once at startup. Poll runs triggered via the REST API or MCP also ignore it and run immediately.

Tip

A poll schedule works well together with sync windows: schedule a poll for when an allow window opens so that deferred changes are deployed right away.

Pausing deployments

Set pause in the deployment configuration, not as a poll setting. Polls keep reading the configuration while paused, so a later poll detects when the deployment is resumed. Inline deployment definitions replace repository definitions, so their pause setting is authoritative. For example:

poll-config.yaml
- url: https://github.com/example/app.git
  deployments:
    - name: production
      pause: true

Example

With POLL_CONFIG

Using a YAML anchor

With a YAML anchor (See Fragments and Extensions in Docker Compose), you can define the poll configuration outside the service definition.

docker-compose.yaml
x-poll-config: &poll-config
  POLL_CONFIG: |
    - url: https://github.com/example/some-repo.git
    - url: https://github.com/example/public-repo.git
      reference: dev
      interval: 300  # or as a Go duration: 5m

services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN: xxx
      WEBHOOK_SECRET: xxx
      <<: *poll-config
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data

volumes:
  data:

Inline configuration

docker-compose.yaml
services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN: xxx
      WEBHOOK_SECRET: xxx
      POLL_CONFIG: |
        - url: https://github.com/example/some-repo.git
        - url: https://github.com/example/public-repo.git
          reference: dev
          interval: 300  # or as a Go duration: 5m
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data

volumes:
  data:

With POLL_CONFIG_FILE

poll-config.yaml
- url: https://github.com/example/some-repo.git
- url: https://github.com/example/public-repo.git
  reference: dev
  interval: 300 # (1)!
  1. Or as a Go duration: 5m
docker-compose.yaml
services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN: xxx
      WEBHOOK_SECRET: xxx
      POLL_CONFIG_FILE: /poll-config.yaml
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data
      - ./poll-config.yaml:/poll-config.yaml:ro

volumes:
  data:

Using a docker compose config

docker-compose.yaml
services:
  app:
    container_name: doco-cd
    image: ghcr.io/kimdre/doco-cd:latest
    restart: unless-stopped
    ports:
      - "80:80"
    environment:
      TZ: Europe/Berlin
      GIT_ACCESS_TOKEN: xxx
      WEBHOOK_SECRET: xxx
      POLL_CONFIG_FILE: /poll-config.yml
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - data:/data
    configs: # (1)!
      - source: poll-config.yml
        target: /poll-config.yml

volumes:
  data:

configs:
  poll-config.yml:
    content: |
      - url: https://example.com
        reference: main
      - url: https://other-example.com
        interval: 120  # Or as a Go duration: 2m
      - url: https://yet-another-example.com
        reference: dev
  1. Use with the POLL_CONFIG_FILE environment variable.

OCI Example

poll-config.yaml
- source: oci
  url: ghcr.io/example/deploy-config:production
  interval: 300 # (1)!
  1. Or as a Go duration: 5m

See more at Polling with OCI and OCI Artifact Usage

Local Filesystem Example

poll-config.yaml
- source: git
  url: /local-repos/my-app
  reference: main
  interval: 60 # (1)!
  1. Or as a Go duration: 1m

See more at Polling Local Filesystem Repositories

Inline Deploy Configs

Inline deployments reuse the same fields as .doco-cd.yml files (See Deploy Settings), including support for external secrets and destroy workflows. The poll job url is always used as the deployment source URL.

If the poll config has an inline deployment config and the target repository also contains a .doco-cd.yml file, the file will be ignored in favor of the inline deployment config.

Matching Git webhooks also reuse inline deployments. A poll entry matches a webhook when its repository, reference, and optional target match the webhook request. Short branch names such as main are equivalent to full branch references such as refs/heads/main.

Inline configuration takes precedence

When one or more inline poll entries match a webhook, their deployments are combined and the repository's .doco-cd.yml is ignored. Inline and repository configurations are never merged. Repository configuration discovery is used only when no inline poll entry matches.

Deployment names must remain unique within each Docker context across all matching inline entries.

Poll Config with inline deploy config
- url: https://github.com/example/app.git
  reference: refs/heads/main
  interval: 300
  deployments:
    - name: example-app
      working_dir: services/app
      compose_files:
        - compose.yaml
      env_files:
        - .env.production