onair-cli 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1eb5f2eb79c1eb2da95ef69cb65f8bef60b72dc3d98563a6235573b4ae139fd6
-  data.tar.gz: f5a38c5ef53340a88e41c9c007e68c34d1035d0427b953ac7b4193421201dde7
+  metadata.gz: 863a5cc9f6796e525c125ed320542a3e4d8b076b5a6a5660744c9136ead84cc2
+  data.tar.gz: c771ccb2bd0c72fcf075e48c829556de327ad4dc3b2527db4ca0b5b0ee763e34
 SHA512:
-  metadata.gz: 133e4480b8e8c22835294d0c2b18e79f9ee6ba065ee080c7c5f0e0c61a1a8bf92aecc6ee2e6092bce8ba095ffe7937ce8b6cb6526ca20938ae3d3d54dc39062e
-  data.tar.gz: b4e08f469025a62273c6c848b4d790e8b9a1520a6ce6ab24f0b845bcd7453cfa2040b1d40b3d0a29fe73c13e9c3d4242779022b0b2c43ba11c968f0e5ae74be5
+  metadata.gz: e8016ad8033b28ec15e73cdae96b1b0e94562a4bc28226dfd5b556c8a3a24dc713106b9f8fe5b3c3881c330e71f9a297c768c0a2c9175114eccfdd4cc4eae76d
+  data.tar.gz: f78628cf04574876bc46322b9eba02d8f252152c90d7bc75bd032041be4a9f3741f6f3619d01693a3f9f098e18fcd64c6e14e722c27e65d51640a1bf5e7660e7

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [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
+  last `git push` over SSH. A running build shows as `Pending` and a build
+  that failed after the last success as `Failed`, both without a commit. The
+  rollout line counts containers per process type, and the window in which
+  the previous containers keep serving shows as an estimate.
+- Rows drop `v<version>` when the platform numbers no releases. `--json`
+  carries `null` versions and shas there, and `pending` gains `build_id`.
+
 ## [0.3.0] - 2026-10-08
 
 - Heroku: a rollout line under Deployed counts the dynos of each process type

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`.
@@ -42,8 +44,9 @@ case.
 gem install onair-cli
 ```
 
-Requires Ruby >= 3.2. Auth reuses the Heroku CLI's token from `~/.netrc`
-(written by `heroku login`), falling back to `heroku auth:token`.
+Requires Ruby >= 3.2. On Heroku, auth reuses the Heroku CLI's token from
+`~/.netrc` (written by `heroku login`), falling back to `heroku auth:token`.
+On Dokku, it reuses your SSH setup (see [Dokku](#dokku)).
 
 ## Usage
 
@@ -76,7 +79,8 @@ the API is a faster transport, never a cache.
   run that release: `⟳ rolling out v1234: web 1/3, 2 starting` while dynos
   restart, `✓ rolled out` once every dyno is up on it. With preboot on, the
   previous web dynos keep serving for about three minutes after the new ones
-  are up; that window shows as an estimate.
+  are up; that window shows as an estimate. On Dokku it counts containers,
+  and the estimate is the app's wait-to-retire after the newest build.
 - **Pending** - an in-flight build that's about to replace the deploy.
 - **Releasing** - a newer release whose release phase (e.g. migrations) is
   still running; production still serves the Deployed row until it finishes.
@@ -99,7 +103,86 @@ branch: main         # comparison branch; default: main
 ```
 
 Resolution order: CLI flags → env vars (`HEROKU_APP`, `GITHUB_REPO`) →
-`.onair.yml`.
+`.onair.yml`. `HEROKU_APP` applies only with `platform: heroku`.
+
+### Dokku
+
+```yaml
+platform: dokku
+host: my-dokku   # any SSH destination: dokku@host, or a ~/.ssh/config alias
+app: myapp
+```
+
+onair runs `ssh -o BatchMode=yes <host> <command> <app> --format json` for
+Dokku's report commands, so it needs Dokku 0.38 or newer and an `ssh` client.
+The host must log in as Dokku's `dokku` user, directly or through an alias
+with `User dokku`. Keys, addresses and users come from your SSH config;
+`BatchMode` never prompts, so the key must be loadable without a passphrase
+prompt (`ssh-add`).
+
+The deployed commit is the one the last `git push` deployed. An app deployed
+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)
 
@@ -127,6 +210,7 @@ additively:
   "platform": "heroku",
   "branch": "main",
   "repo": "acme/widgets",
+  "environment": null,
   "remote_head": "<sha>",
   "deployed": {
     "sha": "<sha>", "version": 1234, "description": "Deploy a1b2c3d4",
@@ -149,8 +233,14 @@ additively:
 ```
 
 - `delta.status` is `"current"`, `"behind"`, or `"unknown"`.
-- `pending`: `{ "sha", "started_at", "subject", "author" }` when a build is
-  in flight.
+- `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`.
+- `version` is `null` on platforms that number no releases (Dokku), and a
+  Dokku `release` is a failed build with a `null` sha.
 - `release`: `{ "sha", "version", "description", "status", "started_at",
   "subject", "author" }` when a release newer than the running one is not
   live; `status` is `"pending"` (release phase running) or `"failed"`. While

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,10 +8,16 @@ module Onair
   class Config
     FILENAME = ".onair.yml"
 
-    attr_reader :platform, :app, :repo, :branch, :fetch, :task
+    DEFAULT_ENVIRONMENT = "production"
 
-    def initialize(platform:, app:, repo:, branch:, fetch:, task: 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
@@ -21,16 +27,19 @@ module Onair
 
     def self.resolve(flags = {}, env: ENV, dir: Dir.pwd)
       file = find_file(dir) || {}
-      app = flags[:app] || env["HEROKU_APP"] || file["app"]
-      raise Error, "no app configured - pass --app NAME, set HEROKU_APP, or run `onair init`" if app.nil?
+      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"]
 
       new(
-        platform: file["platform"] || "heroku",
+        platform: platform,
         app: app,
         repo: env["GITHUB_REPO"] || file["repo"],
         branch: file["branch"] || "main",
         fetch: !flags[:no_fetch],
-        task: TaskLink.from_config(file["task"])
+        task: TaskLink.from_config(file["task"]),
+        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
@@ -33,12 +35,19 @@ module Onair
     #                     release, plus an optional estimate of when the
     #                     previous release stops serving; nil when unknown
     #
+    # Versions may be nil on every value, and pending/release shas may be nil
+    # when the platform's builds carry no commit; renderers drop what is absent.
+    #
     # Adapters own their internal concurrency and auth. Everything above
     # (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
@@ -48,6 +57,27 @@ module Onair
       def display_name
         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
+      # prints its own backtrace to stderr.
+      def quiet_thread(&block)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          block.call
+        end
+      end
     end
   end
 end

data/lib/onair/platform/dokku.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+require "time"
+
+module Onair
+  module Platform
+    # Dokku has no HTTP API, so every read is `ssh <host> <subcommand> <app>
+    # --format json`, run in parallel. Keys, users and addresses come from the
+    # user's SSH setup; the adapter only knows the destination.
+    class Dokku < Base
+      GIT_PUSH = "git-push"
+      FULL_SHA = /\A\h{40}\z/
+      # Dokku app names: lowercase letters, digits and dashes.
+      APP_NAME = /\A[a-z0-9][a-z0-9-]*\z/
+      # ps:report's JSON lists one `status-<process>.<n>` entry per container
+      # (named after its CONTAINER.<process>.<n> file), valued like
+      # "running (CID: 0123456789a)". The text output's dash form also matches.
+      CONTAINER_STATUS = /\Astatus-(?<type>.+)[.-]\d+\z/
+      SERVING_STATE = "running"
+      # After a deploy, Dokku keeps the previous containers serving for the
+      # app's wait-to-retire, 60 seconds unless configured.
+      DEFAULT_WAIT_TO_RETIRE = 60
+      RETIRE_NOTE = "retiring: previous containers may still serve"
+      # Wall-clock limit per command, matching the Heroku adapter's read timeout.
+      COMMAND_TIMEOUT = 15
+      SSH_OPTIONS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+        "-o", "ServerAliveInterval=5", "-o", "ServerAliveCountMax=3"].freeze
+
+      def snapshot
+        validate!
+        apps_thread = quiet_thread { dokku("apps:report") }
+        git_thread = quiet_thread { optional { dokku("git:report") } }
+        builds_thread = quiet_thread { optional { dokku("builds:list") } }
+        ps_thread = quiet_thread { optional { dokku("ps:report") } }
+        checks_thread = quiet_thread { optional { dokku("checks:report") } }
+
+        deployed = deployed(apps_thread.value, git_thread.value)
+        builds = Array(builds_thread.value).grep(Hash)
+        Snapshot.new(deployed: deployed, pending: pending(builds), release: failed(builds),
+          latest_built_sha: nil, succeeded_shas: [],
+          rollout: rollout(ps_thread.value, newest(builds, "succeeded"), checks_thread.value))
+      end
+
+      private
+
+      def host
+        @config.host
+      end
+
+      def app
+        @config.app
+      end
+
+      # The host and app go on the ssh command line, so a value starting with
+      # a dash would be read as an ssh option.
+      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
+
+      # Dokku strips the plugin prefix from report JSON keys, so git:report's
+      # `--git-last-updated-at` arrives as `last-updated-at`.
+      # Only a git push records the pushed commit. git:report's sha is not
+      # used: it can read the repo's HEAD rather than what was deployed.
+      def deployed(apps, git)
+        source = apps["deploy-source"].to_s
+        raise Error, "nothing deployed yet for app #{app}" if source.empty?
+
+        metadata = apps["deploy-source-metadata"].to_s
+        sha = (source == GIT_PUSH && FULL_SHA.match?(metadata)) ? metadata : nil
+        Deployed.new(sha: sha, version: nil, description: "deploy source: #{source}",
+          deployed_at: unix_time(git&.dig("last-updated-at")))
+      end
+
+      # Builds carry no commit, so the sha stays unknown until the build is
+      # correlated with the CI run that pushed it.
+      def pending(builds)
+        running = builds.find { |build| status(build) == "running" }
+        running && Pending.new(sha: nil, build_id: running["id"], started_at: parse_time(running["started_at"]))
+      end
+
+      # Only a failure newer than the last success matters; older failed
+      # records were superseded and are stale.
+      def failed(builds)
+        failure = newest(builds, "failed")
+        success = newest(builds, "succeeded")
+        return nil if failure.nil? || (success && started(success) >= started(failure))
+
+        Release.new(sha: nil, version: nil, description: "build #{failure["id"]}", status: :failed,
+          started_at: parse_time(failure["finished_at"]) || started(failure))
+      end
+
+      def newest(builds, wanted)
+        builds.select { |build| status(build) == wanted && started(build) }.max_by { |build| started(build) }
+      end
+
+      # display_status turns a running record whose process died into
+      # "abandoned"; older Dokku versions only report status.
+      def status(build)
+        build["display_status"] || build["status"]
+      end
+
+      def started(build)
+        parse_time(build["started_at"])
+      end
+
+      def rollout(ps, success, checks)
+        return nil unless ps.is_a?(Hash)
+
+        containers = ps.filter_map do |key, value|
+          match = CONTAINER_STATUS.match(key)
+          match && [match[:type], value.to_s.split(" ", 2).first.to_s]
+        end
+        return nil if containers.empty?
+
+        processes = containers.group_by(&:first)
+          .sort_by { |type, _| [(type == "web") ? 0 : 1, type] }
+          .map { |type, rows| process_rollout(type, rows.map(&:last)) }
+        Rollout.new(version: nil, processes: processes, overlap_note: RETIRE_NOTE,
+          overlap_until: retire_deadline(processes, success, checks))
+      end
+
+      # ps:report lists only the current deploy's containers, so nothing is
+      # ever counted as previous.
+      def process_rollout(type, states)
+        waiting = states.reject { |state| state == SERVING_STATE }.tally
+        ProcessRollout.new(type: type, total: states.size, up: states.size - waiting.values.sum,
+          waiting: waiting, previous: 0)
+      end
+
+      def retire_deadline(processes, success, checks)
+        finished = success && parse_time(success["finished_at"])
+        return nil if finished.nil? || !processes.all?(&:complete?)
+
+        finished + wait_to_retire(checks)
+      end
+
+      def wait_to_retire(checks)
+        Integer(checks&.dig("computed-wait-to-retire"), 10)
+      rescue ArgumentError, TypeError
+        DEFAULT_WAIT_TO_RETIRE
+      end
+
+      def optional
+        yield
+      rescue Error
+        nil
+      end
+
+      # Dokku prints warnings on stderr (e.g. "Skipping unreadable build
+      # record"), so only stdout is parsed.
+      def dokku(subcommand)
+        stdout, stderr, status = run(["ssh", *SSH_OPTIONS, host, subcommand, app, "--format", "json"])
+        raise Error, "dokku #{subcommand} timed out on #{host}" if status.nil?
+        raise Error, ssh_error(subcommand, stderr, status) unless status.success?
+
+        JSON.parse(stdout)
+      rescue Errno::ENOENT
+        raise Error, "ssh not found - the Dokku platform needs an ssh client on PATH"
+      rescue JSON::ParserError
+        raise Error, "Dokku returned invalid JSON for #{subcommand}"
+      end
+
+      # Returns [stdout, stderr, status], with a nil status when the command
+      # outlived the timeout and was killed.
+      def run(argv, timeout: COMMAND_TIMEOUT)
+        Open3.popen3(*argv) do |stdin, stdout, stderr, wait|
+          stdin.close
+          out = Thread.new { stdout.read }
+          err = Thread.new { stderr.read }
+          unless wait.join(timeout)
+            begin
+              Process.kill("KILL", wait.pid)
+            rescue Errno::ESRCH
+              nil
+            end
+            return [out.value, err.value, nil]
+          end
+          [out.value, err.value, wait.value]
+        end
+      end
+
+      # ssh itself exits 255; anything else is Dokku's own exit code.
+      def ssh_error(subcommand, stderr, status)
+        line = stderr.lines.map { |text| text.sub(/\A\s*!\s*/, "").strip }.reject(&:empty?).last
+        if status.exitstatus == 255 && stderr.include?("Permission denied")
+          "SSH to #{host} was refused - load the key with `ssh-add`"
+        elsif status.exitstatus == 255
+          "could not reach #{host} over SSH#{line && ": #{line}"}"
+        else
+          "dokku #{subcommand} failed on #{host}#{line && ": #{line}"}"
+        end
+      end
+
+      def unix_time(value)
+        Time.at(Integer(value, 10)).utc
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def parse_time(value)
+        value && Time.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      Platform.register("dokku", self)
+    end
+  end
+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

@@ -16,6 +16,12 @@ module Onair
       # With preboot, Heroku keeps routing to the previous web dynos for about
       # three minutes after the new ones come up.
       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
@@ -36,13 +42,6 @@ module Onair
         @config.app
       end
 
-      def quiet_thread(&block)
-        Thread.new do
-          Thread.current.report_on_exception = false
-          block.call
-        end
-      end
-
       def resolve_token
         token = Auth::Netrc.token(HOST)
         token = Auth::HerokuCli.token if token.nil? || token.empty?
@@ -138,7 +137,7 @@ module Onair
           .sort_by { |type, _| [(type == "web") ? 0 : 1, type] }
           .map { |type, dynos| process_rollout(type, dynos, version) }
         Rollout.new(version: version, processes: processes,
-          overlap_until: preboot ? preboot_handoff(formation, version) : nil)
+          overlap_until: preboot ? preboot_handoff(formation, version) : nil, overlap_note: PREBOOT_NOTE)
       end
 
       def process_rollout(type, dynos, version)

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,
@@ -60,7 +62,8 @@ module Onair
         pending = snapshot.pending
         return nil if pending.nil?
 
-        {sha: pending.sha, started_at: iso(pending.started_at)}.merge(commit_fields(pending.sha))
+        {sha: pending.sha, build_id: pending.build_id, started_at: iso(pending.started_at)}
+          .merge(commit_fields(pending.sha))
       end
 
       def release_payload

data/lib/onair/renderer/tty.rb

@@ -49,6 +49,12 @@ module Onair
         pending = snapshot.pending
         return [] if pending.nil?
 
+        if pending.sha.nil?
+          started = pending.started_at && "started #{age(pending.started_at)}"
+          return commitless_row("Pending:", :yellow, "build #{pending.build_id}", started,
+            paint("⟳ deploying", :yellow)) + [""]
+        end
+
         row_lines("Pending:", :yellow, pending.sha, age(pending.started_at)) + [""]
       end
 
@@ -57,28 +63,50 @@ module Onair
       def release_lines
         release = snapshot.release
         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
 
-        detail = "v#{release.version}"
-        detail = "#{detail}: #{release.description}" if release.sha == snapshot.deployed&.sha
-        label, color, note = if release.status == :failed
+      def versioned_release(release)
+        detail = version_label(release.version)
+        detail = [detail, release.description].compact.join(": ") if release.sha == snapshot.deployed&.sha
+        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.
+      def build_failed_lines(release)
+        commitless_row("Failed:", :red, release.description, age(release.started_at),
+          paint("✗ build failed", :red)) + [""]
       end
 
       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
-          ["  #{paint("Could not resolve the running commit for v#{deployed&.version} " \
-                      "(#{deployed&.description}).", :yellow)}"]
+          subject = ["the running commit", version_label(deployed.version)].compact.join(" for ")
+          ["  #{paint("Could not resolve #{subject} (#{deployed.description}).", :yellow)}"]
         end
       end
 
@@ -86,13 +114,14 @@ module Onair
       # traffic to the previous release, so that window gets its own line.
       def rollout_line
         rollout = @report.rollout
+        target = [version_label(rollout.version)].compact.map { |label| " #{label}" }.join
         text, color = if rollout.complete?
-          ["✓ rolled out v#{rollout.version}: #{process_counts(rollout)}", :dim]
+          ["✓ rolled out#{target}: #{process_counts(rollout)}", :dim]
         elsif rollout.processes.all?(&:complete?)
-          ["⟳ preboot: previous web dynos may still serve for " \
+          ["⟳ #{rollout.overlap_note || "previous release may still serve"} for " \
            "~#{remaining(rollout.overlap_until)} (estimate)", :yellow]
         else
-          ["⟳ rolling out v#{rollout.version}: #{process_counts(rollout)}", :yellow]
+          ["⟳ rolling out#{target}: #{process_counts(rollout)}", :yellow]
         end
         "  #{paint(text, color)}"
       end
@@ -131,6 +160,17 @@ module Onair
         [first, "  #{paint("→", :dim)} #{linkify(subject, info ? sha : nil)}"]
       end
 
+      # A row for a build with no commit: its name stands where the sha would,
+      # and there is no subject line to show.
+      def commitless_row(label, color_key, name, age, extra)
+        age_blurb = age ? "  #{paint("(#{age})", :dim)}" : ""
+        ["  #{paint(label.ljust(LABEL_WIDTH), color_key)}  #{paint(name, :bold)}#{age_blurb}  #{extra}"]
+      end
+
+      def version_label(version)
+        version && "v#{version}"
+      end
+
       def delta_text
         case @report.delta
         when :current
@@ -143,7 +183,8 @@ module Onair
 
       def pinned_line
         deployed = snapshot.deployed
-        "  #{paint("⏸ v#{deployed.version} (#{deployed.description}) - newer build " \
+        running = [version_label(deployed.version), "(#{deployed.description})"].compact.join(" ")
+        "  #{paint("⏸ #{running} - newer build " \
                    "#{snapshot.latest_built_sha[0, 9]} succeeded but is not running", :yellow)}"
       end
 

data/lib/onair/report.rb

@@ -73,8 +73,11 @@ module Onair
       !sha.nil? && !latest.nil? && latest != sha && snapshot.pending.nil? && !release_of_other_commit?(snapshot)
     end
 
+    # A release with no known commit (a failed build on a platform whose
+    # builds carry none) says nothing about commits, so it never counts.
     def self.release_of_other_commit?(snapshot)
-      !snapshot.release.nil? && snapshot.release.sha != snapshot.deployed&.sha
+      sha = snapshot.release&.sha
+      !sha.nil? && sha != snapshot.deployed&.sha
     end
 
     # "Did my merge just ship?" — deliberately a 2-commit first-parent window

data/lib/onair/version.rb

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

data/lib/onair.rb

@@ -9,13 +9,19 @@ module Onair
   CommitInfo = Data.define(:subject, :author_name, :author_email, :committed_at)
 
   # The release currently running in production. `sha` may be nil when the
-  # platform can't resolve the running commit; version/description still render.
+  # platform can't resolve the running commit; `version` is nil on platforms
+  # that number nothing.
   Deployed = Data.define(:sha, :version, :description, :deployed_at)
 
-  Pending = Data.define(:sha, :started_at)
+  # An in-flight build. `sha` is nil when the platform's builds carry no
+  # commit; `build_id` then names the row.
+  Pending = Data.define(:sha, :build_id, :started_at) do
+    def initialize(sha:, started_at:, build_id: nil) = super
+  end
 
   # A release newer than the running one that is not serving traffic: its
   # release phase is still running (status :pending) or it failed (:failed).
+  # A nil `sha` is a failed build whose commit the platform does not record.
   Release = Data.define(:sha, :version, :description, :status, :started_at)
 
   # Dynos of one process type against the running release. `up` counts dynos
@@ -28,8 +34,11 @@ module Onair
   end
 
   # How far the running release has reached its dynos. `overlap_until` is an
-  # estimate of when the previous release stops serving traffic, or nil.
-  Rollout = Data.define(:version, :processes, :overlap_until) do
+  # estimate of when the previous release stops serving traffic, or nil;
+  # `overlap_note` is the platform's phrase for that window.
+  Rollout = Data.define(:version, :processes, :overlap_until, :overlap_note) do
+    def initialize(version:, processes:, overlap_until:, overlap_note: nil) = super
+
     def complete?
       processes.all?(&:complete?) && overlap_until.nil?
     end
@@ -54,6 +63,8 @@ require_relative "onair/auth/github_token"
 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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eugene
@@ -31,6 +31,8 @@ files:
 - lib/onair/git.rb
 - 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