dependabot-github_actions 0.389.0 → 0.390.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28c1be16649f2941b1c6c5cb4f562eb1ef504dea136022b5a35519633dcf19a9
-  data.tar.gz: 56d1bd1e166613184652b00ede70f25ea9371285be99addc463e44fd28236a4b
+  metadata.gz: 915f664971e3665b0f6ee89557dc064b19fac2a49600250d2762a286fca20da7
+  data.tar.gz: a02dc5897d62ee777fac539862d8e0cd728695d43f31ad531e1dc8c5a65db287
 SHA512:
-  metadata.gz: 8310d74f6bde92cc9f0d367751bb8ddfc075abb5e49aa281b5e0a6f6aadd6b8c1eea9f5f80e329afab340d30ab4189e15363c8be431f8bd9a8d28bbf16e1ec8d
-  data.tar.gz: 1f691fdd8dd686c860392abdeb7dadcb01771a197b48cba418a8a8555fa76a851255fa93d53f5eefc19ae3ffa3e0bb920584e19fcc15c6db96da1ee397a4545f
+  metadata.gz: b1d0fe90498dbae54af7ee1105a98c20a56128633d1ab72e11530e890726130f009fb581d616bda816985aa39a6dd1f7605ca94999e10e05a468d8f1ffecf752
+  data.tar.gz: 76a7272475cb1ffcf7964f74f08ac3cfa80efe4612932f8d520b456c3fead93bfa195770420e494d7e1265b2bf0d2237e6b85e9143ed52bf02d52ed985db5ecb

data/lib/dependabot/github_actions/constants.rb

@@ -33,6 +33,13 @@ module Dependabot
     # The path to the config .yml file
     CONFIG_YMLS = T.let("#{WORKFLOW_DIRECTORY}/#{ANYTHING_YML}".freeze, String)
 
+    # The basename of the per-repo Actions lockfile generated by gh-actions-lock
+    LOCKFILE_NAME = T.let("actions.lock", String)
+    # The repo-relative path to the Actions lockfile
+    LOCKFILE_PATH = T.let("#{WORKFLOW_DIRECTORY}/#{LOCKFILE_NAME}".freeze, String)
+    # The only lockfile schema version this ecosystem understands.
+    SUPPORTED_LOCKFILE_VERSION = T.let("v0.0.2", String)
+
     OWNER_KEY = T.let("owner", String)
     REPO_KEY = T.let("repo", String)
     PATH_KEY = T.let("path", String)

data/lib/dependabot/github_actions/file_fetcher.rb

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 
 require "dependabot/file_fetchers"
 require "dependabot/file_fetchers/base"
+require "dependabot/experiments"
 require "dependabot/github_actions/constants"
 
 module Dependabot
@@ -44,7 +45,14 @@ module Dependabot
         fetched_files = []
         fetched_files += correctly_encoded_workflow_files
 
-        return fetched_files if fetched_files.any?
+        if fetched_files.any?
+          # The lockfile is additive: it is only fetched alongside workflow files
+          # and never activates the ecosystem on its own. Relocking also requires
+          # every workflow to be materialized, so retain the workflow-only path if
+          # an invalidly encoded workflow had to be omitted.
+          fetched_files += [actions_lockfile].compact if incorrectly_encoded_workflow_files.empty?
+          return fetched_files
+        end
 
         if incorrectly_encoded_workflow_files.none?
           expected_paths =
@@ -68,6 +76,17 @@ module Dependabot
 
       private
 
+      # Fetches the canonical `.github/workflows/actions.lock` when the update covers
+      # repository workflows. Composite-action directories cannot own a lockfile.
+      sig { returns(T.nilable(DependencyFile)) }
+      def actions_lockfile
+        return unless Dependabot::Experiments.enabled?(:github_actions_lockfile)
+        return unless source.hostname == GITHUB_COM
+        return fetch_file_if_present(LOCKFILE_PATH) if directory == "/"
+
+        fetch_file_if_present(LOCKFILE_NAME) if directory.delete_prefix("/") == WORKFLOW_DIRECTORY
+      end
+
       sig { returns(T::Array[DependencyFile]) }
       def workflow_files
         return @workflow_files unless @workflow_files.empty?

data/lib/dependabot/github_actions/file_parser.rb

@@ -171,9 +171,7 @@ module Dependabot
 
       sig { returns(T::Array[Dependabot::DependencyFile]) }
       def workflow_files
-        # The file fetcher only fetches workflow files, so no need to
-        # filter here
-        dependency_files
+        dependency_files.reject { |file| file.path.delete_prefix("/") == LOCKFILE_PATH }
       end
 
       sig { override.void }

data/lib/dependabot/github_actions/file_updater.rb

@@ -7,6 +7,7 @@ require "dependabot/errors"
 require "dependabot/file_updaters"
 require "dependabot/file_updaters/base"
 require "dependabot/github_actions/constants"
+require "dependabot/github_actions/lockfile"
 
 module Dependabot
   module GithubActions
@@ -15,18 +16,10 @@ module Dependabot
 
       sig { override.returns(T::Array[Dependabot::DependencyFile]) }
       def updated_dependency_files
-        updated_files = []
-
-        dependency_files.each do |file|
-          next unless requirement_changed?(file, dependency)
-
-          updated_files <<
-            updated_file(
-              file: file,
-              content: updated_workflow_file_content(file)
-            )
+        updated_files = changed_workflow_files.map do |file|
+          updated_file(file: file, content: updated_workflow_file_content(file))
         end
-
+        updated_files.concat(relocked_files(updated_files))
         updated_files.reject! { |f| dependency_files.include?(f) }
         raise "No files changed!" if updated_files.none?
 
@@ -49,6 +42,102 @@ module Dependabot
         raise "No workflow files!"
       end
 
