Skip to main content

​
Setup Guide

You will need to create a new GitHub developer application if you don’t already have one. Connect either a GitHub App or a GitHub OAuth Application to Paragon Connect. You can find your GitHub app credentials in your GitHub Developer Settings. You’ll need the following information to set up your GitHub App or GitHub OAuth App with Paragon Connect:
  • Client ID
  • Client Secret

​
GitHub Apps versus GitHub OAuth Applications

GitHub Apps are generally preferred over OAuth apps due to their improved security and scalability. They support fine-grained permissions and allow users to limit access to specific repositories. GitHub Apps can operate on behalf of a user or independently of a user, making them suitable for integrations that should continue functioning even if the original installer leaves an organization. They also provide a centralized webhook configuration across all accessible repositories and organizations, and benefit from higher, scalable rate limits tied to repository and user counts. OAuth apps have lower, non-scaling rate limits and use per-repository webhook configuration. An OAuth app is recommended when access to enterprise-level resources is required, or when using Custom Webhooks, which relies on per-repository or per-organization webhook setup. See Configuring Webhook Triggers for OAuth Applications. Paragon supports both GitHub Apps and OAuth apps across the platform. Learn more about the differences between GitHub Apps and OAuth apps here.

​
Add the Redirect URL to your GitHub app

Paragon provides a redirect URL to send information to your GitHub app. To add the redirect URL to your GitHub app:
  1. Copy the link under “Redirect URL” in your integration settings in Paragon. The Redirect URL is:
https://passport.useparagon.com/oauth
  1. Log into your GitHub Account.
  2. In the top-right corner, select Settings
  3. Under Developer Settings > OAuth Apps, select your GitHub app.
  4. Under General > Authorization callback URL, paste the Redirect URL provided in Step 1.

​
Add your GitHub app to Paragon

Under Integrations > Connected Integrations > GitHub > App Configuration > Configure, fill out your credentials from your developer app in their respective sections:
  • Client ID: Found under Settings > Developer settings > {YOUR APP} > Client ID on your GitHub App page.
  • Client Secret: Found under Settings > Developer settings > {YOUR APP} > Client Secret on your GitHub App page.
Leaving the Client ID and Client Secret blank will use Paragon development keys.

​
Connecting to GitHub

Once your users have connected their GitHub account, you can use the Paragon SDK to access the GitHub API on behalf of connected users. See the GitHub REST API documentation for their full API reference. Any GitHub API endpoints can be accessed with the Paragon SDK as shown in this example. 
// You can find your project ID in the Overview tab of any Integration

// Authenticate the user
paragon.authenticate(<ProjectId>, <UserToken>);
            
// Get issues associated with a repository
paragon.request("github", "/repos/{owner}/{repo}/issues", {
  method: "GET"
});

// Create a comment on an issue
paragon.request("github", "/repos/{owner}/{repo}/issues/{issue_number}/comments", {
  method: "POST",
  body: {
    body: "Looks good to me!"
  }
});

// Specify labels for an issue
paragon.request("github", "/repos/{owner}/{repo}/issues/{issue_number}/labels
", {
  method: "PUT",
  body: {
    labels: [
      'bug',
      'enhancement'
    ]
  }
});

​
Building GitHub workflows

Once your GitHub account is connected, you can add steps to perform the following actions:
  • Create Issue
  • Update Issue
  • Get Issue by Number
  • Lock Issue
  • Search Issue
  • Get Pull Request by Number
  • Get Files Changed in PR
  • Create Release
  • Update Release
  • Get Release by ID
  • Get Release by Tag Name
  • Delete Release
  • Get File
You can also use the GitHub Request step to access any of GitHub’s API endpoints without the authentication piece. When creating or updating issues in GitHub, you can reference data from previous steps by typing {{ to invoke the variable menu.

​
Using Webhook Triggers

Webhook triggers can be used to run workflows based on events in your users’ GitHub account. For example, you might want to trigger a workflow whenever new issues are created in GitHub to sync your users’ GitHub issues to your application in real-time.

​
Selecting the appropriate Trigger type

Paragon can receive GitHub events in two different ways. Which one you use depends on the type of GitHub integration you’re building. We’ll walk through configuring triggers for GitHub Apps and OAuth Applications below.

​
Configuring a GitHub App Trigger

All of your users’ GitHub events are sent to a single Webhook URL configured in your GitHub App registration. Follow the steps below to configure a GitHub App Trigger to use with Paragon.
1

Add the Webhook URL to your GitHub App

Paragon provides a dedicated Webhook URL for your project which can be copied from the integration’s settings in Paragon and pasted into the “Webhook URL” field in the GitHub App settings.
GitHub App Webhook URL
2

(Optional) Add a Webhook Secret to your GitHub App

You have the option to specify a Webhook Secret in your GitHub App settings used to verify the authenticity of event data. Author the secret in GitHub and enter the value in the “Webhook Secret” field in your Paragon integration’s settings.
GitHub Integration Settings
3

Select the appropriate Trigger type

In your Paragon workflow, choose the corresponding Trigger Event (or configure your own Custom Webhook) and select the “GitHub App” trigger type.
GitHub Workflow Settings

​
Configuring Triggers for an OAuth Application

For OAuth Applications in GitHub, Paragon leverages the connected user’s OAuth token to manage webhook subscriptions via the GitHub API. This allows Paragon to programmatically create, update, or remove webhook endpoints at the organization or repository level based on the connected user’s permissions and the trigger’s configuration. Ensure that the necessary scopes are requested in your GitHub App settings (repo for repository hooks or admin:org_hook for organization-wide hooks) to set up these subscriptions. Then in your Paragon workflow, choose the corresponding Trigger Event or configure your own Custom Webhook, and select either the “Repository” or “Organization” trigger type.
GitHub Workflow Settings
You can find the full list of Webhook Triggers for GitHub below:
  • Issue Created
  • Issue Updated
  • PR Created
  • PR Updated
  • Project Created
  • Project Updated
  • Project Created (Classic)
  • Project Updated (Classic)
  • Project Item Created
  • Project Item Updated
For additional webhook triggers, you can configure webhooks for any GitHub webhook event using Custom Webhooks.