Skip to content

Commit 8d2137f

Browse files
AaronDewesAaronDewes
authored
Merge branch 'zitadel:main' into main
2 parents eb0613f + 9dd2773 commit 8d2137f

File tree

335 files changed

+5680
-2771
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

335 files changed

+5680
-2771
lines changed

‎.cursorrules‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Cursor Rules for ZITADEL
2+
3+
You are working in the ZITADEL monorepo.
4+
5+
**ALWAYS** read `AGENTS.md` files in this order:
6+
1. Root `AGENTS.md`
7+
2. The nearest scoped `AGENTS.md` for the files you are changing
8+
9+
If you touch Go code or run Go tooling, inspect `go.mod` first for the required Go version/toolchain.
10+
11+
Use verified Nx targets only. If a target is unclear or missing, run `pnpm nx show project <project>`.
12+
13+
- **Root Context**: [AGENTS.md](AGENTS.md)
14+
- **API App**: [apps/api/AGENTS.md](apps/api/AGENTS.md)
15+
- **Login App**: [apps/login/AGENTS.md](apps/login/AGENTS.md)
16+
- **Docs Site**: [apps/docs/AGENTS.md](apps/docs/AGENTS.md)
17+
- **Management Console**: [console/AGENTS.md](console/AGENTS.md)
18+
- **Backend Internal**: [internal/AGENTS.md](internal/AGENTS.md)
19+
- **Proto Definitions**: [proto/AGENTS.md](proto/AGENTS.md)
20+
- **Shared Packages**: [packages/AGENTS.md](packages/AGENTS.md)
21+
- **Functional UI Tests**: [tests/functional-ui/AGENTS.md](tests/functional-ui/AGENTS.md)

‎.devcontainer/devcontainer.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
},
3434
"features": {
3535
"ghcr.io/devcontainers/features/go:1": {
36-
"version": "1.25.3"
36+
"version": "1.25"
3737
},
3838
"ghcr.io/devcontainers/features/docker-outside-of-docker": {},
3939
"ghcr.io/schlich/devcontainer-features/cypress:1": {
@@ -46,7 +46,7 @@
4646
"remoteEnv": {
4747
"PATH": "${containerEnv:PATH}:/workspaces/zitadel/.artifacts/bin/linux/amd64"
4848
},
49-
"postStartCommand": "echo 'export PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\"' >> ~/.bashrc",
49+
"postStartCommand": "npm install -g nx@21.6.9 && echo 'export PATH=\"${PWD}/.artifacts/bin/$(go env GOOS)/$(go env GOARCH):$PATH\"' >> ~/.bashrc",
5050
"customizations": {
5151
"vscode": {
5252
"extensions": [
@@ -58,4 +58,4 @@
5858
]
5959
}
6060
}
61-
}
61+
}

‎.github/copilot-instructions.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,23 @@
1-
Always respect the terminology defined in the 'Technical Glossary' section of agents.md when generating UI text or documentation.
1+
# GitHub Copilot Instructions for ZITADEL
2+
3+
You are working in the ZITADEL monorepo. This codebase uses specific conventions for its Go backend and Angular/Next.js frontends.
4+
5+
**CRITICAL**: Read `AGENTS.md` in the root first, then the nearest scoped `AGENTS.md` for changed files.
6+
7+
## Key References
8+
- `AGENTS.md`: Root architecture map and global commands.
9+
- `apps/api/AGENTS.md`: API app workflows and backend orchestration targets.
10+
- `apps/login/AGENTS.md`: Specifics for the Next.js Login UI.
11+
- `apps/docs/AGENTS.md`: Specifics for the Fumadocs documentation.
12+
- `console/AGENTS.md`: Specifics for the Angular Console.
13+
- `internal/AGENTS.md`: Backend domain and event-sourcing boundaries.
14+
- `proto/AGENTS.md`: API schema and generation guidance.
15+
- `packages/AGENTS.md`: Shared client/proto package workflows.
16+
- `tests/functional-ui/AGENTS.md`: Cypress functional UI test workflows.
17+
18+
## Behavior
19+
- Before Go-related work, inspect `go.mod` for required Go version/toolchain.
20+
- Use verified Nx targets only; if unsure, run `pnpm nx show project <project>`.
21+
- For backend changes, note we are in transition: relational data is becoming the system of record, while event writes are still required for history/audit.
22+
- Respect terminology defined in the `Technical Glossary` section of `AGENTS.md` when generating UI text or documentation.
23+
- Distinguish between `apps/login` (Next.js) and `console` (Angular) when suggesting frontend code.

‎.github/semantic.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,61 @@
11
# Always validate the PR title, and ignore the commits
22
titleOnly: true
3+
4+
# Allowed types — the PR title type must be one of these.
5+
# This list is the single source of truth referenced by AGENTS.md and CONTRIBUTING.md.
6+
types:
7+
- feat # new feature
8+
- fix # bug fix
9+
- docs # documentation only (no code change)
10+
- refactor # code restructuring without behaviour change
11+
- perf # performance improvement
12+
- test # adding or fixing tests
13+
- build # build system or tooling
14+
- ci # CI/CD pipeline
15+
- chore # maintenance (deps, config, etc.)
16+
- revert # reverts a previous commit
17+
18+
# Allowed scopes — if a scope is provided it must match one of these.
19+
# Scopes are optional; omit rather than invent one not on this list.
20+
# Note: 'docs' is a type, not a scope — use the type 'docs' for documentation changes.
21+
# This list is the single source of truth referenced by AGENTS.md and CONTRIBUTING.md.
22+
scopes:
23+
# Backend — domain areas
24+
- api
25+
- session
26+
- authz
27+
- command
28+
- query
29+
- eventstore
30+
- actions
31+
- crypto
32+
- domain
33+
- feature
34+
- idp
35+
- notification
36+
- oidc
37+
- saml
38+
- webauthn
39+
# Backend — infrastructure
40+
- cache
41+
- config
42+
- database
43+
- migration
44+
- setup
45+
- telemetry
46+
- queue
47+
# Frontend
48+
- console
49+
- login
50+
# API layer
51+
- grpc
52+
- proto
53+
# Cross-cutting
54+
- build
55+
- ci
56+
- deps
57+
- i18n
58+
- integration
59+
- perf
60+
- security
61+
- test

‎.gitignore‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,7 @@ go.work.sum
102102