+      # Workflow files (everything except the lockfile) whose requirement changed.
+      sig { returns(T::Array[Dependabot::DependencyFile]) }
+      def changed_workflow_files
+        dependency_files
+          .reject { |f| lockfile?(f) }
+          .select { |f| requirement_changed?(f, dependency) }
+      end
+
+      # When the repo has an `actions.lock` authoritative for one or more changed
+      # workflows, regenerate it through the gh-actions-lock engine. Lock keys and
+      # onboarding comparisons are repo-relative paths, independent of the Dependabot
+      # `directory`. Workflows absent from the lock (and lockless repos) never reach
+      # here, preserving today's regex-only behavior.
+      sig do
+        params(updated_workflow_files: T::Array[Dependabot::DependencyFile])
+          .returns(T::Array[Dependabot::DependencyFile])
+      end
+      def relocked_files(updated_workflow_files)
+        changed_repository_workflows = changed_workflow_files.select do |file|
+          File.dirname(repo_relative_path(file)) == WORKFLOW_DIRECTORY
+        end
+        return [] if changed_repository_workflows.empty?
+
+        lock = lockfile
+        reader = lockfile_reader
+        return [] unless lock && reader
+
+        changed_onboarded = changed_repository_workflows.select { |f| reader.onboarded?(repo_relative_path(f)) }
+        return [] if changed_onboarded.empty?
+
+        # Gate only once the lock is authoritative for a workflow we're changing, so an
+        # incompatible/malformed lock over untouched workflows never blocks a legacy update.
+        Lockfile::VersionGate.assert_supported!(reader.version)
+        reader.validate_dependency_entries!
+
+        # Materialize the full onboarded closure so the lock remains intact, but fix
+        # only changed workflows so unrelated refs are not touched.
+        content = Lockfile::CliEngine.new(credentials).relock(
+          workflow_files: rewritten_onboarded_workflow_files(reader, updated_workflow_files),
+          lockfile: lock,
+          workflow_paths: changed_onboarded.map { |file| repo_relative_path(file) }
+        )
+
+        [updated_file(file: lock, content: content)]
+      end
+
+      # The onboarded closure as the engine should see it: every workflow the lock
+      # tracks, with bumped refs applied to changed ones and the rest left verbatim.
+      sig do
+        params(
+          reader: Lockfile::Reader,
+          updated_workflow_files: T::Array[Dependabot::DependencyFile]
+        ).returns(T::Array[Dependabot::DependencyFile])
+      end
+      def rewritten_onboarded_workflow_files(reader, updated_workflow_files)
+        updated_by_path = updated_workflow_files.to_h { |file| [repo_relative_path(file), file] }
+        onboarded_workflow_files(reader).map do |file|
+          updated_by_path.fetch(repo_relative_path(file), file)
+        end
+      end
+
+      # All workflow files the lock is authoritative for (changed or not).
+      sig { params(reader: Lockfile::Reader).returns(T::Array[Dependabot::DependencyFile]) }
+      def onboarded_workflow_files(reader)
+        dependency_files
+          .reject { |f| lockfile?(f) }
+          .select { |f| reader.onboarded?(repo_relative_path(f)) }
+      end
+
+      sig { returns(T.nilable(Dependabot::DependencyFile)) }
+      def lockfile
+        dependency_files.find { |f| lockfile?(f) }
+      end
+
+      sig { returns(T.nilable(Lockfile::Reader)) }
+      def lockfile_reader
+        return @lockfile_reader if defined?(@lockfile_reader)
+
+        @lockfile_reader = T.let(
+          Lockfile::Reader.from_files(dependency_files),
+          T.nilable(Lockfile::Reader)
+        )
+      end
+
+      sig { params(file: Dependabot::DependencyFile).returns(T::Boolean) }
+      def lockfile?(file)
+        repo_relative_path(file) == LOCKFILE_PATH
+      end
+
+      # Repo-relative path (no leading slash), independent of the configured
+      # Dependabot directory. This is the canonical form lock keys use.
+      sig { params(file: Dependabot::DependencyFile).returns(String) }
+      def repo_relative_path(file)
+        file.path.delete_prefix("/")
+      end
+
       # rubocop:disable Metrics/AbcSize
       sig { params(file: Dependabot::DependencyFile).returns(String) }
       def updated_workflow_file_content(file)

data/lib/dependabot/github_actions/helpers.rb

@@ -26,7 +26,8 @@ module Dependabot
             ignored_versions: T::Array[String],
             raise_on_ignored: T::Boolean,
             consider_version_branches_pinned: T::Boolean,
-            dependency_source_details: T.nilable(T::Hash[Symbol, String])
+            dependency_source_details: T.nilable(T::Hash[Symbol, String]),
+            git_metadata_fetcher: T.nilable(Dependabot::GitMetadataFetcher)
           )
             .void
         end
@@ -36,7 +37,8 @@ module Dependabot
           ignored_versions: [],
           raise_on_ignored: false,
           consider_version_branches_pinned: false,
-          dependency_source_details: nil
+          dependency_source_details: nil,
+          git_metadata_fetcher: nil
         )
           @dependency = dependency
           @credentials = credentials
@@ -44,6 +46,7 @@ module Dependabot
           @raise_on_ignored = raise_on_ignored
           @consider_version_branches_pinned = consider_version_branches_pinned
           @dependency_source_details = dependency_source_details
+          @git_metadata_fetcher = git_metadata_fetcher
         end
 
         sig { returns(Dependabot::Dependency) }
@@ -79,7 +82,8 @@ module Dependabot
             ignored_versions: ignored_versions,
             raise_on_ignored: raise_on_ignored,
             consider_version_branches_pinned: true,
-            dependency_source_details: source
+            dependency_source_details: source,
+            git_metadata_fetcher: @git_metadata_fetcher
           )
         end
       end

data/lib/dependabot/github_actions/lockfile/cli_engine.rb

