Skip to content

Add --docker-arg option for global Docker CLI arguments #1304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Christof Marti (chrmarti) merged 3 commits into from
Oct 30, 2026
Merged

Add --docker-arg option for global Docker CLI arguments #1304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d9d5d97
Add optional runtime argument prefixes to CLI commands
shuaiyuanxx Sep 16, 2026
7251b0a
Rename --runtime-arg to --docker-arg and support it on all commands
chrmarti Oct 29, 2026
bef5b26
Add --docker-arg integration tests and shorten exec log lines
chrmarti Oct 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/spec-node/configContainer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ async function resolveWithLocalFolder(params: DockerResolverParameters, parsedAu

const { dockerCLI, dockerComposeCLI } = params;
const { env } = common;
const cliParams: DockerCLIParameters = { cliHost, dockerCLI, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
const cliParams: DockerCLIParameters = { cliHost, dockerCLI, dockerArgs: params.dockerArgs, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
await ensureNoDisallowedFeatures(cliParams, config, additionalFeatures, idLabels);

await runInitializeCommand({ ...params, common: { ...common, output: common.lifecycleHook.output } }, config.initializeCommand, common.lifecycleHook.onDidInput);
Expand Down
8 changes: 6 additions & 2 deletions src/spec-node/devContainers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import { Event } from '../spec-utils/event';

export interface ProvisionOptions {
dockerPath: string | undefined;
dockerArgs?: string[];
dockerComposePath: string | undefined;
containerDataFolder: string | undefined;
containerSystemDataFolder: string | undefined;
Expand Down Expand Up @@ -177,7 +178,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
exec: cliHost.exec,
env: cliHost.env,
output: common.output,
}, dockerPath, dockerComposePath);
}, dockerPath, dockerComposePath, options.dockerArgs);

