mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## 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]>
This commit is contained in:
Florian Forster
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Actions
|
||||
sidebar_label: Overview
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
An Identity and Access Management system is a highly interactive environment. ZITADEL includes a powerful feature called **Actions**, which allows you to programmatically react to specific events within the system.
|
||||
|
||||
Actions allow you to define custom scripts (JavaScript) that are executed based on specific triggers (Flows). This enables advanced customization, such as modifying tokens, calling external APIs during login, or customizing authentication flows.
|
||||
|
||||
<img
|
||||
src="/docs/img/guides/console/actionsmenu.png"
|
||||
width="700px"
|
||||
alt="Actions menu"
|
||||
/>
|
||||
|
||||
## How Actions Work
|
||||
|
||||
The Actions architecture consists of three main components:
|
||||
|
||||
1. **Action:** The JavaScript code containing your business logic.
|
||||
2. **Trigger Type:** The specific event in ZITADEL (e.g., "Post Authentication") where code execution is allowed.
|
||||
3. **Flow:** The configuration that links an Action to a Trigger Type.
|
||||
|
||||
### The JavaScript Runtime
|
||||
|
||||
ZITADEL interprets your Action scripts as JavaScript.
|
||||
|
||||
* **Compliance:** Scripts must be **ECMAScript 5.1(+)** compliant.
|
||||
* **Engine:** The underlying engine is [goja](https://github.com/dop251/goja). Refer to their documentation for detailed references about the underlying library features and limitations.
|
||||
|
||||
### Structure of an Action Script
|
||||
|
||||
The script of an action must contain a function that matches the Action's name. ZITADEL calls this function at runtime.
|
||||
|
||||
The function receives two primary objects:
|
||||
|
||||
* `ctx` (Context): Provides **readable** information about the current request (User, Request Info, etc.).
|
||||
* `api` (API): Provides **methods** to mutate state (Set Claims, Deny Access, etc.).
|
||||
|
||||
**Example:**
|
||||
If your action is named **doSomething**, your script must look like this:
|
||||
|
||||
```js
|
||||
function doSomething(ctx, api){
|
||||
// read from ctx and manipulate with api
|
||||
}
|
||||
```
|
||||
|
||||
### Available Modules
|
||||
|
||||
You can use the following built-in modules inside your JavaScript code:
|
||||
|
||||
* [**HTTP module**](../../../apis/actions/modules#http): To call external APIs / Webhooks.
|
||||
* [**Logging module**](../../../apis/actions/modules#log): To log information to stdout (useful for debugging).
|
||||
* [**UUID module**](../../../apis/actions/modules#uuid): To generate UUIDs.
|
||||
|
||||
Stuck customizing ZITADEL actions? Find samples for setting OIDC claims, SAML attributes, extending JIT provisioning data, calling external APIs, and more in [this repository](https://github.com/zitadel/actions).
|
||||
|
||||
## Managing Actions in Management Console
|
||||
|
||||
### 1. Create an Action
|
||||
|
||||
To add an action, navigate to your Organization's top navigation and select **Actions**. Click the **New** button and provide:
|
||||
|
||||
* **Name:** Must match the function name in your script.
|
||||
* **Script:** Your JavaScript code.
|
||||
* **Timeout:** How long the script is allowed to run before being terminated.
|
||||
* **Allowed to Fail:** If checked, the flow will continue even if the script throws an error.
|
||||
|
||||
<img src="/docs/img/guides/console/action.png" alt="Create Action" width="450px" />
|
||||
|
||||
### 2. Create a Flow (Link Action to Trigger)
|
||||
|
||||
Merely creating an Action does not run it. You must create a **Flow** to define *when* it runs.
|
||||
|
||||
1. Select the **Flow Type** (e.g., External Authentication).
|
||||
2. Select the **Trigger** (e.g., Post Authentication).
|
||||
3. Add your Action to the list of executed scripts.
|
||||
|
||||
<img src="/docs/img/guides/console/flow.png" alt="Flow" width="400px" />
|
||||
|
||||
**Example Scenario:**
|
||||
You create an **External Authentication** Flow with a **Post Authentication** trigger. Now, whenever a user authenticates via an external IDP (like Google or Azure AD), your Action is triggered immediately after the authentication step but before the session is finalized.
|
||||
|
||||
## Available Flow Types
|
||||
|
||||
Trigger types define the point during the execution of a request. Each trigger defines which readable information (`ctx`) and mutable properties (`api`) are passed into the called function.
|
||||
|
||||
Currently, ZITADEL supports the following flows:
|
||||
|
||||
* [**Internal Authentication**](../../../apis/actions/internal-authentication): Triggers during login with ZITADEL (username/password).
|
||||
* [**External Authentication**](../../../apis/actions/external-authentication): Triggers during login with an external Identity Provider.
|
||||
* [**Complement Token**](../../../apis/actions/complement-token): Triggers when tokens (ID Token / Access Token) are created, allowing you to add custom claims.
|
||||
* [**Customize SAML Response**](../../../apis/actions/customize-samlresponse): Triggers when a SAML response is generated.
|
||||
|
||||
## References
|
||||
|
||||
* [Guide: Customize Behavior with Actions](/guides/manage/customize/behavior)
|
||||
* [ZITADEL Roadmap](https://zitadel.com/roadmap)
|
||||
Reference in New Issue
Block a user