githubauth

README

go-githubauth

go-githubauth is a Go package that provides utilities for GitHub authentication, including generating and using GitHub App tokens and installation tokens.

Features

go-githubauth package provides implementations of the TokenSource interface from the golang.org/x/oauth2 package. This interface has a single method, Token, which returns an *oauth2.Token.

• Generate GitHub Application JWT Generating a jwt for a github app
• Obtain GitHub App installation tokens Authenticating as a GitHub App

This package is designed to be used with the golang.org/x/oauth2 package, which provides support for OAuth2 authentication.

Installation

To use go-githubauth in your project, you need to have Go installed. You can get the package via:

go get -u github.com/jferrl/go-githubauth

Usage

Usage with go-github and oauth2

package main

import (
 "context"
 "fmt"
 "os"
 "strconv"

 "github.com/google/go-github/v62/github"
 "github.com/jferrl/go-githubauth"
 "golang.org/x/oauth2"
)

func main() {
 privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY"))
 appID, _ := strconv.ParseInt(os.Getenv("GITHUB_APP_ID"), 10, 64)
 installationID, _ := strconv.ParseInt(os.Getenv("GITHUB_INSTALLATION_ID"), 10, 64)

 appTokenSource, err := githubauth.NewApplicationTokenSource(appID, privateKey)
 if err != nil {
  fmt.Println("Error creating application token source:", err)
  return
 }

 installationTokenSource := githubauth.NewInstallationTokenSource(installationID, appTokenSource)

 // oauth2.NewClient create a new http.Client that adds an Authorization header with the token.
 // Transport src use oauth2.ReuseTokenSource to reuse the token.
 // The token will be reused until it expires.
 // The token will be refreshed if it's expired.
 httpClient := oauth2.NewClient(context.Background(), installationTokenSource)

 githubClient := github.NewClient(httpClient)

 _, _, err = githubClient.PullRequests.CreateComment(context.Background(), "owner", "repo", 1, &github.PullRequestComment{
  Body: github.String("Awesome comment!"),
 })
 if err != nil {
  fmt.Println("Error creating comment:", err)
  return
 }
}

Generate GitHub Application Token

First of all you need to create a GitHub App and generate a private key.

To authenticate as a GitHub App, you need to generate a JWT. Generating a jwt for a github app

package main

import (
 "fmt"
 "os"
 "time"

 "github.com/jferrl/go-githubauth"
)

func main() {
 privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY"))
 appID, _ := strconv.ParseInt(os.Getenv("GITHUB_APP_ID"), 10, 64)

 tokenSource, err := githubauth.NewApplicationTokenSource(appID, privateKey, githubauth.WithApplicationTokenExpiration(5*time.Minute))
 if err != nil {
  fmt.Println("Error creating token source:", err)
  return
 }

 token, err := tokenSource.Token()
 if err != nil {
  fmt.Println("Error generating token:", err)
  return
 }

 fmt.Println("Generated token:", token.AccessToken)
}

Generate GitHub App Installation Token

To authenticate as a GitHub App installation, you need to obtain an installation token.

package main

import (
 "fmt"
 "os"
 "strconv"

 "github.com/jferrl/go-githubauth"
)

func main() {
 privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY"))
 appID, _ := strconv.ParseInt(os.Getenv("GITHUB_APP_ID"), 10, 64)
 installationID, _ := strconv.ParseInt(os.Getenv("GITHUB_INSTALLATION_ID"), 10, 64)

 appTokenSource, err := githubauth.NewApplicationTokenSource(appID, privateKey)
 if err != nil {
  fmt.Println("Error creating application token source:", err)
  return
 }

 installationTokenSource := githubauth.NewInstallationTokenSource(installationID, appTokenSource)

 token, err := installationTokenSource.Token()
 if err != nil {
  fmt.Println("Error generating installation token:", err)
  return
 }

 fmt.Println("Generated installation token:", token.AccessToken)
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Overview

Package githubauth provides utilities for GitHub authentication, including generating and using GitHub App tokens and installation tokens. The package is based on the go-github and golang.org/x/oauth2 libraries. It implements a set of TokenSource interfaces for generating GitHub App and installation tokens.

Index

• Constants
• func NewApplicationTokenSource(id int64, privateKey []byte, opts ...ApplicationTokenOpt) (oauth2.TokenSource, error)
• func NewInstallationTokenSource(id int64, src oauth2.TokenSource, opts ...InstallationTokenSourceOpt) oauth2.TokenSource
• type ApplicationTokenOpt
  • func WithApplicationTokenExpiration(expiration time.Duration) ApplicationTokenOpt
• type InstallationTokenSourceOpt
  • func WithContext(ctx context.Context) InstallationTokenSourceOpt
  • func WithEnterpriseURLs(baseURL, uploadURL string) InstallationTokenSourceOpt
  • func WithHTTPClient(client *http.Client) InstallationTokenSourceOpt
  • func WithInstallationTokenOptions(opts *github.InstallationTokenOptions) InstallationTokenSourceOpt

Constants

const (
	// DefaultApplicationTokenExpiration is the default expiration time for the GitHub App token.
	// The expiration time of the JWT, after which it can't be used to request an installation token.
	// The time must be no more than 10 minutes into the future.
	DefaultApplicationTokenExpiration = 10 * time.Minute
)

Functions

func NewApplicationTokenSource

func NewApplicationTokenSource(id int64, privateKey []byte, opts ...ApplicationTokenOpt) (oauth2.TokenSource, error)

NewApplicationTokenSource creates a new GitHub App token source using the provided application ID and private key. Functional options can be passed to customize the token source.

func NewInstallationTokenSource

func NewInstallationTokenSource(id int64, src oauth2.TokenSource, opts ...InstallationTokenSourceOpt) oauth2.TokenSource

NewInstallationTokenSource creates a new GitHub App installation token source using the provided installation ID and token source. Functional options can be passed to customize the installation token source.

Types

type ApplicationTokenOpt

type ApplicationTokenOpt func(*applicationTokenSource)

ApplicationTokenOpt is a functional option for ApplicationTokenSource.

func WithApplicationTokenExpiration

func WithApplicationTokenExpiration(expiration time.Duration) ApplicationTokenOpt

WithApplicationTokenExpiration sets the expiration for the GitHub App token. The expiration time of the JWT must be no more than 10 minutes into the future and greater than 0. If the provided expiration is invalid, the default expiration is used.

type InstallationTokenSourceOpt

type InstallationTokenSourceOpt func(*installationTokenSource)

InstallationTokenSourceOpt is a functional option for InstallationTokenSource.

func WithContext

func WithContext(ctx context.Context) InstallationTokenSourceOpt

WithContext sets the context for the GitHub App installation token source.

func WithEnterpriseURLs

func WithEnterpriseURLs(baseURL, uploadURL string) InstallationTokenSourceOpt

WithEnterpriseURLs sets the base URL and upload URL for the GitHub App installation token source. This should passed after WithHTTPClient to ensure the HTTP client is updated with the new URLs. If the provided URLs are invalid, the default GitHub URLs are used.

func WithHTTPClient

func WithHTTPClient(client *http.Client) InstallationTokenSourceOpt

WithHTTPClient sets the HTTP client for the GitHub App installation token source.

func WithInstallationTokenOptions

func WithInstallationTokenOptions(opts *github.InstallationTokenOptions) InstallationTokenSourceOpt

WithInstallationTokenOptions sets the options for the GitHub App installation token.