docs: create workflow best practices guide

[ambicuity]

Fixes #1743

Description

Creates docs/workflows/03-workflow-best-practices.md — a comprehensive best practices guide for writing and maintaining GitHub Actions workflows and their companion scripts.

Structure

The guide covers 10 key principles:

1. Separate the workflow from the logic — orchestration vs. logic pattern
2. Avoid hardcoding — use environment variables passed from YAML to scripts
3. Secrets handling — never log, transform, or pass unnecessarily
4. Permissions — default to read, escalate only when required
5. Log for debugging — structured, prefixed logs with exit reasons
6. Error handling — expected, operational, and system failure tiers
7. Notify users — inform on failures, tag maintainers when automation can't decide
8. Safety rules — SHA pinning, input validation, destructive action guards
9. Concurrency — concurrency groups to prevent race conditions
10. Testing and dry runs — fork testing, dry-run techniques, local testing

Includes a quick-reference checklist table and cross-references to existing documentation:

• 01-what-are-workflows.md
• 02-architecture.md
• how-to-pin-github-actions.md
• testing_forks.md

Acceptance Criteria

• Fully addresses Issue [Intermediate]: Create docs/github/03-workflow-best-practices.md #1743
• Follows existing docs conventions (matches 01/02 format)
• Valid changelog entry
• DCO and GPG signed commit

[Copilot]

Pull request overview

This PR creates a comprehensive best practices guide for writing and maintaining GitHub Actions workflows, addressing Issue #1743. The guide serves as the third installment in the workflow documentation series, providing practical guidance for contributors and maintainers on creating safe, maintainable, and debuggable automation.

Changes:

• Added docs/workflows/03-workflow-best-practices.md covering 10 key principles for workflow development (orchestration vs logic separation, environment variables, secrets handling, permissions, logging, error handling, user notifications, safety rules, concurrency, and testing)
• Updated CHANGELOG.md to document the new workflow best practices guide under the Docs section

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/workflows/03-workflow-best-practices.md	Comprehensive best practices guide covering workflow safety, maintainability, and testing with code examples, cross-references to existing docs, and a quick-reference checklist
CHANGELOG.md	Added changelog entry documenting the new workflow best practices guide under the Docs section

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

Walkthrough

This PR adds a new workflow best practices documentation file and an Unreleased CHANGELOG entry; there are no code or behavioral changes.

Changes

Cohort / File(s)	Summary
Changelog CHANGELOG.md	Added an Unreleased docs entry referencing the new workflow best practices guide.
Workflow Best Practices Guide docs/workflows/03-workflow-best-practices.md	New comprehensive guide added covering separation of workflow and logic, environment variables, secrets handling, minimal permissions, structured logging, error handling, user notifications, safety rules (pin actions, input validation, destructive-action checks, avoid pull_request_target), concurrency controls, testing and dry-run strategies (fork testing, dry runs, local testing), examples, and checklists.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'docs: create workflow best practices guide' directly and accurately summarizes the main change—adding a new documentation file for workflow best practices.
Description check	✅ Passed	The PR description is well-detailed and clearly related to the changeset, explaining the new documentation file, its structure covering 10 principles, and acceptance criteria alignment.
Linked Issues check	✅ Passed	The PR fully addresses Issue #1743 by creating the required best-practices guide covering all 10 key principles, safety rules, testing strategies, and including a checklist with cross-references to related docs.
Out of Scope Changes check	✅ Passed	All changes are directly in scope: CHANGELOG.md entry and the new docs/workflows/03-workflow-best-practices.md file align with Issue #1743 objectives with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

[ambicuity]

Thanks for the detailed reviews! All feedback has been addressed in the latest push:

#	Feedback	Fix
1	actions/github-script v7.0.1 → v8.0.0 (CodeRabbit)	✅ Updated SHA to ed597411...
2	Invalid YAML in secrets example (CodeRabbit)	✅ Fixed — now uses step-level env: under - run:
3	Add pull_request_target security warning (CodeRabbit)	✅ Added to Section 8 with dangerous/safe patterns
4	behaviour → behavior x4 (Copilot)	✅ American spelling throughout
5	Minimise → Minimize (Copilot)	✅ Fixed
6	dry-run → dry_run input naming (Copilot)	✅ Matches codebase convention (bot-intermediate-assignment.yml)
7	Hyphenate "decision-making" (CodeRabbit)	✅ Fixed

@aceppaluni — Regarding the pull_request_target addition: I agree it's important to document. The new subsection warns against checking out fork code inside pull_request_target workflows (which would execute attacker-controlled code with write permissions). It includes a ❌ dangerous pattern example and guidance on when/how pull_request_target can be used safely.

Also rebased onto main.

[MonaaEid]

That's really nice work! Could you please comment on the issue to be assigned?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@           Coverage Diff           @@
##             main    #1822   +/-   ##
=======================================
  Coverage   93.29%   93.29%           
=======================================
  Files         141      141           
  Lines        9119     9119           
=======================================
  Hits         8508     8508           
  Misses        611      611           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[exploreriii]

Hi @ambicuity could you please rebase, we have some problems merging this

[coderabbitai]

Actionable comments posted: 1

[exploreriii]

@hiero-ledger/hiero-sdk-python-committers please merge when tests pass

[AntonioCeppellini]

Nice work! @ambicuity