You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: fern/docs/pages/tutorials/perform-external-action.mdx
+25-61Lines changed: 25 additions & 61 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,6 @@
1
1
## Introduction
2
2
3
-
In this tutorial, you'll lean how to develop a snap-in that mirrors an issue from
4
-
DevRev to GitHub. This requires addition of a command that can be run from
5
-
the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub.
3
+
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.
6
4
7
5
## Background context
8
6
@@ -24,8 +22,8 @@ the **Discussions** tab of an issue in DevRev, which creates an issue in GitHub.
To initiate the process of creating a GitHub issue directly from a DevRev issue,
46
-
a trigger mechanism is essential. In this context, the implementation involves
47
-
the introduction of a specialized command. This command is designed to be
48
-
executed exclusively from the discussion section of a DevRev issue, serving as
49
-
the catalyst for replicating the issue on GitHub.
43
+
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.
50
44
51
45
#### Action
52
46
53
-
The primary action involves leveraging the issue creation API provided by
54
-
GitHub. This API is utilized to create the GitHub issue seamlessly from the
55
-
corresponding issue in DevRev.
47
+
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.
56
48
57
49
### Creating the snap-in
58
50
59
51
#### Updating the manifest
60
52
61
-
To outline the structure of the snap-in, the initial step is to define key
62
-
attributes in the snap-in's manifest. Begin by specifying the name, description,
63
-
and account display name for the snap-in.
53
+
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.
64
54
65
55
```yml
66
56
version: "2"
@@ -73,9 +63,7 @@ service_account:
73
63
74
64
### Keyrings
75
65
76
-
To facilitate authentication for our API calls, the initial step involves
77
-
creating a Personal Access Token (PAT) in GitHub. This PAT can be stored as a
78
-
[connection](/snapin-development/references/keyrings) within DevRev. Subsequently, this
66
+
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
79
67
connection is employed within our snap-in in the form of keyrings.
80
68
81
69
```yml
@@ -90,21 +78,17 @@ keyrings:
90
78
91
79
### Functions and commands
92
80
93
-
Having established the foundational configurations, the subsequent step is to
94
-
define the functions and commands responsible for orchestrating the core logic
95
-
of the snap-in.
81
+
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.
96
82
97
83
```yaml
98
84
functions:
99
85
- name: command_handler
100
86
description: Function to create a GitHub issue
101
87
```
102
88
103
-
The command clearly states where you can use it. For example, in the
104
-
**Discussions** tab of issues.
89
+
The command states where you can use it. For example, in the **Discussions** tab of issues.
105
90
106
-
It also explains the different situations and
107
-
ways in which you can make use of this command.
91
+
It also explains the different situations and ways in which you can make use of this command.
108
92
109
93
```yml
110
94
commands:
@@ -119,14 +103,12 @@ commands:
119
103
function: command_handler
120
104
```
121
105
122
-
To utilize this command, execute `/gh_issue OrgName RepoName` in the **Discussions**
123
-
tab of the issue. Within the function logic, validations are implemented to
124
-
ensure the correctness of both the organization name (`OrgName`) and repository
106
+
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
125
107
name (`RepoName`) before proceeding with the issue creation.
126
108
127
109
### Function logic
128
110
129
-
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.
111
+
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.
130
112
131
113
To proceed, define the handler function for command events.
Within this handler, the initial step involves extracting the GitHub token
140
-
provided as input in the keyring. Subsequently, the [Octokit](https://github.com/octokit/octokit.js), responsible for
141
-
managing GitHub API requests, is initialized:
121
+
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:
With the SDKs successfully initialized, the next step is to invoke the necessary
164
143
APIs.
165
144
166
-
As a preliminary step, the required fields for creating a GitHub Issue, namely
167
-
**title** and **body**, need to be extracted. These details are sourced from the issue.
145
+
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.
146
+
168
147
To facilitate this, introduce a function defined for this specific purpose:
is used to validate whether the entered repository name is correct.
211
+
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.
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.
261
235
262
236
```ts
263
237
const createGitHubIssue = async (
@@ -287,34 +261,24 @@ The completion of functional logic is a key milestone in the process. After layi
287
261
288
262
### Deploying the snap-in to your organization
289
263
290
-
Once the code has been validated, the next steps involve creating the snap-in
291
-
version and subsequently creating the snap-in itself. Before installing the
292
-
snap-in, it's essential to set up a GitHub Personal Access Token (PAT) and add
293
-
it to the connections in DevRev as a snap-in secret. Ensure that the secret is
294
-
shared within the organization so that the snap-in can utilize it.
264
+
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.
295
265
296
266
Follow these steps to install the snap-in in your organization:
297
267
298
-
#### Step 1: Create a GitHub personal access token
268
+
#### Step 1: Create a GitHub personal access token
299
269
300
-
Generate a GitHub Personal Access Token (PAT) by following the steps outlined in the
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).
302
271
303
272
#### Step 2: Add PAT to DevRev connections
304
273
305
-
Add the generated PAT as a snap-in secret in DevRev. This secret will be used
306
-
during the installation of the snap-in. Ensure that the secret is shared within
307
-
the organization to allow the snap-in to access it.
274
+
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.
308
275
309
276
#### Step 3: Install the snap-in
310
277
311
-
During the installation of the snap-in, utilize the shared secret to
312
-
authenticate and connect with GitHub. This ensures that the snap-in has the
313
-
necessary permissions to interact with GitHub APIs.
278
+
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.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments