From 7cc9dcd9f35d31b82af031f1e71124308ef14a2f Mon Sep 17 00:00:00 2001
From: mvdbeek <m.vandenbeek@gmail.com>
Date: Mon, 13 Jul 2026 12:44:15 +0200
Subject: [PATCH] Make file source form alerts template configurable

---
 .../packages/api-client/src/schema/schema.ts  | 15 +++++++++++
 .../FileSources/Instances/CreateForm.vue      | 25 +++++++++----------
 .../Instances/useGithubRepositoryOptions.ts   | 14 ++++++++++-
 doc/source/admin/data.md                      |  6 +++++
 .../templates/examples/production_github.yml  | 14 +++++++++++
 lib/galaxy/files/templates/models.py          | 22 ++++++++++++++++
 test/unit/files/test_template_models.py       |  5 ++++
 7 files changed, 87 insertions(+), 14 deletions(-)

diff --git a/client/packages/api-client/src/schema/schema.ts b/client/packages/api-client/src/schema/schema.ts
index 895494a3b38..dff3e9becc7 100644
--- a/client/packages/api-client/src/schema/schema.ts
+++ b/client/packages/api-client/src/schema/schema.ts
@@ -13138,10 +13138,25 @@ export interface components {
         };
         /** FileSourceTemplateSummaries */
         FileSourceTemplateSummaries: components["schemas"]["FileSourceTemplateSummary"][];
