Skip to content

Commit cbc9761

Browse files
D-K-Pericallam
D-K-P
and
ericallam
authored
GitHub docs improvements (#568)
* Updated github-triggers and intro * Edited tasks / triggers and main overview page * Added links to scopes docs and improved copy * Added an overview, side bar title and improved the ordering / wording * Added the underlying Github client section and some formatting updates --------- Co-authored-by: Eric Allam <eric@trigger.dev> Co-authored-by: Eric Allam <eallam@icloud.com>
1 parent 59a94c7 commit cbc9761

3 files changed

Lines changed: 3304 additions & 110 deletions

File tree

‎docs/integrations/apis/github-tasks.mdx‎

Lines changed: 232 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,263 @@
11
---
2-
title: Tasks
2+
title: GitHub Tasks
3+
sidebarTitle: Tasks
4+
---
5+
6+
Tasks are executed after the job is triggered and are the main building blocks of a job. You can string together as many tasks as you want.
7+
38
---
49

510
## All tasks
611

7-
| Function Name | Description |
8-
| -------------------------------- | ----------------------------------------------------------- |
9-
| `createIssue` | Creates a new issue in a repository. |
10-
| `addIssueAssignees` | Adds assignees to an existing issue. |
11-
| `addIssueLabels` | Adds labels to an existing issue. |
12-
| `createIssueComment` | Creates a new comment on an existing issue. |
13-
| `getRepo` | Retrieves information about a repository. |
14-
| `createIssueCommentWithReaction` | Creates a new comment on an existing issue with a reaction. |
15-
| `addIssueCommentReaction` | Adds a reaction to an existing issue comment. |
16-
| `updateWebhook` | Updates an existing webhook. |
17-
| `createWebhook` | Creates a new webhook. |
18-
| `listWebhooks` | Lists the webhooks for a repository. |
19-
| `updateOrgWebhook` | Updates an existing webhook for an organization. |
20-
| `createOrgWebhook` | Creates a new webhook for an organization. |
21-
| `listOrgWebhooks` | Lists the webhooks for an organization. |
22-
23-
## Usage
12+
### `createIssue`
13+
14+
Creates a new issue in a repository. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/issues/issues?apiVersion=2022-11-28#create-an-issue).
15+
16+
```ts example.ts
17+
await io.github.createIssue("create issue", {
18+
owner: "<owner-name>", // the name of the owner of the repository
19+
repo: "<repo-name>", // the name of the repository
20+
title: "<issue-title>", // the title of the issue
21+
body: "<issue-description>", // the contents of the issue
22+
});
23+
```
24+
25+
### `addIssueAssignees`
26+
27+
Adds assignees to an existing issue. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/issues/assignees?apiVersion=2022-11-28#add-assignees-to-an-issue).
28+
29+
```ts example.ts
30+
await io.github.addIssueAssignees("add assignee", {
31+
owner: "<owner-name>", // the name of the owner of the repository
32+
repo: "<repo-name>", // the name of the repository
33+
issueNumber: <issue-number>, // the number of the issue
34+
assignees: ["<assignee-name>"], // the name(s) of the assignee(s)
35+
});
36+
```
37+
38+
### `addIssueLabels`
39+
40+
Adds labels to an existing issue. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/issues/labels?apiVersion=2022-11-28#add-labels-to-an-issue).
41+
42+
```ts example.ts
43+
await io.github.addIssueLabels("add label", {
44+
owner: "<owner-name>", // the name of the owner of the repository
45+
repo: "<repo-name>", // the name of the repository
46+
issueNumber: <issue-number>, // the number of the issue
47+
labels: ["<label-name>"], // the name(s) of the label(s)
48+
});
49+
```
50+
51+
### `createIssueComment`
52+
53+
Creates a new comment on an existing issue. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/issues/comments?apiVersion=2022-11-28#create-an-issue-comment).
54+
55+
```ts example.ts
56+
await io.github.createIssueComment("create comment", {
57+
owner: "<owner-name>", // the name of the owner of the repository
58+
repo: "<repo-name>", // the name of the repository
59+
issueNumber: <issue-number>, // the number of the issue
60+
body: "<comment-text>", // the contents of the comment
61+
});
62+
```
63+
64+
### `getRepo`
65+
66+
Retrieves information about a repository. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/repos/repos?apiVersion=2022-11-28#get-a-repository).
67+
68+
```ts example.ts
69+
const repoInfo = await io.github.getRepo({
70+
owner: "<owner-name>", // the name of the owner of the repository
71+
repo: "<repo-name>", // the name of the repository
72+
});
73+
```
74+
75+
### `createIssueCommentWithReaction`
76+
77+
Creates a new comment on an existing issue with a reaction. [Official GitHub docs](https://docs.github.com/en/rest/issues/comments?apiVersion=2022-11-28#create-an-issue-comment).
78+
79+
```ts example.ts
80+
await io.github.createIssueCommentWithReaction("create comment with reaction", {
81+
owner: "<owner-name>", // the name of the owner of the repository
82+
repo: "<repo-name>", // the name of the repository
83+
issueNumber: <issue-number>, // the number of the issue
84+
body: "<comment-text>", // the contents of the comment
85+
content: "<reaction-type>", // the type of reaction
86+
});
87+
```
88+
89+
### `addIssueCommentReaction`
90+
91+
Adds a reaction to an existing issue comment. [Official GitHub docs](https://docs.github.com/en/free-pro-team@latest/rest/reactions/reactions?apiVersion=2022-11-28#create-reaction-for-an-issue-comment).
92+
93+
```ts example.ts
94+
await io.github.addIssueCommentReaction("add reaction", {
95+
owner: "<owner-name>", // the name of the owner of the repository
96+
repo: "<repo-name>", // the name of the repository
97+
commentId: <comment-id>, // the id of the specific comment
98+
content: "<reaction-type>", // the type of reaction
99+
});
100+
```
101+
102+
### `updateWebhook`
103+
104+
Updates an existing webhook. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#update-a-repository-webhook).
105+
106+
```ts example.ts
107+
await io.github.updateWebhook("update webhook", {
108+
owner: "<owner-name>", // the name of the owner of the repository
109+
repo: "<repo-name>", // the name of the repository
110+
webhookId: <webhook-id>, // the unique id of the webhook
111+
config: {
112+
url: "<webhook-url>", // the url to which payloads will be delivered
113+
contentType: "json", // the media type used to serialize the payloads
114+
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
115+
},
116+
});
117+
```
118+
119+
### `createWebhook`
120+
121+
Creates a new webhook. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#create-a-repository-webhook).
122+
123+
```ts example.ts
124+
await io.github.createWebhook("create webhook", {
125+
owner: "<owner-name>", // the name of the owner of the repository
126+
repo: "<repo-name>", // the name of the repository
127+
config: {
128+
url: "<webhook-url>", // the url to which payloads will be delivered
129+
contentType: "json", // the media type used to serialize the payloads
130+
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
131+
},
132+
events: ["<event-type>"], // the events for which the webhook will trigger
133+
});
134+
```
135+
136+
### `listWebhooks`
137+
138+
Lists the webhooks for a repository. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#list-repository-webhooks).
139+
140+
```ts example.ts
141+
const webhooks = await io.github.listWebhooks({
142+
owner: "<owner-name>", // the name of the owner of the repository
143+
repo: "<repo-name>", // the name of the repository
144+
});
145+
```
146+
147+
### `updateOrgWebhook`
148+
149+
Updates an existing webhook for an organization. [Official GitHub docs](https://docs.github.com/en/rest/orgs/webhooks?apiVersion=2022-11-28#update-an-organization-webhook).
150+
151+
```ts
152+
await io.github.updateOrgWebhook("update org webhook", {
153+
org: "<organization-name>", // the name of the organization
154+
webhookId: <webhook-id>, // the unique id of the webhook
155+
config: {
156+
url: "<webhook-url>", // the url to which payloads will be delivered
157+
contentType: "json", // the media type used to serialize the payloads
158+
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
159+
},
160+
});
161+
```
162+
163+
### `createOrgWebhook`
164+
165+
Creates a new webhook for an organization. [Official GitHub docs](https://docs.github.com/en/rest/orgs/webhooks?apiVersion=2022-11-28#create-an-organization-webhook).
166+
167+
```ts example.ts
168+
await io.github.createOrgWebhook("create org webhook", {
169+
org: "<organization-name>", // the name of the organization
170+
config: {
171+
url: "<webhook-url>", // the url to which payloads will be delivered
172+
contentType: "json", // the media type used to serialize the payloads
173+
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
174+
},
175+
events: ["<event-type>"], // the events for which the webhook will trigger
176+
});
177+
```
178+
179+
### `listOrgWebhooks`
180+
181+
Lists the webhooks for an organization. [Official GitHub docs](https://docs.github.com/en/rest/orgs/webhooks?apiVersion=2022-11-28#list-organization-webhooks).
182+
183+
```ts example.ts
184+
const orgWebhooks = await io.github.listOrgWebhooks({
185+
org: "<organization-name>", // the name of the organization
186+
per-page: <number>, // the number of webhooks to return per page (max 100)
187+
page: <number>, // Page number of the results to fetch.
188+
});
189+
```
190+
191+
## Example usage
192+
193+
In this example we'll create a task that adds an assignee and a label to an issue when it's opened.
24194

25195
```ts
26196
client.defineJob({
27197
id: "github-integration-on-issue-opened",
28198
name: "GitHub Integration - On Issue Opened",
29-
version: "0.1.0",
199+
version: "1.0.0",
30200
integrations: { github },
31201
trigger: github.triggers.repo({
32202
event: events.onIssueOpened,
33-
owner: "triggerdotdev",
34-
repo: "empty",
203+
owner: "<your-org-name>",
204+
repo: "<your-repo-name>",
35205
}),
36206
run: async (payload, io, ctx) => {
37207
await io.github.addIssueAssignees("add assignee", {
38208
owner: payload.repository.owner.login,
39209
repo: payload.repository.name,
40210
issueNumber: payload.issue.number,
41-
assignees: ["matt-aitken"],
211+
assignees: ["<assignee-name>"],
42212
});
43213

44214
await io.github.addIssueLabels("add label", {
45215
owner: payload.repository.owner.login,
46216
repo: payload.repository.name,
47217
issueNumber: payload.issue.number,
48-
labels: ["bug"],
218+
labels: ["<label-name>"],
49219
});
50220

51221
return { payload, ctx };
52222
},
53223
});
54224
```
225+
226+
## Using the underlying GitHub client
227+
228+
You can access the [Octokit instance](https://github.com/octokit/octokit.js#octokit-api-client) by using the `runTask` method on the integration:
229+
230+
```ts
231+
const github = new Github({
232+
id: "github",
233+
});
234+
235+
client.defineJob({
236+
id: "github-example-1",
237+
name: "GitHub Example 1",
238+
version: "0.1.0",
239+
trigger: eventTrigger({
240+
name: "github.example",
241+
}),
242+
integrations: {
243+
github,
244+
},
245+
run: async (payload, io, ctx) => {
246+
const contributors = await io.github.runTask(
247+
"get-contributors",
248+
async (octokit, task) => {
249+
const contributors = await octokit.rest.repos.listContributors({
250+
owner: "<owner-name>",
251+
repo: "<repo-name>",
252+
});
253+
254+
return contributors;
255+
},
256+
//this is optional, it will appear on the Run page
257+
{ name: "List Contributors" }
258+
);
259+
},
260+
});
261+
```
262+
263+
Make sure to pass the `idempotencyKey` to the underlying client to ensure that the API call is only executed once. This is only needed for mutating API calls.

0 commit comments

Comments
 (0)