103103
# AI Files
104104
CLAUDE.md
105-
AGENTS.md
106105
.mcp.json
107106
.gemini/*
108107

109-
docs_old
108+
docs_old

agents.md renamed to AGENTS.md

Lines changed: 65 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,45 @@
1+
# ZITADEL Monorepo Guide for AI Agents
2+
3+
## Mission & Context
4+
ZITADEL is an open-source Identity Management System (IAM) written in Go and Angular/React. It provides secure login, multi-tenancy, and audit trails.
5+
6+
## Read Order
7+
1. Read this file first.
8+
2. Read the nearest scoped `AGENTS.md` for the area you edit.
9+
3. If multiple scopes apply, use the most specific path.
10+
11+
## Repository Structure Map
12+
- **`apps/`**: Consumer-facing web applications.
13+
- **`login`**: Next.js authentication UI. See `apps/login/AGENTS.md`.
14+
- **`docs`**: Fumadocs documentation app. See `apps/docs/AGENTS.md`.
15+
- **`api`**: Backend Nx app target. See `apps/api/AGENTS.md`.
16+
- **`console/`**: Angular Management Console. See `console/AGENTS.md`.
17+
- **`internal/`**: Backend domain and service logic. See `internal/AGENTS.md`.
18+
- **`proto/`**: API definitions. See `proto/AGENTS.md`.
19+
- **`packages/`**: Shared TypeScript packages. See `packages/AGENTS.md`.
20+
- **`tests/functional-ui/`**: Cypress functional UI tests. See `tests/functional-ui/AGENTS.md`.
21+
22+
## Technology Stack & Conventions
23+
- **Orchestration**: Nx is used for build and task orchestration.
24+
- **Package Manager**: pnpm.
25+
- **Backend**:
26+
- **Go Version Source of Truth**: Inspect `go.mod` before Go work (`go` and optional `toolchain` directives).
27+
- **Communication**: For V2 APIs, connectRPC is the primary transport. gRPC and HTTP/JSON endpoints are also supported.
28+
- **Pattern**: The backend is transitioning to a relational design. Events are still persisted in a separate table for history/audit, but events are not the system of record.
29+
- **Frontend**:
30+
- **Console**: Angular + RxJS.
31+
- **Login/Docs**: Next.js + React.
32+
133
## ZITADEL Domain & Multi-Tenancy Logic
234

335
### 1. Hierarchy & Ownership
436

537
ZITADEL follows a strict hierarchical containment model. When generating code, logic, or translations, adhere to this structure:
638

739
- **System (Installation):** The entire ZITADEL deployment. Global settings are applied through runtime configuration files or environment variables. See `cmd/defaults.yaml`.
8-
- **Instance (The "Identity System"):**
40+
- **Instance (The "Identity System"):**
941
- **Definition:** A logical partition/virtual tenant. It is a "System inside a System."
10-
- **Isolation:** Data and configurations are strictly isolated between instances.
42+
- **Isolation:** Data and settings are strictly isolated between instances.
1143
- **Translation Rule:** NEVER translate as "Example" or "Case." Use technical terms like "Tenant," "Environment," or the local equivalent of "Logical System Entity."
1244
- **Organization:** A group within an Instance. It owns Users, Projects, and Roles.
1345
- **Project:** A collection of Applications and Auth Policies within an Org.
@@ -43,3 +75,34 @@ If a translation is requested for a language not listed above, follow these prio
4375
2. **Priority 2 (System Entity):** Use a term that implies a "running process" or "logical environment."
4476
3. **Priority 3 (Tenant):** If 'Instance' is ambiguous, use the local word for 'Tenant' (e.g., 租户 in Chinese).
4577
4. **Strict Ban:** NEVER use words that mean "an illustration", "a case", "a sample", or "an example."
78+
79+
## Command Rules
80+
Run commands from the repository root.
81+
82+
- Use verified Nx targets only.
83+
- If target availability is unclear, run `pnpm nx show project <project>`.
84+
- Do not assume all projects have `test`, `lint`, `build`, or `generate` targets.
85+
- Known exception: `@zitadel/console` has no configured `test` target.
86+
87+
## Verified Common Targets
88+
- `@zitadel/api`: `prod`, `build`, `generate`, `generate-install`, `lint`, `test`, `test-unit`, `test-integration`
89+
- `@zitadel/login`: `dev`, `build`, `lint`, `test`, `test-unit`, `test-integration`
90+
- `@zitadel/docs`: `dev`, `build`, `generate`, `install-proto-plugins`, `check-links`, `check-types`, `test`, `lint`
91+
- `@zitadel/console`: `dev`, `build`, `generate`, `install-proto-plugins`, `lint`
92+
93+
## Proto Plugin Binaries
94+
All proto plugins are installed to `.artifacts/bin/<GOOS>/<GOARCH>/` and Nx-cached. `generate` targets wire up the correct install dependency and prepend `.artifacts/bin/` to `$PATH` — no manual install step is needed.
95+
96+
## PR Title Convention
97+
98+
PR titles are validated by the Semantic PR app. Format:
99+
100+
`<type>(<scope>): <short summary>`
101+
102+
**Types**: must come from the list in [`.github/semantic.yml`](.github/semantic.yml) under `types:` — e.g. `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
103+
104+
**Scopes**: optional, but if used must come from the list in [`.github/semantic.yml`](.github/semantic.yml) under `scopes:`. When in doubt, omit the scope — do not invent values not on that list.
105+
106+
## Documentation
107+
- **Human Guide**: See `CONTRIBUTING.md` for setup and contribution details.
108+
- **API Design**: See `API_DESIGN.md` for API specific guidelines.

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# Contributing to Zitadel
22

3-
Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Docusaurus (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows.
3+
Zitadel is an open-source identity and access management platform built with a modern tech stack including Go (API), Next.js/React (Login), Angular (Console), and Fumadocs (Docs) - all orchestrated through an Nx monorepo with pnpm for efficient development workflows.
44

55
## Quick Start
66

77
1. Clone the repository: `git clone https://github.com/zitadel/zitadel` or [open it in a local Dev Container](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/zitadel/zitadel) or [create a GitHub Codespace](https://codespaces.new/zitadel/zitadel)
88
2. If you cloned the repository to your local machine, install the required development dependencies
99
- [Node.js v22.x](https://nodejs.org/en/download/) - Required for UI development and to run development commands `pnpm nx ...`
10-
- [Go 1.24.x](https://go.dev/doc/install) - Required for API development
10+
- [Go](https://go.dev/doc/install) - Required for API development. Use the version declared in `go.mod`.
1111
- [Docker](https://docs.docker.com/engine/install/) - Required for supporting services like the development database and for tests.
1212
- [Cypress runtime dependencies](https://docs.cypress.io/guides/continuous-integration/introduction#Dependencies) - Required for Browser UI tests
1313
<details>
@@ -49,8 +49,9 @@ You can build and start any project with Nx commands.
4949
| **Develop** | `pnpm nx run PROJECT:dev` | Development server | |
5050
| **Generate** | `pnpm nx run PROJECT:generate` | Generate .gitignored files | |
5151
| **Generate Go Files** | `pnpm nx run @zitadel/api:generate-go` | Regenerate checked-in files | This is needed to generate files using [Stringer](https://pkg.go.dev/golang.org/x/tools/cmd/stringer), [Enumer](https://github.com/dmarkham/enumer) or [gomock](https://github.com/uber-go/mock) |
52+
| **Install Proto Plugins** | `pnpm nx run @zitadel/api:generate-install` | Install proto toolchain | Installs Go-based plugins (protoc-gen-go, connect-go, …) to `.artifacts/bin/`. Run automatically by `generate` targets; Nx caches the outputs. |
5253
| **Test - Unit** | `pnpm nx run PROJECT:test-unit` | Run unit tests | |
53-
| **Test - Integration** | `pnpm nx run PROJECT:test-integration` | Run integration tests | Learn mnore about how to [debug API integration tests](#run-api-integration-tests) |
54+
| **Test - Integration** | `pnpm nx run PROJECT:test-integration` | Run integration tests | Learn more about how to [debug API integration tests](#run-api-integration-tests) |
5455
| **Test - Integration Stop** | `pnpm nx run PROJECT:test-integration-stop` | Stop integration containers | |
5556
| **Test - Functional UI** | `pnpm nx run @zitadel/functional-ui:test` | Run functional UI tests | Learn more about how to [develop the Management Console and opening the interactive Test Suite](#pass-management-console-quality-checks) |
5657
| **Test - Functional UI Stop** | `pnpm nx run @zitadel/functional-ui:stop` | Run functional UI containers | |
@@ -129,7 +130,7 @@ The code consists of the following parts:
129130
| API definitions | Specifications of the API | [Protobuf](https://developers.google.com/protocol-buffers) | [./proto/zitadel](./proto/zitadel) | [Contribute to API](#contribute-to-api) |
130131
| Management Console | Frontend the user interacts with after log in | [Angular](https://angular.io), [Typescript](https://www.typescriptlang.org) | [./console](./console) | [Contribute to Frontend](#contribute-to-frontend) |
131132
| Login | Modern authentication UI built with Next.js | [Next.js](https://nextjs.org), [React](https://reactjs.org), [TypeScript](https://www.typescriptlang.org) | [./apps/login](./apps/login) | [Contribute to Frontend](#contribute-to-frontend) |
132-
| Docs | Project documentation made with docusaurus | [Docusaurus](https://docusaurus.io/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) |
133+
| Docs | Project documentation made with Fumadocs | [Fumadocs](https://fumadocs.dev/) | [./apps/docs](./apps/docs) | [Contribute to Frontend](#contribute-to-frontend) |
133134
| translations | Internationalization files for default languages | YAML | [./console](./console) and [./internal](./internal) | [Contribute Translations](#contribute-translations) |
134135

135136
Please follow the guides to validate and test the code before you contribute.
@@ -173,15 +174,13 @@ Make sure you use [semantic release messages format](https://github.com/angular/
173174

174175
#### Type
175176

176-
Must be one of the following:
177-
178-
- **feat**: New Feature
179-
- **fix**: Bug Fix
180-
- **docs**: Documentation
177+
Allowed values are listed in [`.github/semantic.yml`](.github/semantic.yml) under `types:`.
181178

182179
#### Scope
183180

184-
This is optional to indicate which component is affected. If in doubt, leave blank (`<type>: <short summary>`)
181+
This is optional to indicate which component is affected.
182+
Allowed values are listed in [`.github/semantic.yml`](.github/semantic.yml) under `scopes:`.
183+
When in doubt, omit the scope — `<type>: <short summary>` is always valid.
185184

186185
#### Short summary
187186

@@ -368,7 +367,7 @@ Choose your contribution area:
368367

369368
- **[Login App](#contribute-to-login)** (Next.js/React) - Modern authentication flows
370369
- **[Console](#contribute-to-console)** (Angular) - Admin dashboard and user management
371-
- **[Docs](#contribute-to-docs)** (Docusaurus) - Project documentation
370+
- **[Docs](#contribute-to-docs)** (Fumadocs) - Project documentation
372371
- **[Client Packages](#client-packages)** - Shared libraries for API communication
373372

374373
### Project Dependencies
@@ -580,6 +579,18 @@ pnpm nx run @zitadel/proto:generate # Regenerate after proto changes
580579
pnpm nx run @zitadel/client:build # Build after changes
581580
```
582581

582+
### Proto Plugin Convention
583+
584+
All binary proto plugins are installed to `.artifacts/bin/<GOOS>/<GOARCH>/` and declared as Nx target outputs, making them eligible for Nx remote cache.
585+
586+
| Scope | Target | Installs |
587+
|---|---|---|
588+
| `@zitadel/api` | `generate-install` | Go-based plugins: `buf`, `protoc-gen-go`, `protoc-gen-connect-go`, `protoc-gen-openapiv2`, `protoc-gen-validate`, `protoc-gen-authoption`, … |
589+
| `@zitadel/console` | `install-proto-plugins` | `protoc-gen-grpc-web`, `protoc-gen-js`, `protoc-gen-openapiv2` (pre-built binaries, no Go required) |
590+
| `@zitadel/docs` | `install-proto-plugins` | `protoc-gen-connect-openapi` (pre-built binary, no Go required) |
591+
592+
`generate` targets depend on the appropriate install targets and prepend `.artifacts/bin/` to `$PATH` automatically. Running `pnpm nx run PROJECT:generate` is sufficient — no manual plugin installation needed.
593+
583594
### Contribute to Docs
584595

585596
Project documentation is located under [./apps/docs](./apps/docs).

‎MEETING_SCHEDULE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ We will showcase the new Login UI, provide insights into the application's archi
9696

9797
* **Architecture of the Login UI**: Explore how server-side and client-side components interact within the new Login UI and NextJS framework.
9898
* **Session API**: Understand the workings of the Session API
99-
* **OIDC middleware configuration**: Learn how OIDC functions with the new Login UI and the necessary steps for a complete flow.
99+
* **OIDC middleware settings**: Learn how OIDC functions with the new Login UI and the necessary steps for a complete flow.
100100
* **Customization Options / Settings**: Discover how to personalize the login and which ZITADEL settings are implemented.
101101
* **Outlook**: Gain insights into future features
102102
* **Q&A**

0 commit comments

Comments
 (0)