GitHub Actions Settings¶
xfg can manage the Actions settings page of a GitHub repository (Settings > Actions > General) declaratively using the sync command: which actions may run, the default token permissions, who needs approval to run workflows from forks, and how long artifacts, logs and caches are kept.
GitHub-Only Feature
Actions settings only apply to GitHub repositories. Azure DevOps and GitLab repos are skipped when running xfg sync.
Quick Start¶
id: my-config
settings:
actions:
allowedActions: selected
githubOwnedAllowed: true
verifiedAllowed: false
patternsAllowed:
- docker/login-action@*
- amannn/action-semantic-pull-request@*
shaPinningRequired: true
defaultWorkflowPermissions: read
canApprovePullRequestReviews: false
forkPrApprovalPolicy: all_external_contributors
repos:
- git: git@github.com:your-org/your-repo.git
# Preview changes (dry-run)
xfg sync -c config.yaml --dry-run
# Apply the Actions settings
xfg sync -c config.yaml
Every field is optional. xfg only touches what you configure: a field you leave out keeps whatever the repo has.
Configuration Fields¶
| Field | Type | GitHub API |
|---|---|---|
enabled |
boolean | actions/permissions enabled |
allowedActions |
all, local_only or selected |
actions/permissions allowed_actions |
shaPinningRequired |
boolean | actions/permissions sha_pinning_required |
githubOwnedAllowed |
boolean | actions/permissions/selected-actions github_owned_allowed |
verifiedAllowed |
boolean | actions/permissions/selected-actions verified_allowed |
patternsAllowed |
array of strings | actions/permissions/selected-actions patterns_allowed |
defaultWorkflowPermissions |
read or write |
actions/permissions/workflow default_workflow_permissions |
canApprovePullRequestReviews |
boolean | actions/permissions/workflow can_approve_pull_request_reviews |
forkPrApprovalPolicy |
first_time_contributors_new_to_github, first_time_contributors or all_external_contributors |
actions/permissions/fork-pr-contributor-approval approval_policy |
artifactAndLogRetentionDays |
positive integer | actions/permissions/artifact-and-log-retention days |
cacheRetentionDays |
positive integer | actions/cache/retention-limit max_cache_retention_days |
cacheSizeGb |
positive integer | actions/cache/storage-limit max_cache_size_gb |
canApprovePullRequestReviews is GitHub's "Allow GitHub Actions to create and approve pull requests" switch, so it covers creating pull requests as well as approving them.
The schema reference lists the same fields with their descriptions: actionsSettings.
Allowed Actions¶
allowedActions decides which actions and reusable workflows can run:
| Value | Effect |
|---|---|
all |
Any action or reusable workflow |
local_only |
Only actions and reusable workflows in the same repo or organization |
selected |
Only the ones githubOwnedAllowed, verifiedAllowed and patternsAllowed allow |
githubOwnedAllowed, verifiedAllowed and patternsAllowed only apply when allowedActions is selected. patternsAllowed entries look like owner/repo@*, or owner/* for everything from an owner. A pattern that starts with ! blocks the action instead.
xfg compares patternsAllowed as a set, so reordering the list is not a change.
First run on a repo
GitHub only returns the selected-actions list while allowedActions is selected. On a repo that is not in that mode yet, the plan shows githubOwnedAllowed, verifiedAllowed and patternsAllowed as new values, and xfg switches the mode before it writes them.
Workflow Permissions¶
defaultWorkflowPermissions sets what the GITHUB_TOKEN can do in workflows that don't declare their own permissions:. read gives read access to repository contents and packages. Workflows that write (push, create releases, comment on pull requests) then need an explicit permissions: block.
Disabling Actions¶
id: no-actions
settings:
actions:
enabled: false
repos:
- git: git@github.com:your-org/docs-only.git
With enabled: false the repo's other Actions fields are not allowed in the same layer: allowedActions, shaPinningRequired and the selected-actions fields fail validation, because GitHub rejects them while Actions is off.
Inheritance¶
actions merges from root to group to repo, field by field, like settings.repo. A repo that sets one field keeps the rest of the inherited block.
A plain patternsAllowed list replaces the inherited one. To add to it instead, use $arrayMerge: append. inherit: false in a layer drops every inherited field, then applies that layer's own.
id: actions-baseline
settings:
actions:
allowedActions: selected
githubOwnedAllowed: true
patternsAllowed:
- docker/login-action@*
defaultWorkflowPermissions: read
repos:
- git: git@github.com:your-org/api-service.git
- git: git@github.com:your-org/web-app.git
settings:
actions:
patternsAllowed:
$arrayMerge: append # adds to docker/login-action@*
$values:
- aquasecurity/trivy-action@*
- git: git@github.com:your-org/scratch.git
settings:
actions:
allowedActions: all # overrides selected; the inherited selected-actions fields are ignored
When the merged allowedActions is set to all or local_only, xfg ignores the selected-actions fields and prints a warning, so a repo can override an inherited selected without restating the block. When the merged enabled is false, it ignores allowedActions, shaPinningRequired and the selected-actions fields the same way.
The same goes for a repo that has Actions turned off when you run xfg and whose merged config doesn't set enabled: xfg ignores those fields with a warning, because GitHub rejects them while Actions is off. Set enabled: true to turn Actions on and apply them.
Per-Repo Opt-Out¶
To exclude a repo from inherited Actions settings, set actions: false at the repo or group level:
id: my-config
settings:
actions:
allowedActions: selected
githubOwnedAllowed: true
shaPinningRequired: true
repos:
- git: git@github.com:your-org/main-app.git
- git: git@github.com:your-org/private-repo.git
settings:
actions: false # Leave this repo's Actions settings alone
actions: false is only valid when an inherited actions block exists, and not at root level.
Validation¶
xfg checks each layer before it syncs:
allowedActions,defaultWorkflowPermissionsandforkPrApprovalPolicymust be one of the listed values.- The retention and size fields must be positive integers. GitHub enforces the upper limit, which depends on visibility and plan, and xfg shows its error.
patternsAllowedentries must be non-empty strings.- A layer that sets
githubOwnedAllowed,verifiedAllowedorpatternsAllowedtogether with anallowedActionsother thanselectedis an error. - A layer that sets
enabled: falsetogether withallowedActions,shaPinningRequiredor a selected-actions field is an error. - After the layers merge, a repo whose block sets
githubOwnedAllowed,verifiedAllowedorpatternsAllowedmust get anallowedActionsfrom some layer, otherwise the config is rejected. A layer can leaveallowedActionsout and inherit it. - A config whose only
actionsblock is empty does not count as having settings to sync.
What xfg Calls¶
xfg calls only the endpoints that hold a field you configured, and writes only the ones with a difference:
GET actions/permissionsfirst.GET actions/permissions/selected-actionsonly when the repo is inselectedmode.GETfor every other endpoint you configured.PUTfor each endpoint that differs,actions/permissionsbeforeactions/permissions/selected-actions.
A config without cache fields never calls the cache endpoints. When a PUT needs a field you did not configure, xfg sends the repo's current value for it.
With --dry-run, xfg reads the live values and prints the plan as old → new per field, and writes nothing. The settings report lists each change as actions.<field>.
Permissions¶
The credential xfg runs with needs Administration: Read and write on the repo. Reading actions/cache/storage-limit also needs Actions: Read. See GitHub App Authentication.
Limits¶
- GitHub returns errors for settings the repo can't take, for example when an organization or enterprise policy controls the setting (
409), or an unsupported value (422). xfg shows GitHub's message and the run exits non-zero. forkPrApprovalPolicyapplies to public repos only; GitHub rejects it on a private or internal repo, which fails the Actions block in the plan and on apply. A private repo that inherits it opts out withactions: false, because inheritance merges field by field and can't remove a single inherited field.cacheRetentionDaysandcacheSizeGbneed a paid plan or a payment method on file; GitHub rejects the write otherwise.- xfg does not manage organization or enterprise Actions policies, settings that only exist for private repositories, or OIDC subject customization.