Skip to content

Commit e0eb2da

Browse files
authored
Merge pull request #84: dev and main deployment workflow
Route checked dev pushes to isolated staging and promote reviewed releases to main.
2 parents e0bdb58 + bf41955 commit e0eb2da

21 files changed

Lines changed: 469 additions & 13 deletions

‎.github/dependabot.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ version: 2
33
# updates, when enabled in the repository settings, do not follow this schedule.
44
updates:
55
- package-ecosystem: npm
6+
target-branch: dev
67
directory: /
78
schedule:
89
interval: monthly
@@ -38,6 +39,7 @@ updates:
3839
update-types:
3940
- version-update:semver-major
4041
- package-ecosystem: nuget
42+
target-branch: dev
4143
# Dependabot expands ProCoderJi.slnx here, covering the API and test projects
4244
# together so shared .NET packages can move in one reviewed pull request.
4345
directory: /backend
@@ -56,6 +58,7 @@ updates:
5658
- minor
5759
- patch
5860
- package-ecosystem: github-actions
61+
target-branch: dev
5962
directory: /
6063
schedule:
6164
interval: monthly
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import assert from "node:assert/strict";
2+
import test from "node:test";
3+
import { branchPolicy } from "./check-branch-policy.mjs";
4+
5+
const repository = "procoderji-com/procoderji";
6+
const check = (base, head, sourceRepository = repository) => branchPolicy({ base, head, sourceRepository, repository });
7+
8+
test("contributors and bots can send changes to dev", () => {
9+
assert.equal(check("dev", "feat/student-experience", "contributor/procoderji"), null);
10+
assert.equal(check("dev", "dependabot/npm_and_yarn/example"), null);
11+
});
12+
13+
test("main accepts only the canonical dev branch", () => {
14+
assert.equal(check("main", "dev"), null);
15+
assert.ok(check("main", "feat/student-experience"));
16+
assert.ok(check("main", "dependabot/npm_and_yarn/example"));
17+
assert.ok(check("main", "dev", "contributor/procoderji"));
18+
});
19+
20+
test("unknown or absent targets do not silently pass", () => {
21+
assert.ok(check("release/1.0", "dev"));
22+
assert.ok(check(undefined, undefined));
23+
assert.ok(branchPolicy({ base: "main", head: "dev" }));
24+
});
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { pathToFileURL } from "node:url";
2+
3+
export function branchPolicy({ base, head, sourceRepository, repository }) {
4+
if (!base || !head || !sourceRepository || !repository) return "Pull-request branch metadata is incomplete.";
5+
if (base === "dev") return null;
6+
if (base === "main" && head === "dev" && sourceRepository === repository) return null;
7+
if (base === "main") {
8+
return "Production PRs must promote this repository's dev branch. Send feature and dependency PRs to dev first.";
9+
}
10+
return "Contributions target dev; production promotions target main.";
11+
}
12+
13+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
14+
const failure = branchPolicy({
15+
base: process.env.PR_BASE,
16+
head: process.env.PR_HEAD,
17+
sourceRepository: process.env.PR_SOURCE_REPOSITORY,
18+
repository: process.env.TARGET_REPOSITORY,
19+
});
20+
if (failure) {
21+
console.error(failure);
22+
process.exitCode = 1;
23+
} else {
24+
console.log("Branch policy passed.");
25+
}
26+
}

‎.github/workflows/backend-containers.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ on:
1212
- 'vercel.backend.json'
1313
- '.github/workflows/backend-containers.yml'
1414
push:
15-
branches: [main]
15+
branches: [dev, main]
1616
paths:
1717
- 'backend/**'
1818
- 'shared/**'
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Branch policy
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened, edited, ready_for_review]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
branch-policy:
12+
name: Branch policy
13+
runs-on: ubuntu-24.04
14+
timeout-minutes: 5
15+
steps:
16+
- name: Check out proposed policy
17+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
18+
with:
19+
persist-credentials: false
20+
21+
- name: Test branch policy
22+
run: node --test .github/scripts/branch-policy.test.mjs
23+
24+
- name: Enforce contribution and promotion targets
25+
env:
26+
PR_BASE: ${{ github.event.pull_request.base.ref }}
27+
PR_HEAD: ${{ github.event.pull_request.head.ref }}
28+
PR_SOURCE_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
29+
TARGET_REPOSITORY: ${{ github.repository }}
30+
run: node .github/scripts/check-branch-policy.mjs