@@ -0,0 +1,225 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "sorbet-runtime"
+
+require "dependabot/shared_helpers"
+require "dependabot/command_helpers"
+require "dependabot/credential"
+require "dependabot/dependency_file"
+require "dependabot/errors"
+require "dependabot/logger"
+require "dependabot/github_actions/constants"
+require "dependabot/github_actions/lockfile/env"
+require "dependabot/github_actions/lockfile/errors"
+require "dependabot/github_actions/lockfile/reader"
+
+module Dependabot
+  module GithubActions
+    module Lockfile
+      # Shells out to gh-actions-lock to regenerate actions.lock.
+      class CliEngine
+        extend T::Sig
+
+        JsonObject = T.type_alias { T::Hash[String, Object] }
+        FIXED_FINDING_CATEGORIES = T.let(%w(onboarding-required ref-changed stale).freeze, T::Array[String])
+        UNRESOLVABLE_CATEGORIES = T.let(%w(impostor-commit lockfile-forgery).freeze, T::Array[String])
+
+        sig { params(credentials: T::Array[Dependabot::Credential]).void }
+        def initialize(credentials)
+          @credentials = credentials
+        end
+
+        # Binary baked into the ecosystem image; falls back to PATH for local dev.
+        sig { returns(String) }
+        def self.binary_path
+          base = ENV.fetch("DEPENDABOT_NATIVE_HELPERS_PATH", nil)
+          base ? File.join(base, "github_actions", "bin", "gh-actions-lock") : "gh-actions-lock"
+        end
+
+        # Re-pins workflows already tracked in the lockfile. `--no-onboard` refuses new
+        # workflows/actions (surfaced as onboarding-required skips); `--no-narrow`
+        # keeps the exact ref Dependabot wrote.
+        sig do
+          params(
+            workflow_files: T::Array[Dependabot::DependencyFile],
+            lockfile: Dependabot::DependencyFile,
+            workflow_paths: T::Array[String]
+          ).returns(String)
+        end
+        def relock(workflow_files:, lockfile:, workflow_paths: workflow_files.map { |file| repo_path(file) })
+          in_repo(workflow_files, lockfile) do |dir|
+            args = %w(--no-onboard --no-narrow --no-interactive --json=findings) + workflow_paths
+            json, exit_status = run(dir, args)
+
+            skipped = onboarding_skips(json, lockfile)
+            log_skips(skipped)
+
+            # `findings` is the PRE-fix diagnosis; at exit 0 fix-mode already resolved
+            # them. Only exit 1 can carry a survivor (impostor/forgery or a skip).
+            raise_on_findings(json) if exit_status == 1
+
+            File.read(File.join(dir, LOCKFILE_PATH))
+          end
+        end
+
+        private
+
+        sig { returns(T::Array[Dependabot::Credential]) }
+        attr_reader :credentials
+
+        sig do
+          type_parameters(:T)
+            .params(
+              workflow_files: T::Array[Dependabot::DependencyFile],
+              lockfile: T.nilable(Dependabot::DependencyFile),
+              blk: T.proc.params(dir: String).returns(T.type_parameter(:T))
+            )
+            .returns(T.type_parameter(:T))
+        end
+        def in_repo(workflow_files, lockfile, &blk)
+          SharedHelpers.in_a_temporary_directory do |dir|
+            (workflow_files + [lockfile].compact).each do |file|
+              path = File.join(dir, repo_path(file))
+              FileUtils.mkdir_p(File.dirname(path))
+              File.write(path, file.content)
+            end
+            blk.call(dir.to_s) # rubocop:disable Performance/RedundantBlockCall
+          end
+        end
+
+        # Repo-relative path (no leading slash) so the temp repo always mirrors the
+        # real repository layout regardless of the Dependabot directory config.
+        sig { params(file: Dependabot::DependencyFile).returns(String) }
+        def repo_path(file)
+          file.path.delete_prefix("/")
+        end
+
+        # Invokes the binary and returns [parsed JSON, exit code]. Exit is tri-state:
+        # 0 = valid, 1 = blocking findings (still well-formed JSON on stdout, parse it),
+        # 2+ = tool failure (no usable JSON). JSON and exit are not interchangeable in
+        # fix-mode: findings/valid are PRE-fix, exit is POST-fix, so callers gate on exit.
+        sig { params(dir: String, args: T::Array[String]).returns([JsonObject, Integer]) }
+        def run(dir, args)
+          stdout, stderr, exit_status = invoke(dir, args)
+          raise EngineError, "gh-actions-lock failed (exit #{exit_status}): #{stderr.strip}" if exit_status > 1
+
+          json = case (parsed = JSON.parse(stdout))
+                 when Hash then parsed
+                 else raise EngineError, "gh-actions-lock emitted non-object JSON"
+                 end
+
+          [json, exit_status]
+        rescue JSON::ParserError => e
+          raise EngineError, "gh-actions-lock emitted unparseable JSON: #{e.message}"
+        end
+
+        # Runs the binary with no shell (argv array, no escaping) and returns
+        # [stdout, stderr, exit_status].
+        sig { params(dir: String, args: T::Array[String]).returns([String, String, Integer]) }
+        def invoke(dir, args)
+          env_cmd = [Env.build(credentials), self.class.binary_path, *args, { chdir: dir }]
+          stdout, stderr, process = CommandHelpers.capture3_with_timeout(env_cmd)
+
+          # A failed spawn comes back as a nil status, not an exception.
+          if process.nil?
+            raise EngineError,
+                  "gh-actions-lock failed to start (#{self.class.binary_path}): #{stderr.to_s.strip}"
+          end
+          raise EngineError, "gh-actions-lock terminated by signal #{process.termsig}" if process.termsig
+
+          [stdout || "", stderr || "", process.exitstatus]
+        end
+
+        sig { params(json: JsonObject).void }
+        def raise_on_findings(json)
+          T.cast(Array(json["findings"]), T::Array[JsonObject]).each do |finding|
+            next unless finding["severity"].nil? || finding["severity"] == "error"
+
+            category = finding["category"].to_s
+            next if FIXED_FINDING_CATEGORIES.include?(category)
+
+            if UNRESOLVABLE_CATEGORIES.include?(category)
+              raise UnresolvableDependency.new(
+                (finding["dependency"] || "unknown").to_s,
+                (finding["detail"] || category).to_s
+              )
+            end
+
+            raise EngineError, "gh-actions-lock left an unhandled #{category.inspect} finding"
+          end
+        end
+
+        # Partitions onboarding-required findings into genuine skips vs. a lock the
+        # engine could not read. The discriminator is the action, not the path: a
+        # finding is contradictory iff the lock already pins its `dependency` under its
+        # `workflow`. A finding with no `dependency` falls back to the path check.
+        sig do
+          params(json: JsonObject, lockfile: Dependabot::DependencyFile)
+            .returns(T::Array[String])
+        end
+        def onboarding_skips(json, lockfile)
+          findings = T.cast(Array(json["findings"]), T::Array[JsonObject])
+          onboarding = findings.select { |finding| finding["category"] == "onboarding-required" }
+          return [] if onboarding.empty?
+
+          reader = Reader.from_files([lockfile])
+          contradictory, strays = onboarding.partition { |finding| lock_contradicts?(reader, finding) }
+
+          raise_lockfile_unrecognized(contradictory) if contradictory.any?
+
+          strays.map { |finding| workflow_for(finding) }.uniq
+        end
+
+        # True when an onboarding-required finding contradicts a lock we can read.
+        sig { params(reader: T.nilable(Reader), finding: JsonObject).returns(T::Boolean) }
+        def lock_contradicts?(reader, finding)
+          return false unless reader
+
+          action = finding["dependency"].to_s
+          workflow = workflow_for(finding)
+          return reader.pins_action?(workflow, action) unless action.empty?
+
+          reader.onboarded?(workflow)
+        end
+
+        sig { params(finding: JsonObject).returns(String) }
+        def workflow_for(finding)
+          (finding["workflow"] || finding["dependency"] || "unknown").to_s
+        end
+
+        # The engine reported lock-tracked workflows as un-onboarded: it could not read
+        # the lock and treated it as empty. Fail with a lockfile error, not a crash.
+        sig { params(findings: T::Array[JsonObject]).void }
+        def raise_lockfile_unrecognized(findings)
+          paths = findings.map { |finding| workflow_for(finding) }
+          slice_keys = %w(workflow dependency category severity detail)
+          Dependabot.logger.debug(
+            "gh-actions-lock reported lockfile-tracked workflow(s) as un-onboarded " \
+            "(lock unreadable): #{findings.map { |f| f.slice(*slice_keys) }}"
+          )
+          raise Dependabot::DependencyFileNotParseable.new(
+            LOCKFILE_PATH,
+            "gh-actions-lock could not read #{LOCKFILE_PATH} as covering #{paths.join(', ')}, even " \
+            "though the lockfile tracks #{paths.length == 1 ? 'that workflow' : 'those workflows'}. " \
+            "The lockfile is likely malformed or unreadable by the engine: every dependencies entry " \
+            "must include #{Reader::REQUIRED_DEPENDENCY_KEYS.join(', ')}, or the engine silently " \
+            "treats the whole lockfile as empty. No changes were made."
+          )
+        end
+
+        sig { params(skipped: T::Array[String]).void }
+        def log_skips(skipped)
+          return if skipped.empty?
+
+          Dependabot.logger.info(
+            "gh-actions-lock skipped onboarding in #{skipped.size} workflow(s) (no-onboard is " \
+            "update's default; skipped actions remain untracked, not failed): #{skipped.join(', ')}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dependabot/github_actions/lockfile/env.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/credential"
+require "dependabot/github_actions/constants"
+
+module Dependabot
+  module GithubActions
+    module Lockfile
+      # Builds the subprocess environment for the gh-actions-lock engine. Hosted
+      # Dependabot is tokenless behind a MITM proxy that overwrites the auth header,
+      # while proxyless local runs hold the real github.com token in `credentials`.
+      module Env
+        extend T::Sig
+
+        # Placeholder satisfies go-gh's "token must be present" check in hosted mode
+        # where the proxy supplies real auth. Mirrors git's installation-token username.
+        DUMMY_TOKEN = T.let("x-access-token", String)
+
+        sig do
+          params(credentials: T::Array[Dependabot::Credential])
+            .returns(T::Hash[String, String])
+        end
+        def self.build(credentials)
+          env = {}
+
+          github_credential = github_dot_com_credential(credentials)
+          env["GH_TOKEN"] = github_credential&.fetch("password", nil) || DUMMY_TOKEN
+          env["GH_ACTIONS_LOCK_DEPENDABOT_PROXY"] = "1" unless github_credential
+
+          env
+        end
+
+        # Mirrors SharedHelpers.configure_git_to_use_https_with_credentials: prefer a
+        # deliberately-added token over an app installation token ("v1." prefix).
+        sig do
+          params(credentials: T::Array[Dependabot::Credential])
+            .returns(T.nilable(Dependabot::Credential))
+        end
+        def self.github_dot_com_credential(credentials)
+          candidates = credentials.select do |c|
+            c["type"] == "git_source" && c["host"] == GITHUB_COM && c["password"]
+          end
+
+          candidates.find { |c| !c["password"]&.start_with?("v1.") } || candidates.first
+        end
+      end
+    end
+  end
+end

data/lib/dependabot/github_actions/lockfile/errors.rb

@@ -0,0 +1,52 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "dependabot/errors"
+require "dependabot/github_actions/constants"
+
+module Dependabot
+  module GithubActions
+    module Lockfile
+      # Lockfile schema version this ecosystem does not understand. Hard error so we
+      # never half-write an incompatible lockfile.
+      class UnsupportedLockfileVersion < Dependabot::DependencyFileNotParseable
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :found, :supported
+
+        sig { params(found: String, supported: String).void }
+        def initialize(found, supported)
+          @found = found
+          @supported = supported
+          super(
+            LOCKFILE_PATH,
+            "Unsupported actions.lock version #{found.inspect}; " \
+            "this version of Dependabot supports #{supported.inspect}. " \
+            "Upgrade Dependabot or regenerate the lockfile with a compatible gh-actions-lock version."
+          )
+        end
+      end
+
+      # Engine could not resolve a dependency (often a transitive action the job
+      # token cannot reach). We refuse to emit a partial lockfile.
+      class UnresolvableDependency < Dependabot::DependencyFileNotResolvable
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :dependency, :detail
+
+        sig { params(dependency: String, detail: String).void }
+        def initialize(dependency, detail)
+          @dependency = dependency
+          @detail = detail
+          super("Could not resolve #{dependency}: #{detail}")
+        end
+      end
+
+      # Engine itself failed (binary missing, tool failure, unparseable JSON).
+      class EngineError < Dependabot::DependabotError; end
+    end
+  end
+end

data/lib/dependabot/github_actions/lockfile/reader.rb

@@ -0,0 +1,129 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "yaml"
+
+require "dependabot/errors"
+require "dependabot/dependency_file"
+require "dependabot/github_actions/constants"
+
+module Dependabot
+  module GithubActions
+    module Lockfile
+      # Read-only parser for `.github/workflows/actions.lock`. Authoritative only for
+      # the workflow paths in its `workflows:` section, so onboarding is decided per
+      # path via {#onboarded?}, never repo-wide. Never writes: lockfile generation
+      # belongs to the gh-actions-lock engine.
+      class Reader
+        extend T::Sig
+
+        ParsedObject = T.type_alias { T::Hash[String, Object] }
+
+        # Every commit must carry an explicit hash-algorithm prefix.
+        ALGO_PREFIXES = T.let(%w(sha1- sha256-).freeze, T::Array[String])
+
+        # Keys gh-actions-lock requires on every `dependencies` entry. A missing key
+        # makes the engine silently discard the whole lockfile in memory and report
+        # every workflow as un-onboarded.
+        REQUIRED_DEPENDENCY_KEYS = T.let(%w(ref commit owner_id repo_id).freeze, T::Array[String])
+
+        sig { params(content: String).void }
+        def initialize(content)
+          @content = T.let(content, String)
+          @data = T.let(parse, ParsedObject)
+        end
+
+        # Returns a Reader for the lockfile in a DependencyFile array, or nil when the
+        # repo has no lockfile (whole repo is on the legacy path).
+        sig { params(files: T::Array[Dependabot::DependencyFile]).returns(T.nilable(Reader)) }
+        def self.from_files(files)
+          file = files.find { |f| f.path.delete_prefix("/") == LOCKFILE_PATH }
+          return nil unless file
+
+          content = file.content
+          return nil if content.nil? || content.strip.empty?
+
+          new(content)
+        end
+
+        sig { returns(String) }
+        def version
+          @data["version"].to_s
+        end
+
+        sig { params(path: String).returns(T::Boolean) }
+        def onboarded?(path)
+          workflows.key?(path)
+        end
+
+        # True when the lockfile already pins `action_ref` (an `owner/repo@ref`) under
+        # the given workflow path. Discriminates a legitimate new-action skip from a
+        # contradictory "lock read as empty" finding.
+        sig { params(path: String, action_ref: String).returns(T::Boolean) }
+        def pins_action?(path, action_ref)
+          return false if action_ref.empty?
+
+          Array(workflows[path]).include?(action_ref)
+        end
+
+        # Asserts every `dependencies` entry carries {REQUIRED_DEPENDENCY_KEYS}. A
+        # missing key makes the engine silently treat the whole lockfile as empty.
+        # Deferred to the relock gate (not the constructor) so a malformed lock
+        # covering only untouched workflows never blocks a legacy regex update.
+        sig { void }
+        def validate_dependency_entries!
+          dependencies.each do |key, entry|
+            raise parse_error("dependency entry #{key.inspect} is not a mapping") unless entry.is_a?(Hash)
+
+            missing = REQUIRED_DEPENDENCY_KEYS.reject { |field| entry.key?(field) }
+            unless missing.empty?
+              raise parse_error(
+                "dependency entry #{key.inspect} is missing required field(s) #{missing.join(', ')}; " \
+                "gh-actions-lock requires #{REQUIRED_DEPENDENCY_KEYS.join(', ')} on every entry or it " \
+                "silently treats the whole lockfile as empty"
+              )
+            end
+
+            commit = entry["commit"].to_s
+            next if ALGO_PREFIXES.any? { |prefix| commit.start_with?(prefix) }
+
+            raise parse_error(
+              "dependency entry #{key.inspect} has commit #{commit.inspect} without a hash-algorithm prefix " \
+              "(expected one of #{ALGO_PREFIXES.join(', ')})"
+            )
+          end
+        end
+
+        private
+
+        sig { returns(ParsedObject) }
+        def workflows
+          wf = @data["workflows"]
+          wf.is_a?(Hash) ? wf : {}
+        end
+
+        sig { returns(ParsedObject) }
+        def dependencies
+          deps = @data["dependencies"]
+          deps.is_a?(Hash) ? deps : {}
+        end
+
+        sig { returns(ParsedObject) }
+        def parse
+          parsed = YAML.safe_load(@content)
+          raise parse_error("lockfile is not a mapping") unless parsed.is_a?(Hash)
+
+          parsed
+        rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::BadAlias => e
+          raise parse_error(e.message)
+        end
+
+        sig { params(message: String).returns(Dependabot::DependencyFileNotParseable) }
+        def parse_error(message)
+          Dependabot::DependencyFileNotParseable.new(LOCKFILE_PATH, message)
+        end
+      end
+    end
+  end
+end

data/lib/dependabot/github_actions/lockfile/version_gate.rb

@@ -0,0 +1,31 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "dependabot/github_actions/constants"
+require "dependabot/github_actions/lockfile/errors"
+
+module Dependabot
+  module GithubActions
+    module Lockfile
+      # Pre-1.0 lockfile schema revisions may be breaking, so only the explicitly
+      # supported version is safe to read and rewrite.
+      module VersionGate
+        extend T::Sig
+
+        sig { params(found: String).void }
+        def self.assert_supported!(found)
+          return if compatible?(found)
+
+          raise UnsupportedLockfileVersion.new(found, SUPPORTED_LOCKFILE_VERSION)
+        end
+
+        sig { params(found: String).returns(T::Boolean) }
+        def self.compatible?(found)
+          found == SUPPORTED_LOCKFILE_VERSION
+        end
+      end
+    end
+  end
+end

data/lib/dependabot/github_actions/lockfile.rb

@@ -0,0 +1,23 @@
+# typed: strong
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Dependabot
+  module GithubActions
+    # Integration with the gh-actions-lock lockfile (`.github/workflows/actions.lock`),
+    # which is generated and owned by the upstream `gh-actions-lock` CLI. This namespace
+    # is the boundary: {Lockfile::Reader} parses an existing lock (read-only),
+    # {Lockfile::CliEngine} invokes the resolver/rewriter, {Lockfile::Env} builds
+    # the subprocess env, and {Lockfile::VersionGate} rejects unsupported schemas.
+    module Lockfile
+      extend T::Sig
+    end
+  end
+end
+
+require "dependabot/github_actions/lockfile/errors"
+require "dependabot/github_actions/lockfile/reader"
+require "dependabot/github_actions/lockfile/version_gate"
+require "dependabot/github_actions/lockfile/env"
+require "dependabot/github_actions/lockfile/cli_engine"

data/lib/dependabot/github_actions/package/package_details_fetcher.rb

@@ -31,7 +31,8 @@ module Dependabot
             credentials: T::Array[Dependabot::Credential],
             ignored_versions: T::Array[String],
             raise_on_ignored: T::Boolean,
-            security_advisories: T::Array[Dependabot::SecurityAdvisory]
+            security_advisories: T::Array[Dependabot::SecurityAdvisory],
+            git_metadata_fetcher: T.nilable(Dependabot::GitMetadataFetcher)
           ).void
         end
         def initialize(
@@ -39,13 +40,15 @@ module Dependabot
           credentials:,
           ignored_versions: [],
           raise_on_ignored: false,
-          security_advisories: []
+          security_advisories: [],
+          git_metadata_fetcher: nil
         )
           @dependency = dependency
           @credentials = credentials
           @raise_on_ignored = raise_on_ignored
           @ignored_versions = ignored_versions
           @security_advisories = security_advisories
