Skip to content

fix link #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 29, 2025
Merged

fix link #146

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2c53808
fix link
codeon Jan 29, 2025
c379165
minor grammar fixes
codeon Jan 29, 2025
ddfeea0
Apply suggestions from code review
codeon Jan 29, 2025
23edc4e
Update perform-external-action.mdx
Atul-Butola Jan 29, 2025
f519fbc
Update fern/docs/pages/tutorials/perform-external-action.mdx
codeon Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 25 additions & 61 deletions fern/docs/pages/tutorials/perform-external-action.mdx
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [EkLine] reported by reviewdog 🐶

Consider using 'snap-in' instead of 'snapin'. (EK25033)

fern-api-docs/fern/docs/pages/tutorials/perform-external-action.mdx

Line 30 in 23edc4e

If you did not follow the [getting started](/snapin-development/tutorials/getting-started) tutorial then follow these steps to authenticate and initialize the snap-in TypeScript template:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [EkLine] reported by reviewdog 🐶

In general, Use the American spelling 'organization' instead of British "organisation". (EK00001)

fern-api-docs/fern/docs/pages/tutorials/perform-external-action.mdx

Line 193 in 23edc4e

The GitHub REST API (https://docs.github.com/en/rest/orgs/orgs?apiVersion=2022-11-28#get-an-organization) is used to confirm the specified organisation name.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ [EkLine] reported by reviewdog 🐶

Where possible, do not structure sentences in future tense. Use present tense instead. (EK00005)

fern-api-docs/fern/docs/pages/tutorials/perform-external-action.mdx

Line 260 in 23edc4e

The completion of functional logic is a key milestone in the process. After laying the framework, now you'll learn how to install this snap-in for your organization.

Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
## Introduction

In this tutorial, you'll lean 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

Expand All @@ -24,8 +22,8 @@ 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 [jq](https://stedolan.github.io/jq)
- 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)

<Callout intent="info">
Expand All @@ -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"
Expand All @@ -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
Expand All @@ -90,21 +78,17 @@ 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:
- name: command_handler
description: Function to create a GitHub issue
```

The command clearly 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:
Expand All @@ -119,14 +103,12 @@ 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

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.

Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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 (
Expand All @@ -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 (
Expand Down Expand Up @@ -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
#### 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.

</Steps>

## 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).
Loading