From 334f89bb854f5d1847840086da038269aed1df56 Mon Sep 17 00:00:00 2001
From: rcater <rcater@influxdata.com>
Date: Fri, 20 Mar 2026 15:23:16 -0500
Subject: [PATCH] docs(api): document gh: prefix for plugin_filename field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the gh: prefix that allows loading plugins
directly from GitHub repositories. Updates both Core and Enterprise
OpenAPI specs with:

- Updated plugin_filename field description explaining gh: prefix syntax
- New github_plugin example showing usage with system_metrics plugin

closes #6968

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../core/v3/influxdb3-core-openapi.yaml       | 21 ++++++++++++++++++-
 .../v3/influxdb3-enterprise-openapi.yaml      | 21 ++++++++++++++++++-
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml b/api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml
index f41334147..f88c50a0c 100644
--- a/api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml
+++ b/api-docs/influxdb3/core/v3/influxdb3-core-openapi.yaml
@@ -886,6 +886,20 @@ paths:
                   trigger_settings:
                     run_async: false
                     error_behavior: Log
+              github_plugin:
+                summary: Trigger using a plugin from GitHub
+                description: |
+                  Load a plugin directly from the influxdb3_plugins repository using the `gh:` prefix.
+                  The server fetches the plugin file when the trigger is created or started.
+                value:
+                  db: mydb
+                  plugin_filename: "gh:influxdata/system_metrics/system_metrics.py"
+                  trigger_name: system_metrics_trigger
+                  trigger_specification: "every:1m"
+                  disabled: false
+                  trigger_settings:
+                    run_async: false
+                    error_behavior: Log
       responses:
         "200":
           description: Success. Processing engine trigger created.
@@ -2764,7 +2778,12 @@ components:
           description: |
             The path and filename of the plugin to execute--for example,
             `schedule.py` or `endpoints/report.py`.
-            The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3.
+            The path can be absolute or relative to the `--plugin-dir` directory configured when starting InfluxDB 3.
+
+            To load a plugin directly from a remote repository, use the `gh:` prefix--for example,
+            `gh:influxdata/system_metrics/system_metrics.py`. By default, `gh:` paths resolve to
+            the [influxdata/influxdb3_plugins](https://github.com/influxdata/influxdb3_plugins) repository.
+            Configure a custom repository with the `--plugin-repo` server option.
 
             The plugin file must implement the trigger interface associated with the trigger's specification.
         trigger_name:
diff --git a/api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml b/api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml
index 5ff481f9d..0b7801f16 100644
--- a/api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml
+++ b/api-docs/influxdb3/enterprise/v3/influxdb3-enterprise-openapi.yaml
@@ -887,6 +887,20 @@ paths:
                   trigger_settings:
                     run_async: false
                     error_behavior: Log
+              github_plugin:
+                summary: Trigger using a plugin from GitHub
+                description: |
+                  Load a plugin directly from the influxdb3_plugins repository using the `gh:` prefix.
+                  The server fetches the plugin file when the trigger is created or started.
+                value:
+                  db: mydb
+                  plugin_filename: "gh:influxdata/system_metrics/system_metrics.py"
+                  trigger_name: system_metrics_trigger
+                  trigger_specification: "every:1m"
+                  disabled: false
+                  trigger_settings:
+                    run_async: false
+                    error_behavior: Log
       responses:
         "200":
           description: Success. Processing engine trigger created.
@@ -3051,7 +3065,12 @@ components:
           description: |
             The path and filename of the plugin to execute--for example,
             `schedule.py` or `endpoints/report.py`.
-            The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3.
+            The path can be absolute or relative to the `--plugin-dir` directory configured when starting InfluxDB 3.
+
+            To load a plugin directly from a remote repository, use the `gh:` prefix--for example,
+            `gh:influxdata/system_metrics/system_metrics.py`. By default, `gh:` paths resolve to
+            the [influxdata/influxdb3_plugins](https://github.com/influxdata/influxdb3_plugins) repository.
+            Configure a custom repository with the `--plugin-repo` server option.
 
             The plugin file must implement the trigger interface associated with the trigger's specification.
         node_spec: