Enabling "inherit permissions" by default for Packages [GA] (#34689)

Co-authored-by: Felicity Chapman <[email protected]>
Co-authored-by: Vanessa <[email protected]>
Co-authored-by: Melanie Yarbrough <[email protected]>

Author: 4 people

assets/images/help/package-registry/package-settings.png

@@ -86,8 +86,8 @@ You can transfer a repository to another personal account or organization. For m
 
 When you transfer a repository, {% ifversion packages-registries-v2 %}{% data variables.product.prodname_dotcom %} may transfer the packages associated with the repository, depending on the registry the packages belong to.
 
-- For registries that support granular permissions, packages are scoped to a personal account or organization, and the account associated with the package does not change when you transfer a repository. If you have linked a package to a repository, the link is removed when you transfer the repository to another user, and any codespaces or {% data variables.product.prodname_actions %} workflows associated with the repository will lose access to the package. For the list of these registries, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages)."
-- For registries that only support repository-scoped permissions, packages are published directly to repositories, and {% endif %}{% data variables.product.prodname_dotcom %} transfers the packages associated with a repository as part of the repository transfer. All billable usage associated with the packages will subsequently be billed to the new owner of the repository. If the previous repository owner is removed as a collaborator on the repository, they may no longer be able to access the packages associated with the repository.{% ifversion packages-registries-v2 %} For the list of these registries, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages)."{% endif %}
+- For registries that support granular permissions, packages are scoped to a personal account or organization, and the account associated with the package does not change when you transfer a repository. If you have linked a package to a repository, the link is removed when you transfer the repository to another user. Any codespaces or {% data variables.product.prodname_actions %} workflows associated with the repository will lose access to the package. If the package inherited its access permissions from the linked repository, users will lose access to the package. For the list of these registries, see "[Granular permissions for user/organization-scoped packages](#granular-permissions-for-userorganization-scoped-packages)" above.
+- For registries that only support repository-scoped permissions, packages are published directly to repositories, and {% endif %}{% data variables.product.prodname_dotcom %} transfers the packages associated with a repository as part of the repository transfer. All billable usage associated with the packages will subsequently be billed to the new owner of the repository. If the previous repository owner is removed as a collaborator on the repository, they may no longer be able to access the packages associated with the repository.{% ifversion packages-registries-v2 %} For the list of these registries, see "[Permissions for repository-scoped packages](#permissions-for-repository-scoped-packages)" above.{% endif %}
 
 ## Maintaining access to packages in {% data variables.product.prodname_actions %} workflows
 

content/packages/learn-github-packages/about-permissions-for-github-packages.md

@@ -11,17 +11,36 @@ versions:
   ghes: '*'
 shortTitle: Access control & visibility
 ---
-{% data reusables.package_registry.container-registry-ghes-beta %}{% ifversion packages-registries-v2 %}
+{% data reusables.package_registry.container-registry-ghes-beta %}
 
-Packages with granular permissions are scoped to a personal account or organization. You can change the access control and visibility of a package separately from the repository that it is connected (or linked) to.
+{% ifversion packages-registries-v2 %}
+
+A package can inherit its visibility and access permissions from a repository, or, for registries that support granular permissions, you can set the visibility and permissions of the package separately from a repository.
+
+For the list of registries that support granular permisions, and for more information about permissions for packages, packages-related scopes for PATs, or managing permissions for your {% data variables.product.prodname_actions %} workflows, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages)."
 
-Some registries only support repository-scoped permissions. For the list of these registries, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages)."
+{% else %}
+A package inherits the permissions and visibility of the repository in which the package is published. 
 
-{% else %}A package inherits the permissions and visibility of the repository in which the package is published.{% endif %} For more information about permissions for packages, packages-related scopes for PATs, or managing permissions for your actions workflows, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages)."
+For more information about permissions for packages, packages-related scopes for PATs, or managing permissions for your {% data variables.product.prodname_actions %} workflows, see "[AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages)."
+
+{% endif %}
 
 {% ifversion packages-registries-v2 %}
 
