Govern GitHub Actions in the Enterprise: Policies, Templates, Secrets and Variables (GH-200)

GitHub Actions policies are set at three levels — enterprise, organization and repository — and each level can only narrow what the level above allows, never loosen it. An enterprise owner who disables Actions for an organization, restricts the allowed actions or sets a restricted token default has made that choice for everything beneath; the organization and repository settings for it become unavailable or limited to stricter values.

The first policy at every level is enablement: whether workflows may run at all.

Enablement answers where workflows run. It is a different policy from the allowed-actions list (which actions a run may use) and from token permissions (what a run may change). Only enablement stops a workflow from executing. Because the levels nest, turning Actions on somewhere a parent has switched it off is always a change at the parent first: a repository cannot enable what its organization disabled, and an organization cannot enable what its enterprise disabled.

The allowed-actions policy decides which actions and reusable workflows a workflow may reference. At organization level (the enterprise has the same options with "enterprise" in place of the organization name) the choices are:

The select option has three independent controls:

• Allow actions created by GitHub — admits actions in the actions and github organizations (for example actions/setup-node).
• Allow Marketplace actions by verified creators — admits actions from publishers GitHub has verified, such as Docker or HashiCorp. This is a broad switch, not a per-action choice.
• Allow or block specified actions and reusable workflows — a comma-separated list of patterns (next section).

Two exemptions matter everywhere: local actions referenced with a ./ path inside the same repository are never restricted by these policies, and the policy governs sources, not reference formats. Because a lower level can never loosen a higher one, a source the enterprise policy excludes can only be admitted by changing the enterprise policy itself.

The specified list accepts one pattern per action or reusable workflow, separated by commas, and it exists only under the "select non-owner" option.

Combining a wildcard with a block entry lets you keep almost everything open while refusing one known-bad action, without listing the hundreds of actions teams already use:

*, !example-org/format-action@*

The * entry keeps every other source allowed and the ! entry refuses every reference of the one action. Since the open "Allow all" option has no list, blocking anything starts by moving to the select option.

Requiring actions pinned to a full-length commit SHA

The SHA-pinning policy makes GitHub refuse any workflow that references an action by a tag or branch instead of a full 40-character commit SHA. Tags and branches can be moved to new code by whoever controls the action's repository; a commit SHA cannot, so the policy closes the "moved tag" supply-chain attack. It is available at enterprise, organization and repository level.

Its scope is narrower than it sounds:

• It applies to actions referenced with uses: in steps.
• Reusable workflows called with uses: at job level may still be referenced by tag.
• Local actions (./path) are not restricted at all.

Applied to this workflow: the job-level reusable workflow keeps its tag, actions/setup-node@v4 must be rewritten to a 40-character SHA, and the local ./ action is untouched.

jobs:
  build:
    uses: fabrikam/ci-library/.github/workflows/package.yml@v3
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
      - uses: ./.github/actions/format

The policy controls the reference format, not the source: it does not replace the allowed-actions list. Why pinning matters and how to keep pins up to date is covered in the security best-practices lesson of Domain 5.

The workflow-permissions setting chooses the default scopes of GITHUB_TOKEN for workflows that do not declare a permissions key.

Three rules decide most scenarios:

• The default only applies when there is no permissions key. After a switch to restricted, a workflow without a key can still check out code and pull packages, but a step that pushes a tag fails.
• A declared permissions key replaces the default completely. Every scope you list gets the access you give it and every scope you omit becomes none. contents: write lets a release job push tags whatever the default; pull-requests: write alone leaves contents at none, so a tag push fails.
• A restricted enterprise default cannot be loosened. Organizations and repositories cannot choose read and write as their default once the enterprise restricts it. Jobs that need write access declare it in the workflow — which is least-privilege practice anyway.

A separate checkbox, "Allow GitHub Actions to create and approve pull requests", is off by default. While it is off, GITHUB_TOKEN cannot open or approve a pull request even with pull-requests: write: the branch push succeeds and the pull-request API call is refused with a 403.

