SHIP IT FASTER

The average enterprise on Netlify ships 140 times per week. Where does your team rank?

ContactSign Up
Community Plugin
View plugin on GitHub

Build Status Coverage Status

gatsby-source-github-api

Source plugin for pulling data into Gatsby from the official GitHub v4 GraphQL API.

Install

npm i gatsby-source-github-api

How to use

Follow GitHub’s guide how to generate a token.

Once you are done, either create a gatsby-config.js file or open the one you already have.

In there, you want to add this plugin and at least add the token in the options object:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-github-api`,
    options: {
      // url: API URL to use. Defaults to  https://api.github.com/graphql
      url: someUrl,

      // token: required by the GitHub API
      token: someString,

      // GraphQLquery: defaults to a search query
      graphQLQuery: anotherString,

      // variables: defaults to variables needed for a search query
      variables: someObject
    }
  }
];

Examples

Search query:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-github-api`,
    options: {
      token: "hunter2",
      variables: {
        q: "author:ldd state:closed type:pr sort:comments",
        nFirst: 2
      }
    }
  }
];

resulting API call:

  query ($nFirst: Int, $q: String) {
    search(query: "${q}", type: ISSUE, first: ${nFirst}){
      edges{
        node{
          ... on PullRequest{
            title
          }
        }
      }
    }
  }

Custom GraphQL query:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-github-api`,
    options: {
      token: "hunter2",
      variables: {},
      graphQLQuery: `
        query {
          repository(owner:"torvalds",name:"linux"){
            description
          }
        }
        `
    }
  }
];

resulting API call:

query {
  repository(owner: "torvalds", name: "linux") {
    description
  }
}

For more examples see gatsby-starter-github-portfolio.

Tips and Tricks

You’ll probably want to use valid GraphQL queries. To help you, GitHub has a Query Explorer with auto-completion.

Query Explorer

Changelog

  • v0.2.1 update dependencies
  • v0.2.0 provide raw github response
  • v0.1.5 document url option (for GitHub Enterprise users)
  • v0.1.4
    • Add tests
    • expose DEFAULT_QUERY by exporting it
  • v0.1.3
    • Change mediaType of exported node to be ignored by gatsby-transformer-json
    • prettify changelog of this file
  • v0.1.2 Updated yarn.lock to address github security warnings
  • v0.1.1 Updated Readme for easier usage
  • v0.1.0 Submit to Gatsby’s Plugin Library
  • v0.0.4 Update dev dependencies, add linting script to package.json
  • v0.0.3 Initial public release
© 2023 Gatsby, Inc.