---
title: "Contributing | DRAWBRIDGE docs"
description: "How to contribute to Drawbridge, including where the canonical repository lives and how to open issues and merge requests on it."
url: https://drawbridge.apps.wayne.edu/docs/contributing.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Contributing [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#contributing)

This page tells you what Drawbridge is, where changes go, how to build and check them, and the rules a change must keep.

## What the project is [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#what-the-project-is)

Drawbridge is the Citadel auth gateway: one OpenID Connect client to Microsoft Entra ID (through Apache mod_auth_openidc) in front of apps, which signs a short assertion for SESAME's `gateway` driver. It is a container image (`docker/gateway/Dockerfile`) plus a PHP signer and CLI (`bin/drawbridge`). It is not installed with Composer by apps and is not on Packagist.

Its consumer is SESAME's `gateway` driver. The assertion (header, claims, signing algorithm, lifetime) is a contract between the two; change both together. Integration tests run against a SESAME checkout when `SESAME_PATH` is set.

## Where it lives [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#where-it-lives)

Development happens on git.wayne.edu, the canonical repository ([enterprise-apps/drawbridge](https://git.wayne.edu/enterprise-apps/drawbridge)). Changes, issues and merge requests go there. Tags are made there, by the maintainer, with an approver. Drawbridge is not on GitHub: git.wayne.edu is its only home.

## Build and test [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#build-and-test)

| Task | Windows (PowerShell) | Linux and macOS |
| --- | --- | --- |
| Install | `composer install` | `composer install` |
| All checks (what CI runs) | `composer ci` | `composer ci` |
| Validate a config file | `php bin/drawbridge config:validate --config=config/drawbridge.yaml` | same |
| Build the gateway image | `docker build -f docker/gateway/Dockerfile -t drawbridge-gateway .` | same |
| End-to-end rig (mock IdP by default, gateway, echo app, tests) | `rig\run.ps1 [keycloak]` | `sh rig/run.sh [keycloak]` |

`composer ci` runs `composer validate --strict`, PHPUnit (unit and integration suites), Pint, the agent-ready check, PHPStan, `composer audit` and the docs check (`composer docs:check`). The end-to-end suite (`phpunit.e2e.xml.dist`) runs inside the rig. The rig's keys and passwords are throwaway values made for the rig only. The optional `keycloak` argument swaps the mock for a pinned Keycloak started from `rig/keycloak/realm.json` and runs the Keycloak tests instead; that provider checks the client secret and PKCE and knows only the realm's two synthetic users.

The docs pages wear the front page's look through two files: `docs/_header.html` (the masthead and sheet index) and `docs/theme/drawbridge.css` (the front page's tokens mapped onto the docs kit, plus the dark mode it shares with the front page's section 11 in `site/assets/drawbridge.css`; change one, change both). Change the look there, never in `site/assets/docs.css` or `site/assets/docs.js`, which are Squire's kit and are checked by hash. Rebuild with `composer docs`.

## CI [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#ci)

- **GitLab:** Preflight's `php-test` (PHP 8.3, 8.4, 8.5) and `composer-audit` components, a `composer-ci` job, `gateway-image:build` (Buildah, on merge requests and `main`), `gateway-image:publish` (on tags only), a manual `rig` job, and the `advisories` job (scheduled or by hand only).
- **GitHub:** `.github/workflows/ci.yml` calls Preflight's reusable workflow with `composer ci`, plus the `rig` job.
- Green means `composer ci` passes on all three PHP versions on both, and the rig passes on GitHub.

## Rules a change must keep [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#rules-a-change-must-keep)

BEST_PRACTICES.md lists the 55 practices the gateway holds itself to, each with one tag (`Enforced`, `Checked`, `Documented` or `Not yet`), and every `Enforced` practice names the tests that prove it. A change must keep all of them, among them: strip first, fail closed, public is a decision not a default, match the normalized path never the raw one, exact or prefix nothing clever, sign narrowly and briefly, let the module do OpenID Connect, one session per app host, overwrite forwarded headers, keep secrets out of git and out of logs, do not trust the network, run small and boring, bounded dependencies, add headers never overwrite. See [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html) for the full rules and the tests behind each one.

Warning

Keys, PEM files and real config stay out of git (`.gitignore` covers them). Before a release, a secrets scan of the history must show nothing internal in the tree: no server names, people, tenant or client IDs.

## Where open work is listed [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#where-open-work-is-listed)

`OPEN_QUESTIONS.md` lists what is still to be verified against a real tenant and what is not built yet, in three sections: questions (the identity provider rows E-1 to E-8, the platform rows C-1 to C-7, and questions that came up while building), missing configuration, and not built yet. Each "default built" is what the code does today, and each default is the safer choice. `ENTRA_TEST.md` is the checklist for the first real Entra test.

## Releasing [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#releasing)

1. Move the lines under the top heading of `CHANGELOG.md` (Keep a Changelog) to `## X.Y.Z (YYYY-MM-DD)`.
2. `composer ci` and the rig green locally, then both pipelines green for that commit.
3. Run a secrets scan of the history and check that nothing internal (server names, people, tenant or client IDs) is in the tree.
4. Tag `X.Y.Z` (no `v`) on git.wayne.edu. The tag runs `gateway-image:publish`, which pushes the image to the stack's image registry: the group's `images` project, repository `drawbridge-gateway`, at the registry the `NOUGAT_REGISTRY` project variable names, logging in with the `NOUGAT_REGISTRY_USER` and `NOUGAT_REGISTRY_TOKEN` deploy token (protected variables, so release tags must be protected).
5. A release needs a maintainer's approval. Running it in front of real apps also needs the Citadel platform team.

## Who maintains it [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#who-maintains-it)

Wayne State University Enterprise Applications maintains Drawbridge. The internal runbook (accounts, the app registration, secret storage, platform contacts) is held by Enterprise Applications: ask them.

## Related [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#related)

- [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html)
- [Proof](https://drawbridge.apps.wayne.edu/docs/reference/proof.html)
- [Releasing](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html)
- [Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html)
