---
public-agent: true
id: github-actions-workflows
title: GitHub Actions Workflow Standard
status: current
classification: public-agent-standard
safety: reviewed-public
---

# 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:

```yaml
# 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](https://docs.github.com/en/actions/concepts/workflows-and-actions/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.
