deployangel 0.1.15 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fae02d0fd8337fc6eb82ef0492d1bab86d03071dd9c9774dc332e95a6f52ffc9
-  data.tar.gz: 733fce2015cfa6e8fd6f5c618005cdda6c5aabf6aae8d7be128a156c46be65a6
+  metadata.gz: a288e6edf81d6e4119526b5ce13d87e033a9bc54d5a02679bf5d5585771e67fb
+  data.tar.gz: 0530abbe1a6dd018fbb528697e0a86fd7c10377ba09271b1bfd576ac2cca2e3e
 SHA512:
-  metadata.gz: db2bd88f8bb149df827631c8a44453c8a328c790b6174a370d39469c1e025055bfb5923c70f52984b8a1a6f2e702e79a17c600f176375dc053f31c390f7ebae8
-  data.tar.gz: 2e33938b4d09aa6bd342300e2097ad7a10fe8a3a722296acd5e06a6e5fc9f39a9c6f16364907abb159dcfe02c95f659e0df5096e3c51f9334240b1cce50f0faa
+  metadata.gz: 12968f549c284c8c96f5151455341f6966f1c4dc5ee2e3a8a634cbe0d751235c8868ec254a6e40a49376ab260497262107da682ab16f20f0a53c5446ebde6989
+  data.tar.gz: '01408cbd6f6fcb74ef21eb0b3f2db04ebf9c24981c7d798f897edca04487018ad84383216cb6744102b5e6eba1a51f6be5a6204b7757daab328176bca1f76f63'

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.17 (2026-10-08)
+
+- The agent reports from every Rails environment but `development` and `test`,
+  so a staging or preview app running with `RAILS_ENV=staging` works without
+  `DEPLOYANGEL_ENABLED=true`. `config.environments`, when set, still limits it to
+  the listed environments.
+
+## 0.1.16 (2026-10-08)
+
+- The agent finds the release in a git checkout when nothing earlier names
+  it: the commit `HEAD` names, read from `.git` in the app root or up to 3
+  directories above it (worktrees and submodules included), without running
+  `git` (source `git_head`). It comes after a `REVISION` file and before ECS.
+- When nothing else identifies the release, the agent reports a fingerprint
+  of the app's code as the version (`code:` and 12 hex characters, source
+  `code_fingerprint`): the hash of the file digests it already computes. It's
+  worked out in the reporter thread as soon as it starts, never at boot or
+  in a request, and needs file digests on. A warning suggests setting
+  `DEPLOYANGEL_REVISION`: without a commit, DeployAngel shows which files
+  changed but not the commits and pull requests.
+- `deployangel install docker` adds `ARG GIT_SHA` and
+  `ENV DEPLOYANGEL_REVISION=$GIT_SHA` at the end of the Dockerfile's last
+  stage, before its `CMD`, and says which `--build-arg` to pass. It never
+  edits CI workflows.
+
 ## 0.1.15 (2026-10-06)
 
 - Checkpoints report whether they were recorded in an HTTP request or a job

data/README.md

@@ -36,26 +36,46 @@ The agent must know which release it is running. It finds it in this order:
    didn't come from GitHub
 7. Coolify: `SOURCE_COMMIT`. Dokku: `GIT_REV`
 8. a `REVISION` file in the app root, which Capistrano writes and any build step can
