Merge branch 'main' into DIGCS-1-migrate-bibucket-to-github

# Conflicts:
#	src/components/guides-section/consts.js

Author: erioluwadivine

CONTRIBUTING.md renamed to best_practices.md

@@ -1,14 +1,6 @@
-# Contributing to Port's documentation
+# Port documentation style guide
 
-Here you can find resources and guidelines on how to contribute to Port's documentation and how to correctly write and fix documentation content.
-
-## How to contribute
-
-The best way to suggest edits for an existing page is by using the "Edit this page" button at the bottom of most docs, this button will take you to the GitHub interface to make and propose changes.
-
-If you want to add a new documentation page, please fork the repository and after adding the new docs, create a PR which will be reviewed by our team.
-
-Contributions are very welcome. If you need help planning your contribution, feel free to ask us by opening an issue in this repository or by writing in our [community Slack](https://join.slack.com/t/getport/shared_invite/zt-1v5z1z1v-3~1Q1Q1).
+This document details guidelines for contributing to Port's documentation, and demonstrates how to correctly write and review documentation content.
 
 ## Styling guidelines
 

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/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/set-self-service-actions-rbac.md

@@ -114,6 +114,58 @@ Add the `requiredApproval` field to your action:
 </TabItem>
 </Tabs>
 
+## Configure visibility for action runs
+
+When creating or editing a self-service action, you can also control who can **view its runs**, using the relevant toggle in the `Permissions` tab.
+
+
+- **When enabled (default):** All organization members can view the action’s runs.
+- **When disabled:**  
+  - **Admins** can view all runs.  
+  - **Approvers** can view runs they are assigned to approve.  
+  - **Members** can only view their own runs.
+
+This ensures that sensitive operational data remains accessible only to authorized users, while maintaining flexibility and transparency where needed.
+
+
+<Tabs groupId="config-method" queryString values={[
+{label: "UI", value: "ui"},
+{label: "API", value: "api"},
+]}>
+
+<TabItem value="ui">
+
+<img src='/img/self-service-actions/rbac/viewRunAccess.png' width='70%' border='1px' />
+
+</TabItem>
+
+<TabItem value="api">
+
+Add the `isViewRunAccess` field to your action:
+
+```json showLineNumbers
+[
+  {
+    ...
+    "invocationMethod": {
+      "type": "WEBHOOK",
+      "url": "https://example.com"
+    },
+    "trigger": {
+      ...
+      "operation": "CREATE",
+    }
+    // highlight-next-line
+    "isViewRunAccess": true,
+    ...
+  }
+]
+```
+
+</TabItem>
+
+</Tabs>
+
 ### Define approval notifications
 
 By default manual approval notifications are sent via **Email** to users who have [approval permissions](#define-approvers).

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

@@ -37,6 +37,11 @@ In addition to the methods mentioned above, `admins` can find action runs using
 - Go the [entity page](/customize-pages-dashboards-and-plugins/page/entity-page.md) of your desired entity, then select the `Runs` tab.  
    This page will display all action runs that have been executed for the selected Entity.
 
+## Who can view action runs
+
+Run visibility is controlled by the action’s permissions. See [Configure visibility for action runs](/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/#configure-visibility-for-action-runs) for details.
+
+
 ## Fetch an action run
 
 Once an `actionRun` is created, it will have a unique `runId`. Using this id, you can interact with the action run using Port's API. 

docs/actions-and-automations/setup-backend/webhook/port-execution-agent/usage.md

@@ -4,13 +4,7 @@ sidebar_position: 2
 
 # Usage
 
-When using the execution agent, in the `url` field you need to provide a URL to a service (for example, a REST API) that will accept the invocation event.
-
-- The service can be a private service running inside your private network;
-- Or, it can be a public accessible service from the public internet (**note** in this scenario, the execution agent needs corresponding outbound network rules that will allow it to contact the public service).
-
-:::note
-**IMPORTANT**: To make use of the **Port execution agent**, you need to configure:
+To make use of the **Port execution agent**, you need to configure:
 
 <!-- TODO: add back the URLs here for changelog destination -->
 
@@ -22,37 +16,177 @@ For example:
 ```json showLineNumbers
 { "type": "WEBHOOK", "agent": true, "url": "URL_TO_API_INSIDE_YOUR_NETWORK" }
 ```
-:::
 
-Well Done! **Port Agent** is now running in your environment and will trigger any webhook that you've configured (for self-service actions, or changes in the software catalog).
+When using the execution agent, in the `url` field you need to provide a URL to a service (for example, a REST API) that will accept the invocation event.
 
-When a new invocation is detected, the agent will pull it from your Kafka topic and forward it to the internal API in your private network.
+- The service can be a private service running inside your private network;
+- Or, it can be a public accessible service from the public internet (**note** in this scenario, the execution agent needs corresponding outbound network rules that will allow it to contact the public service).
+
+Once configured, the Port Agent will run in your environment and trigger webhooks for self-service actions or software catalog changes.
+
+When a new invocation is detected, the agent pulls it from your Kafka topic and forwards it to the internal API in your private network.
 
 ![Port Execution Agent Logs](/img/self-service-actions/port-execution-agent/portAgentLogs.png)
 
+:::info Advanced configuration
+For a complete list of all available configuration parameters and their descriptions, see the [Port Agent Helm chart README](https://github.com/port-labs/helm-charts/tree/main/charts/port-agent).
+:::
 
-## Advanced configuration
-Some environments require special configuration when working with the Port agent. This includes working with self-signed certificates and/or proxies.
+## Self-signed certificate configuration
 
-Port's agent uses Python's [requests](https://requests.readthedocs.io/en/latest/) library. This allows passing advanced configuration using environment variables.
+For self-hosted 3rd-party applications with self-signed certificates, the agent can be configured to trust custom CA certificates. The `selfSignedCertificate` parameters control this behavior.
 
-To add an environment variable using the agent's Helm chart, either:
+### Option 1: Provide certificate in Helm values
 
-1. Using Helm's `--set` flag:
-```sh showLineNumbers
-helm upgrade --install <MY_INSTALLATION_NAME> port-labs/port-ocean \
+Use this option to provide the certificate content directly in your Helm values file or via the `--set-file` flag.
+
+**How to use:**
+1. Set `selfSignedCertificate.enabled` to `true`
+2. Provide the certificate content in `selfSignedCertificate.certificate`
+3. Keep `selfSignedCertificate.secret.useExistingSecret` as `false` (default)
+
+**Method A: Inline certificate in values.yaml**
+
+Configure in your `values.yaml`:
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: |
+    -----BEGIN CERTIFICATE-----
+    <YOUR_CERTIFICATE_CONTENT>
+    -----END CERTIFICATE-----
+  secret:
+    name: ""
+    key: crt
+    useExistingSecret: false
+```
+
+Install with:
+```bash
+helm install my-port-agent port-labs/port-agent \
+   --create-namespace --namespace port-agent \
+   -f values.yaml
+```
+
+**Method B: Reference certificate file using `--set-file`**
+
+Configure in your `custom_values.yaml`:
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: ""
+  secret:
+    name: ""
+    key: crt
+    useExistingSecret: false
+```
+
+Install with:
+```bash
+helm install my-port-agent port-labs/port-agent \
+   --create-namespace --namespace port-agent \
+   -f custom_values.yaml \
+   --set selfSignedCertificate.enabled=true \
+   --set-file selfSignedCertificate.certificate=/PATH/TO/CERTIFICATE.crt
+```
+
+### Option 2: Use existing Kubernetes secret
+
+Use this option to reference a pre-existing Kubernetes secret that you manage separately. The secret must contain the certificate data.
+
+**How to use:**
+1. Set `selfSignedCertificate.enabled` to `true`
+2. Set `selfSignedCertificate.secret.useExistingSecret` to `true`
+3. Specify the secret name in `selfSignedCertificate.secret.name`
+4. Specify the key within the secret in `selfSignedCertificate.secret.key` (defaults to `crt`)
+5. Leave `selfSignedCertificate.certificate` empty
+
+**Complete configuration:**
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: ""
+  secret:
+    name: my-ca-cert
+    key: ca.crt
+    useExistingSecret: true
+```
+
+### Automatic configuration
+
+When `selfSignedCertificate.enabled` is set to `true`, the Helm chart automatically:
+- Mounts the certificate to `/usr/local/share/ca-certificates/cert.crt`
+- Sets `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` environment variables to point to the certificate
+
+### Multiple certificates
+
+For environments requiring multiple custom certificates, use the `extraVolumes` and `extraVolumeMounts` parameters alongside the built-in `selfSignedCertificate` feature. One certificate must be provided via `selfSignedCertificate`, and additional certificates can be mounted as extra volumes.
+
+**Configuration:**
+```yaml
+selfSignedCertificate:
+  enabled: true
+  secret:
+    name: primary-cert
+    key: ca.crt
+    useExistingSecret: true
+
+extraVolumes:
+  - name: additional-certs
+    secret:
+      secretName: secondary-certs
+extraVolumeMounts:
+  - name: additional-certs
+    mountPath: /usr/local/share/ca-certificates/cert2.crt
+    subPath: cert2.crt
+    readOnly: true
+```
+
+:::info Certificate requirements
+- Each certificate must be provided in PEM format as a separate file
+- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension
+:::
+
+## Overriding configurations
+
+When installing the Port Agent, you can override default values in the `helm upgrade` command:
+
+By using the `--set` flag, you can override specific agent configuration parameters during agent installation/upgrade:
+
+```bash showLineNumbers
+helm upgrade --install my-port-agent port-labs/port-agent \
+    --create-namespace --namespace port-agent \
+    --set env.normal.PORT_ORG_ID="YOUR_ORG_ID" \
+    --set env.normal.KAFKA_CONSUMER_GROUP_ID="YOUR_CONSUMER_GROUP_ID" \
+    --set env.secret.PORT_CLIENT_ID="YOUR_CLIENT_ID" \
+    --set env.secret.PORT_CLIENT_SECRET="YOUR_CLIENT_SECRET" \
+    --set secret.useExistingSecret=false \
+    --set replicaCount=2 \
+    --set resources.limits.memory="512Mi"
+```
+
+## Extra environment variables
+
+To pass extra environment variables to the agent's runtime, you can use the `env.normal` section for non-sensitive variables.
+
+Using Helm's `--set` flag:
+```bash showLineNumbers
+helm upgrade --install my-port-agent port-labs/port-agent \
   # Standard installation flags
   # ...
-  --set env.normal.VAR_NAME=VAR_VALUE 
+  --set env.normal.HTTP_PROXY=http://my-proxy.com:1111 \
+  --set env.normal.HTTPS_PROXY=http://my-proxy.com:2222
 ```
 
-2. The Helm `values.yaml` file:
+Using the `values.yaml` file:
 ```yaml showLineNumbers
 # The rest of the configuration
 # ...
 env:
   normal:
-    VAR_NAME: VAR_VALUE
+    HTTP_PROXY: "http://my-proxy.com:1111"
+    HTTPS_PROXY: "http://my-proxy.com:2222"
+    NO_PROXY: "127.0.0.1,localhost"
 ```
 
 ### Proxy configuration
@@ -69,51 +203,17 @@ ALL_PROXY=http://my-proxy.com:3333
 
 #### `NO_PROXY`
 
-`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-seperated list of hostnames or urls.
+`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-separated list of hostnames or URLs.
 
 For example:
 ```sh showLineNumbers
 NO_PROXY=http://127.0.0.1,google.com
 ```
 
-For more information take a look at the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
-
-### SSL Environment Configuration
-
-### Certificate Configuration
-
-#### Self-signed certificate
-
-Use the following Helm values:
-- Set `selfSignedCertificate.enabled` to `true`.
-- Put your PEM-encoded CA content in `selfSignedCertificate.certificate`.
-
-The certificate should be mounted to `/usr/local/share/ca-certificates/`.
-
-`REQUESTS_CA_BUNDLE` is an environment variable used to specify a custom Certificate Authority (CA) bundle for verifying SSL/TLS certificates in HTTPS requests.
-
-Set `REQUESTS_CA_BUNDLE` to the file path of your CA bundle, which should contain one or more CA certificates in PEM format.
-
-For example:
-```sh
-REQUESTS_CA_BUNDLE=/path/to/cacert.pem
-```
-
-This configuration directs the `requests` library to use the specified CA bundle for SSL/TLS certificate verification, overriding default system settings. It's useful for trusting self-signed certificates or certificates from a private CA.
-
-#### Multiple certificates
-
-Use the following Helm values:
-- Keep your certificate via `selfSignedCertificate` as above.
-- Add other certificates by supplying files via `extraVolumes` and mounting them with `extraVolumeMounts` into the container at `/usr/local/share/ca-certificates/<your-cert-name>.crt`.
-
-:::info Certificate file requirements
-- Each certificate must be provided in a separate PEM file. Files containing multiple certificates are not supported.
-- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension.
-:::
+For more information, see the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
 
 ## Next Steps
 
 Follow one of the guides below:
 
-- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.
+- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.