-## Visibility and access permissions for packages
+## About inheritance of access permissions and visibility
+
+In registries that support granular permissions, packages are scoped to a personal account or organization. In these registries, you can publish a package without linking the package to a repository, then determine who can access the package by setting access permissions and visibility in the package's settings.
+
+If you publish a package that is linked to a repository, the package automatically inherits the visibility of the linked repository. {% ifversion packages-inherit-permissions %}By default, the package also inherits the access permissions of the linked repository. For example, a user who has read access to the linked repository will also have read access to the package. When a package automatically inherits access permissions, {% data variables.product.prodname_actions %} workflows in the linked repository also automatically get access to the package.
+
+A package only inherits the access permissions of a linked repository automatically if you link the repository to the package before you publish the package, such as by adding the `org.opencontainers.image.source` Docker label to a container image. If you connect a published package to a repository from the package's settings page, the package will retain its existing access permissions, and will not inherit the access permissions of the repository unless you explicitly select this option. Additionally, organizations can disable automatic inheritance of access permissions for all new packages scoped to their organization. For more information, see "[Disabling automatic inheritance of access permissions in an organization](#disabling-automatic-inheritance-of-access-permissions-in-an-organization)" below.
+
+When a package inherits permissions from a repository, to grant or remove access to your package, you must configure the permissions settings of the linked repository. If you want to set a package's access settings separately from the repository linked to the package, you must remove the inherited permissions from the package{% else %}You can also choose to have the package inherit the access permissions of the linked repository{% endif %}. For more information, see "[Selecting whether a package inherits permissions from a repository](#selecting-whether-a-package-inherits-permissions-from-a-repository)" below.
+
+If you publish a package in a registry that only supports repository-scoped permissions, the package is always linked to a repository, and always inherits the permissions of the linked repository.
+
+## About setting visibility and access permissions for packages
 
 {% data reusables.package_registry.visibility-and-access-permissions %}
 
@@ -53,24 +72,70 @@ If your package is private or internal and scoped to an organization, then you c
 The selected users or teams will automatically be given access and don't need to accept an invitation first.
 
 {% ifversion packages-registries-v2 %}
-## Inheriting access for a package from a repository
+## Selecting whether a package inherits permissions from a repository
+
+{% ifversion packages-inherit-permissions %}By default, if publish a package that is linked to a repository, the package inherits{% else %}If you link a package to a repository, you can choose whether or not the package inherits{% endif %} the access permissions of the linked repository. We recommend you let packages inherit their permissions from a repository, because this simplifies the process of managing access to a package.
+
+When a package inherits permissions from a repository, to grant or remove access to your package, you must configure the permissions of the linked repository.
+
+{% ifversion packages-inherit-permissions %}If you want to configure a package's access settings on a granular level, separately from the linked repository, you must remove the inherited permissions from the package.{% endif %}
+
+{% note %}
+
+**Note:** If you change how a package gets its access permissions, any existing permissions for the package are overwritten.
 
-For packages scoped to a personal account or an organization, to simplify package management through {% data variables.product.prodname_actions %} workflows, you can enable a package to inherit the access permissions of a repository.
+{% endnote %}
 
-If you inherit the access permissions of the repository where your package's workflows are stored, then you can adjust access to your package through the repository's permissions.
+### Selecting the inheritance setting for packages scoped to your personal account
+
+{% data reusables.package_registry.package-settings-from-user-level %}
+{% data reusables.package_registry.package-settings-option %}
+{% data reusables.package_registry.disable-auto-inheritance-step %}
 
-Once a repository is synced, you can't access the package's granular access settings. To customize the package's permissions through the granular package access settings, you must remove the synced repository first.
+### Selecting the inheritance setting for packages scoped to an organization
+
+{% ifversion packages-inherit-permissions %}
+{% tip %}
+
+**Tip:** If you're the owner of an organization, you can prevent all new packages scoped to your organization from automatically inheriting permissions from a linked repository. For more information, see "[Disabling automatic inheritance of access permissions in an organization](#disabling-automatic-inheritance-of-access-permissions-in-an-organization)" below.
+
+{% endtip %}
+{% endif %}
 
 {% data reusables.package_registry.package-settings-from-org-level %}
 {% data reusables.package_registry.package-settings-option %}
