github-app-auth 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7de14445c693279f09a86e7e1cd7c349c492b30a532b0951d49aed52eec90a96
-  data.tar.gz: b9d44e07749d0e017430f7614d6250ad1370f185839a0ed778573d39a6046e25
+  metadata.gz: 5dfa01cb297c9e23c8f0342a92500065145151061ccf3d5ccc0c9a88f6882500
+  data.tar.gz: 4e320ac747cde80c1734b40d67463be810beadb303d08ed87ce35f461f1c6f0f
 SHA512:
-  metadata.gz: c10995031a23f2b0ee9b4fe6f6e5dbced77fe1fdcd9575d61f59de493a3d4b3190abff8212134e125d6e0bdb6cdc118e7a584141312372c0faa6aa8ef63b956f
-  data.tar.gz: 0db53d013d400c848debb9b5f38092128a8704d199947af608215a911d12bbf5586a945db23509c31692d1f4b232d22ec67afea1a4076e0fbe04f5c99006301f
+  metadata.gz: fb5af34f92a868bdfe6276e19784ae2f8366bee7df538e38aa279558f1038510485a295b714a266b9cc11f778968507316214c276565e3fc9c46b51cdee20015
+  data.tar.gz: 7c203243829d4d54557616f0d514f0ac4da37aff788846d6bfcc89253e4013a16ef6bad1710bf75441dfa7138e061a9a8a4274a92c3bca1f5cca3f12841e32f3

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.4.0
+  - remove deprecated app_* methods that were only repository installations
+  - change require to 'github_app_auth' when adding linter
+
+## 0.3.0
+  - deprecates app_* methods that were only repository installations
+  - adds methods to do organization, repository, and user installations
+
+## 0.2.0
+  - changed lib path to `github-app-auth` instead of `github/app/auth`
+
+## 0.1.0
+  - initial release with support for repository installation authentication

data/README.md

@@ -1,5 +1,8 @@
 # GitHub::App::Auth
 
