need a onedev ai agent ，not onedev agent

The official docs already cover this path. A dedicated “hello world” page is not required to get a first job running. Below is the assembled copy-and-do flow, plus answers to the points that are currently split across pages.

Official starting points:

• Quickstart
• Concepts (build spec, job, trigger, executor, agent)
• Run as Docker Container
• Build Farm with Agents
• Plain Old Build (shell executor, no container)
• Understanding Pipeline

Minimal CI/CD hello world

This is the shortest path after a fresh install: no extra agent, no extra executor configuration.

1. Start OneDev with Docker access

On Linux/Mac:

docker run --name onedev -d --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/onedev:/opt/onedev \
  -p 6610:6610 -p 6611:6611 \
  1dev/server

For rootless Docker, mount $XDG_RUNTIME_DIR/docker.sock instead of /var/run/docker.sock. Production details: Run as Docker Container.

Open http://localhost:6610 and complete setup.

The docker.sock mount is for the OneDev server, so it can start job containers via the host Docker daemon. A separate build agent is not needed for this hello world.

2. Create a project and push a commit

Create a project, for example hello. From a local repo:

git remote add origin http://localhost:6610/hello
git push -u origin main

Use the administrator user/password created during setup.

3. Define the pipeline as .onedev-buildspec.yml

Pipeline definitions live in .onedev-buildspec.yml at the repository root. That is the source of truth.

You can create it either way:

1. GUI (recommended for the first job): open the project and click adding .onedev-buildspec.yml. The GUI writes/commits that YAML file.
2. Commit YAML yourself into the same file.

In the GUI:

1. Add a job, for example hello.
2. Add a Checkout Code step (needed so the working directory has the repo).
3. Add an Execute Commands step:
   • Run in container: yes
   • Image: alpine
   • Commands: echo Hello from OneDev
4. Under job triggers, add Branch update. Leave branches empty to run on every branch, or set main.
5. Save. Saving commits .onedev-buildspec.yml. With a branch-update trigger, that commit (or the next push) starts the job.

If the project looks like a typical Node/Maven/Python/… app, OneDev also suggests a default CI template. The Quickstart uses that path with a React app.

4. Verify the build

Open Builds and wait for job hello. The log should show Hello from OneDev.

If no executors are defined under Administration → Job Executors, that is expected. OneDev auto-discovers a Server Docker Executor when docker works on the server.

When do you need an agent vs built-in executors?

Executors decide where jobs run (Concepts):

For the hello-world above, do not install an agent. With OneDev started as in step 1, auto-discovered Server Docker Executor is enough.

Install agents only when you want jobs on other machines (build farm, Mac/iOS host, extra Docker hosts). Then:

1. Add an agent (Administration → Agents). For Docker agents, set serverUrl to an address the agent container can actually reach — not localhost (Build Farm with Agents).
2. Create a Remote Docker or Remote Shell executor that selects those agents.
3. If you add explicit executors, they replace auto-discovery. The first applicable enabled executor is used unless the job names one.

Server Shell Executor is useful for non-container builds, but it is not auto-discovered. Add it manually under Job Executors if you install OneDev on bare metal without Docker (Plain Old Build).

Docker permissions / docker.sock

There are two different docker.sock mounts:

1. Into the OneDev server container (required for Server Docker Executor when OneDev itself runs in Docker). That is the -v /var/run/docker.sock:/var/run/docker.sock in the install command. The OneDev process must be able to talk to the host Docker daemon.
2. Into job containers (Mount docker sock on the executor). This is off by default. Turn it on only if the job itself runs Docker (docker build, docker run, …). It is a security risk: a malicious job can take over the host Docker daemon. If you enable it, restrict the executor’s job authorization to trusted jobs.

A simple echo / npm / mvn job does not need docker.sock inside the job container. The executor starts a container from the image you specified (alpine above); your commands then run inside that image.

If image pulls fail, check that the server (or agent) can reach the registry. For HTTP/self-signed registries, see Insecure Docker Registry.

Where the pipeline lives, and how push triggers work

• File: .onedev-buildspec.yml in the repo root.
• GUI and YAML edit the same file. The GUI is just an editor that commits valid spec.
• Jobs do not run on push unless the job has a trigger.

Branch update is the push trigger. In YAML it is BranchUpdateTrigger. Options:

• Branches: empty = any branch; or e.g. main
• Touched files: optional path filter
• Applicable users: who pushed

It skips commits whose message contains [skip ci], [ci skip], [no ci], [skip job], [job skip], or [no job].

Other triggers: tag creation, pull request open/update/merge/discard, dependency job finished, cron (Concepts, Understanding Pipeline).

You can also run a job manually from a commit if you do not want a trigger yet.

Common pitfalls

