From b9a8caf57222821f66cc3738ba0f733c7c9d1b35 Mon Sep 17 00:00:00 2001 From: Ben Roose Date: Thu, 17 Oct 2024 07:16:14 -0500 Subject: [PATCH] docs: updates after user testing to github.md (#362) * Update github tutorial after user testing Edited GitHub Tutorial for required command changes, clarity, and formalizing of language. * fix: renumbering section in github.md * fix: minor wording changes to github.md Minor documentation changes for clarity. --------- Co-authored-by: George Vauter --- docs/tutorials/github.md | 68 +++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/docs/tutorials/github.md b/docs/tutorials/github.md index 1eebc14..5c08868 100644 --- a/docs/tutorials/github.md +++ b/docs/tutorials/github.md @@ -1,16 +1,16 @@ # GitHub Tutorial -This tutorial provides an introduction to using `trestlebot` with GitHub. We will be using a single GitHub repository for our trestle authoring workspace and executing the `trestlebot` commands as GitHub actions. Note, each repo is intended to support authoring a single OSCAL model type (SSP, component definition, etc.). If authoring more than one, then a dedeicated repository should be used for each model. +This tutorial provides an introduction to using `trestlebot` with GitHub. We will be using a single GitHub repository for our trestle authoring workspace and executing the `trestlebot` commands as GitHub actions. Note, each repo is intended to support authoring a single OSCAL model type (SSP, component definition, etc.). If authoring more than one OSCAL model type, then a dedicated repository should be used for each model. ### 1. Prerequisites -Before moving on, please ensure you have completed the following: +Before moving on, please ensure the following is completed: 1. Create a new (or use an existing) empty GitHub repository -2. Clone the repo to your local workstation +2. Clone the repo to a local workstation 3. Install trestlebot - * Option 1: Clone the [trestle-bot](https://github.com/RedHatProductSecurity/trestle-bot/tree/main) repo to your local workstation and run `poetry install` + * Option 1: Clone the [trestle-bot](https://github.com/RedHatProductSecurity/trestle-bot/tree/main) repo to a local workstation and run `poetry install` * Option 2: Use the [trestlebot container image](https://github.com/RedHatProductSecurity/trestle-bot?tab=readme-ov-file#run-as-a-container) @@ -18,7 +18,7 @@ Before moving on, please ensure you have completed the following: The `trestlebot` commands will be run inside of GitHub actions. These commands often perform `write` level operations against the repo contents. The GitHub workflows generated in this tutorial make use of [automatic token authentication.](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication) To ensure this is configured correct the following repo settings need to be in place. -*Note: If you choose an alternative method to provide repo access such as personal access tokens or GitHub apps you can skip these steps.* +*Note: If an alternative method is choosen to provide repo access, such as personal access tokens or GitHub apps, the following steps can be skipped.* 1. Click the `Settings` tab for your GitHub repo 2. Select `Actions` -> `General` from the left-hand menu @@ -26,22 +26,33 @@ The `trestlebot` commands will be run inside of GitHub actions. These commands 4. Ensure `Read repository contents and packages permissions` is selected 5. Ensure `Allow GitHub Actions to create and approve pull requests` is checked + ### 3. Initialize trestlebot Workspace -We will now use the `trestlebot init` command to initialize our emtpy GitHub repository. Unlike the other trestlebot commands, this command is run on your local workstation. The trestlebot commands can be installed by cloning the [trestle-bot](https://github.com/RedHatProductSecurity/trestle-bot/tree/main) repo and running `poetry install`. Alternatively these commands can be run using the [trestlebot container image](https://github.com/RedHatProductSecurity/trestle-bot?tab=readme-ov-file#run-as-a-container). For this tutorial we will be authoring a component-definition. +The `trestlebot init` command will initialize the empty GitHub repository. Unlike other trestlebot commands, this command is run on the local workstation. The trestlebot commands can be installed by cloning the [trestle-bot](https://github.com/RedHatProductSecurity/trestle-bot/tree/main) repo and running `poetry install`. Alternatively these commands can be run using the [trestlebot container image](https://github.com/RedHatProductSecurity/trestle-bot?tab=readme-ov-file#run-as-a-container). + +For this tutorial example, we will be authoring a component-definition. + +1a. Running trestlebot init using a locally installed trestlebot: ``` trestlebot-init --oscal-model compdef --working-dir ``` -Using container image: +1b. Running trestlebot init using a trestle-bot container image: + + * *Note: latest image version tag can be found in the [continuouscompliance repo on quay.io](https://quay.io/repository/continuouscompliance/trestle-bot?tab=tags).* ``` -podman run -v :/data:rw trestle-bot:latest --oscal-model compdef --working-dir /data +podman run -v :/data:rw trestle-bot: --oscal-model compdef --working-dir /data ``` -You should now see the following directories in your repo. + * If the local workstation is in SELinux enforcing mode and a permissions error occurs, then the following command should be used instead: +``` +podman run -v :/data:Z trestle-bot: --oscal-model compdef --working-dir /data +``` + * Once the initiatization runs successfully, the following directories will be created within the local copy of the repository. ```bash . @@ -54,43 +65,58 @@ You should now see the following directories in your repo. └── .trestlebot ``` -You can now add any catalog or profile content needed for you authoring process. For this example, we will add the NIST SP 800-53 Rev. 5 catalog to our `/catalogs` directory. +2. Any catalog or profile content needed for the authoring process can now be added. + + * For this example, we will add the NIST SP 800-53 Rev. 5 catalog to our `/catalogs` directory. ``` mkdir catalogs/nist_rev5_800_53 wget https://raw.githubusercontent.com/usnistgov/oscal-content/release-v1.0.5-update/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json -O catalogs/nist_rev5_800_53/catalog.json ``` -Now we will add the NIST SP 800-53 Rev. 5 High Baseline profile to our `profiles/` directory. + * We will also add the NIST SP 800-53 Rev. 5 High Baseline profile to our `profiles/` directory. ``` mkdir profiles/nist_rev5_800_53 wget https://raw.githubusercontent.com/usnistgov/oscal-content/release-v1.0.5-update/nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_HIGH-baseline_profile.json -O profiles/nist_rev5_800_53/profile.json ``` -Our `profile.json` file contains a reference to our `catalog.json` file. By default, this path is not resolvable by compliance-trestle, so we need to run the following command to update the `href` value in the JSON. +3. Our `profile.json` file contains a reference to our `catalog.json` file. By default, this path is not resolvable by compliance-trestle, so we need to run the following command to update the `href` value in the JSON. ``` sed -i 's/NIST_SP-800-53_rev5_catalog.json/trestle:\/\/catalogs\/nist_rev5_800_53\/catalog.json/g' profiles/nist_rev5_800_53/profile.json ``` -Finally you can copy ready-made CI/CD workflows from the `TEMPLATES` directory into your workspace. These are the trestlebot actions that will run as we make changes to the repo contents. +4. Ready-made CI/CD workflows can be copied from the `TEMPLATES` directory within the upstream `trestle-bot` repository into the local trestle workspace. These are the trestlebot actions that will run as changes are made to the repo contents. + + * If trestlebot init was run earlier using a trestle-bot container image, then the upstream trestle-bot repository will first need to be cloned locally into a separate directory. +``` +cd .. +git clone https://github.com/RedHatProductSecurity/trestle-bot.git +cd ../ +``` -**For example Component Definition authoring in GitHub Actions** + * Copy the required template workflows from the separate `trestle-bot` repository into the new workspace repository. ``` mkdir -p .github/workflows -cp TEMPLATES/github/trestlebot-create-component-definition.yml .github/workflows -cp TEMPLATES/github/trestlebot-rules-transform.yml .github/workflows +cp ../trestle-bot/TEMPLATES/github/trestlebot-create-component-definition.yml .github/workflows +cp ../trestle-bot/TEMPLATES/github/trestlebot-rules-transform.yml .github/workflows ``` -Now that we have the initial content needed to begin authoring, go ahead and commit and push to the remote GitHub repo. +5. Trestle-bot initial content is now created locally within the new trestle authoring workspace. This content can now be pushed to the remote GitHub repository. +``` +git add . +git commit -m "added example NIST SP 800-53 profile and component definition authoring workflow" +git push +``` + *Note: if this is the first git push to the remote GitHub repository, then use `git push -u origin main` rather than `git push`.* ### 4. Create a New Component Definition -Now it's time to run our first trestlebot action! We will go ahead and create our first component definition. +Now it's time to run our first trestlebot action within GitHub! We will go ahead and create our first component definition. -1. Open to your GitHub repo in a web browser. +1. Open the new remote GitHub repository in a web browser. 2. Click to the `Actions` tab from the top menu. 3. Click the `Trestle-bot create component definition` action from the left-hand menu. 4. Click `Run Workflow` which will open up a dialog box. @@ -104,6 +130,6 @@ Now it's time to run our first trestlebot action! We will go ahead and create o 6. Click `Run Workflow` -Once the workflow has completed you should have a new Pull Request containing the files trestlebot generated for the component definition. After reviewing the files you can go ahead and merge the PR! +Once the workflow job has completed, there will be a new Pull Request containing the files trestlebot generated for the component definition. After reviewing the committed changes, the Pull Request can then be merged into the main branch! -Congrats, you have successfully created a new trestlebot workspace and now have an authoring environment! \ No newline at end of file +**Congratulations! We have successfully created a new trestlebot workspace and have an authoring environment!**