Dan
c47ad5e038
* integration docs various improvements * Added optional comments to step by step guide * Added API catalog card to the integrations intro * Added Api catalog button to the examples job tab * Tweaked copy of api catalog card * Update introduction.mdx --------- Co-authored-by: Matt Aitken <matt@mattaitken.com>
83 lines
2.5 KiB
Plaintext
83 lines
2.5 KiB
Plaintext
---
|
|
title: GitHub overview & authentication
|
|
sidebarTitle: Overview & authentication
|
|
---
|
|
|
|
## Overview
|
|
|
|
Our GitHub integration allows you to create triggers and tasks that interact with GitHub. Trigger jobs when events happen, like when a new issue is added to a repo, or when a pull request is opened, etc. You can also perform tasks like creating issues, getting information about a repo, adding comments, and much more.
|
|
|
|
<Card
|
|
title="Jobs Showcase - GitHub"
|
|
icon="rocket"
|
|
href="https://trigger.dev/showcase?tags=&apis=github"
|
|
>
|
|
Check out pre-built GitHub jobs in our showcase.
|
|
</Card>
|
|
|
|
## Installing the GitHub packages
|
|
|
|
To get started with our GitHub integration, you need to install the `@trigger.dev/github` packages. You can do this using `npm`, `pnpm`, or `yarn`:
|
|
|
|
<CodeGroup>
|
|
|
|
```bash npm
|
|
npm install @trigger.dev/github@latest
|
|
```
|
|
|
|
```bash pnpm
|
|
pnpm install @trigger.dev/github@latest
|
|
```
|
|
|
|
```bash yarn
|
|
yarn add @trigger.dev/github@latest
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
## Authentication
|
|
|
|
GitHub supports Personal Access Tokens and OAuth. You can use either of these to authenticate with 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({
|
|
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 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.
|
|
</Card>
|
|
<Card title="Tasks" icon="sparkles" href="/integrations/apis/github-tasks">
|
|
Perform tasks such as creating a new issue or a new comment.
|
|
</Card>
|
|
</CardGroup>
|