Securing GitHub Actions¶

GitHub Actions settings exist on organization level (settings.workflows) and on repository level (workflows). When the organization setting is more restrictive, the repository setting is ignored, see Organization settings take precedence. This guide covers the settings that limit what workflows can do.

Restrict the permissions of the GITHUB_TOKEN¶

Every workflow run receives a GITHUB_TOKEN. The setting default_workflow_permissions defines its default permissions:

• read: read access to the repository contents and packages only
• write: read and write access for all permission scopes

Workflows that need more permissions declare them explicitly with the permissions key, e.g. a release job:

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write # create the release
    steps:
      ...

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    workflows+: {
      default_workflow_permissions: "read",
    },
  },
}

Open in the Playground

To switch an existing organization from write to read:

1. Identify the workflows that need write access, e.g. workflows that push commits or tags, create releases, publish packages or comment on pull requests, and add the required permissions to them.
2. Switch the repositories with such workflows first, e.g. one repository at a time, with workflows+: { default_workflow_permissions: "read" }.
3. Switch the organization setting. From then on, a repository setting write is ignored.
4. Watch for failing workflow runs with errors like Resource not accessible by integration.

Prevent workflows from approving pull requests¶

The setting actions_can_approve_pull_request_reviews controls whether workflows can create and approve pull requests with the GITHUB_TOKEN.

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    workflows+: {
      actions_can_approve_pull_request_reviews: false,
    },
  },
}

Open in the Playground

Control which actions can run¶

The setting allowed_actions controls which actions and reusable workflows can run:

• all: any action
• local_only: only actions and reusable workflows defined in the organization
• selected: actions created by GitHub (allow_github_owned_actions), by verified creators (allow_verified_creator_actions) and actions that match allow_action_patterns

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    workflows+: {
      allowed_actions: "selected",
      allow_github_owned_actions: true,
      allow_verified_creator_actions: false,
      allow_action_patterns+: [
        "my-org/*",
        "example-owner/example-action@*",
      ],
    },
  },
}

Open in the Playground

Patterns are described in Allowing select actions and reusable workflows to run. The GitHub policy that requires actions to be pinned to a full-length commit SHA cannot be configured with otterdog.

Approve workflows from forks¶

Pull requests from forks can run workflows. The setting fork_pr_approval_policy defines when a maintainer has to approve such runs:

orgs.newOrg('my-project', 'my-org') {
  settings+: {
    workflows+: {
      fork_pr_approval_policy: "all_external_contributors",
    },
  },
}

Open in the Playground

Disable GitHub Actions where it is not needed¶

Repositories that do not use workflows, e.g. mirrors, can disable GitHub Actions entirely:

orgs.newOrg('my-project', 'my-org') {
  _repositories+:: [
    orgs.newRepo('my-mirror') {
      workflows+: {
        enabled: false,
      },
    },
  ],
}

Open in the Playground

On organization level, enabled_repositories set to selected only enables GitHub Actions for the repositories listed in selected_repositories.

Cache size and costs¶

The setting max_cache_size_gb limits the total size of the GitHub Actions caches of a repository. Increasing it may incur costs: depending on the setup of your otterdog installation, such changes require a review by a designated team, see Cost policy.

Policies can enforce further restrictions on GitHub Actions, e.g. the usage of macOS large runners.

Summary¶