Skip to content

docs: User Guide, restructure, add versioning #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cassidyjames merged 7 commits into from
Jun 16, 2026
Merged

docs: User Guide, restructure, add versioning #353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
33d1049
docs: restructure
cassidyjames Jun 15, 2026
a3e756b
docs: reorganize a bit; copy pass
cassidyjames Jun 15, 2026
844751d
docs: Move book.toml under docs folder
cassidyjames Jun 15, 2026
c43baa5
docs: Build versioned docs
cassidyjames Jun 15, 2026
e01f95e
docs: Correct workflow to refer to Osprey, not Coop
cassidyjames Jun 15, 2026
4a9e978
ci(mdbook): fix zizmor findings — env vars for shell interpolation, d…
cassidyjames Jun 16, 2026
c393929
Merge branch 'main' into cassidyjames/docs
cassidyjames Jun 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 98 additions & 35 deletions .github/workflows/mdbook.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,123 @@
name: Deploy mdBook site to Pages
# docs in `main` get built into `/latest`, docs from tags get built into a subdirectory
# matching the tag name (e.g. `/0.1`). Automatically runs when updating the docs, editing
# this workflow, or pushing a new tag.
#
# Does not handle directly publishing to GitHub Pages; just updates the `gh-pages` branch to
# let GitHub build and deploy from that branch.

name: Update docs with mdbook

on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
branches: ['main']
paths:
- 'docs/**'
- '.github/workflows/mdbook.yml'
tags:
- '[0-9]*'

# Allows you to run this workflow manually from the Actions tab
# Allows you to run this workflow manually from the Actions tab.
# To backfill an old version, pass the tag as the `ref` input so the new
# workflow file runs from main but checks out docs from the specified tag.
workflow_dispatch:
inputs:
ref:
description: 'Tag to build and deploy docs from (e.g. 0.1); leave empty for latest main'
required: false
type: string

# Default to read-only; the deploy job grants itself the extra
# permissions it needs to publish to GitHub Pages.
# Write access needed to push to the gh-pages branch
permissions:
contents: read
contents: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
group: 'mdbook'
cancel-in-progress: false

jobs:
# Build job
build:
runs-on: ubuntu-latest
if: ${{ github.repository == 'roostorg/osprey' }}
env:
MDBOOK_VERSION: 0.5.2
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
# inputs.ref is only set for manual backfills; push-to-main and tag-push events
# default to the triggering ref automatically
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
with:
persist-credentials: false
ref: ${{ inputs.ref }}
Comment thread
coderabbitai[bot] marked this conversation as resolved.

- name: Determine deployment path
id: deploy-path
env:
INPUT_REF: ${{ inputs.ref }}
run: |
# For manual backfill, use the input ref; otherwise derive from the triggering ref
DEPLOY_REF="${INPUT_REF}"
if [[ -z "$DEPLOY_REF" ]]; then
Comment thread
coderabbitai[bot] marked this conversation as resolved.
if [[ "${{ github.event_name }}" == "workflow_dispatch" && "$GITHUB_REF_NAME" != "main" ]]; then
echo "Dispatching from a non-main branch requires a ref input (e.g. a tag name)" >&2
exit 1
fi
DEPLOY_REF="$GITHUB_REF_NAME"
fi
if [[ "$GITHUB_REF_TYPE" == "tag" || "$DEPLOY_REF" =~ ^[0-9] ]]; then
if [[ "$DEPLOY_REF" =~ [^A-Za-z0-9._-] ]]; then
echo "Refusing unsafe deploy ref: $DEPLOY_REF" >&2
exit 1
fi
echo "path=$DEPLOY_REF" >> "$GITHUB_OUTPUT"
else
echo "path=latest" >> "$GITHUB_OUTPUT"
fi

- name: Install mdBook
run: |
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
rustup update
cargo install --version ${MDBOOK_VERSION} mdbook
- name: Setup Pages
id: pages
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
ARCH="x86_64-unknown-linux-gnu"
ARCHIVE="mdbook-v${MDBOOK_VERSION}-${ARCH}.tar.gz"
URL="https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/${ARCHIVE}"
mkdir -p mdbook-bin
curl -sSL -o mdbook.tar.gz "$URL"
tar -xzf mdbook.tar.gz -C mdbook-bin
rm mdbook.tar.gz

- name: Build with mdBook
run: mdbook build
- name: Upload artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: ./book

# Deployment job
deploy:
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
run: ${{ github.workspace }}/mdbook-bin/mdbook build docs

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
env:
GITHUB_TOKEN: ${{ github.token }}
DEPLOY_PATH: ${{ steps.deploy-path.outputs.path }}
run: |
# Clone the gh-pages branch, or initialize it if this is the first deployment
if git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1; then
git clone --depth=1 --single-branch --branch gh-pages \
"https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
_gh-pages
else
mkdir _gh-pages
git -C _gh-pages init
git -C _gh-pages checkout --orphan gh-pages
git -C _gh-pages remote add origin \
"https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
fi

touch _gh-pages/.nojekyll

# Deploy the versioned docs
rm -rf "_gh-pages/${DEPLOY_PATH}"
cp -r docs/book "_gh-pages/${DEPLOY_PATH}"

# Regenerate the root version index
(cd _gh-pages && tree -d -L 1 -H . -T "Osprey Documentation" -o index.html --noreport)
Comment thread
cassidyjames marked this conversation as resolved.

