GitHub

Work with a user's GitHub repositories, issues and pull requests, and receive signed webhooks.

Developer Tools
OAuth 2.0 + PKCE
Works on Free plan
Bundled in Kirak
Maintained by Kirak

How to use it

This profile ships with Kirak. Add "integrations" to modules in kirak.json, then name the profile as below. There is nothing to download, and a copy in your project's integrations/ folder is an error.

Environment variables

Variable	Holds
`KIRAK_INTEGRATION_GITHUB_CLIENT_SECRET`	The OAuth client secret from the vendor's console. Secret: keep it out of kirak.json and out of source control.
`KIRAK_INTEGRATION_GITHUB_WEBHOOK_SECRET`	Checks the signature of each webhook delivery. Secret: keep it out of kirak.json and out of source control.
`KIRAK_AUTH_ENCRYPTION_KEYS`	Encrypts stored tokens. Shared by every integration; the module refuses to start without it.

The names follow the integration's name in kirak.json (github here). Name it something else, such as github_sales, and the variables change to match.

Redirect URL

Register this as the redirect (callback) URL in the vendor's console, with your app's address in place of <your-app> (the base_url in kirak.json):

https://<your-app>/integrations/github/callback

How to get your keys

On GitHub, open Settings > Developer settings > OAuth Apps and choose New OAuth App (for an organisation, use the organisation’s settings).
Set Authorization callback URL to https://<your-app>/integrations/github/callback.
Register the app, copy the client ID, and choose Generate a new client secret.
Put the client ID in kirak.json as integrations.providers.github.client_id, and the client secret in the environment as KIRAK_INTEGRATION_GITHUB_CLIENT_SECRET. Never put the secret in kirak.json.
If your app receives GitHub webhooks, use one random secret for each webhook you create on GitHub and set the same value in the environment as KIRAK_INTEGRATION_GITHUB_WEBHOOK_SECRET. Kirak checks each delivery’s signature with it.

The vendor's own guide · Instructions out of date? ·Suggest an edit

kirak.json

Scopes repo Private and public repositories read:user Read the user's profile data user:email Read the user's email addresses read:org Read org and team membership gist Create and update gists

{
  "integrations": {
    "providers": {
      "github": {
        "type": "oauth2",
        "profile": "github",
        "client_id": "your-client-id",
        "scope": [
          "read:user"
        ]
      }
    }
  }
}

Merged into the profile: scope replaces the profile's default scopes.

Webhooks

Kirak receives GitHub's webhooks at /integrations/github/webhooks, checks the signature (X-Hub-Signature-256), drops duplicates and calls your handler for each event, named from X-GitHub-Event.

Good to know

The authorize and token requests take the scopes space separated; the token response lists them comma separated.
OAuth app tokens do not expire unless the app asks for offline_access, which also returns a refresh token.
A refresh invalidates the old access token and refresh token: store the new pair at once.
Scope meanings are short summaries of GitHub's scopes reference; check it before a release.

Example calls

GET /user/repos: List the signed-in user's repositories
GET /repos/{owner}/{repo}/commits: List the commits of one repository

Help improve this profile

Report a problem ·Suggest an edit to profile.json ·Add a profile ·Vendor docs the profile was checked against

Product names and logos are trademarks of their respective owners. Their use does not imply endorsement. To ask for this icon to be removed, email trademark@kirak.io.