Skip to content

Contributing

Thank you for your interest in AuthEngine. This guide applies to all repositories in the auth-engine organization.

Tagline: One identity for every app and organisation.

New contributor?

Start with Quick Start, then open a good first issue when available.

Repositories

Repository What to change here
auth-engine FastAPI backend, IAM, OIDC, migrations
auth-engine-dashboard Next.js admin UI
auth-engine-infra Terraform, Docker Compose, this documentation
.github Org profile, CONTRIBUTING, SECURITY

Canonical copy on GitHub: CONTRIBUTING.md

Before you start

  1. Read Quick Start and run the stack locally.
  2. Search existing issues — avoid duplicate work.
  3. For large changes, open an issue first to discuss approach.
  4. Look for issues labeled good first issue if you are new to the codebase.

Local development

git clone https://github.com/auth-engine/auth-engine-infra.git
cd auth-engine-infra/compose
cp env.local.example .env
# Set SECRET_KEY and JWT_SECRET_KEY (openssl rand -hex 32)

docker compose up -d --build
docker exec authengine-api auth-engine migrate
Service URL
API / Swagger http://localhost:8000/docs
Dashboard http://localhost:3000

Backend only

git clone https://github.com/auth-engine/auth-engine.git
cd auth-engine
uv sync
cp .env.example .env
auth-engine migrate
auth-engine run

Requires Python 3.12+, uv, and Postgres, Redis, and MongoDB (or use Compose above).

Dashboard only

git clone https://github.com/auth-engine/auth-engine-dashboard.git
cd auth-engine-dashboard
cp .env.example .env.local
npm ci && npm run dev

Pull request workflow

  1. Fork the repository and branch from main (feature/…, fix/…, docs/…).
  2. Keep PRs focused — one logical change when possible.
  3. Test locally:
  4. Backend: CI lint/typecheck; run migrations if models changed.
  5. Dashboard: npm run build must pass.
  6. Docs: verify links if you edited docs/.
  7. Describe the PR — what, why, how tested, Fixes #123.
  8. Open against main.

Code guidelines

  • Match existing style (Ruff/mypy for Python, ESLint for TypeScript).
  • Never commit secrets — use .env.example only.
  • Update documentation here when behavior changes.
  • Prefer small diffs; discuss large refactors in an issue first.

Issues and templates

Type Link
Bug Bug report
Feature Feature request
Question Question
Security Security policy — not a public issue

Suggested GitHub labels

bug · enhancement · question · good first issue

License

Contributions are licensed under the MIT License.

Contact
Website authengine.org
Docs docs.authengine.org
GitHub github.com/auth-engine