Make "Enforcing policies for GitHub Actions in your enterprise" scannable (#51317)
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
This commit is contained in:
Laura Coursen
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Enforcing policies for GitHub Actions in your enterprise
|
||||
intro: 'You can enforce policies for {% data variables.product.prodname_actions %} within your enterprise''s organizations, or allow policies to be set in each organization.'
|
||||
permissions: 'Enterprise owners{% ifversion custom-org-roles %} and users with the "Manage organization Actions policies" permission{% endif %} can enforce policies for {% data variables.product.prodname_actions %} in an enterprise.'
|
||||
intro: "You can enforce policies to manage how {% data variables.product.prodname_actions %} can be used within your enterprise."
|
||||
permissions: "Enterprise owners"
|
||||
redirect_from:
|
||||
- /enterprise/admin/github-actions/enforcing-github-actions-policies-for-your-enterprise
|
||||
- /admin/github-actions/enforcing-github-actions-policies-for-your-enterprise
|
||||
@@ -25,171 +25,153 @@ topics:
|
||||
shortTitle: GitHub Actions policies
|
||||
---
|
||||
|
||||
## What are policies for {% data variables.product.prodname_actions %}?
|
||||
|
||||
## About policies for {% data variables.product.prodname_actions %} in your enterprise
|
||||
Enterprise policies control the options that are available to enterprise members when they use {% data variables.product.prodname_actions %}.
|
||||
|
||||
{% data variables.product.prodname_actions %} helps members of your enterprise automate software development workflows on {% data variables.product.product_name %}. For more information, see "[AUTOTITLE](/actions/learn-github-actions/understanding-github-actions)."
|
||||
If you don't enforce enterprise policies, organization owners{% ifversion custom-org-roles %} and users with the "Manage organization Actions policies" permission{% endif %} have full control over {% data variables.product.prodname_actions %} for their organizations.
|
||||
|
||||
{% ifversion ghes %}If you enable {% data variables.product.prodname_actions %}, any{% else %}Any{% endif %} organization on {% data variables.location.product_location %} can use {% data variables.product.prodname_actions %}. You can enforce policies to control how members of your enterprise on {% data variables.product.product_name %} use {% data variables.product.prodname_actions %}. By default, organization owners{% ifversion custom-org-roles %} and users with the "Manage organization Actions policies" permission{% endif %} can manage how members use {% data variables.product.prodname_actions %}. For more information, see "[AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization)."
|
||||
|
||||
{% ifversion custom-org-roles %}For more information about custom organization roles, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles)."{% endif %}
|
||||
|
||||
## Enforcing a policy to restrict the use of {% data variables.product.prodname_actions %} in your enterprise
|
||||
|
||||
You can choose to disable {% data variables.product.prodname_actions %} for all organizations in your enterprise, or only allow specific organizations. You can also limit the use of public actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}, so that people can only use local actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} that exist in your enterprise.
|
||||
## Enforcing policies
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
1. Under "Policies", select your options.
|
||||
1. After you configure each policy, click **Save**.
|
||||
|
||||
{% data reusables.actions.actions-use-policy-settings %}
|
||||
For more information about each section of the "Policies" page, continue reading.
|
||||
|
||||
{%- ifversion ghes %}
|
||||
{% note %}
|
||||
## Policies
|
||||
|
||||
**Note:** To enable access to public actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}, you must first configure {% data variables.location.product_location %} to connect to {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)."
|
||||
In the "Policies" section, you can control which organizations within your enterprise can use {% data variables.product.prodname_actions %}, with the following options:
|
||||
|
||||
{% endnote %}
|
||||
* Enable {% data variables.product.prodname_actions %} for all organizations
|
||||
* Enable {% data variables.product.prodname_actions %} for specific organizations
|
||||
* Disable {% data variables.product.prodname_actions %} for all organizations
|
||||
|
||||
You can also limit the use of public actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}, with the following options:
|
||||
|
||||
* **Allow all actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}**: Any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} can be used, regardless of who authored it or where it is defined.
|
||||
* **Allow enterprise actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}**: Only actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} defined in a repository within the enterprise can be used. {% ifversion ghec or fpt %}Blocks all access to actions authored by {% data variables.product.prodname_dotcom %}, such as the [`actions/checkout`](https://github.com/actions/checkout) action.{% endif %}
|
||||
* {% data reusables.actions.policy-label-for-select-actions-workflows %}: Any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} defined in a repository within the enterprise can be used, plus any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} that matches criteria you specify.
|
||||
|
||||
<span id="allowing-select-actions-and-reusable-workflows-to-run" ></span>
|
||||
|
||||
### {% data reusables.actions.policy-label-for-select-actions-workflows %}
|
||||
|
||||
If you choose this option, actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} within your enterprise are allowed, and you'll have the following options for allowing other actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}:
|
||||
|
||||
* **Allow actions created by {% data variables.product.prodname_dotcom %}:** Allows all actions created by {% data variables.product.prodname_dotcom %}, located in the [`actions`](https://github.com/actions) and [`github`](https://github.com/github) organizations.
|
||||
* **Allow Marketplace actions by verified creators:** Allows all {% data variables.product.prodname_marketplace %} actions created by verified creators, labeled with {% octicon "verified" aria-label="The verified badge" %}.{% ifversion ghes %}
|
||||
|
||||
Only available if you have {% data variables.product.prodname_github_connect %} enabled and configured with {% data variables.product.prodname_actions %}. See "[AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)."{% endif %}
|
||||
* **Allow specified actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}:** Allows actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} that you specify. You can specify individual actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} or entire organizations and repositories.
|
||||
|
||||
When specifying actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}, use the following syntax:
|
||||
|
||||
* To restrict access to specific tags or commit SHAs of an action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}, use the same syntax used in the workflow to select the action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}.
|
||||
* For an action, the syntax is `OWNER/REPOSITORY@TAG-OR-SHA`. For example, use `actions/javascript-action@v1.0.1` to select a tag or `actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f` to select a SHA.
|
||||
{%- ifversion actions-workflow-policy %}
|
||||
* For a reusable workflow, the syntax is `OWNER/REPOSITORY/PATH/FILENAME@TAG-OR-SHA`. For example, `octo-org/another-repo/.github/workflows/workflow.yml@v1`.
|
||||
{%- endif %}
|
||||
1. Click **Save**.
|
||||
|
||||
{% data reusables.actions.allow-specific-actions-intro %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
1. Under "Policies", select {% data reusables.actions.policy-label-for-select-actions-workflows %} and add your required actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} to the list.
|
||||
* To specify a pattern, use the wildcard character, `*`.
|
||||
* To allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in organizations that start with `space-org`, use `space-org*/*`.
|
||||
* To allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in repositories that start with octocat, use `*/octocat**@*`.
|
||||
|
||||
{% ifversion actions-disable-repo-runners %}
|
||||
|
||||
## Disabling repository-level self-hosted runners
|
||||
## Runners
|
||||
|
||||
{% data reusables.actions.disable-selfhosted-runners-overview %} For more information on creating self-hosted runners at the repository level, see "[AUTOTITLE](/enterprise-cloud@latest/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository)."
|
||||
By default, anyone with admin access to a repository can add a self-hosted runner for the repository, and self-hosted runners come with risks:
|
||||
|
||||
By default anyone with admin access to a repository can add a self-hosted runner for the repository. The enterprise settings allow you to disable the use of repository-level self-hosted runners across all repositories in your enterprise. If you allow repository-level self-hosted runners for your enterprise, organization owners{% ifversion custom-org-roles %} and users with the "Manage organization runners and runner groups" permission{% endif %} can choose to allow or prevent creation of repository-level self-hosted runners for some or all repositories in their organization. For more information see, "[AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization)."
|
||||
* There is no guarantee that self-hosted runners will be hosted on ephemeral, clean virtual machines. As a result, they may be compromised by untrusted code in a workflow.
|
||||
* Anyone who can fork the repository and open a pull request can compromise the self-hosted runner environment, potentially gaining access to secrets and the `GITHUB_TOKEN`, which may have write access to the repository.
|
||||
|
||||
{% ifversion custom-org-roles %}For more information about custom organization roles, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles)."{% endif %}
|
||||
In the "Runners" section, you can mediate these risks by disabling the use of repository-level self-hosted runners.
|
||||
|
||||
{% ifversion ghec %}
|
||||
* **Disable for all organizations**: Prevents the creation of runners at the repository level.
|
||||
* **Disable in all Enterprise Managed User (EMU) repositories**: Prevents the creation of runners for repositories owned by {% data variables.enterprise.prodname_managed_users %}.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.actions.disable-selfhosted-runners-note %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
1. In the "Runners" section, select **Disable for all organizations**.{% ifversion ghec %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: Owners of an {% data variables.enterprise.prodname_emu_enterprise %} can also choose to select **Disable in all Enterprise Managed User (EMU) repositories** to restrict runner creation for repositories that are owned by managed user accounts.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% endif %}
|
||||
1. Click **Save** to apply the change.
|
||||
|
||||
## {% ifversion ghes %}Artifact, log, and cache settings{% else %}Artifact and log retention{% endif %}
|
||||
|
||||
{% ifversion ghes %}
|
||||
|
||||
These policies control storage of artifacts, logs, and caches.
|
||||
|
||||
### Artifact and log retention
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Enforcing a policy for artifact and log retention in your enterprise
|
||||
|
||||
{% data variables.product.prodname_actions %} can store artifact and log files. For more information, see "[AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts)."
|
||||
|
||||
{% data reusables.actions.about-artifact-log-retention %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
{% data reusables.actions.change-retention-period-for-artifacts-logs %}
|
||||
|
||||
## Enforcing a policy for fork pull requests in your enterprise
|
||||
|
||||
You can enforce policies to control how {% data variables.product.prodname_actions %} behaves for {% data variables.location.product_location %} when members of your enterprise{% ifversion ghec %} or outside collaborators{% endif %} run workflows from forks.
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
### Enforcing a policy for approval of pull requests from outside collaborators
|
||||
|
||||
{% data reusables.actions.workflow-run-approve-public-fork %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
{% data reusables.actions.workflows-from-public-fork-setting %}
|
||||
|
||||
{% data reusables.actions.workflow-run-approve-link %}
|
||||
By default, artifacts and log files generated by workflows are retained for 90 days. {% ifversion ghes %}You can change this retention period to anywhere between 1 and 400 days.{% else %}You can change the retention period.
|
||||
|
||||
* For public repositories, you can configure a period between 1 and 90 days.
|
||||
* For private and internal repositories, you can configure a period between 1 and 400 days.
|
||||
{% endif %}
|
||||
|
||||
### Enforcing a policy for fork pull requests in private repositories
|
||||
|
||||
{% data reusables.actions.private-repository-forks-overview %}
|
||||
|
||||
If a policy is enabled for an enterprise, the policy can be selectively disabled in individual organizations or repositories. If a policy is disabled for an enterprise, individual organizations or repositories cannot enable it.
|
||||
|
||||
{% data reusables.actions.private-repository-forks-options %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
{% data reusables.actions.private-repository-forks-configure %}
|
||||
|
||||
{% ifversion ghec or ghes %}
|
||||
|
||||
## Enforcing a policy for workflow permissions in your enterprise
|
||||
|
||||
{% data reusables.actions.workflow-permissions-intro %}
|
||||
|
||||
You can set the default permissions for the `GITHUB_TOKEN` in the settings for your enterprise, organizations, or repositories. If you choose a restricted option as the default in your enterprise settings, this prevents the more permissive setting being chosen in the organization or repository settings.
|
||||
|
||||
{% data reusables.actions.workflow-permissions-modifying %}
|
||||
|
||||
### Configuring the default `GITHUB_TOKEN` permissions
|
||||
|
||||
{% ifversion actions-default-workflow-permissions-restrictive %}
|
||||
By default, when you create a new enterprise, `GITHUB_TOKEN` only has read access for the `contents` and `packages` scopes.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
{% data reusables.actions.workflows.github-token-access %}
|
||||
1. Click **Save** to apply the settings.
|
||||
|
||||
{% ifversion allow-actions-to-approve-pr-with-ent-repo %}
|
||||
|
||||
### Preventing {% data variables.product.prodname_actions %} from creating or approving pull requests
|
||||
|
||||
{% data reusables.actions.workflow-pr-approval-permissions-intro %}
|
||||
|
||||
{% ifversion actions-default-workflow-permissions-restrictive %}
|
||||
By default, when you create a new enterprise, workflows are not allowed to create or approve pull requests.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
1. Under "Workflow permissions", use the **Allow GitHub Actions to create and approve pull requests** setting to configure whether `GITHUB_TOKEN` can create and approve pull requests.
|
||||
1. Click **Save** to apply the settings.
|
||||
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
Changes only apply to new artifacts and log files.
|
||||
|
||||
{% ifversion actions-cache-policy-apis %}
|
||||
|
||||
## Enforcing a policy for cache storage in your enterprise
|
||||
### Maximum and default cache size limits
|
||||
|
||||
{% data reusables.actions.cache-default-size %} {% data reusables.actions.cache-eviction-process %}
|
||||
By default:
|
||||
|
||||
However, you can set an enterprise policy to customize both the default total cache size for each repository, as well as the maximum total cache size allowed for a repository. For example, you might want the default total cache size for each repository to be 5 GB, but also allow {% ifversion actions-cache-admin-ui %}organization owners and{% endif %} repository administrators to configure a total cache size up to 15 GB if necessary.
|
||||
* The total cache storage that {% data variables.product.prodname_actions %} uses on the external storage for {% data variables.location.product_location %} is limited to a maximum of 10 GB per repository.
|
||||
* The maximum allowed size that can be set for a repository is 25 GB.
|
||||
|
||||
{% data reusables.actions.cache-eviction-process %}
|
||||
|
||||
You can customize both the default total cache size for each repository and the maximum total cache size allowed for a repository. For example, you might want the default total cache size for each repository to be 5 GB, but also allow administrators to configure a total cache size up to 15 GB for individual repositories.
|
||||
|
||||
{% ifversion actions-cache-admin-ui %}Organization owners can set a lower total cache size that applies to each repository in their organization. {% endif %}People with admin access to a repository can set a total cache size for their repository up to the maximum cache size allowed by the enterprise {% ifversion actions-cache-admin-ui %}or organization{% endif %} policy setting.
|
||||
|
||||
{% ifversion actions-cache-admin-ui %}
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.actions-tab %}
|
||||
1. In the "Artifact, log, and cache settings" section, under **Maximum cache size limit**, enter a value, then click **Save** to apply the setting.
|
||||
1. In the "Artifact, log, and cache settings" section, under **Default cache size limit**, enter a value, then click **Save** to apply the setting.
|
||||
{% ifversion ghec %}
|
||||
|
||||
## Fork pull request workflows from outside collaborators
|
||||
|
||||
Anyone can fork a public repository, then submit a pull request to propose changes to the repository's workflows. To prevent abuse, workflows will not run automatically on pull requests created by some contributors.
|
||||
|
||||
You can configure which pull requests require approval before they are run.
|
||||
|
||||
* **Require approval for first-time contributors who are new to {% data variables.product.prodname_dotcom %}**. Requires approval for users who have never committed to the repository and have new {% data variables.product.prodname_dotcom %} accounts.
|
||||
* **Require approval for first-time contributors**. Requires approval for users who have never committed to the repository.
|
||||
* **Require approval for all outside collaborators**. Requires approval for all users who are not organization members.
|
||||
|
||||
> [!NOTE] Workflows on the base branch triggered by `pull_request_target` events will always run, regardless of approval settings.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Fork pull request workflows in private repositories
|
||||
|
||||
You can control how users can run workflows on `pull_request` events in private and internal repositories.
|
||||
|
||||
* **Run workflows from fork pull requests**. Users can run workflows from fork pull requests. By default, workflows will use a `GITHUB_TOKEN` with read-only permission, with no access to secrets.
|
||||
* **Send write tokens to workflows from pull requests**. Workflows will use a `GITHUB_TOKEN` with write permission.
|
||||
* **Send secrets to workflows from pull requests**. All secrets are available to the pull request.
|
||||
{%- ifversion actions-private-fork-workflow-approvals %}
|
||||
* **Require approval for fork pull request workflows**. Workflows on pull requests from collaborators without write permission will require approval from someone with write permission before they will run.
|
||||
{%- endif %}
|
||||
|
||||
If a policy is enabled for an enterprise, the policy can be selectively disabled in individual organizations or repositories. If a policy is disabled for an enterprise, individual organizations or repositories cannot enable it.
|
||||
|
||||
{% ifversion ghec or ghes %}
|
||||
|
||||
## Workflow permissions
|
||||
|
||||
In the "Workflow permissions" section, you can set the **default** permissions granted to the `GITHUB_TOKEN`.
|
||||
|
||||
* **Read and write permissions**: By default, `GITHUB_TOKEN` has read and write access for all scopes.
|
||||
* **Read repository contents and packages permissions**: By default, `GITHUB_TOKEN` has only read access for the `contents` and `packages` scopes. The more permissive setting cannot be chosen as the default for individual organizations or repositories.
|
||||
|
||||
Anyone with write access to a repository can still modify the permissions granted to the `GITHUB_TOKEN` for a specific workflow, by editing the `permissions` key in the workflow file.
|
||||
|
||||
**Allow GitHub Actions to create and approve pull requests** is disabled by default. If you enable this setting, `GITHUB_TOKEN` can create and approve pull requests.
|
||||
|
||||
{% endif %}
|
||||
|
||||
@@ -1,5 +1 @@
|
||||
{% note %}
|
||||
|
||||
**Note**: When creation of repository-level self-hosted runners is disabled, workflows can still access self-hosted runners that have been set up at the enterprise or organization level.
|
||||
|
||||
{% endnote %}
|
||||
> [!NOTE] When creation of repository-level self-hosted runners is disabled, workflows can still access self-hosted runners at the enterprise or organization level.
|
||||
|
||||
Reference in New Issue
Block a user