[Advanced]: Optimize .github/workflows/pr-check-examples.yml

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Python SDK codebase and its architectural patterns.

You should feel comfortable:

• navigating multiple modules across src/
• understanding and modifying core SDK abstractions
• reasoning about API design and backwards compatibility
• updating or extending tests, examples, and documentation as needed
• making changes that may affect public-facing behavior

New developers should start with
Good First Issues or Intermediate Issues first.

🐞 Problem Description

We use a script to run our examples and check they all work
.github/workflows/pr-check-examples.yml

We are using over 16,000 minutes/month on this workflow alone

We can optimize this to run fewer minutes/month, without losing usefulness/insight, ideally

The developer will need to research best practices on how to optimize this, given our use cases (the business need for this workflow).

💡 Proposed / Expected Solution

Edit
.github/workflows/pr-check-examples.yml

Spot instances of wasted resources, then optimize

The main improvements are to restrict the possible triggers, for example, there may be no need to run this file if we change documentation, or only run this check once a whole bunch of other workflows pass

Quite open to decisions on how to make the optimizations

🧠 Implementation & Design Notes

This requires some care and testing

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• be a DCO and GPG key signed as git commit -S -s -m "chore: my change" with a GPG key set up

📚 Additional Context, Links, or Prior Art

Optional.

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Add explicit path filters to trigger workflow only for changes to SDK source, examples, dependencies, and proto generation—skipping documentation, tests, and configuration changes
• Restrict push triggers to main branch only, relying on pull_request events for feature branch validation to eliminate duplicate runs
• Implement cancel-in-progress concurrency to automatically cancel stale workflow runs when new commits arrive
• Add timeout and reduce checkout depth as additional resource optimizations

Design Choices

Design Choice 1: Which paths should trigger the examples workflow?

Options Considered:

1. Use paths-ignore to exclude documentation paths (.md, docs/, etc.)
2. Use paths to explicitly include only code-relevant paths (src/, examples/, pyproject.toml, etc.)

Chosen Option: 2

Rationale: Explicit paths inclusion is more maintainable and clearly documents what triggers the workflow, reducing risk of missing new non-code paths in the future.

Design Choice 2: Should push triggers be restricted beyond path filtering?

Options Considered:

1. Keep push: branches: ["**"] with only path filtering
2. Restrict push to branches: [main] only, relying on pull_request trigger for feature branches

Chosen Option: 2

Rationale: Restricting push to main eliminates duplicate workflow runs (push + PR event) for feature branches while still ensuring examples are validated after merge.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Trigger Optimization

Modify the workflow triggers to only run when relevant code changes occur, eliminating unnecessary runs for documentation, test, and configuration file changes.

Task 1: Add Path Filtering to Triggers

Configure both push and pull_request triggers to only run when code paths that affect example execution are modified.