-1. Under "Manage access" or "Inherited access", select the **Inherit access from repository (recommended)** checkbox.
+{% data reusables.package_registry.disable-auto-inheritance-step %}
+
+{% endif %}
+
+{% ifversion packages-inherit-permissions %}
+
+## Disabling automatic inheritance of access permissions in an organization
+
+By default, if you publish a package that is linked to a repository, the package automatically inherits the access permissions of the linked repository. As an organization owner, you can disable automatic inheritance for all packages scoped to your organization. 
+
+If you disable automatic inheritance of access permissions, new packages scoped to your organization will not automatically inherit the permissions of a linked repository. However, anyone with admin permissions to a package in your organization will be able to enable or disable inheritance of permissions for that package.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the sidebar, in the "Code, planning, and automation" section, click **{% octicon "package" aria-label="" %} Packages**.
+1. Under "Default Package Settings", deselect **Inherit access from source repository**.
+1. Click **Save**.
+
+{% endif %}
+
+{% ifversion packages-registries-v2 %}
 
 ## Ensuring workflow access to your package
 
 For packages scoped to a personal account or an organization, to ensure that a {% data variables.product.prodname_actions %} workflow has access to your package, you must give explicit access to the repository where the workflow is stored.
 
 The specified repository does not need to be the repository where the source code for the package is kept. You can give multiple repositories workflow access to a package.
 
+{% ifversion packages-inherit-permissions %}
+If you publish a package that is linked to a repository, {% data variables.product.prodname_actions %} workflows in the linked repository automatically get access to the package, unless your organization has disabled the automatic inheritance of access permissions. For more information, see "[About inheritance of access permissions and visibility](#about-inheritance-of-access-permissions-and-visibility)" above.
+{% endif %}
+
 {% note %}
 
 **Note:** Syncing your package with a repository {% data variables.package_registry.package-settings-actions-access-menu %} is different than connecting your package to a repository. For more information about linking a repository to your package, see "[AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package)."

content/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility.md

@@ -12,7 +12,7 @@ versions:
 shortTitle: Connect a repository
 ---
 
-When you publish a package that is scoped to a personal account or an organization, the package is not linked to a repository by default. By connecting a repository to a package, the package landing page will show information and links from the repository, such as the README.
+When you publish a package that is scoped to a personal account or an organization, the package is not linked to a repository by default. If you connect a package to a repository, the package's landing page will show information and links from the repository, such as the README. The package will inherit the visibility setting of the linked repository, and you can also choose to have the package inherit its access permissions from the linked repository. For more information, see "[AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)."
 
 ## Connecting a repository to a user-scoped package on {% data variables.product.prodname_dotcom %}
 
@@ -29,6 +29,8 @@ When you publish a package that is scoped to a personal account or an organizati
 {% ifversion fpt or ghec or ghes > 3.4 %}
 ## Connecting a repository to a container image using the command line
 
+{% data reusables.package_registry.auto-inherit-permissions-note %}
+
 {% ifversion ghes > 3.4 %}
 {% data reusables.package_registry.container-registry-ghes-beta %}
 {% endif %}

content/packages/learn-github-packages/connecting-a-repository-to-a-package.md

@@ -181,6 +181,8 @@ LABEL org.opencontainers.image.description="My container image"
 LABEL org.opencontainers.image.licenses=MIT
 ```
 
+{% data reusables.package_registry.auto-inherit-permissions-note %}
+
 Alternatively, you can add labels to an image at buildtime with the `docker build` command.
 
 ```shell

content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md

