Merge pull request #4 from hortoncd/add_other_installation_types

Add other installation types rather than just repository

Author: hortoncd

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 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

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    github-app-auth (0.2.0)
+    github-app-auth (0.3.0)
       jwt (~> 2.7)
       octokit (~> 6.1)
       openssl (~> 3.1)

README.md

@@ -67,14 +67,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("myorg")
 ```
 
 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("myorg")
 client = Octokit::Client.new({ bearer_token: token, ... })
 ```
 

github-app-auth.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = "#{spec.homepage}"
   spec.metadata["changelog_uri"] = "#{spec.homepage}"
 
-  spec.files = Dir.glob("lib/**/*") + %w[CODE_OF_CONDUCT.md LICENSE.txt README.md]
+  spec.files = Dir.glob("lib/**/*") + %w[CHANGELOG.md CODE_OF_CONDUCT.md LICENSE.txt README.md]
   spec.require_paths = ["lib"]
   spec.add_dependency "jwt", "~> 2.7"
   spec.add_dependency "octokit", "~> 6.1"

lib/github-app-auth.rb

@@ -5,6 +5,10 @@
 module GitHub
   module App
     module Auth
+      class Error < StandardError; end
+      class InstallationError < Error; end
+      class TokenError< Error; end
+
       class AuthClass
         include GitHub::App::Auth
       end

lib/github-app-auth/app_installation.rb

@@ -1,14 +1,65 @@
 module GitHub
   module App
     module Auth
+      # legacy support because original only supported repo
       def app_installation_client(repo, options = {})
+        puts "DEPRECATED: app_installation_client will be removed in v0.4.0, use repository_installation_client instead"
         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)
+        puts "DEPRECATED: app_installation_token will be removed in v0.4.0, use repository_installation_token instead"
+        installation_token(:repository, repo, options)
+      end
+
+      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 = app_client(options)
+        installation = begin
+          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
+
+        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
     end

lib/github-app-auth/version.rb

@@ -1,7 +1,7 @@
 module GitHub
   module App
     module Auth
-      VERSION = "0.2.0"
+      VERSION = "0.3.0"
     end
   end
 end

spec/github/app/auth/app_installation_spec.rb

@@ -4,34 +4,176 @@
   # Use the class we provide to test the module
   subject { GitHub::App::Auth::AuthClass.new }
 
-  describe ".app_installation_client" do
-    let(:repo) { "test/test-repo" }
+  let(:github_client) { instance_double(Octokit::Client) }
+  let(:installation_id) { "54321" }
+  let(:org) { "test-org" }
+  let(:repo) { "test/test-repo" }
+  let(:token) { "test-token" }
+  let(:user) { "test-user" }
 
-    it "returns an Octokit::Client authorized to an app" do
+  describe ".app_installation_client" do
+    it "returns an Octokit::Client authorized to an app installation" do
       expect(subject).to receive(:app_installation_token)
-                               .with(repo, {})
-                               .and_return("test-token")
+                     .with(repo, {})
+                     .and_return("test-token")
       expect(subject.app_installation_client(repo)).to be_kind_of(Octokit::Client)
     end
+
+    it "returns an Octokit::Client authorized to an app installation" do
+      expect(subject).to receive(:app_installation_token)
+                     .with(repo, {})
+                     .and_return("test-token")
+      expected_output = "DEPRECATED: app_installation_client will be removed in v0.4.0, use repository_installation_client instead\n"
+      expect { subject.app_installation_client(repo) }.to output(expected_output).to_stdout
+    end
   end
 
   describe ".app_installation_token" do
-    let(:github_client) { instance_double(Octokit::Client) }
+    it "returns a JWT token for for an app" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: token)
+      expect(subject.app_installation_token(repo)).to eq(token)
+    end
 
-    let(:installation_id) { "54321" }
+    it "outputs a deprecation notice" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: token)
+      expected_output = [
+        "DEPRECATED: app_installation_client will be removed in v0.4.0, use repository_installation_client instead",
+        "DEPRECATED: app_installation_token will be removed in v0.4.0, use repository_installation_token instead\n"
+      ].join("\n")
+      expect { subject.app_installation_client(repo) }.to output(expected_output).to_stdout
+    end
+  end
 
-    let(:repo) { "test/test-repo" }
+  describe ".organization_installation_client" do
+    it "returns an Octokit::Client authorized to an organization installation" do
+      expect(subject).to receive(:organization_installation_token)
+                     .with(org, {})
+                     .and_return(token)
+      expect(subject.organization_installation_client(org)).to be_kind_of(Octokit::Client)
+    end
+  end
 
+  describe ".organization_installation_token" do
     it "returns a JWT token for for an app" do
       expect(subject).to receive(:app_client)
-                               .and_return(github_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_organization_installation)
+                           .with(org)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: token)
+      expect(subject.organization_installation_token(org)).to eq("test-token")
+    end
+  end
+
+  describe ".repository_installation_client" do
+    it "returns an Octokit::Client authorized to a repo installation" do
+      expect(subject).to receive(:repository_installation_token)
+                     .with(repo, {})
+                     .and_return(token)
+      expect(subject.repository_installation_client(repo)).to be_kind_of(Octokit::Client)
+    end
+  end
+
+  describe ".repository_installation_token" do
+    it "returns a JWT token for for a repo" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: token)
+      expect(subject.repository_installation_token(repo)).to eq(token)
+    end
+  end
+
+  describe ".user_installation_client" do
+    it "returns an Octokit::Client authorized to a user installation" do
+      expect(subject).to receive(:user_installation_token)
+                     .with(user, {})
+                     .and_return(token)
+      expect(subject.user_installation_client(user)).to be_kind_of(Octokit::Client)
+    end
+  end
+
+  describe ".user_installation_token" do
+    it "returns a JWT token for for a user" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_user_installation)
+                           .with(user)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: token)
+      expect(subject.user_installation_token(user)).to eq(token)
+    end
+  end
+
+  describe ".installation_token" do
+    it "raises an error for unsupported installation type" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect { subject.installation_token("unsupported", {}) }.to raise_error(ArgumentError)
+    end
+
+    it "raises an error if no installation id is found" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(token: nil)
+      expect { subject.installation_token(:repository, repo, {}) }.to raise_error(GitHub::App::Auth::InstallationError)
+    end
+
+    it "raises an error if no installation is returned" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(nil)
+      expect { subject.installation_token(:repository, repo, {}) }.to raise_error(GitHub::App::Auth::InstallationError)
+    end
+
+    it "raises an error if no token is returned" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
+      expect(github_client).to receive(:find_repository_installation)
+                           .with(repo)
+                           .and_return(id: installation_id)
+      expect(github_client).to receive(:create_app_installation_access_token)
+                           .with(installation_id)
+                           .and_return(token: nil)
+      expect { subject.installation_token(:repository, repo, {}) }.to raise_error(GitHub::App::Auth::TokenError)
+    end
+
+    it "raises an error if resp is nil for token creation" do
+      expect(subject).to receive(:app_client)
+                     .and_return(github_client)
       expect(github_client).to receive(:find_repository_installation)
-                           .with("test/test-repo")
+                           .with(repo)
                            .and_return(id: installation_id)
       expect(github_client).to receive(:create_app_installation_access_token)
                            .with(installation_id)
-                           .and_return(token: "test-token")
-      expect(subject.app_installation_token(repo)).to eq("test-token")
+                           .and_return(nil)
+      expect { subject.installation_token(:repository, repo, {}) }.to raise_error(GitHub::App::Auth::TokenError)
     end
   end
 end