Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

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

  • v1.0.0 add support for gatsby v3. Remove support for older versions of gatsby
  • 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
© 2024 Gatsby, Inc.