feat(vcs): run repository maintenance in background

Repository operations can exceed proxy timeouts and provide little feedback while requests remain open. Queue browser actions and opt-in API requests as serialized, trackable Celery tasks.

Author: nijel

docs/admin/continuous.rst

@@ -227,10 +227,17 @@ Availability of individual actions depends on permissions, the configured
 version control system, whether pushing is configured, and whether the selected
 object can be locked.
 
-The :guilabel:`File management` actions are available only from
-:guilabel:`Repository maintenance` for an individual translation. These actions
-rewrite that translation file and commit the result; they are not project-wide
-or component-wide operations.
+Repository actions started from this view are queued for background processing.
+For a project, Weblate processes the affected repositories sequentially in one
+task and shows its progress. Repeating the same action opens the existing task;
+a different action cannot be started for the same repository until that task
+finishes.
+
+The :guilabel:`Synchronize` and :guilabel:`Rescan` repository operations are
+queued for background processing as described above. The separate
+:guilabel:`File management` actions are available only for an individual
+translation. They rewrite that translation file and commit the result during
+the web request; they are not project-wide or component-wide operations.
 
 Operations that read repository content, such as updating, resetting, or
 rescanning, also reconcile translation files in Weblate. Added or removed

docs/api.rst

@@ -1204,10 +1204,19 @@ Projects
     :param project: Project URL slug
     :type project: string
     :<json string operation: Operation to perform: one of ``push``, ``pull``, ``commit``, ``reset``, ``cleanup``, ``file-sync``, ``file-scan``
-    :>json boolean result: result of the operation
+    :<json boolean background: Schedule the operation as a background task instead of waiting for it to finish. Defaults to ``false``.
+    :>json boolean result: result of a synchronous operation
     :>json array included_components: full paths of project components included in the operation
     :>json array skipped_components: full paths of project components omitted from the operation
     :>json array permission_blockers: full paths of components preventing access to omitted repositories
+    :>json string detail: Status of a background operation
+    :>json string task_url: URL for tracking a background operation; see :http:get:`/api/tasks/(str:uuid)/`
+
+    With ``background`` set to ``true``, the endpoint returns ``202 Accepted``.
+    Repeating an identical queued operation returns the existing task URL. A
+    conflicting operation returns ``423 Locked`` and the active task URL when
+    available. Eligible project repositories are processed sequentially in one
+    task.
 
     **CURL example:**
 
@@ -1251,6 +1260,33 @@ Projects
             "skipped_components": ["hello/glossary"]
         }
 
+    **Background JSON request example:**
+
+    .. sourcecode:: http
+
+        POST /api/projects/hello/repository/ HTTP/1.1
+        Host: example.com
+        Accept: application/json
+        Content-Type: application/json
+        Authorization: Token TOKEN
+
+        {"operation":"pull","background":true}
+
+    **Background JSON response example:**
+
+    .. sourcecode:: http
+
+        HTTP/1.0 202 Accepted
+        Content-Type: application/json
+
+        {
+            "detail": "Repository operation has been queued.",
+            "included_components": ["hello/app"],
+            "permission_blockers": ["shared/glossary"],
+            "skipped_components": ["hello/glossary"],
+            "task_url": "https://example.com/api/tasks/01234567-89ab-cdef-0123-456789abcdef/"
+        }
+
 
 .. http:get:: /api/projects/(string:project)/components/
 
@@ -3384,6 +3420,13 @@ Tasks
     :>json int progress: Task progress in percent
     :>json object result: Task result or progress details
     :>json string log: Task log
+    :>json boolean cancellable: Whether the task can be cancelled
+
+.. http:delete:: /api/tasks/(str:uuid)/
+
+    Cancels a running task when its ``cancellable`` property is ``true``.
+    Repository operation tasks cannot be cancelled because interruption can
+    leave a repository operation incomplete.
 
 .. _api-statistics:
 

docs/changes.rst

@@ -11,6 +11,7 @@ Weblate 2026.9
 .. rubric:: Improvements
 
 * Removing the final Weblate workspace connection for a GitHub account, or removing the workspace holding it, now also uninstalls the Weblate GitHub App from GitHub.
