Improve handling of tokens in CI.

This commit fixes two problems:
1. We were hitting API rate limits when sending
unauthenticated requests.
2. The builds for the unmodified examples during a PR
were not possible to download if the PR was from a fork.

Author: pfebrer

.github/workflows/docs.yml

@@ -15,6 +15,7 @@ jobs:
     outputs:
       examplesmatrix: ${{ steps.gatherInfo.outputs.examplesjson }}
       latest_docs_run: ${{ steps.gatherInfo.outputs.latest_docs_run }}
+    permissions: read-all # Permissions for the GITHUB_TOKEN
     steps:
       - uses: actions/checkout@v4
         with:
@@ -33,7 +34,7 @@ jobs:
             GET_EXAMPLES_ARGS=" --modified-files $(git diff --name-only -r HEAD^1 HEAD)"
           fi
           echo examplesjson=$(./src/get_examples.py ${GET_EXAMPLES_ARGS}) >> $GITHUB_OUTPUT
-          echo latest_docs_run=$(./src/latest_docs_run.py id) >> $GITHUB_OUTPUT
+          echo latest_docs_run=$(./src/latest_docs_run.py id --api-token ${{ secrets.GITHUB_TOKEN }}) >> $GITHUB_OUTPUT
 
   generate-example:
     needs: setup
@@ -83,6 +84,8 @@ jobs:
     # Run this job even if the generate-example job was skipped due to
     # no examples to run. I.e. only avoid if generate-example failed.
     if: ${{ always() && needs.generate-example.result != 'failure' }}
+    # Permissions for the GITHUB_TOKEN (does not affect GH_DEPLOY_TOKEN)
+    permissions: read-all
     needs: [setup, generate-example]
     runs-on: ubuntu-latest
     steps:
@@ -102,7 +105,7 @@ jobs:
         with:
           path: docs/src/examples
           pattern: example-*
-          github-token: ${{ secrets.GH_READ_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ needs.setup.outputs.latest_docs_run }}
           merge-multiple: true
 
@@ -137,7 +140,7 @@ jobs:
         if: github.event_name == 'push'
         uses: peaceiris/actions-gh-pages@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          github_token: ${{ secrets.GH_DEPLOY_TOKEN }}
           publish_dir: ./gh-pages/
           force_orphan: true
           cname: atomistic-cookbook.org

src/latest_docs_run.py

@@ -21,7 +21,7 @@
 NIGHTLY_LINK = "https://nightly.link/lab-cosmo/atomistic-cookbook/workflows/docs/main"
 
 
-def get_latest_successful_docs_run():
+def get_latest_successful_docs_run(api_token: Optional[str] = None) -> int:
 
     doc_runs_endpoint = GITHUB_ACTIONS_API + "/workflows/docs.yml/runs"
 
@@ -32,6 +32,7 @@ def get_latest_successful_docs_run():
             "per_page": 1,
             "status": "success",
             "exclude_pull_requests": True,
+            "auth": api_token,
         },
     )
 
@@ -99,11 +100,19 @@ def download_latest_examples(
 
     subparsers = parser.add_subparsers(dest="command")
 
-    subparsers.add_parser(
+    id_parser = subparsers.add_parser(
         "id",
         help="Get the ID of the latest successful docs run",
     )
 
+    id_parser.add_argument(
+        "--api-token",
+        default=None,
+        help="""Github API token to use for the API request.
+        If not provided, the request will be unauthenticated, and there
+        are rate limits for unauthenticated requests.""",
+    )
+
     download_parser = subparsers.add_parser(
         "download-examples",
         help=download_latest_examples.__doc__,
@@ -139,4 +148,4 @@ def download_latest_examples(
             exclude=args.exclude,
         )
     elif args.command == "id":
-        print(get_latest_successful_docs_run())
+        print(get_latest_successful_docs_run(api_token=args.api_token))