docs: updates documentation for pull request creation

Updates TROUBLESHOOTING.md with new solution information Moves contributing information to CONTRIBUTIyNG.md with testing information Signed-off-by: Jennifer Power <[email protected]>
RedHatProductSecurity · Jul 10, 2023 · 5fddbc3 · 5fddbc3
1 parent 3dcc280
commit 5fddbc3
Show file tree

Hide file tree

Showing 3 changed files with 75 additions and 23 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,70 @@
+## Contributing
+
+### Format and Styling
+
+```
+make format
+make lint
+```
+
+### Running tests
+```
+make test
+```
+
+### Run with poetry
+```
+poetry run trestle-bot
+```
+
+### Local testing
+
+For this guide, we will be using `podman` to test trestlebot in a running container.
+
+1. Build the image
+
+```bash
+podman build -f Dockerfile -t localhost:5000/trestlebot:latest
+```
+
+2. Create an environment variable files if testing with the entrypoint script.
+
+> The entrypoint script is where the logic for GitHub specific integrations should be. The environment variable files will contain variable set by GitHub Actions.
+
+Example file named `envfile`
+
+```
+cat envfile
+...
+
+GITHUB_OUTPUT=
+INPUT_SKIP_ITEMS=
+INPUT_CHECK_ONLY=true
+INPUT_SKIP_ASSEMBLE=false
+INPUT_SKIP_REGENERATE=false
+INPUT_REPOSITORY=.
+INPUT_BRANCH=test
+INPUT_MARKDOWN_PATH=markdown/profiles
+INPUT_OSCAL_MODEL=profile
+INPUT_SSP_INDEX_PATH=
+INPUT_COMMIT_MESSAGE=
+INPUT_COMMIT_USER_NAME=testuser
+[email protected]
+INPUT_FILE_PATTERN=*.md,*.json
+INPUT_COMMIT_AUTHOR_NAME=
+INPUT_COMMIT_AUTHOR_EMAIL=
+INPUT_TARGET_BRANCH=
+GITHUB_ACTIONS=true
+
+```
+3. Use `podman secret` to store sensitive information like API tokens
+
+```bash
+cat my-token.txt | podman secret create repo-secret -
+```
+
+4. Run the container
+
+```bash
+podman run --entrypoint /entrypoint.sh --secret repo-secret,type=env,target=GITHUB_TOKEN --env-file=envfile -v my-trestle-space:/data -w /data localhost:5000/trestlebot:latest
+```
diff --git a/README.md b/README.md
@@ -41,24 +41,4 @@ Checkout [`action.yml`](./action.yml) for a full list of supported inputs and ou
                 "comp2"
             ]
         },
-```
-
-
-## Contributing
-
-### Format and Styling
-
-```
-make format
-make lint
-```
-
-### Running tests
-```
-make test
-```
-
-### Run with poetry
-```
-poetry run trestle-bot
 ```
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
@@ -5,7 +5,7 @@
 
 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
+## Action does not have permission to commit/pull_request
 
 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:
 
@@ -15,13 +15,15 @@ If your workflow requires that this action make changes to your branch, ensure t
     token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+> You must use this option if you are setting the target branch for pull requests
 ```yaml
 - uses: RedHatProductSecurity/trestle-bot@main
   with:
     markdown_path: "markdown/profiles"
     assemble_model: "profile"
-  env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    github_token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+Also ensure that your token has `content: write` and `pull-requests: write` permissions.
+
 > 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).