lex-github 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c33c30330e8ac63765232cdb2b3534bfc3142232acf3cf4bde8b9e18935e5f49
-  data.tar.gz: aeeb6eb49d4cf8c77be0d6bda5afafed25c164b5c17579f6033e1b0ea8ceb1ff
+  metadata.gz: 528c32f26f0baa590aa8084482cf2c006633669ed182df0e2288198fb509deb4
+  data.tar.gz: 453260cf722e2b8463816e4b9227ac2e6c70996063f68886f062e9710b01eda0
 SHA512:
-  metadata.gz: 758a54fcae7dfec7ef44fbbc9311a71d324ad58b3645d6f487b699202595c44b55238adc7bd13c36e85b60fea1486b930d03dc50a9f9764393a4e27769003d3f
-  data.tar.gz: 6ffefdc158e27d4fc689d5e36ef6a8b7805054d4f30f4ae9d440737e5bcde98d2a4bd8170e1265d0fd036eefb18ff2b40b4a96a77625d6fa057c1f929659beb0
+  metadata.gz: 4060b46c5f83856954a7c49e542351558202f855fe0d471a1984d59522e4d178fe78c2bfcc58d8a254b52bff4e763ff3ec233b16a8d2046fbbeb2b44cf089f4c
+  data.tar.gz: 7d148064e9e9b5225589f6c0d73e30938bc2d56beea9d4f89f2cb0443a2cc03d71f48fbe0b14a8a74ff150e44c4e94450185877c2539127da9ca2daa99507e2a

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- GitHub App authentication (JWT generation, installation tokens, manifest flow)
+- OAuth delegated authentication (Authorization Code + PKCE, device code fallback)
+- Scope-aware credential resolution chain (8 sources, rate limit + scope fallback)
+- `ScopeRegistry` for caching credential-to-owner/repo authorization status
+- `CredentialFallback` Faraday middleware (transparent 403/429 retry with next credential)
+- `RateLimit` Faraday middleware with automatic credential exhaustion tracking
+- `ScopeProbe` Faraday middleware for passive scope learning from API responses
+- `Helpers::Cache` for two-tier API response caching (global Redis + local in-memory)
+- `Helpers::TokenCache` for token lifecycle management with per-installation keying
+- `App::Runners::Auth` (JWT generation, installation token exchange)
+- `App::Runners::Webhooks` (signature verification, event parsing, scope invalidation)
+- `App::Runners::Manifest` (GitHub App manifest flow)
+- `App::Runners::Installations` (list, get, suspend, unsuspend, delete)
+- `App::Runners::CredentialStore` (Vault persistence after manifest flow)
+- `OAuth::Runners::Auth` (authorize_url, exchange_code, refresh, device_code, revoke)
+- `Runners::Actions` (GitHub Actions workflow management)
+- `Runners::Checks` (check runs and check suites)
+- `Runners::Releases` (release and asset management)
+- `Runners::Deployments` (deployment and status management)
+- `Runners::RepositoryWebhooks` (programmatic webhook management)
+- `Helpers::CallbackServer` for standalone OAuth redirect handling
+- `Helpers::BrowserAuth` for browser-based OAuth with PKCE
+- `CLI::Auth` for `legion lex exec github auth login/status`
+- `CLI::App` for `legion lex exec github app setup`
+- `RateLimitError`, `AuthorizationError`, `ScopeDeniedError` error classes
+- `jwt` (~> 2.7) and `base64` (>= 0.1) runtime dependencies
+
+### Changed
+- `Helpers::Client` now uses scope-aware credential resolution (`owner:`, `repo:` context)
+- All existing runners forward `owner:` and `repo:` to `connection()` for scope-aware resolution
+- All existing runners now include `Helpers::Cache` for two-tier API response caching
+- `Client` class includes App and OAuth runner modules
+- Version bump to 0.3.0
+
+## [0.3.0] - 2026-03-30
+
+### Added
+- GitHub App authentication (JWT generation, installation tokens via `App::Runners::Auth`)
+- OAuth delegated user authentication (Authorization Code + PKCE, device code flow via `OAuth::Runners::Auth`)
+- GitHub App manifest flow for streamlined app registration (`App::Runners::Manifest`)
+- Webhook signature verification and event parsing (`App::Runners::Webhooks`)
+- 8-source credential resolution chain: Vault delegated → Settings delegated → Vault App → Settings App → Vault PAT → Settings PAT → GH CLI → ENV (`Helpers::Client`)
+- Rate limit fallback across credential sources with scope-aware skipping (`Helpers::ScopeRegistry`)
+- Token lifecycle management with expiry tracking and rate limit recording (`Helpers::TokenCache`)
+- Two-tier API response caching (global Redis + local in-memory) with configurable per-resource TTLs (`Helpers::Cache`)
+- `jwt` (~> 2.7) and `base64` (>= 0.1) runtime dependencies
+
 ## [0.2.5] - 2026-03-30
 
 ### Changed

