Use client ID and document setup pitfalls

.github/workflows/README.md

@@ -18,10 +18,18 @@ workflow; the org workflow template **Add to project** (Actions → New workflow
      - Repository → Issues: **Read**
      - Repository → Pull requests: **Read & write**
    - Installable on this account only, then **Install** on **All repositories**.
-   - Generate a private key and note the App ID.
+   - Generate a private key and note the Client ID.
+
+   The Projects permission lives under **Organization permissions**, not the
+   identically named one under Repository permissions — an org project board is
+   unreachable with only the repository grant.
+
+   Creating the app does not install it. Install it explicitly, and re-approve
+   the installation whenever the app's permissions change, or the installation
+   keeps the permissions it was created with.
 
 2. **Store the credentials** (Org → Settings → Secrets and variables → Actions):
-   - Variable `PDC_BOT_APP_ID` — the App ID.
+   - Variable `PDC_BOT_CLIENT_ID` — the Client ID (`Iv23...`), not the App ID.
    - Variable `ADD_TO_PROJECT_URL` — the project URL,
      e.g. `https://github.com/orgs/PhilanthropyDataCommons/projects/<n>`.
    - Secret `PDC_BOT_PRIVATE_KEY` — the contents of the downloaded `.pem`.
@@ -33,7 +41,15 @@ workflow; the org workflow template **Add to project** (Actions → New workflow
    **Accessible from repositories in the organization**.
 
 A repository's caller workflow does not succeed until all three steps above are
-complete and the `v1` tag exists.
+complete and the `v1` tag exists. To check what the installation was actually
+granted:
+
+```sh
+gh api /orgs/PhilanthropyDataCommons/installations \
+  --jq '.installations[] | select(.app_slug=="pdc-bot") | .permissions'
+```
+
+`organization_projects: write` must be present.
 
 ### Adding a repository
 
@@ -47,6 +63,8 @@ on:
   issues:
     types: [opened, transferred, reopened]
 
+permissions: {}
+
 jobs:
   add-to-project:
     uses: PhilanthropyDataCommons/.github/.github/workflows/add-to-project.yml@v1
@@ -65,12 +83,19 @@ reach any repository until the tag moves. To publish the current state of
 `main`:
 
 ```sh
-git tag -f v1 main
+git fetch origin
+git tag -f v1 origin/main
 git push -f origin v1
 ```
 
+Tag `origin/main` rather than `main` so a stale local checkout cannot publish
+the wrong commit under a force-pushed tag.
+
+Do not attach a GitHub release to `v1`. Releases can be marked immutable, which
+would permanently prevent the tag from moving.
+
 Cut a `v2` rather than moving `v1` for a breaking change — a new required secret
-or input, or a different trigger contract — and repoint each caller as it is
+or input, or a different trigger contract — and update each caller as it is
 ready.
 
 Actions used inside the reusable workflow are pinned to exact patch versions and

.github/workflows/add-to-project.yml

@@ -16,7 +16,7 @@ jobs:
         id: token
         uses: actions/create-github-app-token@v3.2.0
         with:
-          app-id: ${{ vars.PDC_BOT_APP_ID }}
+          client-id: ${{ vars.PDC_BOT_CLIENT_ID }}
           private-key: ${{ secrets.PDC_BOT_PRIVATE_KEY }}
           owner: ${{ github.repository_owner }}
 

workflow-templates/add-to-project.yml

@@ -4,6 +4,8 @@ on:
   issues:
     types: [opened, transferred, reopened]
 
+permissions: {}
+
 jobs:
   add-to-project:
     uses: PhilanthropyDataCommons/.github/.github/workflows/add-to-project.yml@v1