# 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).

![OBS scmsync Sequence Diagram](assets/scmsync_sequence.png)

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