Skip to content

Add deploy workflow and add/update some documentations.#75

Merged
wpak-ai merged 7 commits into
cppalliance:developfrom
AuraMindNest:feature/deploy
May 29, 2026
Merged

Add deploy workflow and add/update some documentations.#75
wpak-ai merged 7 commits into
cppalliance:developfrom
AuraMindNest:feature/deploy

Conversation

@AuraMindNest
Copy link
Copy Markdown
Collaborator

@AuraMindNest AuraMindNest commented May 29, 2026

Close #67, close #68, close #69.

Summary by CodeRabbit

  • New Features

    • Automated deployment pipeline configured to deploy to staging environment after successful CI runs
    • Environment configuration template added for streamlined deployments
  • Documentation

    • Comprehensive deployment runbook added with step-by-step setup and troubleshooting guidance
    • README significantly enhanced with Quick Start, architecture overview, Celery worker requirements, and CI/CD pipeline documentation
    • CI/CD workflow documentation created
  • Chores

    • Weblate dependency updated to version 2026.5

Review Change Stack

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 29, 2026

Warning

Review limit reached

@AuraMindNest, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 25 minutes and 30 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5e3709fe-b5de-45ba-ad3b-8279eeed227d

📥 Commits

Reviewing files that changed from the base of the PR and between b9f84c3 and 860b18c.

📒 Files selected for processing (10)
  • .env.example
  • .github/workflows/cd.yml
  • README.md
  • docker/README.md
  • docker/docker-compose.cd.yml
  • docker/docker-compose.ci.yml
  • docs/deployment-runbook.md
  • pyproject.toml
  • scripts/integration-functional.sh
  • tests/integration/test_functional.py
📝 Walkthrough

Walkthrough

This PR implements a complete continuous deployment pipeline for cppa-weblate-plugin: it refactors CI workflows into reusable patterns, introduces a new CD workflow that chains off successful CI runs, adds comprehensive environment and deployment documentation, and updates integration test infrastructure to support the new deployment architecture.

Changes

CI/CD Pipeline Refactoring and Deployment

Layer / File(s) Summary
Environment template with annotated deployment variables
.env.example
.env.example provides comprehensive placeholders for Weblate deployment: core settings (debug, title, domain, URL prefix), authentication (LDAP), PostgreSQL and Redis configuration, mail credentials, GitHub VCS integration, optional social auth/monitoring, nginx overrides, and Celery worker setup.
Reusable CI workflow refactoring and main orchestrator
.github/workflows/ci-lint.yml, .github/workflows/ci-test.yml, .github/workflows/ci-package.yml, .github/workflows/ci-dependencies.yml, .github/workflows/ci-combination-*.yml, .github/workflows/ci.yml
Converts lint, test, package, dependencies, and combination-smoke/functional/auth workflows from direct push/PR triggers to reusable workflow_call patterns with explicit permissions, consistent naming, and updated artifact names. Introduces ci.yml orchestrator that runs all reusable workflows in parallel on push/PR to main/develop with secret inheritance for functional tests.
CD deployment workflow with health checks
.github/workflows/cd.yml
New workflow triggers after successful CI on develop via workflow_run, SSHes to server, pulls latest code, runs docker compose build && up -d with CD compose file and .env, polls /weblate/healthz/ for ~180 seconds with bounded retries, and dumps logs on failure. Uses concurrency control per branch to prevent overlapping deployments.
CD Docker Compose configuration
docker/docker-compose.cd.yml, docker/docker-compose.ci.yml
Adds docker-compose.cd.yml defining overlay weblate service that builds from Dockerfile.weblate-plugin, loads .env, binds to localhost-only port, enforces required secrets via ${VAR:?set in .env}, connects to external Redis network, and includes healthcheck. Updates docker-compose.ci.yml header to clarify CI/integration-test purpose.
CI/CD workflow and Docker documentation
.github/README.md, docker/README.md
Adds .github/README.md documenting workflow responsibilities and callable workflow patterns. Updates docker/README.md with separate CI and CD compose examples, .env workflow, and environment variable guidance for nginx path prefix and shared Redis DB selection.
Deployment runbook
docs/deployment-runbook.md
Comprehensive guide covering host prerequisites, one-time PostgreSQL setup, .env creation, Docker build/start, healthcheck behavior, Weblate plugin validation endpoints, post-deploy checks (QuickBook format, Celery worker), automated CD flow, and troubleshooting with symptom/cause/remedy pairs.
README with Quick Start and CI/CD documentation
README.md
Restructures Quick Start with local dev steps and separated Docker guidance. Updates Architecture diagram and module descriptions. Clarifies HTTP route activation prerequisites and WEBLATE_URL_PREFIX effects. Expands Celery requirement and task documentation. Adds "CI / CD Pipelines" section with workflow descriptions and environment references.

