add some docs

.github/workflows/comment-on-forks.yml

@@ -1,4 +1,4 @@
-name: Covector Comment
+name: covector comment on forks
 
 on:
   workflow_run:

.github/workflows/run-on-pr.yml

@@ -1,4 +1,4 @@
-name: covector
+name: covector status
 on: pull_request
 
 jobs:

README.md

@@ -1,6 +1,5 @@
 # covector
 
-
 Transparent and flexible change management for publishing packages and assets. Publish and deploy from a single asset repository, monorepos, and even multi-language repositories.
 
 ## Docs
@@ -21,7 +20,6 @@ Below is a list of all of the packages within this repository. The usage and doc
 | [@covector/command](./packages/command)     | [![npm](https://img.shields.io/npm/v/@covector/command?style=for-the-badge)](https://www.npmjs.com/package/@covector/command)     | [./packages/command/CHANGELOG.md](https://github.com/jbolda/covector/blob/main/packages/command/CHANGELOG.md)     |
 | [@covector/files](./packages/files)         | [![npm](https://img.shields.io/npm/v/@covector/files?style=for-the-badge)](https://www.npmjs.com/package/@covector/files)         | [./packages/files/CHANGELOG.md](https://github.com/jbolda/covector/blob/main/packages/files/CHANGELOG.md)         |
 
-
 ## Prior Art
 
 We drew on inspiration from [changesets](https://github.com/atlassian/changesets) which specifically focuses on the npm ecosystem with the expectation to publish to [npmjs.com](https://www.npmjs.com/). We had a need for much greater flexibility, primarily around additional languages, which changesets wasn't looking to handle. You may notice some similarities around the markdown based change files, and it begins to diverge from there. Since we started the codebase from scratch, it also opened the door for incredibly flexible and unique publishing schemes, deep changelogs, and the ability to publish to any "target" with any "asset" (such as publishing a website, a github action or a vscode extension even!).

packages/action/README.md

@@ -58,3 +58,39 @@ Besides these static outputs, we also supply dynamic outputs for each of your pa
 Outputs will generally be specified in the [action.yml](./action.yml), but since these are dynamic, it is not possible. See the [docs noting this is an optional required](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#outputs).
 
 > If you don't declare an output in your action metadata file, you can still set outputs and use them in a workflow.
+
+## Comments On Forks
+
+The action runs in a reduced-permission environment on forks which will cause an API call to add a comment to fail. To work around this, with `comment: true` specified, it will upload the comment content as an artifact to the workflow if it fails. With the following additional workflow, it will pick up that workflow completion and post the comment as `workflow_run` has normal repository permissions.
+
+```yml
+name: Covector Comment
+
+on:
+  workflow_run:
+    workflows: [covector status] # the `name` of the workflow run on `pull_request` running `status` with `comment: true`
+    types:
+      - completed
+
+# note all other permissions are set to none if not specified
+permissions:
+  # to read the action artifacts
+  actions: read
+  # to write the comment
+  pull-requests: write
+# note that these set the permissions for `secrets.GITHUB_TOKEN`
+#  if you plan to use your own token, use `permissions: {}` instead
+#  to completely remove all default permissions for added security
+
+jobs:
+  download:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success' &&
+      (github.event.workflow_run.head_repository.full_name != github.repository || github.actor == 'dependabot[bot]')
+    steps:
+      - name: covector status
+        uses: jbolda/covector/packages/action@covector-v0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          command: "status"
+```