Update github-actions documentation (#9426)

Merge pull request 9426

.github/actions/spelling/expect.txt

@@ -62,6 +62,7 @@ bridgetownrb
 brightbox
 brighterplanet
 buddyworks
+builtatlightspeed
 Bugfix
 Burela
 byparker
@@ -317,6 +318,7 @@ Kewin
 keycdn
 kickster
 Kinnula
+kinsta
 kiwifruit
 Kolesky
 konklone

docs/_docs/continuous-integration/github-actions.md

@@ -10,8 +10,9 @@ with GitHub Pages you can use GitHub Actions.
 
 ### Control over gemset
 
-- **Jekyll version** --- Instead of using the currently enabled version at `3.9.0`, you can use any
-  version of Jekyll you want. For example `{{site.version}}`, or point directly to the repository.
+- **Jekyll version** --- Instead of using the classic GitHub Pages provided version at `3.9.3`, you
+  can use any version of Jekyll you want. For example `{{site.version}}`, or point directly to the
+  repository.
 - **Plugins** --- You can use any Jekyll plugins irrespective of them being on the
   [supported versions][ghp-whitelist] list, even `*.rb` files placed in the `_plugins` directory
   of your site.
@@ -30,17 +31,6 @@ The first and foremost requirement is a Jekyll project hosted at GitHub. Choose
 project or follow the [quickstart]({{ '/docs/' | relative_url }}) and push the repository to GitHub
 if it is not hosted there already.
 
-We're only going to cover builds from the `main` branch in this page. Therefore, ensure that you
-are working on the `main` branch. If necessary, you may create it based on your default branch.
-When the Action builds your site, the contents of the _destination_ directory will be automatically
-pushed to the `gh-pages` branch with a commit, ready to be used for serving.
-
-{: .note .warning}
-The Action we're using here will create (or reset an existing) `gh-pages` branch on every successful
-deploy.<br/> So, if you have an existing `gh-pages` branch that is used to deploy your production
-build, ensure to make a backup of the contents into a different branch so that you can rollback
-easily if necessary.
-
 The Jekyll site we'll be using for the rest of this page initially consists of just a `_config.yml`,
 an `index.md` page and a `Gemfile`. The contents are respectively:
 
@@ -91,96 +81,17 @@ was generated with an old version of Bundler.
 
 ### Setting up the Action
 
-GitHub Actions are registered for a repository by using a YAML file inside the directory path
-`.github/workflows` (note the dot at the start). For simplicity, here we use one of the
-[Jekyll Actions](#external-links) to show you how to use the action.
-
-Create a **workflow file**, say `github-pages.yml`, using either the GitHub interface or by pushing
-a YAML file to the workflow directory path manually. The base contents are:
-
-{% raw %}
-
-```yaml
-name: Build and deploy Jekyll site to GitHub Pages
-
-on:
-  push:
-    branches:
-      - main # or master before October 2020
-
-jobs:
-  github-pages:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/cache@v2
-        with:
-          path: vendor/bundle
-          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
-          restore-keys: |
-            ${{ runner.os }}-gems-
-      - uses: helaili/jekyll-action@2.0.5    # Choose any one of the Jekyll Actions
-        with:                                # Some relative inputs of your action
-          token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-{% endraw %}
-
-The above workflow can be explained as the following:
-
-- We trigger the build using **on.push** condition for `main` branch only --- this prevents
-  the Action from overwriting the `gh-pages` branch on any feature branch pushes.
-- The **name** of the job matches our YAML filename: `github-pages`.
-- The **checkout** action takes care of cloning your repository.
-- The **cache** action is an optimization to avoid fetching and installing gems on every build.
-- We specify our selected **action** and **version number** using `helaili/jekyll-action@2.0.5`,
-  this handles the build and deploy. You can choose any one of the Jekyll Actions that matches
-  your project and flavor from [GitHub Marketplace](https://github.com/marketplace?type=actions&query=jekyll+action).
-- We set a reference to a secret **environment variable** for the action to use. The `GITHUB_TOKEN`
-  is a secret token automatically initialized at the start of every workflow run.
-  More information can be found in [GitHub documentation](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret). 
-
-Instead of using the **on.push** condition, you could trigger your build on a **schedule** by
-using the [on.schedule] parameter. For example, here we build daily at midnight by specifying
-**cron** syntax, which can be tested at the [crontab guru] site.
-
-```yaml
-on:
-  schedule:
-    - cron: "0 0 * * *"
-```
-
-Note that this string must be quoted to prevent the asterisks from being evaluated incorrectly.
-
-[on.schedule]: https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#onschedule
-[crontab guru]: https://crontab.guru/
-
-### Providing permissions
-
-At the start of each workflow run, GitHub automatically creates a unique `GITHUB_TOKEN` secret to use in
-your workflow. You can use the `GITHUB_TOKEN` to authenticate in a workflow run. You can use the
-`GITHUB_TOKEN` by using the standard syntax for referencing secrets: `${{ secrets.GITHUB_TOKEN }}`.
-For more information, please read [GitHub's docs on token authentication][github-token-ref]
-
-[github-token-ref]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
-
-If you need a token that requires permissions that aren't available in the `GITHUB_TOKEN`, you can create
-a Personal Access Token (PAT), and set it as a secret in your repository for this action to push to the
-`gh-pages` branch:
-
-1. On your GitHub profile, under **Developer Settings**, go to the [Personal Access Tokens][tokens]
-   section.
-2. **Create** a token. Give it a name like "GitHub Actions" and ensure it has permissions to
-   `public_repos` (or the entire `repo` scope for private repository) --- necessary for the action
-   to commit to the `gh-pages` branch.
-3. **Copy** the token value.
-4. Go to your repository's **Settings** and then the **Secrets** tab.
-5. **Create** a token named `YOUR_CUSTOM_TOKEN` (_important_). Give it a value using the value copied
-   above.
+1. Go to the **Settings** tab on your repository.
+    1. Click **Pages** under **Code and automation**.
+    2. Change **Source** under **Build and deployment** from **Deploy from a branch** to **GitHub Actions**.
+2. Go to the **Actions** tab on your repository.
+    1. Start a **New workflow** and search for **Jekyll**.
+    2. Click **Configure** under the **Jekyll** workflow (not **GitHub Pages Jekyll** workflow).
+    3. Review the change and click **Commit changes**.
 
 ### Build and deploy
 
-On pushing any local changes onto `main`, the action will be triggered and the build will
+On pushing any local changes onto the default branch, the action will be triggered and the build will
 **start**.
 
 To watch the progress and see any build errors, check on the build **status** using one of the
@@ -193,40 +104,18 @@ following approaches:
 - **Actions tab**
   - Go to the repository's Actions tab. Click on the `jekyll` workflow tab.
 
-If all goes well, all steps will be green and the built assets will now exist on the `gh-pages`
-branch.
-
-On a successful build, GitHub Pages will **publish** the site stored on the repository `gh-pages`
-branches. Note that you do not need to setup a `gh-pages` branch or enable GitHub Pages, as the
-action will take care of this for you.
-(For private repositories, you'll have to upgrade to a paid plan).
-
-To see the **live site**:
-
-1. Go to the **environment** tab on your repository.
-2. Click **View Deployment** to see the deployed site URL.
-3. View your site at the **URL**. Make sure the `timeago` filter works as expected.
-4. Optionally **add** this URL to your repository's main page and to your `README.md`, to make it
-   easy for people to find.
+If all goes well, all steps will be green and the built assets will be uploaded to GitHub Pages. 
 
-When you need to make further **changes** to the site, commit to `master` and push. The workflow
-will build and deploy your site again.
+To see the **live site**, go to the **Deployments** tab on your repository, and click on the deployed
+site URL.
 
-Be sure **not to edit** the `gh-pages` branch directly, as any changes will be lost on the next
-successful deploy from the Action.
+When you need to make further **changes** to the site, commit to the default branch and push.
+The workflow will build and deploy your site again.
 
 ## External links
 
-- [jekyll-actions] is an action available on the GitHub Marketplace and was used in this guide.
-- [jekyll-actions-quickstart] is an unofficial repository that includes a live demo of the
-  `jekyll-actions` action. That project can be used as a template for making a new site.
-- [jekyll-action-ts] is another action to build and publish Jekyll sites on GiHub Pages that includes HTML formatting options with Prettier and caching.
-- [jekyll-deploy-action] is a GitHub Action to deploy the Jekyll site conveniently for GitHub Pages (An alternative action with better speed and compatibility).
+- [starter-workflows] is the official repository providing the workflow template used in this guide.
 
 [ghp-whitelist]: https://pages.github.com/versions/
 [timeago-plugin]: https://rubygems.org/gems/jekyll-timeago
-[tokens]: https://github.com/settings/tokens
-[jekyll-actions]: https://github.com/marketplace/actions/jekyll-actions
-[jekyll-actions-quickstart]: https://github.com/MichaelCurrin/jekyll-actions-quickstart
-[jekyll-action-ts]: https://github.com/limjh16/jekyll-action-ts
-[jekyll-deploy-action]: https://github.com/jeffreytse/jekyll-deploy-action
+[starter-workflows]: https://github.com/actions/starter-workflows/blob/main/pages/jekyll.yml