data/CLAUDE.md

@@ -6,11 +6,11 @@
 
 ## Purpose
 
-Legion Extension that connects LegionIO to GitHub. Provides runners for interacting with the GitHub REST API covering repositories, issues, pull requests, users, organizations, gists, search, labels, comments, commits, branches, and file contents.
+Legion Extension that connects LegionIO to GitHub. Provides runners for interacting with the GitHub REST API covering repositories, issues, pull requests, users, organizations, gists, search, labels, comments, commits, branches, file contents, GitHub App authentication, OAuth delegated auth, and webhook handling.
 
 **GitHub**: https://github.com/LegionIO/lex-github
 **License**: MIT
-**Version**: 0.2.4
+**Version**: 0.3.0
 
 ## Architecture
 
@@ -29,40 +29,66 @@ Legion::Extensions::Github
 │   ├── Commits           # List, get, compare commits
 │   ├── Branches          # Create branches via Git Data API
 │   └── Contents          # Commit multiple files via Git Data API
+├── App/
+│   └── Runners/
+│       ├── Auth          # JWT generation, installation token exchange, list/get installations
+│       ├── Webhooks      # HMAC signature verification, event parsing
+│       ├── Manifest      # GitHub App manifest flow (generate, exchange code, manifest URL)
+│       └── Installations # Full installation management (list repos, suspend, delete)
+├── OAuth/
+│   └── Runners/
+│       └── Auth          # PKCE + Authorization Code, device code, refresh, revoke
 ├── Helpers/
