[Intermediate]: Investigate shared workflow/action strategy for GitHub bot scripts

[darshit2308]

🧩 Intermediate Friendly

This issue is a good fit for contributors who are already familiar with the Hiero C++ SDK and feel comfortable navigating the codebase.

Intermediate Issues often involve:

• Exploring existing implementations
• Understanding how different components work together
• Making thoughtful changes that follow established patterns

The goal is to support deeper problem-solving while keeping the task clear, focused, and enjoyable to work on.

Important

🧭 About Intermediate Issues

Intermediate Issues are a great next step for contributors who enjoy digging into the codebase and reasoning about how things work.

These issues often:

• Involve multiple related files or components
• Encourage investigation and understanding of existing behavior
• Leave room for thoughtful implementation choices
• Stay focused on a clearly defined goal

Other kinds of contributions — from beginner-friendly tasks to large system-level changes — are just as valuable and use different labels.

👾 Description of the Task

The C++ SDK workflows currently invoke local bot scripts directly from each workflow using actions/github-script. While this works well for a single repository, it makes future migration to shared automation harder because every repository would need to duplicate the same workflow and script execution structure.

Several workflows currently repeat the same execution pattern:

• Checkout default branch
• Run harden-runner
• Run actions/github-script
• Require a local .github/scripts/*.js handler

Relevant Files

Workflows

• .github/workflows/on-pr.yaml
• .github/workflows/on-pr-update.yaml
• .github/workflows/on-comment.yaml
• .github/workflows/on-pr-close.yaml
• .github/workflows/on-schedule-inactivity.yaml
• .github/workflows/on-pr-review-labels.yaml

Bot Handlers

• .github/scripts/bot-on-pr-open.js
• .github/scripts/bot-on-pr-update.js
• .github/scripts/bot-on-comment.js
• .github/scripts/bot-inactivity.js

💡 Proposed Approach

Re-scope this issue from an implementation refactor into a design investigation.

The goal is not to change the C++ SDK workflows yet. Instead, this task should evaluate whether a shared workflow/action wrapper is actually the right direction for the C++ bot workflows, given the constraints around pull_request_target, local composite actions, StepSecurity visibility, per-workflow differences, and the still-evolving hiero-hackers automation prototypes.

The output of this issue should be a recommendation, not code changes.

👩‍💻 Investigation Deliverables

• Identify the actual target among the current hiero-hackers automation prototypes, or document that no single target has been selected yet.
• Define the proposed wrapper/reusable workflow/action interface that SDK repositories would call, including expected inputs such as config path, automation name, token handling, and repository-specific policy.
• Investigate the StepSecurity impact and document whether step-security/harden-runner can remain visible in caller workflows, or whether wrapping it would likely reintroduce duplicate remediation PRs.
• Provide a concrete before/after example for one simple C++ workflow, such as .github/workflows/on-pr.yaml.
• Provide a concrete before/after example for one awkward C++ workflow, such as .github/workflows/on-pr-review-labels.yaml or .github/workflows/on-pr-close.yaml.
• Recommend whether this wrapper/refactor should proceed now, be deferred until the external automation repo/API is mature, or be replaced by a different approach such as keeping workflow wiring local while moving reusable logic into a central action/app.

✔️ Acceptance Criteria

• The issue documents the selected or likely target automation prototype, or clearly states that the target is still undecided.
• The proposed caller interface is described clearly enough for maintainers to evaluate.
• StepSecurity behavior is explicitly addressed.
• At least one simple workflow before/after is included.
• At least one awkward workflow before/after is included.
• The final recommendation clearly states whether implementation should proceed, be deferred, or change direction.
• No production workflow or bot behavior changes are made as part of this issue.

---

📋 Step-by-Step Contribution Guide

To help keep contributions consistent and easy to review, we recommend following these steps:

• Comment /assign to request the issue
• Wait for assignment
• Fork the repository and create a branch
• Set up the project using the instructions in README.md
• Make the requested changes
• Sign each commit using -s -S
• Push your branch and open a pull request

Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.

❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.

🤔 Additional Information

This issue was originally opened as a preparatory workflow refactor. Based on maintainer feedback, it is now scoped as an investigation so the project can decide whether a shared wrapper/action approach is worthwhile before changing production C++ SDK workflows.

[rwalworth]

Thanks for putting this together @darshit2308, and for the broader push on the bot/automation cleanup - I can see you're thinking carefully about reuse across SDKs, which is a direction we do care about. Before we move this forward I want to flag some history and context that constrains how this refactor can actually look.

1. The obvious wrapper approach has already been tried in this repo and reverted. We had a local composite action at .github/actions/setup-bot/action.yml that bundled the harden-runner + checkout boilerplate - essentially what the "lightweight wrapper" in your proposal would be. It broke every bot run with:

Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '.github/actions/setup-bot'. Did you forget to run actions/checkout before running your local action?

The root cause is structural: bot workflows use pull_request_target (and issue_comment), which doesn't auto-checkout the repo. A local composite action requires its file to be on disk before GitHub can load it, but the action was the checkout - chicken-and-egg. I inlined the steps back into every workflow in #1189. So local composite actions are a no-go for these workflows. That really only leaves us two options:

• Same-repo reusable workflows (uses: ./.github/workflows/foo.yml) - these do work with pull_request_target because GitHub resolves them before the job starts. But they're job-level only, so each caller becomes a single uses: line pointing at a fully-defined job. That makes it harder to vary per-workflow differences (e.g. the download-artifact step in on-pr-review-labels.yaml, the two-job structure of on-pr-close.yaml).
• Remote actions/workflows hosted in some external sdk-automations repo - which brings me to the next point.

2. Hiding harden-runner behind a wrapper resurrects StepSecurity PR noise. This isn't theoretical - we can see it in repo history. While the setup-bot composite action existed (Feb 20–24), it contained the harden-runner step, but StepSecurity opened #1187 the same day #1167 landed, and #1191 the day after - both saying "add harden-runner to these workflows," targeting the caller files (on-comment.yaml, on-commit.yaml, on-pr.yaml). Both got closed unmerged. Since #1189 inlined the steps back, StepSecurity has been silent on this for ~2.5 months. The bot scans each .github/workflows/*.yaml file individually and doesn't follow uses: into local composite actions; I expect the same is true for reusable workflows referenced via uses: ./.github/workflows/foo.yml, though we haven't tested it. Any wrapper design that removes the literal step-security/harden-runner line from the caller workflow files will silently re-open that PR firehose. The issue's acceptance criterion "the refactor does not change contributor-facing bot behavior" would be silently violated by a steady drip of unwanted StepSecurity PRs the maintainer team has to triage.

3. The target repo is too early to design against. I assume you mean hiero-hackers/sdk-automations - the hiero-analytics/sdk-automations reference in the issue doesn't resolve. The actual repo:

• is 10 days old (created 2026-05-01) and hasn't been pushed to since creation;
• contains only a LICENSE and a 73-byte README.md - no workflows yet;
• is scoped per its description to "callable workflows that the python sdk can call," i.e. Python first, not C++;
• lives in hiero-hackers, a community/prototype org separate from hiero-ledger, which currently has five concurrent prototypes for this problem space (sdk-automations, hiero-workflow-orchestrator, hiero-hybrid-workflow-app, hiero-maintainer-automation-prototype, analytics).

I know you have a fork of it, so I imagine you're closer to the direction than I am - could you point me at whichever of those five prototypes is the actual chosen target, and any design doc on the wrapper interface? Without knowing which one we're preparing for (and what its shape will be), I don't want to bake a specific assumption into our production workflows in the official-org repo.

4. The per-workflow differences are larger than the shared boilerplate. Across the six workflows, the repeated portion is ~5–8 lines per file (harden-runner + checkout + github-script), but the differences (event types, permissions, concurrency keys, if: guards, checkout refs, the unique download-artifact step in on-pr-review-labels.yaml, the two-job structure of on-pr-close.yaml) are meaningful. Especially given the constraints in points 1 and 2, a wrapper that parameterizes all of that risks being longer than what we have today. I'd want to see a concrete before/after for at least two workflows - one simple (e.g. on-pr.yaml) and one awkward (e.g. on-pr-review-labels.yaml or on-pr-close.yaml) - before committing to this approach.

5. We just did a structural refactor here. #1167 ("Refactor bot workflows to one script per GitHub event") closed in February, and the current shape is the deliberate result of it. I'd want a stronger case than "future migration" before another structural pass.

6. Triage this with the rest of the cluster. This is one of five issues you opened on the same day (#1625, #1626, #1627, #1628, #1629), and #1634 is already in flight for #1625. @exploreriii left a lot of "should we also abstract X" review comments on #1634 and explicitly said they're waiting on my direction. Before we add more parallel refactors in this area, I'd like to land #1634 (or decide it needs reshaping) and then talk about the overall direction across all five issues as one decision rather than five.

I'm going to leave this open for discussion for now. Once #1634 settles, we have a clear pointer to which hiero-hackers prototype is the real target (and its API shape), and a concrete plan for keeping StepSecurity quiet under whatever wrapper we pick, we can come back and decide whether this refactor is the right next step and what its scope should be. Appreciate the patience; your work in this area has been really useful, and I'd rather coordinate it than rush it.

[darshit2308]

Thanks Robert, this makes sense. I understand now that #1627 should not move directly into implementation.

The main correction from my side is that I treated the workflow wrapper as a preparatory refactor, but the target architecture is not settled enough yet for that. In particular:

• local composite actions are out of scope here because of the pull_request_target / checkout issue from fix: Inline setup-bot composite action into bot workflows #1189;
• step-security/harden-runner likely needs to remain explicit in caller workflows unless we have a tested way to avoid StepSecurity opening duplicate remediation PRs;
• hiero-analytics/sdk-automations was an incorrect reference from me. The public repo I can see is hiero-hackers/sdk-automations, but I agree that it is too early to treat that as the chosen production target or wrapper API
• the workflow differences may be more important than the small duplicated setup block.

I will not start implementation work on #1627 now. I think the right next step, after #1634 / #1625 settles, is to turn this into a small design investigation rather than a code refactor.

That investigation could include:

1. the actual chosen target among the current prototypes, if one has been selected;
2. the proposed wrapper/reusable workflow interface;
3. a StepSecurity plan showing whether harden-runner can remain visible in caller workflows;
4. a concrete before/after for one simple workflow (on-pr.yaml);
5. a concrete before/after for one awkward workflow (on-pr-review-labels.yaml or on-pr-close.yaml);
6. a recommendation on whether this wrapper is worth doing at all, or whether the current explicit workflow structure should stay until the external automation repo/API is mature.

For now I’ll treat #1627 as parked behind #1634 and the broader #1625-#1629 direction discussion. Thanks for the detailed history; this helps me avoid making a clean-looking refactor that would create operational noise for maintainers.

[rwalworth]

Quick update: #1634 merged, so #1625 is closed and the bot policy/config layer is in.

@darshit2308 - your proposed re-scope from a code refactor to a design investigation is exactly the shape I want for this one, and the six deliverables you listed are a good definition of done. The two open dependencies (which of the hiero-hackers prototypes is the real target, and whether StepSecurity can be kept quiet under a wrapper) don't need to be resolved before the investigation starts - answering them is part of the deliverable.

When you have time, please update the issue description to reflect this - i.e. replace the "Proposed Approach / Implementation Steps / Acceptance Criteria" sections with the design-investigation scope (those six items as the deliverables, with the output being a recommendation rather than code changes). Once it's updated I'll re-triage it for skill/priority and move it off needs-info. Same arrangement as #1629.

No rush, and thanks again for the careful engagement on this cluster.

[darshit2308]

Thanks @rwalworth , I’ve updated the issue description to reflect the design-investigation scope and the six deliverables, with the output being a recommendation rather than code changes.

[rwalworth]

Thanks @darshit2308 - the new description looks good, and the explicit "no production workflow or bot behavior changes" line is a nice scope guardrail.

The investigation findings and recommendation should be posted as a comment on this issue. Keeping it here lets reviewers refine the recommendation in-thread. Once the direction is settled, we'll open a separate implementation issue that links back to the discussion here with the decided-upon approach.

I'm triaging this as Intermediate difficulty with low priority - intermediate because producing a credible recommendation needs comfort with GitHub Actions internals, StepSecurity behavior, and pull_request_target semantics, plus the judgment to compare wrapper shapes against per-workflow differences; low because nothing user-facing depends on the outcome and the external automation target isn't moving yet, so there's no time pressure.

Given you're already deep in this context @darshit2308, I'll go ahead and assign you. If you're not interested in taking this on at the moment, feel free to comment "/unassign" and another contributor can pick it up.