github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

GitHub docs improvements (#568)

Browse Source 
* 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>
This commit is contained in:
Dan
2023-10-09 16:48:38 +01:00
committed by GitHub
parent 59a94c710e
commit cbc976188e
3 changed files with 3302 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integrations/apis/github-tasks.mdx
+231 -22
View File
@@ -1,54 +1,263 @@
---
title: Tasks
title: GitHub Tasks
sidebarTitle: Tasks
---
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.
---
## All tasks
| Function Name | Description |
| -------------------------------- | ----------------------------------------------------------- |
| `createIssue` | Creates a new issue in a repository. |
| `addIssueAssignees` | Adds assignees to an existing issue. |
| `addIssueLabels` | Adds labels to an existing issue. |
| `createIssueComment` | Creates a new comment on an existing issue. |
| `getRepo` | Retrieves information about a repository. |
| `createIssueCommentWithReaction` | Creates a new comment on an existing issue with a reaction. |
| `addIssueCommentReaction` | Adds a reaction to an existing issue comment. |
| `updateWebhook` | Updates an existing webhook. |
| `createWebhook` | Creates a new webhook. |
| `listWebhooks` | Lists the webhooks for a repository. |
| `updateOrgWebhook` | Updates an existing webhook for an organization. |
| `createOrgWebhook` | Creates a new webhook for an organization. |
| `listOrgWebhooks` | Lists the webhooks for an organization. |
### `createIssue`
## Usage
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).
```ts example.ts
await io.github.createIssue("create issue", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
title: "<issue-title>", // the title of the issue
body: "<issue-description>", // the contents of the issue
});
```
### `addIssueAssignees`
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).
```ts example.ts
await io.github.addIssueAssignees("add assignee", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
issueNumber: <issue-number>, // the number of the issue
assignees: ["<assignee-name>"], // the name(s) of the assignee(s)
});
```
### `addIssueLabels`
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).
```ts example.ts
await io.github.addIssueLabels("add label", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
issueNumber: <issue-number>, // the number of the issue
labels: ["<label-name>"], // the name(s) of the label(s)
});
```
### `createIssueComment`
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).
```ts example.ts
await io.github.createIssueComment("create comment", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
issueNumber: <issue-number>, // the number of the issue
body: "<comment-text>", // the contents of the comment
});
```
### `getRepo`
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).
```ts example.ts
const repoInfo = await io.github.getRepo({
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
});
```
### `createIssueCommentWithReaction`
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).
```ts example.ts
await io.github.createIssueCommentWithReaction("create comment with reaction", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
issueNumber: <issue-number>, // the number of the issue
body: "<comment-text>", // the contents of the comment
content: "<reaction-type>", // the type of reaction
});
```
### `addIssueCommentReaction`
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).
```ts example.ts
await io.github.addIssueCommentReaction("add reaction", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
commentId: <comment-id>, // the id of the specific comment
content: "<reaction-type>", // the type of reaction
});
```
### `updateWebhook`
Updates an existing webhook. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#update-a-repository-webhook).
```ts example.ts
await io.github.updateWebhook("update webhook", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
webhookId: <webhook-id>, // the unique id of the webhook
config: {
url: "<webhook-url>", // the url to which payloads will be delivered
contentType: "json", // the media type used to serialize the payloads
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
},
});
```
### `createWebhook`
Creates a new webhook. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#create-a-repository-webhook).
```ts example.ts
await io.github.createWebhook("create webhook", {
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
config: {
url: "<webhook-url>", // the url to which payloads will be delivered
contentType: "json", // the media type used to serialize the payloads
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
},
events: ["<event-type>"], // the events for which the webhook will trigger
});
```
### `listWebhooks`
Lists the webhooks for a repository. [Official GitHub docs](https://docs.github.com/en/rest/webhooks/repos?apiVersion=2022-11-28#list-repository-webhooks).
```ts example.ts
const webhooks = await io.github.listWebhooks({
owner: "<owner-name>", // the name of the owner of the repository
repo: "<repo-name>", // the name of the repository
});
```
### `updateOrgWebhook`
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).
```ts
await io.github.updateOrgWebhook("update org webhook", {
org: "<organization-name>", // the name of the organization
webhookId: <webhook-id>, // the unique id of the webhook
config: {
url: "<webhook-url>", // the url to which payloads will be delivered
contentType: "json", // the media type used to serialize the payloads
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
},
});
```
### `createOrgWebhook`
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).
```ts example.ts
await io.github.createOrgWebhook("create org webhook", {
org: "<organization-name>", // the name of the organization
config: {
url: "<webhook-url>", // the url to which payloads will be delivered
contentType: "json", // the media type used to serialize the payloads
secret: "<webhook-secret>", // If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.
},
events: ["<event-type>"], // the events for which the webhook will trigger
});
```
### `listOrgWebhooks`
Lists the webhooks for an organization. [Official GitHub docs](https://docs.github.com/en/rest/orgs/webhooks?apiVersion=2022-11-28#list-organization-webhooks).
```ts example.ts
const orgWebhooks = await io.github.listOrgWebhooks({
org: "<organization-name>", // the name of the organization
per-page: <number>, // the number of webhooks to return per page (max 100)
page: <number>, // Page number of the results to fetch.
});
```
## Example usage
In this example we'll create a task that adds an assignee and a label to an issue when it's opened.
```ts
client.defineJob({
id: "github-integration-on-issue-opened",
name: "GitHub Integration - On Issue Opened",
version: "0.1.0",
version: "1.0.0",
integrations: { github },
trigger: github.triggers.repo({
event: events.onIssueOpened,
owner: "triggerdotdev",
repo: "empty",
owner: "<your-org-name>",
repo: "<your-repo-name>",
}),
run: async (payload, io, ctx) => {
await io.github.addIssueAssignees("add assignee", {
owner: payload.repository.owner.login,
repo: payload.repository.name,
issueNumber: payload.issue.number,
assignees: ["matt-aitken"],
assignees: ["<assignee-name>"],
});
await io.github.addIssueLabels("add label", {
owner: payload.repository.owner.login,
repo: payload.repository.name,
issueNumber: payload.issue.number,
labels: ["bug"],
labels: ["<label-name>"],
});
return { payload, ctx };
},
});
```
## Using the underlying GitHub client
You can access the [Octokit instance](https://github.com/octokit/octokit.js#octokit-api-client) by using the `runTask` method on the integration:
```ts
const github = new Github({
id: "github",
});
client.defineJob({
id: "github-example-1",
name: "GitHub Example 1",
version: "0.1.0",
trigger: eventTrigger({
name: "github.example",
}),
integrations: {
github,
},
run: async (payload, io, ctx) => {
const contributors = await io.github.runTask(
"get-contributors",
async (octokit, task) => {
const contributors = await octokit.rest.repos.listContributors({
owner: "<owner-name>",
repo: "<repo-name>",
});
return contributors;
},
//this is optional, it will appear on the Run page
{ name: "List Contributors" }
);
},
});
```
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.
docs/integrations/apis/github-triggers.mdx
+3035 -28
View File
File diff suppressed because it is too large Load Diff
docs/integrations/apis/github.mdx
+36 -58
View File
@@ -1,11 +1,21 @@
---
title: "GitHub: Introduction"
sidebarTitle: "Introduction"
title: GitHub overview & authentication
sidebarTitle: Overview & authentication
---
<Snippet file="integration-getting-started.mdx" />
## Overview
## Installation
Our GitHub integration allows you to create triggers and tasks that interact with GitHub. For examples of some of the things you can do with it, check out our Jobs Showcase:
<Card
title="Jobs Showcase - GitHub"
icon="rocket"
href="https://trigger.dev/showcase?tags=&integrations=github"
>
Check out pre-built GitHub jobs in our showcase.
</Card>
## Installing the GitHub packages
<CodeGroup>
@@ -25,25 +35,41 @@ yarn add @trigger.dev/github@latest
## Authentication
GitHub supports Personal Access Tokens and OAuth.
GitHub supports Personal Access Tokens and OAuth. You can use either of these to authenticate with GitHub.
```ts
import { Github } from "@trigger.dev/github";
### Personal Access Token
To create a personal access token on GitHub, login and [follow the instructions](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). Information on the required scopes can be found [here](https://docs.github.com/en/developers/apps/scopes-for-oauth-apps).
```ts my-job.ts
import { GitHub } from "@trigger.dev/github";
//create GitHub client using a token
const github = new Github({
const github = new GitHub({
id: "github",
token: process.env.GITHUB_TOKEN!,
});
...
```
### OAuth
To use OAuth you can connect to GitHub via the Trigger.dev [web app](https://cloud.trigger.dev). Click 'Integrations' in the side panel of any project, and configure GitHub with the ID you want to use in your job and the required [scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps).
```ts my-job.ts
import { GitHub } from "@trigger.dev/github";
//create GitHub client using OAuth
const github2 = new Github({
id: "github2",
const github = new GitHub({
id: "github",
});
...
```
## Triggers and Tasks
Once you have set up a GitHub client, you can use it to create triggers and tasks.
<CardGroup cols={2}>
<Card title="Triggers" icon="stars" href="/integrations/apis/github-triggers">
Trigger Jobs when events happen in GitHub, such as a new commit or a new issue.
@@ -52,51 +78,3 @@ const github2 = new Github({
Perform tasks such as creating a new issue or a new comment.
</Card>
</CardGroup>
## Using the underlying client
You can use the underlying client to do anything Octokit supports. In this example we create a project card when a new issue is opened..
<Info>
View [the official GitHub docs](https://docs.github.com/en/rest) for everything that is
supported{" "}
</Info>
```ts
import { Github, events } from "@trigger.dev/github";
const github = new Github({
id: "github",
token: process.env.GITHUB_TOKEN!,
});
client.defineJob({
id: "alert-on-new-github-issues",
name: "Alert on new GitHub issues",
version: "0.1.1",
trigger: github.triggers.repo({
event: events.onIssueOpened,
owner: "triggerdotdev",
repo: "trigger.dev",
}),
integrations: {
github,
},
run: async (payload, io, ctx) => {
//io.github.runTask allows you to use the underlying SDK client
const { data } = await io.github.runTask(
"create-card",
async (client) => {
return client.rest.projects.createCard({
column_id: 123,
note: "test",
});
},
{ name: "Create card" }
);
//log the url of the created card
await io.logger.info(data.url);
},
});
```