git-workflow-documentation/architecture/hld/scmsync_flow.md

OBS Git scmsync Workflow

This document outlines the complete workflow for how a git push to a Gitea repository triggers a source synchronization in the Open Build Service (OBS).

Components Involved

The end-to-end process involves several distinct components:

1. Gitea: The Git repository hosting service.
2. gitea_obs_bridge: A lightweight Perl web service that acts as a webhook receiver, translating generic Git webhooks into specific OBS API calls.
3. OBS API (Frontend): The main entry point for the Open Build Service, built on Ruby on Rails. It handles authentication and forwards requests to the backend.
4. OBS Backend Components:
   • bs_srcserver: The core source management server.
   • bs_servicedispatch: Manages the dispatching of source service events.
   • bs_service: The daemon responsible for executing source services.
   • SQLite DB: Stores source-related metadata, including the scmsync table mapping Git repositories to OBS packages.
5. obs-scm-bridge: A Python command-line tool installed as an OBS source service. It performs the actual Git operations (clone, fetch) to sync the sources.

Configuration

For the flow to work, two key pieces of configuration are required:

1. OBS Package Configuration: The OBS package (or project) must be configured with a <scmsync> tag in its metadata (_meta file).
2. Gitea Webhook: A webhook must be configured in the Gitea repository to point to the gitea_obs_bridge service.

The Step-by-Step Flow

1. git push: A developer pushes new commits to a branch in a Gitea repository.

2. Webhook Trigger: Gitea sends a webhook to gitea_obs_bridge.

3. API Call: gitea_obs_bridge calls the OBS API endpoint POST /source?cmd=triggerscmsync.

4. Backend Proxy: The OBS API proxies this request directly to the bs_srcserver backend process.

5. Lookup Involved Projects/Packages: bs_srcserver queries its internal SQLite database to identify all OBS projects or packages linked to the specific Git repository and branch.

6. Create Service Run Events: For each identified entity, a service run event is generated. These events are handled by the bs_servicedispatch process.

7. Dispatch to Service Daemon: bs_servicedispatch hands over the event to the bs_service daemons.

8. Execute obs-scm-bridge: The daemon executes the obs-scm-bridge source service.

   • For Packages: The bridge runs similarly to a standard source service, syncing the sources directly.
   • For Projects: The bridge first runs to identify all changed packages. For each changed package, a new service event is generated, triggering subsequent syncs.

Note: The OBS schedulers are designed to wait until all sources are fully updated before scheduling any new build jobs, ensuring build consistency regardless of the number of events generated.