1. docker.sock not mounted on the OneDev server when using Docker install → no Server Docker Executor discovered → job fails with no applicable executor.
2. Expecting an agent for the first job. Agents are for remote machines, not for “CI is enabled”.
3. Enabling mount docker sock on the executor for a job that only needs a language image. Leave it off unless the job runs Docker CLI.
4. Adding executors and then wondering why auto-discover stopped. Once any executor is defined, auto-discover is not used.
5. Agent serverUrl set to localhost. Agent containers cannot reach OneDev at http://localhost:6610. Use a host IP or DNS name the agent can open.
6. Server URL under Administration → System Setting should be a URL browsers, agents, and (when relevant) job containers can reach. localhost is fine for browsing on the same machine; it is wrong for agents on other hosts/containers.
7. Missing Checkout step. Command steps do not clone the repo for you.
8. Command step “run in container” off, while only a Docker executor is available (or the reverse: container step with only a shell executor).
9. No Branch update trigger, then pushing code and expecting a build.
10. Bare-metal OneDev without Docker, and no Server Shell Executor added manually.

Please say if this is enough to get a first job running, or if you still want a standalone hello-world page added to the official docs.

OneDev uses agent for two different products. You do not install a CI/CD agent to get an AI collaborator.

CI/CD agent is a process on a remote machine that runs build jobs. You only need it for Remote Docker / Remote Shell executors. Server Docker, Server Shell, and Kubernetes executors do not require it. See Build Farm with Agents and Concepts.

AI user (often called an AI agent) is a virtual collaborator. It can chat, implement issues, review pull requests, and run a coding agent inside a workspace. That is a different setup.

Minimal path to an AI user:

1. Create a user of type AI, pick the chat model, set entitlements (who and which projects may use it), optionally add a system prompt.
   Working with AI User

2. Grant Create Workspace on projects it should use. Grant Code Writer as well if it should implement issues and open pull requests, not only answer questions.
   Collaborate with AI User

3. Add a workspace spec from a template (for example Codex in Container). Enable task automation and set Applicable AI User for Task Automation.

4. Run as the AI user, create a workspace from that spec, sign in the coding agent, then delete the workspace so those settings are reused. For Codex, enable Sign in with Device Code in ChatGPT account settings first.

5. Chat from the UI, or assign an issue / mention the user (for example @aibot work on this issue).
   Chat with AI User
   Assign Issues to AI User

Community edition runs workspaces on the OneDev server, so an AI user does not need a CI/CD agent. Enterprise edition can also provision workspaces on agents or Kubernetes if you want to offload them.

More: AI tutorials, Workspaces, TOD CLI and skills for Cursor/Claude/Codex on your own machine.

Please confirm if this is the AI-user setup you needed, or what is still missing.

@fzkin let me know if you have unclear points following the quick start guide.

I understand the documentation you provided. Just to clarify, the suggestions above were AI‑generated. I’ve been using OneDev since version 9.0.5 and have developed numerous scripts working with its API. To be honest, tutorials are supposed to be written for humans, not for AI. In addition, many releases contain breaking changes. The .onedev‑buildspec.yml files generated by AI following the official documentation always end up with syntax errors. I’ve considered workarounds, such as asking AI to refer to source‑code examples to generate configs. But every time there is a breaking change in a new version, all of that effort has to start over from scratch. From my perspective, OneDev is capable of doing a great many things. However, configurations require repeated manual verification. It no longer fits the current era, where we expect documentation clear enough for AI to fully take over project‑level CI configuration.

Understood. The earlier comment assembled existing pages so a first job can be run; it is not a human-written official tutorial, and it does not replace one.

The YAML failures are expected if an AI copies tutorial snippets. Docs explain the model (jobs, steps, triggers); they are not a versioned schema. The spec format has a version field and changes across releases, so examples that were valid on an older server fail on a newer one.

For a spec that matches the server you are running:

• Edit .onedev-buildspec.yml in the project GUI and save. OneDev writes YAML for that version.
• Or have the AI use the live schema: tod build get-spec-schema, then tod build check-spec (validates and upgrades). See Working with CLI and Skills.

That still requires a schema/tool pass. It does not meet the bar of documentation that is complete and stable enough for an AI to own project CI from the docs alone.

@robin please take this from here: official human-maintained CI tutorial plus docs/examples kept aligned with the current spec schema so generated YAML stays valid across releases.

To be honest, tutorials are supposed to be written for humans, not for AI. In addition, many releases contain breaking changes.

I am confused, which tutorial are you referring to. Most tutorials there are written manually. Also for most of the CI/CD spec changes across releases, they will be migrated automatically. Can you cite some example?

Just to clarify, the suggestions above were AI‑generated

Yes servicedesk is a AI user, and it proves to be very helpful answering community user questions (and even better than me many times).

I understand. I’m just clarifying that the entire content of my first‑raised issue was AI‑generated. I am not complaining or confused about AI‑generated outputs themselves. To give you a simple example: if I use a plain‑chat Codex‑style assistant and ask it to maintain a local OneDev instance, with the goal of setting up built‑in CI/CD to deploy and keep the service running locally long‑term, you can clearly see how helpless the AI becomes when trying to work from OneDev’s documentation.