Deprecate config key branch of GitlabDiscoveryEntityProvider in favor of new key fallbackBranch

relates #13587, #16502

Signed-off-by: Andreas Berger <andreas@berger-ecommerce.com>

.changeset/silver-lies-rest.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend-module-gitlab': minor
+---
+
+The configuration key `branch` of the `GitlabDiscoveryEntityProvider` has been deprecated in favor of the configuration key `fallbackBranch`.
+To migrate to the new configuration value, rename `branch` to `fallbackBranch`.

docs/integrations/gitlab/discovery.md

@@ -21,7 +21,7 @@ catalog:
     gitlab:
       yourProviderId:
         host: gitlab-host # Identifies one of the hosts set up in the integrations
-        branch: main # Optional. Uses `master` as default
+        fallbackBranch: main # Optional. Fallback to be used if there is no default branch configured at the Gitlab repository. It is only used, if `branch` is undefined. Uses `master` as default
         group: example-group # Optional. Group and subgroup (if needed) to look for repositories. If not present the whole instance will be scanned
         entityFilename: catalog-info.yaml # Optional. Defaults to `catalog-info.yaml`
         projectPattern: '[\s\S]*' # Optional. Filters found projects based on provided patter. Defaults to `[\s\S]*`, which means to not filter anything

plugins/catalog-backend-module-gitlab/src/lib/types.ts

@@ -61,7 +61,15 @@ export type GitlabProviderConfig = {
   host: string;
   group: string;
   id: string;
-  branch: string;
+  /**
+   * @deprecated use `fallbackBranch` instead
+   */
+  branch?: string;
+  /**
+   * If there is no default branch defined at the project, this fallback is used to discover catalog files.
+   * Defaults to: `master`
+   */
+  fallbackBranch: string;
   catalogFile: string;
   projectPattern: RegExp;
   userPattern: RegExp;

plugins/catalog-backend-module-gitlab/src/providers/GitlabDiscoveryEntityProvider.ts

@@ -177,11 +177,15 @@ export class GitlabDiscoveryEntityProvider implements EntityProvider {
         continue;
       }
 
-      if (this.config.branch === '*' && project.default_branch === undefined) {
+      if (
+        this.config.fallbackBranch === '*' &&
+        project.default_branch === undefined
+      ) {
         continue;
       }
 
-      const project_branch = project.default_branch ?? this.config.branch;
+      const project_branch =
+        project.default_branch ?? this.config.fallbackBranch;
 
       const projectHasFile: boolean = await client.hasFile(
         project.path_with_namespace ?? '',
@@ -204,7 +208,7 @@ export class GitlabDiscoveryEntityProvider implements EntityProvider {
   }
 
   private createLocationSpec(project: GitLabProject): LocationSpec {
-    const project_branch = project.default_branch ?? this.config.branch;
+    const project_branch = project.default_branch ?? this.config.fallbackBranch;
     return {
       type: 'url',
       target: `${project.web_url}/-/blob/${project_branch}/${this.config.catalogFile}`,

plugins/catalog-backend-module-gitlab/src/providers/config.test.ts

@@ -50,7 +50,7 @@ describe('config', () => {
       expect(r).toStrictEqual({
         id: 'test',
         group: 'group',
-        branch: 'master',
+        fallbackBranch: 'master',
         host: 'host',
         catalogFile: 'catalog-info.yaml',
         projectPattern: /[\s\S]*/,
@@ -84,7 +84,7 @@ describe('config', () => {
       expect(r).toStrictEqual({
         id: 'test',
         group: 'group',
-        branch: 'not-master',
+        fallbackBranch: 'not-master',
         host: 'host',
         catalogFile: 'custom-file.yaml',
         projectPattern: /[\s\S]*/,
@@ -122,7 +122,7 @@ describe('config', () => {
       expect(r).toStrictEqual({
         id: 'test',
         group: 'group',
-        branch: 'master',
+        fallbackBranch: 'master',
         host: 'host',
         catalogFile: 'catalog-info.yaml',
         projectPattern: /[\s\S]*/,

plugins/catalog-backend-module-gitlab/src/providers/config.ts

@@ -29,7 +29,10 @@ import { GitlabProviderConfig } from '../lib';
 function readGitlabConfig(id: string, config: Config): GitlabProviderConfig {
   const group = config.getOptionalString('group') ?? '';
   const host = config.getString('host');
-  const branch = config.getOptionalString('branch') ?? 'master';
+  const fallbackBranch =
+    config.getOptionalString('fallbackBranch') ??
+    config.getOptionalString('branch') ??
+    'master';
   const catalogFile =
     config.getOptionalString('entityFilename') ?? 'catalog-info.yaml';
   const projectPattern = new RegExp(
@@ -50,7 +53,7 @@ function readGitlabConfig(id: string, config: Config): GitlabProviderConfig {
   return {
     id,
     group,
-    branch,
+    fallbackBranch,
     host,
     catalogFile,
     projectPattern,