@@ -123,6 +123,8 @@ The {% data variables.product.prodname_registry %} registry stores npm packages
 
 By default, your package is published in the {% data variables.product.prodname_dotcom %} repository that you specify in the name field of the *package.json* file. For example, you would publish a package named `@my-org/test` to the `my-org/test` {% data variables.product.prodname_dotcom %} repository. If you're running [npm v8.5.3](https://github.com/npm/cli/releases/tag/v8.5.3) or later, you can add a summary for the package listing page by including a *README.md* file in your package directory. For more information, see "[Working with package.json](https://docs.npmjs.com/getting-started/using-a-package.json)" and "[How to create Node.js Modules](https://docs.npmjs.com/getting-started/creating-node-modules)" in the npm documentation.
 
+{% data reusables.package_registry.auto-inherit-permissions-note %}
+
 You can publish multiple packages to the same {% data variables.product.prodname_dotcom %} repository by including a `URL` field in the *package.json* file. For more information, see "[Publishing multiple packages to the same repository](#publishing-multiple-packages-to-the-same-repository)."
 
 You can set up the scope mapping for your project using either a local *.npmrc* file in the project or using the `publishConfig` option in the *package.json*. {% data variables.product.prodname_registry %} only supports scoped npm packages. Scoped packages have names with the format of `@NAMESPACE/PACKAGE-NAME`. Scoped packages always begin with an `@` symbol. You may need to update the name in your *package.json* to use the scoped name. For example, if you're the user `octocat` and your package is named `test`, you would assign the scoped package name as follows: `"name": "@octocat/test"`.

content/packages/working-with-a-github-packages-registry/working-with-the-npm-registry.md

@@ -138,6 +138,8 @@ If you don't already have a {% data variables.product.pat_generic %} to use for
 
 When publishing, {% ifversion packages-nuget-v2 %}if you are linking your package to a repository, {% endif %}the `OWNER` of the repository specified in your *.csproj* file must match the `NAMESPACE` that you use in your *nuget.config* authentication file. Specify or increment the version number in your *.csproj* file, then use the `dotnet pack` command to create a *.nuspec* file for that version. For more information on creating your package, see "[Create and publish a package](https://docs.microsoft.com/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli)" in the Microsoft documentation.
 
+{% data reusables.package_registry.auto-inherit-permissions-note %}
+
 {% data reusables.package_registry.authenticate-step %}
 2. Create a new project. Replace `PROJECT_NAME` with the name you'd like to give the project.
   ```shell

content/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.md

@@ -89,6 +89,8 @@ $ bundle config https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% els
 
 {% ifversion packages-rubygems-v2 %}{% data reusables.package_registry.publishing-user-scoped-packages %}{% else %}By default, GitHub publishes the package to an existing repository with the same name as the package. For example, when you publish `GEM_NAME` to the `octo-org` organization, GitHub Packages publishes the gem to the `octo-org/GEM_NAME` repository.{% endif %} For more information on creating your gem, see "[Make your own gem](http://guides.rubygems.org/make-your-own-gem/)" in the RubyGems documentation.
 
+{% data reusables.package_registry.auto-inherit-permissions-note %}
+
 {% data reusables.package_registry.authenticate-step %}
 1. Build the package from the *gemspec* to create the *.gem* package. Replace `GEM_NAME` with the name of your gem.
   ```

content/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry.md

@@ -0,0 +1,5 @@
+# Issue 9145
+# Packages inherit access permissions by default
+versions:
+  fpt: '*'
+  ghec: '*'

data/features/packages-inherit-permissions.yml

@@ -0,0 +1,9 @@
+{% ifversion packages-inherit-permissions %}
+
+{% note %}
+
+**Note:** If you publish a package that is linked to a repository, the package automatically inherits the access permissions of the linked repository, and {% data variables.product.prodname_actions %} workflows in the linked repository automatically get access to the package, unless your organization has disabled automatic inheritance of access permissions. For more information, see "[AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#about-inheritance-of-access-permissions-and-visibility)."
+
+{% endnote %}
+
+{% endif %}