OBS Git Interface

A lightweight web interface for the Open Build Service (OBS), focusing on git-managed sources and providing a modern, streamlined experience for package development workflows.

Overview

OBS Git Interface is a read-only web application that provides an intuitive interface to browse and monitor OBS build results with a focus on packages synchronized from Git repositories. It seamlessly integrates with Gitea to provide a unified view of your git repositories and their build status.

Key Features

🔧 Git-Centric Approach

This interface emphasizes a package-centric approach for git-based packages. This means all maintained branches are hosted in the same organisation. It seamlessly integrates with Gitea to show repository details, branches, commits, and build status for packages synchronized from git repositories.

📦 Legacy Project Support

While the interface excels with git-managed packages, you can also browse legacy OBS projects that use traditional source handling. Note that functionality for these legacy projects is limited, as the focus is on modern git-based workflows.

🔍 Search and Browse Build Results

The interface is designed to make it easy to search and browse build results across projects, repositories, and architectures. The monitor page provides real-time build status updates with efficient filtering and search capabilities.

👁️ Read-Only Access

OBS Git Interface is read-only by design. It can be used with any web browser or HTTP client that doesn't attempt modifications. This makes it safe for browsing, monitoring, and analysis without risk of accidental changes.

API Provider

OBS Git Interface can be used as api for an OBS instance. It is possible to use it for example to get build logs, run local builds and do other non-modifing operations.

Deployment Options

🌐 Default Configuration

By default, the interface connects to the official openSUSE OBS instance at api.opensuse.org, making it immediately useful for openSUSE development. It is using your local osc authentification cookie by default.

💻 Local Deployment

The interface can be run locally on your machine and configured to connect to any OBS API endpoint. This is perfect for:

• Development and testing workflows
• Connecting to custom OBS instances
• Private or internal build services
• Offline work with local OBS backends

🖥️ Local OBS Backend

If you have a local OBS instance running, the interface can connect directly to it, providing the same intuitive git-centric experience for your local build infrastructure.

Running Locally

Prerequisites

• Python 3.13 or higher
• pip (Python package manager)

Installation

1. Clone or download the repository:

   cd /path/to/obs-lite-flask
   

2. Install dependencies:

   pip install -r requirements.txt
   

   Or install required packages manually:

   pip install flask requests markupsafe markdown
   

Quick Start

Run the application with default settings (connects to api.opensuse.org), using your osc login cookie:

python obs_git_explorer.py --read-osc-cookie

Then open your browser and navigate to:

http://localhost:5000

Configuration Options

Using Command-Line Arguments

# Connect to a custom OBS server
python obs_git_explorer.py --gitea-url https://gitea.example.com --backend-url https://api.example.com/

# Connect to a local OBS source server, using openSUSE gitea server
python obs_git_explorer.py --backend-url http://localhost:5352/

# Specify also a custom Gitea server
python obs_git_explorer.py --backend-url http://localhost:5352/ --gitea-url https://gitea.example.com --gitea-org my_default_organisation

# Change port and host. Use 0.0.0.0 to make it accessable from all networks.
python obs_git_explorer.py --host 127.0.0.1 --port 8080

# Enable debug mode
python obs_git_explorer.py --debug

# Use authentication
python obs_git_explorer.py --username myuser --password mypass

# Use OSC cookie (read from ~/.local/state/osc/cookiejar)
python obs_git_explorer.py --read-osc-cookie

# Use SSH signature authentication (like osc)
python obs_git_explorer.py --ssh-auth --ssh-user myuser --ssh-key ~/.ssh/id_rsa

Using Configuration File

Create a configuration file at ~/.config/obs-lite/config.ini:

[server]
host = 127.0.0.1
port = 5000
debug = false

[backend]
url = https://api.opensuse.org/

[gitea]
url = https://src.opensuse.org
organization = pool

[auth]
# Read OSC cookie
read_osc_cookie = true

# Or use HTTP Basic Auth
# username = myuser
# password = mypass

# Or use SSH signature auth
# ssh_enabled = true
# ssh_user = myuser
# ssh_key_path = ~/.ssh/id_rsa

[ssl]
# SSL certificate verification
verify = /etc/ssl/ca-bundle.pem
# verify = true
# verify = false

[features]
enable_gitea_iframe = false

Then run:

python obs_git_explorer.py --config-file ~/.config/obs-lite/config.ini

Or if using the default location:

python obs_git_explorer.py

See config.ini.example for complete configuration reference.

Daemon Cache Mode (Optional)

For production deployments with high traffic, you can enable daemon cache mode to improve performance by offloading cache updates to a background process:

1. Enable daemon mode in your config:

[cache]
daemon_mode = true

2. Run the cache daemon as a background service:

# Run manually
obs-git-cache-daemon --config-file ~/.config/obs-lite/config.ini

# Or as systemd service (recommended)
sudo cp obs-git-cache-daemon.service.example /etc/systemd/system/obs-git-cache-daemon.service
sudo systemctl enable obs-git-cache-daemon
sudo systemctl start obs-git-cache-daemon

3. Run the web application (which now uses read-only cache):

gunicorn -c gunicorn.conf.py obs_git_explorer.wsgi:app

How it works:

• Daemon mode OFF (default): Web app updates caches on-demand when users access pages
• Daemon mode ON: Web app reads from cache only; daemon listens to OBS /lastevents and updates caches in real-time when changes occur
• The daemon uses event-driven updates via /lastevents endpoint with client=obs-lite and obsname=HOSTNAME
• Events are tracked using the sync number, ensuring no events are missed
• This provides near-instant cache updates while keeping web app response times consistent

Event-driven architecture:

• Daemon connects to OBS /lastevents endpoint
• Backend returns events with a sync number
• Daemon processes relevant events (project/package changes)
• Updates affected caches immediately
• Uses sync number on next call to get only new events
• Fallback to periodic refresh on errors

When to use:

• High-traffic deployments with many concurrent users
• When cache updates cause noticeable delays in web responses
• Production environments where consistent response times matter
• When you want real-time cache updates instead of periodic polling

Use Cases

• Package Maintainers: Monitor build status across multiple repositories and architectures
• Developers: Track git-synchronized packages and their build results
• Release Managers: Get an overview of project health and build failures
• Contributors: Browse packages and understand build dependencies
• CI/CD Integration: Read-only API access for automation and monitoring

Technical Details

• Backend: Flask web framework
• Caching: SQLite-based per-backend caching for performance
• Authentication: Supports OSC cookies, HTTP Basic Auth, and SSH signature authentication
• API Access: Read-only proxy to OBS API endpoints
• Gitea Integration: API-based integration with Gitea for repository information

Security

This application is read-only by design:

• Only GET requests are allowed
• POST, PUT, PATCH, and DELETE requests are blocked
• No modifications can be made to OBS backend
• Safe for public access and monitoring

Examples

Connect to Official openSUSE OBS

python obs_git_explorer.py

Connect to Local OBS Instance

python obs_git_explorer.py --backend-url http://localhost:5352/

Connect to Custom OBS with Authentication

python obs_git_explorer.py \
  --backend-url https://build.example.com/ \
  --username myuser \
  --password mypass \
  --gitea-url https://git.example.com \
  --gitea-org myorg

Use with OSC Cookie (for authenticated access)

python obs_git_explorer.py --read-osc-cookie

License

This software is open source. Please refer to the project repository for license information.

Support

For issues, feature requests, or contributions, please visit the project repository.