Merge pull request #23 from DeterminateSystems/readme

README: organize "Running GitHub Actions CI" instructions into own section

README.md

@@ -27,7 +27,7 @@ jobs:
           extra_nix_config: |
             access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
       - name: Update flake.lock
-        uses: DeterminateSystems/update-flake-lock@v3
+        uses: DeterminateSystems/update-flake-lock@vX
 ```
 
 ## Example updating specific input(s)
@@ -62,7 +62,11 @@ jobs:
 
 ## Running GitHub Actions CI
 
-GitHub Actions will not run workflows when a branch is pushed by or a PR is opened by a GitHub Action. To work around this, try:
+GitHub Actions will not run workflows when a branch is pushed by or a PR is opened by a GitHub Action. There are two ways to have GitHub Actions CI run on a PR submitted by this action.
+
+### Without a Personal Authentication Token
+
+Without using a Personal Authentication Token, you can manually run the following to kick off a CI run:
 
 ```
 git branch -D update_flake_lock_action
@@ -72,6 +76,32 @@ git commit --amend --no-edit
 git push origin update_flake_lock_action --force
 ```
 
+### With a Personal Authentication Token
+
+By providing a Personal Authentication Token, the PR will be submitted in a way that bypasses this limitation (GitHub will essentially think it is the owner of the PAT submitting the PR, and not an Action).
+You can create a token by visiting https://github.com/settings/tokens and select at least the `repo` scope. Then, store this token in your repository secrets (i.e. 'https://github.com/<USER>/<REPO>/settings/secrets/actions') as `GH_TOKEN_FOR_UPDATES` and set up your workflow file like the following:
+
+```yaml
+name: update-flake-lock
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: '0 0 * * 1,4' # Run twice a week
+
+jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Install Nix
+        uses: cachix/install-nix-action@v16
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@vX
+        with:
+          token: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
+```
+
 ## Contributing
 
 Feel free to send a PR or open an issue if you find something functions unexpectedly! Please make sure to test your changes and update any related documentation before submitting your PR.

action.yml

@@ -5,6 +5,10 @@ inputs:
     description: 'A space-separated list of inputs to update. Leave empty to update all inputs.'
     required: false
     default: ''
+  token:
+    description: 'GITHUB_TOKEN or a `repo` scoped Personal Access Token (PAT)'
+    required: false
+    default: ${{ github.token }}
 runs:
   using: "composite"
   steps:
@@ -38,6 +42,7 @@ runs:
         branch: update_flake_lock_action
         delete-branch: true
         title: "flake.lock: Update"
+        token: ${{ inputs.token }}
         body: |
           Automated changes by the [update-flake-lock](https://github.com/DeterminateSystems/update-flake-lock) GitHub Action.