devops-config-resolver

devops-config-resolver

Resolves the active configuration for the DevOps coding agent by layering multiple sources in a defined precedence order and enforcing governance constraints before any code action begins.

Guardrails Handoff Check

Before running any governance checks, inspect the workspace root for .guardrails-agent.json.

If .guardrails-agent.json exists:

• Set internal flag guardrailsActive: true
• Skip the entire Governance section below — those checks are now handled by the policy-enforcement skill via the agent's adapter skill.
• Continue with: language resolution, framework detection, guidelines path resolution, and LSP startup only.

If .guardrails-agent.json does not exist:

• guardrailsActive: false
• Proceed with all sections below as normal (backwards-compatible mode).

Configuration File

Read .devops-agent.json from the workspace root if it exists. This file is optional; all fields fall back to plugin defaults when absent. Parse it as JSON and surface a clear error if the file is present but malformed.

The file is typically created by the /devops-init command, which scaffolds it with auto-detected values as defaults.

Resolution Order

Apply the following five-level priority chain. Higher levels fully override lower levels for the same key. Merge objects at the same key rather than replacing them, except where a level explicitly sets a scalar.

1. Per-invocation override — options passed directly in the current prompt (e.g., "use Azure DevOps with ECR", inline @config blocks).
2. Directory mapping — directoryMapping entries in .devops-agent.json matched against the path of the file being worked on (e.g., services/api → { "language": "dotnet", "platform": "github-actions" }).
3. Auto-detection — signals derived from files present in the workspace (see section below).
4. Config defaults — top-level defaults declared in .devops-agent.json (defaults.platform, defaults.runner, defaults.registry, defaults.docker).
5. Plugin defaults — hard-coded fallbacks bundled with the core plugin.

Auto-Detection Signals

When no higher-priority source specifies a value, scan the workspace for the following signals.

Platform Detection

Signal	Resolved Platform
.github/ directory present	GitHub Actions
.github/workflows/*.yml files exist	GitHub Actions
azure-pipelines.yml present	Azure DevOps
.azuredevops/ directory present	Azure DevOps

When both GitHub Actions and Azure DevOps signals are present (monorepo case), report multi-platform detection. The agent will process platforms sequentially.

Language Detection

Language	Signals
.NET	.cs files, .csproj, .sln, global.json, Directory.Build.props
Node.js	package.json, tsconfig.json, .nvmrc, yarn.lock, pnpm-lock.yaml
Java	.java files, pom.xml, build.gradle, build.gradle.kts, mvnw
Go	.go files, go.mod, go.sum
Python	*.py files, requirements.txt, pyproject.toml, setup.py, Pipfile

When multiple language signals match, prefer the more specific signal (dedicated build file > generic source file; e.g., pom.xml > .java files).

Registry Detection

Registry	Signals
ACR	Existing azure/docker-login in workflows, azurecr.io references in any config or YAML
ECR	Existing aws-actions/amazon-ecr-login in workflows, .amazonaws.com references

Governance Enforcement

After resolving the configuration, enforce the following constraints. All checks are evaluated before any code action proceeds.

Approved Platforms

If governance.approvedPlatforms is set, verify that the resolved platform is included in the list. If not, halt with:

Platform '<resolved>' is not in approvedPlatforms. Update .devops-agent.json or contact your admin.

Approved Registries

If governance.approvedRegistries is set, verify that the resolved registry type is included in the list. If not, halt with:

Registry '<resolved>' is not in approvedRegistries. Update .devops-agent.json or contact your admin.

Approved Languages

If governance.approvedLanguages is set, verify that the resolved language is included in the list. If not, halt with:

Language '<resolved>' is not in approvedLanguages. Update .devops-agent.json or contact your admin.

Mandatory Guidelines

If governance.mandatoryGuidelines is true and no guidelines file is configured or resolvable for the active platform, halt with a blocking error:

mandatoryGuidelines is true but no guidelines file is configured for platform '<platform>'. Set guidelines path in .devops-agent.json.

Enforced LSP

If governance.enforceLsp is true and the YAML LSP server for the active platform module is not available (not installed, not running, or unreachable), halt with a blocking error:

enforceLsp is true but the YAML LSP server for '<platform>' is not available. Ensure the platform module plugin is installed and the LSP is running.

Org Policy Endpoint

If governance.orgPolicyEndpoint is configured in .devops-agent.json, fetch the org policy before resolving governance rules.

Request:

GET <orgPolicyEndpoint>
Authorization: Bearer <org-api-token>
X-Plugin-Name: devops-coding-agent
X-Plugin-Version: <current-version>

Response handling:

Condition	Behavior
Timeout or 5xx	Fail-closed. Halt with: "Cannot reach org policy endpoint. Contact your admin."
401 or 403	Halt with: "Org policy endpoint returned auth error. Check your API token configuration."
Not configured (no endpoint set)	Use .devops-agent.json governance fields only; skip this step.
200 OK	Merge returned policy over .devops-agent.json governance fields (policy wins on conflict). Cache the result for 1 hour per session.

The cache is per-session and in-memory. Re-fetch at session start or when the cache is stale (older than 1 hour).

Policy response fields (merged over local config governance when present):

{
  "approvedPlatforms": ["github-actions", "azure-devops"],
  "approvedRegistries": ["acr", "ecr"],
  "approvedLanguages": ["dotnet", "nodejs", "java", "golang", "python"],
  "mandatoryGuidelines": true,
  "enforceLsp": true,
  "pinnedVersions": {
    "devops-coding-agent": ">=1.0.0 <2.0.0",
    "devops-github-actions": ">=1.0.0"
  }
}

Output

Emit the resolved configuration as structured data before proceeding. The output includes:

{
  "platform": "<resolved-platform>",
  "language": "<resolved-language>",
  "runner": {
    "type": "self-hosted",
    "labels": ["self-hosted", "linux", "x64"],
    "pool": null
  },
  "registry": {
    "type": "acr",
    "name": "yourorg.azurecr.io",
    "loginServer": "yourorg.azurecr.io"
  },
  "docker": {
    "baseImage": null,
    "nonRootUser": true,
    "hardened": true
  },
  "stages": {
    "build": { "enabled": true, "required": true },
    "unitTest": { "enabled": true, "required": false },
    "integrationTest": { "enabled": false, "required": false },
    "sonarScan": { "enabled": true, "required": false },
    "snykScan": { "enabled": true, "required": false },
    "wizScan": { "enabled": false, "required": false },
    "dockerBuild": { "enabled": true, "required": true },
    "registryPush": { "enabled": true, "required": true }
  },
  "guidelinesFile": "<path-or-null>",
  "lspAvailable": true,
  "governance": {
    "approvedPlatforms": [],
    "approvedRegistries": [],
    "approvedLanguages": [],
    "mandatoryGuidelines": false,
    "enforceLsp": false,
    "orgPolicyEndpoint": "<url-or-null>"
  },
  "resolutionSource": {
    "platform": "<level>",
    "language": "<level>",
    "registry": "<level>",
    "runner": "<level>"
  }
}

resolutionSource records which level (per-invocation, directory-mapping, auto-detection, config-defaults, plugin-defaults) provided each resolved value, for transparency and debugging.