+![Tests](https://github.com/hortoncd/github-app-auth/actions/workflows/tests.yml/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/github-app-auth.svg)](https://badge.fury.io/rb/github-app-auth)
+
 A gem to make (at least) some forms of GitHub App authentication easy.  It is built as an includable module, with the option of a class to
 instantiate if preferred.
 
@@ -22,7 +25,7 @@ Or install it yourself as:
 ## Usage
 
 ```
-require "github-app-auth"
+require "github_app_auth"
 ```
 
 Include the module in your class
@@ -67,14 +70,44 @@ See [the GitHub documentation](https://docs.github.com/en/apps/creating-github-a
 
 The examples are using the gem as an includable module, but can also be used with the available AuthClass class..
 
-Auth as an application installation for a repo and return an Octokit::Client.
+There are several methods of authenticating as an application installation.
+
+#### Organization Installation
+
+Auth as an application installation for an organization and return an Octokit::Client.
+```
+client = organization_installation_client("myorg")
+```
+
+Alternatively you can retrieve the token, and then set up your own GitHub client (Octokit or whatever you prefer) as needed.
+```
+token = organization_installation_token("myorg")
+client = Octokit::Client.new({ bearer_token: token, ... })
+```
+
+#### Repository Installation
+
+Auth as an application installation for a repository and return an Octokit::Client.
+```
+client = repository_installation_client("myaccount/myrepo")
+```
+
+Alternatively you can retrieve the token, and then set up your own GitHub client (Octokit or whatever you prefer) as needed.
+```
+token = repository_installation_token("myaccount/myrepo")
+client = Octokit::Client.new({ bearer_token: token, ... })
+```
+
+#### User Installation
+
+Auth as an application installation for a user and return an Octokit::Client.
 ```
-client = app_installation_client("myaccount/myrepo")
+client = user_installation_client("myuser")
 ```
 
 Alternatively you can retrieve the token, and then set up your own GitHub client (Octokit or whatever you prefer) as needed.
 ```
-token = app_instalation_token("myaccount/myrepo")
+token = user_installation_token("myuser")
 client = Octokit::Client.new({ bearer_token: token, ... })
 ```
 

data/lib/{github-app-auth → github_app_auth}/app.rb

@@ -1,12 +1,15 @@
+# frozen_string_literal: true
+
 require "jwt"
 require "openssl"
 require_relative "client"
 
 module GitHub
   module App
+    # GitHub App Authentication
     module Auth
       def app_client(options = {})
-        client(:bearer_token => app_token(options))
+        client(bearer_token: app_token(options))
       end
 
       # options: the following can be passed via the options hash.  if missing
@@ -32,19 +35,11 @@ module GitHub
       end
 
       def app_id(options = {})
-        if options[:github_app_id]
-          options[:github_app_id]
-        else
-          ENV["GITHUB_APP_ID"]
-        end
+        options[:github_app_id] || ENV["GITHUB_APP_ID"]
       end
 
       def app_private_key(options = {})
-        if options[:github_app_private_key]
-          options[:github_app_private_key]
-        else
-          ENV["GITHUB_APP_PRIVATE_KEY"]
-        end
+        options[:github_app_private_key] || ENV["GITHUB_APP_PRIVATE_KEY"]
       end
     end
   end

data/lib/github_app_auth/app_installation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module GitHub
+  module App
+    # GitHub App Installation Authentication
+    module Auth
+      def organization_installation_client(org, options = {})
+        client(bearer_token: organization_installation_token(org, options))
+      end
+
+      def organization_installation_token(org, options = {})
+        installation_token(:organization, org, options)
+      end
+
+      def repository_installation_client(repo, options = {})
+        client(bearer_token: repository_installation_token(repo, options))
+      end
+
+      def repository_installation_token(repo, options = {})
+        installation_token(:repository, repo, options)
+      end
+
+      def user_installation_client(user, options = {})
+        client(bearer_token: user_installation_token(user, options))
+      end
+
+      def user_installation_token(user, options = {})
+        installation_token(:user, user, options)
+      end
+
+      # Supported types are :organization, :repository, :user
+      def installation_token(type, name, options = {})
+        application_client(options)
+        installation = installation_by_type(type, name)
+
+        if installation.nil? || installation[:id].nil?
+          raise GitHub::App::Auth::InstallationError, "Could not find installation for #{type}: #{name}"
+        end
+
+        resp = application_client.create_app_installation_access_token(installation[:id])
+        if resp.nil? || resp[:token].nil?
+          raise GitHub::App::Auth::TokenError, "Could generate installation token for #{type}: #{name}"
+        end
+
+        resp[:token]
+      end
+
+      def installation_by_type(type, name)
+        case type
+        when :organization
+          application_client.find_organization_installation(name)
+        when :repository
+          application_client.find_repository_installation(name)
+        when :user
+          application_client.find_user_installation(name)
+        else
+          raise ArgumentError, "Unsupported installation type: #{type}"
+        end
+      end
+
+      def application_client(options = {})
+        @application_client ||= app_client(options)
+      end
+    end
+  end
+end

data/lib/{github-app-auth → github_app_auth}/client.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 require "octokit"
 
 module GitHub
   module App
+    # GitHub App client
     module Auth
       def client(options = {})
         Octokit::Client.new(options)

data/lib/{github-app-auth → github_app_auth}/version.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module GitHub
   module App
     module Auth
-      VERSION = "0.2.0"
+      VERSION = "0.4.0"
     end
   end
 end

data/lib/github_app_auth.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "github_app_auth/app"
+require "github_app_auth/app_installation"
+require "github_app_auth/version"
+
+module GitHub
+  module App
+    # GitHub App Authentication
+    module Auth
+      class Error < StandardError; end
+      class InstallationError < Error; end
+      class TokenError < Error; end
+
+      class AuthClass
+        include GitHub::App::Auth
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: github-app-auth
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chris Horton
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-05 00:00:00.000000000 Z
+date: 2023-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -59,14 +59,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- lib/github-app-auth.rb
-- lib/github-app-auth/app.rb
-- lib/github-app-auth/app_installation.rb
-- lib/github-app-auth/client.rb
-- lib/github-app-auth/version.rb
+- lib/github_app_auth.rb
+- lib/github_app_auth/app.rb
+- lib/github_app_auth/app_installation.rb
+- lib/github_app_auth/client.rb
+- lib/github_app_auth/version.rb
 homepage: https://github.com/hortoncd/github-app-auth
 licenses:
 - MIT
@@ -82,7 +83,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/github-app-auth/app_installation.rb

@@ -1,16 +0,0 @@
-module GitHub
-  module App
-    module Auth
-      def app_installation_client(repo, options = {})
-        client(bearer_token: app_installation_token(repo, options))
-      end
-
-      def app_installation_token(repo, options = {})
-        application_client = app_client
-        installation = application_client.find_repository_installation(repo)
-        resp = application_client.create_app_installation_access_token(installation[:id])
-        resp[:token]
-      end
-    end
-  end
-end

data/lib/github-app-auth.rb

@@ -1,13 +0,0 @@
-require "github-app-auth/app"
-require "github-app-auth/app_installation"
-require "github-app-auth/version"
-
-module GitHub
-  module App
-    module Auth
-      class AuthClass
-        include GitHub::App::Auth
-      end
-    end
-  end
-end