docs: enable this workflow to modify workflow files (#429)

* docs: remove unnecessary use of token for checkout in the example

* docs: enable support for submodules by default

* docs: add explanations on how to enable modifications of workflow files

* docs: fix typo and indentation

* docs: fix typo

* docs: enable support for submodules by default

* docs: disable support for submodules by default

README.md

@@ -88,8 +88,10 @@ jobs:
       # To use this repository's private action, you must check out the repository
       - name: Checkout
         uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+        # https://github.com/actions/checkout#usage
+        # uncomment if you use submodules within the source repository
+        # with:
+        #   submodules: true
 
       - name: actions-template-sync
         uses: AndreasAugustin/[email protected]
@@ -128,6 +130,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          # submodules: true
           token: ${{ steps.generate_token.outputs.token }}
 
       - name: actions-template-sync
@@ -163,6 +166,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          # submodules: true
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: actions-template-sync
@@ -216,6 +220,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
+          # submodules: true
           token: ${{ secrets.CUSTOM_GITHUB_PAT }}
 
       - name: Test action step PAT
@@ -325,13 +330,52 @@ hooks:
 
 * refusing to allow a GitHub App to create or update workflow `.github/workflows/******.yml` without `workflows` permission
 
-This happens because the template repository is trying to overwrite some files inside `.github/workflows/`.
-A GitHub action currently can't overwrite these files.
-To ignore those, simply create a file in the root directory named `.templatesyncignore` with the content `.github/workflows/`.
+  This happens because the template repository is trying to overwrite some files inside `.github/workflows/`.
+
+  Currently `GITHUB_TOKEN` can't be given `workflow` permission. You can grant our workflow with `workflows` permission using a PAT following the steps below:
+
+  1. [Create a PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) with these repository permissions granted: `contents:write`, `workflows:write`, `metadata:read`.
+
+  2. Copy the generated token and [create a new secret for your target repository](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
+
+  3. Configure the `checkout` action to use the token in secrets like this:
+     ```yaml
+     # File: .github/workflows/template-sync.yml
+
+     on:
+         # cronjob trigger
+       schedule:
+       - cron:  "0 0 1 * *"
+       # manual trigger
+       workflow_dispatch:
+     jobs:
+       repo-sync:
+         runs-on: ubuntu-latest
+         # https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
+         permissions:
+           contents: write
+           pull-requests: write
+
+         steps:
+           # To use this repository's private action, you must check out the repository
+           - name: Checkout
+             uses: actions/checkout@v4
+             with:
+               # submodules: true
+               token: ${{ secrets.<secret_name> }}
+
+           - name: actions-template-sync
+             uses: AndreasAugustin/[email protected]
+             with:
+               github_token: ${{ secrets.GITHUB_TOKEN }}
+               source_repo_path: <owner/repo>
+               upstream_branch: <target_branch> # defaults to main
+               pr_labels: <label1>,<label2>[,...] # optional, no default
+     ```
 
 * pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)
 
-Open your project `Settings > Actions > General` and select the checkbox `Allow GitHub Actions to create and approve pull requests`
+  Open your project `Settings > Actions > General` and select the checkbox `Allow GitHub Actions to create and approve pull requests`
 under the `Workflow permissions` section.
 
 ## Release Updates