Introduction

Commitspark is a set of tools to manage structured data with Git through a GraphQL API.

This repository holds code for a Commitspark Git adapter that provides access to Git repositories hosted on GitHub.

Installation

npm i @commitspark/git-adapter-github

Usage

Instantiate the adapter with createAdapter(), providing GitHubRepositoryOptions with the following parameters:

| Option name | Required | Default value | Description | |-------------------|----------|-------------------------------------|---------------------------------------------------| | repositoryOwner | True | | GitHub repository owner, e.g. commitspark | | repositoryName | True | | GitHub repository name, e.g. git-adapter-github | | accessToken | True | | GitHub access token (see details below) | | pathSchemaFile | False | commitspark/schema/schema.graphql | Path to schema file in repository | | pathEntryFolder | False | commitspark/entries/ | Path to folder for entries |

Access Token

An accessToken may be any one of the following types of tokens:

Personal Access Tokens (classic)

A personal access token with repo scope is required.

Fine-grained Personal Access Tokens

For read-only access, a fine-grained personal access token with the following repository permissions is sufficient:

| Permission | Access | |------------|-----------| | Contents | Read-only | | Metadata | Read-only |

For write-access, permissions must be as follows:

| Permission | Access | |------------|----------------| | Contents | Read and write | | Metadata | Read-only |

In both cases, ensure the fine-grained permissions you give actually apply to the repository you want to work with.

OAuth Tokens

Access tokens for a user obtained from an OAuth app can be used in the same way (including permissions) as fine-grained personal access tokens.

Error Handling

This adapter sends requests to the GitHub GraphQL API. In case a request fails, HTTP and GraphQL errors are mapped to GitAdapterError exceptions with ErrorCode values from the @commitspark/git-adapter package. This enables the Commitspark GraphQL API library to handle adapter errors in an adapter-agnostic way.

HTTP Status Code Mapping

HTTP error status codes are mapped as follows:

| HTTP Status | GitAdapter ErrorCode | |-------------|----------------------| | 400 | BAD_REQUEST | | 401 | UNAUTHORIZED | | 403 | FORBIDDEN | | 404 | NOT_FOUND | | 409 | CONFLICT | | 429 | TOO_MANY_REQUESTS | | Other | INTERNAL_ERROR |

GitHub GraphQL API Error Type Mapping

GitHub GraphQL API error types are mapped as follows:

| GitHub Error Type | GitAdapter ErrorCode | |-------------------|----------------------| | NOT_FOUND | NOT_FOUND | | RATE_LIMITED | TOO_MANY_REQUESTS | | FORBIDDEN | FORBIDDEN | | STALE_DATA | CONFLICT | | Other | INTERNAL_ERROR |

All errors include the original error message from GitHub for debugging purposes.

As GitHub GraphQL error types (codes) are not documented (see GitHub documentation issue #22607), mapping of GraphQL error types is done on a best-effort basis.

Example

To use this adapter together with the Commitspark GraphQL API library, your code could be the following:

import { createAdapter } from '@commitspark/git-adapter-github'
import { createClient } from '@commitspark/graphql-api'

const gitHubAdapter = createAdapter({
  repositoryOwner: process.env.GITHUB_REPOSITORY_OWNER,
  repositoryName: process.env.GITHUB_REPOSITORY_NAME,
  accessToken: process.env.GITHUB_ACCESS_TOKEN,
})

const client = await createClient(gitHubAdapter)

License

The code in this repository is licensed under the permissive ISC license (see LICENSE).