[2023-01-04]: RubyGems Package Registry migration to v2 (#33347)

Co-authored-by: Vanessa <vgrl@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>

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

@@ -22,6 +22,7 @@ The following {% data variables.product.prodname_registry %} registries support
 - {% data variables.product.prodname_container_registry %}
 {% ifversion packages-npm-v2 %}- npm registry{% endif %}
 {% ifversion packages-nuget-v2 %}- NuGet registry{% endif %}
+{% ifversion packages-rubygems-v2 %}- RubyGems registry{% endif %}
 
 {% endif %}
 
@@ -34,10 +35,10 @@ The following {% data variables.product.prodname_registry %} registries **only**
 
 {% ifversion not fpt or ghec %}- Docker registry (`docker.pkg.github.com`){% endif %}
 {% ifversion packages-npm-v2 %}{% else %}- npm registry{% endif %}
-- RubyGems registry
 - Apache Maven registry
 - Gradle registry
 {% ifversion packages-nuget-v2 %}{% else %}- NuGet registry{% endif %}
+{% ifversion packages-rubygems-v2 %}{% else %}- RubyGems registry{% endif %}
 
 For {% ifversion ghes %}the {% data variables.product.prodname_container_registry %}{% else %}other registries{% endif %}, you can choose to allow packages to be scoped to a user or an organization, or linked to a repository. {% ifversion docker-ghcr-enterprise-migration %}For information about migration to the {% data variables.product.prodname_container_registry %}, see "[Migrating to the {% data variables.product.prodname_container_registry %} from the Docker registry](/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry)."{% endif %}
 

content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md

@@ -26,6 +26,8 @@ You can extend the CI and CD capabilities of your repository by publishing or in
 {% ifversion packages-registries-v2 %}
 ### Authenticating to package registries with granular permissions
 
+Some {% data variables.product.prodname_registry %} registries support granular permissions. This means you can choose to allow packages to be owned by a user or an organization, or linked to a repository. For the list of registries that support granular permissions, see "[About permissions for {% data variables.product.prodname_registry %}](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages)." 
+
 {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
 
 ### Authenticating to package registries with repository-scoped permissions

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

@@ -42,10 +42,19 @@ When installing or publishing a Docker image, the {% data variables.product.prod
 
 ## Authenticating to the {% data variables.product.prodname_container_registry %}
 
-{% ifversion fpt or ghec or ghes > 3.4 %}
-To authenticate to the {% data variables.product.prodname_container_registry %} (`ghcr.io`) within a {% data variables.product.prodname_actions %} workflow, use the `GITHUB_TOKEN` for the best security and experience. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
+{% data reusables.package_registry.authenticate-packages %}
+
+{% ifversion packages-registries-v2 %}
+
+### Authenticating in a {% data variables.product.prodname_actions %} workflow
+
+This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
+
+{% data reusables.package_registry.v2-actions-codespaces %}
 {% endif %}
 
+### Authenticating with a {% data variables.product.pat_v1 %}
+
 {% ifversion ghes %}Ensure that you replace `HOSTNAME` with {% data variables.location.product_location_enterprise %} hostname or IP address in the examples below.{% endif %}
 
 {% data reusables.package_registry.authenticate-to-container-registry-steps %}
@@ -62,7 +71,7 @@ This example pushes the `2.5` version of the image.
   $ docker push {% data reusables.package_registry.container-registry-hostname %}/OWNER/IMAGE_NAME:2.5
   ```
 
-When you first publish a package, the default visibility is private. To change the visibility or set access permissions, see "[Configuring a package's access control and visibility](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)."
+{% data reusables.package_registry.publishing-user-scoped-packages %} You can link a published package to a repository using the user interface or command line. For more information, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package)."
 
 ## Pulling container images
 

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

@@ -37,9 +37,11 @@ If you reach this limit, consider deleting package versions or contact Support f
 {% data reusables.package_registry.authenticate-packages %}
 
 {% ifversion packages-npm-v2 %}
-{% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
+### Authenticating in a {% data variables.product.prodname_actions %} workflow
 
-You can also choose to give access permissions to packages independently for {% data variables.product.prodname_codespaces %} and {% data variables.product.prodname_actions %}. For more information, see "[Ensuring Codespaces access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-codespaces-access-to-your-package) and [Ensuring workflow access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package)."
+This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
+
+{% data reusables.package_registry.v2-actions-codespaces %}
 {% endif %}
 
 ### Authenticating with a {% data variables.product.pat_generic %}
@@ -104,7 +106,7 @@ $ npm login --scope=@OWNER --registry=https://HOSTNAME/_registry/npm/
 {% ifversion packages-npm-v2 %}
 The {% data variables.product.prodname_registry %} registry stores npm packages within your organization or personal account, and allows you to associate a package with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.
 
-{% data reusables.package_registry.publishing-user-scoped-packages %}
+{% data reusables.package_registry.publishing-user-scoped-packages %} For more information on linking a published package with a repository, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package)."
 {% endif %}
 
 By default, {% data variables.product.prodname_registry %} publishes a package in the {% data variables.product.prodname_dotcom %} repository 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.

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

@@ -26,22 +26,28 @@ shortTitle: NuGet registry
 
 {% data reusables.package_registry.authenticate-packages %}
 
-{% ifversion packages-nuget-v2 %}
-You can choose to give access permissions to packages independently for {% data variables.product.prodname_github_codespaces %} and {% data variables.product.prodname_actions %}. For more information, see "[Ensuring Codespaces access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-codespaces-access-to-your-package)" and "[Ensuring workflow access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package)."
-{% endif %}
+### Authenticating in a {% data variables.product.prodname_actions %} workflow
 
-### Authenticating with `GITHUB_TOKEN` in {% data variables.product.prodname_actions %}
+{% ifversion packages-nuget-v2 %}
+This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} {% endif %}
 
 Use the following command to authenticate to {% data variables.product.prodname_registry %} in a {% data variables.product.prodname_actions %} workflow using the `GITHUB_TOKEN` instead of hardcoding a {% data variables.product.pat_generic %} in a nuget.config file in the repository:
 
 ```shell
 dotnet nuget add source --username USERNAME --password {%raw%}${{ secrets.GITHUB_TOKEN }}{% endraw %} --store-password-in-clear-text --name github "https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/OWNER/index.json"
 ```
+{% ifversion packages-nuget-v2 %}{% else %}{% data reusables.package_registry.authenticate-packages-github-token %}{% endif %}
 
-{% data reusables.package_registry.authenticate-packages-github-token %}
+{% ifversion packages-nuget-v2 %}
+
+{% data reusables.package_registry.v2-actions-codespaces %}
+
+{% endif %}
 
 ### Authenticating with a {% data variables.product.pat_generic %}
 
+{% data reusables.package_registry.authenticate-packages %}
+
 {% data reusables.package_registry.required-scopes %}
 
 To authenticate to {% data variables.product.prodname_registry %} with the `dotnet` command-line interface (CLI), create a *nuget.config* file in your project directory specifying {% data variables.product.prodname_registry %} as a source under `packageSources` for the `dotnet` CLI client.
@@ -99,7 +105,7 @@ You can publish a package to {% data variables.product.prodname_registry %} by a
 
 The NuGet registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.
 
-{% data reusables.package_registry.publishing-user-scoped-packages %}
+{% data reusables.package_registry.publishing-user-scoped-packages %} For more information on linking a published package with a repository, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package)."
 
 If you specify a `RepositoryURL` in your `nuget.config` file, the published package will automatically be connected to the specified repository. For more information, see "[Publishing a package using a `nuget.config` file](/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#publishing-a-package-using-a-nugetconfig-file)." For information on linking an already-published package to a repository, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package)."
 

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

@@ -40,7 +40,15 @@ shortTitle: RubyGems registry
 
 {% data reusables.package_registry.authenticate-packages %}
 
-{% data reusables.package_registry.authenticate-packages-github-token %}
+{% ifversion packages-rubygems-v2 %}
+
+### Authenticating in a {% data variables.product.prodname_actions %} workflow
+
+This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %}
+
+{% data reusables.package_registry.v2-actions-codespaces %}
+
+{% endif %}
 
 ### Authenticating with a {% data variables.product.pat_generic %}
 
@@ -79,16 +87,14 @@ $ bundle config https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% els
 
 ## Publishing a package
 
-{% data reusables.package_registry.default-name %} For example, when you publish `<GEM NAME>` to the `octo-org` organization, {% data variables.product.prodname_registry %} publishes the gem to the `octo-org/<GEM NAME>` repository. 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.viewing-packages %}
+{% 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.authenticate-step %}
-2. Build the package from the *gemspec* to create the *.gem* package.
+1. Build the package from the *gemspec* to create the *.gem* package.
   ```
   gem build <GEM NAME>.gemspec
   ```
-3. Publish a package to {% data variables.product.prodname_registry %}, replacing `OWNER` with the name of the user or organization account that owns the repository containing your project and `<GEM NAME>` with the name of your gem package.{% ifversion ghes %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace *HOSTNAME* with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif ghae %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry, `rubygems.HOSTNAME`. Replace *HOSTNAME* with the hostname of {% data variables.location.product_location %}.{% endif %}
+1. Publish a package to {% data variables.product.prodname_registry %}, replacing `OWNER` with the name of {% ifversion packages-rubygems-v2 %}your user or organization account{% else %}the user or organization account that owns the repository containing your project{% endif %} and `<GEM NAME>` with the name of your gem package.{% ifversion ghes %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace *HOSTNAME* with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif ghae %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry, `rubygems.HOSTNAME`. Replace *HOSTNAME* with the hostname of {% data variables.location.product_location %}.{% endif %}
 
   ```
   $ gem push --key github \
@@ -96,6 +102,22 @@ $ bundle config https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% els
   <GEM NAME>-0.0.1.gem
   ```
 
+{% ifversion packages-rubygems-v2 %}
+
+## Connecting a package to a repository
+
+The RubyGems registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.
+
+You can ensure gems will be linked to a repository as soon as they are published by including the URL of the {% data variables.product.prodname_dotcom %} repository in the `github_repo` field in `gem.metadata`. You can link multiple gems to the same repository. {% ifversion ghes %} In the following example, replace *HOSTNAME* with the host name of {% data variables.location.product_location %}.{% endif %}
+
+```ruby
+gem.metadata = { "github_repo" => "ssh://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY" }
+```
+
+For information on linking a published package with a repository, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package)."
+
+{% else %} 
+
 ## Publishing multiple packages to the same repository
 
 To publish multiple gems to the same repository, you can include the URL to the {% data variables.product.prodname_dotcom %} repository in the `github_repo` field in `gem.metadata`. If you include this field, {% data variables.product.prodname_dotcom %} matches the repository based on this value, instead of using the gem name.{% ifversion ghes or ghae %} Replace *HOSTNAME* with the host name of {% data variables.location.product_location %}.{% endif %}
@@ -104,12 +126,14 @@ To publish multiple gems to the same repository, you can include the URL to the
 gem.metadata = { "github_repo" => "ssh://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY" }
 ```
 
+{% endif %}
+
 ## Installing a package
 
 You can use gems from {% data variables.product.prodname_registry %} much like you use gems from *rubygems.org*. You need to authenticate to {% data variables.product.prodname_registry %} by adding your {% data variables.product.prodname_dotcom %} user or organization as a source in the *~/.gemrc* file or by using Bundler and editing your *Gemfile*.
 
 {% data reusables.package_registry.authenticate-step %}
-1. For Bundler, add your {% data variables.product.prodname_dotcom %} user or organization as a source in your *Gemfile* to fetch gems from this new source. For example, you can add a new `source` block to your *Gemfile* that uses {% data variables.product.prodname_registry %} only for the packages you specify, replacing *GEM NAME* with the package you want to install from {% data variables.product.prodname_registry %} and *OWNER* with the user or organization that owns the repository containing the gem you want to install.{% ifversion ghes %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace *HOSTNAME* with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif ghae %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry, `rubygems.HOSTNAME`. Replace *HOSTNAME* with the hostname of {% data variables.location.product_location %}.{% endif %}
+1. For Bundler, add your {% data variables.product.prodname_dotcom %} user or organization as a source in your *Gemfile* to fetch gems from this new source. For example, you can add a new `source` block to your *Gemfile* that uses {% data variables.product.prodname_registry %} only for the packages you specify, replacing *GEM NAME* with the package you want to install from {% data variables.product.prodname_registry %} and *OWNER* with the user or organization that owns {% ifversion packages-rubygems-v2 %}{%else%}the repository containing {% endif %}the gem you want to install.{% ifversion ghes %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace *HOSTNAME* with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% elsif ghae %} Replace `REGISTRY-URL` with the URL for your instance's Rubygems registry, `rubygems.HOSTNAME`. Replace *HOSTNAME* with the hostname of {% data variables.location.product_location %}.{% endif %}
 
   ```ruby
   source "https://rubygems.org"

data/features/packages-nuget-v2.yml

@@ -1,5 +1,5 @@
 # Issue 7874
-# npm NuGet Registry Improvements (v2) Public Beta
+# npm NuGet Registry Improvements (v2)
 versions:
   fpt: '*'
   ghec: '*'

data/features/packages-rubygems-v2.yml

@@ -0,0 +1,5 @@
+# Issue 7872
+# RubyGems Registry Improvements (v2)
+versions:
+  fpt: '*'
+  ghec: '*'

data/reusables/package_registry/authenticate_with_pat_for_v2_registry.md

@@ -1,9 +1,3 @@
-Some {% data variables.product.prodname_registry %} registries support granular permissions. This means you can choose to allow packages to be owned by a user or an organization, or linked to a repository. For the list of registries that support granular permissions, see "[About permissions for {% data variables.product.prodname_registry %}](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages)."
+For registries that support granular permissions, if your workflow is using a {% data variables.product.pat_generic %} to authenticate to a registry, we highly recommend you update your workflow to use the `GITHUB_TOKEN`. For guidance on updating your workflows that authenticate to a registry with a {% data variables.product.pat_generic %}, see "[Upgrading a workflow that accesses a registry using a {% data variables.product.pat_generic %}](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-a-registry-using-a-personal-access-token)."
 
-For registries that support granular permissions, if your workflow is using a {% data variables.product.pat_generic %} to authenticate to a registry, then we highly recommend you update your workflow to use the `GITHUB_TOKEN`.
-
-For guidance on updating your workflows that authenticate to a registry with a {% data variables.product.pat_generic %}, see "[Upgrading a workflow that accesses a registry using a {% data variables.product.pat_generic %}](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-a-registry-using-a-personal-access-token)."
-
-For more information about the `GITHUB_TOKEN`, see "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow#using-the-github_token-in-a-workflow)."
-
-For more information about the best practices when using a registry in actions, see "[Security hardening for GitHub Actions](/actions/getting-started-with-github-actions/security-hardening-for-github-actions#considering-cross-repository-access)."
+For more information about the `GITHUB_TOKEN`, see "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow#using-the-github_token-in-a-workflow)." For more information about the best practices when using a registry in actions, see "[Security hardening for GitHub Actions](/actions/getting-started-with-github-actions/security-hardening-for-github-actions#considering-cross-repository-access)."

data/reusables/package_registry/publishing-user-scoped-packages.md

@@ -1 +1 @@
-When you first publish a package, the default visibility is private. When a package is linked to repository, the package visibility is dependent on the repository's visibility. To change the visibility or set access permissions, see "[Configuring a package's access control and visibility](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)."
+When you first publish a package, the default visibility is private. When a package is linked to a repository, the package visibility is dependent on the repository's visibility. To change the visibility or set access permissions, see "[Configuring a package's access control and visibility](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)."

data/reusables/package_registry/v2-actions-codespaces.md

@@ -0,0 +1 @@
+You can also choose to give access permissions to packages independently for {% data variables.product.prodname_github_codespaces %} and {% data variables.product.prodname_actions %}. For more information, see "[Ensuring Codespaces access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-codespaces-access-to-your-package)" and "[Ensuring workflow access to your package](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package)."