+          @git_metadata_fetcher = git_metadata_fetcher
 
           @git_helper = T.let(git_helper, Dependabot::GithubActions::Helpers::Githelper)
         end
@@ -123,7 +126,10 @@ module Dependabot
               ref = git_commit_checker.local_ref_for_latest_version_matching_existing_precision
               return ref if ref && ref.fetch(:version) > current_version
 
-              git_commit_checker.local_ref_for_latest_version_lower_precision
+              lower_precision_ref = git_commit_checker.local_ref_for_latest_version_lower_precision
+              return ref if ref&.fetch(:version) == current_version
+
+              lower_precision_ref
             end,
             T.nilable(T::Hash[Symbol, T.untyped])
           )
@@ -270,7 +276,8 @@ module Dependabot
             ignored_versions: ignored_versions,
             raise_on_ignored: raise_on_ignored,
             consider_version_branches_pinned: false,
-            dependency_source_details: nil
+            dependency_source_details: nil,
+            git_metadata_fetcher: @git_metadata_fetcher
           )
         end
       end

data/lib/dependabot/github_actions/update_checker/latest_version_finder.rb

@@ -32,7 +32,8 @@ module Dependabot
             security_advisories: T::Array[Dependabot::SecurityAdvisory],
             raise_on_ignored: T::Boolean,
             options: T::Hash[Symbol, T.untyped],
