TiDB Operator(v2) Development Guide

November 20, 2025 ยท View on GitHub

Prerequisites

Please install Go 1.23.x. If you want to run TiDB Operator locally, please also install the latest version of Docker.

Workflow

Step 1: Fork TiDB Operator on GitHub

Visit TiDB Operator

Click Fork button (top right) to establish a cloud-based fork.

Step 2: Clone fork to local machine

Define a local working directory:

working_dir=$GOPATH/src/github.com/pingcap

Set user to match your github profile name:

user={your github profile name}

Create your clone:

mkdir -p $working_dir
cd $working_dir
git clone git@github.com:$user/tidb-operator.git

Set your clone to track upstream repository.

cd $working_dir/tidb-operator
git remote add upstream https://github.com/pingcap/tidb-operator

Since you don't have write access to the upstream repository, you need to disable pushing to upstream master:

git remote set-url --push upstream no_push
git remote -v

The output should look like:

origin    git@github.com:$(user)/tidb-operator.git (fetch)
origin    git@github.com:$(user)/tidb-operator.git (push)
upstream  https://github.com/pingcap/tidb-operator (fetch)
upstream  no_push (push)

Step 3: Branch

Get your local master up to date:

cd $working_dir/tidb-operator
git fetch upstream
git checkout v2
git rebase upstream/v2

Branch from v2:

git checkout -b myfeature

Step 4: Develop

Edit the code

You can now edit the code on the myfeature branch.

Genearate and check

Sometimes you may have to re-generate code by the following commands. If you don't know whether you need to run it, just run it.

make generate

Run following commands to check your code change.

make check

This will show errors if your code change does not pass checks (e.g. unit, lint). Please fix them before submitting the PR.

Start TiDB Operator locally and do manual tests

At first, you must have Docker installed and running.

We use kind to start a Kubernetes cluster locally.

Run following commands to run e2e

make e2e

We use Ginkgo to write our e2e cases, So you can run a specified case by following commands

GINKGO_OPTS='--focus "regexp of case"' make e2e

You can also skip preparing e2e environment and run e2e directly by following commands

GINKGO_OPTS='--focus "regexp of case"' make e2e/run

You can see logs of operator by following commands

make logs/operator

And if you have some changes but just want to update operator, you can

make push && make reload/operator

You can also deploy and re-deploy manifests by

make deploy

Step 5: Keep your branch in sync

While on your myfeature branch, run the following commands:

git fetch upstream
git rebase upstream/v2

Step 6: Commit

Before you commit, make sure that all checks are passed:

make check

Then commit your changes.

git commit

Likely you'll go back and edit/build/test some more than commit --amend in a few cycles.

Step 7: Push

When your commit is ready for review (or just to establish an offsite backup of your work), push your branch to your fork on github.com:

git push origin myfeature

Step 8: Create a pull request

  1. Visit your fork at https://github.com/$user/tidb-operator (replace $user obviously).
  2. Click the Compare & pull request button next to your myfeature branch.
  3. Edit the description of the pull request to match your change, and if your pull request introduce a user-facing change, a release note is required.

Step 9: Get a code review

Once your pull request has been opened, it will be assigned to at least two reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Commit changes made in response to review comments to the same branch on your fork.

Very small PRs are easy to review. Very large PRs are very difficult to review.

Developer Docs

If you hope to submit a new feature, please see RFCs Template