Skip to content

Commit 05cfce1

Browse files
gvautergvauter
authored
docs: initialize mkdocs config and workflow for github pages (#315)
* docs: initialize mkdocs site with placeholder content * ci: add workflow to publish mkdocs content to github pages * fix: pin actions using commit hashes not version tags * fix: resolve lint issues in yaml Signed-off-by: George Vauter <gvauter@redhat.com> --------- Signed-off-by: George Vauter <gvauter@redhat.com>
1 parent ee86f5c commit 05cfce1

File tree

5 files changed

+494
-1
lines changed

5 files changed

+494
-1
lines changed

‎.github/workflows/mkdocs.yml

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: publish-docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
paths:
7+
- 'mkdocs.yml'
8+
- 'docs/**'
9+
10+
permissions:
11+
contents: write
12+
13+
jobs:
14+
gh-deploy:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pin@v4
18+
- uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # pin@v5
19+
with:
20+
python-version: '3.11'
21+
- uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # pin@v4
22+
with:
23+
key: ${{ github.ref }}
24+
path: .cache
25+
- run: pip install mkdocs-material
26+
- run: mkdocs gh-deploy --force

‎docs/index.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# trestle-bot
2+
3+
[![Pre commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
4+
[![License](https://img.shields.io/badge/license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)
5+
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=rh-psce_trestle-bot&metric=coverage)](https://sonarcloud.io/summary/new_code?id=rh-psce_trestle-bot)
6+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=rh-psce_trestle-bot&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=rh-psce_trestle-bot)
7+
8+
9+
10+
trestle-bot assists users in leveraging [Compliance-Trestle](https://github.com/oscal-compass/compliance-trestle) in CI/CD workflows for [OSCAL](https://github.com/usnistgov/OSCAL) formatted compliance content management.
11+
12+
> WARNING: This project is currently under initial development. APIs may be changed incompatibly from one commit to another.
13+
14+
## Getting Started
15+
16+
### Available Commands
17+
18+
The `autosync` command will sync trestle-generated Markdown files to OSCAL JSON files in a trestle workspace. All content under the provided markdown directory when the action is run will be transformed. This action supports all top-level models [supported by compliance-trestle for authoring](https://oscal-compass.github.io/compliance-trestle/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring/).
19+
20+
The `rules-transform` command can be used when managing [OSCAL Component Definitions](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/component-definition/json-outline/) in a trestle workspace. The action will transform rules defined in the rules YAML view to an OSCAL Component Definition JSON file.
21+
22+
The `create-cd` command can be used to create a new [OSCAL Component Definition](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/component-definition/json-outline/) in a trestle workspace. The action will create a new Component Definition JSON file and corresponding directories that contain rules YAML files and trestle-generated Markdown files. This action prepares the workspace for use with the `rules-transform` and `autosync` actions.
23+
24+
The `sync-upstreams` command can be used to sync and validate upstream OSCAL content stored in a git repository to a local trestle workspace. Which content is synced is determined by the `include_model_names` and `exclude_model_names` inputs.
25+
26+
The `create-ssp` command can be used to create a new [OSCAL System Security Plans](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/system-security-plan/json-outline/) (SSP) in a trestle workspace. The action will create a new SSP JSON file and corresponding directories that contain trestle-generated Markdown files. This action prepares the workspace for use with the `autosync` action by creating or updating the `ssp-index.json` file. The `ssp-index.json` file is used to track the relationships between the SSP and the other OSCAL content in the workspace for the `autosync` action.
27+
28+
Below is a table of the available commands and their current availability as a GitHub Action:
29+
30+
| Command | Available as a GitHub Action |
31+
|--------------------|------------------------------|
32+
| `autosync` | &#10003; |
33+
| `rules-transform` | &#10003; |
34+
| `create-cd` | &#10003; |
35+
| `sync-upstreams` | &#10003; |
36+
| `create-ssp` | |
37+
38+
For detailed documentation on how to use each action, see the README.md in each folder under [actions](./actions/).
39+
40+
### Supported Git Providers
41+
42+
> Note: Only applicable if using `trestle-bot` to create pull requests. Automatically detecting the git
43+
provider information is supported for GitHub Actions (GitHub) and GitLab CI (GitLab).
44+
45+
- GitHub
46+
- GitLab
47+
48+
### Run as a Container
49+
50+
> Note: When running the commands in a container, all are prefixed with `trestlebot` (e.g. `trestlebot-autosync`). The default entrypoint for the container is the autosync command.
51+
52+
Build and run the container locally:
53+
54+
```bash
55+
podman build -f Dockerfile -t trestle-bot .
56+
podman run -v $(pwd):/data -w /data trestle-bot
57+
```
58+
59+
Container images are available in `quay.io`:
60+
61+
```bash
62+
podman run -v $(pwd):/data -w /data quay.io/continuouscompliance/trestle-bot:<tag>
63+
```
64+
65+
## Contributing
66+
67+
For information about contributing to trestle-bot, see the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
68+
69+
## License
70+
71+
This project is licensed under the Apache 2.0 License - see the [LICENSE.md](LICENSE) file for details.
72+
73+
## Troubleshooting
74+
75+
See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for troubleshooting tips.

‎mkdocs.yml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
site_name: trestle-bot
2+
3+
theme:
4+
name: material
5+
language: en
6+
features:
7+
- content.code.annotation
8+
- content.code.copy
9+
- content.tabs.link
10+
- navigation.sections
11+
- navigation.tabs
12+
- navigation.top
13+
- search.highlight
14+
- search.suggest
15+
- toc.integrate
16+
palette:
17+
- scheme: default
18+
toggle:
19+
icon: material/toggle-switch-off-outline
20+
name: Switch to dark mode
21+
- scheme: slate
22+
toggle:
23+
icon: material/toggle-switch
24+
name: Switch to light mode
25+
26+
markdown_extensions:
27+
- toc:
28+
toc_depth: 2
29+
- pymdownx.superfences:
30+
custom_fences:
31+
- name: mermaid
32+
class: mermaid
33+
format: !!python/name:pymdownx.superfences.fence_code_format
34+
35+
copyright: |
36+
&copy; Copyright 2023 Red Hat, Inc.</a>

0 commit comments

Comments
 (0)