-            cooldown_options: T.nilable(Dependabot::Package::ReleaseCooldownOptions)
+            cooldown_options: T.nilable(Dependabot::Package::ReleaseCooldownOptions),
+            git_metadata_fetcher: T.nilable(Dependabot::GitMetadataFetcher)
           ).void
         end
         def initialize(
@@ -43,7 +44,8 @@ module Dependabot
           security_advisories:,
           raise_on_ignored:,
           options: {},
-          cooldown_options: nil
+          cooldown_options: nil,
+          git_metadata_fetcher: nil
         )
           @dependency          = dependency
           @dependency_files    = dependency_files
@@ -53,9 +55,19 @@ module Dependabot
           @raise_on_ignored    = raise_on_ignored
           @options             = options
           @cooldown_options = cooldown_options
+          @git_metadata_fetcher = git_metadata_fetcher
 
           @git_helper = T.let(git_helper, Dependabot::GithubActions::Helpers::Githelper)
-          super
+          super(
+            dependency: dependency,
+            dependency_files: dependency_files,
+            credentials: credentials,
+            ignored_versions: ignored_versions,
+            security_advisories: security_advisories,
+            raise_on_ignored: raise_on_ignored,
+            options: options,
+            cooldown_options: cooldown_options
+          )
         end
 
         sig { returns(Dependabot::Dependency) }
