Merge pull request #29424 from lukealbao/luke/branch-slash-doc

[docs] add branch naming caveat to github discovery integration

.changeset/clear-pigs-share.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog-backend-module-github': minor
+---
+
+**BREAKING**: Explicitly rejects branch names containing a slash character.
+
+The module now rejects any configuration that contains slashes in branch names. The reason for this is that the ingestion will run into downstream problems if they were let through. If you had configuration with a slash in the branch name in `filters.branch`, your application may fail to start up.
+
+If you are affected by this, please move over to using branches that do not have slashes in them.

docs/integrations/github/discovery.md

@@ -152,7 +152,7 @@ If you do so, `default` will be used as provider ID.
   Wildcards cannot be used if the `validateLocationsExist` option is set to `true`.
 - **`filters`** _(optional)_:
   - **`branch`** _(optional)_:
-    String used to filter results based on the branch name.
+    String used to filter results based on the branch name. Branch name cannot have any slash (`/`) characters.
     Defaults to the default Branch of the repository.
   - **`repository`** _(optional)_:
     Regular expression used to filter results based on the repository name.

plugins/catalog-backend-module-github/src/providers/GithubEntityProviderConfig.test.ts

@@ -311,4 +311,24 @@ describe('readProviderConfigs', () => {
 
     expect(() => readProviderConfigs(config)).toThrow();
   });
+
+  it('throws an error when filters.branch contains a slash', () => {
+    const config = new ConfigReader({
+      catalog: {
+        providers: {
+          github: {
+            invalidBranchUser: {
+              organization: 'test-org',
+              catalogPath: '/*/catalog-info.yaml',
+              filters: {
+                branch: 'test/a',
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(() => readProviderConfigs(config)).toThrow();
+  });
 });

plugins/catalog-backend-module-github/src/providers/GithubEntityProviderConfig.ts

@@ -104,6 +104,12 @@ function readProviderConfig(
     );
   }
 
+  if (branchPattern?.includes('/')) {
+    throw new Error(
+      'Error while processing GitHub provider config. Slash characters (/) are not allowed in filters.branch',
+    );
+  }
+
   const schedule = config.has('schedule')
     ? readSchedulerServiceTaskScheduleDefinitionFromConfig(
         config.getConfig('schedule'),