README.lhs

# GitHub App Token

[![Hackage](https://img.shields.io/hackage/v/github-app-token.svg?style=flat)](https://hackage.haskell.org/package/github-app-token)
[![Stackage Nightly](http://stackage.org/package/github-app-token/badge/nightly)](http://stackage.org/nightly/package/github-app-token)
[![Stackage LTS](http://stackage.org/package/github-app-token/badge/lts)](http://stackage.org/lts/package/github-app-token)
[![CI](https://github.com/freckle/github-app-token/actions/workflows/ci.yml/badge.svg)](https://github.com/freckle/github-app-token/actions/workflows/ci.yml)

[Generate an installation access token for a GitHub App][docs]

[docs]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation

## Getting an AccessToken

<!--
```haskell
module Main (module Main) where

import Configuration.Dotenv qualified as Dotenv
import Control.Monad (when)
import Data.Traversable (for)
import GitHub.App.Token.Refresh
import System.Directory (doesFileExist)
import Test.Hspec qualified as Hspec
import Text.Markdown.Unlit ()
```
-->

```haskell
import Prelude

import Data.Aeson (FromJSON)
import Data.ByteString.Char8 qualified as BS8
import Data.Text (Text)
import Data.Text.Encoding (encodeUtf8)
import GHC.Generics (Generic)
import GitHub.App.Token
import Network.HTTP.Simple
import Network.HTTP.Types.Header (hAuthorization, hUserAgent)
import System.Environment

getAppToken :: IO AccessToken
getAppToken = do
  appId <- AppId . read <$> getEnv "GITHUB_APP_ID"
  privateKey <- PrivateKey . BS8.pack <$> getEnv "GITHUB_PRIVATE_KEY"
  installationId <- InstallationId . read <$> getEnv "GITHUB_INSTALLATION_ID"

  let creds = AppCredentials {appId, privateKey}
  generateInstallationToken creds installationId
```

## Using an AccessToken

```haskell
data Repo = Repo
  { name :: Text
  , description :: Text
  }
  deriving stock (Eq, Show, Generic)
  deriving anyclass FromJSON

getRepo :: AccessToken -> String -> IO Repo
getRepo token name = do
  req <- parseRequest $ "https://api.github.com/repos/" <> name
  resp <- httpJSON
    $ addRequestHeader hAuthorization ("Bearer " <> encodeUtf8 token.token)
    $ addRequestHeader hUserAgent "github-app-token/example"
    $ req

  pure $ getResponseBody resp
```

## Getting a Scoped AccessToken

By default, a token is created with repositories access and permissions as
defined in the installation configuration. Either of these can be changed by
using `generateInstallationTokenScoped`:

```haskell
getScopedAppToken :: IO AccessToken
getScopedAppToken = do
  appId <- AppId . read <$> getEnv "GITHUB_APP_ID"
  privateKey <- PrivateKey . BS8.pack <$> getEnv "GITHUB_PRIVATE_KEY"
  installationId <- InstallationId . read <$> getEnv "GITHUB_INSTALLATION_ID"

  let
    creds = AppCredentials {appId, privateKey}
    create = mempty
      { repositories = ["github-app-token"]
      , permissions = contents Read
      }

  generateInstallationTokenScoped create creds installationId
```

## Getting an AccessToken for an Owner

```haskell
getOwnerAppToken :: IO AccessToken
getOwnerAppToken = do
  appId <- AppId . read <$> getEnv "GITHUB_APP_ID"
  privateKey <- PrivateKey . BS8.pack <$> getEnv "GITHUB_PRIVATE_KEY"

  let creds = AppCredentials {appId, privateKey}
  generateOwnerToken creds $ Org "freckle"
```

## Getting a Self-Refreshing AccessToken

Installation tokens are good for one hour, after which point using them will
respond with `401 Unauthorized`. To avoid this, you can use the
`GitHub.App.Token.Refresh` module to maintain a background thread that refreshes
the token as necessary:

```haskell
getRepos :: [String] -> IO [Repo]
getRepos names = do
  ref <- refreshing getAppToken

  repos <- for names $ \name -> do
    token <- getRefresh ref
    getRepo token name

  cancelRefresh ref
  pure repos
```

<!--
```haskell
main :: IO ()
main = do
  isLocal <- doesFileExist ".env"
  when isLocal $ Dotenv.loadFile Dotenv.defaultConfig

  Hspec.hspec $ do
    Hspec.describe "Basic usage" $ do
      Hspec.it "works" $ do
        token <- getAppToken
        getRepo token "freckle/github-app-token"
          `Hspec.shouldReturn` Repo
            { name = "github-app-token"
            , description = "Generate an installation token for a GitHub App"
            }

    Hspec.describe "Scoped usage" $ do
      Hspec.it "works" $ do
        token <- getScopedAppToken
        getRepo token "freckle/github-app-token"
          `Hspec.shouldReturn` Repo
            { name = "github-app-token"
            , description = "Generate an installation token for a GitHub App"
            }

    Hspec.describe "By owner" $ do
      Hspec.it "works" $ do
        token <- getOwnerAppToken
        getRepo token "freckle/github-app-token"
          `Hspec.shouldReturn` Repo
            { name = "github-app-token"
            , description = "Generate an installation token for a GitHub App"
            }

    Hspec.describe "Self-refreshing tokens" $ do
      Hspec.it "works" $ do
        let
          names :: [String]
          names =
            [ "freckle/github-app-token"
            , "freckle/stack-action"
            , "freckle/stackctl"
            ]

        getRepos names `Hspec.shouldReturn`
          [ Repo {name="github-app-token", description = "Generate an installation token for a GitHub App"}
          , Repo {name="stack-action", description = "GitHub Action to build, test, and lint Stack-based Haskell projects"}
          , Repo {name="stackctl", description = "Manage CloudFormation Stacks through specifications"}
          ]
```
-->

---

[CHANGELOG](./CHANGELOG.md) | [LICENSE](./LICENSE)