Project Configuration

Repositories can configure agentic-ci behavior by placing files in a .agentic-ci/ directory at the repository root.

File	Purpose
config.yml	General project configuration (setup steps, etc.)
openshell-policy.yml	Additional network endpoints for the OpenShell sandbox

Setup Steps

Setup steps are commands that run on the host before the workdir is uploaded into the sandbox. They execute with full network access, making them ideal for dependency installation that the sandboxed agent cannot perform itself.

This is primarily useful for the OpenShell backend, where the sandbox restricts network access to a small set of allowed endpoints (GitHub, GitLab, Vertex AI, etc.) and does not permit general-purpose package registry access. The Podman and Local backends already have full network access, so setup steps are not needed there.

Configuration

Add a setup key to .agentic-ci/config.yml:

# .agentic-ci/config.yml
setup:
  - name: Install dependencies
    run: npm ci
  - name: Build project
    run: npm run build

Both object form and bare-string shorthand are supported:

# Object form (recommended for clarity)
setup:
  - name: Install dependencies
    run: npm ci

# Bare-string shorthand
setup:
  - npm ci

Each step object accepts:

Field	Required	Description
run	yes	Shell command to execute
name	no	Human-readable label for log output

How It Works

1. The sandbox is created and the network policy is applied
2. Setup steps run sequentially on the host in the workdir
3. The workdir (now including setup step outputs like node_modules/) is uploaded into the sandbox
4. The agent starts inside the sandbox

Host (internet access)          Sandbox (isolated)
─────────────────────           ──────────────────
1. sandbox.create()
2. npm ci  ─────────────┐
   (setup step)         │
3. sandbox.upload() ────┼──→  /sandbox/repo/
                        │     ├── node_modules/  ✓
                        │     ├── src/
                        │     └── ...
4.                      └──→  agent starts

Behavior

• Steps run with shell=True, so pipes, redirects, and shell builtins work as expected.
• Steps run sequentially in the order they appear in the config.
• If a step fails (non-zero exit code), the run aborts with an error.
• Each step has a 10-minute timeout to prevent hanging commands from blocking CI indefinitely.
• Malformed entries (e.g. missing run key, non-string run value) are skipped with a warning.
• Set AGENTIC_CI_SKIP_SETUP=1 to skip all setup steps (useful for lightweight jobs like triage that don't need dependencies).

Example: Node.js Project

# .agentic-ci/config.yml
setup:
  - name: Install dependencies
    run: npm ci

This ensures node_modules/ is present inside the sandbox so the agent can run tests, linting, and type checks without needing general internet access.

Network Policy (OpenShell)

Projects can declare additional network endpoints for the OpenShell sandbox in .agentic-ci/openshell-policy.yml. These are merged with the built-in defaults (duplicates are ignored).

# .agentic-ci/openshell-policy.yml
endpoints:
  - "redhat.atlassian.net:443:read-only"
  - "*.example.com:443:full"

Each endpoint uses the format host:port:access where access is one of full, read-only, or read-write.

The --policy CLI flag takes precedence: if a flag path is provided and the file exists, the repo-level file is ignored.

See OpenShell Backend for the full list of built-in default endpoints.