Overview
Background job for bulk installation and verification of GitLab webhooks across repositories, provided by the OpenHands enterprise sync layer.
Description
VerifyWebhookStatus is a background job class that manages the bulk installation and verification of GitLab webhooks for repositories that require them. It processes repositories in chunks to handle large-scale deployments efficiently and respects GitLab API rate limits.
The job operates in a pipeline: fetch_rows() retrieves batches of repositories that need webhook installation (using a CHUNK_SIZE of 100), verify_conditions_are_met() checks prerequisites for each repository (such as having valid credentials and repository access), create_new_webhook() performs the actual GitLab API call to install the webhook, and install_webhooks() orchestrates the full flow across all pending repositories.
A notable design feature is the handling of BreakLoopException, which is thrown when the GitLab API returns rate-limiting responses. Rather than failing the entire batch, the exception is caught at the orchestration level to gracefully stop processing and allow the job to resume in its next scheduled run. This prevents the job from burning through API quota and ensures forward progress across multiple executions.
Usage
Use VerifyWebhookStatus as a scheduled background job that runs periodically to ensure all repositories have up-to-date webhook configurations. It is typically invoked by the task scheduler and does not require manual triggering.
Code Reference
Source Location
Signature
class VerifyWebhookStatus:
CHUNK_SIZE = 100
def __init__(self, session: Session, config: AppConfig):
...
def fetch_rows(self, offset: int = 0) -> List[Repository]:
"""Fetches a chunk of repositories needing webhook installation."""
...
def verify_conditions_are_met(self, repo: Repository) -> bool:
"""Checks prerequisites for webhook installation (credentials, access, etc.)."""
...
def create_new_webhook(self, repo: Repository) -> bool:
"""Calls the GitLab API to install the webhook. Returns True on success."""
...
def install_webhooks(self) -> None:
"""Orchestrates bulk webhook installation. Handles BreakLoopException for rate limiting."""
...
Import
from enterprise.sync.install_gitlab_webhooks import VerifyWebhookStatus
I/O Contract
Inputs
Constructor
| Name |
Type |
Required |
Description
|
| session |
Session |
Yes |
SQLAlchemy database session for querying repositories
|
| config |
AppConfig |
Yes |
Application configuration containing GitLab API credentials and webhook URLs
|
fetch_rows()
| Name |
Type |
Required |
Description
|
| offset |
int |
No |
Pagination offset for fetching repository chunks (default: 0)
|
verify_conditions_are_met()
| Name |
Type |
Required |
Description
|
| repo |
Repository |
Yes |
The repository ORM object to check prerequisites for
|
create_new_webhook()
| Name |
Type |
Required |
Description
|
| repo |
Repository |
Yes |
The repository to install the webhook on via the GitLab API
|
Outputs
| Method |
Return Type |
Description
|
| fetch_rows() |
List[Repository] |
A chunk of up to CHUNK_SIZE (100) repositories needing webhook installation
|
| verify_conditions_are_met() |
bool |
True if the repository meets all prerequisites for webhook installation
|
| create_new_webhook() |
bool |
True if the webhook was successfully installed via the GitLab API
|
| install_webhooks() |
None |
Processes all pending repositories; stops gracefully on BreakLoopException
|
Constants
| Name |
Value |
Description
|
| CHUNK_SIZE |
100 |
Number of repositories to fetch per batch for processing
|
Exception Handling
| Exception |
Raised By |
Handled By |
Behavior
|
| BreakLoopException |
create_new_webhook() (on rate limit) |
install_webhooks() |
Stops the current batch processing; job resumes on next scheduled run
|
Usage Examples
Running the Webhook Installation Job
from enterprise.sync.install_gitlab_webhooks import VerifyWebhookStatus
# Typically run by a task scheduler
job = VerifyWebhookStatus(session=db_session, config=app_config)
# Install webhooks for all pending repositories
# Processes in chunks of 100, stops gracefully on rate limits
job.install_webhooks()
Manual Single-Repository Check
job = VerifyWebhookStatus(session=db_session, config=app_config)
# Check a specific repository
repo = session.query(Repository).get("repo-id-123")
if job.verify_conditions_are_met(repo):
success = job.create_new_webhook(repo)
if success:
logger.info(f"Webhook installed for {repo.name}")
else:
logger.warning(f"Failed to install webhook for {repo.name}")
else:
logger.info(f"Prerequisites not met for {repo.name}")
Related Pages
Environment
