GitHub Actions Workflow Standard
This standard covers workflow files in .github/workflows/*.yml and.github/workflows/*.yaml. GitHub's [workflow syntax
reference](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
defines supported event, job, permission and step syntax. The [secure use
guide](https://docs.github.com/en/actions/how-tos/security-for-github-actions/security-guides)
covers platform security practices. Meridian policy below describes ownership
and review expectations rather than duplicating the full syntax reference.
YAML workflow files can carry a compact reference comment near the top:
# Public standard: https://agents.meridianstack.dev/standards/github-actions-workflows
Workflow ownership and reuse
Keep workflows as a thin repository-owned orchestration layer. Invoke stable
root commands and package-owned entrypoints instead of copying application
logic, provider operations or long shell programs into YAML. The repository
owns its workflow triggers, job graph and runner requirements; each package
owns its implementation and focused validation commands.
Use a reusable workflow for coherent job-level automation shared across
workflows. Use a composite action for reusable step sequences. GitHub requires
reusable workflows to be called from a job and located directly in.github/workflows; composite actions package steps for use inside a job.
See reusing workflow configurations.
Generated workflow files must be changed through their canonical source and
generator, not edited in place.
Permissions and references
Grant GITHUB_TOKEN only the permissions the workflow or job needs. Prefer
job-level permissions when jobs have different requirements, and explicitly
use no permissions where a job needs no token access. Treat events that expose
untrusted contributions differently from trusted repository events; do not
combine privileged write access with untrusted code execution without a
reviewed design.
Pin third-party actions and reusable workflows to reviewed immutable commit
SHAs where the repository's supply-chain policy requires it. A tag is easier
to read but can move; a full commit SHA fixes the referenced revision. Keep
updates reviewable through the repository's declared dependency maintenance
path. GitHub platform or organisational enforcement may differ by repository;
check the applicable policy rather than assuming it from workflow syntax.
Secrets are not ordinary workflow inputs. Pass only the secrets needed by a
job, avoid printing them, and do not expose privileged credentials to
untrusted pull-request code. Prefer narrowly scoped, short-lived identity
flows supported by the target provider over long-lived credentials where the
deployment contract permits.
Validation and exceptions
Validate changed workflows with the repository's maintained workflow and
dependency checks, then run the root commands they invoke when practical.
Permission or action-pin exceptions need a concrete compatibility or trust
reason and an owner. Keep provider names, private workflow inventories,
credentials and account-specific operational detail out of public guidance.