-9. ECS, including Fargate: the container's image, from the metadata endpoint ECS
-   provides (one local request at boot). The image tag is the release when it's a
-   commit or a version like `v1.4.2`; with a moving tag like `latest`, the image
-   digest is
+9. a git checkout, for servers deployed by `git pull`, Fabric, or Ansible: the commit
+   `HEAD` names, read from `.git` in the app root or up to 3 directories above it
+   (worktrees and submodules included). The agent reads the files; it never runs `git`
+10. ECS, including Fargate: the container's image, from the metadata endpoint ECS
+    provides (one local request at boot). The image tag is the release when it's a
+    commit or a version like `v1.4.2`; with a moving tag like `latest`, the image
+    digest is
+11. a fingerprint of the app's code, reported as `code:` and 12 hex characters: the
+    hash of the [file digests](#what-it-sends) the agent already computes, so the
+    same code is the same release. It needs file digests on, and is worked out in
+    the background when the reporter starts, not at boot. Without a commit, the
+    dashboard shows which files changed but not the commits and pull requests, so
+    the agent logs a warning suggesting `DEPLOYANGEL_REVISION`
 
 For other Docker deploys (compose, Swarm, Kubernetes), and on ECS to see each
 release by its commit, bake the commit into the image, since `.dockerignore`
 usually leaves `.git` out:
 
+```bash
+bundle exec deployangel install docker
+```
+
+adds this to the end of the Dockerfile's last stage, before its `CMD` (so the
+layers above it stay cached):
+
 ```dockerfile
 ARG GIT_SHA
 ENV DEPLOYANGEL_REVISION=$GIT_SHA
 ```
 
