Skip to content

Migrating to deploy_on_peach_v2

The checklist for moving a group's repo(s) from the previous (v1) pipe/peach-jobs-ci pipeline to pipe/peach-ray-ci's deploy_on_peach_v2.yml. What the new pipeline does and how a repo is configured day-to-day is in Setting up your repository; this page is the one-time switch.

Steps 1–5 and 7 are for the group's own owner/maintainer; step 6 is for the PEACH core team, and the two halves can run in parallel.

Prerequisites (one-time, per group)

  1. Create <group>/peach-ray — a private repo in your group, default branch main, one README commit. Tag that commit with your codops' current prod version (e.g. <codops>_v1.0.86) so v2 tag numbering continues from prod, not from v1.0.1. This repo is the generated-output home: serveconfigs, Dockerfiles and <codops>_vX.Y.Z tags land here, never in your source repo.

  2. Mint two tokens and set them as masked CI/CD variables on the app repo:

    Token Where minted Scope Becomes variable
    semantic-release the app repo api GITLAB_TOKEN
    peach-ray-write-v2 <group>/peach-ray write_repository PEACH_RAY_WRITE_TOKEN

    Developer level is enough for both — unless v* tags are protected on the app repo, in which case the semantic-release token must be Maintainer-level or it cannot push the release tag.

  3. Ask the PEACH core team for the platform CI variables on the app repo (BASIC_AUTH_SECRET, PEACH_JOBS_AWS_ACCESS_KEY_ID, PEACH_JOBS_AWS_SECRET_ACCESS_KEY, GITLAB_WEBHOOK_TOKEN, UPDOWN_API_KEY).

Repo changes (branch + MR, don't touch the default branch yet)

  1. Seed the semver baseline (repos with a Python package only): tag the default branch with the package's current version (vX.Y.Z). Safe to do at any time before the switch — the v1 pipeline runs nothing on tag pushes.

  2. The migration MR itself:

    • .gitlab-ci.yml: include pipe/peach-ray-ci / deploy_on_peach_v2.yml, set HAS_PACKAGE: "true" if the repo publishes a Python package; a local stages: replaces the template's list wholesale, so it must repeat the template's stages before adding any of its own; keep your existing lint/test jobs. See Setting up your repository.
    • pyproject.toml: hatchling + hatch-vcs, dynamic = ["version"] — the git tag becomes the version; regenerate uv.lock afterwards.
    • peach.conf: pin your package as <pkg>==LATEST_PUBLISHED_VERSION — the pipeline resolves the sentinel to the version it just published.
    • Delete all manual version-bump machinery — bump scripts, version-sync CI jobs, pre-commit hooks, docs saying "bump the version in N places". semantic-release owns versioning now; see Releasing your library with semantic commit messages.
    • Mind the two environment rules when several repos share one codops: a py_environments name (including base) is owned by exactly one repo per codops — other repos declare a named env and reference it with py_env: on their endpoints and tasks — and an env's name must not equal a package it installs (the generated uv project is named after the env, and uv rejects a project that depends on itself).

PEACH core team side

  1. Relay access for the group (one ask, done once): the group is added to the CodeBuild relay allowlist and gets a relay runner token. Without this the image-build job sits pending forever.

Cutover

  1. Merge and watch the first two pipelines: the default-branch push (validation + semantic-release cutting the first tag) and the resulting tag pipeline (publish → deploy → build → promote). Verify by artifact: the new <codops>_vX.Y.Z tag exists in <group>/peach-ray, and your dev environment runs the new image. Prod promotion stays manual — see Promotion and rollback.

    If your codops has no dev environment, set PROMOTE: "false" in the CI first — otherwise a merge deploys straight to prod.

Rollback

Steps 1–4 are safe at any time and change nothing about the running v1 pipeline; only merging step 5 flips the repo over. Reverting that MR restores v1 exactly.