-│   └── Client            # Faraday connection builder (GitHub API v3)
+│   ├── Client            # 8-source scope-aware credential resolution chain + Faraday builder
+│   ├── Cache             # Two-tier read-through/write-through API response caching
+│   ├── TokenCache        # Token lifecycle management (store, fetch, expiry, rate limits)
+│   └── ScopeRegistry     # Credential-to-scope authorization cache (org/repo level)
 └── Client                # Standalone client class (includes all runners)
 ```
 
+### Credential Resolution Chain (8 sources, in priority order)
+
+1. `resolve_vault_delegated` — OAuth user token from Vault (`github/oauth/delegated/token`)
+2. `resolve_settings_delegated` — OAuth user token from `Legion::Settings[:github][:oauth][:access_token]`
+3. `resolve_vault_app` — GitHub App installation token (requires cached token from `TokenCache`)
+4. `resolve_settings_app` — App token from settings (requires cached token)
+5. `resolve_vault_pat` — PAT from Vault (`github/token`)
+6. `resolve_settings_pat` — PAT from `Legion::Settings[:github][:token]`
+7. `resolve_gh_cli` — Token from `gh auth token` CLI command (cached 300s)
+8. `resolve_env` — `GITHUB_TOKEN` environment variable
+
+Rate-limited credentials are skipped. Scope-denied credentials (for a given owner/repo) are skipped.
+
 ## Dependencies
 
 | Gem | Purpose |
 |-----|---------|
 | `faraday` | HTTP client for GitHub REST API |
+| `jwt` (~> 2.7) | RS256 JWT generation for GitHub App authentication |
+| `base64` (>= 0.1) | PKCE code challenge computation |
+| `legion-cache` | Two-tier caching (global Redis + local in-memory) |
+| `legion-crypt` | Vault secret resolution for credentials |
+| `legion-settings` | Settings-based credential resolution |
 
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `lib/legion/extensions/github.rb` | Extension entry point, requires all runners |
-| `lib/legion/extensions/github/client.rb` | Standalone client class |
-| `lib/legion/extensions/github/helpers/client.rb` | Faraday connection builder |
-| `lib/legion/extensions/github/runners/repositories.rb` | Repo CRUD, branches, tags |
-| `lib/legion/extensions/github/runners/issues.rb` | Issue CRUD |
-| `lib/legion/extensions/github/runners/pull_requests.rb` | PR CRUD, merge, files, reviews |
-| `lib/legion/extensions/github/runners/users.rb` | User lookup, followers/following |
-| `lib/legion/extensions/github/runners/organizations.rb` | Org info, repos, members |
-| `lib/legion/extensions/github/runners/gists.rb` | Gist CRUD |
-| `lib/legion/extensions/github/runners/search.rb` | Search repos/issues/users/code |
-| `lib/legion/extensions/github/runners/labels.rb` | Label CRUD, add/remove on issues |
-| `lib/legion/extensions/github/runners/comments.rb` | Issue/PR comment CRUD |
-| `lib/legion/extensions/github/runners/commits.rb` | List, get, compare commits |
-| `lib/legion/extensions/github/runners/branches.rb` | Create branches via Git Data API |
-| `lib/legion/extensions/github/runners/contents.rb` | Commit multiple files via Git Data API |
+| `lib/legion/extensions/github.rb` | Extension entry point, requires all modules |
+| `lib/legion/extensions/github/client.rb` | Standalone client class (includes all runners) |
+| `lib/legion/extensions/github/helpers/client.rb` | Credential resolution chain + Faraday builder |
+| `lib/legion/extensions/github/helpers/cache.rb` | Two-tier API response caching |
+| `lib/legion/extensions/github/helpers/token_cache.rb` | Token lifecycle + rate limit tracking |
+| `lib/legion/extensions/github/helpers/scope_registry.rb` | Credential-to-scope authorization cache |
+| `lib/legion/extensions/github/app/runners/auth.rb` | JWT generation, installation tokens |
+| `lib/legion/extensions/github/app/runners/webhooks.rb` | Webhook signature verification, event parsing |
+| `lib/legion/extensions/github/app/runners/manifest.rb` | GitHub App manifest registration flow |
+| `lib/legion/extensions/github/app/runners/installations.rb` | Installation management |
+| `lib/legion/extensions/github/oauth/runners/auth.rb` | OAuth PKCE, device code, token refresh/revoke |
 
 ## Testing
 
-57 specs across 14 spec files.
+131 specs across 23 spec files (growing with each new runner).
 
 ```bash
 bundle install

data/README.md

@@ -1,6 +1,6 @@
 # lex-github
 
