From 276e9bc5dc79de3666215f7796dd9f6956e51c2e Mon Sep 17 00:00:00 2001
From: Jeffrey Boadi <viprapp@gmail.com>
Date: Wed, 18 Feb 2026 17:10:59 +0100
Subject: [PATCH] feat(docs): added ci doc for the app project

---
 docs/projects/app/ci.md | 115 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/projects/app/ci.md

diff --git a/docs/projects/app/ci.md b/docs/projects/app/ci.md
new file mode 100644
index 0000000..32311ef
--- /dev/null
+++ b/docs/projects/app/ci.md
@@ -0,0 +1,115 @@
+# App CI (Stage 3)
+
+This repo uses GitHub Actions to ensure every PR is validated and every merge to
+`main` produces a deployable artifact.
+
+## Goals (Stage 3)
+
+- PRs: fail fast on docs + workflow mistakes, and prove the app still boots.
+- main: publish a container image to GHCR.
+
+## Workflows involved
+
+- `.github/workflows/ci.yml`
+  - Lints GitHub Actions workflows (actionlint)
+  - Docs quality checks (markdownlint + lychee)
+  - PR-only: build container + smoke test via Docker Compose
+
+- `.github/workflows/publish-image.yml`
+  - Builds the app image
+  - Pushes to GHCR on `main`
+
+## What runs on pull requests
+
+### 1) Workflow lint: actionlint
+
+Purpose: catch invalid inputs, typos, wrong action parameters, invalid contexts,
+and similar mistakes before merge.
+
+Where: `ci.yml` job `actionlint`
+
+Expected outcome:
+
+- Workflow YAML is valid
+- Incorrect action inputs are rejected (for example, passing `context` to
+  `docker/setup-buildx-action`, which does not support it)
+
+### 2) Docs quality gates
+
+Where: `ci.yml` job `docs-quality`
+
+- Markdown lint (format consistency)
+- Link check (keeps repo clean)
+
+### 3) App container: build + smoke test
+
+Where: `ci.yml` job `app-container-pr`
+
+Steps:
+
+1. Build the app image with Buildx (`docker/build-push-action`) and load it into
+   the runner Docker daemon.
+2. Start the Compose stack from `projects/app/`.
+3. Validate the HTTP health endpoint.
+
+Smoke test commands (conceptually):
+
+- `docker compose up -d --wait`
+- `docker compose ps`
+- `curl http://localhost:8000/healthz`
+
+Notes:
+
+- The curl check can fail if the app container is still starting even though
+  Compose has started the container. The job should rely on service health and
+  /or retry the curl check briefly.
+
+## What runs on push to main
+
+### Publish container image to GHCR
+
+Where: `publish-image.yml`
+
+Image name:
+
+- `ghcr.io/<owner>/<repo>/app`
+
+Tags:
+
+- `latest`
+- `sha-<git-sha>` (or `sha` tag style produced by metadata-action)
+
+Authentication:
+
+- Uses `GITHUB_TOKEN` with `packages: write`
+
+## Artifacts produced
+
+- GHCR container image:
+  - `ghcr.io/viprapp/jevops/app:latest`
+  - `ghcr.io/viprapp/jevops/app:sha-...`
+
+## How to verify quickly
+
+### Check CI on a PR
+
+- Open the PR
+- Ensure these checks pass:
+  - actionlint
+  - docs-quality
+  - app - build + smoke test (PR)
+
+### Check publish on main
+
+- Merge PR to `main`
+- Confirm `publish-image` workflow run succeeded
+- Confirm tags exist in GHCR for the repo
+
+## Common issues and how we catch them
+
+- Wrong paths (for example wrong Dockerfile path):
+  - Caught by actionlint (workflow validation) and by the container build step
+- Wrong action inputs:
+  - Caught by actionlint (example: invalid inputs to setup-buildx-action)
+- Compose starts but app not ready yet (curl reset/refused):
+  - Fix by waiting for health or adding small curl retry loop