@@ -150,7 +162,8 @@ module Dependabot
                           credentials: credentials,
                           ignored_versions: ignored_versions,
                           raise_on_ignored: raise_on_ignored,
-                          security_advisories: security_advisories
+                          security_advisories: security_advisories,
+                          git_metadata_fetcher: @git_metadata_fetcher
                         ),
             T.nilable(Dependabot::GithubActions::Package::PackageDetailsFetcher)
           )
@@ -363,7 +376,8 @@ module Dependabot
             ignored_versions: ignored_versions,
             raise_on_ignored: raise_on_ignored,
             consider_version_branches_pinned: false,
-            dependency_source_details: nil
+            dependency_source_details: nil,
+            git_metadata_fetcher: @git_metadata_fetcher
           )
         end
       end

data/lib/dependabot/github_actions/update_checker.rb

@@ -4,8 +4,10 @@
 require "sorbet-runtime"
 
 require "dependabot/errors"
+require "dependabot/git_metadata_fetcher"
 require "dependabot/github_actions/constants"
 require "dependabot/github_actions/containing_branch_finder"
+require "dependabot/github_actions/lockfile/reader"
 require "dependabot/github_actions/requirement"
 require "dependabot/github_actions/version"
 require "dependabot/update_checkers"
@@ -17,6 +19,8 @@ module Dependabot
     class UpdateChecker < Dependabot::UpdateCheckers::Base
       extend T::Sig
 
