Workflow settings

A workflow can be a boolean, a raw YAML string, a complete vendor workflow ({ provider, workflow }), or a WorkflowOptions object. The object is merged over the generated GitHub default, so you only describe what changes. These options apply to every GitHub workflow (ci, changelog, release, issues, sync).

dbx.config.ts

toolchain: {
    ci: {
        ci: {
            enabled: true,
            pushBranches: ['main', 'next'],
            pullRequestBranches: ['main', 'release/**'],
            triggers: { schedule: [{ cron: '0 6 * * *' }] },
            tokens: { nodeVersion: '24' },
            extra: { permissions: { contents: 'read' } },
            steps: {
                after: [{ name: 'Lint', run: 'yarn lint' }],
            },
            jobs: {
                smoke: {
                    'runs-on': 'ubuntu-latest',
                    steps: [{ run: 'echo ok' }],
                },
            },
        },
    },
}

Option	What it does
enabled	Enable/disable this workflow (default: enabled when present).
provider	Vendor for a complete workflow object (default github).
pushBranches	Replace on.push.branches.
pullRequestBranches	Replace on.pull_request.branches.
triggers	Merge extra on.* triggers.
extra	Merge extra top-level keys (permissions, concurrency, env, ...).
steps	Inject steps before/after a job's generated steps (one group or per-job).
jobs	Merge extra complete jobs.
tokens	Override workflow tokens (nodeVersion, packageManager, yarnVersion, ...).
filename	Override the generated file name (default ci.yml, release.yml, ...).
dir	Override the output directory (default .github/workflows).

Steps

steps accepts one group or an array of groups. A group targets a job id (default: the first/primary job) and can add steps before or after the generated ones:

steps: [
    { job: 'ci', before: [{ name: 'Install extras', run: 'yarn add -D foo' }] },
    { job: 'ci', after: [{ name: 'Smoke', run: 'yarn smoke' }] },
];

Tokens

The default workflow templates use replacements. tokens merges over the project-wide values, so one workflow can use a different Node version or package manager without changing project. Overriding packageManager switches to that manager's default version unless you also set packageManagerVersion (or the legacy yarnVersion alias).

Raw YAML

A string is used as the workflow file's exact content. It is not merged, not token-replaced and gets no generated header; an empty string disables it.

Vendor workflows

Set provider (github, gitlab or azure) with a complete workflow object to write another CI vendor's pipeline instead of the generated GitHub default. The object is written as-is (with the toolchain's replacements applied), so it must be a complete pipeline:

dbx.config.ts

toolchain: {
    ci: {
        ci: {
            provider: 'gitlab',
            workflow: {
                stages: ['test'],
                test: { stage: 'test', script: ['yarn test'] },
            },
        },
        release: {
            provider: 'azure',
            workflow: {
                trigger: ['main'],
                pool: { vmImage: 'ubuntu-latest' },
                steps: [{ script: 'yarn build' }],
            },
        },
    },
}

The default paths are .gitlab-ci.yml and azure-pipelines.yml (GitHub keeps .github/workflows/<id>.yml); filename and dir override them. A complete vendor workflow defines its own triggers, so the ci.changelog.branches defaults do not rewrite them. dbx workflow runs each workflow with its vendor CLI (glab ci run, az pipelines run --name <pipeline>, or gh workflow run).

Set setup: true to inject the provider-specific setup before the pipeline's own steps: GitHub gets the checkout/Node/Corepack/install steps, GitLab gets a node:<version> image plus a before_script, and Azure gets UseNode@1 plus an install script. It defaults to false, so the workflow is written as-is.

If a hand-written .gitlab-ci.yml / azure-pipelines.yml already exists, sync leaves it untouched and records a workflow conflict, exactly like a GitHub workflow. Set ci.<id>: { enabled: false } to opt out explicitly.

Custom workflows

Add any number of extra workflows with toolchain.ci.custom, keyed by workflow id. A custom workflow is enabled by presence (there is no boolean form): a string is written verbatim, a complete vendor workflow ({ provider, workflow }) is written as-is, or an object is merged over an empty GitHub workflow — build it with triggers, extra and jobs (plus filename / dir):

dbx.config.ts

toolchain: {
    ci: {
        custom: {
            deploy: {
                triggers: { workflow_dispatch: {}, push: { branches: ['main'] } },
                filename: 'deploy.yml', // default: deploy.yml
                dir: '.github/workflows', // default
                jobs: {
                    deploy: {
                        'runs-on': 'ubuntu-latest',
                        steps: [
                            { uses: 'actions/checkout@v4' },
                            { run: 'yarn deploy' },
                        ],
                    },
                },
            },
        },
    },
}

This writes .github/workflows/deploy.yml and manages it like any built-in workflow (the generated header is prepended, and dbx sync --check tracks it). Set setup: true to inject the shared checkout/Node/Corepack/install steps into each job; steps the job already defines are not duplicated.

Existing workflows

If a generated workflow path already contains a hand-written workflow that dbx has never managed (no manifest entry and no generated header), dbx sync leaves it untouched, warns, and records the conflict in .dbx/toolchain/manifest.json. Set ci.<id>: { enabled: false } (or, for a custom workflow, ci.custom.<id>: { enabled: false }) to make the opt-out explicit. The file is also never deleted when the workflow is later disabled, because dbx did not create it. Use dbx workflow --list (or --list --json) to see the enabled workflows and their exact paths; dbx workflow <id|file> honours filename and dir overrides.