feat: add plan metadata flags for title and description with validation - #20705

Thank you for your pull request and welcome to our community. We could not parse the GitHub identity of the following contributors: vuchumanh.
This is most likely caused by a git client misconfiguration; please make sure to:

1. check if your git client is configured with an email to sign commits git config --list | grep email
2. If not, set it up using git config --global user.email email@example.com
3. Make sure that the git commit email is configured in your GitHub account settings, see https://github.com/settings/emails

We require contributors to sign our Contributor License Agreement, and we don't have yours on file. In order for us to review and merge your code, please sign CLA and add your name to contributors list.

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Hi @manhvu1997 . Thanks for the PR.

Before we review the implementation in detail, could you share the use case that motivated this? From the diff, the main functional change seems to be allowing bytebase-action rollout to set a custom plan title and description instead of using the generated release ID as the title.

It would help to understand the workflow you’re trying to support. For example, are you trying to map Bytebase plans back to GitHub PRs, CI build metadata, change tickets, release notes, or some internal approval process?

A concrete example of the GitHub Actions usage and what you expect to see in Bytebase would help us decide whether these should be first-class action flags, whether the flag names/defaults are right, and whether we need to support things like multiline descriptions or templated values.

Thank @RainbowDashy for the feedback.

The motivation is to make plans created by bytebase-action more self-descriptive.

Today, when a rollout is created via the action, the generated plan uses the release ID as its title (e.g. release_20260628-RC01) and doesn't have a description. As a result, when looking at the Plans page, it's difficult to understand the purpose of a plan without opening it or tracing it back to the CI pipeline.

For example, this is what I see:

Title: release_20260628-RC01
Description: (empty)

In practice, I'd like to populate these fields with meaningful information from our CI/CD pipeline, for example:

Title

Add customer_status column to users

Description

GitHub PR: #1234
Commit: abc1234
Release: release_20260628-RC01
Change request: CR-2026-0158

This makes it much easier for operators and DBAs to identify what a rollout (created by bytebase-action) is doing directly from the Bytebase UI, without having to inspect the SQL or correlate the release ID with external systems.

I intentionally made both flags optional:

--plan-title defaults to the current behavior (the release ID), so there is no breaking change.
--plan-description is optional and simply provides additional context when available.

My primary use case is improving the readability and traceability of plans created by bytebase-action, although the same metadata can also be used to reference PRs, CI builds, release information, or internal change tickets if desired.

Thanks, that context helps. The use case makes sense: even in GitOps, Bytebase is still the control plane for operators/DBAs to monitor, approve, troubleshoot, and audit rollouts, so the generated release_... title is not very scannable on the Plans page.

I think the product requirement here is traceability from a Bytebase plan/rollout back to the GitOps source: PR/MR, commit, CI run, release ID, and optionally an internal change ticket.

One thing I want to think through before accepting this exact API is whether free-form --plan-title / --plan-description is the right long-term surface, or whether this metadata should be modeled closer to the GitOps release/VCS source and then propagated/rendered on the plan/rollout. The latter may give us more consistent behavior across GitHub/GitLab/Bitbucket/Azure and avoid every CI workflow inventing its own description format.

For this PR, could you share the exact GitHub Actions snippet you plan to use, including how you would populate the title and description? That will help us evaluate whether these flags are sufficient, whether multiline values work well in practice, and whether we should instead expose more structured GitOps metadata.

Currently I'm using GitLab CI instead of GitHub Actions so I can share the equivalent GitLab workflow snippet.
In my workflow developers do not manually pass free-form values in CI. They use a script to generate the SQL migration file. This script asks for a title and description then writes them as comments at the top of the SQL file.
During CI another script parses those comments. Maps them to --plan-title and --plan-description.
We also add details to the description with GitLab metadata, such as the merge request author.
Later we can add information like MR IID and title commit SHA, pipeline URL release ID and internal ticket if needed.
Example SQL:

-- plan-title: Add email column to users
-- plan-description: Support email-based notification and account recovery flows.

Example GitLab CI usage:

bytebase-action rollout
--pattern-file "$RELEASE_FILE"
--plan-title "$(cat "$OUT.title")"
--plan-description "$(cat "$OUT.desc")"

Where "$OUT.desc" is generated from the SQL comment plus GitLab CI context for example:
Description from SQL migration.

• Merge Request Author: ${CI_MERGE_REQUEST_AUTHOR_USERNAME}
• Merge Request: !${CI_MERGE_REQUEST_IID}

I agree that structured GitOps metadata may be a long-term solution across GitHub, GitLab, Bitbucket and Azure.
For this PR my goal is to make the current GitOps-generated plans more readable and traceable with change to the developer workflow using GitLab CI and GitLab metadata.