Git Settings¶

Settings to configure Git authentication and clone behavior.

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.

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
  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 no domain entry matches, doco-cd falls back to global GIT_ACCESS_TOKEN / SSH_PRIVATE_KEY values 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

# 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

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.

Commit Status Reporting¶

Doco-CD can post a commit status back to the source Git provider after each deployment, making the result visible directly on the commit or pull request in the Git web UI.

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.

Three states are reported:

• pending — set once after the repository is cloned and the deployment begins.
• success — set when all deployment stages complete successfully.
• failure — set when any stage fails after initialisation.

Required Token Permissions¶

The token used for commit status reporting needs permission to write commit statuses through the provider API. The same requirements apply whether you use the global GIT_ACCESS_TOKEN or a domain-scoped token from GIT_AUTH_DOMAINS.

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"

GIT_SCM_API_URL must be 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.

Example¶

services:
  app:
    environment:
      GIT_ACCESS_TOKEN: xxx         # token must be allowed to write commit statuses
      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