Description

The repository has 22+ GitHub Actions workflow files but no instructions for writing or modifying workflows. This means Copilot doesn't receive guidance on the repository's security requirements, dependency pinning standards, or workflow patterns when editing .yml files in .github/workflows/.

Current state:

• Workflow files: 22+ in .github/workflows/
• Security scripts: scripts/security/Test-DependencyPinning.ps1
• SHA validation: scripts/security/Test-SHAStaleness.ps1
• Copilot instructions: ❌ None for GitHub Actions

Acceptance Criteria

• Create .github/instructions/github-actions.instructions.md
• Include dependency pinning requirements (full SHA pins)
• Document actionlint validation requirements
• Include permissions best practices (least privilege)
• Include reusable workflow patterns
• Add applyTo: '**/.github/workflows/*.yml' glob pattern
• Follow frontmatter schema (instruction-frontmatter.schema.json)

Proposed Solution

File structure

---
description: "Required instructions for GitHub Actions workflow files"
applyTo: '**/.github/workflows/*.yml'
maturity: stable
---

# GitHub Actions Instructions

These instructions define workflow conventions enforced by actionlint and security validation in this codebase.

## Dependency Pinning

All action references MUST use full SHA pins, not version tags:

**Required:**
```yaml
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Not allowed:

uses: actions/checkout@v4
uses: actions/[email protected]

Version tag MUST appear in a trailing comment for readability.

Permissions

• Define explicit permissions: block at workflow or job level
• Use least-privilege principle (only request needed permissions)
• Never use permissions: write-all

Example:

permissions:
  contents: read
  pull-requests: write

Validation

Workflows must pass:

• actionlint - Syntax and best practice validation
• Test-DependencyPinning.ps1 - SHA pinning validation
• Test-SHAStaleness.ps1 - SHA freshness validation

Workflow Structure

• Use descriptive name: for workflows and jobs
• Group related jobs with needs: dependencies
• Use concurrency: to prevent duplicate runs
• Prefer reusable workflows for common patterns

Security

• Never expose secrets in logs
• Use GITHUB_TOKEN instead of PATs when possible
• Validate external inputs before use
• Use if: github.event_name == 'pull_request' guards appropriately

## Files to Create

| File | Purpose |
|------|---------|
| `.github/instructions/github-actions.instructions.md` | Copilot guidance for workflow files |

## References

- Security validation: `scripts/security/Test-DependencyPinning.ps1`
- SHA validation: `scripts/security/Test-SHAStaleness.ps1`
- Tool checksums: `scripts/security/tool-checksums.json`
- Existing workflows: `.github/workflows/`

## Time Estimate

1-2 hours