-and build with `docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .`. On
-DigitalOcean App Platform, set `DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH}` in
-the app spec. On Elastic Beanstalk, see
-[Deploying to Elastic Beanstalk](#deploying-to-elastic-beanstalk). If the agent
-finds none of these, its telemetry can't be tied to a deploy, and the dashboard
-says so.
+Then build with `docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .`
+(`fly deploy --build-arg GIT_SHA=$(git rev-parse HEAD)` on Fly.io, or
+`build-args: GIT_SHA=${{ github.sha }}` with GitHub's docker/build-push-action).
+It changes nothing if the Dockerfile already sets `DEPLOYANGEL_REVISION`, and
+never edits CI workflows. A build without the argument leaves the variable
+empty, which counts as unset. On DigitalOcean App Platform, set
+`DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH}` in the app spec. On Elastic
+Beanstalk, see [Deploying to Elastic Beanstalk](#deploying-to-elastic-beanstalk).
+If the agent finds none of these, its telemetry can't be tied to a deploy, and
+the dashboard says so.
 
 ## What it sends
 
@@ -122,7 +142,7 @@ Environment variables are enough for most apps. To override in code:
 ```ruby
 # config/initializers/deployangel.rb
 DeployAngel.configure do |config|
-  config.environments = %w[production staging] # default: production only
+  config.environments = %w[production] # default: every environment but development and test
 end
 ```
 
@@ -298,6 +318,9 @@ It writes `.kamal/hooks/post-deploy`, which runs `deployangel release` after eac
 to add). Set `DEPLOYANGEL_API_TOKEN` (a CI deploys token) wherever you run
 `kamal deploy`. The hook never fails a deploy.
 
+Kamal apps don't need `deployangel install docker`: `KAMAL_VERSION` already
+identifies the release.
+
 ### Deploying with Capistrano
 
 Capistrano writes a `REVISION` file into each release, so the agent already

data/lib/deployangel/agent.rb

@@ -16,7 +16,7 @@ module DeployAngel
     # later still lands in time.
     FLUSH_JITTER = 1.0..50.0
 
-    attr_reader :config, :release, :instance
+    attr_reader :config, :instance
     attr_writer :metadata
 
     def initialize(config:, environment:, root: nil, framework: nil, framework_version: nil,
@@ -24,6 +24,11 @@ module DeployAngel
       @config = config
       @active = config.active?(environment)
       @release = Release.resolve(config: config, env: env, root: root)
+      # Nothing named the release, so the code fingerprint may. It hashes the
+      # app's files, so the reporter computes it before its first send (see
+      # #release), never at boot or in a request.
+      @fingerprint_pending = @release.unknown?
+      @release_mutex = Mutex.new
       @runtime = Protocol.runtime(framework: framework, framework_version: framework_version)
       @transport = transport || Transport.new(config)
       @env = env
@@ -33,8 +38,6 @@ module DeployAngel
       @thread_mutex = Mutex.new
       @warned = {}
       reset_process_state
-      warn_once(:unknown_release, "DeployAngel could not determine the release; set DEPLOYANGEL_REVISION " \
-        "or enable Heroku dyno metadata. Telemetry will not be attributed to deployments.") if @active && @release.unknown?
       start_reporter if @active && eager
     end
 
@@ -42,6 +45,25 @@ module DeployAngel
       @active
     end
 
+    # The release this process is running. The first call may build the file
+    # digests for the code fingerprint, so only the reporter thread and
+    # shutdown call it; requests and jobs never read the release.
+    def release
+      return @release unless @fingerprint_pending
+
+      @release_mutex.synchronize do
+        if @fingerprint_pending
+          @release = Release.code_fingerprint(@metadata&.file_manifest) || @release
+          @fingerprint_pending = false
+          warn_about_release
+        end
+      end
+      @release
+    rescue StandardError
+      @fingerprint_pending = false
+      @release
+    end
+
     def record_request(route_key:, status:, duration_ms:, unhandled: false, in_totals: true)
       return unless @active
 
@@ -113,7 +135,7 @@ module DeployAngel
       return 0 unless @active
 
       @aggregator.drain(include_current: include_current, max_periods: config.max_queued_payloads).each do |period|
-        @buffer.push(Transport.encode(Protocol.telemetry(period, instance: @instance, release: @release,
+        @buffer.push(Transport.encode(Protocol.telemetry(period, instance: @instance, release: release,
           runtime: @runtime, capabilities: capabilities)))
       end
       send_buffered
@@ -162,7 +184,7 @@ module DeployAngel
       return if @metadata_sent || @metadata.nil? || paused?
 
       base = { "protocol_version" => Protocol::VERSION, "instance" => @instance.to_protocol,
-               "release" => @release.to_protocol, "runtime" => @runtime }.merge(@metadata.to_protocol)
+               "release" => release.to_protocol, "runtime" => @runtime }.merge(@metadata.to_protocol)
       result = @transport.post(METADATA_PATH, base)
       return unless result.ok?
 
@@ -187,6 +209,10 @@ module DeployAngel
       end
 
       def run_reporter
+        # Off the request path, so a process that exits within a minute or two
+        # doesn't build the fingerprint at shutdown instead. Only once the
+        # framework has attached the metadata it's built from.
+        release if @metadata
         until @stopping
           sleep(seconds_until_next_flush)
           break if @stopping
@@ -242,6 +268,18 @@ module DeployAngel
         @paused_until && @clock.call < @paused_until
       end
 
+      def warn_about_release
+        return unless @active
+
+        if @release.unknown?
+          warn_once(:unknown_release, "DeployAngel could not determine the release; set DEPLOYANGEL_REVISION " \
+            "or enable Heroku dyno metadata. Telemetry will not be attributed to deployments.")
+        elsif @release.source == "code_fingerprint"
+          warn_once(:code_fingerprint, "DeployAngel identifies releases by a fingerprint of the app's code. " \
+            "Set DEPLOYANGEL_REVISION to the deployed commit to see each release's commits and pull requests.")
+        end
+      end
+
       def warn_once(key, message)
         return if @warned[key]
 

data/lib/deployangel/cli.rb

@@ -33,7 +33,8 @@ module DeployAngel
         exception  Details for a fingerprint     deployangel exception FINGERPRINT
         check      Report a smoke test result    --name=NAME --status=pass|fail [--covers=a,b]
                                                  [--commit=SHA | --deployment=ID] [--details-url=URL]
-        install    Add a deploy hook             deployangel install kamal
+        install    Add a Kamal deploy hook, or    deployangel install kamal
+                   bake the commit into an image  deployangel install docker
         mcp        Run the MCP server over stdio (for coding agents)
 
       With no target, verify, plan, and check use the current git HEAD commit.
@@ -57,6 +58,25 @@ module DeployAngel
       bundle exec deployangel release || true
     SH
 
+    # Goes at the end of the Dockerfile's last stage: a value that changes
+    # with every commit invalidates the cache of every layer after it.
+    DOCKER_BUILD_HELP = <<~HELP.chomp
+      Pass the commit when you build the image:
+
+        docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .
+        fly deploy --build-arg GIT_SHA=$(git rev-parse HEAD)
+        GitHub Actions (docker/build-push-action):
+          build-args: GIT_SHA=${{ github.sha }}
+
+      Kamal apps don't need this: DeployAngel reads Kamal's KAMAL_VERSION.
+    HELP
+
+    DOCKERFILE_LINES = <<~DOCKERFILE
+      # The commit this image runs, for DeployAngel. Build with --build-arg GIT_SHA=$(git rev-parse HEAD).
+      ARG GIT_SHA
+      ENV DEPLOYANGEL_REVISION=$GIT_SHA
+    DOCKERFILE
+
     def initialize(argv, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr, client: nil,
                    sleeper: ->(seconds) { sleep(seconds) }, clock: -> { Time.now }, git_head: nil, root: Dir.pwd)
       @root = root
@@ -206,12 +226,17 @@ module DeployAngel
         0
       end
 
-      # Writes .kamal/hooks/post-deploy, or says what to add to a hook that
-      # already exists, rather than overwriting it.
       def install
-        target = @argv.shift
-        return usage_error("install needs a target: deployangel install kamal") unless target == "kamal"
+        case (target = @argv.shift)
+        when "kamal" then install_kamal
+        when "docker" then install_docker
+        else usage_error("install needs a target: deployangel install kamal, or deployangel install docker")
+        end
+      end
 
+      # Writes .kamal/hooks/post-deploy, or says what to add to a hook that
+      # already exists, rather than overwriting it.
+      def install_kamal
         relative = File.join(".kamal", "hooks", "post-deploy")
         path = File.join(@root, relative)
         if File.exist?(path)
@@ -231,6 +256,55 @@ module DeployAngel
         0
       end
 
+      # Adds DEPLOYANGEL_REVISION, from a GIT_SHA build arg, to the Dockerfile.
+      # It never edits CI workflows; it says what to pass instead.
+      def install_docker
+        path = File.join(@root, "Dockerfile")
+        unless File.file?(path)
+          @stderr.puts("deployangel: no Dockerfile in #{@root}; run this where your Dockerfile is")
+          return USAGE_ERROR
+        end
+
+        content = File.read(path)
+        if content.include?("DEPLOYANGEL_REVISION")
+          @stdout.puts("Dockerfile already sets DEPLOYANGEL_REVISION.")
+          return 0
+        end
+
+        File.write(path, with_revision(content))
+        @stdout.puts("Added DEPLOYANGEL_REVISION to the Dockerfile's last stage. #{DOCKER_BUILD_HELP}")
+        0
+      end
+
+      # Before the CMD and ENTRYPOINT lines that end the last stage, with any
+      # comment just above them, or at the end if the stage doesn't end with
+      # one. Continuation lines aren't instructions.
+      def with_revision(content)
+        lines = content.lines
+        instructions = []
+        continuing = false
+        lines.each_with_index do |line, index|
+          text = line.strip
+          next if text.empty? || text.start_with?("#")
+
+          instructions << [ index, text[/\A\w+/].to_s.upcase ] unless continuing
+          continuing = text.end_with?("\\")
+        end
+
+        stage = instructions.drop(instructions.rindex { |_, word| word == "FROM" } || 0)
+        trailing = stage.reverse.take_while { |_, word| %w[CMD ENTRYPOINT].include?(word) }
+        if trailing.empty?
+          lines[-1] = "#{lines[-1].chomp}\n" if lines.any?
+          lines << "\n" unless lines.empty? || lines[-1].strip.empty?
+          lines << DOCKERFILE_LINES
+        else
+          at = trailing.last.first
+          at -= 1 while at.positive? && lines[at - 1].strip.start_with?("#")
+          lines.insert(at, DOCKERFILE_LINES)
+        end
+        lines.join
+      end
+
       def mcp
         require_relative "mcp"
         MCP::Server.new(client: client, input: @stdin, output: @stdout, error_output: @stderr,

data/lib/deployangel/configuration.rb

@@ -17,7 +17,7 @@ module DeployAngel
       @token = env["DEPLOYANGEL_TOKEN"]
       @endpoint = env["DEPLOYANGEL_URL"] || DEFAULT_ENDPOINT
       @enabled = parse_boolean(env["DEPLOYANGEL_ENABLED"])
-      @environments = %w[production]
+      @environments = nil
       @release_version = env["DEPLOYANGEL_RELEASE_VERSION"]
       @revision = env["DEPLOYANGEL_REVISION"]
       @flush_interval = 60
@@ -38,13 +38,19 @@ module DeployAngel
       @sidekiq_cron_schedule_file = nil
     end
 
-    # Reports only with a token. By default only in the listed
-    # environments; DEPLOYANGEL_ENABLED forces it on or off.
+    # Reports only with a token, and by default in every environment but
+    # these, so staging and preview apps work as they are while a token
+    # copied into a developer's .env stays quiet.
+    NON_REPORTING_ENVIRONMENTS = %w[development test].freeze
+
+    # config.environments, when set, lists the only environments to report
+    # from; DEPLOYANGEL_ENABLED forces it on or off.
     def active?(environment)
       return false if token.to_s.empty? || endpoint.to_s.empty?
       return enabled unless enabled.nil?
+      return environments.map(&:to_s).include?(environment.to_s) if environments
 
-      environments.include?(environment.to_s)
+      !NON_REPORTING_ENVIRONMENTS.include?(environment.to_s)
     end
 
     # Whether requests to a route are left out. Rails answers HEAD with the

data/lib/deployangel/core/release.rb

@@ -13,9 +13,15 @@ module DeployAngel
     # Tags that move from build to build, so they can't identify a release.
     MOVING_TAGS = %w[latest main master production prod staging stable release].freeze
 
+    # Look for .git this many directories above the app's root, for an app
+    # that lives in a subdirectory of its repository.
+    GIT_PARENT_LEVELS = 3
+
     # Order: explicit configuration, Heroku dyno metadata, the hosting
     # platform's own variables (Kamal, Render, Fly.io, Railway, Coolify, and
-    # Dokku's GIT_REV), a REVISION file, then ECS container metadata.
+    # Dokku's GIT_REV), a REVISION file, a git checkout, then ECS container
+    # metadata. When none of them names the release, the agent falls back to
+    # a fingerprint of the app's code (code_fingerprint), computed later.
     def self.resolve(config:, env: ENV, root: nil, http: method(:fetch_metadata))
       if present?(config.release_version) || present?(config.revision)
         build(config.release_version, config.revision, "config")
@@ -36,6 +42,8 @@ module DeployAngel
         build(nil, env["GIT_REV"], "git_rev")
       elsif root && File.file?(revision_path = File.join(root, "REVISION"))
         build(nil, File.read(revision_path, 100), "revision_file")
+      elsif root && (commit = git_head(root))
+        build(nil, commit, "git_head")
       elsif present?(env["ECS_CONTAINER_METADATA_URI_V4"]) && (release = ecs(http.call(env["ECS_CONTAINER_METADATA_URI_V4"])))
         release
       else
@@ -73,6 +81,77 @@ module DeployAngel
       tag unless tag.empty?
     end
 
+    # A server deployed by `git pull` (or Fabric, or Ansible) runs from a
+    # checkout, where HEAD names the commit. Read from the repository's
+    # files, never by running git. Nil if anything is missing or unreadable.
+    def self.git_head(root)
+      git_dir = find_git_dir(File.expand_path(root)) or return
+      common_dir = git_dir
+      commondir = File.join(git_dir, "commondir")
+      common_dir = File.expand_path(File.read(commondir, 1024).strip, git_dir) if File.file?(commondir)
+
+      head = File.read(File.join(git_dir, "HEAD"), 200).to_s.strip
+      ref = head.delete_prefix("ref:").strip if head.start_with?("ref:")
+      commit = ref ? read_ref(ref, git_dir, common_dir) : head
+      commit = commit.to_s.strip.downcase
+      commit if commit.match?(COMMIT_FORMAT)
+    rescue StandardError
+      nil
+    end
+
+    # .git is a directory, or for a worktree or submodule, a file naming the
+    # real one ("gitdir: ../.git/worktrees/shop").
+    def self.find_git_dir(dir)
+      (GIT_PARENT_LEVELS + 1).times do
+        git = File.join(dir, ".git")
+        return File.directory?(git) ? git : linked_git_dir(git) if File.exist?(git)
+
+        parent = File.dirname(dir)
+        return if parent == dir
+
+        dir = parent
+      end
+      nil
+    end
+
+    def self.linked_git_dir(file)
+      path = File.read(file, 1024).to_s[/\Agitdir:\s*(.+)$/, 1]&.strip
+      File.expand_path(path, File.dirname(file)) if present?(path)
+    end
+
+    # A branch's commit is in its ref file, in the worktree's own git dir or
+    # the common one, or else in packed-refs. Refs come from a file on disk,
+    # so anything outside refs/ is ignored rather than read.
+    def self.read_ref(ref, git_dir, common_dir)
+      return unless ref.start_with?("refs/") && !ref.include?("..")
+
+      [ git_dir, common_dir ].uniq.each do |dir|
+        path = File.join(dir, ref)
+        return File.read(path, 100) if File.file?(path)
+      end
+
+      packed = File.join(common_dir, "packed-refs")
+      return unless File.file?(packed)
+
+      File.foreach(packed) do |line|
+        next if line.start_with?("#", "^")
+
+        commit, name = line.split(" ", 2)
+        return commit if name.to_s.strip == ref
+      end
+      nil
+    end
+
+    # The release of an app that names it no other way: the hash of the file
+    # digests the agent already sends (Metadata#file_manifest), so the same
+    # code gives the same release. None when digests are off or truncated.
+    def self.code_fingerprint(manifest)
+      return unless manifest.is_a?(Hash) && !manifest["truncated"] && manifest["count"].to_i.positive?
+
+      hash = manifest["hash"].to_s
+      build("code:#{hash[0, 12]}", nil, "code_fingerprint") if hash.match?(/\A\h{12}/)
+    end
+
     # ECS (Fargate, and EC2 with a recent agent) serves each container's
     # metadata at ECS_CONTAINER_METADATA_URI_V4. The image tag identifies the
     # release, and is the commit when it looks like one. A moving tag such

data/lib/deployangel/metadata.rb

@@ -167,6 +167,8 @@ module DeployAngel
       end
     end
 
+    # Built once per process, by the reporter: the metadata send and the
+    # code fingerprint (Release.code_fingerprint) both read it.
     def file_manifest
       @file_manifest ||= begin
         if @config.file_digests
@@ -180,9 +182,9 @@ module DeployAngel
         else
           { "hash" => nil, "count" => 0, "truncated" => false, "files" => {} }
         end
+      rescue StandardError
+        { "hash" => nil, "count" => 0, "truncated" => false, "files" => {} }
       end
-    rescue StandardError
-      { "hash" => nil, "count" => 0, "truncated" => false, "files" => {} }
     end
   end
 end

data/lib/deployangel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeployAngel
-  VERSION = "0.1.15"
+  VERSION = "0.1.17"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.15
+  version: 0.1.17
 platform: ruby
 authors:
 - Jordan Owens