Add service Account documentation for docs

.azure/dev-pr-check.yaml

@@ -1,7 +1,7 @@
 pr:
   branches:
     include:
-      - dev
+      - PE
 
 trigger: none
 

.azure/templates/build.yaml

@@ -42,23 +42,48 @@ steps:
 
       cwd=`pwd`
 
-      for dir in ${cwd}/*/; do
-        if [ -d ${f} ]; then
-        dir=${dir%*/}
-        dirName=${dir##*/}
-          if [ ${dirName} != "dist" ]; then
-          mkdir -p $(Build.ArtifactStagingDirectory)/dist/${dirName}
-          cd ${dir}
+      # Define known document directories and their site subdirectories
+      declare -A SITE_DIRS=(
+        ["developer-docs"]="developer"
+        ["pe-docs"]="platform-engineer"
+      )
 
-          pwd
-          mkdocs build -c
-
-          cd ../..
-          ls ${cwd}/${dirName}/site/
-          mv -f ${cwd}/${dirName}/site/* $(Build.ArtifactStagingDirectory)/dist/${dirName}/
+      # Process only the required directories
+      for doc_dir in "${!SITE_DIRS[@]}"; do
+        echo "Processing ${doc_dir}..."
+        # Find the parent directory containing this doc directory
+        for parentDir in ${cwd}/*/; do
+          if [ -d "${parentDir}${doc_dir}" ]; then
+            parentDir=${parentDir%*/}
+            parentDirName=${parentDir##*/}
+
+            # Create destination directory
+            mkdir -p $(Build.ArtifactStagingDirectory)/dist/${doc_dir}
+
+            # Build the documentation
+            cd "${parentDir}/${doc_dir}"
+            pwd
+            mkdocs build -c
+
+            # Move the built files to the staging directory
+            site_subdir="${SITE_DIRS[${doc_dir}]}"
+            echo "Moving files from site/${site_subdir}/ to dist/${doc_dir}/"
+            ls "${cwd}/${parentDirName}/${doc_dir}/site/${site_subdir}/"
+            mv -f "${cwd}/${parentDirName}/${doc_dir}/site/${site_subdir}"/* $(Build.ArtifactStagingDirectory)/dist/${doc_dir}/
+
+            # Return to the original directory
+            cd "${cwd}"
+            break
           fi
-        fi
+        done
       done
 
       echo "=== After building ==="
-      ls -l $(Build.ArtifactStagingDirectory)/dist/
+      # Check that the expected directories have content
+      for doc_dir in "${!SITE_DIRS[@]}"; do
+        ls -l $(Build.ArtifactStagingDirectory)/dist/${doc_dir}
+        if [ -z "$(ls -A $(Build.ArtifactStagingDirectory)/dist/${doc_dir})" ]; then
+          echo "Error: ${doc_dir} directory is empty."
+          exit 1
+        fi
+      done

.github/workflows/ci.yml

@@ -1,8 +1,8 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
-     - dev
+      - PE
 permissions:
   contents: write
 jobs:
@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.12
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
@@ -44,6 +44,34 @@ jobs:
           pip install mkdocs-glightbox==0.3.4
           pip install mkdocs-include-markdown-plugin==1.0.0
           pip install mkdocs-open-in-new-tab==1.0.3
-      - run: mkdocs gh-deploy --config-file en/mkdocs.yml --force
+      - name: Build site developer
+        run: mkdocs build --config-file en/developer-docs/mkdocs.yml
+      - name: Build site platform-engineer
+        run: mkdocs build --config-file en/pe-docs/mkdocs.yml 
+      - name: Create/fetch gh-pages-v2
+        run: |
+          if git ls-remote --heads origin gh-pages-v2 | grep -q gh-pages-v2; then
+            git fetch origin gh-pages-v2
+            git checkout gh-pages-v2
+          else
+            git switch --orphan gh-pages-v2
+          fi
+      - name: Create gh-pages-v2 branch developer subdirectory
+        run: |
+          rm -rf choreo/docs/developer  # Clear existing directory if needed
+          mkdir -p choreo/docs/developer
+          cp -r en/developer-docs/site/developer/* choreo/docs/developer/ 
+      - name: Create gh-pages-v2 branch platform-engineer subdirectory
+        run: |
+          rm -rf choreo/docs/platform-engineer  # Clear existing directory if needed
+          mkdir -p choreo/docs/platform-engineer
+          cp -r en/pe-docs/site/platform-engineer/* choreo/docs/platform-engineer/
+      - name: Push Changes to gh-pages-v2
+        run: |
+          git add choreo/docs/developer/
+          git commit -m "Update developer directory"
+          git add choreo/docs/platform-engineer/
+          git commit -m "Deploy to platform-engineer directory"
+          git push origin gh-pages-v2 --force
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}                 

README.md

@@ -103,7 +103,7 @@ $ pip install --upgrade pip
 To clone the Choreo documentation GitHub repository and run the site on your local server, follow these steps:
 
 1. Fork `https://github.com/wso2/docs-choreo-dev`.
-2. Navigate to the locatiion where you want to clone the repo and clone the forked repository.
+2. Navigate to the location where you want to clone the repo and clone the forked repository.
 
     ```shell
     $ git clone https://github.com/[git-username]/docs-choreo-dev.git

en/docs/administer/configure-a-custom-domain-for-your-organization.md → en/developer-docs/docs/administer/configure-a-custom-domain-for-your-organization.md

@@ -6,7 +6,7 @@ This section provides an overview of Choreo’s custom domain configuration mode
 
 ## Choreo custom domain configuration model
 
-Choreo allows organization administrators to add custom domains for their organizations. When an administrator adds custom domains to an organization, component developers can submit requests to utilize the custom domains for their respective components. These requests require approval from the organization administrator. Upon approval, the custom domain and the relevant URL customization become available to the component.
+Choreo allows organization administrators to add custom domains for their organizations. When an administrator adds custom domains to an organization, developers can utilize the custom domains for their respective components. 
 
 ## Configure a custom domain for an organization
 
@@ -123,7 +123,7 @@ You can see the added custom domain listed in the **Active Domains** tab under t
 
  ![Active domains](../assets/img/administer/configure-domain/active-domains.png)
 
-The custom domain you added will be available to the entity types in the specified environment. You can request the custom domain when configuring a custom URL for a component.
+The custom domain you added will be available to the entity types in the specified environment. You can use the custom domain when configuring a custom URL for a component.
 
 !!! info "Note"
      If you add a custom domain for the **Developer Portal** type, the customization is applied immediately, and you can access the organization’s Developer Portal via the added domain.
@@ -132,14 +132,14 @@ If you want to view the entity types that use a particular custom domain, click
 
 ## Configure a custom URL for a component
 
-When an organization administrator adds custom domains for specific environments, developers can request any available custom domain to configure a custom URL for a component in a specific environment.
+When an organization administrator adds custom domains for specific environments, developers can use any available custom domain to configure a custom URL for a component in a specific environment.
 
-### Request a custom URL for a component
+### Add a custom URL to a component
 
-To request a custom URL for your component, follow the steps given below:
+To add a custom URL for your component, follow the steps given below:
 
 !!! info "Note"
-     Before you request a custom domain for a specific environment, ensure that the component is deployed to that environment.
+     Before you add a custom domain for a specific environment, ensure that the component is deployed to that environment.
 
 1. Sign in to the [Choreo Console](https://console.choreo.dev/).
 2. In the **Component Listing** pane, click on the component for which you want to customize the URL.
@@ -148,41 +148,24 @@ To request a custom URL for your component, follow the steps given below:
 
     ![Active deployments](../assets/img/administer/configure-domain/active-deployments.png)
 
-5. To configure a custom URL for a component in a specific environment, click the **Edit URL Mapping** icon under the **Action** column corresponding to the respective environment. This opens the **URL Settings** dialog, where you can specify values to request for a custom URL.
+5. To configure a custom URL for a component in a specific environment, click the **Edit URL Mapping** icon under the **Action** column corresponding to the respective environment. This opens the **URL Settings** dialog, where you can specify values to add to a custom URL.
 
     ![URL settings](../assets/img/administer/configure-domain/url-settings.png)
 
 6. In the **URL Settings** dialog, select a domain to configure a custom URL.
 
     !!! tip
-          - The **Domain** drop-down lists the available domains for the component. You can  request for any listed domain.
-          - If you want to request a custom URL for an API, you must specify an appropriate context path in the **Path** field. The **Path** field displays the default context path for the API. You can edit the path depending on your preference. 
+          - The **Domain** drop-down lists the available domains for the component. You can  add any listed domain.
+          - If you want to add a custom URL for an API, you must specify an appropriate context path in the **Path** field. The **Path** field displays the default context path for the API. You can edit the path depending on your preference. 
 
-7. Click **Configure**. This creates the custom URL mapping, which you can see under the **URL Settings** tab.  The custom URL request will be in the **Pending** status until an organization administrator approves the request.
+7. Click **Deploy**. This creates the custom URL mapping, which you can see under the **URL Settings** tab.  The custom URL will be in the **Approved** state.
 
-    ![Pending custom URL request](../assets/img/administer/configure-domain/pending-custom-url-request.png)
-
-### Approve a custom URL request
-
-When a developer requests a custom URL, the request will be listed in the organization-level settings page under the **URL Settings** tab.
-
-To approve a custom URL mapping, follow the steps given below:
+    ![Approved custom URL](../assets/img/administer/configure-domain/approved-custom-url.png)
 
 !!! info "Note"
-     To approve custom URL requests, you must have organization administrator privileges.
-
-1. Sign in to the [Choreo Console](https://console.choreo.dev/).
-2. In the Choreo Console header, click the **Organization** list.
-3. In the left navigation menu, click **Settings**. This opens the organization-level settings page.
-4. Click the **URL Settings** tab and then click the **Pending URL Requests** tab. You will see all the pending URL mapping requests sent by developers.
-
-    ![Pending URL requests](../assets/img/administer/configure-domain/pending-url-requests.png)
-
+     By default, any user with the `Manage URL Mappings` permission can deploy custom URL mappings. For better governance, you can configure an approval process for URL mappings using [Choreo Workflows](./configure-approvals-for-choreo-workflows.md).
 
-5. Go to the custom URL you want to approve and click the corresponding **Approve URL Mapping** icon under the **Action** column.
-6. Review the details and click **Approve**.
-
-   Once approved, the invoke URL of the component gets replaced with the configured custom URL.
+   Once deployed, both the custom URL and the default URL can be used to access the component. 
 
    ![Custom URL](../assets/img/administer/configure-domain/custom-url.png)
 

en/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md → en/developer-docs/docs/administer/configure-an-external-idp/configure-azure-ad-as-an-external-idp.md

@@ -24,7 +24,7 @@ Follow the steps below to add Azure AD as an IdP in Choreo:
     !!! info
         - In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats)
         For example, convert `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`-> `https://login.microsoftonline.com/<tenant-id>/.well-known/openid-configuration`
-        - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access tokendocumentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). 
+        - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access token documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). 
 
 8. Leave the **Apply to all environments** checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the **Environments** list.
 9. Review the endpoints and click **Next**.

en/docs/administer/configure-approvals-for-choreo-workflows.md → en/developer-docs/docs/administer/configure-approvals-for-choreo-workflows.md

@@ -2,12 +2,14 @@
 
 Choreo allows you to configure approval processes for specific workflows within the platform. An approval process for a workflow ensures that critical or sensitive changes are properly managed and controlled.
 
-Choreo currently allows you to configure approvals for environment promotion and API subscription workflows.
+Choreo currently allows you to configure approvals for environment promotion, API subscription and URL customization workflows.
 
 Configuring approvals for environment promotion allows authorized users to control components being promoted to a critical/production environment. 
 
 Configuring approvals for the API subscription workflow allows you to create subscription plans that require approval before being activated. This feature allows you to control access to APIs by requiring administrative review and authorization of subscriptions before they become active.
 
+Configuring approvals for URL customization workflows allows you to control custom URL mappings by requiring review and approval before the customization is applied.
+
 ## Permissions to review and respond to approval requests
 
 Click the respective tab for details on permissions depending on the workflow for which you want to configure approvals:
@@ -29,6 +31,15 @@ Click the respective tab for details on permissions depending on the workflow fo
       - **PROJECT-MANAGEMENT**: 
           Grants access to view and approve workflow requests. This is the same permission used to update or delete projects.
 
+=== "URL customization"
+
+     To review and respond to URL customization approval requests, a user must have the following permissions. Administrators must ensure that users designated to review and respond to approval requests have these permissions:
+
+      - **WORKFLOW-MANAGEMENT**:
+          - Approve custom URL mapping requests: Grants access to review and approve custom URL mapping requests.
+      - **URL-MANAGEMENT**: 
+          - Manage Custom Domains: Grants access to manage custom domains for the organization.
+
 ## Set up an approval process for a workflow
 
 To set up an approval process for a workflow, follow these steps:
@@ -61,3 +72,7 @@ Once you enable the approval process for a workflow, see the following details o
 === "API subscription"
 
      Once you configure an approval process for API subscription, administrators can select the **Approval required** checkbox to create or update subscription plans to require approval. For details, see [Create API Subscription Plans](../administer/create-api-subscription-plans.md). API consumers using these plans must request approval to proceed. For details, see step 7 in [Subscribe to an API with a Subscription Plan](../api-management/manage-api-traffic/subscribe-to-an-api-with-a-subscription-plan.md). An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the subscription is granted.
+
+=== "URL customization"
+
+     Once you configure an approval process for URL customization, developers must submit a request for approval to configure a custom URL for a component. Instead of being automatically deployed, the URL mapping will go into a pending state. An authorized approver must then [review and approve the request](./review-workflow-approval-requests.md) before the custom URL is activated for the respective component. 

en/developer-docs/docs/administer/configure-exposed-environments-to-developer-portal.md

@@ -0,0 +1,16 @@
+# Configure Exposed Environments to Developer Portal
+
+The Choreo Developer Portal enables external developers to discover and consume APIs published by your organization. Through the Choreo Console, you can manage which API environments are visible and accessible in the Developer Portal.
+
+Follow these steps to configure which environments are visible in the Developer Portal:
+
+!!! Note -
+    Organizations created after **April 24th, 2025**, will have the **Production** environment exposed by default. Organizations created before this date will continue to allow all environments visible in the Developer Portal.
+
+1. Sign in to [Choreo](https://console.choreo.dev/).
+
+2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. 
+
+3. In the left navigation menu, click **Settings**. Under the **API Management** tab, go to **Developer Portal**.
+
+4. Expand the **Environments** section and configure the environments exposed to the Developer Portal.

en/developer-docs/docs/administer/configure-identity-providers-for-developer-portal.md

@@ -0,0 +1,19 @@
+# Configure Identity Providers for Developer Portal
+
+You can configure the Identity Providers (IdPs) available for consumers to authenticate and generate API keys in the Developer Portal from the Choreo Console.
+
+!!! Note -
+    Organizations created after **April 24th, 2025**, will have the **Choreo Built-in Identity Provider** configured by default. Organizations created before this date will continue to allow all configured identity providers to be used in the Developer Portal.
+
+Follow these steps to configure Identity Providers:
+
+1. Sign in to [Choreo](https://console.choreo.dev/).
+
+2. In the Choreo Console, go to the top navigation menu and click **Organization**. Then select your organization. 
+
+3. In the left navigation menu, click **Settings**. Under the **API Management** tab, go to **Developer Portal**.
+
+4. In the **Identity Providers** section, specify which identity providers should be used for both the **Sandbox** and **Production** environments of the Developer Portal.
+
+!!! Note -
+    Any identity provider configured for the Developer Portal's **Production** environment must also be enabled in the Choreo **Production** environment.