+      GitSource = T.type_alias { T::Hash[Symbol, String] }
+
       require_relative "update_checker/latest_version_finder"
 
       sig { override.returns(T.nilable(T.any(String, Gem::Version))) }
@@ -53,11 +57,16 @@ module Dependabot
         )
       end
 
+      sig { override.returns(T::Boolean) }
+      def up_to_date?
+        super && !onboarded_requirements_changed?
+      end
+
       sig { override.returns(T::Array[Dependabot::DependencyRequirement]) }
       def updated_requirements
         updated_reqs = dependency.requirements.map do |req|
-          source = req[:source]
-          updated = updated_ref(source)
+          source = T.cast(req.source, GitSource)
+          updated = updated_ref(source, onboarded: onboarded_requirement?(req))
           next req unless updated
 
           current = source[:ref]
@@ -65,8 +74,8 @@ module Dependabot
           # Maintain a short git hash only if it matches the latest
           if req[:type] == "git" &&
              git_commit_checker.ref_looks_like_commit_sha?(updated) &&
-             git_commit_checker.ref_looks_like_commit_sha?(current) &&
-             updated.start_with?(current)
+             git_commit_checker.ref_looks_like_commit_sha?(T.must(current)) &&
+             updated.start_with?(T.must(current))
             next req
           end
 
@@ -78,23 +87,118 @@ module Dependabot
 
       private
 
+      sig { params(requirements_to_unlock: T.nilable(Symbol)).returns(T::Boolean) }
+      def numeric_version_can_update?(requirements_to_unlock:)
+        return true if super
+        return false unless requirements_to_unlock == :own
+
+        onboarded_requirements_changed?
+      end
+
+      sig { returns(T::Boolean) }
+      def onboarded_requirements_changed?
+        dependency.requirements.zip(updated_requirements).any? do |current, updated|
+          onboarded_requirement?(current) && current != updated
+        end
+      end
+
+      # A requirement is "onboarded" when the repo carries an `actions.lock` that is
+      # authoritative for the requirement's workflow. Only onboarded requirements get
+      # per-source precision selection; everything else flows through the combined
+      # finder exactly as before, so non-onboarded repos see byte-identical behavior.
+      sig { params(req: Dependabot::DependencyRequirement).returns(T::Boolean) }
+      def onboarded_requirement?(req)
+        file = dependency_files.find { |f| f.name == req.file }
+        return false unless file
+        return false unless File.dirname(file.path.delete_prefix("/")) == WORKFLOW_DIRECTORY
+
+        reader = lockfile_reader
+        return false unless reader
+
+        reader.onboarded?(file.path.delete_prefix("/"))
+      end
+
+      sig { returns(T.nilable(Dependabot::GithubActions::Lockfile::Reader)) }
+      def lockfile_reader
+        return @lockfile_reader if defined?(@lockfile_reader)
+
+        @lockfile_reader = T.let(
+          Dependabot::GithubActions::Lockfile::Reader.from_files(dependency_files),
+          T.nilable(Dependabot::GithubActions::Lockfile::Reader)
+        )
+      end
+
       sig { returns(T.nilable(Dependabot::GithubActions::UpdateChecker::LatestVersionFinder)) }
       def latest_version_finder
         @latest_version_finder ||=
           T.let(
-            LatestVersionFinder.new(
-              dependency: dependency,
-              credentials: credentials,
-              dependency_files: dependency_files,
-              security_advisories: security_advisories,
-              ignored_versions: ignored_versions,
-              raise_on_ignored: raise_on_ignored,
-              cooldown_options: update_cooldown
-            ),
+            build_latest_version_finder(dependency),
             T.nilable(Dependabot::GithubActions::UpdateChecker::LatestVersionFinder)
           )
       end
 
