Add cicd.instructions.md style guide for GitHub Actions workflows

Agent-Logs-Url: https://github.com/MoonModules/WLED-MM/sessions/2198b03d-660a-40a6-ad60-17f948a038a2

Co-authored-by: softhack007 <91616163+softhack007@users.noreply.github.com>

Author: Copilot

.github/cicd.instructions.md

@@ -0,0 +1,153 @@
+---
+applyTo: ".github/workflows/*.yml,.github/workflows/*.yaml"
+---
+# CI/CD Conventions — GitHub Actions Workflows
+
+## YAML Style
+
+- Indent with **2 spaces** (no tabs)
+- Every workflow, job, and step must have a `name:` field that clearly describes its purpose
+- Group related steps logically; separate unrelated groups with a blank line
+- Comments (`#`) are encouraged for non-obvious decisions (e.g., why `fail-fast: false` is set, what a cron expression means)
+
+## Workflow Structure
+
+### Triggers
+
+- Declare `on:` triggers explicitly; avoid bare `on: push` without branch filters on long-running or expensive jobs
+- Prefer `workflow_call` for shared build logic (see `build.yml`) to avoid duplicating steps across workflows
+- Document scheduled triggers (`cron:`) with a human-readable comment:
+
+```yaml
+schedule:
+  - cron: '0 2 * * *'  # run at 2 AM UTC daily
+```
+
+### Jobs
+
+- Express all inter-job dependencies with `needs:` — never rely on implicit ordering
+- Use job `outputs:` + step `id:` to pass structured data between jobs (see `get_default_envs` in `build.yml`)
+- Set `fail-fast: false` on matrix builds so that a single failing environment does not cancel others
+
+### Runners
+
+- Pin to a specific Ubuntu version (`ubuntu-22.04`, `ubuntu-24.04`) rather than `ubuntu-latest` for reproducible builds
+- Only use `ubuntu-latest` in jobs where exact environment reproducibility is not required (e.g., trivial download/publish steps)
+
+### Tool and Language Versions
+
+- Pin tool versions explicitly:
+  ```yaml
+  python-version: '3.12'
+  ```
+- Do not rely on the runner's pre-installed tool versions — always install via a versioned setup action
+
+### Caching
+
+- Always cache package managers and build tool directories when the job installs dependencies:
+  ```yaml
+  - uses: actions/cache@v4
+    with:
+      path: ~/.cache/pip
+      key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+      restore-keys: |
+        ${{ runner.os }}-pip-
+  ```
+- Include the environment name or a relevant identifier in cache keys when building multiple targets
+
+### Artifacts
+
+- Name artifacts with enough context to be unambiguous (e.g., `firmware-${{ matrix.environment }}`)
+- Avoid uploading artifacts that will never be consumed downstream
+
+---
+
+## Security
+
+### Permissions — Least Privilege
+
+Declare explicit `permissions:` blocks. The default token permissions are broad; scope them to the minimum required:
+
+```yaml
+permissions:
+  contents: read       # for checkout
+```
+
+For jobs that publish releases or write to the repository:
+
+```yaml
+permissions:
+  contents: write      # create/update releases
+```
+
+A common safe baseline for build-only jobs:
+
+```yaml
+permissions:
+  contents: read
+```
+
+### Supply Chain — Action Pinning
+
+**Third-party actions** (anything outside the `actions/` and `github/` namespaces) should be pinned to a specific release tag. Branch pins (`@main`, `@master`) are **not allowed** — they can be updated by the action author at any time without notice:
+
+```yaml
+# ✅ Acceptable — specific version tag
+uses: softprops/action-gh-release@v2
+
+# ❌ Not acceptable — mutable branch reference
+uses: andelf/nightly-release@main
+```
+
+SHA pinning (e.g., `uses: someorg/some-action@abc1234`) is the most secure option for third-party actions; it is recommended when auditing supply-chain risk is a priority. At minimum, always use a specific version tag.
+
+**First-party actions** (`actions/checkout`, `actions/cache`, `actions/upload-artifact`, etc.) pinned to a major version tag (e.g., `@v4`) are acceptable because GitHub maintains and audits these.
+
+When adding a new third-party action:
+1. Check that the action's repository is actively maintained
+2. Review the action's source before adding it
+3. Prefer well-known, widely-used actions over obscure ones
+
+### Credentials and Secrets
+
+- Use `${{ secrets.GITHUB_TOKEN }}` for operations within the same repository — it is automatically scoped and rotated
+- Never commit secrets, tokens, or passwords into workflow files or any tracked file
+- Never print secrets in `run:` steps, even with `echo` — GitHub masks known secrets but derived values are not automatically masked
+- Scope secrets to the narrowest step that needs them using `env:` at the step level, not at the workflow level:
+
+```yaml
+# ✅ Scoped to the step that needs it
+- name: Create release
+  uses: softprops/action-gh-release@v2
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+
+# ❌ Unnecessarily broad
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+- Personal Access Tokens (PATs, stored as repository secrets) should have the minimum required scopes and should be rotated periodically
+
+### Script Injection
+
+`${{ }}` expressions are evaluated before the shell script runs. If an expression comes from untrusted input (PR titles, issue bodies, branch names from forks), it can inject arbitrary shell commands.
+
+**Never** interpolate `github.event.*` values directly into a `run:` step:
+
+```yaml
+# ❌ Injection risk — PR title is attacker-controlled
+- run: echo "${{ github.event.pull_request.title }}"
+
+# ✅ Safe — value passed through an environment variable
+- env:
+    PR_TITLE: ${{ github.event.pull_request.title }}
+  run: echo "$PR_TITLE"
+```
+
+This rule applies to any value that originates outside the repository (issue bodies, labels, comments, commit messages from forks).
+
+### Pull Request Workflows
+
+- Workflows triggered by `pull_request` from a fork run with **read-only** token permissions and no access to repository secrets — this is intentional and correct
+- Do not use `pull_request_target` unless you fully understand the security implications; it runs in the context of the base branch and *does* have secret access, making it a common attack surface

.github/copilot-instructions.md

@@ -69,4 +69,4 @@ Main development branch: `mdev`
 - **PR reviews:** Authors do not need to commit `html_*.h` files; they are generated during firmware builds.
 - **Provide references** when making analyses or recommendations. Base them on the correct branch or PR.
 - **C++ formatting available**: `clang-format` is installed but not in CI
-- No automated linting is configured — match existing code style in files you edit. See `cpp.instructions.md` and `web.instructions.md` for language-specific conventions.
+- No automated linting is configured — match existing code style in files you edit. See `cpp.instructions.md` and `web.instructions.md` for language-specific conventions, and `cicd.instructions.md` for GitHub Actions workflows.