Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (96 loc) · 5.99 KB

AGENTS.md

File metadata and controls

135 lines (96 loc) · 5.99 KB
Raw

Agents Guide

This document explains the OADP rebase system for AI agents working in this repository.

What This Repo Does

OADP maintains downstream forks of the Velero backup/restore ecosystem for OpenShift. Each fork carries downstream-only patches on top of upstream releases. This repository automates the process of rebasing those forks onto new upstream versions while preserving all downstream patches.

The rebase process is orchestrated by rebasebot, a tool that cherry-picks downstream commits onto new upstream base tags. This repo provides the configuration, hook scripts, and CI automation around rebasebot.

Architecture

Data Flow

versions/oadp-1.X.env          (SSOT: upstream tags, SHAs)
        │
        ├─→ rebase-configs/     (what to rebase, which hooks to run)
        ├─→ verify-tag-sha_*.sh (generated: supply chain verification)
        └─→ docs/version-matrix.md (generated: reference tables)

run-oadp-rebase.sh
        │
        ├─→ load_config()      (sources versions file, then config file)
        ├─→ get_wave_repos()   (returns repos for a branch + wave number)
        └─→ rebasebot          (container or CLI, runs hooks)

Versions Files

Each OADP release has a versions/oadp-1.X.env with upstream tags:

OADP_BRANCH="oadp-1.6"
VELERO_UPSTREAM_TAG="v1.18.2-rc.2"
VELERO_TAG_SHA="c253c7fe37d78c9b7e55c68544f7c5b2608712d8"
KOPIA_UPSTREAM_TAG="v0.22.3-velero-patch"
AWS_PLUGIN_TAG="v1.14.1"
GCP_PLUGIN_TAG="v1.14.1"
AZURE_PLUGIN_TAG="v1.14.1"
KUBEVIRT_PLUGIN_TAG="v0.9.0"

Configs reference these via ${VELERO_UPSTREAM_TAG:?...} — the :? guard fails fast if the variable is missing.

Config Files

rebase-configs/org_repo_branch.env.sh — shell scripts sourced by run-oadp-rebase.sh. They set:

  • SOURCE_UPSTREAM_REPO — upstream org/repo:tag
  • DESTINATION_DOWNSTREAM_REPO — downstream org/repo:branch
  • REBASE_REPO — working fork for PRs
  • HOOK_SCRIPTS — post-rebase hooks to run
  • SKIP_REPO — set to "true" to skip (e.g., restic)

Downstream-only repos (oadp-operator, openshift-velero-plugin, etc.) set source == dest as a hack to trigger hooks without rebasing.

Hook Scripts

rebasebot-hook-scripts/*.sh — run inside the rebasebot container after cherry-picking. Common hooks:

Hook Purpose
go-replace_velero_oadp-1.X.sh Point go.mod at downstream velero fork
go-replace_kopia_oadp-1.X.sh Point go.mod at downstream kopia fork
go-mod-tidy-and-commit.sh Run go mod tidy + go vet (shared, not version-specific)
restic-submodule-and-commit_oadp-1.X.sh Sync restic git submodule
velero-submodule-and-commit_oadp-1.X.sh Sync velero git submodule (for must-gather)
kopia-submodule-and-commit_oadp-1.X.sh Sync kopia git submodule (for must-gather)
normalize-dockerfiles-and-commit.sh Strip Go patch versions in Dockerfiles (shared)
verify-tag-sha_oadp-1.X.sh Generated — verify upstream tag wasn't recreated
oadp-operator-copy-crds-from-velero-and-commit_oadp-1.X.sh Copy CRDs from velero fork
go-use-tag_oadp-operator_oadp-1.X.sh Pin oadp-operator module to branch
go-use-tag_oadp-non-admin_oadp-1.X.sh Pin oadp-non-admin module to branch

Version-specific hooks differ only in their branch name variable. The go-replace_velero hooks for 1.3/1.4 omit the KCP workaround that 1.6 includes.

Wave System

Repos must rebase in order because of dependency chains:

Wave Purpose Examples
1 Independent deps kopia, restic
2 Core velero
3 Plugins + operator velero-plugin-for-aws, oadp-operator
4 Downstream controllers oadp-non-admin, openshift-velero-plugin
5 Final dependents oadp-must-gather, oadp-cli

Wave composition varies by OADP version — not all repos exist for all versions. See docs/version-matrix.md for the full matrix.

Generated Files

These files are generated from the SSOT and must never be edited by hand:

  • rebasebot-hook-scripts/verify-tag-sha_oadp-1.*.sh — generated by tools/generate-verify-tag-sha.sh
  • docs/version-matrix.md — generated by tools/generate-version-matrix.sh

Run make generate to regenerate. Run make verify-generate to check they're up to date.

How To

Update an upstream tag

Edit versions/oadp-1.X.env, run make generate && make test, commit.

Add configs for a new OADP version

  1. Create versions/oadp-1.X.env
  2. Create hook scripts (copy nearest version, change branch name)
  3. Create config files referencing SSOT variables
  4. Add mappings in get_config_name() and waves in get_wave_repos() in run-oadp-rebase.sh
  5. make generate && make test

Test a config

./run-oadp-rebase.sh -t velero-oadp-1.6           # loads config, prints details
./run-oadp-rebase.sh --dry-run --local-hooks \
  --working-dir ~/workdir -s ~/.rebasebot/secrets \
  velero-oadp-1.6                                   # full dry-run with rebasebot

Run the full validation suite

make test    # syntax-check + config-load + verify-hooks + verify-generate

Important Patterns

  • Configs are shell scripts sourced in the context of run-oadp-rebase.sh. They can use variables set by the versions file because load_config() sources the versions file first.
  • The Go tool (tools/rebase-status/) also parses configs. Its parseConfigFileToData merges versions file variables before expanding config variables. If the SSOT schema changes, update registry.go too.
  • resolve-config.sh is used by the auto-rebase pipeline independently of run-oadp-rebase.sh. It also sources the versions file before the config.
  • Remote vs local hooks: In container mode, hooks are fetched from git or mounted from ./rebasebot-hook-scripts/. They run inside the container with no access to the repo root — this is why verify-tag-sha hooks have the SHA baked in rather than reading from the versions file at runtime.