fix/wait for check discovery (#139)

Author: jgallinari

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## v1.5.1 - 2026-03-25
+
+### Added
+
+- Add `checks-discovery-timeout` option to poll for checks that haven't been created yet (e.g. jobs with `needs` dependencies) (#137)
+
 ## v1.5.0 - 2026-01-25
 
 ### Added

action.yml

@@ -44,6 +44,10 @@ inputs:
     description: "Fail the action if no checks match the check-name or check-regexp filters"
     required: false
     default: true
+  checks-discovery-timeout:
+    description: "Seconds to wait for checks to be discovered before failing (useful for jobs with needs dependencies)"
+    required: false
+    default: "60"
 
 runs:
   using: "composite"
@@ -72,6 +76,7 @@ runs:
         RUNNING_WORKFLOW_NAME: ${{ inputs.running-workflow-name }}
         API_ENDPOINT: ${{ inputs.api-endpoint }}
         FAIL_ON_NO_CHECKS: ${{ inputs.fail-on-no-checks }}
+        CHECKS_DISCOVERY_TIMEOUT: ${{ inputs.checks-discovery-timeout }}
 
 branding:
   icon: "check-circle"

app/services/github_checks_verifier.rb

@@ -20,6 +20,7 @@ class GithubChecksVerifier < ApplicationService
   config_accessor(:fail_on_no_checks) { true }
   config_accessor(:ignore_checks) { [] }
   config_accessor(:verbose) { true }
+  config_accessor(:discovery_timeout) { 60 }
   config_accessor(:wait) { 30 }
   config_accessor(:workflow_name) { '' }
 
@@ -73,6 +74,18 @@ def apply_regexp_filter(checks)
     checks.select! { |check| check.name[Regexp.new(check_regexp)] } if check_regexp.present?
   end
 
+  def wait_for_check_discovery(all_checks)
+    return all_checks unless filters_present? && all_checks.blank? && fail_on_no_checks
+
+    wait_until = Time.now + discovery_timeout
+    while all_checks.blank? && Time.now < wait_until
+      puts "Matching checks have not been found yet, will check again in #{wait} seconds. " \
+           "(Limit: #{discovery_timeout}s)"
+      all_checks = (sleep(wait) && query_check_status)
+    end
+    all_checks
+  end
+
   def all_checks_complete(checks)
     checks.all? { |check| check.status == 'completed' }
   end
@@ -110,8 +123,7 @@ def show_checks_conclusion_message(checks)
   end
 
   def wait_for_checks
-    all_checks = query_check_status
-
+    all_checks = wait_for_check_discovery(query_check_status)
     fail_if_requested_check_never_run(all_checks)
 
     until all_checks_complete(all_checks)

entrypoint.rb

@@ -16,6 +16,7 @@
 api_endpoint = ENV.fetch('API_ENDPOINT', '')
 ignore_checks = ENV.fetch('IGNORE_CHECKS', nil)
 fail_on_no_checks = ENV.fetch('FAIL_ON_NO_CHECKS', 'true')
+discovery_timeout = ENV.fetch('CHECKS_DISCOVERY_TIMEOUT', '60')
 
 GithubChecksVerifier.configure do |config|
   config.allowed_conclusions = allowed_conclusions.split(',').map(&:strip)
@@ -31,6 +32,7 @@
   config.wait = wait.to_i
   config.workflow_name = workflow_name
   config.fail_on_no_checks = fail_on_no_checks == 'true'
+  config.discovery_timeout = discovery_timeout.to_i
 end
 
 GithubChecksVerifier.call

spec/services/github_checks_verifier_spec.rb

@@ -106,6 +106,7 @@
   describe '#fail_if_requested_check_never_run' do
     it 'raises an exception if check_name is not empty and all_checks is' do
       service.config.check_name = 'test'
+      service.config.discovery_timeout = 0
 
       all_checks = []
       allow(service).to receive(:query_check_status).and_return all_checks
@@ -149,6 +150,7 @@
       it 'raises an exception when check_regexp is set and no checks match' do
         service.config.check_regexp = 'non-matching-regexp'
         service.config.fail_on_no_checks = true
+        service.config.discovery_timeout = 0
 
         all_checks = []
         allow(service).to receive(:query_check_status).and_return all_checks
@@ -160,6 +162,7 @@
       it 'raises an exception when check_name is set and no checks match' do
         service.config.check_name = 'non-existing-check'
         service.config.fail_on_no_checks = true
+        service.config.discovery_timeout = 0
 
         all_checks = []
         allow(service).to receive(:query_check_status).and_return all_checks
@@ -170,6 +173,64 @@
     end
   end
 
+  describe '#wait_for_check_discovery' do
+    before do
+      service.config.ref = '_'
+      service.config.client.access_token = '_'
+    end
+
+    it 'polls until checks are found within the timeout' do
+      service.config.check_name = 'delayed-check'
+      service.config.fail_on_no_checks = true
+      service.config.discovery_timeout = 30
+      service.wait = 0
+
+      completed_check = [Helpers::CheckRun.new(name: 'delayed-check', status: 'completed', conclusion: 'success')]
+      call_count = 0
+      allow(service).to receive(:query_check_status) do
+        call_count += 1
+        call_count < 3 ? [] : completed_check
+      end
+
+      output = with_captured_stdout { service.call }
+      expect(output).to include('Matching checks have not been found yet')
+    end
+
+    it 'logs discovery message when fail_on_no_checks is false' do
+      service.config.check_name = 'non-existing-check'
+      service.config.fail_on_no_checks = false
+      service.config.discovery_timeout = 30
+
+      allow(service).to receive(:query_check_status).and_return []
+
+      output = with_captured_stdout { service.call }
+      expect(output).not_to include('Matching checks have not been found yet')
+    end
+
+    it 'succeeds immediately when fail_on_no_checks is false' do
+      service.config.check_name = 'non-existing-check'
+      service.config.fail_on_no_checks = false
+      service.config.discovery_timeout = 30
+
+      allow(service).to receive(:query_check_status).and_return []
+
+      output = with_captured_stdout { service.call }
+      expect(output).to include('No checks found matching the filter, but fail-on-no-checks is false')
+    end
+
+    it 'fails after discovery timeout is exceeded' do
+      service.config.check_name = 'never-found-check'
+      service.config.fail_on_no_checks = true
+      service.config.discovery_timeout = 0
+      service.wait = 0
+
+      allow(service).to receive(:query_check_status).and_return []
+
+      expected_msg = 'The requested check was never run against this ref, exiting...'
+      expect { service.call }.to raise_error(SystemExit).and output(/#{expected_msg}/).to_stdout
+    end
+  end
+
   describe '#fail_unless_all_conclusions_allowed' do
     it 'raises an exception if some check conclusion is not allowed' do
       all_checks = [