Fork policies decide whether and how workflows run for pull requests opened from forks, and the options differ for public and private repositories.

Public repositories choose how much approval outside contributors need before workflows run on their pull requests — for example only for first-time contributors who are new to GitHub, for all first-time contributors, or for all external contributors. One trigger is outside this gate: workflows triggered by pull_request_target always run, because they execute from the base branch in the base repository's trusted context. That is exactly why a pull_request_target workflow must never check out and execute the fork's code while secrets or a write token are available.

Private and internal repositories have four separate checkboxes:

The checkboxes are independent. The two "Send" options are the ones that hand code from a fork a write token or the repository's secrets, so they belong only where every forking contributor is trusted; approval adds a human check before any of it runs.

An organization distributes standard automation in three ways, and they solve different problems: templates suggest a starting file, Access sharing lets other repositories call private code, and rulesets enforce a workflow without touching the repositories.

Workflow templates

An organization publishes templates in a repository named .github, inside a workflow-templates directory (not .github/workflows). Each template is a workflow file plus a metadata file with the same base name ending in .properties.json, whose name and description are required (an icon and categories are optional). The placeholder $default-branch is replaced with the target repository's default branch when the workflow is created — the new file contains the literal branch name, such as develop; it is not re-evaluated at run time.

Visibility decides where templates are offered: templates in a public .github repository appear in all repository types; an internal one in internal and private repositories; a private one only in private repositories. With a private or internal .github repository users also need Read access to it. Templates belong to the owning organization — other organizations in the same enterprise do not see them. Authoring templates and reusable workflows in detail is the subject of the Domain 2 lesson on templates and reusable workflows.

Sharing actions and reusable workflows from private and internal repositories

Actions and reusable workflows in a private or internal repository are usable only inside that repository until its Settings > Actions > General > Access option grants more. A private repository can be opened to repositories in the same organization (or, for a user-owned repository, the same user); an internal repository can be opened to repositories in the enterprise. Repositories owned by an enterprise's organizations get a wider choice too: a private repository can also be opened to the whole enterprise (callers must themselves be private), and an internal one can be limited to its own organization (callers must be private or internal). Internal visibility exists only for enterprise accounts, so a GitHub Team organization shares a private repository at organization level. Neither the allowed-actions list nor people's repository roles grant this access, and making the repository public breaks any privacy requirement. The allowed-actions policy still applies on top: sharing makes an action reachable, the policy decides whether it may run.

Required workflows through rulesets

The "Require workflows to pass before merging" rule is configured once in an organization (or enterprise) ruleset. It names a source repository, a workflow file and a ref, and targets repositories by name or property. Its rules:

• It runs on pull_request, pull_request_target and merge_group with their default activity types, and ignores filters such as branches, paths and types — so the check runs on every targeted pull request. Work that should be skipped must be decided inside the jobs.
• The source repository's visibility must suit the targets: a public source runs anywhere, an internal one in internal and private repositories, a private one only in private repositories.
• An internal or private source must also allow access from outside its repository in its Actions Access setting, or the workflow never starts.
• Most CodeQL actions (such as init and analyze) are blocked in ruleset workflows, even inside a called reusable workflow; only upload-sarif is allowed. For organization-wide CodeQL, GitHub recommends default setup plus the "Require code scanning results" rule.

Custom organization roles let an owner delegate parts of Actions administration without making someone an organization owner. GitHub provides separate fine-grained permissions for Actions:

Build the role from only the permissions the person needs: someone who maintains organization secrets and variables but must not change policies gets those two permissions and nothing else. The Admin role on repositories is the wrong tool — it does not reach organization-level settings and grants far more than needed. Runner and runner-group management itself belongs to the sibling topic on managing runners at scale.

Secrets are encrypted values that GitHub redacts from logs; configuration variables are plain-text settings that are not redacted. Anything that grants access — a token, a password, a connection string, a webhook URL with an embedded key — is a secret; a region name, a feature flag or a host name is a variable. Workflows read them through different contexts:

steps:
  - run: ./deploy.sh --region "${{ vars.REGION }}"
    env:
      API_KEY: ${{ secrets.API_KEY }}