+      # A finder scoped to a single requirement's source ref, so version selection
+      # precision-matches THAT ref (e.g. `v4.3.1` → latest 3-segment tag) instead of
+      # the combined dependency version (the lower of all refs, which flattens every
+      # requirement to the coarsest precision). Finders remain scoped per ref, but share
+      # one repository metadata fetcher. Falls back to the combined finder for sources
+      # whose ref is not a version (SHA / branch), where precision has no meaning.
+      sig { params(source: T.nilable(GitSource)).returns(LatestVersionFinder) }
+      def latest_version_finder_for(source)
+        ref = source&.fetch(:ref, nil)
+        return T.must(latest_version_finder) unless ref && version_class.correct?(ref)
+
+        @latest_version_finder_for ||= T.let({}, T.nilable(T::Hash[String, LatestVersionFinder]))
+        @latest_version_finder_for[ref] ||= build_latest_version_finder(per_source_dependency(source, ref))
+      end
+
+      sig { params(dep: Dependabot::Dependency).returns(LatestVersionFinder) }
+      def build_latest_version_finder(dep)
+        LatestVersionFinder.new(
+          dependency: dep,
+          credentials: credentials,
+          dependency_files: dependency_files,
+          security_advisories: security_advisories,
+          ignored_versions: ignored_versions,
+          raise_on_ignored: raise_on_ignored,
+          cooldown_options: update_cooldown,
+          git_metadata_fetcher: git_metadata_fetcher
+        )
+      end
+
+      sig { returns(Dependabot::GitMetadataFetcher) }
+      def git_metadata_fetcher
+        @git_metadata_fetcher ||= T.let(
+          Dependabot::GitMetadataFetcher.new(
+            url: T.must(
+              dependency.requirements.filter_map do |requirement|
+                T.cast(requirement.source, T.nilable(GitSource))&.fetch(:url, nil)
+              end.first
+            ),
+            credentials: credentials
+          ),
+          T.nilable(Dependabot::GitMetadataFetcher)
+        )
+      end
+
+      # A synthetic single-requirement dependency whose version mirrors the precision
+      # of `source[:ref]`. The downstream precision machinery keys entirely off
+      # `dependency.version`, so this is what makes per-source precision selection work
+      # without touching the shared combined dependency reported up to the rest of the
+      # update.
+      sig do
+        params(source: GitSource, ref: String)
+          .returns(Dependabot::Dependency)
+      end
+      def per_source_dependency(source, ref)
+        Dependabot::Dependency.new(
+          name: dependency.name,
+          version: Dependabot::GithubActions::Version.remove_leading_v(ref).to_s,
+          requirements: [{ requirement: nil, groups: [], source: source, file: nil, metadata: {} }],
+          package_manager: dependency.package_manager
+        )
+      end
+
       sig { returns(T::Array[Dependabot::SecurityAdvisory]) }
       def active_advisories
         security_advisories.select do |advisory|
@@ -143,12 +247,17 @@ module Dependabot
         )
       end
 
-      sig { params(source: T.nilable(T::Hash[Symbol, String])).returns(T.nilable(String)) }
-      def updated_ref(source)
+      sig do
+        params(source: T.nilable(GitSource), onboarded: T::Boolean)
+          .returns(T.nilable(String))
+      end
+      def updated_ref(source, onboarded: false)
         # TODO: Support Docker sources
         return unless git_commit_checker.git_dependency?
 
-        if vulnerable? && (new_tag = T.must(latest_version_finder).lowest_security_fix_release)
+        finder = onboarded ? latest_version_finder_for(source) : T.must(latest_version_finder)
+
+        if vulnerable? && (new_tag = finder.lowest_security_fix_release)
           return new_tag.fetch(:tag)
         end
 
@@ -156,13 +265,13 @@ module Dependabot
 
         # Return the git tag if updating a pinned version
         if source_git_commit_checker.pinned_ref_looks_like_version? &&
-           (new_tag = T.must(latest_version_finder).latest_version_tag_respecting_cooldown)
+           (new_tag = finder.latest_version_tag_respecting_cooldown)
           return new_tag.fetch(:tag)
         end
 
         # Return the pinned git commit if one is available
         if source_git_commit_checker.pinned_ref_looks_like_commit_sha? &&
-           (new_commit_sha = latest_commit_sha(source_git_commit_checker))
+           (new_commit_sha = latest_commit_sha(source_git_commit_checker, finder))
           return new_commit_sha
         end
 
@@ -170,17 +279,20 @@ module Dependabot
         nil
       end
 
-      sig { params(source_checker: Dependabot::GitCommitChecker).returns(T.nilable(String)) }
-      def latest_commit_sha(source_checker)
-        latest_tag = T.must(latest_version_finder).latest_version_tag
+      sig do
+        params(source_checker: Dependabot::GitCommitChecker, finder: LatestVersionFinder)
+          .returns(T.nilable(String))
+      end
+      def latest_commit_sha(source_checker, finder)
+        latest_tag = finder.latest_version_tag
         return unless latest_tag
 
         if source_checker.local_tag_for_pinned_sha
-          new_tag = T.must(latest_version_finder).latest_version_tag_respecting_cooldown
+          new_tag = finder.latest_version_tag_respecting_cooldown
           new_tag&.fetch(:commit_sha)
         else
           # Keep SHA rewrites aligned with the checker decision (including cooldown filtering).
-          latest = latest_version
+          latest = finder.latest_release_version
           latest.is_a?(String) ? latest : latest_commit_for_pinned_ref
         end
       end
@@ -198,7 +310,8 @@ module Dependabot
           ignored_versions: ignored_versions,
           raise_on_ignored: raise_on_ignored,
           consider_version_branches_pinned: false,
-          dependency_source_details: nil
+          dependency_source_details: nil,
+          git_metadata_fetcher: git_metadata_fetcher
         )
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dependabot-github_actions
 version: !ruby/object:Gem::Version
-  version: 0.389.0
+  version: 0.390.0
 platform: ruby
 authors:
 - Dependabot
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.389.0
+        version: 0.390.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.389.0
+        version: 0.390.0
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -248,6 +248,12 @@ files:
 - lib/dependabot/github_actions/file_parser.rb
 - lib/dependabot/github_actions/file_updater.rb
 - lib/dependabot/github_actions/helpers.rb
+- lib/dependabot/github_actions/lockfile.rb
+- lib/dependabot/github_actions/lockfile/cli_engine.rb
+- lib/dependabot/github_actions/lockfile/env.rb
+- lib/dependabot/github_actions/lockfile/errors.rb
+- lib/dependabot/github_actions/lockfile/reader.rb
+- lib/dependabot/github_actions/lockfile/version_gate.rb
 - lib/dependabot/github_actions/metadata_finder.rb
 - lib/dependabot/github_actions/package/package_details_fetcher.rb
 - lib/dependabot/github_actions/package_manager.rb
@@ -260,7 +266,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dependabot/dependabot-core/issues
-  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.389.0
+  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.390.0
 rdoc_options: []
 require_paths:
 - lib