Author SHA1 Message Date
GitHub Actions 91077fa527 Merge remote-tracking branch 'origin/main' into backups_helper
Python package / build (flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics, 3.12.3) (pull_request) Successful in 35s
Python package / build (flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics, 3.13) (pull_request) Successful in 37s
Python package / build (flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics, 3.14) (pull_request) Successful in 40s
Python package / build (flake8 . --count --select=E9,F63,F7,F82 --ignore=F824 --show-source --statistics, 3.12.3) (pull_request) Successful in 35s
Python package / build (flake8 . --count --select=E9,F63,F7,F82 --ignore=F824 --show-source --statistics, 3.13) (pull_request) Successful in 36s
Python package / build (flake8 . --count --select=E9,F63,F7,F82 --ignore=F824 --show-source --statistics, 3.14) (pull_request) Successful in 38s
Python package / build (mypy --no-incremental --config-file mypy.ini backend tests, 3.12.3) (pull_request) Successful in 1m43s
Python package / build (mypy --no-incremental --config-file mypy.ini backend tests, 3.13) (pull_request) Successful in 1m42s
Python package / build (mypy --no-incremental --config-file mypy.ini backend tests, 3.14) (pull_request) Successful in 1m45s
Python package / build (pip list, 3.12.3) (pull_request) Successful in 34s
Python package / build (pip list, 3.13) (pull_request) Successful in 36s
Python package / build (pip list, 3.14) (pull_request) Successful in 37s
Python package / build (python -c "import sys; print(f'Python {sys.version}'); print(f'Build: {sys.version_info}'); print(f'Implementation: {sys.implementation}')", 3.12.3) (pull_request) Successful in 32s
Python package / build (python -c "import sys; print(f'Python {sys.version}'); print(f'Build: {sys.version_info}'); print(f'Implementation: {sys.implementation}')", 3.13) (pull_request) Successful in 37s
Python package / build (python -c "import sys; print(f'Python {sys.version}'); print(f'Build: {sys.version_info}'); print(f'Implementation: {sys.implementation}')", 3.14) (pull_request) Successful in 38s
Python package / tests (pytest, 3.12.3) (pull_request) Canceled after 0s
Python package / tests (pytest, 3.13) (pull_request) Canceled after 0s
Python package / tests (pytest, 3.14) (pull_request) Canceled after 0s
2026-08-04 12:29:42 +00:00
GitHub Actions 8ffbb96c37 Squash 2026-06-11 20:35:58 +00:00
36 changed files with 339 additions and 1988 deletions
+8 -4
View File
@@ -20,16 +20,16 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.PUSH_TOKEN }}
token: ${{ secrets.GITHUB_TOKEN }}
- name: Configure git
run: |
git config user.email "gitea-actions[bot]@noreply.localhost"
git config user.name "Gitea Actions"
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "GitHub Actions"
- name: Fetch all branches
run: |
git remote set-url origin "https://x-access-token:${PUSH_TOKEN}@gitea.rudolf.keenetic.link/${GITHUB_REPOSITORY}.git"
git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
git fetch --all --prune
- name: Merge every branch onto main
@@ -37,6 +37,7 @@ jobs:
run: |
set -eo pipefail
MAIN=main
# Collect remote branch names (exclude HEAD and main)
branches=$(git for-each-ref --format='%(refname:short)' refs/remotes/origin/ \
| sed 's|^origin/||' \
| grep -v -e '^HEAD$' -e '^main$' -e '^origin$' \
@@ -48,8 +49,11 @@ jobs:
continue
fi
echo "=== Processing branch: $br ==="
# Create/update a local branch from remote
git checkout -B "$br" "origin/$br"
# Merge origin/main into branch (non-interactive)
if git merge --no-edit "origin/$MAIN"; then
# Push updated branch to remote (no force)
if git push origin "$br"; then
echo "Pushed merged $br"
else
+8 -4
View File
@@ -18,16 +18,16 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.PUSH_TOKEN }}
token: ${{ secrets.GITHUB_TOKEN }}
- name: Configure git
run: |
git config user.email "gitea-actions[bot]@noreply.localhost"
git config user.name "Gitea Actions"
git config user.email "github-actions[bot]@users.noreply.github.com"
git config user.name "GitHub Actions"
- name: Fetch all branches
run: |
git remote set-url origin "https://x-access-token:${PUSH_TOKEN}@gitea.rudolf.keenetic.link/${GITHUB_REPOSITORY}.git"
git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
git fetch --all --prune
- name: Merge every branch onto main
@@ -35,6 +35,7 @@ jobs:
run: |
set -eo pipefail
MAIN=main
# Collect remote branch names (exclude HEAD and main)
branches=$(git for-each-ref --format='%(refname:short)' refs/remotes/origin/ \
| sed 's|^origin/||' \
| grep -v -e '^HEAD$' -e '^main$' -e '^origin$' \
@@ -46,9 +47,12 @@ jobs:
continue
fi
echo "=== Processing branch: $br ==="
# Create/update a local branch from remote
git reset --hard HEAD
git checkout -B "$br" "origin/$br"
# Merge origin/main into branch (non-interactive)
if git merge --no-edit --squash "origin/$MAIN"; then
# Push updated branch to remote (no force)
git reset --soft "origin/$MAIN"
git commit -m "Squash"
if git push origin "$br" --force-with-lease; then
+54 -18
View File
@@ -1,3 +1,6 @@
# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
name: Python package
on:
@@ -7,40 +10,73 @@ on:
pull_request:
branches: [ "main" ]
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.12.3", "3.13", "3.14"]
python-version: [
# "3.11.3",
"3.12.3",
"3.13",
"3.14",
# "3.15",
]
checker: [
"python -c \"import sys; print(f'Python {sys.version}'); print(f'Build: {sys.version_info}'); print(f'Implementation: {sys.implementation}')\"",
"pip list",
"flake8 . --count --select=E9,F63,F7,F82 --ignore=F824 --show-source --statistics",
"flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics",
# "ty check backend",
"mypy --no-incremental --config-file mypy.ini backend tests",
]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
- name: Set up Python ${{ matrix.python-version }}, ${{ matrix.checker }}
uses: actions/setup-python@v3
with:
python-version: ${{ matrix.python-version }}
cache: 'pip'
cache-dependency-path: |
requirements.txt
requirements-dev.txt
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt
- name: Run checker
run: ${{ matrix.checker }}
- name: Lint (flake8)
tests:
runs-on: ubuntu-latest
needs: build
strategy:
fail-fast: false
matrix:
python-version: [
# "3.11.3",
"3.12.3",
"3.13",
"3.14",
# "3.15",
]
checker: [
"pytest",
]
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}, ${{ matrix.checker }}
uses: actions/setup-python@v3
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
flake8 . --count --select=E9,F63,F7,F82 --ignore=F824 --show-source --statistics
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
# sudo apt-get update
# sudo apt-get upgrade -y
# sudo apt-get install -y --no-install-recommends git docker.io
python -m pip install --upgrade pip
pip install -r requirements-dev.txt
playwright install --with-deps chromium
- name: Run checker
run: "pytest"
- name: Type-check (mypy)
run: mypy --no-incremental --config-file mypy.ini backend tests
-111
View File
@@ -1,111 +0,0 @@
# Adding a new stack to brencher
A "stack" is one self-contained Docker Swarm service that brencher manages
end-to-end: detect HEAD changes, build, deploy, and expose service status to
the UI. This file documents how to wire one up so it picks up commits
without an operator clicking "Update" in the UI every time.
## Repository layout
Brencher looks at exactly one commit on one ref per environment. For a new
stack `my_stack`:
1. Push branch `feat/my_stack` (or whatever the team convention is) to a
Git repo listed in `remotes` of the config file.
2. Drop the repo in `gitea` or `github` so it's reachable through the same
remotes that other stacks use.
3. Make sure `my_stack/stack-compose.yml` and a Dockerfile (typically
`my_stack/Dockerfile`) exist at the path the config will point at.
## Config file: `backend/configs/<stack>.py`
The shape is fixed by `enironment.Environment` and the steps it pulls in.
Look at `backend/configs/hermes.py` for the canonical pattern. A new config
must:
- Build a `GitClone` with at least one remote whose `url` points to the repo
above.
- Build a `DockerSwarmCheck(stack_name="<stack>")` to introspect the
deployed service.
- Build **`GitUnmerge(clone, dockerSwarmCheck)`** and wrap it into
`SharedStateHolderInMemory(unmerge=unmerge)`. This is what makes
autodeploy work — `GitUnmerge` reads the `org.brencher.version` label
from the running swarm task and converts it into
`desired_branches`, so each polling cycle asks "is HEAD ≠ what's
deployed?" without any UI input.
- Wire a `CheckoutMerged(clone, desired_branches=state, push=False, …)`.
Push stays `False` for first-party stacks; set `True` only when you want
brencher to push auto-named branches back to origin.
- Build a `DockerComposeBuild` (or `DockerSwarmBuild` if a Swarmfile is
used) pointing at the compose path in the repo.
- Build a `DockerSwarmDeploy(wd=clone, buildDocker=…, stackChecker=…, …)`
with the same `stack_name`. Image tag is `auto-<short-sha>` driven by
`checkoutMerged.progress().version`.
- Optionally append a `SimpleLog(message={"userLinks": {...}})` for the
link to surface in the UI.
- Set `__all__` and export the `Environment` named after the stack id.
- Add it to `Environment.pipeline` in the canonical order:
`clone → state → checkoutMerged → dockerSwarmCheck → build → deploy →
optionals`. Build and deploy are explicit `DockerComposeBuild` and
`DockerSwarmDeploy` siblings; do not collapse them into one step.
If you skip the `GitUnmerge` line, `state.branches` will stay empty and
the stack will only deploy when an operator pushes a `branches` update
through the UI. Don't skip it; it's the difference between a self-driving
stack and a manual one. See `connectivity_tester.py` history for the bug
this caused.
## Verification checklist
- `python3 -c "from backend.configs.my_stack import my_stack"` works in
the brencher container.
- `PROFILES="my_stack" python3 backend/app.py` boots and the UI renders a
row for `my_stack` with non-empty branches (from `GitUnmerge`,
pointing at whatever image is currently deployed).
- Push to the configured branch, wait one full polling cycle
(~`RESET_INTERVAL` = 180s, plus the next pipeline tick), then confirm
the service was redeployed with a new `org.brencher.version` label.
- No UI `environment_update` was issued in between.
## Common foot-guns
- `dockerfile:` path in `stack-compose.yml` is interpreted relative to the
compose file's directory. The compose file and the Dockerfile must
live side-by-side; use `dockerfile: Dockerfile`, not
`dockerfile: <relative-path>`.
- Removing the `name:` key from the top of `stack-compose.yml` is fine
for `docker stack deploy` — the stack name comes from the CLI option
brencher sets.
- `EXTRA_ENDPOINTS` and friends are env vars; if you reference them in
compose, define them in the `envs=lambda: {...}` of the
`DockerComposeBuild` and `DockerSwarmDeploy`. `substitute` uses
`env.get(...)` for deploys but `env[...]` (raises) for builds, so an
unlisted variable kills the build but quietly produces an empty string
in the deploy.
- Compose files must not assume Docker networks that don't exist. Use
either an `external: true` net that already exists in Swarm, drop
the `networks:` block entirely, or `driver: overlay` for a
stack-private net.
## Tracking
When you add a stack, also:
- Open a tracking issue in `admin/brencher` titled
`[ready-to-test] <stack>: …` with `state=` from your
`GitUnmerge`-derived branches and what URL/port the service exposes.
- Add the stack id to the `PROFILES` env var in the brencher stack
compose (`docker_stack` / Swarm declarative) so it gets picked up on
next rollout. The admin overlay is where this lives.
## Build delegation pattern (Actions)
Brencher does not run docker build or docker push itself. It dispatches a Gitea
Actions workflow via `POST /api/v1/repos/{owner}/{repo}/actions/workflows/{file}/dispatches`,
waits for the run to complete, then runs `docker stack deploy`.
Use `steps.actions.GiteaActionsTrigger` and `steps.actions.GiteaActionsAwait`
in the stack config, set `buildDocker=None` on `DockerSwarmDeploy`, and let Swarm
resolve and pull the image on target nodes during deploy. Credentials must be
available to the deploy path and the compose image must point to a registry the
runner can push to (e.g. Gitea Container Registry `gitea.rudolf.keenetic.link/<owner>/<repo>`).
+1 -1
View File
@@ -33,7 +33,7 @@ docker service update --secret-rm brencher-secrets brencher_brencher-backend
docker service update --secret-rm brencher-secrets brencher2_brencher-backend
docker secret rm brencher-secrets
printf "GIT_USERNAME=git\nGIT_PASSWORD=TODO\nGITEA_TOKEN=TODO\n" | \
printf "GIT_USERNAME=git\nGIT_PASSWORD=TODO\n" | \
docker secret create brencher-secrets -
docker service update --secret-add brencher-secrets brencher_brencher-backend
-3
View File
@@ -17,6 +17,3 @@
state: str # 'Active' or 'Pause'
pipeline: Dict[str, Any]
+4 -13
View File
@@ -48,30 +48,21 @@ class App:
"name": r.name,
"status": [str(result), stack],
"error": True,
"is_running": False,
"is_running": True,
})
else:
step_state = {
pipeline_state.append({
"name": r.name,
"status": result,
"is_running": False,
}
step_errors = getattr(r, "errors", [])
if step_errors:
step_state["status"] = {"result": result, "errors": step_errors}
step_state["error"] = True
step_warnings = getattr(r, "warnings", [])
if step_warnings and not step_errors:
step_state["status"] = {"result": result, "warnings": step_warnings}
step_state["warning"] = True
pipeline_state.append(step_state)
})
except BaseException as e:
stack = traceback.format_exception(type(e), e, e.__traceback__)
pipeline_state.append({
"name": r.name,
"status": [str(e), stack],
"error": True,
"is_running": False,
"is_running": True,
})
env_dtos[env.id] = {'id': env.id }
env_dtos[env.id]['pipeline'] = pipeline_state
+61
View File
@@ -0,0 +1,61 @@
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.docker import DockerSwarmCheck, DockerSwarmDeploy
from enironment import Environment
from steps.checks import SimpleLog, UrlCheck
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(url="https://github.com/rudolf1/uber_backup.git", branchNamePrefix="photosHelper")
sharedState = SharedStateHolderInMemory(unmerge=None)
checkoutMerged = CheckoutMerged(clone,
desired_branches=sharedState,
push = False,
git_user_email="rudolfss13@gmail.com",
git_user_name="brencher_bot"
)
sharedState.set_branches([("photosHelper/master", "HEAD")])
dockerSwarmCheck = DockerSwarmCheck(
stack_name = "photosHelper",
)
deployDocker = DockerSwarmDeploy(
wd=clone,
buildDocker=None,
stackChecker=dockerSwarmCheck,
envs = lambda: {
"version": "auto-" + checkoutMerged.progress().version
},
stack_name = "photosHelper",
docker_compose_path = "docker-compose.yml",
)
unmerge = GitUnmerge(clone, dockerSwarmCheck)
checkPing = UrlCheck(
url="https://backuper.rudolf.keenetic.link/api/server/ping",
expected = {"res":"pong"},
)
logUrls = SimpleLog(message = {
"userLinks": {
"App": "https://backuper.rudolf.keenetic.link",
}
})
backups_helper = Environment(
id="backupsHelper",
state=sharedState,
pipeline=[
clone,
sharedState,
checkoutMerged,
dockerSwarmCheck,
unmerge,
deployDocker,
checkPing,
logUrls
]
)
+6 -9
View File
@@ -5,10 +5,7 @@ from steps.docker import DockerComposeBuild, DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(remotes=[
{"name": "github", "url": "https://github.com/rudolf1/brencher.git"},
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/brencher"},
])
clone = GitClone(url="https://github.com/rudolf1/brencher.git")
dockerSwarmCheck = DockerSwarmCheck(
stack_name="brencher",
@@ -48,10 +45,10 @@ deployDocker = DockerSwarmDeploy(
docker_compose_path="docker-compose.yml",
)
#checkPing = UrlCheck(
# url="https://brencher.rudolf.keenetic.link/state",
# expected=checkPingF,
#)
checkPing = UrlCheck(
url="https://brencher.rudolf.keenetic.link/state",
expected=checkPingF,
)
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://brencher.rudolf.keenetic.link/",
@@ -71,7 +68,7 @@ brencher = Environment(
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing,
checkPing,
logUrls
]
)
+6 -10
View File
@@ -21,11 +21,7 @@ def checkPingF(obj: Any) -> None:
raise Exception(f"brencher2 check failed for: {v}")
clone = GitClone(remotes=[
{"name": "github", "url": "https://github.com/rudolf1/brencher.git"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/brencher"},
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/brencher"},
])
clone = GitClone(url="https://github.com/rudolf1/brencher.git")
dockerSwarmCheck = DockerSwarmCheck(
stack_name="brencher2",
@@ -76,10 +72,10 @@ deployDocker = DockerSwarmDeploy(
docker_compose_path="docker-compose.yml",
)
#checkPing = UrlCheck(
# url="https://brencher.rudolf.keenetic.link/state",
# expected=checkPingF,
#)
checkPing = UrlCheck(
url="https://brencher.rudolf.keenetic.link/state",
expected=checkPingF,
)
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://brencher.rudolf.keenetic.link/",
@@ -102,7 +98,7 @@ brencher2 = Environment(
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing,
checkPing,
logUrls
],
)
-91
View File
@@ -1,91 +0,0 @@
import os
from enironment import Environment
from steps.actions import GiteaActionsAwait, GiteaActionsTrigger
from steps.checks import SimpleLog
from steps.docker import DockerSwarmCheck, DockerSwarmDeploy
from steps.git import CheckoutMerged, GitClone, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(remotes=[
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/ansible"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/ansible"},
],
credEnvPrefix="GITEA",
)
dockerSwarmCheck = DockerSwarmCheck(stack_name="connectivity_tester")
unmerge = GitUnmerge(clone, dockerSwarmCheck)
state = SharedStateHolderInMemory(unmerge=unmerge)
checkoutMerged = CheckoutMerged(
clone,
desired_branches=state,
push="gitea_admin",
git_user_email="rudolfss13@gmail.com",
git_user_name="brencher_bot",
)
GITEA_API = os.environ.get("GITEA_API", "https://gitea.rudolf.keenetic.link/api/v1")
GITEA_TOKEN = os.environ.get("GITEA_TOKEN", "")
WORKFLOW_OWNER = "admin"
WORKFLOW_REPO = "ansible"
WORKFLOW_FILE = "release.yml"
def _inputs() -> dict:
return {"tag": "auto-" + checkoutMerged.progress().version}
trigger_build = GiteaActionsTrigger(
api_base=GITEA_API,
owner=WORKFLOW_OWNER,
repo=WORKFLOW_REPO,
workflow_file=WORKFLOW_FILE,
ref=lambda: checkoutMerged.progress().remote_branch_name or "master",
token=GITEA_TOKEN,
inputs=_inputs,
wd=checkoutMerged,
)
await_build = GiteaActionsAwait(
api_base=GITEA_API,
owner=WORKFLOW_OWNER,
repo=WORKFLOW_REPO,
token=GITEA_TOKEN,
run=lambda: trigger_build.progress(),
)
deployDocker = DockerSwarmDeploy(
wd=clone,
buildDocker=None,
stackChecker=dockerSwarmCheck,
envs=lambda: {
"version": "auto-" + checkoutMerged.progress().version,
"registry_owner": "admin",
},
stack_name="connectivity_tester",
docker_compose_path="connectivity_tester/stack-compose.yml",
)
logUrls = SimpleLog(message={
"userLinks": {
"Connectivity tester": "http://connectivity-tester.keenetic.link:8765/",
},
})
__all__ = ["connectivity_tester"]
connectivity_tester = Environment(
id="connectivity_tester",
state=state,
pipeline=[
clone,
state,
checkoutMerged,
dockerSwarmCheck,
trigger_build,
await_build,
deployDocker,
logUrls,
],
)
-80
View File
@@ -1,80 +0,0 @@
from enironment import Environment
from steps.checks import SimpleLog, UrlCheck
from steps.docker import DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
# Dual-remote clone for the ansible mirror (the deploy target, not brencher itself).
# - gitea_hermes is where the feature branch lives (hermes/ansible:*)
# - gitea_admin is the live-deploy source (where brencher-bot reads compose files from)
#
# Why not github? github.com is unreachable from the brencher container -- the
# proxy returns HTTP 403 on CONNECT tunnel, so the URL would always fail to
# fetch. See backend/configs/docker_socket_proxy.py for the same migration.
#
# Why drop branchNamePrefix? GitClone only applies its prefix refspec to a
# remote named "origin" (backend/steps/git.py ~L104); neither remote here is
# named "origin", so the prefix would be a silent no-op. Both remotes fetch
# their full refset instead.
#
# Why two remotes? The deploy step (DockerSwarmDeploy) checks out a specific
# branch and uses the resulting checkout as wd for the compose path. With
# gitea_hermes as primary, feature branches opened in the fork are picked up;
# gitea_admin provides the live-deploy source as a fallback / for cross-fork
# PRs. This matches the form in backend/configs/brencher.py after PR #3.
clone = GitClone(remotes=[
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/ansible"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/ansible"},
])
dockerSwarmCheck = DockerSwarmCheck(
stack_name="gitea",
)
unmerge = GitUnmerge(clone, dockerSwarmCheck)
state = SharedStateHolderInMemory(unmerge=unmerge)
checkoutMerged = CheckoutMerged(clone,
desired_branches=state,
push=False,
git_user_email="rudolfss13@gmail.com",
git_user_name="brencher_bot"
)
deployDocker = DockerSwarmDeploy(
wd=clone,
buildDocker=None,
stackChecker=dockerSwarmCheck,
envs=lambda: {
"version": "auto-" + checkoutMerged.progress().version,
},
stack_name="gitea",
docker_compose_path="poc/gitea/stack-compose.yml",
)
# checkPing1 = UrlCheck(
# url="http://100.70.193.97:8087/api/status",
# expected=lambda obj: obj['gateway_running'] == 'true' and obj['auth_required'] == 'true',
# )
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://gitea.rudolf.keenetic.link",
}
})
__all__ = ["gitea"]
gitea = Environment(
id="gitea",
state=state,
pipeline=[
clone,
state,
checkoutMerged,
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing1,
logUrls
]
)
+3 -6
View File
@@ -4,10 +4,7 @@ from steps.docker import DockerComposeBuild, DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(remotes=[
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/mcps"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/mcps"},
])
clone = GitClone(url="https://github.com/rudolf1/uber_backup.git", branchNamePrefix="immoscout")
dockerSwarmCheck = DockerSwarmCheck(
stack_name="gmail_mcp",
@@ -26,7 +23,7 @@ checkoutMerged = CheckoutMerged(clone,
buildDocker = DockerComposeBuild(clone,
docker_repo_username="",
docker_repo_password="",
docker_compose_path="docker-compose.yml",
docker_compose_path="gmail-mcp-server/docker-compose.yml",
docker_repo_url="https://registry.rudolf.keenetic.link",
publish=False,
envs=lambda: {
@@ -42,7 +39,7 @@ deployDocker = DockerSwarmDeploy(
"version": "auto-" + checkoutMerged.progress().version,
},
stack_name="gmail_mcp",
docker_compose_path="docker-compose.yml",
docker_compose_path="gmail-mcp-server/docker-compose.yml",
)
checkPing1 = UrlCheck(
-63
View File
@@ -1,63 +0,0 @@
from enironment import Environment
from steps.checks import SimpleLog
from steps.docker import DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(remotes=[
# {"name": "github", "url": "https://github.com/rudolf1/uber_backup.git", "prefix": "ansible"},
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/ansible"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/ansible"},
])
dockerSwarmCheck = DockerSwarmCheck(
stack_name="hermes",
)
unmerge = GitUnmerge(clone, dockerSwarmCheck)
state = SharedStateHolderInMemory(unmerge=unmerge)
checkoutMerged = CheckoutMerged(clone,
desired_branches=state,
push=False,
git_user_email="rudolfss13@gmail.com",
git_user_name="brencher_bot"
)
deployDocker = DockerSwarmDeploy(
wd=clone,
buildDocker=None,
stackChecker=dockerSwarmCheck,
envs=lambda: {
"version": "auto-" + checkoutMerged.progress().version,
},
stack_name="hermes",
docker_compose_path="poc/hermes/stack-compose.yml",
)
# checkPing1 = UrlCheck(
# url="http://100.70.193.97:8087/api/status",
# expected=lambda obj: obj['gateway_running'] == 'true' and obj['auth_required'] == 'true',
# )
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://hermes.rudolf.keenetic.link",
}
})
__all__ = ["hermes"]
hermes = Environment(
id="hermes",
state=state,
pipeline=[
clone,
state,
checkoutMerged,
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing1,
logUrls
]
)
-94
View File
@@ -1,94 +0,0 @@
from enironment import Environment
from steps.checks import SimpleLog, UrlCheck
from steps.docker import DockerComposeBuild, DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
# Dual-remote clone for the ansible mirror (the deploy target, not brencher itself).
# - gitea_hermes is where the feature branch lives (hermes/ansible:*)
# - gitea_admin is the live-deploy source (where brencher-bot reads compose files from)
#
# Why not github? github.com is unreachable from the brencher container -- the
# proxy returns HTTP 403 on CONNECT tunnel, so the URL would always fail to
# fetch. See backend/configs/docker_socket_proxy.py for the same migration.
#
# Why drop branchNamePrefix? GitClone only applies its prefix refspec to a
# remote named "origin" (backend/steps/git.py ~L104); neither remote here is
# named "origin", so the prefix would be a silent no-op. Both remotes fetch
# their full refset instead.
#
# Why two remotes? The deploy step (DockerSwarmDeploy) checks out a specific
# branch and uses the resulting checkout as wd for the compose path. With
# gitea_hermes as primary, feature branches opened in the fork are picked up;
# gitea_admin provides the live-deploy source as a fallback / for cross-fork
# PRs. This matches the form in backend/configs/brencher.py after PR #3.
clone = GitClone(remotes=[
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/ansible"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/ansible"},
])
dockerSwarmCheck = DockerSwarmCheck(
stack_name="hermes_infra",
)
unmerge = GitUnmerge(clone, dockerSwarmCheck)
state = SharedStateHolderInMemory(unmerge=unmerge)
checkoutMerged = CheckoutMerged(clone,
desired_branches=state,
push=False,
git_user_email="rudolfss13@gmail.com",
git_user_name="brencher_bot"
)
buildDocker = DockerComposeBuild(clone,
docker_repo_username="",
docker_repo_password="",
docker_compose_path="hermes_squid/stack-compose.yml",
docker_repo_url="https://registry.rudolf.keenetic.link",
publish=False,
build_cache = True,
envs=lambda: {
"version": "auto-" + checkoutMerged.progress().version,
# "user_group": "1000:137"
},
)
deployDocker = DockerSwarmDeploy(
wd=clone,
buildDocker=buildDocker,
stackChecker=dockerSwarmCheck,
envs=lambda: {
"version": "auto-" + checkoutMerged.progress().version,
},
stack_name="hermes_infra",
docker_compose_path="hermes_squid/stack-compose.yml",
)
# checkPing1 = UrlCheck(
# url="http://100.70.193.97:8088/api/status",
# expected=lambda obj: obj['gateway_running'] == 'true' and obj['auth_required'] == 'true',
# )
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://hermes.rudolf.keenetic.link",
}
})
__all__ = ["hermes_infra"]
hermes_infra = Environment(
id="hermes_infra",
state=state,
pipeline=[
clone,
state,
checkoutMerged,
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing1,
logUrls
]
)
+6 -27
View File
@@ -4,28 +4,7 @@ from steps.docker import DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
# Dual-remote clone for the ansible mirror (the deploy target, not brencher itself).
# - gitea_hermes is where the feature branch lives (hermes/ansible:*)
# - gitea_admin is the live-deploy source (where brencher-bot reads compose files from)
#
# Why not github? github.com is unreachable from the brencher container -- the
# proxy returns HTTP 403 on CONNECT tunnel, so the URL would always fail to
# fetch. See backend/configs/docker_socket_proxy.py for the same migration.
#
# Why drop branchNamePrefix? GitClone only applies its prefix refspec to a
# remote named "origin" (backend/steps/git.py ~L104); neither remote here is
# named "origin", so the prefix would be a silent no-op. Both remotes fetch
# their full refset instead.
#
# Why two remotes? The deploy step (DockerSwarmDeploy) checks out a specific
# branch and uses the resulting checkout as wd for the compose path. With
# gitea_hermes as primary, feature branches opened in the fork are picked up;
# gitea_admin provides the live-deploy source as a fallback / for cross-fork
# PRs. This matches the form in backend/configs/brencher.py after PR #3.
clone = GitClone(remotes=[
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/ansible"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/ansible"},
])
clone = GitClone(url="https://github.com/rudolf1/uber_backup.git", branchNamePrefix="ansible")
dockerSwarmCheck = DockerSwarmCheck(
stack_name="immich",
@@ -52,10 +31,10 @@ deployDocker = DockerSwarmDeploy(
docker_compose_path="poc/immich/stack-compose.yml",
)
#checkPing = UrlCheck(
# url="https://immich.rudolf.keenetic.link/api/server/ping",
# expected={"res": "pong"},
#)
checkPing = UrlCheck(
url="https://immich.rudolf.keenetic.link/api/server/ping",
expected={"res": "pong"},
)
logUrls = SimpleLog(message={
"userLinks": {
"App": "https://immich.rudolf.keenetic.link",
@@ -73,7 +52,7 @@ immich = Environment(
dockerSwarmCheck,
unmerge,
deployDocker,
# checkPing,
checkPing,
logUrls
]
)
+1 -5
View File
@@ -3,11 +3,7 @@ from steps.docker import DockerComposeBuild, DockerSwarmCheck, DockerSwarmDeploy
from steps.git import GitClone, CheckoutMerged, GitUnmerge
from steps.shared_state import SharedStateHolderInMemory
clone = GitClone(remotes=[
{"name": "github", "url": "https://github.com/rudolf1/reverseproxy.git"},
{"name": "gitea_admin", "url": "https://gitea.rudolf.keenetic.link/admin/reverseproxy"},
{"name": "gitea_hermes", "url": "https://gitea.rudolf.keenetic.link/hermes/reverseproxy"},
])
clone = GitClone(url="https://github.com/rudolf1/reverseproxy.git")
dockerSwarmCheck = DockerSwarmCheck(
stack_name="torrserv_proxy",
-177
View File
@@ -1,177 +0,0 @@
import json
import logging
import os
import time
import urllib.error
import urllib.request
from dataclasses import dataclass
from typing import Any, Callable, Dict, Optional, Union
from enironment import AbstractStep
from steps.git import CheckoutMerged
logger = logging.getLogger(__name__)
@dataclass
class GiteaActionsRun:
run_id: int
status: str
conclusion: Optional[str]
html_url: str
InputsSource = Union[Dict[str, str], Callable[[], Dict[str, str]], None]
RefSource = Union[str, Callable[[], Optional[str]], None]
class GiteaActionsTrigger(AbstractStep[GiteaActionsRun]):
"""Trigger a Gitea Actions workflow via the dispatches API."""
def __init__(self,
api_base: str,
owner: str,
repo: str,
workflow_file: str,
ref: RefSource,
token: str,
inputs: InputsSource = None,
wd: Optional[CheckoutMerged] = None,
poll_timeout_sec: int = 1800,
poll_interval_sec: int = 10,
**kwargs: Any) -> None:
super().__init__(**kwargs)
self.api_base = api_base.rstrip("/")
self.owner = owner
self.repo = repo
self.workflow_file = workflow_file
self.ref = ref
self.token = token
self.inputs = inputs
self.wd = wd
self.poll_timeout_sec = poll_timeout_sec
self.poll_interval_sec = poll_interval_sec
def _http(self, method: str, url: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
data = None
headers = {"Authorization": f"token {self.token}", "Accept": "application/json"}
if body is not None:
data = json.dumps(body).encode()
headers["Content-Type"] = "application/json"
req = urllib.request.Request(url, data=data, headers=headers, method=method)
with urllib.request.urlopen(req, timeout=30) as r:
body_bytes = r.read()
if not body_bytes or r.status == 204:
return {}
return json.loads(body_bytes.decode())
def _list_recent_runs(self) -> Optional[GiteaActionsRun]:
url = f"{self.api_base}/repos/{self.owner}/{self.repo}/actions/runs?limit=1"
try:
data = self._http("GET", url)
except urllib.error.HTTPError as e:
logger.error("list runs failed: %s", e)
return None
items = data.get("workflow_runs") or []
if not items:
return None
r = items[0]
return GiteaActionsRun(
run_id=r["id"],
status=r.get("status", ""),
conclusion=r.get("conclusion"),
html_url=r.get("html_url", ""),
)
def progress(self) -> GiteaActionsRun:
latest = self._list_recent_runs()
resolved_inputs: Dict[str, str] = {}
if callable(self.inputs):
resolved_inputs = self.inputs() or {}
elif isinstance(self.inputs, dict):
resolved_inputs = self.inputs
ref = self.ref() if callable(self.ref) else self.ref
body: Dict[str, Any] = {"ref": ref}
if resolved_inputs:
body["inputs"] = resolved_inputs
url = (
f"{self.api_base}/repos/{self.owner}/{self.repo}"
f"/actions/workflows/{self.workflow_file}/dispatches"
)
try:
self._http("POST", url, body=body)
except urllib.error.HTTPError as e:
if e.code != 500:
raise
raise RuntimeError(
"POST /dispatches returned 500 (gitea-side bug on this instance). "
"Workaround: trigger the workflow manually by pushing a tag matching "
f"the workflow's `on.push.tags` filter, e.g. "
f"`git push <repo> HEAD:refs/tags/auto-<sha>`. "
f"Requested workflow: {self.owner}/{self.repo}/{self.workflow_file}@{ref}"
) from e
deadline = time.time() + self.poll_timeout_sec
while time.time() < deadline:
current = self._list_recent_runs()
if current is None or (latest is not None and current.run_id == latest.run_id):
time.sleep(self.poll_interval_sec)
continue
return current
raise TimeoutError(
f"Gitea Actions did not pick up a new run within {self.poll_timeout_sec}s"
)
class GiteaActionsAwait(AbstractStep[GiteaActionsRun]):
"""Wait for a previously-triggered Gitea Actions run to complete."""
def __init__(self,
api_base: str,
owner: str,
repo: str,
token: str,
run: Callable[[], GiteaActionsRun],
poll_timeout_sec: int = 1800,
poll_interval_sec: int = 10,
**kwargs: Any) -> None:
super().__init__(**kwargs)
self.api_base = api_base.rstrip("/")
self.owner = owner
self.repo = repo
self.token = token
self._run = run
self.poll_timeout_sec = poll_timeout_sec
self.poll_interval_sec = poll_interval_sec
def _http(self, method: str, url: str) -> Dict[str, Any]:
headers = {"Authorization": f"token {self.token}", "Accept": "application/json"}
req = urllib.request.Request(url, headers=headers, method=method)
with urllib.request.urlopen(req, timeout=30) as r:
return json.loads(r.read().decode())
def progress(self) -> GiteaActionsRun:
run = self._run()
deadline = time.time() + self.poll_timeout_sec
while time.time() < deadline:
data = self._http(
"GET",
f"{self.api_base}/repos/{self.owner}/{self.repo}/actions/runs/{run.run_id}",
)
status = data.get("status", "")
conclusion = data.get("conclusion")
if status == "completed":
if conclusion != "success":
raise RuntimeError(
f"Gitea Actions run {run.run_id} concluded with {conclusion}: "
f"{run.html_url}"
)
return GiteaActionsRun(
run_id=run.run_id,
status=status,
conclusion=conclusion,
html_url=run.html_url,
)
time.sleep(self.poll_interval_sec)
raise TimeoutError(
f"Gitea Actions run {run.run_id} did not complete within {self.poll_timeout_sec}s"
)
+6 -72
View File
@@ -1,4 +1,3 @@
import hashlib
import logging
import os
import re
@@ -100,7 +99,7 @@ class DockerComposeBuild(AbstractStep[Dict[str, str]]):
pass
logger.info(f"Building image {image} from {build_ctx}, {build_dockerfile}")
img, _ = client.images.build(path=build_ctx, dockerfile=build_dockerfile, tag=image, nocache=not self.build_cache, rm=True)
img, _ = client.images.build(path=build_ctx, dockerfile=build_dockerfile, tag=image, nocache=not self.build_cache, rm=not self.build_cache)
if self.publish:
logger.info(f"Pushing image {image}")
@@ -198,39 +197,12 @@ class DockerSwarmDeploy(AbstractStep[str]):
content = f.read()
content = re.sub(r'\$\{([^}]+)\}', lambda m: env.get(m.group(1), ""), content)
compose = yaml.safe_load(content)
version = env["version"]
if "configs" in compose:
sanitized_version = re.sub(r'[^a-zA-Z0-9_.-]', '_', version)
full_prefix = f"{self.stack_name}_"
def _config_full_name(base_name: str) -> str:
full = f"{full_prefix}{base_name}_{sanitized_version}"
if len(full) <= 64:
return f"{base_name}_{sanitized_version}"
return hashlib.sha256(full.encode("utf-8")).hexdigest()[:32]
config_names = {
name: _config_full_name(name)
for name in compose["configs"]
}
compose["configs"] = {
config_names.get(name, name): config
for name, config in compose["configs"].items()
}
for service in compose.get("services", {}).values():
for config in service.get("configs", []):
if isinstance(config, str):
config_index = service["configs"].index(config)
service["configs"][config_index] = config_names.get(config, config)
elif isinstance(config, dict) and "source" in config:
config["source"] = config_names.get(config["source"], config["source"])
if "services" in compose:
for svc in compose["services"].values():
if "build" in svc:
del svc["build"]
svc["labels"] = {"org.brencher.version": env["version"]}
del env["version"]
env.pop("registry_owner", None)
merge_dicts(compose, env)
# logger.info(f"Final compose: {compose}")
content = yaml.safe_dump(compose)
@@ -296,8 +268,6 @@ class DockerSwarmDeploy(AbstractStep[str]):
# Deploy stack to Docker Swarm
cmd = [
"docker", "stack", "deploy",
"--with-registry-auth",
"--detach=false",
"--prune",
"-c", tmp_compose_path,
self.stack_name
@@ -309,27 +279,12 @@ class DockerSwarmDeploy(AbstractStep[str]):
swarmEnv = {k: v for k, v in dotenv_values(os.path.join(os.path.dirname(tmp_compose_path), ".env")).items()
if v is not None}
# merge_dicts(swarmEnv, env)
result = subprocess.run(cmd, capture_output=True, text=True, cwd=os.path.dirname(tmp_compose_path))
#, env=swarmEnv)
result = subprocess.run(cmd, capture_output=True, text=True)
# , cwd=os.path.dirname(tmp_compose_path), env=swarmEnv)
os.remove(tmp_compose_path)
logger.info(f"docker stack deploy stdout: {result.stdout or '<empty>'}")
logger.info(f"docker stack deploy stderr: {result.stderr or '<empty>'}")
stderr_lower = result.stderr.lower()
docker_error_markers = (
"failed to ",
"error response from daemon",
"rpc error",
"denied",
"no such image",
)
if result.returncode != 0 or any(marker in stderr_lower for marker in docker_error_markers):
deploy_output = (
f"exit code: {result.returncode}\n"
f"stdout:\n{result.stdout or '<empty>'}\n"
f"stderr:\n{result.stderr or '<empty>'}"
)
logger.error(f"Stack deploy failed:\n{deploy_output}")
raise RuntimeError(f"Stack deploy failed:\n{deploy_output}")
if result.returncode != 0:
logger.error(f"Stack deploy failed: {result.stderr}")
raise RuntimeError(f"Stack deploy failed: {result.stderr}")
logger.info(f"Stack deployed successfully: {result.stdout}")
# Check health of all deployed services
@@ -353,25 +308,4 @@ class DockerSwarmDeploy(AbstractStep[str]):
if not_running:
raise BaseException(f"Services not started yet: {', '.join(not_running)}")
version_mismatches = []
for svc_name, svc in expected_services.items():
full_svc_name = f"{self.stack_name}_{svc_name}"
services_list = client.services.list(filters={"name": full_svc_name})
if not services_list:
continue
service_labels = services_list[0].attrs.get("Spec", {}).get("TaskTemplate", {}).get("ContainerSpec", {}).get("Labels", {})
expected_version = svc.get("labels", {}).get("org.brencher.version")
actual_version = service_labels.get("org.brencher.version")
if expected_version != actual_version:
version_mismatches.append(
f"{full_svc_name} expected version {expected_version}, got {actual_version}"
)
update_status = services_list[0].attrs.get("UpdateStatus", {})
if update_status.get("State") in {"paused", "rollback_paused", "rollback_started"}:
version_mismatches.append(
f"{full_svc_name} Swarm update {update_status.get('State')}: {update_status.get('Message', '')}"
)
if version_mismatches:
raise RuntimeError(f"Deployment did not apply requested versions: {'; '.join(version_mismatches)}")
return f"Stack deployed successfully: {result.stdout}"
-49
View File
@@ -1,49 +0,0 @@
import json
import logging
import os
import re
import subprocess
from typing import Any, Callable, Dict
import yaml
from enironment import AbstractStep
from steps.git import GitClone
logger = logging.getLogger(__name__)
class DockerComposePull(AbstractStep[Dict[str, str]]):
"""Pull images referenced by a docker-compose file from a remote registry."""
def __init__(self,
wd: GitClone,
docker_compose_path: str,
envs: Callable[[], Dict[str, Any]],
**kwargs: Any) -> None:
super().__init__(**kwargs)
self.wd = wd
self.envs = envs
self.docker_compose_path = docker_compose_path
def progress(self) -> Dict[str, str]:
env = self.envs()
compose_path = os.path.join(self.wd.progress(), self.docker_compose_path)
with open(compose_path, "r") as f:
content = f.read()
content = re.sub(r"\$\{([^}]+)\}", lambda m: env.get(m.group(1), ""), content)
compose = yaml.safe_load(content)
for svc in compose.get("services", {}).values():
if "build" in svc:
del svc["build"]
tmp_path = compose_path + ".pull.yml"
with open(tmp_path, "w") as f:
yaml.safe_dump(compose, f)
try:
subprocess.run(
["docker", "compose", "-f", tmp_path, "pull"],
check=True,
cwd=self.wd.progress(),
)
finally:
os.unlink(tmp_path)
return {name: svc.get("image", "") for name, svc in compose.get("services", {}).items()}
+58 -150
View File
@@ -13,65 +13,17 @@ from git.objects import Commit
logger = logging.getLogger(__name__)
AUTO_BRANCH_PREFIX = "auto-"
class GitClone(AbstractStep[str]):
def __init__(self,
url: str | List[str] | None = None,
remotes: List[Dict[str, str]] | None = None,
repo_path: str | None = None,
branchNamePrefix: str = "",
credEnvPrefix: str = "GIT",
def __init__(self, url: str, repo_path: str | None = None,
branchNamePrefix: str = "", credEnvPrefix: str = "GIT",
**kwargs: Any):
super().__init__(**kwargs)
# `remotes` is the explicit form: a list of {"name": "...", "url": "..."}.
# `url` is kept as a shorthand: a single string becomes one remote named
# "origin"; a list of strings becomes remotes named "origin", "repo1",
# "repo2", ... (matches the behavior introduced by the "multiple remotes"
# change so existing positional-list callers keep working).
if remotes is not None and url is not None:
raise ValueError("Pass either 'url' or 'remotes', not both")
normalized: List[Dict[str, str]] = []
if remotes is not None:
seen: Set[str] = set()
for entry in remotes:
if not isinstance(entry, dict):
raise TypeError(
f"Each entry in 'remotes' must be a dict with 'name' and 'url', got {type(entry).__name__}"
)
name = entry.get("name")
url_value = entry.get("url")
if not name or not isinstance(name, str):
raise ValueError("Each remote requires a non-empty 'name' (string)")
if not url_value or not isinstance(url_value, str):
raise ValueError(f"Remote {name!r} requires a non-empty 'url' (string)")
if name in seen:
raise ValueError(f"Duplicate remote name: {name!r}")
seen.add(name)
normalized.append({"name": name, "url": url_value})
elif url is not None:
if isinstance(url, str):
raw = [url]
else:
raw = list(url)
for index, repository_url in enumerate(raw):
name = "origin" if index == 0 else f"repo{index}"
normalized.append({"name": name, "url": repository_url})
else:
raise ValueError("GitClone requires either 'url' or 'remotes'")
if len(normalized) == 0:
raise ValueError("At least one repository URL is required")
self.remotes = normalized
# Derived view used by repo_path keying and any introspection.
self.urls = [r["url"] for r in normalized]
self.url = url
self.repo_path = repo_path
self.branchNamePrefix = branchNamePrefix
self.credEnvPrefix = credEnvPrefix
self.errors: List[str] = []
def _get_auth_git_url(self, url: str) -> str:
username = os.getenv(f'{self.credEnvPrefix}_USERNAME')
@@ -84,53 +36,33 @@ class GitClone(AbstractStep[str]):
return url
def progress(self) -> str:
self.errors = []
repo_url = self.url
self.repo_path = self.repo_path or os.path.join(tempfile.gettempdir(),
f"{self.env.id}_{hashlib.sha1('|'.join(self.urls).encode()).hexdigest()[:5]}")
logger.info(f"Cloning repositories {self.remotes} to {self.repo_path}")
f"{self.env.id}_{hashlib.sha1(repo_url.encode()).hexdigest()[:5]}")
logger.info(f"Cloning repository {repo_url} to {self.repo_path}")
os.makedirs(self.repo_path, exist_ok=True)
try:
if os.path.exists(os.path.join(self.repo_path, ".git")):
logger.info(f"Repository already cloned at {self.repo_path}, fetching updates.")
repo = git.Repo(self.repo_path)
if 'origin' not in repo.remotes or repo.remotes.origin.url != self._get_auth_git_url(repo_url):
repo.create_remote('origin', self._get_auth_git_url(repo_url))
result = repo.remotes.origin.fetch(prune=True)
if not result or any(fetch_info.flags & fetch_info.ERROR for fetch_info in result):
raise BaseException(f"Failed to fetch updates for {repo_url}")
else:
repo = git.Repo.init(self.repo_path)
fetched_remotes = 0
for entry in self.remotes:
remote_name = entry["name"]
repository_url = entry["url"]
try:
auth_url = self._get_auth_git_url(repository_url)
if remote_name in repo.remotes:
remote = repo.remotes[remote_name]
if remote.url != auth_url:
remote.set_url(auth_url)
else:
remote = repo.create_remote(remote_name, auth_url)
with repo.config_writer() as config:
config.set_value(
f'remote "{remote_name}"',
'fetch',
f'+refs/heads/*:refs/remotes/{remote_name}/*',
)
if remote_name == "origin" and self.branchNamePrefix != "":
with repo.config_writer() as config:
config.set_value('remote "origin"', "fetch",
f"+refs/heads/{self.branchNamePrefix}/*:refs/remotes/origin/{self.branchNamePrefix}/*")
result = remote.fetch(prune=True)
if not result or any(fetch_info.flags & fetch_info.ERROR for fetch_info in result):
raise BaseException(f"Failed to fetch updates for {remote_name}")
fetched_remotes += 1
except BaseException as remote_error:
if "File contains no section headers" in str(remote_error):
raise
self.errors.append(f"Unable to fetch remote {remote_name} ({repository_url}): {remote_error}")
logger.warning("Unable to fetch remote %s (%s): %s", remote_name, repository_url, remote_error)
if fetched_remotes == 0:
logger.warning("No configured git remotes are available; keeping the local repository state")
if not os.path.exists(os.path.join(self.repo_path, ".git")):
raise BaseException(f"Failed to clone repositories {self.remotes} to {self.repo_path}")
repo.remotes.append(repo.create_remote(
'origin',
self._get_auth_git_url(repo_url)
))
if self.branchNamePrefix != "":
repo.config_writer().set_value('remote "origin"', "fetch",
f"+refs/heads/{self.branchNamePrefix}/*:refs/remotes/origin/{self.branchNamePrefix}/*").release()
repo.remotes.origin.fetch(prune=True)
if not os.path.exists(os.path.join(self.repo_path, ".git")):
raise BaseException(f"Failed to clone repository {repo_url} to {self.repo_path}")
except BaseException as e:
logger.error(f"Error during git clone/fetch, removing directory {self.repo_path}: {str(e)}")
shutil.rmtree(self.repo_path)
@@ -141,24 +73,21 @@ class GitClone(AbstractStep[str]):
repo = git.Repo(self.repo_path)
result: Dict[str, List[Any]] = {}
for ref in repo.refs:
if not ref.is_remote() or ref.name.endswith('/HEAD'):
continue
remote_name, branch_name = ref.name.split('/', 1)
if branch_name.startswith(AUTO_BRANCH_PREFIX) or branch_name.startswith('auto/'):
continue
branch_key = branch_name if remote_name == 'origin' else ref.name
result[branch_key] = []
cmt = [ref.commit]
for _ in range(10):
for commit in cmt:
result[branch_key].append({
'hexsha': commit.hexsha,
'author': commit.author.name,
'date': commit.committed_datetime.isoformat(),
'message': commit.message.strip()
})
if ref.name.startswith('origin/') and not ref.name.startswith('origin/HEAD'):
branch_name = ref.name[len('origin/'):]
if not branch_name.startswith('auto/'): # Skip auto branches
result[branch_name] = []
cmt = [ref.commit]
for _ in range(10):
for commit in cmt:
result[branch_name].append({
'hexsha': commit.hexsha,
'author': commit.author.name,
'date': commit.committed_datetime.isoformat(),
'message': commit.message.strip()
})
cmt = [p for c in cmt for p in c.parents]
cmt = [p for c in cmt for p in c.parents]
return result
@@ -183,18 +112,6 @@ def ensure_clean(repo: git.Repo) -> None:
raise BaseException(f"Changes in repo: U{repo.untracked_files}")
def _resolve_branch_ref(repo: git.Repo, branch_key: str, default_remote: str) -> str:
# Branch keys can be "branch", "origin/branch", "gitea_admin/branch", etc.
# If the key has a remote prefix that matches a known remote, use it
# verbatim; otherwise fall back to the primary configured remote so
# configs that don't name a remote `origin` still work.
if "/" in branch_key:
remote_name, _ = branch_key.split("/", 1)
if remote_name in repo.remotes:
return branch_key
return f"{default_remote}/{branch_key}"
class CheckoutMerged(AbstractStep[CheckoutAndMergeResult]):
wd: GitClone
@@ -202,7 +119,8 @@ class CheckoutMerged(AbstractStep[CheckoutAndMergeResult]):
desired_branches: AbstractStep[SharedState],
git_user_email: str,
git_user_name: str,
push: bool | str = True,
ignore_missing_branches: bool = True,
push: bool = True,
**kwargs: Any):
super().__init__(**kwargs)
self.wd = wd
@@ -210,7 +128,7 @@ class CheckoutMerged(AbstractStep[CheckoutAndMergeResult]):
self.git_user_email = git_user_email
self.git_user_name = git_user_name
self.push = push
self.ignore_missing_branches = ignore_missing_branches
def _find_merge_childs(self, tree: Dict[Commit, List[Commit]], commit: Commit) -> List[Commit]:
visited = [commit]
@@ -229,23 +147,17 @@ class CheckoutMerged(AbstractStep[CheckoutAndMergeResult]):
def find_desired_commits(self, repo: git.Repo, branches: List[Tuple[str, str]]) -> Dict[Commit, str]:
# Extract commit ids for the selected branches
commit_ids: Dict[Commit, str] = {}
# Default remote: prefer the first remote GitClone was configured with
# (so non-"origin" configs like github/gitea_admin work without the
# caller having to qualify every branch key).
default_remote = "origin"
if isinstance(getattr(self.wd, "remotes", None), list) and self.wd.remotes:
primary = self.wd.remotes[0]["name"]
if primary in repo.remotes:
default_remote = primary
for branch_pair in branches:
try:
branch_name, desired_commit = branch_pair
if desired_commit == 'HEAD':
commit = repo.commit(_resolve_branch_ref(repo, branch_name, default_remote))
commit = repo.commit(f'origin/{branch_name}')
else:
commit = repo.commit(desired_commit)
commit_ids[commit] = branch_name
except BaseException as e:
if not self.ignore_missing_branches:
raise e
stack = traceback.format_exception(type(e), e, e.__traceback__)
logger.error(f"Error finding desired commits for branch {branch_pair}: {str(e)}\n{''.join(stack)}")
return commit_ids
@@ -320,18 +232,16 @@ class CheckoutMerged(AbstractStep[CheckoutAndMergeResult]):
version = '-'.join([x.hexsha[0:8] for x in sorted_commits])
for ref in repo.refs:
if ref.is_remote() and ref.commit == repo.head.commit and not ref.name.endswith('/HEAD'):
if ref.is_remote() and ref.is_valid() and ref.commit == repo.head.commit and ref.name != 'origin/HEAD':
logger.info(f"Merge commit {ref.commit} corresponds to branch {ref}")
remote_name, branch_name = ref.name.split('/', 1)
remote_branch_name = branch_name if remote_name == 'origin' else ref.name
remote_branch_name = ref.name[len('origin/'):]
break
if self.push:
if self.push and remote_branch_name is None:
auto_branch_hash = hashlib.sha1(''.join([x.hexsha for x in sorted_commits]).encode()).hexdigest()
auto_branch_name = f"{AUTO_BRANCH_PREFIX}{version}"
push_remote = self.push if isinstance(self.push, str) else "origin"
auto_branch_name = f"auto-{version}"
logger.info(f"Pushing {repo.head.commit.hexsha} -> {auto_branch_name}")
repo.git.push('-f', push_remote, f"HEAD:refs/heads/{auto_branch_name}")
repo.git.push('-f', 'origin', f"HEAD:refs/heads/{auto_branch_name}")
remote_branch_name = auto_branch_name
return CheckoutAndMergeResult(
@@ -365,12 +275,9 @@ class GitUnmerge(AbstractStep[GitUnmergeResult]):
super().__init__(**kwargs)
self.wd = wd
self.check = check
self.warnings: List[str] = []
def progress(self) -> GitUnmergeResult:
self.warnings = []
wd = self.wd.progress()
repo = git.Repo(wd)
deployState: Mapping[str, HasVersion] = self.check.progress()
versions = set([it.version for it in deployState.values()])
@@ -378,20 +285,20 @@ class GitUnmerge(AbstractStep[GitUnmergeResult]):
raise BaseException(f"Expected exactly one version, got: {versions}")
version = list(versions)[0]
if not version:
return GitUnmergeResult(branches=[], columns={"Deployed": {}})
if version is None:
raise BaseException(f"Expected exactly one version, got: {versions}")
repo = git.Repo(wd)
childs: Dict[Commit, List[Commit]] | None = None
if version.startswith(AUTO_BRANCH_PREFIX):
version_parts = version[len(AUTO_BRANCH_PREFIX):].split('-')
if 'auto-' in version:
version_parts = version[len('auto-'):].split('-')
commits: List[Tuple[str, str]] = []
for v in version_parts:
commit = repo.commit(v)
branches = [ref.name for ref in repo.refs
if ref.is_remote() and not ref.name.endswith('/HEAD') and ref.commit.hexsha == commit.hexsha]
branches = [b[len('origin/'):] if b.startswith('origin/') else b for b in branches]
# branches = [head.name for head in repo.heads if head.commit.hexsha == commit.hexsha]
branches = [ref.name for ref in repo.remotes.origin.refs if not ref.name.startswith('origin/HEAD') and ref.commit.hexsha == commit.hexsha]
branches = [b[len('origin/'):] for b in branches if
b.startswith('origin/') ]
if len(branches) == 0 or branches[0].startswith('auto/'):
if childs is None:
@@ -400,9 +307,10 @@ class GitUnmerge(AbstractStep[GitUnmergeResult]):
while len(commitsSet) > 0:
current = commitsSet.pop()
for child in childs.get(current, []):
branches = [ref.name for ref in repo.refs
if ref.is_remote() and not ref.name.endswith('/HEAD') and ref.commit.hexsha == child.hexsha]
branches = [b[len('origin/'):] if b.startswith('origin/') else b for b in branches]
branches = [ref.name for ref in repo.remotes.origin.refs if
ref.commit.hexsha == child.hexsha]
branches = [b[len('origin/'):] for b in branches if
b.startswith('origin/') and not b.startswith('origin/HEAD')]
if len(branches) > 0:
commitsSet = set()
+2 -5
View File
@@ -42,11 +42,8 @@ class SharedStateHolderInMemory(AbstractStep[SharedState], SharedStateHolder):
def progress(self) -> SharedState:
if len(self.state.branches) == 0:
if self.unmerge:
try:
unmerge = self.unmerge.progress()
self.state = replace(self.state, branches=unmerge.branches, token=uuid.uuid4().hex)
except BaseException as e:
logger.error("Unmerge failed: %s", e)
unmerge = self.unmerge.progress()
self.state = replace(self.state, branches=unmerge.branches, token=uuid.uuid4().hex)
return self.state
+7
View File
@@ -60,3 +60,10 @@ class CachingStep(AbstractStep[T], Generic[T]):
def __getattr__(self, name: str) -> Any:
"""Delegate unknown attributes to the wrapped step."""
return getattr(self._step, name)
def __setattr__(self, name: str, value: Any) -> None:
"""Delegate unknown attributes to the wrapped step."""
if name in {"name", "_step", "_result", "_input_hash"}:
super().__setattr__(name, value)
else:
setattr(self._step, name, value)
+8 -32
View File
@@ -94,15 +94,6 @@ class WebApp:
merged = _merge_dicts(merged, connector.branches)
return merged
def get_selection_summary(self) -> Dict[str, Dict[str, Any]]:
return {
env_id: {
"branches": env.get("branches", []),
"dry": env.get("dry"),
}
for env_id, env in self.get_global_envs_to_emit().items()
}
# --- Async scheduling from sync threads ---
def _schedule_async(self, coro: Any) -> None:
@@ -116,12 +107,12 @@ class WebApp:
disconnected = set()
message = custom_json_dumps({event: data})
for websocket, state in self.ws_connections.items():
if state.get(event) == message:
for websocket in self.ws_connections.keys():
if self.ws_connections[websocket].get(event) == message:
continue
try:
await websocket.send_text(message)
state[event] = message
self.ws_connections[websocket][event] = message
except Exception as e:
logger.error(f"Error sending to websocket: {e}")
disconnected.add(websocket)
@@ -138,7 +129,6 @@ class WebApp:
async def broadcast_environments(self, data: Any) -> None:
await self.broadcast("environments", data)
await self.broadcast("version", self.get_version())
async def broadcast_error(self, data: Any) -> None:
await self.broadcast("error", data)
@@ -150,16 +140,11 @@ class WebApp:
# --- Routes ---
def get_version(self) -> str:
return os.getenv('VERSION', 'unknown') or 'unknown'
async def serve_index(self) -> FileResponse:
return FileResponse(os.path.join(FRONTEND_DIR, 'index.html'))
async def serve_state(self) -> Response:
state = self.get_global_envs_to_emit()
state['version'] = self.get_version()
return Response(content=custom_json_dumps(state), media_type="application/json")
return Response(content=custom_json_dumps(self.get_global_envs_to_emit()), media_type="application/json")
async def serve_branches_route(self) -> Response:
return Response(content=custom_json_dumps(self.get_global_branches_to_emit()), media_type="application/json")
@@ -172,19 +157,16 @@ class WebApp:
async def websocket_endpoint(self, websocket: WebSocket) -> None:
await websocket.accept()
state = self.ws_connections.setdefault(websocket, {})
logger.info("UI connected: selected=%s", self.get_selection_summary())
self.ws_connections[websocket] = {}
try:
# Send initial state on connect and record it so duplicate broadcasts are suppressed
branches_payload = custom_json_dumps({"branches": self.get_global_branches_to_emit()})
envs_payload = custom_json_dumps({"environments": self.get_global_envs_to_emit()})
version_payload = custom_json_dumps({"version": self.get_version()})
await websocket.send_text(version_payload)
await websocket.send_text(branches_payload)
state["branches"] = branches_payload
self.ws_connections[websocket]["branches"] = branches_payload
await websocket.send_text(envs_payload)
state["environments"] = envs_payload
self.ws_connections[websocket]["environments"] = envs_payload
while True:
data = await websocket.receive_text()
@@ -192,12 +174,7 @@ class WebApp:
if "update" in message:
update_data = message.get("update") or {}
logger.info(
"UI selection update: env=%s branches=%s dry=%s",
update_data.get('id', ''),
update_data.get('branches'),
update_data.get('dry'),
)
logger.info(f"Received environment update: {update_data}")
if self.secondaryManager:
await self.secondaryManager.send({"update": update_data})
id = update_data.get('id', '')
@@ -237,7 +214,6 @@ class WebApp:
if isinstance(p, CachingStep):
p.reset()
logger.info(f"Updated environment {env.id} branches to {update_data.get('branches')}, dry={update_data.get('dry')}")
logger.info("UI selection resolved: selected=%s", self.get_selection_summary())
self.core.environment_update_event.set()
await self.broadcast_environments(self.get_global_envs_to_emit())
-1
View File
@@ -1 +0,0 @@
blank1
+1 -2
View File
@@ -16,8 +16,7 @@ services:
- PYTHONUNBUFFERED=1
- VIRTUAL_HOST=brencher.rudolf.keenetic.link
- LETSENCRYPT_HOST=brencher.rudolf.keenetic.link
- VERSION=${version}
- PROFILES=brencher2,torrserv_proxy,immich,gmail_mcp,hermes,hermes_infra,gitea,connectivity_tester
- PROFILES=brencher2,torrserv_proxy,immich,registry,gmail_mcp,backupsHelper
- SECONDARY_BRENCHER=http://host.docker.internal:5002
deploy:
replicas: 1
-148
View File
@@ -1,148 +0,0 @@
# Brencher — backend use cases
## Цель приложения
Brencher получает состояние Git-репозиториев и Docker Swarm, сопоставляет выбранные коммиты с развёрнутым состоянием и запускает pipeline сборки/развёртывания. Этот файл описывает сценарии клиента backend API: запрос, ответ, ошибку и серверный побочный эффект.
## Граница API
- REST endpoint-ы текущего backend: `GET /state`, `GET /branches` и `GET /`/static resources.
- Изменение выбранных веток, применение, dry run и передача UI-событий выполняются через `WebSocket /ws`, а не через REST mutation endpoint.
- Данные API являются состоянием процесса и не образуют постоянное хранилище.
## REST use cases
### B-01. Получить состояние окружений — `GET /state`
1. Клиент отправляет `GET /state`.
2. Backend возвращает JSON с текущей версией, окружениями, выбранными ветками/коммитами, deployed-состоянием и текущими Jobs/pipeline, если они доступны.
3. Если состояние ещё не собрано, ответ содержит начальное/пустое состояние, а pipeline продолжает работу асинхронно.
4. Ошибка backend или недоступное окружение отражается в состоянии соответствующего окружения и логах; REST сам по себе не запускает deploy.
### B-02. Получить доступные ветки — `GET /branches`
1. Клиент отправляет `GET /branches`.
2. Backend возвращает ветки, полученные из настроенных remotes, с remote-префиксами при необходимости.
3. Ответ может измениться после fetch или pipeline update.
4. Ошибка Git/fetch не превращается в успешный полный список и фиксируется как ошибка обработки.
### B-03. Получить веб-приложение — `GET /`
1. Клиент отправляет `GET /`.
2. Backend возвращает `frontend/index.html`; статические CSS/JS-файлы обслуживаются через static route.
3. HTTP-ответ загружает UI, но не устанавливает realtime-соединение: UI отдельно открывает `/ws`.
### B-04. Получить статический ресурс или неизвестный путь
1. Клиент запрашивает путь через HTTP.
2. Backend пытается обслужить файл frontend.
3. Отсутствующий ресурс возвращается как HTTP-ошибка/не найденный ресурс согласно FastAPI/static handler.
## WebSocket-команды, доступные backend-клиенту
Эти сценарии не являются REST, но необходимы для полного описания backend API: текущий код принимает команды по `/ws`.
### B-05. Открыть `/ws` и получить начальное состояние
1. Клиент устанавливает WebSocket-соединение.
2. Backend отправляет сообщения с `version`, `branches` и `environments`.
3. Backend регистрирует соединение и его последнее отправленное состояние.
4. При disconnect соединение удаляется из реестра.
### B-06. Передать обновление выбранного окружения
1. Клиент отправляет JSON-сообщение с изменением `environment`, `branches`/commit selection и параметрами применения.
2. Backend обновляет состояние окружения и запускает соответствующую обработку.
3. Backend рассылает новое состояние подключённым WebSocket-клиентам.
4. Некорректный JSON, неизвестное окружение или ошибка обработки становятся ошибкой WebSocket/pipeline.
### B-07. Запустить применение или dry run
1. Клиент отправляет команду применения с выбранной веткой, `HEAD`, историческим или произвольным commit.
2. Для нескольких веток backend может выполнить merge; конфликт останавливает соответствующий шаг.
3. При dry run backend выполняет анализ и подготовительные шаги, но не должен выполнять финальное развёртывание.
4. Результат, Jobs и ошибка публикуются через WebSocket; отдельного REST endpoint для mutation нет.
## Серверные pipeline use cases
### B-08. Обновить Git-состояние
1. Backend выполняет fetch настроенных Git remotes.
2. Клиент получает новые branches/commits через `/branches` или WebSocket update.
3. Ошибка credentials, сети или отсутствующего remote прерывает зависимые шаги.
4. Для основного профиля `brencher` используются GitHub и `hermes/brencher`; `admin/brencher` не используется. `brencher2` — независимый профиль.
### B-09. Разрешить выбранный commit
1. Backend принимает branch, `HEAD`, исторический или произвольный commit.
2. Проверяет наличие ref/commit и получает соответствующее состояние.
3. Неизвестный ref/commit становится ошибкой pipeline.
4. Имена одинаковых веток разных remotes должны сохранять remote-контекст.
### B-10. Объединить несколько веток
1. Backend получает несколько выбранных источников.
2. Выполняет checkout и merge в рабочем каталоге.
3. При конфликте merge pipeline останавливается и публикует ошибку.
4. Устаревшее состояние токена/выбора может быть отклонено сервером; отдельное structured conflict-сообщение текущий код не гарантирует.
### B-11. Проверить deployed-состояние Swarm
1. Backend обращается к Docker API/socket и читает labels, image/version, stack/service и replica state.
2. Docker Swarm является целью проверки и deploy, а не обязательным исполнителем image build.
3. Недоступный socket, stack или service публикуется как ошибка.
### B-12. Запустить сборку и публикацию образа
1. В конфигурациях, где включён локальный build, backend подготавливает compose/build pipeline.
2. В конфигурациях Actions backend может вызвать Gitea Actions workflow и дождаться его результата; сборка и push выполняются runner-ом.
3. Публикация в registry является условной; в текущем основном `brencher` она отключена (`publish=False`).
4. Ошибка build, workflow, registry или credentials не считается успешным pipeline.
### B-13. Выполнить deploy
1. После успешного pipeline backend выполняет Docker Swarm deploy либо делегирует его настроенному шагу.
2. После deploy проверяет version/labels и replicas.
3. Несовпадение версии или количества replicas публикуется как ошибка/неуспешное состояние.
4. Отдельной rollback-кнопки или гарантированного rollback API нет.
### B-14. Автоматически обнаружить drift
1. `GitUnmerge` сопоставляет deployed label с remote HEAD и desired branches.
2. При отличии backend формирует pipeline автоматически, без UI-команды.
3. При отсутствии diff deploy не выполняется.
4. Конфигурация без корректно подключённого `GitUnmerge` не может самостоятельно восстановить desired branches после перезапуска.
### B-15. Проверить URL health check
1. Настроенный профиль выполняет HTTP GET к сервису.
2. Проверяет HTTP 200, JSON и ожидаемые поля рекурсивно.
3. Несовпадение ответа или недоступность сервиса становится ошибкой health-check шага.
### B-16. Синхронизировать secondary Brencher
1. При заданном `SECONDARY_BRENCHER` backend подключается к отдельному удалённому экземпляру по WebSocket.
2. Передаёт update и объединяет полученные branches/environments с локальными.
3. Конфликт одинаковых environment ID не маскируется.
4. При обрыве выполняются reconnect/retry с задержкой; после исчерпания попыток ошибка пишется в журнал.
## Операционные и security boundaries
### B-17. Запустить разные режимы
1. Оператор задаёт `PROFILES` или CLI-аргумент и может исключить профиль префиксом `-`.
2. `noweb` запускает backend без web UI; глобальный `dry` включает dry run.
3. Порт, конфигурация, secondary URL и credentials задаются внешней конфигурацией.
### B-18. Обработать несколько клиентов
1. Backend хранит несколько WebSocket-соединений.
2. Обновление рассылается подключённым клиентам, если payload изменился; одинаковые payload дедуплицируются для конкретного соединения.
3. Один клиент может увидеть устаревший выбор другого; сервер отклоняет часть stale-состояний, но не предоставляет полноценную блокировку операторов.
### B-19. Зафиксировать границу доступа
1. Backend предоставляет статус и команды управления через web/API layer.
2. В исходном web layer нет встроенной authentication/authorization-проверки.
3. Защита должна обеспечиваться reverse proxy, сетью или внешним механизмом доступа.
4. Нельзя считать открытый endpoint безопасным только потому, что он использует FastAPI/WebSocket.
-368
View File
@@ -1,368 +0,0 @@
# Сценарии, не покрытые тестами
## Цель документа
Этот документ фиксирует сценарии из требований Brencher, для которых в текущем репозитории нет автоматического теста или есть только частичное покрытие. Проверка выполнена по файлам `tests/test_*.py`, тестовой документации и исходникам backend/frontend.
Ссылки `[B-*]` и `[U-*]` ведут на требования в документах:
- [Backend use cases](USE_CASES_BACKEND.md)
- [UI use cases](USE_CASES_UI.md)
- [AGENTS.md](../AGENTS.md) — требования к self-driving/autodeploy-конфигурации
- [tests/README.md](../tests/README.md) — заявленная область существующих integration tests
## Границы текущего покрытия
Покрыты или частично покрыты существующими тестами:
- Git clone, named remotes, validation и восстановление повреждённого local config — `tests/test_git_integration.py`;
- checkout/merge одной, двух и трёх веток, fast-forward, merge conflict и auto branch — `tests/test_git_integration.py`;
- GitUnmerge для valid/invalid version и non-HEAD commit — `tests/test_git_integration.py`;
- stale token на уровне shared state — `tests/test_cached_env.py`, `tests/test_processing_initial_branches.py`;
- apply через UI и повторное появление apply при конфликте — `tests/test_apply_changes.py`;
- dry run и переход к deploy после его выключения — `tests/test_dry_run_playwright.py`;
- отображение deployed column после apply/deploy — `tests/test_deploy_column_playwright.py`;
- кэширование pipeline step — `tests/test_caching_step.py`.
Эти тесты не покрывают весь пользовательский сценарий целиком: например, проверка `GET /state` на HTTP 200 не проверяет все поля ответа, а локальный container test не является тестом Docker Swarm rollout.
## Непокрытые UI-сценарии
### NU-09. Красная рамка toggle-кнопки при проблемном pipeline
**Требование:** [U-06](USE_CASES_UI.md#u-06-отфильтровать-окружения-toggle-кнопками).
Нет автоматического UI-теста, который проверяет:
- красную рамку для окружения с `error`-шагом;
- красную рамку для окружения с `is_running`-шагом;
- отсутствие красной рамки у окружения, где все шаги завершены успешно;
- обновление рамки после WebSocket-сообщения с новым pipeline state;
- сохранение возможности включать и выключать проблемную toggle-кнопку.
## Непокрытые backend-сценарии
### NB-01. Получение главной страницы и static resource
**Требование:** [B-03](USE_CASES_BACKEND.md#b-03-получить-веб-приложение--get) и [B-04](USE_CASES_BACKEND.md#b-04-получить-статический-ресурс-или-неизвестный-путь).
Нет теста, который проверяет:
- `GET /` и наличие `index.html`;
- загрузку `app.js` и `styles.css`;
- ошибку неизвестного static path;
- поведение при недоступном/повреждённом статическом ресурсе.
Связанные исходники: [`backend/web.py`](../backend/web.py), [`frontend/index.html`](../frontend/index.html).
### NB-02. Полный контракт REST `GET /state`
**Требование:** [B-01](USE_CASES_BACKEND.md#b-01-получить-состояние-окружений--get-state).
Существующие тесты проверяют в основном HTTP 200 и отдельные поля. Нет contract-теста на:
- `version`;
- `branches_token`;
- `dry`;
- desired branches/commits;
- deployed columns;
- Jobs и pipeline statuses;
- пустое/начальное состояние;
- ошибку отдельного окружения без падения всего ответа.
Связанные тесты: [`test_deploy_column_playwright.py`](../tests/test_deploy_column_playwright.py), [`test_apply_changes.py`](../tests/test_apply_changes.py).
### NB-03. Полный контракт REST `GET /branches`
**Требование:** [B-02](USE_CASES_BACKEND.md#b-02-получить-доступные-ветки--get-branches).
Нет отдельного REST contract-теста на:
- структуру `{environment: {branch: commits}}`;
- commit objects и их поля;
- несколько remotes и remote-префиксы в HTTP-ответе;
- изменение результата после fetch;
- ошибку Git/fetch.
Связанный код: [`backend/web.py`](../backend/web.py), [`backend/steps/git.py`](../backend/steps/git.py).
### NB-04. WebSocket initial state, malformed messages и unknown environment
**Требования:** [B-05](USE_CASES_BACKEND.md#b-05-открыть-ws-и-получить-начальное-состояние) и [B-06](USE_CASES_BACKEND.md#b-06-передать-обновление-выбранного-окружения).
Playwright-тесты используют WebSocket косвенно, но нет backend-теста на:
- точный порядок/состав initial `version` → `branches` → `environments`;
- несколько клиентов и независимое состояние deduplication;
- malformed JSON;
- неизвестное имя окружения;
- disconnect cleanup;
- ошибку отправки broadcast одному клиенту.
Связанный код: [`backend/web.py`](../backend/web.py).
### NB-05. Git credentials и ошибки внешнего Git
**Требование:** [B-08](USE_CASES_BACKEND.md#b-08-обновить-git-состояние).
Git integration tests работают с локальными repositories и не проверяют:
- authentication failure GitHub/Gitea;
- отсутствие или неправильные `GIT_USERNAME`/`GIT_PASSWORD`;
- network timeout и недоступный remote;
- поведение pipeline после failed fetch;
- сохранение корректного состояния после частично успешного fetch нескольких remotes.
Связанные исходники: [`backend/steps/git.py`](../backend/steps/git.py), [`README.instruction.md`](../README.instruction.md).
### NB-06. Выбор исторического и произвольного commit через backend
**Требование:** [B-07](USE_CASES_BACKEND.md#b-07-запустить-применение-или-dry-run) и [B-09](USE_CASES_BACKEND.md#b-09-разрешить-выбранный-commit).
Тесты проверяют branch/`HEAD` и внутренний Git commit resolution, но нет API/UI integration-теста на:
- исторический commit из branch history;
- произвольный полный или короткий SHA;
- неизвестный ref;
- commit, недоступный в выбранном remote;
- различение одинакового имени branch в разных remotes.
Связанные тесты: [`test_git_integration.py`](../tests/test_git_integration.py), [`docs/USE_CASES_UI.md`](USE_CASES_UI.md).
### NB-07. Swarm state inspection
**Требование:** [B-11](USE_CASES_BACKEND.md#b-11-проверить-deployed-состояние-swarm).
Текущие Playwright-тесты используют обычный Docker container. Нет теста на Docker Swarm API/socket, который проверяет:
- чтение `org.brencher.version` label;
- stack/service image;
- desired и running replicas;
- unavailable stack/service;
- недоступный Docker socket;
- несовпадение deployed version.
Связанный код: [`backend/steps/docker.py`](../backend/steps/docker.py), [`backend/steps/shared_state.py`](../backend/steps/shared_state.py).
### NB-08. Actions workflow, registry и deploy после workflow
**Требования:** [B-12](USE_CASES_BACKEND.md#b-12-запустить-сборку-и-публикацию-образа) и [B-13](USE_CASES_BACKEND.md#b-13-выполнить-deploy).
Нет теста на configuration-dependent Actions flow:
- dispatch Gitea Actions workflow;
- ожидание завершения workflow;
- failed/cancelled workflow;
- credentials registry;
- pull уже опубликованного image на Swarm node;
- `docker stack deploy` и проверку replicas/version после deploy;
- отсутствие локального build/push при `buildDocker=None`.
Требование self-driving pipeline и порядок шагов описаны в [`AGENTS.md`](../AGENTS.md#build-delegation-pattern-actions). Связанные исходники: [`backend/steps/actions.py`](../backend/steps/actions.py), [`backend/steps/docker.py`](../backend/steps/docker.py).
### NB-09. Автоматический drift/autodeploy без UI-команды
**Требование:** [B-14](USE_CASES_BACKEND.md#b-14-автоматически-обнаружить-drift).
GitUnmerge тестируется изолированно, но нет end-to-end теста, который:
1. запускает backend с deployed Swarm label;
2. меняет remote HEAD;
3. ждёт polling cycle;
4. проверяет автоматический pipeline без `environment_update` из UI;
5. проверяет новый image/version и replicas.
Это прямо требуется checklist-ом [`AGENTS.md`](../AGENTS.md#verification-checklist): push branch, дождаться polling cycle и подтвердить redeploy без UI update.
### NB-10. Health check
**Требование:** [B-15](USE_CASES_BACKEND.md#b-15-проверить-url-health-check).
Нет теста на `UrlCheck`/HTTP health-check flow:
- HTTP 200 с ожидаемым JSON;
- неправильный status code;
- невалидный JSON;
- рекурсивное несовпадение expected fields;
- timeout и недоступный service;
- влияние failed health check на pipeline/deploy status.
Связанный код: backend-конфигурации с `UrlCheck` и соответствующий pipeline step.
### NB-11. Secondary Brencher
**Требование:** [B-16](USE_CASES_BACKEND.md#b-16-синхронизировать-secondary-brencher).
Нет теста на `SECONDARY_BRENCHER`:
- подключение к remote `/ws`;
- forwarding update;
- объединение branches/environments;
- duplicate environment ID;
- reconnect и backoff;
- исчерпание retry attempts.
Связанный код: [`backend/secondary.py`](../backend/secondary.py).
### NB-12. Startup modes, profiles и restart recovery
**Требование:** [B-17](USE_CASES_BACKEND.md#b-17-запустить-разные-режимы).
Нет теста на:
- `PROFILES` с несколькими профилями;
- исключение профиля через `-profile`;
- `noweb` headless mode;
- глобальный `dry` startup mode;
- custom port/configuration;
- восстановление state после backend restart;
- отличие локального `brencher2` profile от `SECONDARY_BRENCHER`.
Связанный код: [`backend/app.py`](../backend/app.py), [`backend/discover_envs.py`](../backend/discover_envs.py).
### NB-13. Multi-client concurrency
**Требование:** [B-18](USE_CASES_BACKEND.md#b-18-обработать-несколько-клиентов).
Нет теста на два или более одновременно подключённых клиента:
- broadcast одного update всем клиентам;
- dedup одинакового payload для каждого клиента;
- disconnect одного клиента без влияния на остальные;
- параллельные updates разных окружений;
- race при одновременном изменении одного окружения.
Связанный код: [`backend/web.py`](../backend/web.py).
### NB-14. Security boundary
**Требование:** [B-19](USE_CASES_BACKEND.md#b-19-зафиксировать-границу-доступа).
Нет security integration-теста, который проверяет явно заявленную границу:
- REST endpoints доступны без встроенной auth/authz;
- WebSocket также не требует application-level credentials;
- внешний reverse proxy может ограничить доступ;
- неизвестный/неавторизованный клиент не получает ложный `401` от самого backend.
Связанный код: [`backend/web.py`](../backend/web.py), [`README.instruction.md`](../README.instruction.md).
## Непокрытые UI-сценарии
### NU-01. WebSocket reconnect и отсутствие socket leak
**Требование:** [U-03](USE_CASES_UI.md#u-03-переподключиться-после-разрыва-websocket).
Нет Playwright-теста, который принудительно закрывает socket и проверяет:
- reconnect;
- повторную загрузку initial state;
- отсутствие нескольких параллельных WebSocket instances;
- корректное закрытие старого socket;
- отображение reconnect/disconnected state.
Связанные исходники: [`frontend/app.js`](../frontend/app.js), [`backend/web.py`](../backend/web.py).
### NU-02. Фильтрация окружений toggle-кнопками и текстом
**Требования:** [U-06](USE_CASES_UI.md#u-06-отфильтровать-окружения-toggle-кнопками) и [U-06a](USE_CASES_UI.md#u-06a-отфильтровать-окружения-текстом).
Нет UI-теста на:
- отображение toggle-кнопки для каждого окружения;
- выбор одного и нескольких окружений;
- фильтрацию branches и Jobs/pipeline по выбранным окружениям;
- отображение ссылок, статусов и колонок только выбранных окружений;
- поведение при выключении всех кнопок;
- сохранение выбора при обновлении WebSocket-состояния;
- ввод текстового фильтра, отсутствие совпадений и очистку фильтра;
- то, что фильтры не изменяют backend state.
Связанный исходник: [`frontend/app.js`](../frontend/app.js).
### NU-03. История и произвольный commit в UI
**Требования:** [U-10](USE_CASES_UI.md#u-10-выбрать-исторический-commit) и [U-11](USE_CASES_UI.md#u-11-ввести-произвольный-commit).
Существующие Playwright-тесты выбирают branch/commit из ограниченного сценария, но нет теста на:
- открытие полной commit history;
- исторический commit;
- ручной SHA/ref;
- невалидный commit;
- возврат selection к `HEAD`.
Связанные файлы: [`frontend/app.js`](../frontend/app.js), [`frontend/index.html`](../frontend/index.html).
### NU-04. Merge нескольких branches через UI
**Требование:** [U-13](USE_CASES_UI.md#u-13-объединить-несколько-branches).
Внутренние Git integration tests проверяют merge, но нет Playwright-теста на выбор нескольких branches, отображение selection и показ merge conflict в Jobs/error panel.
Связанные тесты/исходники: [`test_git_integration.py`](../tests/test_git_integration.py), [`frontend/app.js`](../frontend/app.js).
### NU-05. Jobs, pipeline progress и error rendering
**Требование:** [U-15](USE_CASES_UI.md#u-15-наблюдать-jobs-и-pipeline) и [U-18](USE_CASES_UI.md#u-18-увидеть-ошибку-gitcredentialsregistrydockerhealth-check).
Тесты проверяют отдельные конечные состояния, но нет полного UI-теста на:
- все pipeline steps в правильном порядке;
- running → success;
- running → failed;
- текст ошибки и failed step;
- повторный запуск после внешней ошибки;
- registry/Docker/health-check error display.
Связанный исходник: [`frontend/app.js`](../frontend/app.js).
### NU-06. User links
**Требование:** [U-16](USE_CASES_UI.md#u-16-просмотреть-ссылки-сервиса).
Нет теста на получение `userLinks`, наличие ссылок в UI, корректный href и отсутствие выдуманной ссылки при пустом `userLinks`.
Связанные исходники: [`frontend/app.js`](../frontend/app.js), [`frontend/index.html`](../frontend/index.html).
### NU-07. Automatic update reflected in UI
**Требование:** [U-17](USE_CASES_UI.md#u-17-увидеть-автоматический-deploy-без-действия-в-ui).
Нет end-to-end теста, который меняет remote HEAD без UI Update и проверяет отображение нового desired/deployed state и pipeline progress.
Связанный requirement checklist: [`AGENTS.md`](../AGENTS.md#verification-checklist).
### NU-08. Secondary state in UI
**Требование:** [U-20](USE_CASES_UI.md#u-20-работать-с-secondary-brencher).
Нет UI-теста на объединённое состояние local/secondary, duplicate environment conflict, secondary disconnect и отображение reconnect result.
Связанные файлы: [`backend/secondary.py`](../backend/secondary.py), [`frontend/app.js`](../frontend/app.js).
### NU-09. Direct REST diagnostics in UI/browser
**Требование:** [U-21](USE_CASES_UI.md#u-21-просмотреть-состояние-через-прямой-rest-url).
Тесты используют `/state` и `/branches` как вспомогательные API, но нет самостоятельного диагностики-теста, который проверяет:
- открытие endpoint в браузере;
- JSON content type;
- стабильную структуру ответа;
- read-only характер endpoint;
- ошибку недоступного окружения в JSON.
Связанные тесты: [`test_deploy_column_playwright.py`](../tests/test_deploy_column_playwright.py), [`test_containertest.py`](../tests/test_containertest.py).
## Итог
Наиболее критичные пробелы для приоритетного добавления тестов:
1. autodeploy/drift без UI-команды — [B-14](USE_CASES_BACKEND.md#b-14-автоматически-обнаружить-drift), [U-17](USE_CASES_UI.md#u-17-увидеть-автоматический-deploy-без-действия-в-ui);
2. Docker Swarm inspect/deploy и Actions workflow — [B-11](USE_CASES_BACKEND.md#b-11-проверить-deployed-состояние-swarm), [B-12](USE_CASES_BACKEND.md#b-12-запустить-сборку-и-публикацию-образа), [B-13](USE_CASES_BACKEND.md#b-13-выполнить-deploy);
3. WebSocket initial state/reconnect, multi-client и socket leak — [B-05](USE_CASES_BACKEND.md#b-05-открыть-ws-и-получить-начальное-состояние), [B-18](USE_CASES_BACKEND.md#b-18-обработать-несколько-клиентов), [U-03](USE_CASES_UI.md#u-03-переподключиться-после-разрыва-websocket);
4. secondary Brencher — [B-16](USE_CASES_BACKEND.md#b-16-синхронизировать-secondary-brencher), [U-20](USE_CASES_UI.md#u-20-работать-с-secondary-brencher);
5. REST contracts, errors и security boundary — [B-01](USE_CASES_BACKEND.md#b-01-получить-состояние-окружений--get-state), [B-02](USE_CASES_BACKEND.md#b-02-получить-доступные-ветки--get-branches), [B-19](USE_CASES_BACKEND.md#b-19-зафиксировать-границу-доступа).
Отдельное ограничение: `test_containertest.py::test_start` помечен `skip`, поэтому его проверки startup/API не входят в фактически исполняемое покрытие.
-192
View File
@@ -1,192 +0,0 @@
# Brencher — UI use cases
## Цель приложения
Brencher показывает оператору состояние Git-источников и Docker Swarm, позволяет выбрать версию окружения и наблюдать pipeline. Этот файл описывает только пользовательские действия в UI и состояние, которое UI получает от сервера.
## Канал состояния
- После открытия страницы UI устанавливает один WebSocket `/ws`.
- Сервер присылает `version`, `branches` и `environments`, затем рассылает изменения Jobs/pipeline и окружений.
- UI отображает полученное состояние; REST `/state` и `/branches` являются backend read API и не заменяют realtime WebSocket.
- Отдельной UI-кнопки rollback в текущей реализации нет.
## UI use cases
### U-01. Открыть приложение
1. Пользователь открывает `/`.
2. UI загружает HTML, CSS и JavaScript.
3. UI открывает `/ws`.
4. На экране появляются версия приложения, список branches, окружения, выбранные коммиты и Jobs.
5. Если данных ещё нет, UI показывает loading/пустое состояние.
### U-02. Получить начальное состояние
1. После подключения сервер отправляет `version`, `branches` и `environments`.
2. UI заменяет loading данными сервера.
3. Для каждого окружения отображаются desired branches/commits, deployed commit/version и pipeline status.
4. Ошибки окружения показываются как состояние Jobs или error message.
### U-03. Переподключиться после разрыва WebSocket
1. Пользователь остаётся на странице при закрытии или ошибке сокета.
2. UI показывает disconnected/reconnecting state.
3. UI повторяет подключение с задержкой.
4. После нового подключения сервер снова присылает initial state.
5. При повторных соединениях UI не должен считать старое состояние актуальнее нового; фактические ошибки reconnect видны в логах/статусе.
### U-04. Просмотреть окружения и deployed state
1. Пользователь открывает список окружений.
2. UI показывает название, selected/desired commit, deployed commit, version, replicas и текущий шаг pipeline, если эти данные прислал сервер.
3. Пользователь сравнивает desired и deployed state.
4. Недоступное окружение остаётся в списке с ошибкой, а не считается успешно развёрнутым.
### U-05. Просмотреть branches и remote-контекст
1. Пользователь открывает выбор branch.
2. UI показывает branches, полученные от сервера.
3. Одинаковые имена branches разных remotes должны отображаться с контекстом remote.
4. После Git fetch сервер присылает обновлённый список, и UI перерисовывает выбор.
### U-06. Отфильтровать окружения toggle-кнопками
1. UI показывает toggle-кнопку для каждого доступного окружения/стэка.
2. Пользователь включает одну или несколько toggle-кнопок.
3. UI оставляет в branches только выбранные окружения.
4. UI оставляет в Jobs/pipeline только выбранные окружения.
5. Ссылки, статусы и колонки Jobs также относятся только к выбранным окружениям.
6. Если все toggle-кнопки выключены, UI показывает все окружения.
7. Фильтр меняет только отображение и не изменяет серверное состояние.
8. Обновление состояния не должно сбрасывать активный выбор toggle-кнопок, если выбранные окружения всё ещё существуют.
9. Если pipeline окружения содержит хотя бы один неуспешный (`error`) или незаконченный (`is_running`) шаг, соответствующая toggle-кнопка получает красную рамку.
10. Красная рамка обновляется вместе с состоянием pipeline и не изменяет доступность или поведение toggle-кнопки.
### U-06a. Отфильтровать окружения текстом
1. Пользователь вводит текст фильтра.
2. UI оставляет подходящие окружения/стэки.
3. Фильтр меняет только отображение и не изменяет серверное состояние.
4. Очистка фильтра возвращает полный список.
### U-07. Обновить отображаемое состояние
1. Пользователь нажимает refresh/update в UI.
2. UI отправляет серверу соответствующее WebSocket-сообщение либо ожидает очередное состояние pipeline.
3. Сервер присылает branches/environments/jobs.
4. UI обновляет строки, статусы и ошибки.
5. Автоматического UI-таймера каждые пять минут не следует предполагать; обновление может быть pipeline-driven.
### U-08. Выбрать branch
1. Пользователь выбирает branch для окружения.
2. UI меняет локальный selection.
3. При применении selection отправляется серверу через WebSocket.
4. После server update UI отображает выбранное состояние и результат pipeline.
### U-09. Выбрать `HEAD`
1. Пользователь выбирает `HEAD` или текущую вершину branch.
2. UI показывает этот выбор как desired version.
3. При применении сервер разрешает актуальный commit branch.
4. Результат checkout/build/deploy и deployed version приходят в Jobs/state.
### U-10. Выбрать исторический commit
1. Пользователь открывает историю branch.
2. UI показывает доступные commits.
3. Пользователь выбирает конкретный commit.
4. UI отправляет selection при применении.
5. Ошибка отсутствующего commit или merge отображается как ошибка pipeline.
### U-11. Ввести произвольный commit
1. Пользователь вводит commit/ref, если такой control доступен.
2. UI передаёт значение серверу.
3. Сервер проверяет ref/commit и возвращает состояние.
4. Неизвестный commit отображается как ошибка, а не как успешная выбранная версия.
### U-12. Применить выбранное состояние
1. Пользователь выбирает окружение и версию.
2. Нажимает apply/update.
3. UI отправляет команду через WebSocket.
4. UI показывает queued/running/success/error по сообщениям сервера.
5. После завершения показывает selected и deployed state отдельно.
### U-13. Объединить несколько branches
1. Пользователь выбирает несколько branches для одного окружения.
2. UI отображает состав selection.
3. При apply сервер выполняет merge.
4. Успешный результат продолжает pipeline; merge conflict отображается в Jobs/error.
5. Отдельного обещания автоматического разрешения конфликтов UI не даёт.
### U-14. Запустить dry run
1. Пользователь включает dry run.
2. UI отправляет selection с dry-run параметром.
3. UI показывает Git/analysis/build-preparation progress.
4. UI не должен показывать dry run как выполненный deploy.
5. Результат и ограничения dry run приходят от сервера; подготовительные шаги могут выполняться до финального запрета deploy.
### U-15. Наблюдать Jobs и pipeline
1. Пользователь раскрывает Jobs или строку окружения.
2. UI получает и показывает этапы clone, state, checkout/merge, build/workflow, Swarm check и deploy.
3. Для текущего шага отображаются progress/status/log message, если они пришли.
4. Ошибка останавливает визуальный success flow и остаётся видимой для диагностики.
### U-16. Просмотреть ссылки сервиса
1. Сервер присылает `userLinks` в результатах pipeline.
2. UI показывает ссылки на приложение/status или связанные сервисы.
3. Пользователь открывает ссылку в браузере.
4. Если `userLinks` нет, UI не должен придумывать URL.
### U-17. Увидеть автоматический deploy без действия в UI
1. Пользователь не нажимает Update.
2. Сервер обнаруживает, что remote HEAD отличается от deployed label.
3. Сервер запускает pipeline и присылает Jobs/environments update.
4. UI отображает changed desired/deployed state и progress.
5. Если diff нет, UI не показывает ложный deploy.
### U-18. Увидеть ошибку Git/credentials/registry/Docker/health check
1. Пользователь наблюдает Jobs или error panel.
2. UI показывает неуспешный шаг и текст ошибки, если он прислан сервером.
3. Пользователь устраняет внешнюю причину и повторяет update.
4. Наличие error state не считается успешным deploy.
### U-19. Увидеть stale/conflict state
1. Два клиента могут выбирать одно или разные окружения одновременно.
2. Один клиент может получить состояние, устаревшее относительно другого клиента.
3. Сервер может отклонить stale update.
4. UI сохраняет локальный выбор до следующего обновления, если сервер не прислал отдельное conflict message.
5. Structured conflict dialog текущий backend не гарантирует.
### U-20. Работать с secondary Brencher
1. UI получает объединённое состояние локального backend и отдельного secondary Brencher, если `SECONDARY_BRENCHER` настроен.
2. Пользователь видит branches/environments обоих источников согласно данным сервера.
3. Обрыв secondary-соединения отображается как error/stale state.
4. После reconnect UI получает новое initial/update состояние.
5. `brencher2` сам по себе является локальным профилем и не означает наличие secondary-сервера.
### U-21. Просмотреть состояние через прямой REST URL
1. Пользователь открывает `/state` или `/branches` в браузере/инструменте.
2. Сервер возвращает JSON.
3. Это read-only диагностика и не заменяет UI-соединение `/ws`.
4. Изменение selection через эти GET endpoint-ы не выполняется.
## Ограничения UI
- UI не предоставляет отдельного rollback control.
- UI не делает постоянное хранилище: после перезапуска backend in-memory state может исчезнуть.
- Реальный deploy зависит от Git, credentials, Docker socket, registry, Swarm и настроек pipeline.
- В web layer нет встроенной authentication/authorization; безопасность UI должна обеспечиваться внешним reverse proxy или сетью.
- Разные профили запускаются через backend configuration; UI отображает только состояние, которое backend прислал.
+10 -75
View File
@@ -13,8 +13,6 @@ const closeStatus = document.getElementById('close-status');
const refreshBranchesBtn = document.getElementById('refresh-branches');
const applyChangesBtn = document.getElementById('apply-changes');
const branchFilter = document.getElementById('branch-filter');
const envFilterToggles = document.getElementById('env-filter-toggles');
const appVersion = document.getElementById('app-version');
// Branches list (flattened) for UI rendering: [{ envId, envName, branch, commits: [] }]
let branches = [];
@@ -22,7 +20,6 @@ let filteredBranches = [];
// Toggle state: show all branches or filtered
let showAllBranches = false;
const activeEnvFilters = new Set();
// Environment runtime state storage:
// environmentsRaw: array as received from backend: [ [envObj, jobsArr], ... ]
@@ -70,7 +67,6 @@ function checkForPendingChanges() {
function filterBranches() {
const filterText = branchFilter.value.toLowerCase().trim();
filteredBranches = branches.filter(({envId, branch, commits}) => {
if (activeEnvFilters.size > 0 && !activeEnvFilters.has(envId)) return false;
const selList = selectedBranchesByEnv[envId] || [];
const isSelected = selList.some(([b]) => b === branch);
// Always show branches that appear in any column (e.g. deployed branches from GitUnmerge)
@@ -89,41 +85,6 @@ function filterBranches() {
renderBranches();
}
function environmentHasPipelineProblem(envObj) {
return Array.isArray(envObj.pipeline) && envObj.pipeline.some(job =>
job && (job.error || job.is_running)
);
}
function renderEnvironmentFilters() {
const environments = environmentsRaw
.filter(envObj => envObj && (envObj.id || envObj.name))
.map(envObj => ({id: envObj.id || envObj.name, name: envObj.name || envObj.id}))
.sort((a, b) => a.name.localeCompare(b.name));
const environmentIds = new Set(environments.map(env => env.id));
[...activeEnvFilters].forEach(envId => {
if (!environmentIds.has(envId)) activeEnvFilters.delete(envId);
});
envFilterToggles.innerHTML = environments.map(({id, name}) => {
const hasPipelineProblem = environmentHasPipelineProblem(
environmentsRaw.find(envObj => (envObj.id || envObj.name) === id) || {}
);
return `
<button type="button" class="env-filter-toggle${activeEnvFilters.has(id) ? ' active' : ''}${hasPipelineProblem ? ' has-pipeline-problem' : ''}" data-env="${escapeHtml(id)}" aria-pressed="${activeEnvFilters.has(id)}"${hasPipelineProblem ? ' title="Pipeline has failed or unfinished steps"' : ''}>${escapeHtml(name)}</button>
`;
}).join('');
envFilterToggles.querySelectorAll('.env-filter-toggle').forEach(button => {
button.onclick = () => {
const envId = button.dataset.env;
if (activeEnvFilters.has(envId)) activeEnvFilters.delete(envId);
else activeEnvFilters.add(envId);
renderEnvironmentFilters();
filterBranches();
renderJobs();
};
});
}
function getCommitDropdownOptions(envId, branchName, desiredCommit) {
const branchObj = branches.find(b => b.envId === envId && b.branch === branchName);
let options = '';
@@ -194,7 +155,12 @@ function renderBranches() {
}
checkForPendingChanges();
const branchesToShow = filteredBranches.length > 0 || branchFilter.value.trim() || activeEnvFilters.size > 0 ? filteredBranches : branches;
const branchesToShow = filteredBranches.length > 0 || branchFilter.value.trim() ? filteredBranches : branches;
if (!branchesToShow.length) {
branchesList.innerHTML = '<p class="loading">No branches found.</p>';
return;
}
// Group by envId for clearer separation
const groups = branchesToShow.reduce((acc, b) => {
acc[b.envId] = acc[b.envId] || {envName: b.envName, rows: []};
@@ -202,30 +168,18 @@ function renderBranches() {
return acc;
}, {});
environmentsRaw
.filter(envObj => envObj && (activeEnvFilters.size === 0 || activeEnvFilters.has(envObj.id || envObj.name)))
.forEach(envObj => {
const envId = envObj.id || envObj.name;
if (!groups[envId]) groups[envId] = {envName: envObj.name || envId, rows: []};
});
if (!Object.keys(groups).length) {
branchesList.innerHTML = '<p class="loading">No branches found.</p>';
return;
}
branchesList.innerHTML = Object.entries(groups).map(([envId, {envName, rows}]) => {
const envCols = columnsByEnv[envId] || {};
const colNames = Object.keys(envCols);
return `
<div class="env-block">
<h3 class="env-title">
Environment: ${escapeHtml(envName || envId)}
Environment: ${envName || envId}
<button class="dry-run-btn ${dryRunByEnv[envId] ? 'dry-run-active' : ''}" data-env="${envId}" title="${dryRunByEnv[envId] ? 'Dry run on — click to resume' : 'Running — click to pause (dry run)'}">
${dryRunByEnv[envId] ? '▶' : '⏸'}
</button>
</h3>
${rows.length ? `<table class="branches-table">
<table class="branches-table">
<thead>
<tr>
<th>Deploy</th>
@@ -256,7 +210,7 @@ function renderBranches() {
</tr>`;
}).join('')}
</tbody>
</table>` : '<p class="loading">No branches found.</p>'}
</table>
</div>`;
}).join('');
// Event wiring
@@ -328,12 +282,7 @@ function renderJobs() {
jobsList.innerHTML = '<p class="loading">No jobs found.</p>';
return;
}
const visibleEnvironments = environmentsRaw.filter(envObj => activeEnvFilters.size === 0 || activeEnvFilters.has(envObj.id || envObj.name));
if (visibleEnvironments.length === 0) {
jobsList.innerHTML = '<p class="loading">No jobs found.</p>';
return;
}
jobsList.innerHTML = visibleEnvironments
jobsList.innerHTML = environmentsRaw
.slice()
.sort((a, b) => (a.name || a.id || '').localeCompare(b.name || b.id || ''))
.map((envObj) => {
@@ -376,7 +325,6 @@ function renderJobs() {
const storageKey = 'jobSpoiler:' + key;
const safeId = 'spoiler-' + encodeURIComponent(key).replace(/[^a-zA-Z0-9_-]/g, '_');
const isError = job.error;
const isWarning = job.warning;
const isRunning = !!job.is_running;
const openByDefault = isError || (window._jobSpoilerState && window._jobSpoilerState[storageKey] === 'open');
@@ -388,8 +336,6 @@ function renderJobs() {
? `<span class="step-spinner" title="Running"></span>`
: isError
? `<span style="color:#dc3545;font-weight:bold;margin-right:6px;" title="Error">!</span>`
: isWarning
? `<span style="color:#d99700;font-weight:bold;margin-right:6px;" title="Warning">⚠</span>`
: `<span style="color:#28a745;font-weight:bold;margin-right:6px;" title="OK">✔</span>`}
${envObj.id} - ${job.name}
</div>
@@ -479,7 +425,6 @@ function setupWebSockets() {
const data = message.environments;
payload = data || {};
environmentsRaw = Object.values(payload);
renderEnvironmentFilters();
// Sync selections and column data per environment
environmentsRaw.forEach((envObj) => {
@@ -532,8 +477,6 @@ function setupWebSockets() {
filterBranches();
renderJobs();
showStatus('Environments updated.');
} else if ('version' in message) {
appVersion.textContent = `Version: ${message.version || 'unknown'}`;
} else if ('error' in message) {
console.error('Error from server:', message.error);
if (message.error && message.error.code === 'BRANCH_STATE_CONFLICT' && message.error.envId) {
@@ -586,14 +529,6 @@ function updateEnvironment() {
showStatus('Changes applied (pending server confirmation).');
}
// Initial load
(function applyUrlFilter() {
const params = new URLSearchParams(window.location.search);
const initialFilter = params.get('filter');
if (initialFilter && branchFilter) {
branchFilter.value = initialFilter;
filterBranches();
}
})();
setupWebSockets();
showStatus('Loading branches...');
renderBranches();
-2
View File
@@ -10,7 +10,6 @@
<div class="container">
<header>
<h1>Brencher - Branch Merger</h1>
<p class="version" id="app-version">Version: loading...</p>
<div id="status-bar" class="status-bar hidden">
<span id="status-message"></span>
<button id="close-status">×</button>
@@ -24,7 +23,6 @@
<input type="text" id="branch-filter"
placeholder="Filter branches by name, commit ID, or commit message..." class="filter-input">
</div>
<div id="env-filter-toggles" class="env-filter-toggles" aria-label="Environment filters"></div>
<div class="control-bar" style="float: left;">
<button id="toggle-show-all" class="toggle-button">Show All</button>
</div>
-36
View File
@@ -15,13 +15,6 @@ body {
padding: 32px;
}
.version {
color: #6c757d;
font-family: monospace;
font-size: 0.85rem;
margin-top: -12px;
}
.primary-button {
background: #007bff;
color: #fff;
@@ -136,35 +129,6 @@ body {
box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
}
.env-filter-toggles {
display: flex;
flex-wrap: wrap;
gap: 8px;
clear: both;
padding: 8px 0;
}
.env-filter-toggle {
background: #fff;
color: #495057;
border: 1px solid #adb5bd;
border-radius: 4px;
padding: 8px 14px;
cursor: pointer;
font-size: 0.9rem;
}
.env-filter-toggle:hover,
.env-filter-toggle.active {
background: #007bff;
color: #fff;
border-color: #007bff;
}
.env-filter-toggle.has-pipeline-problem {
border: 2px solid #dc3545;
}
/* Branches table styling */
.branches-table {
width: 100%;
-4
View File
@@ -11,7 +11,3 @@ types-PyYAML
types-requests
types-docker
testcontainers
+1 -129
View File
@@ -5,12 +5,10 @@ These tests run in a Docker-like isolated environment to avoid harming the host
They simulate remote and local git repositories and test various merge scenarios.
"""
import os
import shutil
import tempfile
import git
import pytest
from steps.git import CheckoutAndMergeResult, GitClone, GitUnmergeResult
from steps.git import CheckoutAndMergeResult, GitUnmergeResult
from .test_remote_repo import RemoteRepoHelper
@@ -18,123 +16,6 @@ from .test_remote_repo import RemoteRepoHelper
class TestGitIntegration:
"""Integration tests for git operations"""
def test_git_clone_multiple_urls(self, repo_helper: RemoteRepoHelper) -> None:
repo_helper.create_commit(repo_helper.repo, "master", "master", "README.md", "content", "Initial commit")
second_url = f"file://{repo_helper.remote_dir}"
clone = GitClone(url=[repo_helper.remote_dir, second_url])
clone.env = repo_helper.env
repo_path = clone.progress()
repo = git.Repo(repo_path)
assert {remote.name for remote in repo.remotes} == {"origin", "repo1"}
assert repo.remotes.origin.url == repo_helper.remote_dir
assert repo.remotes.repo1.url == second_url
assert set(clone.get_branches()) == {"master", "repo1/master"}
def test_git_clone_filters_auto_branches(self, repo_helper: RemoteRepoHelper) -> None:
repo_helper.create_commit(repo_helper.repo, "master", "master", "README.md", "content", "Initial commit")
repo_helper.create_commit(repo_helper.repo, "master", "feature", "feature.txt", "feature", "Feature commit")
repo_helper.create_commit(repo_helper.repo, "master", "auto-abc12345", "auto.txt", "auto", "Auto commit")
clone = GitClone(url=repo_helper.remote_dir)
clone.env = repo_helper.env
clone.progress()
assert set(clone.get_branches()) == {"master", "feature"}
def test_git_clone_named_remotes(self, repo_helper: RemoteRepoHelper) -> None:
# Two real local repos served as separate "remotes". The user controls
# their names explicitly via the `remotes=[{name,url}]` API.
def fresh_repo(prefix: str, message: str) -> str:
path = tempfile.mkdtemp(prefix=prefix)
repo = git.Repo.init(path, bare=False)
with repo.config_writer() as cw:
cw.set_value("user", "email", "test@example.com")
cw.set_value("user", "name", "Test User")
repo_helper.create_commit(repo, "master", "master", "README.md", "content", message)
return path
github_dir = fresh_repo("test_named_github_", "github initial")
gitea_dir = fresh_repo("test_named_gitea_", "gitea initial")
try:
clone = GitClone(remotes=[
{"name": "github", "url": github_dir},
{"name": "gitea_admin", "url": gitea_dir},
])
clone.env = repo_helper.env
repo_path = clone.progress()
repo = git.Repo(repo_path)
# User-chosen names appear exactly; the auto-generated "origin" /
# "repo1" names from the positional-list form do NOT leak in.
assert {r.name for r in repo.remotes} == {"github", "gitea_admin"}
assert "origin" not in repo.remotes
assert "repo1" not in repo.remotes
assert repo.remotes.github.url == github_dir
assert repo.remotes.gitea_admin.url == gitea_dir
# `get_branches` keeps the <remote>/<branch> shape for non-origin
# names; the user gets the full provenance in the key.
assert set(clone.get_branches()) == {"github/master", "gitea_admin/master"}
finally:
shutil.rmtree(github_dir, ignore_errors=True)
shutil.rmtree(gitea_dir, ignore_errors=True)
def test_git_clone_keeps_available_remote_when_another_is_unreachable(self, repo_helper: RemoteRepoHelper) -> None:
repo_helper.create_commit(repo_helper.repo, "master", "master", "README.md", "content", "Initial commit")
clone = GitClone(remotes=[
{"name": "available", "url": repo_helper.remote_dir},
{"name": "unreachable", "url": "/does/not/exist"},
])
clone.env = repo_helper.env
clone.progress()
assert "available/master" in clone.get_branches()
assert len(clone.errors) == 1
assert "unreachable" in clone.errors[0]
def test_git_clone_keeps_empty_repository_when_all_remotes_are_unreachable(self, repo_helper: RemoteRepoHelper) -> None:
clone = GitClone(url="/does/not/exist")
clone.env = repo_helper.env
repo_path = clone.progress()
assert os.path.isdir(os.path.join(repo_path, ".git"))
assert clone.get_branches() == {}
def test_git_clone_remotes_validation(self) -> None:
# Empty list: rejected (would produce an unusable clone).
with pytest.raises(ValueError, match="At least one repository URL is required"):
GitClone(remotes=[])
# Missing / empty / non-string name or url: rejected.
with pytest.raises(ValueError, match="non-empty 'name'"):
GitClone(remotes=[{"url": "git@example.com:foo/bar.git"}])
with pytest.raises(ValueError, match="non-empty 'name'"):
GitClone(remotes=[{"name": "", "url": "git@example.com:foo/bar.git"}])
with pytest.raises(ValueError, match="non-empty 'url'"):
GitClone(remotes=[{"name": "github"}])
with pytest.raises(ValueError, match="non-empty 'url'"):
GitClone(remotes=[{"name": "github", "url": ""}])
# Duplicate name: rejected.
with pytest.raises(ValueError, match="Duplicate remote name"):
GitClone(remotes=[
{"name": "github", "url": "git@example.com:a/b.git"},
{"name": "github", "url": "git@example.com:c/d.git"},
])
# Passing both `url` and `remotes`: rejected.
with pytest.raises(ValueError, match="not both"):
GitClone(url="git@example.com:a/b.git", remotes=[{"name": "github", "url": "git@example.com:a/b.git"}])
# Passing neither: rejected.
with pytest.raises(ValueError, match="requires either 'url' or 'remotes'"):
GitClone()
def test_checkout_merged_one_branch(self, repo_helper: RemoteRepoHelper) -> None:
# Create main branch with initial commit
commit1 = repo_helper.create_commit(repo_helper.repo, "master", "master", "file1.txt", "content1",
@@ -370,15 +251,6 @@ class TestGitIntegration:
with pytest.raises(BaseException, match="Version format not recognized"):
repo_helper.git_unmerge.progress()
def test_git_unmerge_empty_version_uses_default_branch(self, repo_helper: RemoteRepoHelper) -> None:
repo_helper.create_commit(repo_helper.repo, "master", "master", "file1.txt", "content", "Initial commit")
repo_helper.set_desired_branches([])
repo_helper.mock_check.version = lambda: "" # type: ignore[attr-defined]
result = repo_helper.git_unmerge.progress()
assert result.branches == [()]
def test_git_unmerge_nonhead_commit(self, repo_helper: RemoteRepoHelper) -> None:
# Create initial commit
commit1 = repo_helper.create_commit(repo_helper.repo, "master", "master", "file1.txt", "content1",
+61
View File
@@ -0,0 +1,61 @@
from git import BadName
import pytest
from enironment import get_step
from steps.git import CheckoutMerged
from tests.conftest import repo_helper
from .test_remote_repo import RemoteRepoHelper
class TestGitRemoveBranch:
"""Integration tests for git operations"""
def test_checkout_merged_one_branch(self, repo_helper: RemoteRepoHelper) -> None:
# Create main branch with initial commit
commit1 = repo_helper.create_commit(repo_helper.repo, "master", "master", "file1.txt", "content1",
"Initial commit") # noqa: F841
commit2 = repo_helper.create_commit(repo_helper.repo, "master", "branch1", "file2.txt", "content2",
"Branch1 commit") # noqa: F841
commit3 = repo_helper.create_commit(repo_helper.repo, "master", "branch2", "file3.txt", "content3",
"Branch2 commit") # noqa: F841
repo_helper.enable_caching()
repo_helper.set_desired_branches([("branch1", "HEAD"), ("branch2", "HEAD")])
repo_helper.progress()
repo_helper.verify_working_directory_files([
('file1.txt', 'content1'),
('file2.txt', 'content2'),
('file3.txt', 'content3'),
])
assert repo_helper.checkout_merged.progress().version == '-'.join([it[:8] for it in sorted([commit2.hexsha, commit3.hexsha])])
repo_helper.remove_branch(repo_helper.repo, "branch2")
# CheckoutMerged should raise an error when it can't find the branch, and ignore_missing_branches is False
get_step(repo_helper.env.pipeline, CheckoutMerged).ignore_missing_branches = False
with pytest.raises(BadName, match="Ref 'origin/branch2' did not resolve to an object"):
repo_helper.progress()
assert repo_helper.get_desired_branches() == [("branch1", "HEAD"), ("branch2", "HEAD")]
with pytest.raises(BadName, match="Ref 'origin/branch2' did not resolve to an object"):
repo_helper.checkout_merged.progress()
# Now set ignore_missing_branches to True and verify that it ignores the missing branch and continues processing
get_step(repo_helper.env.pipeline, CheckoutMerged).ignore_missing_branches = True
repo_helper.progress()
assert repo_helper.get_desired_branches() == [("branch1", "HEAD"), ("branch2", "HEAD")]
assert repo_helper.checkout_merged.progress().version == '-'.join([it[:8] for it in [commit2.hexsha]])
# Removing missing branch should be processed well
repo_helper.set_desired_branches([("branch1", "HEAD")])
repo_helper.progress()
assert repo_helper.checkout_merged.progress().version == '-'.join([it[:8] for it in [commit2.hexsha]])
repo_helper.verify_working_directory_files([
('file1.txt', 'content1'),
('file2.txt', 'content2'),
])
+27 -7
View File
@@ -10,8 +10,8 @@ import tempfile
from typing import Dict, Tuple, List, Callable, cast
import git
from enironment import Environment, AbstractStep, SharedStateHolder, get_step
from enironment import Environment, AbstractStep, wrap_in_cached, get_step, SharedStateHolder
from processing import reset_caches
from steps.docker import DockerSwarmCheckResult
from steps.git import CheckoutAndMergeResult, CheckoutMerged, GitUnmerge, GitClone, HasVersion, GitUnmergeResult
from steps.shared_state import SharedStateHolderInMemory
@@ -106,6 +106,22 @@ class RemoteRepoHelper:
def mock_check(self) -> AbstractStep[Dict[str, HasVersion]]:
return get_step(self.env.pipeline, MockDockerSwarmCheck)
def enable_caching(self) -> None:
"""Wrap environment pipeline in caching steps"""
self.env = wrap_in_cached(self.env)
def progress(self) -> None:
reset_caches([self.env])
for i in self.env.pipeline:
i.progress()
def remove_branch(self, repo: git.Repo, branch_name: str) -> None:
"""Remove a branch from the repository"""
if branch_name in [head.name for head in repo.heads]:
repo.delete_head(branch_name, force=True)
else:
raise BaseException(f"Branch doesn't exist {branch_name}.")
def teardown(self) -> None:
"""Clean up temporary directories"""
if self.remote_dir:
@@ -142,7 +158,9 @@ class RemoteRepoHelper:
with open(file_path, 'w') as f:
f.write(content)
repo.index.add([filename])
return repo.index.commit(message)
result = repo.index.commit(message)
repo.git.checkout(result.hexsha, detach=True)
return result
def verify_working_directory_files(self, expected_files: List[Tuple[str, str]]) -> None:
"""Verify that working directory contains exactly the expected files with correct content.
@@ -168,10 +186,12 @@ class RemoteRepoHelper:
repo = git.Repo(repo_path)
commits = list(repo.iter_commits("--all", max_count=30))
refs = [
f"{_as_text(it.commit)[:10]}:{_as_text(it.name)}, is_remote:{it.is_remote()}"
for it in repo.refs
]
refs = []
for it in repo.references:
try:
refs.append(f"{_as_text(it.commit)[:10]}:{_as_text(it.name)}, is_remote:{it.is_remote()}")
except Exception as e:
refs.append(f"Error reading branch {it.name}: {e}")
lines = [
f"{_as_text(commit.hexsha)[:10]} (p{[_as_text(it.hexsha)[:10] for it in commit.parents]}): {_as_text(commit.message).splitlines()[0]}"
for commit in commits