onair-cli 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6929334a2f930a5e7e05e43067c8442ae9b85d3dc9967c960c4ff9c0e34ebc7
-  data.tar.gz: 4f029777e9e3ee5aabc3977ad930ba2cf35d82a4c5e9c76a0995197d250ae389
+  metadata.gz: 863a5cc9f6796e525c125ed320542a3e4d8b076b5a6a5660744c9136ead84cc2
+  data.tar.gz: c771ccb2bd0c72fcf075e48c829556de327ad4dc3b2527db4ca0b5b0ee763e34
 SHA512:
-  metadata.gz: c85de1face07ebb3c04cadc6001ac5e92edff4b3632f87f1f79158f212c3063761ee6efdfdf69709bfe09251b0d0c5271dec5aaa38291b84b3cc523f705d5f3e
-  data.tar.gz: 3325a141acd7f90491a2b9c547097acbd68b1eba14d72462d518e61e564923a6c5e332263eab7403f99a751bb7278acf47a0d98d2f010492267796ad797e0538
+  metadata.gz: e8016ad8033b28ec15e73cdae96b1b0e94562a4bc28226dfd5b556c8a3a24dc713106b9f8fe5b3c3881c330e71f9a297c768c0a2c9175114eccfdd4cc4eae76d
+  data.tar.gz: f78628cf04574876bc46322b9eba02d8f252152c90d7bc75bd032041be4a9f3741f6f3619d01693a3f9f098e18fcd64c6e14e722c27e65d51640a1bf5e7660e7

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-02
+
+- GitHub Deployments: `platform: github_deployments` reads one environment's
+  deployments (`environment:`, default `production`) through the GitHub API
+  with the `gh` token, so anyone who can read the repo sees what is deployed
+  without host access. The newest successful deployment is Deployed, a newer
+  in-flight one is Pending with its commit, and a newer failed one is Failed.
+  It reports what CI recorded, not what the host runs.
+- `app:` is required only by the platforms that use it. `--json` gains an
+  `environment` field, and `deployed` is `null` when nothing successful is deployed yet.
+
 ## [0.4.0] - 2026-11-02
 
 - Dokku: `platform: dokku` with a `host:` reads the running commit from the

data/README.md

@@ -28,6 +28,8 @@ case.
 ## Principles
 
 1. **Truth over convenience.** What's *running*, not what was built last.
