Gatsby source plugin for getting access to GitHub projects.

WARNING: As of 4/5/2018, the GitHub Projects REST API is considered to be a “preview” release and is subject to breaking changes without notice. Those changes may make this plugin not work.

For the latest information, see the GitHub Projects API documentation.

Usage

Prerequisites

You will need to get a GitHub personal access token to authenticate with. You can generate one through the GitHub web interface at Settings > Developer settings > Personal access tokens.

Installation

npm install gatsby-source-github-projects

Configuration

In gatsby-config.js, modify your plugins array:

plugins: [
  {
    resolve: `gatsby-source-github-projects`,
    options: {
      organization: <YOUR ORGANIZATION NAME>,

      // This is the GitHub personal access token from above. We recommend
      // setting it as an environment variable.
      token: process.env.GH_TOKEN,

      // Array of project numbers to query. Omit this option to load all
      // projects (and their issues) for your organization.
      projects: [1, 3, 4],
    },
  },
  …
],

Data

This plugin traverses the organization’s GitHub projects and expands the results into source nodes for projects, columns, and cards.

All data from the REST API responses is returned as fields on the nodes, with snake_case keys converted to camelCase. The original GitHub id field for the source nodes is preserved as githubId. Consult the GitHub Projects API documentation for more information.

Hydrated fields

Fields are added for the expanded objects: GithubProject has a columns field that’s an array of GithubProjectColumn nodes. Likewise, GithubProjectColumn has a cards field of GithubProjectCard nodes.

If the GithubProjectCard references a GitHub issue through its content_url field, that’s expanded to an issue field on the GithubProjectCard.

Sample GraphQL query

You can use GraphiQL to explore all of the data available. Here’s a sample of some of what you can get:

{
  githubProject {
    name
    createdAt
    updatedAt
    columns {
      id
      name
      cards {
        id
        note
        creator {
          login
          htmlUrl
        }
        issue {
          number
          title
          htmlUrl
          state
          user {
            login
            htmlUrl
          }
          labels {
            name
            color
          }
          assignees {
            login
            htmlUrl
            avatarUrl
          }
        }
      }
    }
  }
}

Development

This package uses language features as of Node 8. We don’t transpile the source files for simplicity.

Right now there are no tests. Your best bet is to npm link this repo into CityOfBoston/github-project-export and see if that site works.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].