Merge branch 'main' into PORTN-123-rename-old-aws-to-aws-on-prem-2

Author: sivanel97

docs/actions-and-automations/actions-and-automations.md

@@ -5,10 +5,9 @@ import PortTooltip from "/src/components/tooltip/tooltip.jsx"
 One of Port's core offerings is the ability to automate and simplify the processes and routines of your developers.  
 This is done using two powerful tools:
 
-## 1. Self-service actions
+## 1. Actions
 
-Create a wide range of personalized, controlled actions that developers can use to scaffold a service, provision a cloud resource, or any other logic that serves your organization.  
-Self-service actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that developers or AI agents can run. You can create a wide range of personalized, controlled actions to scaffold a service, provision a cloud resource, or any other logic that serves your organization. Actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 :::tip Live demo
 For real-world examples of self-service actions, check out our [live demo](https://showcase.port.io/self-serve).

docs/actions-and-automations/create-self-service-experiences/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Create self-service actions",
+  "label": "Create actions",
   "position": 1
 }

docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md

@@ -14,7 +14,9 @@ import ExecuteActionLocations from '/docs/actions-and-automations/create-self-se
 </center>
 <br/>
 
-Drive developer productivity by allowing developers to use self-service actions like scaffolding a service or provisioning a cloud resource. Developer self-service drives consistency and repeatability and ensures that their routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that either developers or AI agents can run. They drive developer productivity by enabling them to use actions like scaffolding a service or provisioning a cloud resource.  
+
+Actions drive consistency and repeatability and ensure that routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 Port's action model is designed to be flexible and can be used to cover a wide range of use-cases:
 
@@ -24,7 +26,7 @@ Port's action model is designed to be flexible and can be used to cover a wide r
 4. **Stateful** - every invoked action affects the software catalog by adding/modifying/deleting one or more entities.
 5. **Secure by design** - does not require keys to sensitive infrastructure by using an event-based model. All actions are audited and can include guardrails like manual approval and TTL.
 
