Skip to content

Commit 16f3729

Browse files
jain-shreyans-dbjain-shreyans-db
authored
Merge branch 'master' into db-contrib/waltz-7446-Documentation-is-out-of-date
2 parents 5e04489 + 8ee1bab commit 16f3729

26 files changed

+1192
-103
lines changed

‎.build.settings.xml‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,7 @@
2121
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2222
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
2323

24-
2524
<profiles>
26-
2725
<profile>
2826
<id>build-postgres</id>
2927
<activation><activeByDefault>false</activeByDefault></activation>
@@ -47,5 +45,26 @@
4745
<database.catalog></database.catalog>
4846
</properties>
4947
</profile>
48+
49+
<profile>
50+
<id>build-mssql-alt</id>
51+
<activation><activeByDefault>false</activeByDefault></activation>
52+
<properties>
53+
<database.url>jdbc:sqlserver://localhost:1433;databaseName=waltz;encrypt=true;trustServerCertificate=true</database.url>
54+
<database.user>sa</database.user>
55+
<database.password>Waltz#123</database.password>
56+
<database.schema>dbo</database.schema>
57+
<database.catalog>waltz</database.catalog>
58+
</properties>
59+
</profile>
5060
</profiles>
61+
62+
<servers>
63+
<server>
64+
<id>jooq-pro</id>
65+
<username>${env.JOOQ_USERNAME}</username>
66+
<password>${env.JOOQ_PASSWORD}</password>
67+
</server>
68+
</servers>
69+
5170
</settings>

