Code & Execution
By the end of this page you will have the configurations a coding agent needs, and know which tool setting each one connects to.
Prerequisites
- Developer Developer role or above.
- A connected executor, for the recommended setup — see Remote Executors.
- An agent with code tools attached — see Built-in tools.
What these five are for
Agents that work on a repository need rules: where to put the working copy, what they may touch, how to build it, what counts as done. Those rules live here rather than in each agent, so one change applies everywhere.
| Configuration | What it answers | How many you need |
|---|---|---|
| Code Workspace | Where the working copy lives, on what branch, and what an agent may touch | One per project |
| Code Toolchain | How this repository builds and tests | One per repository |
| Command Sandbox | How commands run, and which are permitted | One per project |
| Code Quality Gate | Your definition of done | One per project, often one for the whole organisation |
| Specification Standards | What a good requirement or plan looks like here | One per project, often one for the whole organisation |
Only Code Toolchain is genuinely per-repository. Two .NET services with the same build command can share one; a .NET service and a React app cannot.
Your git credential is not in this category. The Azure DevOps and GitHub credentials your agents use to clone, push and open pull requests are Integrations, because they are credentials rather than policy. Setting up a coding agent means visiting two categories: Code & Execution for the five below, and Integrations for the credential.
The fastest working setup
Three configurations get you running. The other two can be created untouched and tightened later.
Create a Command Sandbox and turn execution on
Execution backend starts as Disabled, which means nothing runs. Set it to remote_executor to run commands on your own executor. Leave everything else at its default.
Create a Code Workspace
Accept every default. The defaults clone into your executor, work on main, prefix agent branches with agent/, and refuse to touch main, master, develop or release/*.
Create a Code Toolchain for the repository
Set Stack, Build command, Test command and Test report path. Those four make build and test results useful rather than raw text.
Create the Quality Gate and Specification Standards
Both work entirely from their defaults. Create them now so the tools have something to bind to, and adjust later.
Code Workspace
Where an agent’s copy of a repository lives, and what it may do to the files.
| Field | Default | What it does |
|---|---|---|
| Where the working copy lives | executor | executor = on your own qRemoteX, with your SDKs and your network. managed = a volume inside qRaptor. local = a plain directory, development only. This also decides where the tools run — with executor, every file, git and build call goes to your executor, so if none is online those calls fail. |
| Pinned executor | blank | Pins every operation to one machine. Leave blank and the first clone picks one. Set it when a project has several repositories — see below. |
| Default branch | main | Cloned and checked out when nothing names a branch. |
| Agent branch prefix | agent/ | Prepended to every branch an agent creates, so agent work is identifiable at a glance. |
| Protected branches | main, master, develop, release/* | Agents can never commit or push to these. Refused deterministically, not merely discouraged. Globs allowed. |
| How agents deliver work | branch_only | branch_only = push to a branch. pull_request_only = never push directly, always open a pull request. any = no restriction. |
| Allowed git hosts | dev.azure.com, visualstudio.com, github.com | A clone URL on any other host is refused. Trim to yours; add an on-premises host if you have one. |
| Protected files | .env, **/*.pem, **/*.key, **/*.p12, secrets/**, **/appsettings.*.json | Never readable or writable by an agent, whatever it asks. Add your own secret locations — this is the main thing standing between an agent and your credentials. |
| Ignored paths | node_modules/**, bin/**, obj/**, dist/**, build/**, .git/**, **/*.lock | Skipped when listing, searching and measuring. Add your own build output. |
| Clone depth · Maximum repository size · Maximum file count · Maximum single-file size | 1 · 2048 MB · 20000 · 1 MB | Limits on what may be cloned and read. Raise Clone depth to 0 for full history, which git blame and some release tooling need. |
| Project repositories | empty | Declare the project’s repositories once, so an agent never has to be told a URL. See below. |
Leaving a tool’s workspace setting empty does not fail — it quietly uses platform defaults. Your protected branches and protected files are then not applied. Bind this configuration on every code tool, even when the defaults look right. See Binding them to tools.
Project repositories
Declare the repositories that make up the project and an agent can open one by name, or open all of them at once:
[
{ "name": "api", "url": "https://dev.azure.com/Org/Project/_git/payments-api", "default_branch": "main" },
{ "name": "web", "url": "https://dev.azure.com/Org/Project/_git/payments-web", "default_branch": "develop" }
]name and url are required; default_branch falls back to the Default branch above. A malformed entry is skipped rather than failing the others, and every URL is still checked against Allowed git hosts.
This list is also the only place the pull request tool can learn a repository’s URL when the working copy lives on an executor.
Set a Pinned executor when you use several repositories. With more than one open there is no single “current” workspace, so a later build can be routed to a machine that has no working copy.
Code Toolchain
How one repository builds and tests. This is what makes any technology work without a platform change — dotnet build, npm run build, mvn package and an in-house script are all the same code path.
| Field | What it does |
|---|---|
| Stack | dotnet, node, python, java, go, rust, php, ruby or other. Picks the output parsers, so build errors come back as structured findings rather than raw text, and infers a command when none is set. |
| Build command · Test command | e.g. dotnet build --nologo -c Release and dotnet test --logger trx. Leave blank to accept a stack default. |
| Restore / install command | e.g. dotnet restore. Runs before build and test. Blank by default on purpose — a build tool must not install packages nobody asked it to install. |
| Test report path | A .trx or JUnit XML file. Set this. It is read as ground truth for pass/fail counts, which beats scraping output. |
| Coverage report path | Needed before the quality gate’s coverage check can measure anything. |
| Working directory | When the buildable project is not at the repository root. |
| Lint command · Type-check command · Security scan command | Optional. Leave one blank and its tool returns a refusal saying so — and its quality gate check is skipped. |
| Environment variables | Extra variables for every command. Never secrets — bind those on the tool. |
| Required executor labels | e.g. {"dotnet": "8.0"}. Matched against an executor’s labels, so a .NET build never lands on a Node-only machine. |
| Build timeout · Test timeout | Raise for a cold restore or a slow integration suite. |
Required executor labels cannot steer the clone, only the build, test and command tools. To make sure the first clone lands on the right machine, also set Pinned executor on the Code Workspace.
Command Sandbox
How commands actually run, and which are permitted.
Execution backend starts as Disabled. Until you change it, every build, test and command is refused with “Command execution is not configured for this project”. This is the single most common setup mistake, and nothing else on this page matters until it is fixed.
| Field | Default | What it does |
|---|---|---|
| Execution backend | disabled | remote_executor = your own executor, which has your SDKs (recommended). in_process = inside qRaptor, Python only. disabled = nothing runs. |
| Which commands are permitted | curated_plus | curated = the built-in list only. curated_plus = the built-in list plus anything you add. unrestricted = any command, and only on your own remote executor. |
| Additional allowed commands | the built-in list | Executable names only, no arguments — ["make", "docker", "terraform"]. With curated_plus these are added to the built-ins, not instead of them. |
| Blocked patterns | rm -rf /, rm -rf ~, sudo , chmod 777, mkfs, /etc/shadow | Refused anywhere in a command, whatever the policy above. unrestricted is not unguarded. |
| Maximum execution time | 600 s | Raise for real builds. A cold .NET restore can exceed ten minutes. |
| Maximum captured output | 262144 bytes | Longer output is truncated from the middle, keeping the head and tail where the errors are. |
Code Quality Gate
Your definition of done, applied as one verdict. Every field has a working default, so you can create this with no changes at all.
| Field | Default | What it does |
|---|---|---|
| Build must pass | on | |
| Tests must run | on | |
| Maximum failing tests | 0 | Raise only for known failures you have consciously accepted. |
| Minimum coverage (%) | 0 | 0 disables the check. Needs a Coverage report path on the toolchain to measure anything. |
| Maximum lint errors · Maximum type errors · Maximum high-severity findings | 0 | Each applies only when the toolchain declares the matching command. |
Checks are derived, not listed. A check runs when the toolchain has a command for it. There is no “which checks” field, because asking for a lint check with no lint command could only ever be a mistake.
Specification Standards
What a good requirement, plan or test specification looks like in your organisation. Drives the specification validator.
| Field | Default | What it does |
|---|---|---|
| Required sections | title, summary, acceptance_criteria | Top-level sections a document must contain. One missing and the document is refused, with the finding naming which. Add risks, rollback, whatever your process needs. |
| Minimum acceptance criteria | 1 | Raise to stop an agent writing a plan nobody can verify. Three is a reasonable floor. |
| Require traceability | off | Every item must cite the requirement it satisfies. |
| Maximum document size | 262144 bytes | Specifications are held in shared context, which is bounded. |
Only mechanically checkable rules belong here. “No ambiguous wording” is a judgement, and belongs in a reviewing agent’s instructions — a substring match on “fast” flags “fast-forward merge” and misses “should feel responsive”.
Binding them to tools
Creating a configuration does not connect it to anything. Each code tool has settings that point at one — a workspace, a sandbox, a toolchain, a quality gate, a specification standard — and you choose it per tool, from a dropdown.
The dropdown only lists configurations of the right kind, so you cannot bind a toolchain where a sandbox belongs. An empty dropdown means you have not created a configuration of that kind yet.
The git credential works the same way, on the tool’s token setting — but it comes from Integrations, not from this category. See Configuration & secrets.
Common issues
- “Command execution is not configured for this project” — The Command Sandbox’s Execution backend is still
Disabled. - “No build command is configured for this project” — No toolchain is bound to that tool, or the toolchain has no Build command and its stack has no default.
- Your protected branches and protected files are ignored — The workspace configuration is not bound on that tool. It does not fail; it falls back to platform defaults.
- A tool’s configuration dropdown is empty — No configuration of that kind exists yet. Create it first.
- You cannot find your access token under Code & Execution — It is an Integration. Create an Azure DevOps or GitHub configuration there.
- A build runs on a machine with no working copy — Several repositories are open and no executor is pinned. Set Pinned executor on the Code Workspace.
- Nothing happens, and no error names a configuration — Check an executor is actually online. With Where the working copy lives set to
executor, every file, git and build call depends on one.