Add examples for publish:github:pull-request scaffolder action

Signed-off-by: parmar-abhinav <abhi171b010@gmail.com>

.changeset/wise-weeks-design.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Add examples for `publish:github:pull-request` scaffolder action & improve related tests

plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.examples.test.ts

@@ -0,0 +1,552 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TemplateAction } from '@backstage/plugin-scaffolder-node';
+import { getVoidLogger } from '@backstage/backend-common';
+import { ConfigReader } from '@backstage/config';
+import {
+  DefaultGithubCredentialsProvider,
+  GithubCredentialsProvider,
+  ScmIntegrations,
+} from '@backstage/integration';
+import { PassThrough } from 'stream';
+import {
+  OctokitWithPullRequestPluginClient,
+  createPublishGithubPullRequestAction,
+} from './githubPullRequest';
+import yaml from 'yaml';
+import { examples } from './githubPullRequest.examples';
+import { createMockDirectory } from '@backstage/backend-test-utils';
+
+const mockOctokit = {
+  rest: {
+    pulls: {
+      requestReviewers: jest.fn(),
+    },
+  },
+};
+
+jest.mock('octokit', () => ({
+  Octokit: class {
+    constructor() {
+      return mockOctokit;
+    }
+  },
+}));
+
+describe('publish:github:pull-request examples', () => {
+  const config = new ConfigReader({
+    integrations: {
+      github: [
+        { host: 'github.com', token: 'tokenlols' },
+        { host: 'ghe.github.com' },
+      ],
+    },
+  });
+  const integrations = ScmIntegrations.fromConfig(config);
+  let githubCredentialsProvider: GithubCredentialsProvider;
+  let action: TemplateAction<any>;
+
+  const mockContext = {
+    workspacePath: 'lol',
+    logger: getVoidLogger(),
+    logStream: new PassThrough(),
+    output: jest.fn(),
+    createTemporaryDirectory: jest.fn(),
+  };
+  let fakeClient: {
+    createPullRequest: jest.Mock;
+    rest: {
+      pulls: { requestReviewers: jest.Mock };
+    };
+  };
+  const mockDir = createMockDirectory();
+  const workspacePath = mockDir.resolve('workspace');
+
+  beforeEach(() => {
+    mockDir.clear();
+    jest.resetAllMocks();
+    githubCredentialsProvider =
+      DefaultGithubCredentialsProvider.fromIntegrations(integrations);
+    fakeClient = {
+      createPullRequest: jest.fn(async (_: any) => {
+        return {
+          url: 'https://api.github.com/myorg/myrepo/pull/123',
+          headers: {},
+          status: 201,
+          data: {
+            html_url: 'https://github.com/myorg/myrepo/pull/123',
+            number: 123,
+            base: {
+              ref: 'main',
+            },
+          },
+        };
+      }),
+      rest: {
+        pulls: {
+          requestReviewers: jest.fn(async (_: any) => ({ data: {} })),
+        },
+      },
+    };
+
+    const clientFactory = jest.fn(
+      async () => fakeClient as unknown as OctokitWithPullRequestPluginClient,
+    );
+
+    mockDir.setContent({
+      [workspacePath]: { 'file.txt': 'Hello there!' },
+    });
+
+    action = createPublishGithubPullRequestAction({
+      integrations,
+      githubCredentialsProvider,
+      clientFactory,
+    });
+  });
+
+  afterEach(jest.resetAllMocks);
+
+  it('Create a pull request', async () => {
+    const input = yaml.parse(examples[0].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with target branch name', async () => {
+    const input = yaml.parse(examples[1].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      base: 'test',
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request as draft', async () => {
+    const input = yaml.parse(examples[2].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: true,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with target path', async () => {
+    const input = yaml.parse(examples[3].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'targetPath/file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with source path', async () => {
+    mockDir.setContent({
+      [workspacePath]: {
+        source: { 'foo.txt': 'Hello there!' },
+        irrelevant: { 'bar.txt': 'Nothing to see here' },
+      },
+    });
+    const input = yaml.parse(examples[4].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'foo.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with token', async () => {
+    const input = yaml.parse(examples[5].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with reviewers', async () => {
+    const input = yaml.parse(examples[6].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      pull_number: 123,
+      reviewers: ['foobar'],
+    });
+
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with team reviewers', async () => {
+    const input = yaml.parse(examples[7].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Create my new app',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      pull_number: 123,
+      team_reviewers: ['team-foo'],
+    });
+
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with commit message', async () => {
+    const input = yaml.parse(examples[8].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: undefined,
+      changes: [
+        {
+          commit: 'Custom commit message',
+          files: {
+            'file.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).not.toHaveBeenCalled();
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+
+  it('Create a pull request with all parameters', async () => {
+    mockDir.setContent({
+      [workspacePath]: {
+        source: { 'foo.txt': 'Hello there!' },
+        irrelevant: { 'bar.txt': 'Nothing to see here' },
+      },
+    });
+    const input = yaml.parse(examples[9].example).steps[0].input;
+
+    await action.handler({
+      ...mockContext,
+      workspacePath,
+      input,
+    });
+
+    expect(fakeClient.createPullRequest).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      title: 'Create my new app',
+      body: 'This PR is really good',
+      head: 'new-app',
+      draft: true,
+      base: 'test',
+      changes: [
+        {
+          commit: 'Commit for foo changes',
+          files: {
+            'targetPath/foo.txt': {
+              content: Buffer.from('Hello there!').toString('base64'),
+              encoding: 'base64',
+              mode: '100644',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(fakeClient.rest.pulls.requestReviewers).toHaveBeenCalledWith({
+      owner: 'owner',
+      repo: 'repo',
+      pull_number: 123,
+      reviewers: ['foobar'],
+      team_reviewers: ['team-foo'],
+    });
+
+    expect(mockContext.output).toHaveBeenCalledTimes(3);
+    expect(mockContext.output).toHaveBeenCalledWith('targetBranchName', 'main');
+    expect(mockContext.output).toHaveBeenCalledWith(
+      'remoteUrl',
+      'https://github.com/myorg/myrepo/pull/123',
+    );
+    expect(mockContext.output).toHaveBeenCalledWith('pullRequestNumber', 123);
+  });
+});

plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.examples.ts

@@ -0,0 +1,206 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { TemplateExample } from '@backstage/plugin-scaffolder-node';
+import yaml from 'yaml';
+
+export const examples: TemplateExample[] = [
+  {
+    description: 'Create a pull request',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with target branch name',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest with target branch name',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            targetBranchName: 'test',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request as draft',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest as draft',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            draft: true,
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with target path',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest with target path',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            targetPath: 'targetPath',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with source path',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest with source path',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            sourcePath: 'source',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with token',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            token: 'gph_YourGitHubToken',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with reviewers',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest with reviewers',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            reviewers: ['foobar'],
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with team reviewers',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest with team reviewers',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            teamReviewers: ['team-foo'],
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with commit message',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            commitMessage: 'Custom commit message',
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description: 'Create a pull request with all parameters',
+    example: yaml.stringify({
+      steps: [
+        {
+          action: 'publish:github:pull-request',
+          name: 'Create a pull reuqest',
+          input: {
+            repoUrl: 'github.com?repo=repo&owner=owner',
+            branchName: 'new-app',
+            title: 'Create my new app',
+            description: 'This PR is really good',
+            targetBranchName: 'test',
+            draft: true,
+            targetPath: 'targetPath',
+            sourcePath: 'source',
+            token: 'gph_YourGitHubToken',
+            reviewers: ['foobar'],
+            teamReviewers: ['team-foo'],
+            commitMessage: 'Commit for foo changes',
+          },
+        },
+      ],
+    }),
+  },
+];

plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts

@@ -31,6 +31,7 @@ import {
   serializeDirectoryContents,
 } from '../../../../lib/files';
 import { Logger } from 'winston';
+import { examples } from './githubPullRequest.examples';
 
 export type Encoding = 'utf-8' | 'base64';
 
@@ -143,6 +144,7 @@ export const createPublishGithubPullRequestAction = (
     commitMessage?: string;
   }>({
     id: 'publish:github:pull-request',
+    examples,
     schema: {
       input: {
         required: ['repoUrl', 'title', 'description', 'branchName'],