-## 💡 Common self-service actions
+## Common self-service actions
 
 - [**Scaffold** a new service](https://docs.port.io/guides/all/scaffold-a-new-service/).
 - [**Create** a cloud resource](https://docs.port.io/guides/all/create-cloud-resource-using-iac).
@@ -37,7 +39,7 @@ In our [live demo](https://showcase.port.io/self-serve), you can see examples fo
 
 ## How does it work?
 
-1. A user **executes an action** from Port's UI interface.
+1. A user or AI agent **executes an action** from Port's UI interface or through API calls.
 2. A pre-defined **payload** containing any desired metadata about the action and its inputs is **sent** to your infrastructure.
 3. A **job is triggered** and the user gets a **continuous indication** about its progress.
 4. Once the action is running, you can use Port's API to **update Port on its status** and provide information such as **logs and links to the resulting handlers**.

docs/customize-pages-dashboards-and-plugins/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "Pages & dashboards",
+  "label": "Interface designer",
   "position": 8,
   "className": "custom-sidebar-item sidebar-menu-pages-and-dashboards"
 }

docs/customization.md renamed to docs/customize-pages-dashboards-and-plugins/customization.md

@@ -125,37 +125,31 @@ Next, we will create an AI agent that generates GitHub issues from Jira tickets
 
     ```json showLineNumbers
     {
-      "identifier": "github_issue_creation",
-      "title": "Github Issue Creation",
+      "identifier": "work_item_synchronizer",
+      "title": "Work Item Synchronizer",
       "icon": "Details",
       "team": [],
       "properties": {
-        "description": "Creates Github issues from Jira tickets",
+        "description": "Ensures seamless workflow continuity across development tools",
         "status": "active",
-        "allowed_blueprints": [
-          "service",
-          "githubIssue",
-          "githubRepository",
-          "_user",
-          "_team"
-        ],
-        "allowed_actions": [
-          "create_github_issue"
-        ],
         "prompt": "Create a GitHub issue that builds on the context of a linked Jira ticket.\n\nThe GitHub issue should:\n1.\tSummarize and clearly explain the task, using the Jira description as a base.\n2.\tAugment the description with relevant insights from the repository — such as the README, setup or contribution instructions, existing issues, or implementation notes — to make the issue fully self-contained.\n3.\tThe **issue title MUST start with the Jira ticket key**, using the format: `<Jira-Ticket-ID> - <what needs to be done>` (e.g., `JIRA-1234 - Add missing lint configuration`). This ensures PRs created by Copilot are linkable back to Jira.\n4.\tAdd GitHub labels, including one with the Jira ticket key (e.g., `JIRA-1234`), and any additional relevant labels (e.g., bug, enhancement, infra).\n5.\tAlso include a label named `auto_assign` in all creations.\n6. The GitHub issue body should end with the following directive:\n🚨 **IMPORTANT NOTE FOR COPILOT**: When creating the pull request to resolve this issue:\n    1. You **must ALWAY include the Jira ticket ID** (e.g., `JIRA-1234`) in the **PR title**.\n    2. Do **not** rename the PR title or remove the Jira ticket reference.\n    3. Add GitHub labels with the Jira ticket key (e.g., `JIRA-1234`) to the PR.\n\nIf no direct match can be confidently made (e.g., across multiple repos), make a best guess, and clearly state any assumptions in the issue body.",
         "execution_mode": "Automatic",
-        "conversation_starters": []
+        "conversation_starters": [],
+        "tools": [
+          "^(list|get|search|track|describe)_.*",
+          "run_create_github_issue"
+        ]
       },
       "relations": {}
     }
     ```
     </details>
 
-5. Click `Create` to save the agent.
+    :::tip MCP Enhanced Capabilities
+    The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog, providing richer context for GitHub issue creation. Additionally, we explicitly add `run_create_github_issue` to the tools, which instructs the AI agent to call this specific action to create GitHub issues from Jira tickets.
+    :::
 
-:::tip Enhance Context with Integrations
-The more integrations and data you add to the agent, the richer the context it will provide to the Copilot agent. Consider integrating additional data sources like deployment history, related incidents, and more to enhance the AI agent's effectiveness.
-:::
+5. Click `Create` to save the agent.
 
 
 ## Set up automations
@@ -207,7 +201,7 @@ This automation can be configured to trigger based on various criteria. Currentl
       },
       "invocationMethod": {
         "type": "WEBHOOK",
-        "url": "https://api.getport.io/v1/agent/github_issue_creation/invoke",
+        "url": "https://api.getport.io/v1/agent/work_item_synchronizer/invoke",
         "agent": false,
         "synchronized": true,
         "method": "POST",

docs/guides/all/automatically-resolve-tickets-with-coding-agents.md

@@ -65,37 +65,28 @@ Install the following integration to have access to these data sources:
    ```json showLineNumbers
    {
      "identifier": "task_assistant_ai_agent",
-     "title": "Task Assistant AI Agent",
-     "icon": "Airflow",
+     "title": "Clarity AI",
+     "icon": "Details",
+     "team": [],
      "properties": {
+       "description": "Automatically enriches Jira tasks with relevant context when developers start working on them",
        "status": "active",
-       "allowed_blueprints": [
-         "service",
-         "githubRepository",
-         "_user",
-         "githubPullRequest",
-         "jiraIssue",
-         "jiraProject",
-         "githubUser",
-         "_team",
-         "jiraUser"
-       ],
-       "allowed_actions": [
-         "comment_on_jira_issue"
-       ],
-       "executionMode": "Automatic",
-       "prompt": "## Comment Format\n\nHey there [User's First Name], it's Clarity - the Port AI agent!\nI noticed you just started working on a new task: [link to assigned issue].\nHere's some context to help you get started\n\nDevs who might have input:\nList up to 3 developers (excluding the user), explain briefly why each is relevant. If none, write a meaningful explanation.\n\nSimilar Jira Issues:\nList up to 3 Jira issues (not assigned to the user), mention the assigned person and why it's relevant. If none, explain why.\n\nSimilar Pull Requests:\nList up to 3 pull requests (not assigned to the user), mention the creator and why it's relevant. If none, explain why.\n\nEach section can have fewer than 3 items. Always explain if empty.\n\n## Instructions\n\nSend the comment according to the format above in the most relevant given JIRA Issue. Use the `comment_on_jira_issue` tool to achieve that.",
-       "allowed_tools": [
-         "Entities Search",
-         "Entities Similarity Search",
-         "Entities Group"
+       "prompt": "# Task\nUse the \"comment_on_jira_issue\" action, automatically send a greeting using their first name and explain this is an automatic message. Then share three sections with emojis for helpful context.\n\n## Message Format\nHey there [First Name], it's Clarity :crystal_ball: - the Port AI agent!\nI noticed you just started working on a new task: [link to assigned issue].\nHere's some context to help you get started :blobdance:\n\n:male-technologist: Devs who might have input:\nList up to 3 developers (excluding the user), explain briefly why each is relevant. If none, write a meaningful explanation.\n\n:jira: Similar Tasks:\nList up to 3 Jira issues (not assigned to the user), mention the assigned person and why it's relevant. If none, explain why.\n\n:github_on_fire: Similar Pull Requests:\nList up to 3 pull requests in statuses \"open\" or \"merged\", mention the creator and why it's relevant. If none, explain why.\n\n## Guidelines\n- Each section can have fewer than 3 items. Always explain\n",
+       "execution_mode": "Automatic",
+       "tools": [
+         "^(list|get|search|track|describe)_.*",
+         "run_comment_on_jira_issue"
        ]
      },
      "relations": {}
    }
    ```
    </details>
 
+   :::tip MCP Enhanced Capabilities
+   The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog, providing richer context for task enrichment. Additionally, we explicitly add `run_comment_on_jira_issue` to the tools, which instructs the AI agent to call this specific action to comment on Jira issues with contextual information.
+   :::
+
 5. Click on `Create` to save the agent.
 
 ### Set up the automation trigger

docs/guides/all/enrich-tasks-with-ai.md

@@ -265,31 +265,31 @@ Next, we will create an AI agent that generates helpful incident updates with co
       "icon": "Alert",
       "team": [],
       "properties": {
-        "description": "AI agent that generates contextual incident updates and sends them to Slack with on-call tagging",
+        "description": "AI agent that generates helpful incident updates and sends them to Slack with on-call tagging",
         "status": "active",
-        "allowed_blueprints": [
-          "pagerdutyIncident",
-          "service",
-          "githubRepository"
-        ],
-        "allowed_actions": [
-          "update_incident_with_ai_update"
-        ],
-        "prompt": "You are an expert incident management AI agent generating clear, contextual incident updates for Slack notifications.\nYour task is to produce Slack-compatible incident updates for incident changes shared with engineering and on-call teams. Focus on clarity, relevance, and next steps.\n\nYour Slack incident update MUST follow this structure and tone:\n\n- 🚨 *Problem:* Brief description of what changed and why it triggered this update.\n- 📊 *Impact:* Which services or what is affected? Any delivery, uptime, or user-facing issues?\n- 🧠 *Insights / Diagnostics:* Add key technical context from repository metadata: last commit, contributor, vulnerabilities, etc or draw from your technical knowledge on what would have caused this.\n- 🔧 *Action Required:* List next steps for the on-call team. Be specific about what they need to check or resolve.\n\n🔧 **Slack Output Rules**\n* NEVER USE `**bold**` or `[text](url)` — instead use:\n    * `*bold*` for emphasis\n     * `<https://url.com|Label>` for links\n* Use emoji to indicate sections: `🚨`, `📋`, `👥`, `🔄`\n* Use bullet points (`-`) for clarity\n* Separate sections with one line space (not headers)\n* Never include raw markdown headers like `###` or `---`\n* Your final output **must** look clean when copy-pasted into a Slack message.\n\n*After generating your incident update, you MUST ALWAYS run the 'update_incident_with_ai_update' action to save the update to the incident record.*\n\n## Sample Response Format\n🚨 *Incident Update: API Latency Spike on analytics-service*\n\n*Problem:*\n`analytics-service` has breached its latency SLO for the past 15 minutes. Response time spiked from 800ms to 4.5s\n\n*Impact:*\nThis service powers real-time analytics for customer dashboards. Users may experience slow or failing dashboard loads, particularly in high-traffic regions.\n\n*Insights/Diagnostics:*\n- The latest deployment (2025-07-21 13:03 UTC) introduced new filtering logic\n- Recent commits by Maria include changes to Redis query batching and fallback caching\n- Maria is not currently on-call. Assigned engineers: Omri and Tal.\n- 2 known vulnerability exists—could be a contributing factor.\n\n🔧 *Action Required:*\n- On-call engineers Marvin and Tal should roll back to the previous deploy version while isolating the Redis call regressions.\n- Re-run load tests locally with Maria's changes to confirm memory/caching issues.\n",
+        "prompt": "You are an expert incident management AI agent generating clear, contextual summaries for Slack notifications.\nYour task is to produce Slack-compatible summaries for incident updates shared with engineering and on-call teams. Focus on clarity, relevance, and next steps.\n\nYour Slack summary MUST follow this structure and tone:\n\n- 🚨 *Problem:* Brief summary of what changed and why it triggered this update.\n- 📊 *Impact:* Which services or what is affected? Any delivery, uptime, or user-facing issues?\n- 🧠 *Insights / Diagnostics:* Add key technical context from repository metadata: last commit, contributor, vulnerabilities, etc or draw from your technical knowledge on what would have caused this.\n- 🔧 *Action Required:* List next steps for the on-call team. Be specific about what they need to check or resolve.\n\n🔧 **Slack Output Rules**\n* NEVER USE `**bold**` or `[text](url)` — instead use:\n    * `*bold*` for emphasis\n     * `<https://url.com|Label>` for links\n* Use emoji to indicate sections: `🚨`, `📋`, `👥`, `🔄`\n* Use bullet points (`-`) for clarity\n* Separate sections with one line space (not headers)\n* Never include raw markdown headers like `###` or `---`\n* Your final output **must** look clean when copy-pasted into a Slack message.\n\n*After generating your update, you MUST ALWAYS run the 'update_incident_with_ai_update' action to save the update to the incident record.*\n\n## Sample Response Format\n🚨 *Incident Update: API Latency Spike on analytics-service*\n\n*Problem:*\n`analytics-service` has breached its latency SLO for the past 15 minutes. Response time spiked from 800ms to 4.5s\n\n*Impact:*\nThis service powers real-time analytics for customer dashboards. Users may experience slow or failing dashboard loads, particularly in high-traffic regions.\n\n*Insights/Diagnostics:*\n- The latest deployment (2025-07-21 13:03 UTC) introduced new filtering logic\n- Recent commits by Maria include changes to Redis query batching and fallback caching\n- Maria is not currently on-call. Assigned engineers: Omri and Tal.\n- 2 known vulnerability exists—could be a contributing factor.\n\n🔧 *Action Required:*\n- On-call engineers Marvin and Tal should roll back to the previous deploy version while isolating the Redis call regressions.\n- Re-run load tests locally with Maria's changes to confirm memory/caching issues.\n",
         "execution_mode": "Automatic",
         "conversation_starters": [
           "What is the latest update on INC-123?",
           "Generate an update for INC-123, we've found the root cause",
           "Create a Slack update for incident INC-456",
           "Summarize the current status of incident INC-789",
           "What's the latest on the database outage incident?"
+        ],
+        "tools": [
+          "^(list|get|search|track|describe)_.*",
+          "run_update_incident_with_ai_update"
         ]
       },
       "relations": {}
     }
     ```
     </details>
 
+    :::tip MCP Enhanced Capabilities
+    The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The `^(list|get|search|track|describe)_.*` pattern allows the agent to access and analyze related entities in your software catalog such as incidents, services, deployment etc., providing richer context for incident analysis. Additionally, we explicitly add `run_update_incident_with_ai_update` to the tools, which instructs the AI agent to call this specific action to update incident records with AI-generated summaries.
+    :::
+
 5. Click `Create` to save the agent.