+   The one exception is opt-in: `platform: github_deployments` reports what
+   CI recorded, not what the host runs (see [GitHub Deployments](#github-deployments)).
 2. **Zero runtime dependencies.** Ruby stdlib only.
 3. **Read-only.** Never deploys, never rolls back, never writes to git except
    an explicit lazy `git fetch`.
@@ -123,6 +125,65 @@ another way (`git:from-image`, `git:sync`) shows the deploy source instead
 of a commit. Dokku builds record no commit, so `Pending` and `Failed` name
 the build, and pinned detection stays silent.
 
+### GitHub Deployments
+
+For teams whose CI deploys to a host most developers cannot reach (a Dokku
+box behind a firewall, a VPS where only admins hold SSH keys). If CI records
+each deploy as a GitHub Deployment, anyone who can read the repo sees what is
+deployed, with no access to the host.
+
+```yaml
+platform: github_deployments
+repo: acme/widgets       # default: inferred from origin
+environment: production  # default: production
+```
+
+No `app:` is needed. onair reads the environment's last 10 deployments and
+the newest status of each through the GitHub API, with the token from
+`GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token`; without one it asks you to run
+`gh auth login`. The token needs read access to the repo's deployments.
+
+- **Deployed** is the newest deployment whose status is `success`.
+- **Pending** is a newer deployment that is `queued`, `pending` or
+  `in_progress`, with its commit.
+- **Failed** is a newer deployment whose status is `failure` or `error`.
+- A deployment with no status yet is ignored.
+- With no successful deployment among the last 10, the report says so in one
+  line, under any Pending or Failed row.
+- If the status of a deployment newer than the deployed one cannot be read,
+  the report fails rather than show an older commit as running.
+
+**This adapter reports what CI recorded, not what the host runs.** A deploy
+that bypassed CI stays invisible until the next recorded one, and a CI job
+that records the sha it pushed reports that sha even if the host ended up
+running something else. So have CI record the sha it reads back from the host
+after the deploy, not the sha it pushed. For example, in GitHub Actions:
+
+```yaml
+permissions:
+  deployments: write
+steps:
+  - uses: actions/checkout@v4
+  - name: Deploy
+    env:
+      GH_TOKEN: ${{ github.token }}
+    run: |
+      id=$(gh api repos/${{ github.repository }}/deployments \
+        -f ref=${{ github.sha }} -f environment=production \
+        -F auto_merge=false -f 'required_contexts[]' --jq .id)
+      gh api repos/${{ github.repository }}/deployments/$id/statuses -f state=in_progress
+      if ./deploy.sh && [ "$(./running-sha.sh)" = "${{ github.sha }}" ]; then
+        state=success
+      else
+        state=failure
+      fi
+      gh api repos/${{ github.repository }}/deployments/$id/statuses -f state=$state
+```
+
+Here `deploy.sh` deploys and `running-sha.sh` asks the host which commit it
+runs. When the host runs a different commit than the one pushed, the job
+records a failure rather than a false success.
+
 ### Task links (optional)
 
 If your commit subjects carry task ids (Jira, Linear, Notion, anything), tell
@@ -149,6 +210,7 @@ additively:
   "platform": "heroku",
   "branch": "main",
   "repo": "acme/widgets",
+  "environment": null,
   "remote_head": "<sha>",
   "deployed": {
     "sha": "<sha>", "version": 1234, "description": "Deploy a1b2c3d4",
@@ -171,6 +233,9 @@ additively:
 ```
 
 - `delta.status` is `"current"`, `"behind"`, or `"unknown"`.
+- `environment` is the GitHub Deployments environment read, `null` on other
+  platforms. With `platform: github_deployments`, `app` is `null`, and
+  `deployed` is `null` when no deployment among the last 10 succeeded.
 - `pending`: `{ "sha", "build_id", "started_at", "subject", "author" }` when
   a build is in flight. On Dokku `sha` is `null` and `build_id` names the
   build; on Heroku `build_id` is `null`.

data/lib/onair/cli.rb

@@ -62,17 +62,17 @@ module Onair
     def status(flags)
       config = Config.resolve(flags)
       git = Git.new(fetch_allowed: config.fetch)
-      adapter = Platform.build(config)
       repo = config.repo || git.origin_repo
+      adapter = Platform.build(config, repo: repo)
       now = Time.now
       report = Orchestrator.new(config: config, adapter: adapter, git: git, repo: repo, now: now).run
 
       if flags[:json]
         puts Renderer::Json.new(report: report, app: config.app, platform: config.platform,
-          branch: config.branch, repo: repo, task: config.task).render
+          branch: config.branch, repo: repo, environment: adapter.environment, task: config.task).render
       else
         tty = $stdout.tty?
-        print Renderer::Tty.new(report: report, app: config.app, platform_label: adapter.display_name,
+        print Renderer::Tty.new(report: report, app: adapter.target_label, platform_label: adapter.display_name,
           branch: config.branch, repo: repo, task: config.task,
           color: tty && !no_color?, hyperlinks: tty, now: now).render
       end

data/lib/onair/config.rb

@@ -8,13 +8,16 @@ module Onair
   class Config
     FILENAME = ".onair.yml"
 
-    attr_reader :platform, :app, :repo, :branch, :fetch, :task, :host
+    DEFAULT_ENVIRONMENT = "production"
 
-    # `host` is the SSH destination for SSH-driven platforms (Dokku); nil
-    # elsewhere, and only the adapter that needs it checks it.
-    def initialize(platform:, app:, repo:, branch:, fetch:, task: nil, host: nil)
+    attr_reader :platform, :app, :repo, :branch, :fetch, :task, :host, :environment
+
+    # `app`, `host` and `environment` are each read by the adapters that need
+    # them; those adapters check them, so any may be nil elsewhere.
+    def initialize(platform:, app:, repo:, branch:, fetch:, task: nil, host: nil, environment: nil)
       @platform = platform
       @host = host
+      @environment = environment
       @app = app
       @repo = repo
       @branch = branch
@@ -27,7 +30,6 @@ module Onair
       platform = file["platform"] || "heroku"
       # HEROKU_APP names a Heroku app, so it must not redirect another platform.
       app = flags[:app] || ((platform == "heroku") ? env["HEROKU_APP"] : nil) || file["app"]
-      raise Error, "no app configured - pass --app NAME, set HEROKU_APP, or run `onair init`" if app.nil?
 
       new(
         platform: platform,
@@ -36,7 +38,8 @@ module Onair
         branch: file["branch"] || "main",
         fetch: !flags[:no_fetch],
         task: TaskLink.from_config(file["task"]),
-        host: file["host"]
+        host: file["host"],
+        environment: file["environment"] || DEFAULT_ENVIRONMENT
       )
     end
 

data/lib/onair/platform/base.rb

@@ -9,21 +9,23 @@ module Onair
         @registry[name] = klass
       end
 
-      def build(config)
+      def build(config, repo: nil)
         klass = @registry[config.platform]
         if klass.nil?
           raise Error,
             "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(", ")})"
         end
 
-        klass.new(config)
+        klass.new(config, repo: repo)
       end
     end
 
     # Adapter contract: implement #snapshot returning a Snapshot.
     #
     #   deployed:         the release CURRENTLY RUNNING (nil sha only if
-    #                     truly unresolvable)
+    #                     truly unresolvable), or nil when the platform
+    #                     records no successful deploy; renderers then show
+    #                     one line in its place
     #   pending:          newest in-flight build, or nil
     #   release:          newest release above the running one that is not
     #                     running (release phase pending or failed), or nil
@@ -40,8 +42,12 @@ module Onair
     # (delta, pinned, mine, rendering) is platform-agnostic and must not
     # reference any specific platform.
     class Base
-      def initialize(config)
+      NO_APP = "no app configured - pass --app NAME, set HEROKU_APP, or run `onair init`"
+
+      # `repo` is the GitHub repo (config or origin remote), or nil.
+      def initialize(config, repo: nil)
         @config = config
+        @repo = repo
       end
 
       def snapshot
@@ -52,6 +58,16 @@ module Onair
         self.class.name.split("::").last
       end
 
+      # What the report's header names next to the platform.
+      def target_label
+        @config.app
+      end
+
+      # The deploy environment the adapter reads, for platforms that have one.
+      def environment
+        nil
+      end
+
       private
 
       # Exceptions surface via #value; without this the dying thread also

data/lib/onair/platform/dokku.rb

@@ -58,6 +58,7 @@ module Onair
       def validate!
         raise Error, "no host configured - add `host:` to #{Config::FILENAME}" if host.to_s.empty?
         raise Error, "invalid Dokku host #{host.inspect}" if host.start_with?("-")
+        raise Error, NO_APP if app.nil?
         raise Error, "invalid Dokku app name #{app.inspect}" unless APP_NAME.match?(app)
       end
 

data/lib/onair/platform/github_deployments.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "time"
+require "uri"
+
+module Onair
+  module Platform
+    # Reads what CI recorded as GitHub Deployments for one environment, so
+    # anyone who can read the repo sees production without host access. It
+    # reports CI's record, not what the host runs.
+    class GithubDeployments < Base
+      HOST = "api.github.com"
+      API_VERSION = "2022-11-28"
+      WINDOW = 10
+      # owner/name, with no all-dot segment, since the repo goes into a URL path.
+      REPO_NAME = %r{\A(?!\.+/)[\w.-]+/(?!\.+\z)[\w.-]+\z}
+      SUCCESS = "success"
+      # GitHub marks an older successful deployment inactive once a newer one
+      # in the environment succeeds, so both states count as deployed once.
+      SUCCEEDED_STATES = %w[success inactive].freeze
+      IN_FLIGHT_STATES = %w[queued pending in_progress].freeze
+      FAILED_STATES = %w[failure error].freeze
+
+      def initialize(config, repo: nil)
+        super
+        raise Error, "no GitHub repo - add `repo: owner/name` to #{Config::FILENAME}" if @repo.to_s.empty?
+        raise Error, "invalid GitHub repo #{@repo.inspect} - expected owner/name" unless REPO_NAME.match?(@repo)
+      end
+
+      def snapshot
+        token = resolve_token
+        rows = with_statuses(token, deployments(token))
+        # A deployment whose status could not be read may be the one running,
+        # so any such row above the newest success fails the report.
+        index = rows.index { |row| row[:error] || row[:state] == SUCCESS }
+        raise rows[index][:error] if index && rows[index][:error]
+
+        newer = index ? rows.first(index) : rows
+        succeeded = rows.select { |row| SUCCEEDED_STATES.include?(row[:state]) }.map { |row| row[:sha] }.uniq
+        Snapshot.new(deployed: index && deployed(rows[index]), pending: pending(newer), release: failed(newer),
+          latest_built_sha: succeeded.first, succeeded_shas: succeeded, rollout: nil)
+      end
+
+      def display_name
+        "GitHub"
+      end
+
+      def target_label
+        "#{@repo} (#{environment})"
+      end
+
+      def environment
+        @config.environment || Config::DEFAULT_ENVIRONMENT
+      end
+
+      private
+
+      def resolve_token
+        token = Auth::GithubToken.token
+        raise Error, "no GitHub token found - run `gh auth login`" if token.nil? || token.empty?
+
+        token
+      end
+
+      def deployments(token)
+        query = URI.encode_www_form(environment: environment, per_page: WINDOW)
+        with_http { |http| get(http, token, "/repos/#{@repo}/deployments?#{query}") }
+      end
+
+      # Pairs each deployment with its newest status, newest deployment first.
+      # A failed statuses call keeps its row with the error, for #snapshot to
+      # judge; a deployment with no status yet says nothing, so it is skipped.
+      def with_statuses(token, deployments)
+        threads = deployments.map do |deployment|
+          quiet_thread do
+            newest_status(token, deployment["id"])
+          rescue Error => e
+            e
+          end
+        end
+        deployments.zip(threads.map(&:value)).filter_map do |deployment, status|
+          next if status.nil?
+
+          row = {id: deployment["id"], sha: deployment["sha"], created_at: parse_time(deployment["created_at"])}
+          next row.merge(error: status) if status.is_a?(Error)
+
+          row.merge(state: status["state"], status_at: parse_time(status["created_at"]))
+        end.sort_by { |row| row[:created_at] || Time.at(0) }.reverse
+      end
+
+      def newest_status(token, id)
+        with_http { |http| get(http, token, "/repos/#{@repo}/deployments/#{id}/statuses?per_page=1") }.first
+      end
+
+      def deployed(row)
+        Deployed.new(sha: row[:sha], version: nil, description: "deployment #{row[:id]}",
+          deployed_at: row[:status_at])
+      end
+
+      def pending(newer)
+        row = newer.find { |candidate| IN_FLIGHT_STATES.include?(candidate[:state]) }
+        row && Pending.new(sha: row[:sha], started_at: row[:created_at])
+      end
+
+      def failed(newer)
+        row = newer.find { |candidate| FAILED_STATES.include?(candidate[:state]) }
+        row && Release.new(sha: row[:sha], version: nil, description: "deployment #{row[:id]}",
+          status: :failed, started_at: row[:status_at])
+      end
+
+      def with_http(&)
+        Net::HTTP.start(HOST, 443, use_ssl: true, open_timeout: 5, read_timeout: 15, &)
+      rescue Net::OpenTimeout, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+        raise Error, "GitHub API request failed: #{e.message}"
+      end
+
+      def get(http, token, path)
+        request = Net::HTTP::Get.new(path)
+        request["Authorization"] = "Bearer #{token}"
+        request["Accept"] = "application/vnd.github+json"
+        request["X-GitHub-Api-Version"] = API_VERSION
+        response = http.request(request)
+        raise Error, error_message(response, path) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "GitHub API returned invalid JSON for #{path}"
+      rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, SystemCallError, OpenSSL::SSL::SSLError => e
+        raise Error, "GitHub API request failed: #{e.message}"
+      end
+
+      def error_message(response, path)
+        case response.code.to_i
+        when 401 then "GitHub rejected the token (401) - run `gh auth login`"
+        when 404 then "GitHub repo not found or not visible to this token: #{@repo}"
+        when 403, 429
+          if response["x-ratelimit-remaining"] == "0"
+            "GitHub API rate limit reached - try again later"
+          else
+            "GitHub API returned #{response.code} for #{path}"
+          end
+        else "GitHub API returned #{response.code} for #{path}"
+        end
+      end
+
+      def parse_time(value)
+        value && Time.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      Platform.register("github_deployments", self)
+    end
+  end
+end

data/lib/onair/platform/heroku.rb

@@ -18,6 +18,11 @@ module Onair
       PREBOOT_HANDOFF = 180
       PREBOOT_NOTE = "preboot: previous web dynos may still serve"
 
+      def initialize(config, repo: nil)
+        super
+        raise Error, NO_APP if app.nil?
+      end
+
       def snapshot
         token = resolve_token
         releases_thread = quiet_thread { releases(token) }

data/lib/onair/renderer/json.rb

@@ -8,8 +8,9 @@ module Onair
     # Machine-readable status. The schema is a public API documented in the
     # README — additive changes only.
     class Json
-      def initialize(report:, app:, platform:, branch:, repo:, task: nil)
+      def initialize(report:, app:, platform:, branch:, repo:, environment: nil, task: nil)
         @report = report
+        @environment = environment
         @app = app
         @platform = platform
         @branch = branch
@@ -27,6 +28,7 @@ module Onair
           platform: @platform,
           branch: @branch,
           repo: @repo,
+          environment: @environment,
           remote_head: @report.remote_head,
           deployed: deployed_payload,
           pending: pending_payload,

data/lib/onair/renderer/tty.rb

@@ -65,14 +65,27 @@ module Onair
         return [] if release.nil?
         return build_failed_lines(release) if release.sha.nil?
 
+        label, color, note = release.version.nil? ? versionless_release(release) : versioned_release(release)
+        row_lines(label, color, release.sha, age(release.started_at), extra: paint(note, color)) + [""]
+      end
+
+      def versioned_release(release)
         detail = version_label(release.version)
         detail = [detail, release.description].compact.join(": ") if release.sha == snapshot.deployed&.sha
-        label, color, note = if release.status == :failed
+        if release.status == :failed
           ["Failed:", :red, "✗ release phase failed (#{detail})"]
         else
           ["Releasing:", :yellow, "⟳ release phase (#{detail})"]
         end
-        row_lines(label, color, release.sha, age(release.started_at), extra: paint(note, color)) + [""]
+      end
+
+      # A platform that numbers no releases names the deploy by its description.
+      def versionless_release(release)
+        if release.status == :failed
+          ["Failed:", :red, "✗ deploy failed (#{release.description})"]
+        else
+          ["Releasing:", :yellow, "⟳ deploying (#{release.description})"]
+        end
       end
 
       # A failed build whose commit the platform does not record.
@@ -83,15 +96,17 @@ module Onair
 
       def deployed_lines
         deployed = snapshot.deployed
-        if deployed&.sha
+        return ["  #{paint("No successful deploy recorded.", :yellow)}"] if deployed.nil?
+
+        if deployed.sha
           lines = row_lines("Deployed:", :green, deployed.sha, age(deployed.deployed_at), extra: delta_text)
           lines << rollout_line if @report.rollout
           lines << pinned_line if @report.pinned
           lines.concat(yours_lines)
           lines
         else
-          subject = ["the running commit", version_label(deployed&.version)].compact.join(" for ")
-          ["  #{paint("Could not resolve #{subject} (#{deployed&.description}).", :yellow)}"]
+          subject = ["the running commit", version_label(deployed.version)].compact.join(" for ")
+          ["  #{paint("Could not resolve #{subject} (#{deployed.description}).", :yellow)}"]
         end
       end
 

data/lib/onair/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Onair
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/onair.rb

@@ -64,6 +64,7 @@ require_relative "onair/remote_head"
 require_relative "onair/platform/base"
 require_relative "onair/platform/heroku"
 require_relative "onair/platform/dokku"
+require_relative "onair/platform/github_deployments"
 require_relative "onair/renderer/tty"
 require_relative "onair/renderer/json"
 require_relative "onair/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: onair-cli
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eugene
@@ -32,6 +32,7 @@ files:
 - lib/onair/orchestrator.rb
 - lib/onair/platform/base.rb
 - lib/onair/platform/dokku.rb
+- lib/onair/platform/github_deployments.rb
 - lib/onair/platform/heroku.rb
 - lib/onair/remote_head.rb
 - lib/onair/renderer/json.rb