repo sync

content/actions/guides/building-and-testing-ruby.md

@@ -0,0 +1,318 @@
+---
+title: Building and testing Ruby
+intro: You can create a continuous integration (CI) workflow to build and test your Ruby project.
+product: '{% data reusables.gated-features.actions %}'
+versions:
+  free-pro-team: '*'
+  enterprise-server: '>=2.22'
+---
+
+{% data reusables.actions.enterprise-beta %}
+{% data reusables.actions.enterprise-github-hosted-runners %}
+
+### Introduction
+
+This guide shows you how to create a continuous integration (CI) workflow that builds and tests a Ruby application. If your CI tests pass, you may want to deploy your code or publish a gem.
+
+### Prerequisites
+
+We recommend that you have a basic understanding of Ruby, YAML, workflow configuration options, and how to create a workflow file. For more information, see:
+
+- [Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions)
+- [Ruby in 20 minutes](https://www.ruby-lang.org/en/documentation/quickstart/)
+
+### Starting with the Ruby workflow template
+
+{% data variables.product.prodname_dotcom %} provides a Ruby workflow template that will work for most Ruby projects. For more information, see the [Ruby workflow template](https://github.com/actions/starter-workflows/blob/master/ci/ruby.yml).
+
+To get started quickly, add the template to the `.github/workflows` directory of your repository.
+
+{% raw %}
+```yaml
+name: Ruby
+
+on:
+  push:
+    branches: [ $default-branch ]
+  pull_request:
+    branches: [ $default-branch ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
+      with:
+        ruby-version: 2.6
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake
+```
+{% endraw %}
+
+### Specifying the Ruby version
+
+The easiest way to specify a Ruby version is by using the `ruby/setup-ruby` action provided by the Ruby organization on GitHub. The action adds any supported Ruby version to `PATH` for each job run in a workflow. For more information see, the [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby).
+
+Using either Ruby's `ruby/setup-ruby` action or GitHub's `actions/setup-ruby` action is the recommended way of using Ruby with GitHub Actions because it ensures consistent behavior across different runners and different versions of Ruby.
+
+The `setup-ruby` action takes a Ruby version as an input and configures that version on the runner.
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/checkout@v2
+- uses: ruby/setup-ruby@v1
+  with:
+    ruby-version: 2.6 # Not needed with a .ruby-version file
+- run: bundle install
+- run: bundle exec rake
+```
+{% endraw %}
+
+Alternatively, you can check a `.ruby-version` file  into the root of your repository and `setup-ruby` will use the version defined in that file.
+
+### Testing with multiple versions of Ruby
+
+You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 2.7, 2.6, and 2.5. The 'x' is a wildcard character that matches the latest patch release available for a version. 
+
+{% raw %}
+```yaml
+strategy:
+  matrix:
+    ruby-version: [2.7.x, 2.6.x, 2.5.x]
+```
+{% endraw %}
+
+Each version of Ruby specified in the `ruby-version` array creates a job that runs the same steps. The {% raw %}`${{ matrix.ruby-version }}`{% endraw %} context is used to access the current job's version. For more information about matrix strategies and contexts, see "Workflow syntax for GitHub Actions" and "Context and expression syntax for GitHub Actions."
+
+The full updated workflow with a matrix strategy could look like this:
+
+{% raw %}
+```yaml
+name: Ruby CI
+
+on:
+  push:
+    branches: [ $default-branch ]
+  pull_request:
+    branches: [ $default-branch ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: [2.7.x, 2.6.x, 2.5.x]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake
+```
+{% endraw %}
+
+### Installing dependencies with Bundler
+
+The `setup-ruby` action will automatically install bundler for you. The version is determined by your `gemfile.lock` file. If no version is present in your lockfile, then the latest compatible version will be installed.
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/checkout@v2
+- uses: ruby/setup-ruby@v1
+  with:
+    ruby-version: 2.6
+- run: bundle install
+```
+{% endraw %}
+
+#### Caching dependencies
+
+The `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs.
+
+To enable caching, set the following.
+
+{% raw %}
+```yaml
+steps:
+- uses: ruby/setup-ruby@v1
+    with:
+      bundler-cache: true
+```
+{% endraw %}
+
+This will configure bundler to install your gems to `vendor/cache`. For each successful run of your workflow, this folder will be cached by Actions and re-downloaded for subsequent workflow runs. A hash of your gemfile.lock and the Ruby version are used as the cache key. If you install any new gems, or change a version, the cache will be invalidated and bundler will do a fresh install.
+
+**Caching without setup-ruby**
+
+For greater control over caching, you can use the `actions/cache` Action directly. For more information, see "[Caching dependencies to speed up your workflow](/actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows)."
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/cache@v2
+  with:
+    path: vendor/bundle
+    key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+    restore-keys: |
+      ${{ runner.os }}-gems-
+- name: Bundle install
+  run: |
+    bundle config path vendor/bundle
+    bundle install --jobs 4 --retry 3
+```
+{% endraw %}
+
+If you're using a matrix build, you will want to include the matrix variables in your cache key. For example, if you have a matrix strategy for different ruby versions (`matrix.ruby-version`) and different operating systems (`matrix.os`), your workflow steps might look like this:
+
+{% raw %}
+```yaml
+steps:
+- uses: actions/cache@v2
+  with:
+    path: vendor/bundle
+    key: bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}
+    restore-keys: |
+      bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-
+- name: Bundle install
+  run: |
+    bundle config path vendor/bundle
+    bundle install --jobs 4 --retry 3
+```
+{% endraw %}
+
+### Matrix testing your code
+
+The following example matrix tests all stable releases and head versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS.
+
+{% raw %}
+```yaml
+name: Matrix Testing
+
+on:
+  push:
+    branches: [ $default-branch ]
+  pull_request:
+    branches: [ $default-branch ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu, macos]
+        ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - run: bundle install
+    - run: bundle exec rake
+```
+{% endraw %}
+
+### Linting your code
+
+The following example installs `rubocop` and uses it to lint all files. For more information, see [Rubocop](https://github.com/rubocop-hq/rubocop). You can [configure Rubocop](https://docs.rubocop.org/rubocop/configuration.html) to decide on the specific linting rules.
+
+{% raw %}
+```yaml
+name: Linting
+
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+    - run: bundle install
+    - name: Rubocop
+      run: rubocop
+```
+{% endraw %}
+
+### Publishing Gems
+
+You can configure your workflow to publish your Ruby package to any package registry you'd like when your CI tests pass.
+
+You can store any access tokens or credentials needed to publish your package using repository secrets. The following example creates and publishes a package to `GitHub Package Registry` and `RubyGems`.
+
+{% raw %}
+```yaml
+
+name: Ruby Gem
+
+on:
+  # Manually publish
+  workflow_dispatch:
+  # Alternatively, publish whenever changes are merged to the default branch.
+  push:
+    branches: [ $default-branch ]
+  pull_request:
+    branches: [ $default-branch ]
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby 2.6
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+    - run: bundle install
+
+    - name: Publish to GPR
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+      env:
+        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+        OWNER: ${{ github.repository_owner }}
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"
+```
+{% endraw %}
+

content/actions/guides/index.md

@@ -31,6 +31,7 @@ You can use {% data variables.product.prodname_actions %} to create custom conti
 {% link_in_list /building-and-testing-nodejs %}
 {% link_in_list /building-and-testing-powershell %}
 {% link_in_list /building-and-testing-python %}
+{% link_in_list /building-and-testing-ruby %}
 {% link_in_list /building-and-testing-java-with-maven %}
 {% link_in_list /building-and-testing-java-with-gradle %}
 {% link_in_list /building-and-testing-java-with-ant %}

content/actions/index.md

@@ -79,7 +79,7 @@ versions:
     <div class="mb-3">{% octicon "search" width="24" %}</div>
     <h3 class="text-normal">Sorry, there is no result for <strong class="js-code-example-filter-value"></strong></h3>
     <p class="my-3 f4">It looks like we don't have an example that fits your filter.<br>Try another filter or add your code example</p>
-    <a href="https://github.com/github/docs/blob/HEAD/data/variables/action_code_examples.yml">Learn how to add a code example {% octicon "arrow-right" %}</a>
+    <a href="https://github.com/github/docs/blob/main/data/variables/action_code_examples.yml">Learn how to add a code example {% octicon "arrow-right" %}</a>
   </div>
 </div>
 {% endif %}

content/admin/enterprise-management/configuring-collectd.md

@@ -10,7 +10,7 @@ versions:
 ---
 ### Set up an external `collectd` server
 
-If you haven't already set up an external `collectd` server, you will need to do so before enabling `collectd` forwarding on {% data variables.product.product_location %}. Your `collectd` server must by running `collectd` version 5.x or higher.
+If you haven't already set up an external `collectd` server, you will need to do so before enabling `collectd` forwarding on {% data variables.product.product_location %}. Your `collectd` server must be running `collectd` version 5.x or higher.
 
 1. Log into your `collectd` server.
 2. Create or edit the `collectd` configuration file to load the network plugin and populate the server and port directives with the proper values. On most distributions, this is located at `/etc/collectd/collectd.conf`

content/admin/packages/configuring-third-party-storage-for-packages.md

@@ -21,7 +21,10 @@ For the best experience, we recommend using a dedicated bucket for {% data varia
 
 {% warning %}
 
-**Warning:** Make sure to configure the bucket you'll want to use in the future. We do not recommend changing your storage after you start using {% data variables.product.prodname_registry %}.
+**Warnings:**
+- It's critical you set the restrictive access policies you want for your storage bucket because {% data variables.product.company_short %} does not apply specific object permissions or additional access control lists (ACLs) to your storage bucket configuration. For example, if you make your bucket public, data in the bucket will be accessible on the public internet. For more information, see [Setting bucket and object access permissions](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/set-permissions.html) in the AWS Documentation.
+- We recommend using a dedicated bucket for {% data variables.product.prodname_registry %}, separate from the bucket you use for {% data variables.product.prodname_actions %} storage.
+- Make sure to configure the bucket you'll want to use in the future. We do not recommend changing your storage after you start using {% data variables.product.prodname_registry %}.
 
 {% endwarning %}
 

content/admin/packages/index.md

@@ -1,6 +1,5 @@
 ---
 title: Managing GitHub Packages for your enterprise
-shortTitle: GitHub Packages
 intro: 'You can enable {% data variables.product.prodname_registry %} for your enterprise and manage {% data variables.product.prodname_registry %} settings and allowed packaged types.'
 redirect_from:
   - /enterprise/admin/packages