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.

Project specific config file

This is the ProjectGit config file. For runtime config file, see bottom.

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	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

The configuration file is a JSON file that consists of a list of project git locations that are then consulted for their workflow.config config files.

[]ProjectGit = {
   "org" | "org/repo" | "org/repo#branch"
}

default repo = _ObsPrj
default branch = as specified in Gitea

For example,

[ "org", "openSUSE/Leap", "openSUSE/Leap#16.0" ]

Are all valid entries. These are then resolved to,

For org, it's assumed that default repository of _ObsPrj in org organization and using Gitea's default branch
For openSUSE/Leap, the repository "Leap" using Gitea's default branch in openSUSE organization.
For openSUSE/Leap#16.0, the repository "Leap" with branch "16.0" in openSUSE organization.

For each of these project gits, workflow.config is read.

Runtime Options

Option	Default	Environmental Default	Notes
git-author	AutoGits PR Review Bot	AUTOGITS_GIT_AUTHOR	Name of author for bot created commits
git-email	noone@suse.de	AUTOGITS_GIT_EMAIL	Email for the bot created commits
config		AUTOGITS_CONFIG	Path to above config file
gitea-url	https://src.opensuse.org	AUTOGITS_GITEA_URL	Gitea's URL instance
rabbit-url	amqps://rabbit.opensuse.org	AUTOGITS_RABBIT_URL	RabbitMQ's URL instance
debug	false	AUTOGITS_DEBUG	Extra logging
check-on-start	false	AUTOGITS_CHECK_ON_START	Whether to check all projects for consistency on start. Can take a while
check-interval	5		Consistency check interval
repo-path	Uses temp directory	AUTOGITS_REPO_PATH	Path where to store repositories.