# Prepare a Repository for Gridly

Give this document to an agent working in the repository you want to connect
to an existing Gridly installation.

Use this request in the target repository:

> Read https://openforge-gridly.pages.dev/repository-setup-guide.md and help me
> prepare this repository for Gridly. First inspect the project and discuss the
> setup choices with me.

This guide prepares one repository. It does not install Gridly or change the
existing Gridly server and worker hosts.

## Runtime

- The Gridly server reads GitLab issues and queues jobs.
- A Gridly runner takes jobs and starts development containers.
- OpenCode and the project's tools run inside those containers.
- The development container does not contain the Gridly binary.

## 1. Inspect the Project

Read the project instructions, dependency files, CI files, container files,
and existing Gridly files. Find the language versions, install/build/test
commands, required services, and delivery rules.

Report what you found. Ask only for missing decisions:

- GitLab project URL, project path, and default branch.
- Existing Gridly server version and whether it supports repository discovery.
- Development image name and registry, or whether a new image is needed.
- OpenCode model and agent.
- Labels, branch rules, and merge request rules.
- Required container env names and non-secret values, host file/directory mounts,
  and read-only or writable access. Confirm Gridly v0.8.3 support with the operator.

Ask for credential names and how they are supplied. Never read secret files or
put credential values in the repository or image.

## 2. Prepare the Development Image

Reuse the existing project image when it already contains:

- OpenCode.
- Git and basic shell tools.
- The project's runtime, package manager, build tools, and tests.

Otherwise create and publish a project image using the project's normal
container process. The image must be available to the existing Gridly runner.
It must not contain the Gridly server or Gridly runner.

Run OpenCode and the project's selected tests in the image before using its
tag in the Gridly configuration.

## 3. Add the Workflow

Use the configuration path supported by the existing server:

- If repository discovery is supported, add `.gridly-project.yaml` to the
  GitLab default branch.
- Otherwise, give the workflow settings to the operator so they can add them
  to the existing server configuration.

For discovery, use the deployed server's documented schema with
`main_label`, `labels`, and `jobs`.

The workflow needs:

- An analysis job matching `todo`.
- An implementation job matching both `gridly:ready` and `gridly:execute`.
- The project image, model, agent, prompt, and timeout for each job.
- A prompt that ends with a plain `RESULT:` line.
- Optional `init` commands when the job needs source code or other setup.

Use the project's real test command and delivery rules. Replace all example
values with the choices agreed with the user.

The worker provides an empty workspace for each run. Add `init` to a job if
the project needs code before OpenCode starts. Commands run in order inside
the development container (or on the worker host for host jobs). For example:

```yaml
    init:
      - "git clone https://gitlab.com/group/project.git ."
```

This behavior is unreleased. Check that the server and worker versions support
`init` before using it in a deployed project.

### Optional Container Environment and Mounts

With Gridly v0.8.3 or newer, add `envs` and `mounts` under `jobs.<name>` in
`.gridly-project.yaml` (or the legacy server job profile). These are job settings,
not Helm server volumes or worker daemon settings:

```yaml
    envs:
      - "APP_ENV=development"
      - "TASK_ISSUE={{ issue.iid }}"
    mounts:
      - type: bind
        source: /srv/gridly/config/app.yaml
        target: /etc/myapp/app.yaml
        read_only: true
      - type: bind
        source: /srv/gridly/cache
        target: /opt/cache
```

**Mounts:** `type: bind`, `source`, and `target` are required. Sources are existing
files or directories on the Docker/Podman host; targets are paths in the container.
Both paths must be absolute and literal, without `~`, variables, or templates.
Missing sources fail the start instead of being created. `read_only` defaults
to `false`; concurrent jobs share writable sources.

The operator must provide accessible sources on every eligible worker, including
VM sharing when needed. Do not create host paths as part of repository setup.
Avoid duplicate or nested targets and conflicts with Gridly's workspace, masked
files, and SSH mount. Only bind mounts are supported, not named volumes or tmpfs.

**Environment:** use `envs` as a list of `KEY=value` strings. Keys must match
`[A-Za-z_][A-Za-z0-9_]*`; bare names do not import values from the host.
Values support issue templates, empty values, and additional `=` characters.
The last duplicate wins and overrides the image value. Gridly-owned variables,
such as `GRIDLY_RUN_ID`, `HOME`, and `OPENCODE_PORT`, ignore job overrides;
use job `agent` and `model` fields for those settings.

Explicit envs reach OpenCode and its tools. The Gridly worker on the host sends
the job to OpenCode in the container through its HTTP API. The image needs
OpenCode, not a Gridly binary. Confirm that the server and worker node are
updated. The HTTP-controlled container runtime is unreleased. Settings apply to new runs and debug
containers, not existing containers or already queued jobs.

See the [complete project example](https://gitlab.com/openforge/gridly-scheduler/-/blob/main/example/gridly-project.yaml)
and [technical contract](https://gitlab.com/openforge/gridly-scheduler/-/blob/main/docs/spec_container-mounts-env.md)
for the full reserved-name list and path validation rules.

## 4. Labels and First Issue

Create or reuse the labels configured by the existing Gridly server. The
default flow is:

1. Add `gridly` and `todo` to request analysis.
2. Review the analysis and wait for `gridly:ready`.
3. Add `gridly:execute` to approve implementation.
4. Check the final `gridly:done` or `gridly:failed` status.

The operator should create missing labels in the target GitLab project and
confirm that the server uses the same names.

Use one small test issue with clear acceptance criteria. Confirm that analysis
runs, the issue receives a useful comment, and implementation starts only after
the explicit approval label is added.

If the jobs use mounts or envs, also verify file/directory access, the intended
read-only or writable behavior, and one non-secret variable inside an OpenCode tool.

## 5. Handoff

Finish with a short report containing:

- Changed files.
- Image, model, and workflow selected.
- Tests and image checks that actually ran.
- Operator steps still needed.
- Required host paths, permissions, and server/worker version updates, if any.
- Any remaining blocker.