Integration Test Infrastructure Updates

Layer / File(s) Summary
Compose file defaults and GitHub SSH host key setup
scripts/lib/compose.sh, scripts/lib/weblate-stack.sh, scripts/integration-functional.sh, tests/integration/lib/docker_exec.py
Updates compose file defaults to reference CI-specific compose. Adds stack_ensure_github_known_hosts() to seed GitHub host keys in container via ssh-keyscan. Updates integration-functional.sh to call host key setup after stack health. Updates docker_exec.py to reference CI compose file.
Ephemeral GitHub repo branch creation and naming
tests/integration/lib/gh_repo.py
Adds ensure_branch() method to query default branch and create missing branches via Git refs API. Updates push_fixtures() to use the helper. Refactors default_repo_name() with new naming prefix and truncated suffix logic.
Functional test assertions for result validation
tests/integration/test_functional.py
Adds _assert_process_all_ok() helper to validate process_all result structure. Updates component creation, idempotency, and Celery add-or-update tests to apply the new validation helper.
Project configuration and script headers
pyproject.toml, scripts/README.md
Bumps Weblate[all] dependency to version 2026.5. Includes .env.example in build source-include. Adds SPDX license header to scripts/README.md.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

  • docs/deployment-runbook.md #68: Implements the deployment runbook file docs/deployment-runbook.md with step-by-step deployment guide, health check validation, and troubleshooting procedures that fulfill deployment documentation requirements.
  • README completion #69: Completes README documentation updates covering Quick Start, architecture, Celery worker verification, and CI/CD pipeline sections referenced in project documentation improvements.

Possibly related PRs

  • cppalliance/cppa-weblate-plugin#51: Overlaps on CI workflow refactoring for lint, test, dependencies, and package workflows with consistent naming and structure updates.
  • cppalliance/cppa-weblate-plugin#73: Updates the same integration functional test entrypoint and assertions in test_functional.py that validate in-container and Celery flows.
  • cppalliance/cppa-weblate-plugin#72: Extends the integration test stack helpers introduced in that PR by adding GitHub SSH host key seeding in scripts/lib/weblate-stack.sh.

Suggested reviewers

  • henry0816191

Poem

A pipeline flows from push to deploy,
Reusable workflows bring developer joy!
🐇 From lint to test, each check runs free,
Health polls and logs keep sanity—
CD awaits on the staging spree! 🚀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title references 'deploy workflow' and 'documentations', which align with the main changes (CD workflow, docker compose files, deployment runbook, and README updates).
Linked Issues check ✅ Passed All acceptance criteria from #67 are met: CD workflow created with workflow_run trigger, SSH deploy, health checks, Docker compose setup, .env.example template, and CI workflow renames completed.
Out of Scope Changes check ✅ Passed All changes are scoped to #67 objectives: CD workflow setup, Docker compose files, environment template, documentation, and CI helper updates. No unrelated changes detected.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@AuraMindNest AuraMindNest requested a review from henry0816191 May 29, 2026 08:45
Comment thread .github/workflows/cd.yml
Comment thread .github/workflows/cd.yml Outdated
Comment thread .env.example Outdated
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (3)
.github/workflows/ci.yml (2)

13-15: ⚡ Quick win

Scope actions: write to the jobs that actually need it.

At the workflow level this grants artifact/cancel permissions to lint, test, package, and dependency-audit too, even though the write path is only needed by the combination jobs that upload failure artifacts. Move actions: write down to those jobs and keep the default permission read-only.

♻️ Suggested permission scoping
 permissions:
-  actions: write
   contents: read

 jobs:
   lint:
     uses: ./.github/workflows/ci-lint.yml
   test:
     uses: ./.github/workflows/ci-test.yml
   package:
     uses: ./.github/workflows/ci-package.yml
   dependencies:
     uses: ./.github/workflows/ci-dependencies.yml
   combination-smoke:
+    permissions:
+      actions: write
+      contents: read
     uses: ./.github/workflows/ci-combination-smoke.yml
   combination-functional:
+    permissions:
+      actions: write
+      contents: read
     uses: ./.github/workflows/ci-combination-functional.yml
     secrets: inherit
   combination-auth:
+    permissions:
+      actions: write
+      contents: read
     uses: ./.github/workflows/ci-combination-auth.yml
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 13 - 15, The workflow currently sets
permissions at the top-level with "permissions: actions: write" which
unnecessarily grants write to all jobs; change the top-level permissions block
to keep actions read-only ("permissions: actions: read" and contents: read) and
remove actions: write there, then add a scoped "permissions: actions: write"
only to the specific jobs that perform artifact uploads (the jobs that run
upload-artifact/cancel steps) by adding a per-job permissions block in those job
definitions; ensure job-level permission blocks reference "actions: write" and
leave other jobs to inherit the default read-only permissions.

28-30: ⚡ Quick win

Pass only GH_TEST_REPO_TOKEN instead of inheriting all secrets.

ci-combination-functional.yml declares a single optional secret and only reads that one. secrets: inherit unnecessarily exposes every caller-available secret to this job.

🔐 Suggested secret narrowing
   combination-functional:
     uses: ./.github/workflows/ci-combination-functional.yml
-    secrets: inherit
+    secrets:
+      GH_TEST_REPO_TOKEN: ${{ secrets.GH_TEST_REPO_TOKEN }}
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/ci.yml around lines 28 - 30, The job
combination-functional currently uses secrets: inherit which exposes all caller
secrets to the called workflow; change it to pass only the GH_TEST_REPO_TOKEN
secret to the reusable workflow (ci-combination-functional.yml) by replacing the
inherit usage with an explicit single-secret mapping for GH_TEST_REPO_TOKEN so
only that secret is forwarded.
.github/workflows/cd.yml (1)

47-52: 💤 Low value

Health check timing is correct but documentation is inconsistent.

The implementation correctly uses 36 iterations (180s total), matching the Docker Compose healthcheck grace period (60s start_period + 12×10s retries = 180s). This prevents false-negative deploy failures during slow migrations.