‎.github/workflows/ci.yml‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,16 @@ name: CI
33
on:
44
pull_request:
55
push:
6-
branches: [main]
6+
branches: [dev, main]
77
workflow_dispatch:
88

99
permissions:
1010
contents: read
1111

1212
concurrency:
1313
group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
14-
cancel-in-progress: true
14+
# Cancel stale PR checks, but never interrupt a push run during a deployment.
15+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
1516

1617
jobs:
1718
verify:
@@ -148,3 +149,43 @@ jobs:
148149
ConnectionStrings__Platform: 'Host=localhost;Port=5432;Database=procoderji_test;Username=postgres;Password=postgres'
149150
PublicOrigin: http://localhost:3000
150151
run: dotnet run --project backend/src/ProCoderJi.Api --configuration Release --no-build --no-launch-profile -- --migrate
152+
153+
deploy:
154+
name: Deploy checked branch
155+
permissions:
156+
contents: read
157+
deployments: write
158+
needs: [verify, site-quality, backend]
159+
if: github.event_name == 'push' && github.repository == 'procoderji-com/procoderji' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main')
160+
runs-on: ubuntu-24.04
161+
timeout-minutes: 20
162+
environment:
163+
name: ${{ github.ref_name == 'main' && 'production' || 'staging' }}
164+
url: ${{ vars.PUBLIC_ORIGIN }}
165+
concurrency:
166+
group: deploy-${{ github.ref_name }}
167+
cancel-in-progress: false
168+
steps:
169+
- name: Check out checked commit
170+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
171+
with:
172+
persist-credentials: false
173+
174+
- name: Set up Node.js
175+
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
176+
with:
177+
node-version: 24
178+
179+
- name: Install deployment CLI
180+
run: npm install --global vercel@65.14.0
181+
182+
- name: Deploy backend, verify storage, then deploy frontend
183+
env:
184+
VERCEL_ORG_ID: ${{ vars.VERCEL_ORG_ID }}
185+
VERCEL_FRONTEND_PROJECT_ID: ${{ vars.VERCEL_FRONTEND_PROJECT_ID }}
186+
VERCEL_BACKEND_PROJECT_ID: ${{ vars.VERCEL_BACKEND_PROJECT_ID }}
187+
PUBLIC_ORIGIN: ${{ vars.PUBLIC_ORIGIN }}
188+
BACKEND_ORIGIN: ${{ vars.BACKEND_ORIGIN }}
189+
VERCEL_FRONTEND_TOKEN: ${{ secrets.VERCEL_FRONTEND_TOKEN }}
190+
VERCEL_BACKEND_TOKEN: ${{ secrets.VERCEL_BACKEND_TOKEN }}
191+
run: node scripts/deploy-vercel.mjs

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,13 @@ fork as `origin`, and continue from the same checkout.
5353

5454
## Start a branch
5555

56-
Update your local `main` before starting a new change:
56+
Update your local `dev` before starting a new change:
5757

5858
```bash
59-
git switch main
6059
git fetch upstream
61-
git merge --ff-only upstream/main
62-
git push origin main
60+
git switch dev
61+
git merge --ff-only upstream/dev
62+
git push origin dev
6363
git switch -c feat/describe-the-change
6464
```
6565

