Git Settings¶

Settings to configure Git authentication, clone behavior, and deployment reporting.

Supported transports¶

Doco-CD accepts HTTP(S), SSH, native Git (git://host/path), and local filesystem repository URLs.

General¶

Authentication¶

The following settings configure how Doco-CD authenticates with Git providers when cloning or pulling repositories.

Supported authentication methods:

• HTTP(S) authentication with access tokens. See Required Token Permissions below.
• SSH authentication with private keys.
• If you need different credentials for different hosts, use Domain-scoped Authentication.

Credential Scope¶

Doco-CD selects the HTTP(S) credential for each URL by its host:

1. Doco-CD finds the GIT_AUTH_DOMAINS entry that matches the host (see Matching Behavior).
2. If the entry has its own git_access_token or GitHub App, doco-cd uses it.
3. If the entry has no HTTP(S) credential of its own (only domains, or only an SSH key), doco-cd uses the global GIT_ACCESS_TOKEN or the global GitHub App.
4. If no entry matches the host, doco-cd sends no HTTP(S) credential. Public repositories still work anonymously. Private repositories fail with an error that names the host. GIT_AUTH_ALLOW_ANY_HOST changes this step.

The port is not part of the match. An entry for git.example.com applies to https://git.example.com:8443/... too.

SSH keys are not affected by these rules. SSH URLs use the matched entry key, then the global SSH_PRIVATE_KEY.

Migrating from Global Credentials¶

Versions before v0.130.0 sent the global GIT_ACCESS_TOKEN or global GitHub App credentials to every HTTP(S) host, see the Git credential security advisory. By default, doco-cd now refuses to start with an error like this if a global HTTP(S) credential has no scope:

global Git HTTP(S) credentials must be scoped with GIT_AUTH_DOMAINS: GIT_ACCESS_TOKEN is set, but no GIT_AUTH_DOMAINS entry lists the hosts that may receive it. ...

To fix it, add an entry with only domains for each host that the global credential is for:

services:
  doco-cd:
    environment:
      GIT_ACCESS_TOKEN: xxx
      GIT_AUTH_DOMAINS: |
        - domains:
            - github.com

Things to check during the migration:

• Add every host that you clone from with the global credential. This includes hosts of Compose Git include URLs and submodules.
• If you use SOURCE_URL_REWRITES, doco-cd selects the credential for the host after the rewrite. Add the rewritten host, not the original host.
• An entry with its own git_access_token or GitHub App now takes precedence over the global credential for its hosts. Before, the global GIT_ACCESS_TOKEN won over a domain-scoped GitHub App.
• Every entry must have at least one valid domain. Domains with a scheme, path, port, or a wildcard that is not a leading *. are rejected at startup.
• If you roll back to an older version, that version ignores the scope and sends the global credential to every HTTP(S) host again.
• For a self-updating installation, add GIT_AUTH_DOMAINS to the managed Compose file before or together with the version upgrade. Older versions accept an entry with only domains, so you can add it first. If the new version does not start because the scope is missing, doco-cd rolls back and does not retry until a new commit arrives. Push a commit that adds the scope to retry the update.
• If you run bootstrap.sh from the self-updating example, it forwards GIT_AUTH_DOMAINS and uses github.com if you do not set it.

Limits of the Scope¶

The scope controls which hosts receive a credential. It does not control which repositories doco-cd deploys from.

• Doco-CD still clones public repositories from unlisted hosts anonymously.
• A scoped wildcard such as *.example.com trusts every subdomain. Use exact domains if other people can create subdomains.
• An attacker who can make a listed host serve content, or who can intercept plain http:// traffic to it, can still get the credential. Use HTTPS.
• Webhook requests still need a valid WEBHOOK_SECRET. Keep it secret, because anyone with it can trigger deployments of any repository URL.

Disabling the Scope¶

If you do not want to maintain GIT_AUTH_DOMAINS, you can turn off the scope for the global credential:

services:
  doco-cd:
    environment:
      GIT_ACCESS_TOKEN: xxx
      GIT_AUTH_ALLOW_ANY_HOST: "true"

Use it only if every source of repository URLs is trusted, and if the credential has the smallest possible permissions (for example a fine-grained token with read-only access to selected repositories).

The setting changes only hosts without a matching entry. GIT_AUTH_DOMAINS entries keep their rules, the redirect protection of the API clients stays active, and commit status reporting still uses the credential of the repository host.

The repository's docker-compose.yml forwards GIT_AUTH_ALLOW_ANY_HOST from .env with a default of false. For a self-updating installation, set the option in the managed Compose service too. bootstrap.sh forwards it only to the one-shot bootstrap container.

SSH Host-Key Verification¶

Doco-CD supports two host-key trust modes for Git SSH remotes:

• Operator-managed: Set SSH_KNOWN_HOSTS_FILE to a mounted known_hosts file. Doco-CD treats it as authoritative and read-only. Add both the old and new server keys before a planned rotation, then remove the old key after the rotation.
• Automatic (default): Leave SSH_KNOWN_HOSTS_FILE unset. Doco-CD obtains a host key on first use and automatically replaces a changed key for the same host and port. This avoids interruption when providers rotate keys, but it trusts the key returned by the network and therefore does not protect against a host-key substitution attack.

Example using a read-only Docker config:

services:
  doco-cd:
    environment:
      SSH_KNOWN_HOSTS_FILE: /run/configs/git_known_hosts
    configs:
      - source: git_known_hosts
        target: /run/configs/git_known_hosts

configs:
  git_known_hosts:
    file: ./known_hosts

Rotating a Mounted Host Key¶

When a Git server reports a changed key, obtain the new key from a trusted source and add it to the mounted known_hosts file. Doco-CD will then accept the new key on the next connection.

For hosted providers, use the official host-keys. For example GitHub.com or GitLab.com.

Use ssh-keyscan to obtain the host key:

ssh-keyscan -t ed25519 git.example.com

ssh-keyscan -p 2222 -t ed25519 git.example.com

Required Token Permissions¶

The token used for HTTP(S) clone/fetch access needs permission to read repository contents. The same requirements apply whether you use the global GIT_ACCESS_TOKEN or a domain-scoped token from GIT_AUTH_DOMAINS.

See below provider-specific setup steps:

Domain-scoped Authentication¶

Use domain-scoped config when you fetch from multiple Git providers/domains and need separate credentials.

Syntax and Format¶

The domain-scoped authentication configuration is a YAML list where each entry defines credentials for one or more domains.

Entry Structure¶

Each entry in the list has the following structure:

- domains:                          # (Required) List of domain names or patterns
    - domain1.com
    - domain2.com
    - '*.example.com'
  git_access_token: xxx             # (Optional) HTTP token for git access. If omitted, the global credential is used
  git_access_token_user: oauth2     # (Optional) Username for git_access_token (e.g. gitlab+deploy-token-1234567)
  ssh_private_key: |                # (Optional) SSH private key content
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
  ssh_private_key_passphrase: xxx   # (Optional) Passphrase for encrypted SSH key

Available Options¶

Authentication Method Selection¶

• Use git_access_token for HTTP(S) based Git access
• Use ssh_private_key (and optionally ssh_private_key_passphrase) for SSH-based Git access
• Use github_app_id + github_app_private_key for GitHub App based HTTP(S) access
• Do not mix methods in the same entry

Matching Behavior¶

• Exact domain match wins over wildcard entries.
• If multiple wildcard patterns match, the longest suffix wins (most specific).
• Wildcards only match subdomains. Example: *.example.com matches git.example.com, but not example.com.
• If the matched entry has no HTTP(S) credential of its own, doco-cd uses the global GIT_ACCESS_TOKEN or GitHub App for HTTP(S) URLs.
• If no domain entry matches, doco-cd sends no HTTP(S) credential. For SSH URLs, it uses the global SSH_PRIVATE_KEY if set.
• Submodule remotes are resolved independently, so each submodule can use credentials for its own domain.

Examples¶

services:
  app:
    environment:
      GIT_AUTH_DOMAINS: |
        # Example value for GIT_AUTH_DOMAINS
        - domains:
            - github.com
          github_app_id: "123456"
          github_app_private_key: |
            -----BEGIN RSA PRIVATE KEY-----
            ...
            -----END RSA PRIVATE KEY-----
          # Optional: pin a known installation id. If omitted, doco-cd resolves it by owner/repo.
          # github_app_installation_id: 987654321

        - domains:
            - gitlab.com
            - '*.corp.example.com'
          ssh_private_key: |
            -----BEGIN OPENSSH PRIVATE KEY-----
            ...
            -----END OPENSSH PRIVATE KEY-----
          ssh_private_key_passphrase: ""

        - domains:
            - gitlab.example.com
          # GitLab deploy token: git_access_token_user must be the deploy token's username.
          git_access_token: "gldt-xxxxxxxxxxxxxxxxxxxx"
          git_access_token_user: gitlab+deploy-token-1234567

        # No own HTTP credential: these hosts receive the global GIT_ACCESS_TOKEN or GitHub App.
        - domains:
            - git.example.com

# Example value for GIT_AUTH_DOMAINS
- domains:
    - github.com
  github_app_id: "123456"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    -----END RSA PRIVATE KEY-----
  # Optional: pin a known installation id. If omitted, doco-cd resolves it by owner/repo.
  # github_app_installation_id: 987654321

- domains:
    - gitlab.com
    - '*.corp.example.com'
  ssh_private_key: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
  ssh_private_key_passphrase: ""

- domains:
    - gitlab.example.com
  # GitLab deploy token: git_access_token_user must be the deploy token's username.
  git_access_token: "gldt-xxxxxxxxxxxxxxxxxxxx"
  git_access_token_user: gitlab+deploy-token-1234567

# No own HTTP credential: these hosts receive the global GIT_ACCESS_TOKEN or GitHub App.
- domains:
    - git.example.com

services:
  app:
    environment:
      GIT_AUTH_DOMAINS_FILE: /run/secrets/git_auth_domains
    secrets:
      - git_auth_domains

secrets:
  git_auth_domains:
    file: ./git-auth-domains.yaml

GitHub Apps¶

GitHub Apps are supported natively and can be configured globally (see below) or per domain. Doco-CD will auto-detect the installation by repository owner/name and mint short-lived installation access tokens. The detected installation ID is cached for an hour, and looked up again earlier if the App is reinstalled; set GITHUB_APP_INSTALLATION_ID to skip the lookup entirely.

A global GitHub App needs a GIT_AUTH_DOMAINS entry without its own HTTP(S) credential, for example - domains: [github.com], the same as a global GIT_ACCESS_TOKEN (see Credential Scope). Doco-CD calls the GitHub API with the App credentials only for hosts in that scope. These calls do not follow redirects to another host.

Commit Status Reporting¶

Doco-CD can report deployment outcomes to the source Git provider, making the result visible directly on the commit or pull request in the Git web UI. Reporting is disabled by default. Enable it with GIT_COMMIT_STATUS=true.

This closes the GitOps feedback loop: instead of only seeing success or failure in container logs or Apprise notifications, the commit itself is marked with the deployment outcome.

Once pre-deployment checks confirm work is needed, Doco-CD reports each deployment under its existing name, doco-cd/<stack> or doco-cd/<target>/<stack> when a target is configured. Queued reporting is published before waiting for a mutation admission slot.

Deployments excluded by a webhook reference filter or requiring no changes do not receive deployment-specific checks or statuses. When the entire webhook run is skipped, Doco-CD reports a run-level result under doco-cd/<target>/deploy when a target is configured, or doco-cd/deploy otherwise. The same target-aware name is used for Git clone failures and failures before deployment configuration can be resolved, including polling runs. This keeps failures and skipped runs for different targets separate on the same commit.

While a deployment runs, its check or status also shows the current deployment phase, the same one logged by the deployment in progress heartbeat, for example pulling images or waiting for services to start. A phase is only published once it has lasted 3 seconds, so short phases cost no API requests. Phase updates are best-effort: each is sent once without retries, a provider rate limit pauses them for the rest of the deployment, and the final result always replaces them.

When doco-cd updates itself, the instance that finishes the handover completes the original reporting backend and target, even if the update disables GIT_COMMIT_STATUS. The finishing instance must still have credentials with the required permissions.

Required Token Permissions¶

Token-based reporting needs permission to write commit statuses through the provider API, whether credentials come from the global GIT_ACCESS_TOKEN or a domain-scoped token in GIT_AUTH_DOMAINS.

Doco-CD uses the credential that is scoped to the repository host for reporting. If no credential is scoped to that host, doco-cd logs a warning and does not report. Reporting requests do not follow redirects to another host, so the credential cannot go to a different server.

If an access token is also used to clone Git repositories over HTTP(S) (see Authentication), add the permission below in addition to the existing clone permissions required by your provider (see Required Token Permissions above).

Provider Auto-Detection¶

When GIT_SCM_PROVIDER is not set, doco-cd detects the provider from the repository URL:

Self-Hosted Instances and API URL¶

Doco-CD derives the SCM API base URL from the clone URL by converting its scheme to https://. This works correctly for most setups, but two scenarios require an explicit override via GIT_SCM_API_URL:

SSH clone URL with a non-standard SSH port

When the clone URL is an SSH URL with a custom port (e.g. ssh://git@gitea.example.com:2222/org/repo.git), doco-cd strips the port before building the API URL so the API call targets https://gitea.example.com/... correctly. If for any reason this stripping doesn't produce the right host or port (e.g. the HTTPS endpoint is on a non-standard port), set the API base URL explicitly:

GIT_SCM_API_URL: "https://gitea.example.com:8443"

SSH and HTTPS served from different hostnames or ports

Some self-hosted setups route SSH clones through a dedicated hostname or port (e.g. git.internal:2222) while the HTTPS API is on a different address (e.g. https://git.example.com). In that case the auto-derived URL will be wrong regardless of port stripping:

GIT_SCM_API_URL: "https://git.example.com"

For commit status reporting, configure GIT_SCM_API_URL as an http:// or https:// URL pointing to the root of the SCM instance (no path, no trailing slash). Provider-specific API paths (e.g. /api/v1, /api/v4) are appended automatically.

This override also applies to native GitHub Checks requests. For GitHub Enterprise Server, a root URL automatically gains /api/v3; an explicit API prefix such as https://ghe.example.com/api/v3 is used as-is. Set GIT_SCM_PROVIDER=github as described above.

Example¶

services:
  app:
    environment:
      GIT_ACCESS_TOKEN: xxx         # token must be allowed to write commit statuses
      GIT_AUTH_DOMAINS: |           # hosts that receive GIT_ACCESS_TOKEN
        - domains: [github.com]
      GIT_COMMIT_STATUS: "true"
      # GIT_SCM_PROVIDER: gitlab   # uncomment for self-hosted GitLab at a custom domain
      # GIT_SCM_API_URL: https://git.example.com  # optional explicit API base URL override