feat(git): 支援以任務環境變數提供 PAT

新增依任務名稱推導的 PAT 環境變數，讓容器內 HTTPS remote push 可透過 GIT_ASKPASS 完成驗證，並讓手動與自動 push 共用同一套流程。

同步補上 Docker Compose 範例、README 說明與 Git 操作測試。

Author: flier268

README.md

@@ -36,7 +36,8 @@ Open `http://127.0.0.1:8080`.
 - Set `output_subdir` to choose where generated Markdown lives under the target root.
 - Each target repo keeps `.office-docs-sync-state.json` at the repo root with per-task source file hashes and output mappings.
 - The app still uses filesystem events for low-latency sync, but every task also runs a periodic hash scan to catch missed updates and deletes.
-- Auto push uses the system git credential or SSH setup already present on the machine.
+- Auto push uses the system git credential or SSH setup already present on the machine by default.
+- For HTTPS remotes in containers, set a task-scoped PAT environment variable named from the task name plus `_key`. Non-word characters in the task name become `_`; for example task `Docs Sync` reads `Docs_Sync_key` (uppercase `DOCS_SYNC_KEY` is also accepted). The token is injected only for the git push process through `GIT_ASKPASS`.
 
 ## Service install
 

app/git_ops.py

@@ -1,7 +1,13 @@
 from __future__ import annotations
 
+import os
+import re
+import stat
+import tempfile
+from contextlib import contextmanager
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
+from typing import Iterator
 
 from git import Repo
 from git.exc import GitCommandError, InvalidGitRepositoryError, NoSuchPathError
@@ -10,6 +16,11 @@
 from .sync_state import MANIFEST_NAME
 
 
+def git_pat_env_var_name(task_name: str) -> str:
+    normalized = re.sub(r"\W+", "_", task_name.strip()).strip("_")
+    return f"{normalized or 'TASK'}_key"
+
+
 class GitManager:
     def __init__(self) -> None:
         self._next_push_at: dict[int, datetime] = {}
@@ -53,15 +64,64 @@ def maybe_push(self, task: SyncTask) -> bool:
         next_push = self._next_push_at.get(task_id)
         if not next_push or datetime.now(timezone.utc) < next_push:
             return False
+        self.push(task)
+        self._next_push_at.pop(task_id, None)
+        self._last_push_at[task_id] = datetime.now(timezone.utc)
+        return True
+
+    def push(self, task: SyncTask) -> None:
         repo = self.ensure_repo(task)
         try:
             remote = repo.remote(task.git.remote_name)
-            remote.push(task.git.branch)
+            with self._push_environment(task, repo):
+                remote.push(task.git.branch)
         except (ValueError, GitCommandError):
             raise
-        self._next_push_at.pop(task_id, None)
-        self._last_push_at[task_id] = datetime.now(timezone.utc)
-        return True
 
     def last_push_at(self, task_id: int) -> datetime | None:
         return self._last_push_at.get(task_id)
+
+    @contextmanager
+    def _push_environment(self, task: SyncTask, repo: Repo) -> Iterator[None]:
+        token = self._pat_for_task(task)
+        if not token:
+            yield
+            return
+
+        askpass_path = self._write_askpass_script(token)
+        try:
+            with repo.git.custom_environment(GIT_ASKPASS=str(askpass_path), GIT_TERMINAL_PROMPT="0"):
+                yield
+        finally:
+            askpass_path.unlink(missing_ok=True)
+
+    def _pat_for_task(self, task: SyncTask) -> str | None:
+        for env_var in self._pat_env_var_candidates(task):
+            token = os.getenv(env_var)
+            if token:
+                return token
+        return None
+
+    def _pat_env_var_candidates(self, task: SyncTask) -> list[str]:
+        primary = git_pat_env_var_name(task.name)
+        candidates = [primary, primary.upper()]
+        raw = f"{task.name}_key"
+        if raw not in candidates:
+            candidates.append(raw)
+        return candidates
+
+    def _write_askpass_script(self, token: str) -> Path:
+        fd, name = tempfile.mkstemp(prefix="office-docs-git-askpass-", suffix=".sh")
+        path = Path(name)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write("#!/bin/sh\n")
+            handle.write('case "$1" in\n')
+            handle.write('  *Username*) printf "%s\\n" "x-access-token" ;;\n')
+            handle.write(f'  *) printf "%s\\n" "{self._shell_double_quote(token)}" ;;\n')
+            handle.write("esac\n")
+        path.chmod(path.stat().st_mode | stat.S_IXUSR)
+        return path
+
+    @staticmethod
+    def _shell_double_quote(value: str) -> str:
+        return value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$").replace("`", "\\`")

app/main.py

@@ -118,7 +118,7 @@ def push_task(task_id: int) -> dict[str, str]:
         if not task:
             raise HTTPException(status_code=404, detail="Task not found")
         try:
-            git_manager.ensure_repo(task).remote(task.git.remote_name).push(task.git.branch)
+            git_manager.push(task)
         except Exception as exc:  # pragma: no cover - external
             raise HTTPException(status_code=400, detail=str(exc)) from exc
         return {"status": "pushed"}

docker-compose.example.yml

@@ -8,6 +8,7 @@ services:
       APP_DATA_DIR: /data
       HOST: 0.0.0.0
       PORT: 8080
+      # Docs_Sync_key: ghp_xxx
     volumes:
       - ./data:/data
     restart: unless-stopped

tests/test_git_ops.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+
+from git import Repo
+
+from app.git_ops import GitManager, git_pat_env_var_name
+from app.models import SyncTask, TaskGitConfig, TaskPaths
+
+
+def make_task(tmp_path: Path, name: str = "Task API") -> SyncTask:
+    source = tmp_path / "source"
+    target = tmp_path / "target"
+    source.mkdir()
+    target.mkdir()
+    return SyncTask(
+        name=name,
+        paths=TaskPaths(source_dir=str(source), target_root=str(target), output_subdir="md"),
+        git=TaskGitConfig(enabled=True, auto_push=True),
+    )
+
+
+def test_git_pat_env_var_name_uses_task_name() -> None:
+    assert git_pat_env_var_name("Task API") == "Task_API_key"
+    assert git_pat_env_var_name(" docs/sync ") == "docs_sync_key"
+
+
+def test_git_pat_for_task_reads_task_key_env(tmp_path: Path, monkeypatch) -> None:
+    task = make_task(tmp_path, name="Task API")
+    monkeypatch.setenv("Task_API_key", "pat-token")
+
+    assert GitManager()._pat_for_task(task) == "pat-token"
+
+
+def test_git_pat_for_task_accepts_uppercase_env(tmp_path: Path, monkeypatch) -> None:
+    task = make_task(tmp_path, name="Task API")
+    monkeypatch.setenv("TASK_API_KEY", "pat-token")
+
+    assert GitManager()._pat_for_task(task) == "pat-token"
+
+
+def test_push_environment_sets_askpass_for_pat(tmp_path: Path, monkeypatch) -> None:
+    task = make_task(tmp_path)
+    repo = Repo.init(Path(task.paths.target_root), initial_branch=task.git.branch)
+    monkeypatch.setenv("Task_API_key", "pat-token")
+
+    manager = GitManager()
+    with manager._push_environment(task, repo):
+        env = repo.git._environment
+        askpass = Path(env["GIT_ASKPASS"])
+        assert env["GIT_TERMINAL_PROMPT"] == "0"
+        assert askpass.exists()
+        assert "pat-token" in askpass.read_text(encoding="utf-8")
+
+    assert repo.git._environment == {}
+    assert not askpass.exists()