@@ -120,11 +120,16 @@ git commit -m "Describe the change"
120120
git push -u origin <your-branch-name>
121121
```
122122

123-
Open a pull request from your fork branch to `procoderji-com/procoderji:main`. Fill in the
123+
Open a pull request from your fork branch to `procoderji-com/procoderji:dev`. Fill in the
124124
template, link a related issue when one exists, explain the resulting behavior, and list the
125125
checks you ran.
126126
Include screenshots for visible UI changes and sources or permissions for learning content.
127127

128+
`dev` is the integration/staging branch; `main` is production. Feature and dependency changes
129+
go through `dev`. Maintainers promote the canonical `dev` branch to `main` after staging checks;
130+
contributors do not send feature branches directly to `main`. See the
131+
[branch and deployment workflow](docs/branching-and-releases.md).
132+
128133
Respond to review feedback and keep the branch up to date when needed. Maintainers review
129134
student value, correctness, accessibility, and maintenance cost before merging. A proposed
130135
feature may need a smaller scope or further discussion.

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ synchronization is a separate capability; paid billing is future work.
2222
| Import a portfolio from a text template | [Markdown import](portfolio-markdown.md), [template](../public/templates/portfolio.md) |
2323
| Work on portfolio fields, policy, publication, or storage | [Shared rules](../shared/portfolio/README.md), [Portfolio API](portfolio-api.md) |
2424
| Configure production hosting and the site domain | [Deployment](deployment.md) |
25+
| Contribute to dev, test staging and promote a production release | [Branches and releases](branching-and-releases.md) |
2526
| Run the API and choose a database with Docker | [Containers](containers.md) |
2627
| Configure the selected hosted PostgreSQL database | [Neon setup](neon.md) |
2728
| Report a vulnerability privately | [Security policy](../SECURITY.md) |

‎docs/branching-and-releases.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Branches and deployments
2+
3+
ProCoderJii uses two long-lived branches:
4+
5+
| Branch | Purpose | Deployment |
6+
| --- | --- | --- |
7+
| `dev` | Default contribution branch; reviewed features and dependency updates integrate here. | Staging, after CI passes. |
8+
| `main` | Reviewed production releases. | Production, after CI passes. |
9+
10+
The flow is `feature/* -> PR -> dev -> staging checks -> PR -> main`. There is no permanent
11+
`release` branch. Version tags can identify releases without creating another integration branch.
12+
13+
## Contributions
14+
15+
Create a feature branch from current `dev` in your fork and open the PR against canonical `dev`.
16+
Both branches reject deletion and force pushes and require PR review and passing checks.
17+
The Branch policy check rejects a feature/fork PR directly into `main`; only this repository's
18+
`dev` branch can be promoted. A fork branch named `dev` is not a production promotion.
19+
20+
Commits and contribution PRs use the contributor account. For the project owner's two-account
21+
workflow, contributions use `Coding-Professional`; reviews and merges use `procoder-ji`.
22+
23+
## Promote a release
24+
25+
1. Make sure `dev` includes current `main`. If production has advanced independently, open a
26+
`main -> dev` synchronization PR and run checks before testing staging again.
27+
2. Wait for the exact `dev` commit's CI and staging deployment to pass. Exercise the changed
28+
student journey on staging with sample data. Check migrations, account/portfolio privacy,
29+
mobile and keyboard behavior when affected.
30+
3. Open a PR from **canonical `dev` to `main`**, describing the behavior being released and
31+
the staging checks. Review as `procoder-ji` and satisfy all required checks.
32+
4. Use a **merge commit** for this promotion, preserving ancestry between the long-lived
33+
branches. Squash merges remain suitable for individual feature PRs into `dev`.
34+
5. Production deploys after the new `main` commit passes CI. Confirm the deployment summary,
35+
health/session checks, canonical redirects and affected public routes.
36+
37+
Do not deploy unreviewed feature commits to production. Urgent fixes follow the same route;
38+
there is no permanent bypass branch. Database schema changes remain deliberate release
39+
operations: test the migrations on staging and apply approved production migrations with the
40+
direct connection before rolling out code that requires them. The runtime keeps migration on
41+
startup disabled. Never use a production database to run browser fixtures.
42+
43+
## Deployment environments
44+
45+
Each GitHub environment has branch restrictions and separate project-scoped deployment tokens.
46+
The CI deployment job runs only on canonical `dev`/`main` pushes, after frontend, browser/SEO
47+
and backend checks pass. PRs and fork workflows receive no deployment credentials.
48+
49+
| Environment | Allowed branch | Frontend project | Backend project |
50+
| --- | --- | --- | --- |
51+
| `staging` | `dev` | `procoderji-dev` | `procoderji-api-dev` |
52+
| `production` | `main` | `procoderji` | `procoderji-api` |
53+
54+
Environment variables: `VERCEL_ORG_ID`, `VERCEL_FRONTEND_PROJECT_ID`,
55+
`VERCEL_BACKEND_PROJECT_ID`, `PUBLIC_ORIGIN`, and `BACKEND_ORIGIN`.
56+
Environment secrets: `VERCEL_FRONTEND_TOKEN` and `VERCEL_BACKEND_TOKEN`. Scope each token to
57+
its project, give it an expiration date and rotate it before expiry. Tokens are never printed
58+
or committed. The script passes them directly to the CLI child process without a shell or
59+
command echo; it never dumps provider output into the workflow logs.
60+
Database and Google credentials stay in the appropriate Vercel project's secret settings.
61+
62+
Staging uses a schema-only Neon branch and a fresh `procoderji_dev` database, with a separate
63+
runtime role. Production student records and Data Protection keys are not copied into it.
64+
Use a separate Google OAuth client with the staging frontend callback. Until configured,
65+
staging supports guest practice and editor previews while account saving is unavailable.
66+
67+
Set `DEPLOYMENT_ENVIRONMENT=staging` in the staging frontend. Staging and Vercel previews send
68+
`noindex, nofollow` and disallow crawling; a dedicated staging project is still a production
69+
*build*, so `NODE_ENV` alone is not an environment boundary. Indexing directives are not access
70+
control. Use sample data and configure hosting access protection when private QA is needed.
71+
72+
The deployment script copies tracked source only. It prepares the backend's service configuration
73+
in an isolated directory, deploys/verifies the API first, then deploys the frontend. The live
74+
summary records the checked source commit and both origins. A failure stops the rollout; inspect
75+
the relevant Vercel project and restore its previous deployment if a rollback is needed.
76+
77+
Disable a previous independent Git deployment connection after this pipeline has been verified;
78+
otherwise a second deployment path can publish before CI finishes. The canonical GitHub Actions
79+
pipeline does not require granting Vercel's GitHub integration access to an organization.
80+
81+
## Operator recovery
82+
83+
For a manual staging check from a trusted checkout, set the staging project IDs and origins in
84+
the current process, authenticate Vercel CLI, and run
85+
`node scripts/deploy-vercel.mjs --local-staging`. This mode is unavailable in GitHub Actions and
86+
cannot select production. Source files and the operator's existing auth remain separate.
87+
88+
For a production incident, use the hosting dashboard's rollback to the previous verified
89+
deployment, then send the fix through `dev`. Do not delete student records or blindly reverse a
90+
schema migration as part of an application rollback.

‎docs/maintainer-guide.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ These steps do not need repeated owner permission. Existing decisions, including
1919
backend and selected Neon PostgreSQL deployment, remain valid. A person implementing that
2020
approved scope should continue through a reviewable change and its relevant checks.
2121

22-
Use the pull-request workflow for changes to `main`, and satisfy the repository's active review
22+
Use feature PRs into `dev`, then a reviewed promotion PR from canonical `dev` into `main`.
23+
Follow [branching and releases](branching-and-releases.md), and satisfy the active review
2324
and status-check rules before merging. Maintainers can merge routine changes within their
2425
authorised scope once the relevant checks and review are complete. Production rollout and
2526
private-credential access follow the separately agreed operating scope.

0 commit comments

Comments
 (0)