However, docs/deployment-runbook.md still documents the old 24-iteration/120s behavior and needs to be updated to reflect the current 36-iteration/180s implementation.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/cd.yml around lines 47 - 52, Update the docs to reflect
the current Weblate health-check timing: the workflow uses the shell loop "for i
in $(seq 1 36)" hitting "/weblate/healthz/" (36 iterations = 180s total), so
change any references to the old 24-iteration/120s values to 36 iterations /
180s in deployment-runbook.md and any related documentation, ensuring the
documented rationale matches the Docker Compose healthcheck (start_period +
retries).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docker/docker-compose.cd.yml`:
- Line 32: The healthcheck uses a hardcoded path in the test command (the CMD
entry that runs curl) which breaks when WEBLATE_URL_PREFIX changes; update the
test healthcheck CMD to construct the URL using the WEBLATE_URL_PREFIX
environment variable (e.g., concatenate localhost:8080 with
${WEBLATE_URL_PREFIX} before /weblate/healthz/) so the curl call follows the
configured prefix and avoids false-unhealthy deployments.

In `@docker/docker-compose.ci.yml`:
- Line 6: The CI command example is invalid because "&& up" is not a standalone
command; update the comment to show a runnable sequence such as running the
build then a full compose up (e.g., use "docker compose -f
docker/docker-compose.ci.yml build && docker compose -f
docker/docker-compose.ci.yml up") or a single command with build ("docker
compose -f docker/docker-compose.ci.yml up --build") so the copy-paste example
works.

In `@docker/README.md`:
- Around line 22-25: The CD example in the README runs "docker compose -f
docker/docker-compose.cd.yml --env-file .env up -d" directly which can deploy
stale images; update the snippet to run an explicit build step first by invoking
"docker compose -f docker/docker-compose.cd.yml --env-file .env build" (or
"docker compose build -f docker/docker-compose.cd.yml --env-file .env") before
the "up -d" command so the images are rebuilt prior to bringing services up.

In `@scripts/integration-functional.sh`:
- Around line 35-36: Gate the GitHub SSH known_hosts seeding behind the GitHub
test toggle by only running the echo and stack_ensure_github_known_hosts when
the GH_TEST_REPO_TOKEN (the GitHub-backed tests toggle) is set/true; modify the
script to check the environment variable (GH_TEST_REPO_TOKEN) or an existing
enable-GitHub flag before calling stack_ensure_github_known_hosts so outbound
ssh-keyscan to github.com only happens when GitHub tests are enabled.

In `@tests/integration/test_functional.py`:
- Around line 35-44: The helper _assert_process_all_ok currently treats a
successful submodule as failing if components_created + components_updated == 0;
update the function so it no longer conflates success with mutation by removing
or disabling the assertion that enforces created + updated > 0 (leave the
existing checks that failed == 0, that results is non-empty, and that each
entry.get("success") is True intact). Modify the logic in _assert_process_all_ok
to only assert on the success flag and existing container structure so
idempotent/no-op successful runs (e.g., in TestAddOrUpdateCeleryFlow) do not
trigger false negatives.

---

Nitpick comments:
In @.github/workflows/cd.yml:
- Around line 47-52: Update the docs to reflect the current Weblate health-check
timing: the workflow uses the shell loop "for i in $(seq 1 36)" hitting
"/weblate/healthz/" (36 iterations = 180s total), so change any references to
the old 24-iteration/120s values to 36 iterations / 180s in
deployment-runbook.md and any related documentation, ensuring the documented
rationale matches the Docker Compose healthcheck (start_period + retries).

In @.github/workflows/ci.yml:
- Around line 13-15: The workflow currently sets permissions at the top-level
with "permissions: actions: write" which unnecessarily grants write to all jobs;
change the top-level permissions block to keep actions read-only ("permissions:
actions: read" and contents: read) and remove actions: write there, then add a
scoped "permissions: actions: write" only to the specific jobs that perform
artifact uploads (the jobs that run upload-artifact/cancel steps) by adding a
per-job permissions block in those job definitions; ensure job-level permission
blocks reference "actions: write" and leave other jobs to inherit the default
read-only permissions.
- Around line 28-30: The job combination-functional currently uses secrets:
inherit which exposes all caller secrets to the called workflow; change it to
pass only the GH_TEST_REPO_TOKEN secret to the reusable workflow
(ci-combination-functional.yml) by replacing the inherit usage with an explicit
single-secret mapping for GH_TEST_REPO_TOKEN so only that secret is forwarded.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 584e084e-1746-4bf3-83f9-639e364ca20a

📥 Commits

Reviewing files that changed from the base of the PR and between 6c26e45 and b9f84c3.

⛔ Files ignored due to path filters (1)
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (24)
  • .env.example
  • .github/README.md
  • .github/workflows/cd.yml
  • .github/workflows/ci-combination-auth.yml
  • .github/workflows/ci-combination-functional.yml
  • .github/workflows/ci-combination-smoke.yml
  • .github/workflows/ci-dependencies.yml
  • .github/workflows/ci-lint.yml
  • .github/workflows/ci-package.yml
  • .github/workflows/ci-test.yml
  • .github/workflows/ci.yml
  • README.md
  • docker/README.md
  • docker/docker-compose.cd.yml
  • docker/docker-compose.ci.yml
  • docs/deployment-runbook.md
  • pyproject.toml
  • scripts/README.md
  • scripts/integration-functional.sh
  • scripts/lib/compose.sh
  • scripts/lib/weblate-stack.sh
  • tests/integration/lib/docker_exec.py
  • tests/integration/lib/gh_repo.py
  • tests/integration/test_functional.py

Comment thread docker/docker-compose.cd.yml Outdated
Comment thread docker/docker-compose.ci.yml Outdated
Comment thread docker/README.md
Comment thread scripts/integration-functional.sh Outdated
Comment thread tests/integration/test_functional.py Outdated
@AuraMindNest AuraMindNest requested a review from henry0816191 May 29, 2026 15:48
@AuraMindNest AuraMindNest requested a review from wpak-ai May 29, 2026 15:57
@wpak-ai wpak-ai merged commit 724e4b0 into cppalliance:develop May 29, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README completion docs/deployment-runbook.md CD workflow (deploy.yml)

3 participants