## Todos for release
- [x] Configure Env in docs project on vercel
- [x] Configure Root Path in the docs project on vercel
- [ ] Remove old CSP https://github.com/zitadel/website/pull/1592
## What we did
This pull request migrates the project documentation from the old
`docs/` directory to the new `apps/docs/` directory, introduces a new
documentation system built with Next.js and Fumadocs, and updates all
relevant references, configuration files, and documentation to reflect
this change. It also adds new configuration and ignore files for the new
documentation app, updates CI and linting to exclude the new docs from
certain checks, and revises the contributing guidelines accordingly.
**Documentation System Migration and New Docs App**
* Migrated all documentation from `docs/` to `apps/docs/`, and updated
all references in `README.md`, `CONTRIBUTING.md`, and other files to
point to the new location.
[[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640)
[[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607)
[[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687)
[[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3)
[[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30)
* Added a new Next.js/Fumadocs-based documentation app under
`apps/docs/`, including core app files, layouts, routing, search API,
and a comprehensive `README.md` with development and contribution
instructions.
[[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74)
[[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39)
[[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7)
[apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81),
[apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79),
[[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7)
[[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29)
[[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25)
**Configuration and Tooling Updates**
* Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and
`.github/dependabot.yml` to properly handle the new docs app: excluded
`apps/docs` from certain checks, added npm dependency updates for the
docs app, and excluded generated content.
[[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14)
[[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6)
[[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129)
[[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106)
* Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3
version for consistency.
**Licensing and Miscellaneous**
* Added `apps/docs/` to the list of licensed directories in
`LICENSING.md`.
These changes ensure the documentation is now maintained in a modern,
scalable system and all project tooling is updated to support the new
structure.
---------
Co-authored-by: Federico Coppede <[email protected]>
# Which Problems Are Solved
This PR improves our NX caching, especially for the console and api.
It makes sure that if the console is changed the api is also rebuilt and
if the api is changed the functional-ui tests are rerun. It is important
to note this only fixes a subset of our problems.
# How the Problems Are Solved
NX ignores .gitignored files even if they are explicitly added to the
inputs of an NX target. To counteract this one can add these files to a
.nxignore file with a negated pattern.
https://nx.dev/docs/reference/inputs#token-behavior-with-nested-projects
. This solution is not documented per se but can be find in this Github
issue: https://github.com/nrwl/nx/issues/6821 . Further more nx
calculates the hashes of inputs at the start and does not recalculate
them even if a dependency of a target changes. To solve this problem one
needs to use
https://nx.dev/docs/reference/inputs#outputs-of-dependent-tasks . This
comment of an NX developer helped me further to understand the actual
behaviour of NX:
https://github.com/nrwl/nx/issues/33379#issuecomment-3657929455 .
# Additional Changes
Because the functional-ui tests now correctly run again they had to be
fixed. This pr unifies the field names in the user create v1 and v2 ui.
# Additional Context
To document this somewhere, this proposed fix does not work:
https://github.com/nrwl/nx/issues/6821#issuecomment-1309475504 . In my
local testing NX runtime inputs also get executed at the beginning of
the NX loop and ignore subsequent changes by targets. While testing this
fix and browsing through NX code I found this, which could be helpful in
the future and isn't documented: https://github.com/nrwl/nx/pull/31428
# Which Problems Are Solved
- Some mail providers (e.g.: MS Exchange) have deprecated plain auth
# How the Problems Are Solved
Adds XOauth2 auth option to SMPT
- SMTP config now can contain XOAuth2 auth config
- Proto files are updated to have a oneof for configuration selection.
Old fields for configuring plain auth are still available not to create
a breaking change. These can be removed in the future.
- Columns are added to the database to persist the config
# Additional Changes
none
# Additional Context
Replace this example with links to related issues, discussions, discord
threads, or other sources with more context.
Use the Closing #issue syntax for issues that are resolved with this PR.
- Closes#8042
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Tim Möhlmann <[email protected]>
# Which Problems Are Solved
The following terms have all been renamed to management console:
- Customer Portal (when used to mean the console)
- Console
- Admin Console
# How the Problems Are Solved
- Search & Replace smartly
- Use Copilot for translation files
Changes done to: backend + frontend codebase, docs, translations and
protobufs (descriptions only)
# Additional Context
- Partially Closes#11279
# Which Problems Are Solved
The docs and console API generators used an unversioned
`buf.build/grpc-ecosystem/openapiv2` plugin for the code generation. The
latest version has an issue and fails.
# How the Problems Are Solved
- pin the plugin to the latest running version
# Additional Changes
none
# Additional Context
- noticed internally
- requires backport to at least v4.x
- https://github.com/grpc-ecosystem/grpc-gateway/issues/6274
# Which Problems Are Solved
Duplicate of https://github.com/zitadel/zitadel/pull/11405
- Users migrating from Actions V1 to V2 lack comprehensive documentation
explaining the architectural differences and migration patterns
- The existing migration guide doesn't provide enough context on why
Actions changed and how to map V1 concepts to V2
- No clear reference table mapping common use cases to the appropriate
V2 execution types
# How the Problems Are Solved
- Added a new comprehensive migration guide
(`actions-v1-to-v2-migration.md`) covering:
- Deprecation notice for Actions V1 (sunsetting in ZITADEL V5)
- Architecture deep dive comparing V1 (embedded JavaScript) vs V2
(webhook model)
- Key architectural differences table
- Business benefits of migrating to V2
- Use case mapping table with links to ready-to-deploy Cloudflare Worker
examples
- Detailed flow explanations for Internal Authentication, External
Authentication, Complement Token, and SAML Response customization
---------
Co-authored-by: Rajat Singh <[email protected]>
Closes#11386
# Which Problems Are Solved
This PR fixes an issue where the `successUrl` and `failureUrl` for
implicit IdP flows (initiated via OIDC `idp🆔...` scopes) were being
constructed using `request.nextUrl.origin`. This failed to account for:
- `x-zitadel-forward-host` headers (essential for proper public URL
resolution).
- `NEXT_PUBLIC_BASE_PATH` configuration.
# How the Problems Are Solved
The fix replaces the manual string concatenation with the shared
`constructUrl` helper, ensuring consistent and correct URL generation.
Co-authored-by: Livio Spring <[email protected]>
## Which Problems Are Solved
- Add comprehensive Arabic language support to ZITADEL
## How the Problems Are Solved
- Added full Arabic translation files for the login UI, console, and
notification (yaml and json).
- Ensured all keys match the latest English reference files to avoid
missing or inconsistent entries.
- Updated the localization loader to include `ar` as a supported
language.
## Additional Changes
## Additional Context
Closes#11146
---------
Co-authored-by: Marco A. <[email protected]>
# Which Problems Are Solved
User with older instances, created at version 3.3.3 or earlier may have
been affected with feature flags no longer applying. Older version of
Zitadel had a bug in console where toggling a single feature would apply
a state to all features, creating around 12 events each request. Then 4
feature flags and their event types were removed in v4, meaning that the
`offset` value in the projection's current state could be wrong by 4 if
the instance was affected by the above bug.
# How the Problems Are Solved
Increment the feature projection versions, so that the tables get
recomputed and the current states entries becomes accurate again.
# Additional Changes
- none
# Additional Context
- Original bug: https://github.com/zitadel/zitadel/issues/10459
- Reported through support
# Which Problems Are Solved
There's currently no way to retrieve a project based on the client_id of
an application. A developer would need to iterate through all projects
and their applications to make the correlation.
# How the Problems Are Solved
- Added a possibility to filter for `client_id` and `entity_id` on the
ListApplications endpoint.
- Added the `project_id` on the `Application` response (used on the
ListApplications endpoint).
# Additional Changes
None
# Additional Context
- closes#11340
- requires backport to v4.x
# Which Problems Are Solved
While moving the some requests from the v2beta organization service to
v2, the `org_id` property of the `AddOrganization` request was
deprecated in favor of `organization_id`. However, the internal logic
was adjusted, resulting in a ingored `organization_id`.
# How the Problems Are Solved
- properly favor `organization_id` over `org_id` and added a note to the
proto.
# Additional Changes
none
# Additional Context
- closes#11269
- requires backport to v4.x
# Which Problems Are Solved
- Outdated Quickstart, with old screenshots
- Quickstart was too long
- Quickstart had lots of prose text, which wasn't really developer
focused
# How the Problems Are Solved
- Replaced outdated screenshots with the latest UI.
- Streamlined long-form prose into actionable, developer-focused steps.
- Shortened the overall length to help developers reach "Success"
faster.
---------
Co-authored-by: Florian Forster <[email protected]>
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
As part of the naming consistency initiative, the term `Manager Roles`
is replaced by `Administrator Roles`
# How the Problems Are Solved
By replacing `Manager Roles` with `Administrator Roles` in API docs,
Console UI, and guides.
# Additional Changes
N/A
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/11293
---------
Co-authored-by: Copilot <[email protected]>
Added the list of egress IPs per region for Zitadel Cloud outgoing
requests from Actions/IDP connections/SMTP/SMS/etc.
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Florian Forster <[email protected]>
# Which Problems Are Solved
As part of the consistent naming effort, this PR focuses on "Trusted
Domains".
# How the Problems Are Solved
- All terms referring to a domain that is used in API responses were
changed to "Trusted Domain" or "trusted domain".
# Additional Changes
None
# Additional Context
- closes#11297
---------
Co-authored-by: Copilot <[email protected]>
Closes#11345
# Which Problems Are Solved
When changing password, users could have run into a race condition /
eventual consistency issue which resulted in:
- Verification failures in `sendPassword`
- The user receiving a `couldNotCreateSession` or
`couldNotCreateSessionForUser` error despite providing a valid password.
# How the Problems Are Solved
- Previously, `checkSessionAndSetPassword` was fired without await,
causing the code to proceed immediately to
`sendPassword`. This resulted in `sendPassword` trying to verify the
user's session with the new password before the password update had
actually completed on the server.
- Now the password change call is executed by the login service user
only, ommitting eventual `membership not found (AUTHZ-cdgFk)` errors
from the API by using the user session itself. The login checks for a
recent password change (within 5 minutes) as well to ensure session
freshness.
# Which Problems Are Solved
As part of the consistent naming effort, this PR focuses on "Custom
Domains".
# How the Problems Are Solved
- All terms referring to a domain identifying an instance were changed
to "Custom Domain" or "custom domain".
- All placeholders were changed to `${CUSTOM_DOMAIN}` or
`$CUSTOM_DOMAIN` (if escaping was not possible)
- Some other placeholders were change to the same style.
- One occurrence of custom domain was changed to organization domain to
prevent misunderstandings.
# Additional Changes
None
# Additional Context
- closes#11296
- customer portal is fixed on
https://github.com/zitadel/website/pull/1570
- angular example is updated on
https://github.com/zitadel/zitadel-angular/pull/29
# Which Problems Are Solved
This PR fixes a problem where expired or cleared sessions could not be
reauthenticated when passkey was set as single method.
# How the Problems Are Solved
The logic now correctly falls back to creating a new session if the
context is provided.
Co-authored-by: Livio Spring <[email protected]>
Changes made to the docs UI:
**Code Blocks:** Implemented "Mac Terminal" style blocks with traffic
light dots, rounded corners, and deep shadows. Enforced high-contrast
dark theme for code in all modes.
**Typography**: Updated weights and tighter letter spacing for headings.
**Admonitions**: Updated alerts to use cleaner borders and softer
shadows.
---------
Co-authored-by: Copilot <[email protected]>
# Which Problems Are Solved
The new breadcrumbs were causing problems with some more advanced
Zitadel setups. This pr removes the new breadcrumbs to revert to the old
navigation behaviour.
# How the Problems Are Solved
Most of the changes could be kept but those specific to the navigation
where mostly reverted.
# Additional Changes
Updated some dependencies.
# Additional Context
- Closes#10863
# Which Problems Are Solved
When setting a password expiry policy, users without password, e.g.
federated users, would be prompted to change their password. This was
due to two bugs, where the policy would be applied for all users.
Additionally, whenever a user was created a `PasswordChanged` timestamp
would be set, regardless if the user has a password or not.
# How the Problems Are Solved
- Only apply the password expiry check on local authentication and users
with a password (e.g. passkey only users would not be prompted)
- Only set the `PasswordChanged` timestamp for users with password
# Additional Changes
None
# Additional Context
- reported through Discord:
https://discord.com/channels/927474939156643850/1447235781717397596/1450481990808637470
- requires backport to v4.x
# Which Problems Are Solved
Naming inconsistency w.r.t the usage of Given Name / Family Name instead
of First Name / Last Name
# How the Problems Are Solved
* By replacing given and family names with first and last names in UI
and docs (not in the API definitions)
* Updated translations in multiple languages to first and last names
instead of given/family names
# Additional Changes
* Add `internal/**/*.yaml` path to the nx sources input to rebuild the
binary upon changes to these files
* Fix failing unit tests in `user_notifier_legacy_test.go` by updating
`Passwordless` with `Passkey`
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/11308
---------
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Wim Van Laer <[email protected]>
Closes#11006
# Which Problems Are Solved
This PR addresses an issue where the ignoreUnknownUsernames setting was
not being respected in certain scenarios during the login flow.
Specifically:
- When a user was found but rejected due to login settings (e.g.,
disableLoginWithEmail), the system would return a "User not found" error
instead of redirecting to the password page as dictated by
ignoreUnknownUsernames.
- When a user was not found, and the flow fell through the registration
checks (e.g., IDP redirect failed), it would also return "User not
found" without checking ignoreUnknownUsernames.
# How the Problems Are Solved
- Introduced a helper function `handleUserNotFound` in
`apps/login/src/lib/server/loginname.ts` to centralize the logic for
checking ignoreUnknownUsernames and redirecting to the password page.
- Updated the user validation logic to call handleUserNotFound when a
user is found but rejected by policy.
- Updated the registration fallback logic to call handleUserNotFound
instead of directly returning an error.
- Added new test cases in `apps/login/src/lib/server/loginname.test.ts`
to verify the fix and ensure no regressions.
# Additional Changes
- Fixed inconsistency in translation files
---------
Co-authored-by: Livio Spring <[email protected]>
# Which Problems Are Solved
Fixes a problem where submit buttons where not correctly enabled onBlur
event
# How the Problems Are Solved
By changing the react-hook-form mode property to onChange, buttons are
enabled as intended
<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->
# Which Problems Are Solved
Adding a generic SMTP server using the gRPC endpoints resulted in an
error. This was because the password field was requried.
# How the Problems Are Solved
Removed the requirement for a password from the mail config.
# Additional Context
closes#11084
# Which Problems Are Solved
Inconsistent naming of passkeys
# How the Problems Are Solved
translations are done using gemini
# Additional Changes
# Additional Context
- Closes#11298
---------
Co-authored-by: Gayathri Vijayan <[email protected]>
# Which Problems Are Solved
A customer reported that when the session in console expires and the
user is prompted to re-authenticate, users get a "mfa required" error
after the re-authentication, resp. after a redirect to the login.
Because of the login policy settings, they're not required to actively
re-authenticate, but are automatically signed-in again and then get the
error.
It was discovered, that the problem is due to the login v1 loading the
wrong login policy (from the default org or instance default) instead of
the user's organization. If there are differences in the allowed second
factors, e.g. if the user's organization allows OTP Email, but the
default policy doesn't allow that and neither policy enforces MFA, then
the login will not check for 2FA/MFA. The then created new OIDC session
/ tokens won't contain any MFA information, which results in the
described error.
# How the Problems Are Solved
When creating the auth request internally, we now check for a userID set
by the id_token_hint. In case it is set, the corresponding user will be
loaded already and the request will be aggregated with their information
incl. the organization id.
A `selectUser` function has been added for this and the existing
`SelectUser` used in the account selection page has been updated to use
the new function.
# Additional Changes
None
# Additional Context
- reported through support
- requires backport to v4.x and v3.x
Co-authored-by: Silvan <[email protected]>
# Which Problems Are Solved
A customer reported that multiple filters on the ListAdministrators
endpoint were returning a `List.Query.Invalid` error.
They were missing the implementation.
# How the Problems Are Solved
Implement `and`, `or`, `not` and `role` filters.
# Additional Changes
None
# Additional Context
- reported by customer
- requires backport to v4.x
# Which Problems Are Solved
Zitadel did not provide easy correlation between errors, logs, traces
and metrics. The configuration for those instrumentations was also not
consistent, with some supporting different exporters then others.
Implementation and parsing of config was also spaghettified over
multiple packages, with awkward parsing and inconsistent naming of
options.
# How the Problems Are Solved
All telemetry is now merged under the name "instrumentation". Why?
1. We thought it was a good idea in the past to call the milestone
exporter `Telemtry` in the runtime config. Calling this `TelemetryV2`
looks weird.
2. Not everything is a meter and not everything is sent (tele...).
3. It's also
[defined](https://opentelemetry.io/docs/concepts/instrumentation/) as
such by the OTEL documentation.
## New features
- Adds structured, context based logging with trace-ID awareness
- Static log fields are added to the context, such as service and
request path
- Static log fields are injected in each logline emitted by the
application
- Structured logs can also be send to an otel exporter
- Structured logs can be printed to StdErr in text and JSON format
- Error sinks make sure every error is logged at the correct level:
- Warnings for client side errors (HTTP 400 range, Invalid request etc)
- Error for server side errors (Internal server errors)
- Metrics can now also be send to a OTEL collector. (previously they
could only be scraped from `/debug/metrics` with prometheus)
## Exporters
This change adds all the exporters supported by OTEL upstream and some
google specific exporters for our cloud deployment.
- StdOut / StdErr: all instrumentations
- OTEL gRPC / HTTP: all instrumentations
- Google: all instrumentations except logging
- Prometheus (pull-based): only metrics
The exception is profiling, which only supports the google exporting due
to lack of support by OTEL upstream.
## Configuration and structure
- All instrumentation is moved into the new `backend/v3/instrumentation`
package. It reuses configuration types, so both code and runtime
configuration are easier to understand.
- The `internal/telemetry` packages are removed.
- Instrumentation is started with a single function and a proper
shutdown function is now provided.
- Legacy configuration is still parsed from the runtime config, as long
as the new configuration is disabled. This allows backporting this
feature to v4 without breaking existing configurations.
# Additional Changes
- Devcontainer: set `$PATH` variable so installed go binaries can be run
individually, without NX.
- NX: install GCI tool to fix imports
# Additional Context
- Closes https://github.com/zitadel/zitadel/issues/8408
- Closes https://github.com/zitadel/zitadel/issues/6664
- Backport to v4
# Which Problems Are Solved
As part of the naming inconsistencies (#5888) we want to ensure action
v1 flow name are always correct and mapping to enum values line up:
#11309
# How the Problems Are Solved
Rename last "Customize SAML Response" occurrences to "Complement SAML
Response" where it's referring to the flow type. There are some titles
left with "customize SAML / OIDC response", which refer to the intent of
customizing the outcome and not directly to the flow type.
# Additional Changes
None
# Additional Context
- closes 11309
# Which Problems Are Solved
When building zitadel through `go build` or using an IDE debugging tool,
ldflags are not passed by dedault. In the past this was taken care of by
the `make compile` command, which got replaced by NX. The `nx
@zitadel/api:build` command does not set the ldflags either. Only the
`pack-platform` command does.
Because the ldflags aren't passed, the `date` and other variables remain
empty in the `cmd/build` package. During init of the package, if the
`version` is empty it defaults to the `date` variable. When the `date`
field was empty, the parsed `dateTime` would default to `time.Now()`,
but the `date` variable remained empty, resulting in a empty version.
A consistently empty version string prevents upgrades of projections on
dev systems, as the version from the last run is used.
# How the Problems Are Solved
If date failed to parse and `dateTime` is set to Now, use the formated
string of `dateTime` as `date`.
# Additional Context
- Blocks https://github.com/zitadel/zitadel/pull/11239
RamonandGitHub
Mridang AgarwallaandGitHub
Marco A.andGitHub
Livio SpringandGitHub