‎.github/workflows/README.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
2+
# Waltz Integration Builds (Postgres + MSSQL)
3+
4+
![Postgres + MSSQL Build](https://github.com/finos/waltz/actions/workflows/maven-dual-build.yml/badge.svg?branch=master)
5+
6+
This repository supports running **dual database integration builds**:
7+
8+
- ✅ Postgres integration build
9+
- ✅ MSSQL integration build (requires jOOQ licence secrets)
10+
11+
Due to GitHub security restrictions, secrets are **not available to pull requests raised from forks**.
12+
To accommodate this, the workflow includes a `workflow_dispatch` trigger to allow manual execution when needed.
13+
14+
---
15+
16+
## 🧱 Architecture Diagram
17+
18+
The diagram below shows how the GitHub Actions workflow gates the MSSQL integration build based on whether the
19+
required jOOQ secrets are available.
20+
21+
> Tip: GitHub renders Mermaid diagrams automatically in Markdown.
22+
23+
```mermaid
24+
flowchart TD
25+
A[Trigger
26+
PR / push / workflow_dispatch] --> B[Checkout + Build Setup]
27+
B --> C[Check jOOQ secrets
28+
JOOQ_USERNAME & JOOQ_PASSWORD]
29+
30+
C -->|Secrets available| D[Run Postgres integration build]
31+
C -->|Secrets available| E[Run MSSQL integration build]
32+
D --> F[Publish results]
33+
E --> F
34+
35+
C -->|Secrets NOT available| G[Run Postgres integration build]
36+
G --> H[Skip MSSQL build gracefully
37+
Emit warning/annotation]
38+
H --> I[Publish results]
39+
```
40+
41+
### Key points
42+
43+
- **Postgres always runs** (fork PRs included).
44+
- **MSSQL only runs when jOOQ secrets are available** (e.g., in the upstream repo, FINOS branches, or maintainer-triggered runs).
45+
- When secrets are missing, the workflow **skips MSSQL cleanly** and still reports success for the overall pipeline.
46+
47+
---
48+
49+
## 🔐 GitHub Security Limitation
50+
51+
GitHub does **not expose repository secrets to PRs created from forks**.
52+
53+
Because the MSSQL build requires the following secrets:
54+
55+
- `JOOQ_USERNAME`
56+
- `JOOQ_PASSWORD`
57+
58+
The MSSQL build cannot run automatically in fork-based PRs unless secrets are available in that repository.
59+
60+
---
61+
62+
## ⚙️ Workflow Behaviour
63+
64+
### When jOOQ Secrets Are NOT Available
65+
66+
- The Postgres build runs normally.
67+
- The MSSQL build is **skipped gracefully**.
68+
- The workflow completes successfully.
69+
- A warning annotation explains why MSSQL was skipped.
70+
71+
This prevents unnecessary build failures while maintaining transparency.
72+
73+
---
74+
75+
### When jOOQ Secrets Are Available
76+
77+
- Both Postgres and MSSQL integration builds run.
78+
- All artefacts are generated.
79+
- Full database compatibility is validated.
80+
81+
---
82+
83+
# 🚀 Recommended Contribution Workflows
84+
85+
## ✅ Option 1 — Fork Maintains Its Own jOOQ Licence
86+
87+
Each fork maintains its **own jOOQ licence secrets**.
88+
89+
**Benefits:**
90+
- MSSQL build runs automatically.
91+
- Full dual-database testing in every PR.
92+
- Faster feedback cycle.
93+
94+
Ideal for long-running or frequently updated forks.
95+
96+
---
97+
98+
## ✅ Option 2 — PR via FINOS Fork Branch
99+
100+
1. Raise a PR from your fork to a **temporary branch on the FINOS fork**.
101+
2. Secrets are available in the FINOS fork.
102+
3. Confirm both Postgres and MSSQL builds pass.
103+
4. Raise a final PR from that branch to `master`.
104+
105+
This ensures full integration validation before merging.
106+
107+
---
108+
109+
## ✅ Option 3 — Maintainer-Triggered Full Build (Recommended for Open Contribution)
110+
111+
1. Contributor opens PR from fork.
112+
- Postgres build runs automatically.
113+
- MSSQL build is skipped (no secrets available).
114+
2. Maintainer reviews the PR.
115+
3. Maintainer manually triggers the full build using:
116+
- `workflow_dispatch`
117+
- or a re-run with secrets (if using protected environments).
118+
4. Both Postgres and MSSQL builds run.
119+
5. If green → merge directly.
120+
121+
**Benefits:**
122+
- Secrets remain centralized and protected.
123+
- No need for contributors to store licence keys.
124+
- No intermediate PR branch required.
125+
- Clean PR workflow.
126+
- Maintainers retain control of licence usage.
127+
128+
Ideal for open-source governance models.
129+
130+
---
131+
132+
## 🛠 Manual Build Trigger
133+
134+
The workflow supports:
135+
136+
```
137+
workflow_dispatch
138+
```
139+
140+
This allows maintainers to run the full dual-database build on demand.
141+
142+
---
143+
144+
## 🧩 Graceful Failure Design
145+
146+
The workflow includes a `check-jooq-secrets` step which:
147+
148+
- Detects whether `JOOQ_USERNAME` and `JOOQ_PASSWORD` are configured.
149+
- Conditionally enables the MSSQL build.
150+
- Prevents hard failures when secrets are unavailable.
151+
- Provides a clear annotation message in workflow logs.
152+
153+
---
154+
155+
## 📦 Build Matrix Overview
156+
157+
| Scenario | Postgres | MSSQL | Result |
158+
|----------|----------|--------|--------|
159+
| Fork PR (no secrets) | ✅ Runs | ⏭ Skipped | ✅ Success |
160+
| Fork with secrets | ✅ Runs | ✅ Runs | ✅ Success |
161+
| FINOS branch | ✅ Runs | ✅ Runs | ✅ Success |
162+
| Maintainer-triggered build | ✅ Runs | ✅ Runs | ✅ Success |
163+
164+
---
165+
166+
## Summary
167+
168+
This setup provides:
169+
170+
- Secure handling of jOOQ licence secrets
171+
- Dual database validation
172+
- Clear contributor workflows
173+
- Graceful CI behaviour
174+
- Manual override capability

0 commit comments

Comments
 (0)