-GitHub integration for [LegionIO](https://github.com/LegionIO/LegionIO). Provides runners for interacting with the GitHub REST API including repositories, issues, pull requests, labels, comments, commits, users, organizations, gists, and search.
+GitHub integration for [LegionIO](https://github.com/LegionIO/LegionIO). Provides runners for interacting with the GitHub REST API including repositories, issues, pull requests, labels, comments, commits, users, organizations, gists, search, Actions workflows, checks, releases, deployments, webhooks, and full GitHub App + OAuth authentication.
 
 ## Installation
 
@@ -8,6 +8,62 @@ GitHub integration for [LegionIO](https://github.com/LegionIO/LegionIO). Provide
 gem install lex-github
 ```
 
+## Authentication
+
+### Personal Access Token (PAT)
+
+```ruby
+client = Legion::Extensions::Github::Client.new(token: 'ghp_your_token')
+```
+
+### GitHub App (JWT + Installation Token)
+
+```ruby
+# Set in Legion::Settings
+# github.app.app_id: '12345'
+# github.app.private_key_path: '/path/to/private-key.pem'
+# github.app.installation_id: '67890'
+
+client = Legion::Extensions::Github::Client.new
+# Credentials resolved automatically from settings
+```
+
+Or via Vault:
+```
+vault write secret/github/app/app_id value='12345'
+vault write secret/github/app/private_key value='-----BEGIN RSA PRIVATE KEY-----...'
+vault write secret/github/app/installation_id value='67890'
+```
+
+### OAuth Delegated (browser-based login)
+
+```bash
+# CLI login
+legion lex exec github auth login
+```
+
+```ruby
+# Programmatic (using the CLI::Auth mixin)
+auth = Object.new.extend(Legion::Extensions::Github::CLI::Auth)
+result = auth.login(client_id: 'Iv1.abc', client_secret: 'secret')
+# Opens browser → PKCE flow; token can be stored in Vault if Vault integration is configured
+```
+
+### Credential Resolution Chain
+
+lex-github resolves credentials automatically in priority order:
+
+1. Vault OAuth delegated token
+2. Settings OAuth access token
+3. Vault GitHub App installation token (auto-generates on miss)
+4. Settings GitHub App installation token
+5. Vault PAT
+6. Settings PAT (`github.token`)
+7. `gh` CLI token (`gh auth token`)
+8. `GITHUB_TOKEN` environment variable
+
+Rate-limited credentials are skipped automatically. Scope-denied credentials (`403`) are skipped for the specific owner/repo and retried with the next source.
+
 ## Standalone Usage
 
 ```ruby
@@ -28,117 +84,133 @@ client.create_issue(owner: 'octocat', repo: 'Hello-World', title: 'Bug report')
 client.list_pull_requests(owner: 'octocat', repo: 'Hello-World')
 client.create_pull_request(owner: 'octocat', repo: 'Hello-World', title: 'Fix', head: 'fix-branch', base: 'main')
 client.merge_pull_request(owner: 'octocat', repo: 'Hello-World', pull_number: 42)
-client.list_pull_request_reviews(owner: 'octocat', repo: 'Hello-World', pull_number: 42)
-
-# Labels
-client.list_labels(owner: 'octocat', repo: 'Hello-World')
-client.create_label(owner: 'octocat', repo: 'Hello-World', name: 'bug', color: 'd73a4a')
-client.add_labels_to_issue(owner: 'octocat', repo: 'Hello-World', issue_number: 1, labels: ['bug'])
-
-# Comments
-client.list_comments(owner: 'octocat', repo: 'Hello-World', issue_number: 1)
-client.create_comment(owner: 'octocat', repo: 'Hello-World', issue_number: 1, body: 'Looks good!')
-client.update_comment(owner: 'octocat', repo: 'Hello-World', comment_id: 42, body: 'Updated text')
-client.delete_comment(owner: 'octocat', repo: 'Hello-World', comment_id: 42)
-
-# Users
-client.get_authenticated_user
-client.get_user(username: 'octocat')
-
-# Organizations
-client.get_org(org: 'github')
-client.list_org_repos(org: 'github')
-
-# Gists
-client.list_gists
-client.create_gist(files: { 'hello.rb' => { content: 'puts "hello"' } })
-
-# Search
-client.search_repositories(query: 'ruby language:ruby')
-client.search_issues(query: 'bug label:bug')
+
+# GitHub Actions
+client.list_workflows(owner: 'octocat', repo: 'Hello-World')
+client.trigger_workflow(owner: 'octocat', repo: 'Hello-World', workflow_id: 'ci.yml', ref: 'main')
+client.get_workflow_run(owner: 'octocat', repo: 'Hello-World', run_id: 12345)
+
+# Check Runs (CI status)
+client.create_check_run(owner: 'octocat', repo: 'Hello-World', name: 'CI', head_sha: 'abc123')
+client.update_check_run(owner: 'octocat', repo: 'Hello-World', check_run_id: 1,
+                        status: 'completed', conclusion: 'success')
+
+# Releases
+client.list_releases(owner: 'octocat', repo: 'Hello-World')
+client.create_release(owner: 'octocat', repo: 'Hello-World', tag_name: 'v1.0.0')
+
+# Deployments
+client.create_deployment(owner: 'octocat', repo: 'Hello-World', ref: 'main', environment: 'production')
+client.create_deployment_status(owner: 'octocat', repo: 'Hello-World', deployment_id: 1, state: 'success')
+
+# Webhooks
+client.list_webhooks(owner: 'octocat', repo: 'Hello-World')
+client.create_webhook(owner: 'octocat', repo: 'Hello-World',
+                      config: { url: 'https://example.com/webhook', content_type: 'json' })
+
+# GitHub App
+jwt_token = client.generate_jwt(app_id: '12345', private_key: File.read('private-key.pem'))
+client.create_installation_token(jwt: jwt_token, installation_id: '67890')
+client.list_installations(jwt: jwt_token)
+
+# Webhook verification
+client.verify_signature(payload: request.body.read, signature: request.env['HTTP_X_HUB_SIGNATURE_256'],
+                        secret: 'webhook_secret')
 ```
 
 ## Functions
 
 ### Repositories
-- `list_repos` - List repositories for a user
-- `get_repo` - Get a single repository
-- `create_repo` - Create a new repository
-- `update_repo` - Update repository settings
-- `delete_repo` - Delete a repository
-- `list_branches` - List branches
-- `list_tags` - List tags
+- `list_repos`, `get_repo`, `create_repo`, `update_repo`, `delete_repo`, `list_branches`, `list_tags`
 
 ### Issues
-- `list_issues` - List issues for a repository
-- `get_issue` - Get a single issue
-- `create_issue` - Create a new issue
-- `update_issue` - Update an issue
-- `list_issue_comments` - List comments on an issue
-- `create_issue_comment` - Create a comment on an issue
+- `list_issues`, `get_issue`, `create_issue`, `update_issue`, `list_issue_comments`, `create_issue_comment`
 
 ### Pull Requests
-- `list_pull_requests` - List pull requests
-- `get_pull_request` - Get a single pull request
-- `create_pull_request` - Create a pull request
-- `update_pull_request` - Update a pull request
-- `merge_pull_request` - Merge a pull request
-- `list_pull_request_commits` - List commits on a PR
-- `list_pull_request_files` - List files changed in a PR
-- `list_pull_request_reviews` - List reviews on a PR
+- `list_pull_requests`, `get_pull_request`, `create_pull_request`, `update_pull_request`, `merge_pull_request`
+- `list_pull_request_commits`, `list_pull_request_files`, `list_pull_request_reviews`, `create_review`
 
 ### Labels
-- `list_labels` - List labels for a repository
-- `get_label` - Get a single label by name
-- `create_label` - Create a new label
-- `update_label` - Update a label
-- `delete_label` - Delete a label
-- `add_labels_to_issue` - Add labels to an issue
-- `remove_label_from_issue` - Remove a label from an issue
+- `list_labels`, `get_label`, `create_label`, `update_label`, `delete_label`
+- `add_labels_to_issue`, `remove_label_from_issue`
 
 ### Comments
-- `list_comments` - List comments on an issue or PR
-- `get_comment` - Get a single comment by ID
-- `create_comment` - Create a comment on an issue or PR
-- `update_comment` - Update a comment
-- `delete_comment` - Delete a comment
+- `list_comments`, `get_comment`, `create_comment`, `update_comment`, `delete_comment`
 
 ### Users
-- `get_authenticated_user` - Get the authenticated user
-- `get_user` - Get a user by username
-- `list_followers` - List followers
-- `list_following` - List following
+- `get_authenticated_user`, `get_user`, `list_followers`, `list_following`
 
 ### Organizations
-- `list_user_orgs` - List organizations for a user
-- `get_org` - Get an organization
-- `list_org_repos` - List repos in an organization
-- `list_org_members` - List organization members
+- `list_user_orgs`, `get_org`, `list_org_repos`, `list_org_members`
 
 ### Gists
-- `list_gists` - List gists
-- `get_gist` - Get a single gist
-- `create_gist` - Create a gist
-- `update_gist` - Update a gist
-- `delete_gist` - Delete a gist
+- `list_gists`, `get_gist`, `create_gist`, `update_gist`, `delete_gist`
 
 ### Search
-- `search_repositories` - Search repositories
-- `search_issues` - Search issues and PRs
-- `search_users` - Search users
-- `search_code` - Search code
+- `search_repositories`, `search_issues`, `search_users`, `search_code`
 
 ### Commits
-- `list_commits` - List commits on a repository
-- `get_commit` - Get a single commit by SHA
-- `compare_commits` - Compare two commits, branches, or tags
+- `list_commits`, `get_commit`, `compare_commits`
+
+### Branches
+- `create_branch`
+
+### Contents
+- `commit_files`
+
+### GitHub Actions
+- `list_workflows`, `get_workflow`, `list_workflow_runs`, `get_workflow_run`, `trigger_workflow`
+- `cancel_workflow_run`, `rerun_workflow`, `rerun_failed_jobs`
+- `list_workflow_run_jobs`, `download_workflow_run_logs`, `list_workflow_run_artifacts`
+
+### Checks
+- `create_check_run`, `update_check_run`, `get_check_run`
+- `list_check_runs_for_ref`, `list_check_suites_for_ref`, `get_check_suite`
+- `rerequest_check_suite`, `list_check_run_annotations`
+
+### Releases
+- `list_releases`, `get_release`, `get_latest_release`, `get_release_by_tag`
+- `create_release`, `update_release`, `delete_release`
+- `list_release_assets`, `delete_release_asset`
+
+### Deployments
+- `list_deployments`, `get_deployment`, `create_deployment`, `delete_deployment`
+- `list_deployment_statuses`, `create_deployment_status`, `get_deployment_status`
+
+### Repository Webhooks
+- `list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`
+- `ping_webhook`, `test_webhook`, `list_webhook_deliveries`
+
+### GitHub App Auth
+- `generate_jwt`, `create_installation_token`, `list_installations`, `get_installation`
+- `generate_manifest`, `exchange_manifest_code`, `manifest_url`
+- `verify_signature`, `parse_event`, `receive_event`
+
+### OAuth
+- `generate_pkce`, `authorize_url`, `exchange_code`, `refresh_token`
+- `request_device_code`, `poll_device_code`, `revoke_token`
+
+## Error Handling
+
+```ruby
+begin
+  client.get_repo(owner: 'org', repo: 'private-repo')
+rescue Legion::Extensions::Github::RateLimitError => e
+  puts "Rate limited, resets at: #{e.reset_at}"
+rescue Legion::Extensions::Github::ScopeDeniedError => e
+  puts "No credential authorized for #{e.owner}/#{e.repo}"
+rescue Legion::Extensions::Github::AuthorizationError => e
+  puts "All credentials exhausted: #{e.attempted_sources}"
+end
+```
 
 ## Requirements
 
 - Ruby >= 3.4
 - [LegionIO](https://github.com/LegionIO/LegionIO) framework (optional for standalone client usage)
-- GitHub personal access token or app token
 - `faraday` >= 2.0
+- `jwt` ~> 2.7 (for GitHub App authentication)
+- `base64` >= 0.1 (for OAuth PKCE)
 
 ## License
 

data/lex-github.gemspec

@@ -26,7 +26,9 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'base64', '>= 0.1'
   spec.add_dependency 'faraday', '>= 2.0'
+  spec.add_dependency 'jwt', '~> 2.7'
   spec.add_dependency 'legion-cache',     '>= 1.3.11'
   spec.add_dependency 'legion-crypt',     '>= 1.4.9'
   spec.add_dependency 'legion-data',      '>= 1.4.17'

data/lib/legion/extensions/github/app/actor/token_refresh.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Github
+      module App
+        module Actor
+          class TokenRefresh < Legion::Extensions::Actors::Every # rubocop:disable Legion/Extension/SelfContainedActorRunnerClass,Legion/Extension/EveryActorRequiresTime
+            def use_runner?    = false
+            def check_subtask? = false
+            def generate_task? = false
+
+            def time
+              45 * 60
+            end
+
+            # rubocop:disable Legion/Extension/ActorEnabledSideEffects
+            def enabled?
+              defined?(Legion::Extensions::Github::Helpers::TokenCache)
+            rescue StandardError => _e
+              false
+            end
+            # rubocop:enable Legion/Extension/ActorEnabledSideEffects
+
+            def manual
+              log.info('App::Actor::TokenRefresh: refreshing installation token')
+              settings = github_app_settings
+              return unless settings[:app_id] && settings[:private_key] && settings[:installation_id]
+
+              auth = Object.new.extend(Legion::Extensions::Github::App::Runners::Auth)
+              jwt_result = auth.generate_jwt(app_id: settings[:app_id], private_key: settings[:private_key])
+              return unless jwt_result[:result]
+
+              token_result = auth.create_installation_token(
+                jwt:             jwt_result[:result],
+                installation_id: settings[:installation_id]
+              )
+              return unless token_result.dig(:result, 'token')
+
+              token_cache.store_token(
+                token:      token_result[:result]['token'],
+                auth_type:  :app_installation,
+                expires_at: Time.parse(token_result[:result]['expires_at'])
+              )
+              log.info('App::Actor::TokenRefresh: installation token refreshed')
+            rescue StandardError => e
+              log.error("App::Actor::TokenRefresh: #{e.message}")
+            end
+
+            private
+
+            def github_app_settings
+              return {} unless defined?(Legion::Settings)
+
+              Legion::Settings[:github]&.dig(:app) || {}
+            rescue StandardError => _e
+              {}
+            end
+
+            def token_cache
+              Object.new.extend(Legion::Extensions::Github::Helpers::TokenCache)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/github/app/actor/webhook_poller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Github
+      module App
+        module Actor
+          class WebhookPoller < Legion::Extensions::Actors::Poll # rubocop:disable Legion/Extension/SelfContainedActorRunnerClass,Legion/Extension/EveryActorRequiresTime
+            def use_runner?    = false
+            def check_subtask? = false
+            def generate_task? = false
+
+            def time
+              60
+            end
+
+            # rubocop:disable Legion/Extension/ActorEnabledSideEffects
+            def enabled?
+              github_poll_settings[:owner] && github_poll_settings[:repo]
+            rescue StandardError => _e
+              false
+            end
+            # rubocop:enable Legion/Extension/ActorEnabledSideEffects
+
+            def manual
+              settings = github_poll_settings
+              owner = settings[:owner]
+              repo = settings[:repo]
+              return unless owner && repo
+
+              client = Legion::Extensions::Github::Client.new
+              return unless client.respond_to?(:list_events)
+
+              result = client.list_events(owner: owner, repo: repo)
+              events = result[:result]
+              return unless events.is_a?(Array)
+
+              events.each do |event|
+                publish_event(event)
+              end
+            rescue StandardError => e
+              log.error("App::Actor::WebhookPoller: #{e.message}")
+            end
+
+            private
+
+            def github_poll_settings
+              return {} unless defined?(Legion::Settings)
+
+              Legion::Settings[:github]&.dig(:webhook_poller) || {}
+            rescue StandardError => _e
+              {}
+            end
+
+            def publish_event(event)
+              Legion::Extensions::Github::App::Transport::Messages::Event.new(event).publish
+            rescue StandardError => e
+              log.warn("WebhookPoller#publish_event: #{e.message}")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/github/app/hooks/setup.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Github
+      module App
+        module Hooks
+          class Setup < Legion::Extensions::Hooks::Base # rubocop:disable Legion/Extension/HookMissingRunnerClass
+            mount '/setup/callback'
+
+            def self.runner_class
+              'Legion::Extensions::Github::App::Runners::Manifest'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/github/app/hooks/webhook.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Github
+      module App
+        module Hooks
+          class Webhook < Legion::Extensions::Hooks::Base # rubocop:disable Legion/Extension/HookMissingRunnerClass
+            mount '/webhook'
+
+            def self.runner_class
+              'Legion::Extensions::Github::App::Runners::Webhooks'
+            end
+          end
+        end
+      end
+    end
+  end
+end