Allowlisting and policy — controlling which actions are permitted

Pinning binds the workflow to specific bytes. Allowlisting decides which actions are permitted to be pinned. Pinning is a per-workflow discipline; allowlisting is an organisation-level policy. Pinning without allowlisting is deciding how to reference an action without deciding which actions to trust. Allowlisting without pinning is deciding which actions to trust without enforcing the reference form that keeps that trust intact. The two controls are complementary.

What allowlisting closes

Three risks remain after pinning every third-party action:

1. Unvetted actions. A new engineer adds an action that no one has reviewed.
2. Stale allowlist. An action was reviewed 18 months ago. The maintainer and dependencies have changed.
3. Cross-team drift. Different teams allow different actions.

flowchart LR
    A["Workflow PR"] --> B["Allowlist check"]
    B --> C{"Action permitted?"}
    C -->|yes| D["Pin check"]
    D --> E{"Full SHA?"}
    E -->|yes| F["Merge allowed"]
    E -->|no| G["Block - tag/branch"]
    C -->|no| H["Block - not on allowlist"]

Both blocks are mechanical; both are auditable.

The allowlist entry

Five fields:

• Owner. The GitHub user or organisation that maintains the action. The trust anchor.
• Repository. The specific repository the action lives in.
• Version range or pinned SHAs. The versions the team has reviewed. SHA ranges preferred over tag ranges.
• Reviewer. The team member who performed the review.
• Review cadence. The interval for re-review. Six months is a common default.

# Example allowlist entry - organisation settings
allowed_actions:
  - vendor/aws-actions/configure-aws-credentials
  - first-party/actions/checkout
  - first-party/actions/setup-node
  - reviewed/thirdparty/deploy-helper

Each entry is a record of intent: “the organisation considers this action safe to pin”.

Configuring the allowlist at organisation scale

Three levels:

• Repository. Each repo configures its own allowlist under Settings > Actions > General.
• Organisation. The org configures a default allowlist for every repo unless overridden.
• Enterprise. The enterprise configures a policy for every org.

For consistent enforcement, the organisation or enterprise level is the right scope. The policy is set once; every repo inherits; every workflow is covered.

The review cadence

An allowlist entry is a snapshot of the team’s trust position. The trust position is not permanent. Three events trigger a re-review: maintainer change, major upstream release, or review-cadence expiry. The re-review reads the commit history since the previous review, audits the dependency tree for new CVEs, and confirms the maintainer’s responsiveness.

Allowlist + pinning + ephemeral runners

Three controls close the third-party-action risk:

• Allowlisting decides which actions are permitted.
• Pinning decides which version of the permitted action the workflow executes.
• Ephemeral runners decide which secrets and which filesystem state the action can reach.

Allowlisting and pinning are enforced in the workflow file; runner configuration is enforced by the runner fleet policy. Neither layer alone is sufficient.

Production discipline

1. Configure an organisation-level allowlist. Every repo inherits; every workflow is covered.
2. Block unallowlisted actions at the merge gate. A PR that references an action not on the allowlist is rejected by branch protection or a custom linter.
3. Capture the metadata. Every entry has an owner, a reviewer, a version range, and a review cadence.
4. Review on cadence. The entry expires on its review date.
5. Combine with pinning. Allowlisting and pinning are enforced together.

Cross-course references

• Git, CI/CD & GitOps — Part LXVI-05 (Pinning to SHA) establishes the immutable-reference defence.
• Git, CI/CD & GitOps — Part LXV-04 (Runner as Actor) covers the ephemeral-runner control.
• Git, CI/CD & GitOps — Part LXVI-01 (Why third-party actions are a risk) establishes the trust boundary.
• Git, CI/CD & GitOps — Part XLV-04 (Policy as Code) covers the broader pattern.

Quiz