Actions governance has historically been a set of independent settings. Actions policies bring it into the rulesets framework, with targeting.
The framework is new, it is in public preview, and the honest guidance is: understand it, try it, and do not build a control that depends solely on it until the preview label comes off.
The short answer
Section titled “The short answer”Actions policies are built on the rulesets framework, which means they inherit its targeting model — selecting organisations and repositories by list, name pattern or custom property.
Available at enterprise, organisation and repository levels.
Two rule types are documented: event and actor.
Actions policies currently contain one policy type: workflow execution protections, itself documented as being in public preview.
Which is the shape of a framework being built out. One policy type today, on a foundation designed to hold more.
Why the rulesets framework matters here
Section titled “Why the rulesets framework matters here”The existing Actions settings are global to their level. An organisation’s default workflow permission is one value for the whole organisation. The allowed-actions setting is one policy for everything.
Which forces the value to the most permissive any repository needs. If one repository legitimately requires a permissive setting, the whole organisation gets it — or that repository gets an exception maintained by hand.
Rulesets targeting solves exactly this. A policy targeted at production-tier repositories can be stricter than one targeting everything, and a repository joins or leaves the stricter policy by having its custom property set.
The same reasoning as branch rules. The move from branch protection settings to rulesets was about targeting, and this is the same move applied to Actions.
And the same layering behaviour applies. Rules aggregate rather than override, so an enterprise-level Actions policy establishes a floor that organisations and repositories can tighten but not relax.
Event and actor rules
Section titled “Event and actor rules”Event rules concern what triggers a workflow — which events may cause execution, under which conditions.
Actor rules concern who or what caused it — which identities may trigger a workflow run.
Together they address the question the existing settings could not express well: not just what may run, but under what circumstances and at whose instigation.
The obvious application is untrusted triggers. A workflow triggered by a pull request from somebody outside the organisation is a different risk from the same workflow triggered by a member. Expressing that as policy, centrally, rather than as a per-workflow authoring convention, is the improvement.
Check the current rule set in GitHub’s documentation before designing. A preview framework’s rule catalogue is the thing most likely to have grown since anything was written about it.
Workflow execution protections
Section titled “Workflow execution protections”The one policy type Actions policies currently contains, itself documented as being in public preview.
Conceptually: controls over when workflow execution is permitted, expressed through the event and actor rule types above.
The problem it addresses is the one described in Actions governance: a workflow is code in a repository, and the controls over what triggers it have historically lived in that same file. A centrally-defined protection is one that a repository cannot remove by editing its own workflow.
Which is the durable value of moving this into rulesets. A required workflow or an execution protection defined at the enterprise level is not subject to being edited away by somebody with write access to the repository.
The problem being solved
Section titled “The problem being solved”Concretely, what does targeted Actions policy make possible that the flat settings do not?
Different execution rules for different repository tiers. A production-tier repository should not run workflows triggered by an outside contributor’s pull request without approval; a documentation repository reasonably can. As a global setting, you must choose one behaviour for both.
Different rules for public and internal repositories. Public repositories accept pull requests from anybody; internal ones accept them from enterprise members. The trust models differ and the policy should.
Different rules by compliance scope. Repositories in a regulated scope may need execution restrictions that would be needless friction elsewhere.
A floor that repositories cannot lower. A workflow authoring convention lives in a file the repository owns. A centrally-defined protection does not.
Consistency across organisations. Twenty organisations each configuring Actions settings independently produce twenty configurations. An enterprise policy produces one.
Each of these is currently handled by exception, by convention, or not at all. That is the gap, and it is a real one — the flat settings model has genuinely reached its limits in a large estate.
Layering and where the floor sits
Section titled “Layering and where the floor sits”Because the framework inherits ruleset semantics, the layering guidance transfers directly.
Rules aggregate; they do not override. An enterprise-level Actions policy sets a floor. Organisations and repositories can add restrictions above it and cannot relax it.
Which means the enterprise policy should be the minimum acceptable behaviour, not the target behaviour. Anything in it applies everywhere with no local escape.
Differentiation comes from targeting, not from levels. If most repositories need one rule and production repositories need a stricter one, that is two policies with different property targets — not an enterprise policy that organisations override, because they cannot.
Bypass actors are the escape hatch, and the same discipline applies: narrow, named, justified, and reviewed. A bypass list that grows means the policy does not match how people work.
And the same rollout discipline. Observe before enforcing, announce before switching, and start with something uncontroversial. See policy rollout.
None of that is new — it is the ruleset model, applied to a new domain. Which is the point of building it on the same framework, and it means the operational knowledge transfers.
How to treat a preview feature
Section titled “How to treat a preview feature”Since much of this cluster involves preview features, the general approach is worth stating once, here.
Use them. A preview feature that solves a real problem is frequently better than the alternative, and waiting for general availability has its own cost.
Do not make them a sole control. If your only enforcement of a requirement is a preview feature, the requirement has an unstated dependency on something that may change. Pair it with something stable.
Record the dependency. In the policy inventory: this control depends on a feature currently in public preview. That sentence is what lets a future reviewer re-evaluate rather than assume.
Re-verify each planning cycle. Preview features reach general availability, change behaviour, or occasionally change shape. A quarterly check of the preview features you depend on is cheap.
Do not describe them as generally available in documentation, control descriptions, or to auditors. Overclaiming here is easy and it undermines everything else you say.
And test rather than assume. Documentation for a preview feature is accurate at the time of writing and the feature may have moved. Confirm the behaviour you depend on, in your own configuration.
Who owns this
Section titled “Who owns this”A short note, because Actions policy sits on a boundary that produces confusion.
It is a security control, so security engineering has a legitimate interest.
It affects every pipeline, so the platform team owns the consequences.
It is configured at enterprise level, so enterprise administrators execute it.
And it constrains what teams can do, so team leads will have opinions.
The workable arrangement: the platform team owns the configuration, security engineering sets the requirements, enterprise administration executes, and there is a forum where the requirements are agreed rather than imposed.
The arrangement that fails is security engineering configuring policy directly without the platform team, because the failure modes are all in CI behaviour that only the platform team understands — and the first broken release will be attributed to the control rather than to the process that created it.
Whoever owns it needs the inventory. Actions policy decisions without knowledge of what workflows exist, what they are triggered by, and what they need are guesses. See Actions governance.
Where this fits alongside existing controls
Section titled “Where this fits alongside existing controls”| Concern | Existing mechanism | Actions policies |
|---|---|---|
| Which actions may run | Allowed-actions setting | Not currently |
| Default token permissions | Organisation/repository setting | Not currently |
| Which workflows must pass | Required workflows in rulesets | Related |
| When a workflow may execute | Workflow authoring | Event and actor rules |
| Which runners are reachable | Runner groups | Not currently |
The existing controls remain the primary ones, and they are generally available. Actions policies add targeting and centrally-defined execution control on top.
Do not defer existing work waiting for the framework. Setting default workflow permissions to read-only, restricting actions, and fixing privileged fork-triggered workflows are all available now, all high value, and none of them depend on a preview feature.
Adopt the framework where it adds something the existing settings cannot express — principally targeting, and protections a repository cannot remove.
The untrusted trigger problem
Section titled “The untrusted trigger problem”Since event and actor rules are the two documented rule types, the class of problem they address deserves a proper treatment.
A workflow run is caused by something. A push, a pull request, a schedule, a manual dispatch, an external event, another workflow.
The trust level of the cause varies enormously. A push to the default branch by a maintainer is trusted. A pull request from a fork by somebody who joined the enterprise this morning is not. A scheduled run is neither — it is unattended.
Historically the workflow author handles this, by choosing triggers carefully and by structuring jobs so untrusted code never meets privilege. That works when the author knows the pattern, and it fails silently when they do not.
Which is a poor place for a security control. It depends on every workflow author in the enterprise knowing a non-obvious rule, and on nobody ever getting it wrong across four hundred repositories.
Centralised event and actor rules move it. The policy states which triggers, from which actors, may cause execution on which repositories — once, centrally, for everybody.
The workflow author’s job becomes simpler, not harder: they write the workflow, and the framework prevents the dangerous trigger combinations rather than relying on them to avoid them.
That is the substantive improvement, and it is worth understanding independently of when the framework reaches general availability — because the same reasoning should shape how you review workflows today.
Trying it
Section titled “Trying it”-
Verify availability for your enterprise and plan. Preview features are frequently restricted.
-
Read the current documentation, not this article, for the rule catalogue. It will have changed.
-
Establish your custom properties first, since targeting depends on them.
-
Start with a narrow target — one property value, a small set of repositories.
-
Use the least disruptive enforcement available. If the rulesets framework’s observation mode applies, use it, exactly as you would for a branch ruleset.
-
Observe for a full cycle. Release processes and scheduled workflows both produce behaviour that a week does not reveal.
-
Record what you configured and why, with the preview dependency noted.
-
Re-check quarterly for behaviour changes and for general availability.
What to do while it matures
Section titled “What to do while it matures”Practical guidance for an enterprise that would benefit from targeted Actions policy but is not ready to depend on a preview feature.
Do the flat settings properly first. Default workflow permissions read-only, workflows unable to approve pull requests, an actions allow list, runner groups designed by reachability. These are generally available, high value, and independent of anything in preview.
Set them to the strictest value everyone can live with, and handle the genuine exceptions individually. That is more work than targeting, and it is available today.
Use required workflows for the things that must not be removable. A workflow required by a ruleset cannot be edited away, and that is available now.
Use CODEOWNERS on workflow paths so changes to CI configuration require approval from a nominated group. A convention, enforced by a generally available mechanism.
Establish the custom properties. Whatever the policy framework looks like when it stabilises, it will target on metadata, and building that metadata is not wasted work under any outcome.
Pilot the preview framework in one organisation. Learning it costs little and positions you to adopt properly when it stabilises.
And write down what you would do differently with it. That list is your adoption plan, and it makes the eventual rollout a matter of executing rather than designing.
Verifying before you rely
Section titled “Verifying before you rely”A short checklist for any preview feature, applied here.
Availability. Is it available for your plan, your platform, and your region? Preview features are frequently restricted, and the restrictions are the detail most likely to invalidate a plan.
Behaviour. Does it do what the documentation says, in your configuration? Test it rather than reading about it.
Interaction. How does it compose with the flat settings you already have? Two mechanisms addressing the same concern can produce behaviour neither documents.
Failure mode. What happens when it does not apply — does the action proceed or is it blocked? A fail-open control and a fail-closed one are very different things and the difference matters.
Observability. Can you see what it did and did not block? A control with no visibility is one you cannot evidence.
Reversibility. Can you disable it quickly if it blocks something important?
Record the answers. They are what a future reviewer needs, and they are what turns “we use Actions policies” into a statement somebody can evaluate.
Common mistakes
Section titled “Common mistakes”Presenting a preview feature as generally available. Undermines every other claim.
Making a preview feature a sole control. An unstated dependency in your control set.
Deferring available work in anticipation of the framework. Default permissions and fork-workflow fixes are available now.
Assuming the documented rule set is current. A preview framework’s catalogue changes.
Configuring targeted policies before establishing metadata. They target nothing.
Enforcing without observation. The same mistake as any ruleset rollout.
Not recording the preview dependency. A future reviewer cannot tell it is there.
The direction of travel
Section titled “The direction of travel”Reading the shape of the framework tells you something useful about where to invest.
GitHub is consolidating governance onto rulesets. Branch and tag rules were first. Repository policies for lifecycle events followed. Actions policies are the same pattern applied to CI.
Which means targeting by custom property is becoming the universal governance interface. Whatever governance capability arrives next, it will almost certainly select repositories the same way.
That makes metadata the durable investment. A ruleset written today may be superseded; the custom properties it targets will be used by whatever supersedes it. Time spent on the schema is time spent on every future control.
And it makes the flat, global settings the legacy shape. They will not disappear, and they are increasingly the coarse version of something the framework expresses better.
The practical implication for planning: treat “we set this globally and maintain a list of exceptions” as a pattern with a limited future, and prefer designs where the differentiation is expressed as metadata even if the enforcement is currently global.
That costs nothing today. A repository with a correctly-set tier property, governed by a global setting, is trivially converted to targeted policy later. One with no metadata is a migration.
Evidence and observability
Section titled “Evidence and observability”Whatever the framework’s final shape, a policy is only useful if you can show what it did.
Configuration is evidence of intent, not of operation. An exported policy definition shows what you meant; it does not show that anything was ever blocked.
Blocked events are evidence of operation. A record of executions the policy prevented is what demonstrates the control working, and it is what an assessor will ask for.
Observation mode output is evidence of readiness, and it is worth keeping from before enforcement — it shows what the policy would have blocked and therefore why it was needed.
Bypass records are evidence of the exception process, and they should be reviewed rather than merely retained.
The audit log carries policy configuration changes, which is the record of when a control was created, modified or removed. Alert on removals.
Export the configuration periodically alongside the other governance artifacts, so that “what was our policy in March” is answerable. See compliance evidence.
And be clear about the preview caveat in any control description. If a control’s evidence depends on a preview feature, the description should say so — that is honest, and it prompts the re-verification that keeps it accurate.
Mental model
Section titled “Mental model”Actions policies apply the rulesets model — targeting, layering, central definition — to CI execution. The framework is the interesting part and it is in public preview. Use it where it expresses something the existing settings cannot, pair it with a stable control, and re-verify it every quarter.
What you learned
Section titled “What you learned”- Actions policies and workflow execution protections are both documented as being in public preview and subject to change
- They are built on the rulesets framework and inherit its targeting model
- Available at enterprise, organisation and repository levels
- Two rule types are documented: event and actor
- Actions policies currently contain one policy type: workflow execution protections
- The value over existing settings is targeting and central definition a repository cannot edit away
- Existing controls — default permissions, allowed actions, runner groups — remain primary and generally available
- A preview feature should not be a sole control, and the dependency should be recorded
- Verify the rule catalogue and behaviour against current documentation rather than any secondary source
Exercise
Section titled “Exercise”Reason from current documentation and your own configuration.
-
Check GitHub’s current documentation for Actions policies. Predict: is it still in public preview?
-
Compare the rule types documented today against the event and actor types described here. Has the catalogue grown?
-
Determine availability for your enterprise and plan.
-
List your existing Actions controls: default permissions, allowed actions, runner groups. Which are set deliberately?
-
Identify one requirement your existing settings cannot express because they are global rather than targeted.
-
Design the policy that would express it, including the custom property it would target.
-
List every preview feature your governance currently depends on. Predict: is that list written down anywhere?
-
Set a quarterly reminder to re-verify each.