copilot-repo-template: Instructions file for GitHub Copilot

YAML Writing Style

Version: 1.7.20260923.0

Metadata

• Status: Active
• Owner: Repository Maintainers
• Last Updated: 2026-09-23
• Scope: Defines authoring standards for all YAML files in this repository, including GitHub Actions workflows, Azure Pipelines YAML, pre-commit configuration, linter configuration, and any other human-authored YAML configuration. Does not cover JSON files (covered by the companion JSON guide, if present) or generated YAML artifacts that are owned by another tool's serializer.
• Related: Repository Copilot Instructions

• Related baseline guidance: .gitattributes Rules

• Related JSON guidance: JSON Writing Style

Purpose and Scope

YAML in this repository is the preferred format for human-authored configuration that benefits from comments, multi-line strings, and a forgiving syntax for editors (workflow files, pre-commit configs, linter configs, application config files committed to source control). JSON is preferred for strict machine interchange and for generated artifacts (lock files, schema documents, tool outputs, structured data exchanged between systems).

To keep YAML safe to edit, easy to diff, and portable across parsers, this repository adopts a conservative, tool-friendly subset of YAML 1.2. Authors MUST prefer explicit, unambiguous constructs over clever or compact YAML features that vary by parser.

Note: This document uses RFC 2119 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) to indicate requirement levels.

Quick Reference Checklist

• [All] MUST use 2-space indentation; MUST NOT use tabs.
• [All] MUST use block style by default; SHOULD NOT use flow style for non-trivial structures.
• [All] MUST use lowercase true, false, and null; MUST NOT use yes/no/on/off (or capitalized variants) as booleans.
• [All] MUST quote values that could be misparsed as booleans, nulls, numbers, dates, or YAML 1.1 truthy tokens.
• [All] MUST quote version pins (for example, "3.13", "1.0") so they cannot be coerced to numbers.
• [All] SHOULD use double quotes only when escape sequences are needed; SHOULD use single quotes for literal regexes and Windows paths.
• [All] SHOULD use block scalars (|, >, |-, >-) for multi-line strings.
• [All] SHOULD NOT use anchors, aliases, merge keys, custom tags, or multi-document files unless required and supported by the consumer.
• [All] MUST NOT commit secrets in YAML.
• [Actions] MUST apply least-privilege permissions: on GitHub Actions workflows.
• [Actions] setup-* action with.*-version: inputs (for example, python-version, node-version, go-version, and dotnet-version) in workflow files under .github/workflows/ MUST resolve from checked-in release-line selectors and MUST NOT use a broad floating selector such as '3.x', 'latest', or '*'. The required granularity follows each ecosystem's release model: Python and Go MUST use major.minor (for example, "3.13" or "1.26"); Node.js MAY use major for an LTS line (for example, "24") or major.minor (for example, "24.17"); .NET MAY use the most specific stable SDK channel selector documented by actions/setup-dotnet, such as major.minor.x (for example, "10.0.x"); for other ecosystems, use the most specific stable release-line selector documented by the action's README.
• [Actions] actions/setup-node MAY instead use the guarded exact Node.js version-file exception. Its file, precedence, exactness, and verification conditions all apply.
• [AzurePipelines] Repositories that use Azure Pipelines language/runtime/SDK tool-installer tasks MUST explicitly provide checked-in compliant selectors for in-scope version or versionSpec inputs and MUST NOT rely on broad task defaults, queue-time-only values, "latest", bare "*", comparator/operator ranges, or composite ranges.
• [AzurePipelines] Azure Pipelines YAML MUST pass retained host-neutral local YAML hooks, and pipeline schema/branch-policy validation MUST be treated as Azure DevOps Services-backed validation rather than actionlint.
• [Actions] Documentation/navigation comments above uses: lines MUST use versionless upstream URLs; the uses: line remains the authoritative action version.
• [Actions] Comments documenting where a GitHub Actions with: tool-version input is pinned, or that such a value must stay aligned across files, SHOULD describe the membership criterion instead of a hardcoded workflow-file list; if a concrete file list is included for convenience, it SHOULD be labeled as a non-authoritative snapshot.
• [Actions] Optional workflow_dispatch string inputs that also need defaults on non-dispatch triggers SHOULD derive the effective value from a single source, using a fallback only in keys where the needed contexts are available, rather than duplicating an unmarked input default: and env: literal.
• [Schemas] Schema-backed YAML MUST pass any schema validator wired into pre-commit or CI; where no validator is wired up for a particular file family, authors SHOULD run the appropriate validator locally before committing.
• [Naming] YAML filenames SHOULD be lowercase kebab-case; GitHub Actions workflows MUST use the .yml extension; project-owned YAML MUST choose .yml or .yaml and use it consistently.
• [IssueForms] In .github/ISSUE_TEMPLATE/*.yml, repo-internal targets in both issue-form value: Markdown links (e.g., bug_report.yml) and config.yml contact_links url: fields MUST use absolute GitHub URLs such as https://github.com/<owner>/<repo>/blob/HEAD/<path> for file links; relative paths MUST NOT be used. Template repositories MAY ship unresolved live URLs using literal OWNER/REPO; other placeholder spellings MUST NOT serve that live role. Angle-bracket URL shapes here are schematic after substitution, and the final rendered URL still needs the real host, owner, and repository. The two file types fail for different reasons: value: Markdown blocks render at /{owner}/{repo}/issues/new?... so relative paths resolve against that URL and 404, while contact_links url: fields are not Markdown at all — GitHub validates them as absolute URLs at form-load time and rejects relative values outright.