ebarault · Oct 9, 2026 · Oct 9, 2026 · Oct 10, 2026
diff --git a/.changeset/gitlab-branch-autocomplete.md b/.changeset/gitlab-branch-autocomplete.md
@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-scaffolder': minor
+'@backstage/plugin-scaffolder-backend-module-gitlab': patch
+---
+
+Added GitLab branch autocompletion to RepoBranchPicker using user SCM credentials.
@@ -551,6 +551,11 @@ repoUrl:
 
 The input props that can be specified under `ui:options` for the `RepoBranchPicker` field extension.
 
+GitLab branch autocompletion requires the GitLab Scaffolder backend module and
+`requestUserCredentials`. The repository must be selected in a field named
+`repoUrl`. Nested GitLab namespaces are supported. Manual branch entry remains
+available when autocompletion is unavailable.
+
 ### `requestUserCredentials`
 
 If defined will request user credentials to auth against the given SCM platform.

@@ -27,6 +27,7 @@ jest.mock('../util', () => ({
 describe('handleAutocompleteRequest', () => {
   const mockIntegrations = {} as ScmIntegrationRegistry;
   const mockClient = {
+    Branches: { all: jest.fn() },
     Groups: {
       all: jest.fn(),
       allProjects: jest.fn(),
@@ -122,6 +123,78 @@ describe('handleAutocompleteRequest', () => {
     });
   });
 
+  it('returns branches for a nested namespace using the supplied credentials', async () => {
+    const handle = createHandleAutocompleteRequest({
+      integrations: mockIntegrations,
+    });
+    mockClient.Branches.all.mockResolvedValue([
+      { name: 'main' },
+      { name: 'feature/example' },
+    ]);
+    await expect(
+      handle({
+        resource: 'branches',
+        token: 'user-token',
+        context: {
+          host: 'gitlab.example.com',
+          owner: 'group/subgroup',
+          repository: 'repo',
+        },
+      }),
+    ).resolves.toEqual({
+      results: [
+        { title: 'main', id: 'main' },
+        { title: 'feature/example', id: 'feature/example' },
+      ],
+    });
+    expect(mockGetClient).toHaveBeenCalledWith({
+      host: 'gitlab.example.com',
+      integrations: mockIntegrations,
+      token: 'user-token',
+    });
+    expect(mockClient.Branches.all).toHaveBeenCalledWith('group/subgroup/repo');
+    mockClient.Branches.all.mockResolvedValue([]);
+    await expect(
+      handle({
+        resource: 'branches',
+        token: 'user-token',
+        context: { owner: 'group', repository: 'empty' },
+      }),
+    ).resolves.toEqual({ results: [] });
+    mockClient.Branches.all.mockRejectedValue(new Error('Forbidden'));
+    await expect(
+      handle({
+        resource: 'branches',
+        token: 'user-token',
+        context: { owner: 'group', repository: 'private' },
+      }),
+    ).rejects.toThrow('Forbidden');
+  });
+
+  it('rejects missing branch context and credentials without listing branches', async () => {
+    const handle = createHandleAutocompleteRequest({
+      integrations: mockIntegrations,
+    });
+    const missingContexts: Record<string, string>[] = [
+      {},
+      { owner: 'group' },
+      { repository: 'repo' },
+    ];
+    for (const context of missingContexts) {
+      await expect(
+        handle({ resource: 'branches', token: 'user-token', context }),
+      ).rejects.toThrow(InputError);
+    }
+    await expect(
+      handle({
+        resource: 'branches',
+        token: '',
+        context: { owner: 'group', repository: 'repo' },
+      }),
+    ).rejects.toThrow('Missing user credentials');
+    expect(mockClient.Branches.all).not.toHaveBeenCalled();
+  });
+
   it('should throw an error for invalid resource', async () => {
     const handleAutocompleteRequest = createHandleAutocompleteRequest({
       integrations: mockIntegrations,

@@ -81,6 +81,27 @@ export function createHandleAutocompleteRequest(options: {
 
         return result;
       }
+      case 'branches': {
+        if (!context.owner || !context.repository) {
+          throw new InputError('Missing owner or repository context parameter');
+        }
+        if (!token) {
+          throw new InputError(
+            'Missing user credentials for branch autocomplete',
+          );
+        }
+
+        const branches = await client.Branches.all(
+          `${context.owner}/${context.repository}`,
+        );
+
+        return {
+          results: branches.map(branch => ({
+            title: branch.name,
+            id: branch.name,
+          })),
+        };
+      }
       case 'repositories': {
         if (!context.id)
           throw new InputError('Missing groupId and userId context parameter');