BSD-3-Clause licensed by Mike Burns, John Wiegley, Oleg Grenrus
Maintained by Andreas Abel
This version can be pinned in stack with:github-0.29@sha256:1a6f082a24df02e38a2de548ce72654537b3aee5383cb57dce5d3ef6386c6752,7939

Module documentation for 0.29

GitHub

Hackage version github on Stackage Nightly Stackage LTS version Haskell-CI

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:

Build-depends:       github

Or from the command line:

cabal v1-install github

Example Usage

See the samples in the samples/ directory.

Note: some samples might be outdated.

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 which 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 GitHub (github')
import qualified GitHub

main :: IO ()
main = do
    possibleUsers <- github' GitHub.usersFollowingR "phadej"
    T.putStrLn $ either (("Error: " <>) . pack . show)
                        (foldMap ((<> "\n") . formatUser))
                        possibleUsers

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

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-2019 Oleg Grenrus.

Available under the BSD 3-clause license.

Alternative

Library github-rest also provides an interface to the GitHub API. It compares itself to github here: https://github.com/LeapYear/github-rest#comparison-to-other-libraries

Changes

Changes for 0.29

2023-06-24, Andreas Abel, Midsommar edition

  • Support for the GitHub Actions API (PR #459):

    • New endpoint modules GitHub.EndPoints.Actions.Artifacts, .Cache, .Secrets, .Workflows, .WorkflowRuns, .WorkflowJobs.
    • Matching data structure modules GitHub.Data.Actions.*.
  • Add field issueStateReason of type Maybe IssueStateReason to Issue with possible values completed, not_planned and reopened (PR #496).

Tested with GHC 7.8 - 9.6.2

Changes for 0.28.0.1

2022-07-23, Andreas Abel

Tested with GHC 7.8 - 9.4.1 alpha3

  • Drop unused dependency vector-instances.
  • Allow latest: aeson-2.1, mtl-2.3, vector-0.13, transformers-0.6.

Changes for 0.28

2022-04-30, Andreas Abel, Valborg edition

Tested with GHC 7.8 - 9.2.2

  • Add constructors to IssueRepoMod that allow filtering issues by milestone, assignee, creator, mentioned user: GitHub.Data.Options.options{Milestone,Assignee,Creator,Mentioned} (PR #470)

  • Add permissions field to Repo. This adds record RepoPermissions and field Repo.repoPermissions in module GitHub.Data.Repos. (PR #476)

  • Add unwatch request GitHub.Endpoints.Activity.Watching.unwatchRepoR (PR #473)

Breaking change:

  • Make searches paginated (PR #474):
    • Adds record GitHub.Data.Repos.CodeSearchRepo.
    • Adds argument FetchCount to GitHub.Endpoints.Search.search{Repos,Code,Issues,Users}R.

Changes for 0.27

2021-10-10, Oleg Grenrus

  • Add vector of SimpleTeam in “requested_teams” field of PullRequest #453
  • Add endpoint to create gist #455
  • Update RepoWebhookEvent #461
  • PullRequest Reviews may not have submitted_at field #450

Changes for 0.26

2020-05-26, Oleg Grenrus

  • Generalize PagedQuery to allow its reuse by preview github APIs #439
  • Add endpoint for listing organizations outside collaborators #445
  • Add endpoint for users search #444
  • Make repoWebhookResponseStatus optional #436
  • Teams improvements #417
  • Add deleteReference endpoint #388

Changes for 0.25

2020-02-18, Oleg Grenrus

  • Add executeRequestWithMgrAndRes #421
  • Add limitsFromHttpResponse #421
  • Add label descriptions #418
  • Add “draft” option to mergeable state #431
  • Use IssueNumber in editIssueR and issueR #429
  • Manage orgs in GitHub Enterprise #420
  • Add support for collaborator permission endpoint #425
  • Add support for the comment reply endpoint #424
  • Organise exports in GitHub #430

Changes for 0.24

2019-11-27, Oleg Grenrus

Major change: Introduce github n-ary combinator to hoist ... -> Request rw res into ... -> IO (Either Error res) (i.e. n-ary executeRequest). With that in place drop .. -> IO (Either Error res) functions.

This reduces symbol bloat in the library. #415

  • Remove double withOpenSSL #414
  • Pull requests reviews API uses issue number #409
  • Update Repo, NewRepo and EditRepo data types #407

Changes for 0.23

2019-10-01, Oleg Grenrus

  • Escape URI paths #404
  • Add OwnerBot to OwnerType #399
  • Make File.fileSha optional #392
  • Update User-Agent to contain up to date version #403 #394

Changes for 0.22

2019-05-31, Oleg Grenrus

  • Type-class for various auth methods #365
  • Throw on non-200 responses #350
  • Add extension point for (preview) media types #370
  • Add missing webhook event types #359
  • Add invitation endpoint #360
  • Add notifications endpoints #324
  • Add ssh keys endpoints #363
  • Case insensitive enum parsing #373
  • Don’t try parse unitary responses #377
  • Update dependencies #364 #368 #369
  • Documentation improvements #357

Changes for 0.21

2019-02-18, Oleg Grenrus

  • Refactor Request type. #349
  • Allow http-client-0.6 #344
  • Change to use cryptohash-sha1 (cryptohash was used before)
  • Add Create milestone endpoints #337
  • Make fileBlobUrl and fileRawUrl optional #339 #340
  • Add organizationsR to request user organizations #345
  • Add updateMilestoneR, deleteMilestoneR #338
  • Allow multiple assignees in NewIssue and EditIssue #336
  • Add pullRequestPatchR and pullRequestDiffR #325

Changes for 0.20

2018-09-26, Oleg Grenrus

  • Add ratelimit endpoint #315
  • Add some deployment endoints #330
  • Add webhook installation events #329
  • Tighten lower bounds (also remove aeson-compat dep) #332

Changes for 0.19

2018-02-19, Oleg Grenrus

  • Fix issue event type enumeration #301
  • Include label info in IssueEvent #302
  • Fix ShowRepo example #306
  • Add “Get archive link” API #307
  • Make “repo” in PullRequestCommit nullable (repository can be gone) #311
  • Add read-only emails endpoint #313
  • Organisation membership API #312
  • Fix isPullRequestMerged and other boolean responses #312
  • Add behind pull request mergeable state #308
  • Add list organisation invitations endpoint

Changes for 0.18

2017-11-10, Oleg Grenrus

  • Endpoints for deleting issue comments. #294
  • Endpoints for (un)starring gists. #296
  • Add archived field to Repo. #298
  • Update dependencies. #295
  • Add Statuses endpoints. #268
  • Add requested reviewers field to pull request records. #292

Changes for 0.17.0

2017-09-26, Oleg Grenrus

  • Add Ord Request instance
  • Repository contents
  • Repository starring endpoints
  • Pull Request review endpoints

Changes for 0.16.0

2017-07-24, Oleg Grenrus

  • Add support for mergeable_state = "blocked".
  • Fix HTTP status code of merge PR
  • Supports newest versions of dependencies
  • user events
  • release endpoints
  • forkExistingRepo

Changes for 0.15.0

2016-11-04, Oleg Grenrus

  • 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

2016-02-02, Oleg Grenrus

  • 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

2016-01-25, Oleg Grenrus

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.

Releases without changelog

Version Date Uploader
0.13.2 2015-04-26 John Wiegley
0.13.1 2014-12-01 César López-Natarén
0.13 2014-11-09 César López-Natarén
0.12 2014-11-09 César López-Natarén
0.11.1 2014-09-07 César López-Natarén
0.11.0 2014-08-25 César López-Natarén
0.10.0 2014-08-18 César López-Natarén
0.9 2014-07-31 John Wiegley
0.8 2014-05-02 John Wiegley
0.7.4 2014-01-22 John Wiegley
0.7.3 2013-12-21 John Wiegley
0.7.2 2013-12-02 John Wiegley
0.7.1 2013-08-08 John Wiegley
0.7.0 2013-04-26 John Wiegley
0.6.0 2013-04-12 John Wiegley

Changes for 0.5.0:

2013-02-05, Mike Burns

  • 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:

2013-01-14, Mike Burns

  • 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:

2012-06-26, Mike Burns

  • Use http-conduit version 1.4.1.10.

Changes for 0.3.0:

2012-06-10, Mike Burns

  • 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:

2012-02-16, Mike Burns

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

Changes for 0.2.0:

2012-02-15, Mike Burns

  • 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.