An undefined variable evaluates to an empty string rather than failing the run, so a condition such as if: ${{ vars.RUN_LOAD_TESTS == 'yes' }} is false when no such variable exists — handy for optional feature flags. An unset or unreachable secret is also an empty string. Secrets cannot be referenced directly in if: conditions (map them to an environment variable first; see the Domain 1 workflow-structure lesson).

Actions never read secrets on their own: the calling workflow passes a value in through a with: input or an env: variable, and a composite action cannot use the secrets context directly. Reusable workflows receive secrets through workflow_call secrets or secrets: inherit (covered in the Domain 2 reusable-workflows lesson).

Scopes

When the same name exists at several levels, the lowest level wins: environment, then repository, then organization — evaluated name by name. For example, if the organization and the repository both define LOG_LEVEL and a qa environment defines only CDN_HOST, a job targeting qa reads LOG_LEVEL from the repository and CDN_HOST from the environment.

On the GitHub Free plan, organization secrets and variables are not accessible to private repositories at all, whatever access policy is chosen; public repositories receive them, private ones get an empty value.

Environment secrets as a gate

Environment secrets are the only scope that protects the value itself. A job receives them only if it has environment: production (a job that merely needs: a job that used the environment gets nothing), and only after the environment's deployment branch policy and required reviewers pass. A repository or organization secret is available to any branch, and an if: github.ref == ... guard can be edited away by the very developer it is meant to stop. Widening who may deploy is therefore done on the environment itself — by changing its deployment branch policy — not by copying the secret to a broader scope.

Secret and variable names follow fixed rules, and secrets have size and count limits that explain several "empty value" puzzles.

• Names may contain only alphanumeric characters and underscores — no spaces.
• Names must not start with the GITHUB_ prefix and must not start with a number.
• Names are case-insensitive (stored in uppercase) and must be unique at their level.

If more than 100 organization secrets are shared with a repository, names late in the alphabet resolve to an empty string. Share fewer secrets with that repository or use repository secrets.

For a value larger than 48 KB — a key file, for example — GitHub documents one workaround: encrypt the file with gpg --symmetric --cipher-algo AES256, commit only the encrypted file, store the passphrase as a secret, and decrypt in a step at run time. GitHub does not redact the decrypted contents, so the workflow must never print them. Moving the value to an environment or organization secret does not help, and a variable would store it in plain text.

Secrets are written to the REST API already encrypted: a client fetches the public key of the scope, encrypts the value with libsodium, and sends the ciphertext. Variables are plain text and use ordinary create/update/read calls.

Secrets

1. GET /repos/{owner}/{repo}/actions/secrets/public-key (or the /orgs/{org}/... or environment equivalent) returns a key and a key_id. Use the key of the scope you are writing to.
2. Encrypt the value with libsodium (a sealed box) using that key and Base64-encode the result.
3. PUT /repos/{owner}/{repo}/actions/secrets/{secret_name} with encrypted_value and key_id — 201 when created, 204 when updated. There is no plain-text or POST form, and secret values can never be read back.

Organization secrets add an access policy: visibility is all, private or selected, with selected_repository_ids for selected. The repository list then has its own endpoints:

The single-repository calls return 409 unless the secret's visibility is selected.

Variables

An organization variable is created with one POST /orgs/{org}/actions/variables carrying name, value and the required visibility; selected_repository_ids is accepted only with selected. Its repository list uses the same replace-or-add-one endpoints as secrets.

GitHub CLI

gh secret set SENTRY_DSN --repo fabrikam/shop           # repository secret
gh secret set SENTRY_DSN --env qa --repo fabrikam/shop  # environment secret
gh secret set SENTRY_DSN --org fabrikam \
  --visibility selected --repos shop,mobile             # org, selected repos
gh variable set LOG_LEVEL --body info --org fabrikam --visibility all

Without --visibility, the CLI gives an organization secret private visibility (private and internal repositories). Managing organization secrets needs the admin:org scope on the CLI's token.