+        /** FileSourceTemplateAlert */
+        FileSourceTemplateAlert: {
+            /** Condition */
+            condition?: string | null;
+            /** Content */
+            content: string;
+            /**
+             * Variant
+             * @default info
+             * @enum {string}
+             */
+            variant?: "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
+        };
         /** FileSourceTemplateSummary */
         FileSourceTemplateSummary: {
             /** Description */
             description: string | null;
+            /** Form Alerts */
+            form_alerts?: components["schemas"]["FileSourceTemplateAlert"][] | null;
             /**
              * Hidden
              * @default false
diff --git a/client/src/components/FileSources/Instances/CreateForm.vue b/client/src/components/FileSources/Instances/CreateForm.vue
index d6b0567310f..137ebd0da74 100644
--- a/client/src/components/FileSources/Instances/CreateForm.vue
+++ b/client/src/components/FileSources/Instances/CreateForm.vue
@@ -7,6 +7,8 @@ import { useConfigurationTemplateCreation } from "@/components/ConfigTemplates/u
 
 import { useGithubRepositoryOptions } from "./useGithubRepositoryOptions";
 
+import ConfigurationMarkdown from "@/components/ObjectStore/ConfigurationMarkdown.vue";
+
 const createUrl = "/api/file_source_instances";
 const createTestUrl = "/api/file_source_instances/test";
 
@@ -27,12 +29,19 @@ function onFormChange(incoming: Record<string, unknown>) {
     formData.value = incoming;
 }
 
-const { dynamicOptions, isRepositoryPicker, noRepositoriesFound } = useGithubRepositoryOptions(
+const { alertConditions, dynamicOptions } = useGithubRepositoryOptions(
     toRef(props, "template"),
     toRef(props, "uuid"),
     formData,
 );
 
+const formAlerts = computed(() => {
+    const activeConditions = new Set(alertConditions.value);
+    return (props.template.form_alerts ?? []).filter(
+        (alert) => !alert.condition || activeConditions.has(alert.condition),
+    );
+});
+
 const { ActionSummary, error, inputs, InstanceForm, onSubmit, submitTitle, loadingMessage, testRunning, testResults } =
     useConfigurationTemplateCreation(
         "file source",
@@ -47,18 +56,8 @@ const { ActionSummary, error, inputs, InstanceForm, onSubmit, submitTitle, loadi
 <template>
     <div id="create-file-source-landing">
         <ActionSummary error-data-description="file-source-creation-error" :test-results="testResults" :error="error" />
-        <BAlert v-if="noRepositoriesFound" show variant="warning" data-description="github-no-repositories">
-            The GitHub App isn't installed on any repository you can access, so there are no owners or
-            repositories to choose. Install it on at least one repository from your
-            <a href="https://github.com/settings/installations" target="_blank" rel="noopener noreferrer">
-                installed GitHub Apps </a
-            >, then reload this page.
-        </BAlert>
-        <BAlert v-else-if="isRepositoryPicker" show variant="info" data-description="github-manage-repositories">
-            Need access to another repository? Update the GitHub App's repository access in a new tab from your
-            <a href="https://github.com/settings/installations" target="_blank" rel="noopener noreferrer">
-                installed GitHub Apps</a
-            >, then reload this page.
+        <BAlert v-for="alert in formAlerts" :key="alert.content" show :variant="alert.variant">
+            <ConfigurationMarkdown :markdown="alert.content" :admin="true" />
         </BAlert>
         <InstanceForm
             :inputs="inputs"
diff --git a/client/src/components/FileSources/Instances/useGithubRepositoryOptions.ts b/client/src/components/FileSources/Instances/useGithubRepositoryOptions.ts
index 44c0feb97b0..ffd356f4104 100644
--- a/client/src/components/FileSources/Instances/useGithubRepositoryOptions.ts
+++ b/client/src/components/FileSources/Instances/useGithubRepositoryOptions.ts
@@ -82,6 +82,18 @@ export function useGithubRepositoryOptions(
             repositories.value.length === 0,
     );
 
+    // These semantic conditions deliberately describe picker state rather than GitHub-specific
+    // wording. Template-defined alerts decide what, if anything, to show for each state.
+    const alertConditions = computed(() => {
+        if (noRepositoriesFound.value) {
+            return ["repository_picker_empty"];
+        }
+        if (isRepositoryPicker.value) {
+            return ["repository_picker_available"];
+        }
+        return [];
+    });
+
     async function fetchRepositories() {
         if (!isRepositoryPicker.value || !uuid.value) {
             return;
@@ -116,7 +128,7 @@ export function useGithubRepositoryOptions(
 
     watch([uuid, isRepositoryPicker], () => void fetchRepositories(), { immediate: true });
 
-    return { dynamicOptions, loading, error, isRepositoryPicker, noRepositoriesFound };
+    return { dynamicOptions, loading, error, isRepositoryPicker, noRepositoriesFound, alertConditions };
 }
 
 function findVariableByMarker(template: FileSourceTemplateSummary, marker: string): string | undefined {
diff --git a/doc/source/admin/data.md b/doc/source/admin/data.md
index d0c37a7d315..5139be935ce 100644
--- a/doc/source/admin/data.md
+++ b/doc/source/admin/data.md
@@ -281,6 +281,12 @@ pointed to by the configuration option `file_source_templates_config_file` in `g
 Alternatively, the configuration can be placed directly into `galaxy.yml` using the
 `file_source_templates` configuration option.
 
+A template can define `form_alerts` to show administrator-authored Markdown alerts while a
+user creates an instance. Each alert has a Bootstrap `variant` and optional `condition`; alerts
+without a condition are always shown. Template capabilities can expose condition names for
+source-specific states, allowing the template to control the message without hard-coding it in
+the form component.
+
 ### File Source Types
 
 #### `posix`
diff --git a/lib/galaxy/files/templates/examples/production_github.yml b/lib/galaxy/files/templates/examples/production_github.yml
index 309df1d8385..65420ecf1d7 100644
--- a/lib/galaxy/files/templates/examples/production_github.yml
+++ b/lib/galaxy/files/templates/examples/production_github.yml
@@ -9,6 +9,20 @@
       You authorize Galaxy to access GitHub on your behalf through GitHub's OAuth flow - no
       personal access token is required. Each repository is a separate file source: create one
       instance of this template per repository you want to access.
+  form_alerts:
+      - condition: repository_picker_empty
+        variant: warning
+        content: |
+            The GitHub App isn't installed on any repository you can access, so there are no owners or
+            repositories to choose. Install it on at least one repository from your
+            <a href="https://github.com/settings/installations" target="_blank" rel="noopener noreferrer">installed GitHub Apps</a>,
+            then reload this page.
+      - condition: repository_picker_available
+        variant: info
+        content: |
+            Need access to another repository? Update the GitHub App's repository access from your
+            <a href="https://github.com/settings/installations" target="_blank" rel="noopener noreferrer">installed GitHub Apps</a>
+            in a new tab, then reload this page.
   variables:
       org:
           label: Repository Owner
diff --git a/lib/galaxy/files/templates/models.py b/lib/galaxy/files/templates/models.py
index d42dacf1328..495f63e55ef 100644
--- a/lib/galaxy/files/templates/models.py
+++ b/lib/galaxy/files/templates/models.py
@@ -56,6 +56,27 @@ FileSourceTemplateType = Literal[
     "ssh",
 ]
 
+FileSourceTemplateAlertVariant = Literal[
+    "primary",
+    "secondary",
+    "success",
+    "danger",
+    "warning",
+    "info",
+    "light",
+    "dark",
+]
+
+
+class FileSourceTemplateAlert(StrictModel):
+    """An administrator-authored alert shown while creating a file source."""
+
+    content: MarkdownContent
+    variant: FileSourceTemplateAlertVariant = "info"
+    # A condition is supplied by a client-side template capability. Omit it for an alert that
+    # should always be visible.
+    condition: str | None = None
+
 
 class PosixFileSourceTemplateConfiguration(StrictModel):
     type: Literal["posix"]
@@ -588,6 +609,7 @@ class FileSourceTemplateBase(StrictModel):
     # template by hiding but keep it in the catalog for backward
     # compatibility for users with existing stores of that template.
     hidden: bool = False
+    form_alerts: list[FileSourceTemplateAlert] | None = None
     variables: list[TemplateVariable] | None = None
     secrets: list[TemplateSecret] | None = None
 
diff --git a/test/unit/files/test_template_models.py b/test/unit/files/test_template_models.py
index 21b16dac0da..08b60709b5c 100644
--- a/test/unit/files/test_template_models.py
+++ b/test/unit/files/test_template_models.py
@@ -296,6 +296,11 @@ def test_production_aws_public_bucket():
 
 def test_production_github_oauth():
     github_template = _get_example_template("production_github.yml")
+    assert github_template.form_alerts is not None
+    assert [alert.condition for alert in github_template.form_alerts] == [
+        "repository_picker_empty",
+        "repository_picker_available",
+    ]
     configuration_obj = template_to_configuration(
         github_template,
         {"org": "galaxyproject", "repo": "galaxy"},