github

Access to the GitHub API, v3.

https://github.com/phadej/github

Version on this page:0.15.0@rev:3
LTS Haskell 23.4:0.29@rev:6
Stackage Nightly 2024-12-09:0.29@rev:6
Latest on Hackage:0.29@rev:6

See all snapshots github appears in

BSD-3-Clause licensed by Mike Burns, John Wiegley, Oleg Grenrus
Maintained by Oleg Grenrus
This version can be pinned in stack with:github-0.15.0@sha256:50040d65a00580e8ff6bfc642b4a99fa722893692908c062629de88d2b3ea20f,6451

Module documentation for 0.15.0

Github

Build Status Hackage Stackage LTS 5 Stackage Nightly

The Github API v3 for Haskell.

Some functions are missing; these are functions where the Github API did not work as expected. The full Github API is in beta and constantly improving.

Installation

In your project’s cabal file:

-- Packages needed in order to build this package.
Build-depends:       github

Or from the command line:

cabal install github

Example Usage

See the samples in the samples/ directory.

Documentation

For details see the reference documentation on Hackage.

Each module lines up with the hierarchy of documentation from the Github API.

Request functions (ending with R) construct a data type with can be executed in IO by executeRequest functions. They are all listed in the root GitHub module.

IO functions produce an IO (Either Error a), where a is the actual thing you want. You must call the function using IO goodness, then dispatch on the possible error message. Here’s an example from the samples:

Many function have samples under samples/ directory.

{-# LANGUAGE NoImplicitPrelude #-}
{-# LANGUAGE OverloadedStrings #-}

import Prelude.Compat

import Data.Text         (Text, pack)
import Data.Text.IO as T (putStrLn)
import Data.Monoid       ((<>))

import qualified GitHub.Endpoints.Users.Followers as GitHub

main :: IO ()
main = do
    possibleUsers <- GitHub.usersFollowing "mike-burns"
    T.putStrLn $ either (("Error: " <>) . pack . show)
                        (foldMap ((<> "\n") . formatUser))
                        possibleUsers

formatUser :: GitHub.SimpleUser -> Text
formatUser = GitHub.untagName . GitHub.simpleUserLogin

Test setup

To run integration part of tests, you’ll need github access token Token is needed, because unauthorised access is highly limited. It’s enough to add only basic read access for public information.

With travis encrypt --org --repo yournick/github "GITHUB_TOKEN=yourtoken" command you get a secret, you can use in your travis setup to run the test-suite there.

Contributions

Please see CONTRIBUTING.md for details on how you can help.

Copyright

Copyright 2011-2012 Mike Burns. Copyright 2013-2015 John Wiegley. Copyright 2016 Oleg Grenrus.

Available under the BSD 3-clause license.

Changes

Changes for 0.15.0

  • Reworked PullRequest (notably pullRequestsFor)
  • Reworked PR and Issue filtering
  • GHC-8.0.1 support
  • Change repoMasterBranch to repoDefaultBranch in Repo
  • Add listTeamReposR
  • Add myStarredAcceptStarR
  • Add HeaderQuery to Request
  • Add Hashable Auth instance
  • Add mkUserId, mkUserName, fromUserId, fromOrganizationId
  • Add ‘userIssuesR’
  • Add ‘organizationIssuesR’
  • Make teamName :: Text amnd teamSlug :: Name Team in both: Team and SimpleTeam
  • Refactor ‘Request’ structure
  • Added multiple issue assignees
  • Preliminary support for repository events: repositoryEventsR
  • Support for adding repository permissions to the team
  • Remove ‘simpleUserType’, it was always the same.

See git commit summary

Changes for 0.14.1

  • Add membersOfWithR, listTeamMembersR
  • Add related enums: OrgMemberFilter, OrgMemberRole, TeamMemberRole
  • Add Enum and Bounded instances to Privacy, Permission, RepoPublicity
  • Don’t require network access for search tests

Changes for 0.14.0

Large API changes:

  • Use Text and Vector in place of String and [].
  • Use Name and Id tagged types for names and identifiers.
  • Make detailed structures un-prefixed, simple ones prefixed with Simple. Example: Team and SimpleTeam.
  • Decouple request creation from execution (*R and executeRequest* functions).
  • Add Binary instances for all data
  • GithubOwner is a newtype of Either User Organization. There’s still SimpleOwner.

Changes for 0.5.0:

  • OAuth.
  • New function: Github.Repos.organizationRepo, to get the repo for a specific organization.
  • Introduce a new newRepoAutoInit flag to NewRepo, for whether to initialize a repo while creating it.
  • Relax the attoparsec version requirements.
  • The above by John Wiegley.

Changes for 0.4.1:

  • Stop using the uri package.
  • Use aeson version 0.6.1.0.
  • Use attoparsec version 0.10.3.0.
  • Use http-conduit over 1.8.
  • Use unordered-containers between 0.2 and 0.3.

Changes for 0.4.0:

  • Use http-conduit version 1.4.1.10.

Changes for 0.3.0:

  • Re-instantiate the Blobs API.
  • repoDescription1 and repoPushedAt are a Maybe GithubDate.
  • Add deleteRepo, editRepo, and createRepo.
  • Private gists, issues, organizations, pull requests, and users.
  • Lock down tls and tls-extra instead of keeping up with the ever-changing http-conduit package.
  • Features by Pavel Ryzhov and Simon Hengel.

Changes for 0.2.1:

  • Expand the unordered-containers dependency to anything in 0.1.x .

Changes for 0.2.0:

  • milestoneDueOn and repoLanguage are now Maybe types.
  • Introduce GithubOwner as the sum type for a GithubUser or GithubOrganization. Everything that once produced a GithubUser now produces a GithubOwner. All record accessors have changed their names
  • Similar to GithubOwner, introduce DetailedOwner, which can be a DetailedUser or a DetailedOrganization. All record accessors have changed their names
  • An HTTPConnectionError now composes SomeException instead of IOException. All exceptions raised by the underlying http-conduit library are encapulated there.
  • The githubIssueClosedBy function now produces a Maybe GithubOwner.
  • Remove the Blobs API, as it is broken upstream.
  • Bugs found and squashed thanks to Joey Hess and Simon Hengel.