edit-build-spec

name	edit-build-spec
description	Author or update `.onedev-buildspec.yml` for OneDev CI/CD. Use when the user asks to create, configure, or modify a OneDev build spec.

Edit OneDev CI/CD spec

Author or update .onedev-buildspec.yml for the current OneDev project.

Prerequisites

• tod is installed and configured.
• The current directory is the project root where .onedev-buildspec.yml belongs.

Workflow

1. Fetch the spec schema first. Before editing anything, get the authoritative spec schema so the generated YAML matches the server's expectations:

   tod build get-spec-schema
   

2. If a CI/CD spec already exists, validate and upgrade it first:

   tod build check-spec
   

   This both validates and upgrades the file to the latest version when needed.
3. Inspect the project. Read the files you need (package manifests, language version files, Dockerfiles, etc.) to understand what image and commands the job should use.
4. Edit .onedev-buildspec.yml applying the user's instruction and the rules below.
5. Validate again after editing:

   tod build check-spec
   

   Keep iterating until tod build check-spec succeeds.

Authoring rules

When writing or modifying .onedev-buildspec.yml:

1. A checkout step is generally needed to clone repository into job working directory
2. Always call tod build get-spec-schema first so the YAML you produce matches the spec schema.
3. If a command step is used, enable "run in container" unless the user explicitly asks otherwise.
4. Different steps run in isolated environments and only share the job working directory. Installing dependencies in one step and running commands that rely on them in another will not work. Keep them in a single step unless the user explicitly wants them separated.
5. If a cache step is used:
   1. Place it before the step that builds or tests the project.
   2. If the project has lock files (package.json, pom.xml, etc.):
      1. Configure checksum files using these lock files.
      2. Configure the upload strategy as UPLOAD_IF_NOT_HIT.
6. To pass files between jobs, have the producing job publish them with the publish-artifact step, and let consuming jobs pull them in via a job dependency.
7. Call tod build check-spec before editing an existing CI/CD spec to make sure it is valid and up to date.
8. Inspect the relevant project files to decide which docker image and commands to use when the user asks you to set up build or test steps.
9. Call tod build check-spec again after editing so the final spec is confirmed valid.