From 2c5380890f1af47ddf8261bb4493fafa70bba973 Mon Sep 17 00:00:00 2001 From: Kapil Garg Date: Wed, 29 Jan 2025 07:21:54 +0530 Subject: [PATCH 1/5] fix link --- fern/docs/pages/tutorials/perform-external-action.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/tutorials/perform-external-action.mdx b/fern/docs/pages/tutorials/perform-external-action.mdx index e41769c6..e3893cff 100644 --- a/fern/docs/pages/tutorials/perform-external-action.mdx +++ b/fern/docs/pages/tutorials/perform-external-action.mdx @@ -24,7 +24,7 @@ the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. ### Installation guide -- Install [DevRev CLI](/snapin-development/references/install-dev-rev-cli) +- Install [DevRev CLI](/snapin-development/references/cli-install) - Install [jq](https://stedolan.github.io/jq) - Install [DevRev SDK](https://www.npmjs.com/package/@devrev/typescript-sdk?activeTab=readme) From c3791658b419b3f8575d8e463d3e3b3f9a18eec3 Mon Sep 17 00:00:00 2001 From: Kapil Garg Date: Wed, 29 Jan 2025 07:27:49 +0530 Subject: [PATCH 2/5] minor grammar fixes --- fern/docs/pages/tutorials/perform-external-action.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/fern/docs/pages/tutorials/perform-external-action.mdx b/fern/docs/pages/tutorials/perform-external-action.mdx index e3893cff..e9acffea 100644 --- a/fern/docs/pages/tutorials/perform-external-action.mdx +++ b/fern/docs/pages/tutorials/perform-external-action.mdx @@ -1,6 +1,6 @@ ## Introduction -In this tutorial, you'll lean how to develop a snap-in that mirrors an issue from +In this tutorial, you'll learn how to develop a snap-in that mirrors an issue from DevRev to GitHub. This requires addition of a command that can be run from the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. @@ -101,7 +101,7 @@ functions: ``` The command clearly states where you can use it. For example, in the -**Discussions** tab of issues. +**Discussions** tab of issues. It also explains the different situations and ways in which you can make use of this command. @@ -126,7 +126,7 @@ name (`RepoName`) before proceeding with the issue creation. ### Function logic -After creating the manifest and establishing the snap-in's logic, the next step is to define the function logic that handles business logic. Once you understand the payload structure of a command, you can proceed with its implementation. +After creating the manifest and establishing the snap-in's logic, the next step is to define the function logic that handles the business logic. Once you understand the payload structure of a command, you can proceed with its implementation. To proceed, define the handler function for command events. @@ -291,11 +291,11 @@ Once the code has been validated, the next steps involve creating the snap-in version and subsequently creating the snap-in itself. Before installing the snap-in, it's essential to set up a GitHub Personal Access Token (PAT) and add it to the connections in DevRev as a snap-in secret. Ensure that the secret is -shared within the organization so that the snap-in can utilize it. +shared within the organization so that the snap-in can utilize it. Follow these steps to install the snap-in in your organization: -#### Step 1: Create a GitHub personal access token +#### Step 1: Create a GitHub personal access token Generate a GitHub Personal Access Token (PAT) by following the steps outlined in the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). From ddfeea022cf0854ddd7c1a579f05cc15f9190a2c Mon Sep 17 00:00:00 2001 From: Kapil Garg Date: Wed, 29 Jan 2025 09:00:35 +0530 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- fern/docs/pages/tutorials/perform-external-action.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/docs/pages/tutorials/perform-external-action.mdx b/fern/docs/pages/tutorials/perform-external-action.mdx index e9acffea..dc595e89 100644 --- a/fern/docs/pages/tutorials/perform-external-action.mdx +++ b/fern/docs/pages/tutorials/perform-external-action.mdx @@ -1,6 +1,6 @@ ## Introduction -In this tutorial, you'll learn how to develop a snap-in that mirrors an issue from +In this tutorial, you learn how to develop a snap-in that mirrors an issue from DevRev to GitHub. This requires addition of a command that can be run from the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. @@ -25,7 +25,7 @@ the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. ### Installation guide - Install [DevRev CLI](/snapin-development/references/cli-install) -- Install [jq](https://stedolan.github.io/jq) +- Install [jq](https://stedolan.github.io/jq). - Install [DevRev SDK](https://www.npmjs.com/package/@devrev/typescript-sdk?activeTab=readme) @@ -100,7 +100,7 @@ functions: description: Function to create a GitHub issue ``` -The command clearly states where you can use it. For example, in the +The command states where you can use it. For example, in the **Discussions** tab of issues. It also explains the different situations and From 23edc4e7945023f5e13982f41d965c3241c88a04 Mon Sep 17 00:00:00 2001 From: Atul-Butola <137884145+Atul-Butola@users.noreply.github.com> Date: Wed, 29 Jan 2025 10:39:46 +0530 Subject: [PATCH 4/5] Update perform-external-action.mdx --- .../tutorials/perform-external-action.mdx | 78 +++++-------------- 1 file changed, 21 insertions(+), 57 deletions(-) diff --git a/fern/docs/pages/tutorials/perform-external-action.mdx b/fern/docs/pages/tutorials/perform-external-action.mdx index dc595e89..abb6e8da 100644 --- a/fern/docs/pages/tutorials/perform-external-action.mdx +++ b/fern/docs/pages/tutorials/perform-external-action.mdx @@ -1,8 +1,6 @@ ## Introduction -In this tutorial, you learn how to develop a snap-in that mirrors an issue from -DevRev to GitHub. This requires addition of a command that can be run from -the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. +In this tutorial, you learn how to develop a snap-in that mirrors an issue from DevRev to GitHub. This requires addition of a command that can be run from the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub. ## Background context @@ -42,25 +40,17 @@ devrev snap_in_version init #### Trigger -To initiate the process of creating a GitHub issue directly from a DevRev issue, -a trigger mechanism is essential. In this context, the implementation involves -the introduction of a specialized command. This command is designed to be -executed exclusively from the discussion section of a DevRev issue, serving as -the catalyst for replicating the issue on GitHub. +To initiate the process of creating a GitHub issue directly from a DevRev issue, a trigger mechanism is essential. In this context, the implementation involves the introduction of a specialized command. This command is designed to be executed exclusively from the discussion section of a DevRev issue, serving as the catalyst for replicating the issue on GitHub. #### Action -The primary action involves leveraging the issue creation API provided by -GitHub. This API is utilized to create the GitHub issue seamlessly from the -corresponding issue in DevRev. +The primary action involves leveraging the issue creation API provided by GitHub. This API is utilized to create the GitHub issue seamlessly from the corresponding issue in DevRev. ### Creating the snap-in #### Updating the manifest -To outline the structure of the snap-in, the initial step is to define key -attributes in the snap-in's manifest. Begin by specifying the name, description, -and account display name for the snap-in. +To outline the structure of the snap-in, the initial step is to define key attributes in the snap-in's manifest. Begin by specifying the name, description, and account display name for the snap-in. ```yml version: "2" @@ -73,9 +63,7 @@ service_account: ### Keyrings -To facilitate authentication for our API calls, the initial step involves -creating a Personal Access Token (PAT) in GitHub. This PAT can be stored as a -[connection](/snapin-development/references/keyrings) within DevRev. Subsequently, this +To facilitate authentication for our API calls, the initial step involves creating a Personal Access Token (PAT) in GitHub. This PAT can be stored as a [connection](/snapin-development/references/keyrings) within DevRev. Subsequently, this connection is employed within our snap-in in the form of keyrings. ```yml @@ -90,9 +78,7 @@ keyrings: ### Functions and commands -Having established the foundational configurations, the subsequent step is to -define the functions and commands responsible for orchestrating the core logic -of the snap-in. +Having established the foundational configurations, the subsequent step is to define the functions and commands responsible for orchestrating the core logic of the snap-in. ```yaml functions: @@ -100,11 +86,9 @@ functions: description: Function to create a GitHub issue ``` -The command states where you can use it. For example, in the -**Discussions** tab of issues. +The command states where you can use it. For example, in the **Discussions** tab of issues. -It also explains the different situations and -ways in which you can make use of this command. +It also explains the different situations and ways in which you can make use of this command. ```yml commands: @@ -119,9 +103,7 @@ commands: function: command_handler ``` -To utilize this command, execute `/gh_issue OrgName RepoName` in the **Discussions** -tab of the issue. Within the function logic, validations are implemented to -ensure the correctness of both the organization name (`OrgName`) and repository +To utilize this command, execute `/gh_issue OrgName RepoName` in the **Discussions** tab of the issue. Within the function logic, validations are implemented to ensure the correctness of both the organization name (`OrgName`) and repository name (`RepoName`) before proceeding with the issue creation. ### Function logic @@ -136,9 +118,7 @@ const handleEvent = async (event: any) => { }; ``` -Within this handler, the initial step involves extracting the GitHub token -provided as input in the keyring. Subsequently, the [Octokit](https://github.com/octokit/octokit.js), responsible for -managing GitHub API requests, is initialized: +Within this handler, the initial step involves extracting the GitHub token provided as input in the keyring. Subsequently, the [Octokit](https://github.com/octokit/octokit.js), responsible for managing GitHub API requests, is initialized: ```ts const githubPAT = event.input_data.keyrings.github_connection; @@ -148,8 +128,7 @@ const octokit = new Octokit({ ``` To facilitate authentication for DevRev API calls, a DevRev token is required. -The initialization process for the DevRev SDK involves using the received -endpoint. +The initialization process for the DevRev SDK involves using the received endpoint. ```ts const devrevToken = event.context.secrets.service_account_token; @@ -163,8 +142,8 @@ const devrevSDK = client.setup({ With the SDKs successfully initialized, the next step is to invoke the necessary APIs. -As a preliminary step, the required fields for creating a GitHub Issue, namely -**title** and **body**, need to be extracted. These details are sourced from the issue. +As a preliminary step, the required fields for creating a GitHub Issue, namely **title** and **body**, need to be extracted. These details are sourced from the issue. + To facilitate this, introduce a function defined for this specific purpose: ```ts @@ -190,8 +169,7 @@ const getIssueDetails = async (workId: string, devrevSDK: any) => { }; ``` -Now, the function can be called within the handler function to obtain the -necessary issue details:: +Now, the function can be called within the handler function to obtain the necessary issue details:: ```ts const workId = event.payload.source_id; @@ -230,9 +208,7 @@ const verifyOrgName = async (orgName: string, octokit: Octokit) => { }; ``` -Similarly, the -[GET Repository](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) -is used to validate whether the entered repository name is correct. +Similarly, the [GET Repository](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#get-a-repository) is used to validate whether the entered repository name is correct. ```ts const verifyRepoName = async ( @@ -255,9 +231,7 @@ const verifyRepoName = async ( }; ``` -After completing all the necessary verifications, the -[POST create issue](https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28#create-an-issue) -can be invoked to create a new issue. +After completing all the necessary verifications, the [POST create issue](https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28#create-an-issue) can be invoked to create a new issue. ```ts const createGitHubIssue = async ( @@ -287,34 +261,24 @@ The completion of functional logic is a key milestone in the process. After layi ### Deploying the snap-in to your organization -Once the code has been validated, the next steps involve creating the snap-in -version and subsequently creating the snap-in itself. Before installing the -snap-in, it's essential to set up a GitHub Personal Access Token (PAT) and add -it to the connections in DevRev as a snap-in secret. Ensure that the secret is -shared within the organization so that the snap-in can utilize it. +Once the code has been validated, the next steps involve creating the snap-in version and subsequently creating the snap-in itself. Before installing the snap-in, it's essential to set up a GitHub Personal Access Token (PAT) and add it to the connections in DevRev as a snap-in secret. Ensure that the secret is shared within the organization so that the snap-in can utilize it. Follow these steps to install the snap-in in your organization: #### Step 1: Create a GitHub personal access token -Generate a GitHub Personal Access Token (PAT) by following the steps outlined in the -[GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). +Generate a GitHub Personal Access Token (PAT) by following the steps outlined in the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). #### Step 2: Add PAT to DevRev connections -Add the generated PAT as a snap-in secret in DevRev. This secret will be used -during the installation of the snap-in. Ensure that the secret is shared within -the organization to allow the snap-in to access it. +Add the generated PAT as a snap-in secret in DevRev. This secret will be used during the installation of the snap-in. Ensure that the secret is shared within the organization to allow the snap-in to access it. #### Step 3: Install the snap-in -During the installation of the snap-in, utilize the shared secret to -authenticate and connect with GitHub. This ensures that the snap-in has the -necessary permissions to interact with GitHub APIs. +During the installation of the snap-in, utilize the shared secret to authenticate and connect with GitHub. This ensures that the snap-in has the necessary permissions to interact with GitHub APIs. ## Resources -The final snap-in code and manifest can be found -[here](https://github.com/devrev/snap-in-examples/tree/main/9-external-action). +The final snap-in code and manifest can be found [here](https://github.com/devrev/snap-in-examples/tree/main/9-external-action). From f519fbc1ae39f617ac0fca3b05070b8153328119 Mon Sep 17 00:00:00 2001 From: Kapil Garg Date: Wed, 29 Jan 2025 10:50:11 +0530 Subject: [PATCH 5/5] Update fern/docs/pages/tutorials/perform-external-action.mdx Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- fern/docs/pages/tutorials/perform-external-action.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/docs/pages/tutorials/perform-external-action.mdx b/fern/docs/pages/tutorials/perform-external-action.mdx index abb6e8da..925bc98d 100644 --- a/fern/docs/pages/tutorials/perform-external-action.mdx +++ b/fern/docs/pages/tutorials/perform-external-action.mdx @@ -271,7 +271,7 @@ Generate a GitHub Personal Access Token (PAT) by following the steps outlined in #### Step 2: Add PAT to DevRev connections -Add the generated PAT as a snap-in secret in DevRev. This secret will be used during the installation of the snap-in. Ensure that the secret is shared within the organization to allow the snap-in to access it. +Add the generated PAT as a snap-in secret in DevRev. This secret is used during the installation of the snap-in. Ensure that the secret is shared within the organization to allow the snap-in to access it. #### Step 3: Install the snap-in