Improve document about Github Actions section (#8853)

Merge pull request 8853

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

@@ -92,8 +92,8 @@ 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). Here we shall employ
+`.github/workflows` (note the dot at the start). For simplicity, here we use one of the
-[Jekyll Actions][jekyll-actions] from the Marketplace for its simplicity.
+[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:
@@ -119,8 +119,8 @@ jobs:
           key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
           restore-keys: |
             ${{ runner.os }}-gems-
-      - uses: helaili/jekyll-action@v2
+      - uses: helaili/jekyll-action@2.0.5    # Choose any one of the Jekyll Actions
-        with:
+        with:                                # Some relative inputs of your action
           token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
@@ -133,8 +133,9 @@ The above workflow can be explained as the following:
 - 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`.
+- We specify our selected **action** and **version number** using `helaili/jekyll-action@2.0.5`,
-  This handles the build and deploy.
+  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). 
@@ -154,6 +155,29 @@ Note that this string must be quoted to prevent the asterisks from being evaluat
 [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.
+
 ### Build and deploy
 
 On pushing any local changes onto `main`, the action will be triggered and the build will
@@ -197,6 +221,7 @@ successful deploy from the Action.
 - [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).
 
 [ghp-whitelist]: https://pages.github.com/versions/
 [timeago-plugin]: https://rubygems.org/gems/jekyll-timeago
@@ -204,3 +229,4 @@ successful deploy from the Action.
 [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