Projects and checks

Define a project#

A project file names repositories, setup commands, readiness checks, and orchestration guidance. It contains credential references, not secret values. Deployment and sign-in settings belong to a separate deployment file.

Example project configuration

name: export-service
revision: 1
repositories:
  - name: export-service
    url: https://github.com/example/export-service.git
    path: repo/export-service
    defaultBranch: main
    credentialRef: github-agentx-sdlc
setup:
  - cwd: repo/export-service
    executable: npm
    args: [ci]
    timeoutSeconds: 600
readiness:
  - cwd: repo/export-service
    executable: npm
    args: [test]
    timeoutSeconds: 600
orchestratorInstructions: >-
  Delegate repository reads, edits, builds, and tests
  to the remote Rovara Code worker.

Replace the example repository and credential reference with your configured project values. Use agentx admin project register --help to see the registration options for your installed version. Increase the immutable revision before changing a registered definition.

Choose the checks#

Use readiness commands for your test suite, lint, or type check. Each command has a working directory, executable, arguments, and timeout. If no readiness commands are available, the runtime can use recognized agent test commands; that gives narrower coverage.

A configured devcontainer runs shell, setup, and readiness in the prepared project environment. Adding one to a later project revision does not move an existing workspace into it.

Required and optional workflow checks#

Project readiness checks always run in Quick and Full and cannot be turned off. A project can also offer up to 20 named optional checks; the task owner chooses among them when approving the coding plan. The chosen IDs are saved with the decision, and a new plan starts with none selected.

developerTasks:
  enabled: true
  optionalWorkflowChecks:
    - id: coverage
      label: Coverage report
      command:
        cwd: repo/payments-api
        executable: npm
        args: [run, coverage]
        timeoutSeconds: 600

A check name should describe its useful coverage. Optional selection does not bypass required checks or change repository merge controls.

Starting tasks from Slack#

developerTasks.enabled controls whether developers may start tasks on the project from an AI tool or a Slack workflow. Starting from Slack also needs shared tasks (SHARED_TASKS) on for the Slack service; without them, AgentX answers every start asking an admin to turn them on.

A plain top-level mention is sorted by the classifier model chosen at agentx init. It sees a fixed instruction and the message text only, never repository content, and waits at most 4 seconds. There is no separate routing model setting. Prefixes (quick:, full:, workflow:, chat:) skip the model.

To save thread replies that do not mention AgentX, the app needs the channels:history and groups:history scopes and the message.channels and message.groups events. Existing installs must update the app from the generated manifest and reinstall it. AgentX ignores, and does not store, channel messages outside task threads.

Repositories AgentX can publish#

When AgentX runs Git itself (to read the agent’s changes or publish them), it ignores what the repository’s Git config asks Git to run:

• Git LFS repositories are not supported yet; publishing is refused when any file uses filter=lfs.
• Other filters are switched off, so an encryption filter such as git-crypt would stage plaintext. Do not register such a repository.
• Submodules checked out in the workspace, or a nested repository the agent creates, stop publication; the error names the path.
• Hooks, signing and credential helpers do not run. Pushes go to the registered URL over HTTPS only, and are refused while the repository sets other url.*, http.* or remote.* keys.

Setup and readiness commands are the project’s own code and run with the worker’s normal Git settings.

Dev container rules#

The dev container runs on the worker host’s Docker, and the agent can edit its configuration. So AgentX checks the merged configuration before each start, and the running container after, and refuses settings that reach the host:

• initializeCommand and dockerComposeFile.
• privileged, securityOpt, and added capabilities other than SYS_PTRACE.
• runArgs that share the host’s processes, network, devices or namespaces.
• Bind mounts of /, the Docker socket, the workspace root or anything outside the workspace.
• Features AgentX cannot pin to the content it checked, and builds that read outside the workspace.

Images, builds, features, lifecycle commands, environment variables, named volumes and bind mounts inside the workspace are allowed. Full dev container and publication rules →

Models, connections and access#

Models

Choose approved provider/model pairs. Worker and orchestration configuration are distinct. External providers receive model requests outside AWS. Developers can also run their own tasks on a connected ChatGPT plan when an admin allows it.

Connectors

Linear, Jira, Asana, GitHub, and remote MCP tools have configured project scopes and server-side credential handling.

Action policy

Rules allow, ask, or deny orchestrator tool calls. They do not gate every shell command or file edit on the coding worker.

Developer tasks

Project settings control whether coding-tool and Slack workflow tasks are enabled and how they may be shared into Slack.

Do not place credentials in command environment fields or project YAML. Verify scope and provider availability before enabling a connection.