const buildPlatformInfo = {
os: mapNodeOSToGOOS(cliHost.platform),
Expand Down Expand Up @@ -213,6 +214,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
const buildKitVersion = options.useBuildKit === 'never' ? undefined : (await dockerBuildKitVersion({
cliHost,
dockerCLI: dockerPath,
dockerArgs: options.dockerArgs,
dockerComposeCLI,
env: cliHost.env,
output,
Expand All @@ -221,11 +223,12 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
ociAuthDiagnostics: common.ociAuthDiagnostics,
}));

const cliVariant = await lookupCLIVariant({ exec: cliHost.exec, cmd: dockerPath, env: cliHost.env, output });
const cliVariant = await lookupCLIVariant({ exec: cliHost.exec, cmd: dockerPath, args: options.dockerArgs, env: cliHost.env, output });

const dockerEngineVer = await dockerEngineVersion({
cliHost,
dockerCLI: dockerPath,
dockerArgs: options.dockerArgs,
dockerComposeCLI,
env: cliHost.env,
output,
Expand All @@ -238,6 +241,7 @@ export async function createDockerParams(options: ProvisionOptions, disposables:
common,
parsedAuthority,
dockerCLI: dockerPath,
dockerArgs: options.dockerArgs,
cliVariant,
dockerComposeCLI: dockerComposeCLI,
dockerEnv: cliHost.env,
Expand Down
24 changes: 21 additions & 3 deletions src/spec-node/devContainersSpecCLI.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import textTable from 'text-table';
import * as jsonc from 'jsonc-parser';

import { createDockerParams, createLog, launch, ProvisionOptions } from './devContainers';
import { SubstitutedConfig, createContainerProperties, envListToObj, inspectDockerImage, isDockerFileConfig, SubstituteConfig, addSubstitution, findContainerAndIdLabels, getCacheFolder, runAsyncHandler } from './utils';
import { SubstitutedConfig, createContainerProperties, envListToObj, inspectDockerImage, isDockerFileConfig, SubstituteConfig, addSubstitution, findContainerAndIdLabels, getCacheFolder, runAsyncHandler, dockerArgOption } from './utils';
import { URI } from 'vscode-uri';
import { ContainerError } from '../spec-common/errors';
import { Log, LogDimensions, LogLevel, makeLog, mapLogLevel } from '../spec-utils/log';
Expand Down Expand Up @@ -132,6 +132,7 @@ export function getAllowedCrossOriginAuthHosts(args: OciAuthArgs) {
function provisionOptions(y: Argv) {
return y.options({
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
'container-data-folder': { type: 'string', description: 'Container data folder where user data inside the container will be stored.' },
'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
Expand Down Expand Up @@ -217,6 +218,7 @@ function provisionHandler(args: ProvisionArgs) {
async function provision({
'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'docker-compose-path': dockerComposePath,
'container-data-folder': containerDataFolder,
'container-system-data-folder': containerSystemDataFolder,
Expand Down Expand Up @@ -280,6 +282,7 @@ async function provision({

const options: ProvisionOptions = {
dockerPath,
dockerArgs,
dockerComposePath,
containerDataFolder,
containerSystemDataFolder,
Expand Down Expand Up @@ -390,6 +393,7 @@ async function doProvision(options: ProvisionOptions, providedIdLabels: string[]
function setUpOptions(y: Argv) {
return y.options({
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'container-data-folder': { type: 'string', description: 'Container data folder where user data inside the container will be stored.' },
'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
'container-id': { type: 'string', required: true, description: 'Id of the container.' },
Expand Down Expand Up @@ -438,6 +442,7 @@ async function setUp(args: SetUpArgs) {
async function doSetUp({
'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'container-data-folder': containerDataFolder,
'container-system-data-folder': containerSystemDataFolder,
'container-id': containerId,
Expand Down Expand Up @@ -469,6 +474,7 @@ async function doSetUp({
const configFile = configParam ? URI.file(path.resolve(process.cwd(), configParam)) : undefined;
const params = await createDockerParams({
dockerPath,
dockerArgs,
dockerComposePath: undefined,
containerSessionDataFolder,
containerDataFolder,
Expand Down Expand Up @@ -564,6 +570,7 @@ function buildOptions(y: Argv) {
return y.options({
'user-data-folder': { type: 'string', description: 'Host path to a directory that is intended to be persisted and share state between sessions.' },
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
'workspace-folder': { type: 'string', description: 'Workspace folder path. The devcontainer.json will be looked up relative to this path. If not provided, defaults to the current directory.' },
'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
Expand Down Expand Up @@ -620,6 +627,7 @@ async function build(args: BuildArgs) {
async function doBuild({
'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'docker-compose-path': dockerComposePath,
'workspace-folder': workspaceFolderArg,
config: configParam,
Expand Down Expand Up @@ -660,6 +668,7 @@ async function doBuild({
const additionalFeatures = additionalFeaturesJson ? jsonc.parse(additionalFeaturesJson) as Record<string, string | boolean | Record<string, string | boolean>> : {};
const params = await createDockerParams({
dockerPath,
dockerArgs,
dockerComposePath,
containerDataFolder: undefined,
containerSystemDataFolder: undefined,
Expand Down Expand Up @@ -720,7 +729,7 @@ async function doBuild({
throw new ContainerError({ description: '--push true cannot be used with --output.' });
}

const buildParams: DockerCLIParameters = { cliHost, dockerCLI: params.dockerCLI, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: params.common.ociAuthDiagnostics };
const buildParams: DockerCLIParameters = { cliHost, dockerCLI: params.dockerCLI, dockerArgs: params.dockerArgs, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: params.common.ociAuthDiagnostics };
await ensureNoDisallowedFeatures(buildParams, config, additionalFeatures, undefined);

// Support multiple use of `--image-name`
Expand Down Expand Up @@ -832,6 +841,7 @@ function runUserCommandsOptions(y: Argv) {
return y.options({
'user-data-folder': { type: 'string', description: 'Host path to a directory that is intended to be persisted and share state between sessions.' },
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
'container-data-folder': { type: 'string', description: 'Container data folder where user data inside the container will be stored.' },
'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
Expand Down Expand Up @@ -893,6 +903,7 @@ async function runUserCommands(args: RunUserCommandsArgs) {
async function doRunUserCommands({
'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'docker-compose-path': dockerComposePath,
'container-data-folder': containerDataFolder,
'container-system-data-folder': containerSystemDataFolder,
Expand Down Expand Up @@ -937,6 +948,7 @@ async function doRunUserCommands({

const params = await createDockerParams({
dockerPath,
dockerArgs,
dockerComposePath,
containerDataFolder,
containerSystemDataFolder,
Expand Down Expand Up @@ -1039,6 +1051,7 @@ function readConfigurationOptions(y: Argv) {
return y.options({
'user-data-folder': { type: 'string', description: 'Host path to a directory that is intended to be persisted and share state between sessions.' },
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
'workspace-folder': { type: 'string', description: 'Workspace folder path. The devcontainer.json will be looked up relative to this path. If --container-id, --id-label, and --workspace-folder are not provided, this defaults to the current directory.' },
'mount-workspace-git-root': { type: 'boolean', default: true, description: 'Mount the workspace using its Git root.' },
Expand Down Expand Up @@ -1077,6 +1090,7 @@ function readConfigurationHandler(args: ReadConfigurationArgs) {
async function readConfiguration({
// 'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'docker-compose-path': dockerComposePath,
'workspace-folder': workspaceFolderArg,
'mount-workspace-git-root': mountWorkspaceGitRoot,
Expand Down Expand Up @@ -1139,14 +1153,15 @@ async function readConfiguration({
exec: cliHost.exec,
env: cliHost.env,
output,
}, dockerCLI, dockerComposePath || 'docker-compose');
}, dockerCLI, dockerComposePath || 'docker-compose', dockerArgs);
const buildPlatformInfo = {
os: mapNodeOSToGOOS(cliHost.platform),
arch: mapNodeArchitectureToGOARCH(cliHost.arch),
};
const params: DockerCLIParameters = {
cliHost,
dockerCLI,
dockerArgs,
dockerComposeCLI,
env: cliHost.env,
output,
Expand Down Expand Up @@ -1307,6 +1322,7 @@ function execOptions(y: Argv) {
return y.options({
'user-data-folder': { type: 'string', description: 'Host path to a directory that is intended to be persisted and share state between sessions.' },
'docker-path': { type: 'string', description: 'Docker CLI path.' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Docker Compose CLI path.' },
'container-data-folder': { type: 'string', description: 'Container data folder where user data inside the container will be stored.' },
'container-system-data-folder': { type: 'string', description: 'Container system data folder where system data inside the container will be stored.' },
Expand Down Expand Up @@ -1369,6 +1385,7 @@ async function exec(args: ExecArgs) {
export async function doExec({
'user-data-folder': persistedFolder,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
'docker-compose-path': dockerComposePath,
'container-data-folder': containerDataFolder,
'container-system-data-folder': containerSystemDataFolder,
Expand Down Expand Up @@ -1402,6 +1419,7 @@ export async function doExec({
const overrideConfigFile = overrideConfig ? URI.file(path.resolve(process.cwd(), overrideConfig)) : undefined;
const params = await createDockerParams({
dockerPath,
dockerArgs,
dockerComposePath,
containerDataFolder,
containerSystemDataFolder,
Expand Down
9 changes: 5 additions & 4 deletions src/spec-node/dockerCompose.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ const serviceLabel = 'com.docker.compose.service';
export async function openDockerComposeDevContainer(params: DockerResolverParameters, workspace: Workspace, config: SubstitutedConfig<DevContainerFromDockerComposeConfig>, idLabels: string[], additionalFeatures: Record<string, string | boolean | Record<string, string | boolean>>): Promise<ResolverResult> {
const { common, dockerCLI, dockerComposeCLI } = params;
const { cliHost, env, output } = common;
const buildParams: DockerCLIParameters = { cliHost, dockerCLI, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
const buildParams: DockerCLIParameters = { cliHost, dockerCLI, dockerArgs: params.dockerArgs, dockerComposeCLI, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
return _openDockerComposeDevContainer(params, buildParams, workspace, config, getRemoteWorkspaceFolder(config.config), idLabels, additionalFeatures);
}

Expand Down Expand Up @@ -155,7 +155,7 @@ export async function buildAndExtendDockerCompose(configWithRaw: SubstitutedConf
const { cliHost, env, output } = common;
const { config } = configWithRaw;

const cliParams: DockerCLIParameters = { cliHost, dockerCLI, dockerComposeCLI: dockerComposeCLIFunc, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
const cliParams: DockerCLIParameters = { cliHost, dockerCLI, dockerArgs: params.dockerArgs, dockerComposeCLI: dockerComposeCLIFunc, env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics: common.ociAuthDiagnostics };
const composeConfig = await readDockerComposeConfig(cliParams, localComposeFiles, envFile);
const composeService = composeConfig.services[config.service];

Expand Down Expand Up @@ -701,7 +701,7 @@ async function useNewProjectName(params: DockerCLIParameters | DockerResolverPar
}
}

export function dockerComposeCLIConfig(params: Omit<PartialExecParameters, 'cmd'>, dockerCLICmd: string, dockerComposeCLICmd: string) {
export function dockerComposeCLIConfig(params: Omit<PartialExecParameters, 'cmd' | 'args'>, dockerCLICmd: string, dockerComposeCLICmd: string, dockerArgs: string[] = []) {
let result: Promise<DockerComposeCLI>;
return () => {
return result || (result = (async () => {
Expand All @@ -711,6 +711,7 @@ export function dockerComposeCLIConfig(params: Omit<PartialExecParameters, 'cmd'
stdout = (await dockerComposeCLI({
...params,
cmd: dockerCLICmd,
args: dockerArgs,
}, 'compose', 'version', '--short')).stdout;
} catch (err) {
stdout = (await dockerComposeCLI({
Expand All @@ -724,7 +725,7 @@ export function dockerComposeCLIConfig(params: Omit<PartialExecParameters, 'cmd'
return {
version,
cmd: v2 ? dockerCLICmd : dockerComposeCLICmd,
args: v2 ? ['compose'] : [],
args: v2 ? [...dockerArgs, 'compose'] : [],
};
})());
};
Expand Down
1 change: 1 addition & 0 deletions src/spec-node/featuresCLI/utils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ export const staticProvisionParams = {
export const staticExecParams = {
'user-data-folder': undefined,
'docker-path': undefined,
'docker-arg': undefined,
'docker-compose-path': undefined,
'container-data-folder': undefined,
'container-system-data-folder': undefined,
Expand Down
2 changes: 1 addition & 1 deletion src/spec-node/imageMetadata.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -351,7 +351,7 @@ export async function getImageBuildInfo(params: DockerResolverParameters | Docke
const envFile = Array.isArray(config.dockerComposeFile) && config.dockerComposeFile.length === 0 && await cliHost.isFile(cwdEnvFile) ? cwdEnvFile : undefined;
const composeFiles = await getDockerComposeFilePaths(cliHost, config, cliHost.env, cliHost.cwd);
const ociAuthDiagnostics = 'cliHost' in params ? params.ociAuthDiagnostics : params.common.ociAuthDiagnostics;
const buildParams: DockerCLIParameters = { cliHost, dockerCLI, dockerComposeCLI, env: cliHost.env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics };
const buildParams: DockerCLIParameters = { cliHost, dockerCLI, dockerArgs: params.dockerArgs, dockerComposeCLI, env: cliHost.env, output, buildPlatformInfo: params.buildPlatformInfo, targetPlatformInfo: params.targetPlatformInfo, ociAuthDiagnostics };

const composeConfig = await readDockerComposeConfig(buildParams, composeFiles, envFile);
const services = Object.keys(composeConfig.services || {});
Expand Down
7 changes: 5 additions & 2 deletions src/spec-node/upgradeCommand.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { Workspace, workspaceFromPath } from '../spec-utils/workspaces';
import { getDefaultDevContainerConfigPath, getDevContainerConfigPathIn, uriToFsPath } from '../spec-configuration/configurationCommonUtils';
import { readDevContainerConfigFile } from './configContainer';
import { ContainerError } from '../spec-common/errors';
import { getCacheFolder, runAsyncHandler } from './utils';
import { dockerArgOption, getCacheFolder, runAsyncHandler } from './utils';
import { Lockfile, generateLockfile, getLockfilePath, writeLockfile } from '../spec-configuration/lockfile';
import { isLocalFile, readLocalFile, writeLocalFile } from '../spec-utils/pfs';
import { readFeaturesConfig } from './featureUtils';
Expand All @@ -26,6 +26,7 @@ export function featuresUpgradeOptions(y: Argv) {
.options({
'workspace-folder': { type: 'string', description: 'Workspace folder. If --workspace-folder is not provided defaults to the current directory.' },
'docker-path': { type: 'string', description: 'Path to docker executable.', default: 'docker' },
'docker-arg': dockerArgOption,
'docker-compose-path': { type: 'string', description: 'Path to docker-compose executable.', default: 'docker-compose' },
'config': { type: 'string', description: 'devcontainer.json path. The default is to use .devcontainer/devcontainer.json or, if that does not exist, .devcontainer.json in the workspace folder.' },
'log-level': { choices: ['error' as 'error', 'info' as 'info', 'debug' as 'debug', 'trace' as 'trace'], default: 'info' as 'info', description: 'Log level.' },
Expand Down Expand Up @@ -57,6 +58,7 @@ export function featuresUpgradeHandler(args: FeaturesUpgradeArgs) {
async function featuresUpgrade({
'workspace-folder': workspaceFolderArg,
'docker-path': dockerPath,
'docker-arg': dockerArgs,
config: configArg,
'docker-compose-path': dockerComposePath,
'log-level': inputLogLevel,
Expand Down Expand Up @@ -88,7 +90,7 @@ async function featuresUpgrade({
exec: cliHost.exec,
env: cliHost.env,
output,
}, dockerPath, dockerComposePath);
}, dockerPath, dockerComposePath, dockerArgs);
const buildPlatformInfo = {
os: mapNodeOSToGOOS(cliHost.platform),
arch: mapNodeArchitectureToGOARCH(cliHost.arch),
Expand All @@ -97,6 +99,7 @@ async function featuresUpgrade({
const dockerParams: DockerCLIParameters = {
cliHost,
dockerCLI: dockerPath,
dockerArgs,
dockerComposeCLI,
env: cliHost.env,
output,
Expand Down
Loading
Loading