• Add paths: filter to the push trigger specifying: src/**, examples/**, pyproject.toml, uv.lock, generate_proto.py, and .github/workflows/pr-check-examples.yml
• Add identical paths: filter to the pull_request trigger
• Including the workflow file itself ensures changes to the workflow get validated

Task 2: Restrict Push Trigger Branch Scope

Limit push trigger to only the main branch to prevent duplicate runs for PRs and unnecessary runs for direct feature branch pushes.

• Change push: branches: ["**"] to push: branches: [main]
• Retain pull_request trigger without branch restrictions to catch all PR activity
• Retain workflow_dispatch for manual triggering capability

🤖 Prompt for AI agents

Modify the `on:` trigger section of `.github/workflows/pr-check-examples.yml` to
restrict when the workflow runs.

- In the `push:` trigger:
  - Change `branches: ["**"]` to `branches: [main]`
- Add a `paths:` filter listing: `src/**`, `examples/**`, `pyproject.toml`,
`uv.lock`, `generate_proto.py`, and `.github/workflows/pr-check-examples.yml`
- In the `pull_request:` trigger:
  - Add the same `paths:` filter with the identical list of paths
- Leave `workflow_dispatch:` unchanged to preserve manual triggering capability

Phase 2: Resource Management Configuration

Add concurrency controls and job-level settings to prevent resource waste from redundant or runaway jobs.

Task 1: Add Concurrency Configuration

Implement concurrency controls following the established pattern from pr-check-test-files.yml to cancel in-progress runs when new commits are pushed.

• Add top-level concurrency: block after the on: trigger section
• Configure group: using the pattern pr-checks-${{ github.workflow }}-${{ github.ref || github.run_id }} to create unique groups per branch
• Set cancel-in-progress: true to automatically cancel stale runs

Task 2: Optimize Job-Level Settings

Apply job-level optimizations to reduce resource consumption and add safety limits.

• Add timeout-minutes: 30 to the run-examples job to match the pattern established in pr-check-test.yml and prevent runaway jobs
• Change fetch-depth: 0 to fetch-depth: 1 in the checkout step since full git history is not required for running examples
• These changes reduce checkout time and ensure jobs don't run indefinitely

🤖 Prompt for AI agents

Add concurrency controls and job-level optimizations to
`.github/workflows/pr-check-examples.yml` to prevent resource waste.

- After the `on:` trigger section, insert a top-level `concurrency:` block:
- Set `group:` to `pr-checks-${{ github.workflow }}-${{ github.ref ||
github.run_id }}`
  - Set `cancel-in-progress: true`
- On the `run-examples` job definition, add `timeout-minutes: 30`
- In the checkout step, change `fetch-depth: 0` to `fetch-depth: 1`

Research

The repository uses GitHub Actions workflows in .github/workflows/ with various trigger patterns. The pr-check-examples.yml workflow currently has no path filtering and triggers on every push to every branch plus all PR events. Other workflows in the repo demonstrate path filtering patterns (pr-check-broken-links.yml filters on **/*.md, deps-check.yml filters on pyproject.toml) and concurrency patterns (pr-check-test-files.yml uses cancel-in-progress: true). The workflow runs 155 example Python scripts against a Hiero Solo test network, which is an expensive operation that shouldn't run for non-code changes.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Modify the `on:` trigger section of `.github/workflows/pr-check-examples.yml` to
restrict when the workflow runs.

- In the `push:` trigger:
  - Change `branches: ["**"]` to `branches: [main]`
- Add a `paths:` filter listing: `src/**`, `examples/**`, `pyproject.toml`,
`uv.lock`, `generate_proto.py`, and `.github/workflows/pr-check-examples.yml`
- In the `pull_request:` trigger:
  - Add the same `paths:` filter with the identical list of paths
- Leave `workflow_dispatch:` unchanged to preserve manual triggering capability
===============================================================================

Task: 2

Add concurrency controls and job-level optimizations to
`.github/workflows/pr-check-examples.yml` to prevent resource waste.

- After the `on:` trigger section, insert a top-level `concurrency:` block:
- Set `group:` to `pr-checks-${{ github.workflow }}-${{ github.ref ||
github.run_id }}`
  - Set `cancel-in-progress: true`
- On the `run-examples` job definition, add `timeout-minutes: 30`
- In the checkout step, change `fetch-depth: 0` to `fetch-depth: 1`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[exploreriii]

One idea is to append it as a new job on the success of integration tests, which use similar set ups
we can abstract some of that to eg .github/actions/setup-hiero-env/action.yml
https://github.com/hiero-ledger/hiero-sdk-python/pull/1895/changes
in this case we probably don't need to run the examples in a matrix, maybe we can just use latest python
trade offs need to be considered, a larger refactor of workflows is possible in this action

[rayank906]

Hi @exploreriii I'd love to be assigned and work on this issue.

[github-actions]

Hi @rayank906, I cannot assign you to this issue yet.

Why?
Advanced issues involve high-risk changes to the core codebase and require prior experience in this repository.

Requirement:

• Complete at least 1 'intermediate' issue (You have: 0)

Please check out our intermediate issues to build your experience first!

@rayank906

[exploreriii]

Hi @rayank906 sorry, if you are new here you will have to complete a good first issue first, you may need to be a little patient if we are running low on them 🥇

[tech0priyanshu]

/working