Merge branch 'main' into feat_fix_pipeline_relation_example

Author: shariff-6

.github/workflows/claude-pr-reviewer.yml

@@ -0,0 +1,76 @@
+name: Claude Docs PR Reviewer
+on:
+  # pull_request:
+  #   types:
+  #     - synchronize
+  #     - reopened
+  #     - opened
+  #   branches:
+  #     - main
+  workflow_dispatch:
+
+jobs:
+  check-if-to-trigger:
+    name: Check if to trigger
+    outputs:
+      changed_files: ${{ steps.changed-files.outputs.any_changed }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Check for changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v46
+        with:
+          files: |
+            docs/**
+
+  claude-docs-pr-reviewer:
+    name: Claude Docs PR Reviewer
+    needs: check-if-to-trigger
+    if: needs.check-if-to-trigger.outputs.changed_files == 'true' && github.event.pull_request.head.repo.full_name == 'port-labs/port-docs'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Configure Git 
+        run: |
+          git config --global user.name "Port Claude AI"
+          git config --global user.email "port-claude-ai@port.io"
+
+      - name: Find and Delete Last Claude Comment
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          echo "Looking for the last Claude comment to delete..."
+          
+          # Get the last Claude comment ID (trying common patterns)
+          last_claude_comment=$(gh api repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments \
+            --jq '.[] | select(.user.login | test("claude"; "i")) | .id' | tail -1)
+          
+          if [ ! -z "$last_claude_comment" ]; then
+            echo "Deleting last Claude comment ID: $last_claude_comment"
+            gh api repos/${{ github.repository }}/issues/comments/$last_claude_comment -X DELETE
+          else
+            echo "No Claude comments found to delete"
+          fi
+
+      - name: Run Claude PR Action
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          allowed_tools: "Bash(git:*),Bash(gh:*),Bash(jq:*),Bash(yq:*),View,GlobTool,GrepTool,BatchTool"
+          direct_prompt: |
+           Please review the following PR and provide a detailed review of the changes according the ./CONTRIBUTING.md provide results in markdown format. Ignore all image files.
+          timeout_minutes: "15"

.github/workflows/sync-docs-with-mapping-config.yml

@@ -13,20 +13,20 @@ jobs:
 
     steps:
       - name: Checkout port-docs (automation tools)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           path: port-docs
 
       - name: Checkout ocean-test (YAML configs source)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: ${{ github.repository_owner }}/ocean-test
           token: ${{ secrets.MAPPING_PAT }}
           path: ocean-test
           ref: main
 
       - name: Checkout Port-monorepo (TypeScript source)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: ${{ github.repository_owner }}/Port-monorepo
           token: ${{ secrets.MAPPING_PAT }}

.github/workflows/updateApiSpec.yaml

@@ -16,7 +16,7 @@ jobs:
     steps:
     # Step 1: Checkout the repository
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         fetch-depth: 0  # Fetch all history for accurate diff
 
@@ -35,7 +35,7 @@ jobs:
     - name: Check for differences
       id: diff_check
       run: |
-        if cmp -s newSpec.yaml static/rawApiSpec.yaml; then
+        if cmp -s newSpec.yaml static/apispec.yaml; then
           echo "diff_found=false" >> $GITHUB_OUTPUT
           echo "No changes detected."
         else
@@ -46,7 +46,7 @@ jobs:
     # Step 5: Update the YAML file in the repository if differences are found
     - name: Update YAML file
       if: steps.diff_check.outputs.diff_found == 'true'
-      run: mv newSpec.yaml static/rawApiSpec.yaml
+      run: mv newSpec.yaml static/apispec.yaml
 
     # Step 6: Create a pull request with the changes using the hash as the branch name
     - name: Create Pull Request

.github/workflows/verify-docs-build.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Test successful production build
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           persist-credentials: true
       - name: Install dependencies

.gitignore

@@ -24,4 +24,7 @@ yarn-error.log*
 .vscode
 
 #workflow cache
-.github/script/__pycache__
+.github/script/__pycache__
+
+# Generated guide metadata
+src/components/guides-section/guide-metadata.json

docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/advanced-form-configurations.md

@@ -204,6 +204,16 @@ Keys that are supported with jqQuery expressions:
 | visible   | the condition to display any property in the form |
 | disabled  | the condition to disable any property in the form |
 
+:::tip Check if string is empty
+To check if a string input is empty, compare it to an empty string, like this:
+
+```json
+{
+  "jqQuery": ".form.version == \"\""
+}
+```
+:::
+
 ---
 
 #### Additional available properties

docs/actions-and-automations/define-automations/setup-trigger.md

@@ -247,8 +247,13 @@ The table below describes the fields in the JSON structure under the `trigger` k
 | **`type`** | The automation's trigger type. Should be set to `automation`. |
 | **`event`** | An object containing data about the event that triggers the automation. |
 | **`event.type`** | The [trigger event type](/actions-and-automations/define-automations/setup-trigger#available-triggers). |
-| **`event.blueprintIdentifier`**<br/>or<br/>**`event.actionIdentifier`** | If using an *entity trigger* - the identifier of the blueprint whose entities will trigger the automation.<br/>If using an *action run trigger* - the identifier of the action whose runs will trigger the automation. |
+| **`event.blueprintIdentifier`**<br/>or<br/>**`event.actionIdentifier`** | If using an *entity trigger* - the identifier of the blueprint whose entities will trigger the automation.<br/>If using an *action run trigger* - the identifier of the action/automation whose runs will trigger the automation. |
 | `condition` | An optional object containing `jq` expressions used to determine which entities the automation will be triggered for. |
 | `condition.type` | The type of condition. Should be set to `JQ`. |
 | `condition.expressions` | An array of expressions used to filter the entities for which the automation will be triggered. |
 | `condition.combinator` | The combinator used to combine the expressions. Should be set to `and` or `or`. |
+
+:::tip Automation action identifiers
+When using the `actionIdentifier` key, you can use an identifier that belongs to an automation as well.  
+This means that automations can be triggered by other automations and are not limited to self-service actions.
+:::

docs/actions-and-automations/reflect-action-progress/reflect-action-progress.md

@@ -128,7 +128,7 @@ When using a `Webhook` as the action backend, a [`Request type` option](/actions
 
 #### Run details
 
-By sending a [`PATCH` request](/api-reference/patch-an-action-run) to Port's API, you can do the following:
+By sending a [`PATCH` request](/api-reference/update-an-action-run) to Port's API, you can do the following:
 
 1. Update the run's status, by using the `status` key with one of these values: `SUCCESS`, `FAILURE`.  
    This will mark the run as completed and show a visual indicator, for example:
@@ -190,7 +190,7 @@ A log message with the `terminationStatus` key can only be sent once for an acti
 
 ## Tying Entities to an action run
 
-You can also add additional context and metadata to an action run by attaching a `run_id` query parameter to every API route that creates or changes an entity (i.e. [`POST`](/api-reference/create-an-entity), [`PUT`](/api-reference/change-an-entity), [`PATCH`](/api-reference/patch-an-entity) and [`DELETE`](/api-reference/delete-an-entity) entity requests).  
+You can also add additional context and metadata to an action run by attaching a `run_id` query parameter to every API route that creates or changes an entity (i.e. [`POST`](/api-reference/create-an-entity), [`PUT`](/api-reference/change-an-entity), [`PATCH`](/api-reference/update-an-entity) and [`DELETE`](/api-reference/delete-an-entity) entity requests).  
 
 By adding the `run_id` parameter, you reflect the change made to the Entity as part of the set of steps the action run performed during its runtime.
 

docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md

@@ -1,3 +1,6 @@
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+
 # Create/update entity
 
 In some cases, we don't want to run complex logic via a workflow or pipeline, but rather want our backend to simply create or update an entity in our software catalog.  
@@ -33,15 +36,15 @@ To use this backend type, you will need to define the following fields:
     | `team` | The team/s this entity will belong to. |
     | `icon` | The icon of the entity. |
     | `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. |
-    | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier. |
+    | `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for "many" relations). |
 
 ### Use jq to map the entity
 
 All fields in the `mapping` object can be mapped using `jq` expressions, by wrapping the value in double curly braces `{{ }}`.  
 
 For example, say we want to assign the initiator of the action to a new entity when it is created, we can take his email from the action run object and assign it to a property named `assignee`:
 
-```json
+```json showLineNumbers
 {
   "identifier": "someTaskEntity",
   "title": "Some Task",
@@ -55,3 +58,106 @@ For example, say we want to assign the initiator of the action to a new entity w
 :::tip Test your mapping
 You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema.
 :::
+
+## Map entity relations
+
+When creating or updating entities, you often need to establish relations with other entities. The mapping approach depends on whether you're dealing with single or multiple entity inputs.
+
+
+<Tabs groupId="relation-mapping" defaultValue="single" values={[
+{label: "Single Entity", value: "single"},
+{label: "Array Entity", value: "array"},
+{label: "Flexible Mapping", value: "flexible"}
+]}>
+
+<TabItem value="single">
+
+For a single entity relation, map the entity identifier directly:
+
+```json showLineNumbers
+{
+  "identifier": "myServiceEntity",
+  "title": "My Service",
+  "properties": {},
+  "relations": {
+    "domain": "{{ .inputs.domain }}"
+  }
+}
+```
+
+</TabItem>
+
+<TabItem value="array">
+
+When your action accepts [array entity inputs](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), you need to extract the identifiers from the array using the `map(.identifier)` pattern:
+
+```json showLineNumbers
+{
+  "identifier": "myUserEntity", 
+  "title": "My User",
+  "properties": {},
+  "relations": {
+    "skills": "{{ .inputs.skills | map(.identifier) }}"
+  }
+}
+```
+
+:::info Array entity inputs
+When users select multiple entities from an [entity array input](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), the input contains an array of entity objects. Each object includes both `identifier` and `title` properties, but relations can only reference entity identifiers.
+:::
+
+</TabItem>
+
+<TabItem value="flexible">
+
+For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs:
+
+```json showLineNumbers
+{
+  "identifier": "myProjectEntity",
+  "title": "My Project", 
+  "properties": {},
+  "relations": {
+    "dependencies": "{{ .inputs.dependencies | if type == \"array\" then map(.identifier) else .identifier end }}"
+  }
+}
+```
+
+This pattern automatically:
+- Extracts identifiers from arrays when multiple entities are selected
+- Uses the identifier directly when a single entity is selected
+
+</TabItem>
+
+</Tabs>
+
+
+### Common use cases
+
+Here are some typical scenarios for mapping array relations:
+
+**Mapping skills to a user:**
+```json showLineNumbers
+"relations": {
+  "skills": "{{ .inputs.selectedSkills | map(.identifier) }}"
+}
+```
+
+**Mapping team members to a project:**
+```json showLineNumbers
+"relations": {
+  "members": "{{ .inputs.teamMembers | map(.identifier) }}"
+}
+```
+
+**Mapping dependencies between services:**
+```json showLineNumbers
+"relations": {
+  "dependsOn": "{{ .inputs.dependencies | map(.identifier) }}"
+}
+```
+
+
+:::info Entity titles in relations
+Relations can only reference entity **identifiers**, not titles. Even though entity objects contain both `identifier` and `title` properties, you must always use `.identifier` when mapping to relations.
+:::

docs/actions-and-automations/setup-backend/webhook/webhook.md

@@ -78,7 +78,7 @@ Alternatively, you can set the execution type to **synchronous**, which will cau
 ### HTTP method
 
 By default, a `POST` request will be sent to the specified endpoint URL.  
-You can change the request to any of the supported types: `POST`, `PUT`, `DELETE`, or `PATCH`.
+You can change the request to any of the supported types: `POST`, `GET`, `PUT`, `DELETE`, or `PATCH`.
 
 ## Trigger Port API