autogits/workflow-pr

Workflow-PR bot

Keeps ProjectGit PRs in-sync with the relative PackageGit PRs.

Target Usage

Any project (devel, codestream, product, etc.) that accepts PRs.

Main Tasks

• Synchronization:

  • When a PackageGit PR is created for a package on a specific project branch, a corresponding PR is automatically generated in ProjectGit.
  • When a PackageGit PR is updated, the corresponding PR against the ProjectGit is updated.
  • A link to the PackageGit PR is stored in the body of the ProjectGit PR comments in the following format:
    • PR: organization/package_name!pull_request_number
    • Example: PR: pool/curl!4
  • It closes an empty ProjectGit PR (e.g., if a PR was initially created for a single package but later integrated into a larger ProjectGit PR).
  • It forwards the Work In Progress (WIP) flag to the ProjectGit PR. If the ProjectGit PR references multiple Package PRs, triggering the WIP flag on the ProjectGit PR side only requires a single WIP package PR.

• Reviewer Management:

  • It adds required reviewers in the ProjectGit PR.
  • It adds required reviewers in the PackageGit PR.
  • If new commits are added to a PackageGit PR, reviewers who have already approved it will be re-added.

• Merge Management:

  • Manages PR merges based on configuration flags (ManualMergeOnly, ManualMergeProject).
  • In general, merge only happens if all mandatory reviews are completed.
  • ManualMergeProject is stricter than ManualMergeOnly and has higher priority.

  Flag	Value	Behavior
  ManualMergeProject	true	Both ProjectGit and PackageGit PRs are merged upon an allowed project maintainer commenting "merge ok” in the ProjectGit PR.
  ManualMergeOnly	true	Both PackageGit PR and ProjectGit PR are merged upon an allowed package maintainer or project maintainer commenting “merge ok” in the PackageGit PR.
  ManualMergeOnly and ManualMergeProject	false	Both ProjectGit and PackageGit PRs are merged as soon as all reviews are completed in both PrjGit and PkgGit PRs.

Config file

• Filename: workflow.config
• Location: ProjectGit
• Format: non-standard JSON (comments allowed)

Field name	Details	Mandatory	Type	Allowed Values	Default
Workflows	Type of workflow	yes	string	“pr”
Organization	The organization where PackageGit PRs are expected to occur	yes	string
Branch	The designated branch for PackageGit PRs	yes	string
GitProjectName	Repository and branch where the ProjectGit lives.	no	string	Format: org/project_repo#branch	By default assumes _ObsPrj with default branch in the Organization
ManualMergeOnly	Merges are permitted only upon receiving a "merge ok" comment from designated maintainers in the PkgGit PR.	no	bool	true, false	false
ManualMergeProject	Merges are permitted only upon receiving a "merge ok" comment in the ProjectGit PR from project maintainers.	no	bool	true, false	false
ReviewRequired	(NOT IMPLEMENTED) If submitter is a maintainer, require review from another maintainer if available.	no	bool	true, false	false
NoProjectGitPR	Do not create PrjGit PR, but still perform other tasks.	no	bool	true, false	false
Reviewers	PrjGit reviewers. Additional review requests are triggered for associated PkgGit PRs. PrjGit PR is merged only when all reviews are complete.	no	array of strings		[]
ReviewGroups	If a group is specified in Reviewers, its members are listed here.	no	array of objects		[]
ReviewGroups > Name	Name of the group	no	string
ReviewGroups > Reviewers	Members of the group	no	array of strings
ReviewGroups > Silent	Add members for notifications. If true, members are not explicitly requested to review. If one member approves, others are removed.	no	bool	true, false	false

Reviewers

Reviews is a list of accounts that need to review package and/or project. They have specific syntax

[~][*|-|+]username

A tilde (~) before a prefix signifies an advisory reviewer. Their input is requested, but their review status will not otherwise affect the process.

Other prefixes indicate project or package association of the reviewer:

• * indicates project and package
• - indicates project-only reviewer
• + indicates package-only reviewer

+ is implied.

For example: [foo, -bar, ~*moo] results in:

• foo: package reviews
• bar: project reviews
• moo: package and project reviews, but ignored

Package Deletion Requests

(NOT YET IMPLEMENTED)

• Removing a Package: To remove a package from a project, submit a ProjectGit Pull Request (PR) that removes the corresponding submodule. The bot will then rename the project branch in the pool by appending "-removed" to its name.

• Adding a Package Again: If you wish to re-add a package, create a new PrjGit PR which adds again the submodule on the branch that has the "-removed" suffix. The bot will automatically remove this suffix from the project branch in the pool.

Labels

The following labels are used, when defined in Repo/Org.

Label Config Entry	Default label	Description
StagingAuto	staging/Auto	Assigned to Project Git PRs when first staged
ReviewPending	review/Pending	Assigned to Project Git PR when package reviews are still pending
ReviewDone	review/Done	Assigned to Project Git PR when reviews are complete on all package PRs

Maintainership

Filename: _maintainership.json
Location: ProjectGit
Format: JSON
Fields:

Key	Value	Notes
package name	array of strings representing the package maintainers	List of package maintainers
“” (empty string)	array of strings representing the project maintainers	List of project maintainers

Maintainership information is defined per project. For PackageGit PR reviews, package maintainers are combined with project maintainers. A review by any of these maintainers is acceptable.

If the submitter is a maintainer it will not get a review requested.

Example:

{
    "package1": [ "reviewer", "reviewer2"],
    "package2": [],

    // "project" maintainer
    "": ["reviewer3", "reviewer4"]
}

Permissions

Permissions are extra permissions assigned to groups or individuals. Groups must be defined in the workflow.config.

    Permissions: []{
       Permission: "force-push" | "release-engineering"
       Members:    []string
    }

• force-push -- allows to issue force-push to the bot to merge even without reviews
• release-engineering -- merge, split package PRs and merge additional commits

NOTE: Project Maintainers have these permissions automatically.

Server configuration

Configuration file:

Field	Type	Notes
root	Array of string	Format org/repo#branch