# Commit and push
git -C _gh-pages config user.name "github-actions[bot]"
git -C _gh-pages config user.email "github-actions[bot]@users.noreply.github.com"
git -C _gh-pages add --all
git -C _gh-pages diff --staged --quiet || \
git -C _gh-pages commit --message "Deploy docs: ${DEPLOY_PATH}"
git -C _gh-pages push origin gh-pages
Comment on lines +8 to +123

@coderabbitai coderabbitai Bot Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Require explicit human approval before merging this workflow change.

This file is a restricted release/deploy workflow, so these changes need an explicit human approval gate before merge.

As per coding guidelines, AGENTS.md > "Human-approval-required actions" marks release/deploy workflows (including .github/workflows/mdbook.yml) as restricted and requiring explicit human approval.

🧰 Tools
🪛 zizmor (1.25.2)

[warning] 48-50: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[error] 56-56: code injection via template expansion (template-injection): may expand into attacker-controllable code

(template-injection)

[info] 99-99: code injection via template expansion (template-injection): may expand into attacker-controllable code

(template-injection)

[error] 76-76: runtime artifacts potentially vulnerable to a cache poisoning attack (cache-poisoning): enables caching by default

(cache-poisoning)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/mdbook.yml around lines 8 - 129, This is a restricted
release/deploy workflow file (mdbook.yml) that requires explicit human approval
before merging according to the coding guidelines in AGENTS.md. Do not attempt
to merge this pull request without obtaining explicit human approval from a
project maintainer, as this workflow file is marked as restricted and
deployment-related, which means it must go through a mandatory approval gate
before it can be merged.

Source: Coding guidelines

46 changes: 26 additions & 20 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,37 @@
# Osprey Documentation
# Welcome

Welcome to the Osprey documentation! This folder contains important information about contributing to and working with this project.
Welcome to the Osprey documentation! Visit [Osprey on GitHub](https://github.com/roostorg/osprey#readme) for source code and project information. These docs are split into a few guides, depending on who you are and what you're looking for:

## Getting Started
- [User Guide](user/): learn about Osprey, its functionality, and the user interface
- [Development Guide](development/): get Osprey running and learn how to navigate the code

New to the project? We recommend reading the documentation in this order:
See additional topics for reference:

1. **[Code of Conduct](https://github.com/roostorg/.github/blob/main/CODE_OF_CONDUCT.md)** - Understand our community standards
2. **[Contributing Guidelines](https://github.com/roostorg/.github/blob/main/CONTRIBUTING.md)** - Learn how to contribute
3. **[Development Guide](DEVELOPMENT.md)** - Set up your development environment and get started using Osprey
4. **[Osprey UI](UI.md)** - Understand how to use and navigate the UI
- [Writing Rules](rules.md)
- [User Research & Personas](research-personas.md)

## Reporting a Bug or Issue
## Contributing

Found a bug or have a feature request? We'd love to hear from you! When opening an issue, please use our templates:
Osprey is an open source project from [ROOST](https://roost.tools) and the community. We welcome contributions and benefit from diverse perspectives and expertise in building safer online spaces.

* [Bug Report](https://github.com/roostorg/osprey/issues/new?template=bug_report.md)
* [Feature Request](https://github.com/roostorg/osprey/issues/new?template=feature_request.md)
* [Submit an Egg (new tool idea) to ROOST!](https://github.com/roostorg/osprey/issues/new?template=documentation.md)
If you're new to the project, we recommend you:

## Need Help?
- Read the [Code of Conduct](https://github.com/roostorg/.github/blob/main/CODE_OF_CONDUCT.md) to understand our community standards
- Review the [Contributing Guidelines](https://github.com/roostorg/.github/blob/main/CONTRIBUTING.md) for all ROOST projects
- Check out the [project board](https://github.com/orgs/roostorg/projects/13) for open issues, milestones, and prioritization

If you can't find what you're looking for in these documents, please:
- Check the project's main README.md
- Open an issue with your question
- Reach out to the maintainers
Writing code is not the only way to help the project. Reviewing pull requests, answering questions, providing feedback, organizing and teaching tutorials, and improving the documentation are all priceless contributions.

---
### Report an issue

Thank you for your interest in contributing to our project!
Found a bug or have a feature request? We'd love to hear from you!

- Search [existing issues](https://github.com/roostorg/osprey/issues) to see if it's already been filed
- Create a [new issue](https://github.com/roostorg/osprey/issues/new) if it's unique

## Get help

If you need help with Osprey or want to get in touch, you are always welcome to:

- [Open a discussion](https://github.com/roostorg/osprey/discussions) with the community
- [Join our Discord server](https://discord.gg/2brrzbqgJF) to chat with contributors, adopters, and other community members
23 changes: 19 additions & 4 deletions docs/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,31 @@
# Summary

[Getting Started](README.md)
[Welcome](README.md)

- [Development](DEVELOPMENT.md)
---

- [User Guide](user/README.md)
- [Investigate](user/investigate/README.md)
- [Labels](user/investigate/labels.md)
- [Query Syntax](user/investigate/query-syntax.md)
- [Manage](user/manage.md)
- [Operate](user/operate.md)

---

- [Development Guide](development/README.md)
- [Workflow](development/workflow.md)
- [Tools Overview](development/tools.md)
- [Troubleshooting](development/troubleshooting.md)
- [IDE Setup](development/ide.md)
- [Release Process](development/releases.md)
- [User Interface](UI.md)

---

# Concepts & More

- [Writing Rules](rules.md)
- [User Research & Personas](user_personas.md)
- [User Research & Personas](research-personas.md)

---

Expand Down
Loading
Loading