+* Core repository maintenance actions now run as background tasks, avoiding request and proxy timeouts. The repository API supports the same behavior using ``background: true``. See :ref:`repository-maintenance`.
 * :ref:`addon-weblate.gettext.xgettext` now accepts multiple custom keywords (newline-separated) passed to xgettext via ``--keyword``, enabling extraction from different function names.
 * Screenshot images are now cached in browsers to reduce repeated downloads.
 * Administrators can now find removed accounts by their former e-mail address in the audit log until :setting:`AUDITLOG_EXPIRY`.

docs/security/threat-model.rst

@@ -25,7 +25,7 @@ documentation; ``*(maintainer)*`` means it was stated by a maintainer during
 this threat-model process; ``*(inferred)*`` means it was reasoned from the
 current project shape and needs maintainer confirmation.
 
-Provenance summary: 103 documented / 64 maintainer / 0 inferred claims.
+Provenance summary: 103 documented / 65 maintainer / 0 inferred claims.
 
 Weblate is a Django-based web localization platform. It accepts work from
 browser users, API clients, project-scoped tokens, repository webhooks, VCS
@@ -193,6 +193,13 @@ repository state, background tasks, outbound requests, and rendered UI.
    * - Client browser/API client to Weblate
      - Untrusted or authenticated requests become permission-checked
        application actions. *(documented)* (source: :doc:`/api`, :doc:`/admin/access`)
+   * - Weblate request process to repository Celery worker
+     - Permission-checked browser and API repository actions become queued work
+       carrying the initiating user and affected repository scope. The worker
+       reacquires the datastore reservation and rechecks the user's current VCS
+       permission across the current linked-component scope before mutation.
+       The broker, datastore, and workers are trusted parts of the same Weblate
+       instance. *(maintainer)*
    * - Webhook sender to Weblate
      - Public forge notifications can schedule repository synchronization
        where hooks are enabled, matching components by exact repository URL
@@ -621,9 +628,13 @@ Security properties Weblate provides
        explicit VCS actions cover every component sharing an affected
        repository, including linked components in other projects. Project-wide
        VCS actions omit repositories where this permission check fails; they do
-       not partially operate on an individual shared checkout. Weblate's normal
-       background commit and push of authorized translation changes does not
-       require the editor to have these VCS permissions. Translation memory
+       not partially operate on an individual shared checkout. Explicit VCS
+       actions queued from the browser or API retain the initiating user,
+       serialize access to the affected repositories, and recheck that user's
+       permission against the current linked-component scope in the worker
+       before mutation. Weblate's normal background commit and push of
+       authorized translation changes does not require the editor to have
+       these VCS permissions. Translation memory
        attributed to an existing restricted component follows that component's
        access rules.
        Unattributed automatic memory, including unmatched legacy entries and

docs/specs/openapi.yaml

@@ -2831,7 +2831,8 @@ class BooleanResultSerializer(ReadOnlySerializer):
     result = serializers.BooleanField()
 
 
-class RepositoryOperationSerializer(BooleanResultSerializer):
+class RepositoryOperationSerializer(ReadOnlySerializer):
+    result = serializers.BooleanField(required=False)
     detail = serializers.CharField(required=False)
     included_components = serializers.ListField(
         child=serializers.CharField(),
@@ -2848,6 +2849,7 @@ class RepositoryOperationSerializer(BooleanResultSerializer):
         required=False,
         help_text="Full paths of components preventing access to skipped repositories.",
     )
+    task_url = serializers.URLField(required=False)
 
 
 class UploadResultSerializer(BooleanResultSerializer):
@@ -3058,6 +3060,7 @@ class RepoRequestSerializer(ReadOnlySerializer):
     operation = serializers.ChoiceField(
         choices=RepoOperations.choices,
     )
+    background = serializers.BooleanField(required=False, default=False)
 
 
 class CommitInfoSerializer(ReadOnlySerializer):
@@ -4347,6 +4350,7 @@ class TaskSerializer(ReadOnlySerializer):
     progress = serializers.IntegerField(min_value=0, max_value=100)
     result = TaskResultField()
     log = serializers.CharField(allow_blank=True)
+    cancellable = serializers.BooleanField()
 
 
 @extend_schema_serializer(