docs: updates README usage and adds TROUBLESHOOTING.md

Signed-off-by: Jennifer Power <[email protected]>

.github/pull_request_template.md

@@ -1,14 +1,12 @@
-# [Pull request title here]
-
 ## Description
 
-Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+<!--Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.-->
 
 Fixes # (issue)
 
 ## Type of change
 
-Please delete options that are not relevant.
+<!--Please delete options that are not relevant.-->
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
@@ -17,7 +15,7 @@ Please delete options that are not relevant.
 
 ## How has this been tested?
 
-Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+<!--Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration-->
 
 - [ ] Test A
 - [ ] Test B

README.md

@@ -2,20 +2,47 @@
 
 trestle-bot assists users in leveraging [Compliance-Trestle](https://github.com/IBM/compliance-trestle) in automated workflows or [OSCAL](https://github.com/usnistgov/OSCAL) formatted compliance content management. 
 
-In addition to trestle-bot, this repo contains the trestle-bot GitHub Action that can optionally be used to host the tresle-bot service within GitHub Actions.
+In addition to trestle-bot, this repo contains the trestle-bot GitHub Action that can optionally be used to host the trestle-bot service within GitHub Actions.
 
 > WARNING: This project is under active development.
 
-## Usage
+## Basic Configuration
 
-trestle-bot supports the following commands:
 
-### `/assemble`
-Converts repo defined markdown formatted OSCAL content to JSON.
+```
+
+name: Example Workflow
+...
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run trestlebot
+        id: trestlebot
+        uses: RedHatProductSecurity/trestle-bot@main
+        with:
+          markdown_path: "markdown/profiles"
+          oscal_model: "profile"
+```
+
+## Inputs and Outputs
+
+Checkout [`action.yml`](./action.yml) for a full list of supported inputs and outputs.
 
+### Additional information on workflow inputs
 
-### `/help`
-Displays help information for trestle-bot.
+- `markdown_path`: This is the location for Markdown generated by the `trestle author <model>-generate` commands
+- `ssp_index_path`: This is a text file that stores the component definition information by name in trestle with the ssp name. Example below
+
+```json
+ "ssp1": {
+            "profile": "profile1",
+            "component definitions": [
+                "comp1",
+                "comp2"
+            ]
+        },
+```
+
 
 ## Contributing
 
@@ -34,9 +61,4 @@ make test
 ### Run with poetry
 ```
 poetry run trestle-bot
-```
-
-## Additional information on workflow inputs
-
-- markdown_path: This is the location for Markdown generated by the `trestle author <model>-generate` commands
-- ssp_index_path: This is a text file that stores the component definition information by name in trestle with the ssp name. Each line should look like ssp:mycomp
+```

TROUBLESHOOTING.md

@@ -0,0 +1,27 @@
+# Troubleshooting
+
+
+## Action does not commit changes back to the correct branch
+
+Verify the trigger you are using. The default branch is set to `github.ref_name`. If triggered on a pull request, you may notice this set to `pr-number/merge`. Set the branch field to `github.heaf_ref` which is set during pull request triggered workflows.
+
+## Action does not have permission to commit
+
+If your workflow requires that this action make changes to your branch, ensure the the token being used has the correct permissions and the token is being set. Some examples of how to set the GitHub token are:
+
+```yaml
+- uses: actions/checkout@v3
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+```yaml
+- uses: RedHatProductSecurity/trestle-bot@main
+  with:
+    markdown_path: "markdown/profiles"
+    assemble_model: "profile"
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+> Note: Using the GitHub token provided with GitHub Action to commit to a branch will [NOT trigger additional workflows](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow).