Plan — BJ-4: Config schema Bitbucket + Jira env blocks#

Summary#

Add conditionally-validated Bitbucket and Jira env var blocks to src/config/config.schema.ts, mirroring the existing GITHUB_APP_* Joi.when() pattern so empty Atlassian config stays backward-compatible and partial configs fail fast with a clear error. Document both blocks in .env.example.

Files#

Path	Action	Purpose
`src/config/config.schema.ts`	modify	Append Bitbucket + Jira Joi entries; gate companions on `BITBUCKET_OAUTH_CLIENT_ID` / `JIRA_OAUTH_CLIENT_ID` via `.when()`
`src/config/config.schema.spec.ts`	modify	Add `Bitbucket mode` and `Jira mode` describe blocks mirroring the existing `GitHub App mode` tests
`.env.example`	modify	Append two commented blocks documenting Bitbucket and Jira vars

Steps#

In config.schema.ts, add BITBUCKET_OAUTH_CLIENT_ID: Joi.string().optional() plus BITBUCKET_OAUTH_CLIENT_SECRET, BITBUCKET_OAUTH_REFRESH_TOKEN, BITBUCKET_WORKSPACE each as Joi.string().when('BITBUCKET_OAUTH_CLIENT_ID', { is: Joi.exist(), then: Joi.required(), otherwise: Joi.optional() }).
Add the remaining Bitbucket vars (BITBUCKET_REPO, BITBUCKET_BOT_USERNAME, BITBUCKET_WEBHOOK_SECRET) as plain Joi.string().optional() — scope lists them but only CLIENT_ID/SECRET/REFRESH_TOKEN/WORKSPACE are required companions per the issue spec.
Repeat the same pattern for Jira: JIRA_OAUTH_CLIENT_ID triggers required status on JIRA_OAUTH_CLIENT_SECRET, JIRA_OAUTH_REFRESH_TOKEN, JIRA_SITE_URL, JIRA_CLOUD_ID. Add JIRA_PROJECT_KEY, JIRA_BOT_USERNAME, JIRA_WEBHOOK_SECRET as plain optional.
In config.schema.spec.ts, add a Bitbucket mode describe: (a) empty Atlassian config passes, (b) only BITBUCKET_OAUTH_CLIENT_ID set fails and the error lists the three missing companions, (c) all four required companions set passes.
Add a matching Jira mode describe following the same three cases with the four Jira companions.
Append two blocks to .env.example under new # --- Bitbucket (optional) --- and # --- Jira (optional) --- headers, with inline comments flagging the trigger var and required companions; leave all lines commented out so GitHub-only deployments keep defaulting off.

Verification#

npm run test -- config.schema.spec passes; new describe blocks cover empty / partial-fail / complete-pass cases.
npm run lint and npm run build are clean.
Running the app with an empty Atlassian section still boots (no regression for existing validEnv fixture).

Risks#

Using only CLIENT_ID as the .when() trigger means a user who sets e.g. only BITBUCKET_OAUTH_CLIENT_SECRET will not get a validation error. This matches the GITHUB_APP_ID pattern already in the repo and is intentional — keeping one designated gateway var keeps error messages clean.

Assumptions#

Trigger vars are BITBUCKET_OAUTH_CLIENT_ID and JIRA_OAUTH_CLIENT_ID (the issue explicitly marks them as the "required together with …" anchors).
*_REFRESH_TOKEN is a bootstrap string only — no format validation required per issue edge case note.
The six non-companion vars (BITBUCKET_REPO, *_BOT_USERNAME, *_WEBHOOK_SECRET, JIRA_PROJECT_KEY) stay plain .optional() at this phase; downstream waves can tighten later.