-
Notifications
You must be signed in to change notification settings - Fork 3
Add MkDocs docs site #125
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.
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
Merged
Add MkDocs docs site #125
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
0ae480f
Add MkDocs docs site
github-actions[bot] 49d3bcd
Merge branch 'main' into main-3aa341b1eb8b467d
strawgate d08c9d0
Merge branch 'main' into main-3aa341b1eb8b467d
strawgate 098ee21
Move agent output from github/ to .github/
strawgate 0aea2db
Refactor docs into site
Copilot dc52e9f
Merge branch 'main' into main-3aa341b1eb8b467d
strawgate File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| name: Docs | ||
|
|
||
| on: | ||
| push: | ||
| branches: [main] | ||
| paths: | ||
| - docs/** | ||
| - mkdocs.yml | ||
| - docs/requirements.txt | ||
| workflow_dispatch: | ||
|
|
||
| permissions: | ||
| contents: read | ||
| pages: write | ||
| id-token: write | ||
|
|
||
| concurrency: | ||
| group: pages | ||
| cancel-in-progress: false | ||
|
|
||
| jobs: | ||
| build: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.11" | ||
| - name: Install docs dependencies | ||
| run: python -m pip install -r docs/requirements.txt | ||
| - name: Build site | ||
| run: python -m mkdocs build --strict | ||
| - name: Upload Pages artifact | ||
| uses: actions/upload-pages-artifact@v3 | ||
| with: | ||
| path: site | ||
| deploy: | ||
| needs: build | ||
| runs-on: ubuntu-latest | ||
| environment: | ||
| name: github-pages | ||
| url: ${{ steps.deployment.outputs.page_url }} | ||
| steps: | ||
| - id: deployment | ||
| uses: actions/deploy-pages@v4 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -22,3 +22,4 @@ env/ | |
| # OS | ||
| .DS_Store | ||
| Thumbs.db | ||
| site/ | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,83 +1,8 @@ | ||
| # Claude Workflows (Composite Actions) | ||
|
|
||
| Composite GitHub Actions wrapping [Claude Code](https://github.com/anthropics/claude-code-action). Consumed via `uses:` in standard GitHub Actions YAML. | ||
| This directory contains the composite actions for Claude Code. | ||
|
|
||
| > **Note:** This directory was renamed from `workflows/` to `claude-workflows/`. A symlink ensures backwards compatibility — existing `uses: elastic/ai-github-actions/claude-workflows/...@v0` references continue to work. | ||
| Full documentation and configuration details live in the docs site: | ||
| https://elastic.github.io/ai-github-actions/workflows/claude-workflows/ | ||
|
|
||
| ## Security | ||
|
|
||
| > **Important:** RWX and RWXP agents can run arbitrary commands, including git commit and git push. To prevent pushes, set `contents: read` (or `contents: none`) in your workflow's `permissions:`. Prompt constraints alone are not sufficient. | ||
|
|
||
| > Workflows triggered by user actions should restrict who can trigger Claude. The example workflows include an `author_association` check allowing only `OWNER`, `MEMBER`, and `COLLABORATOR`. See [SECURITY.md](../SECURITY.md) for detailed guidance. | ||
|
|
||
| ## Available Actions | ||
|
|
||
| ### Review Agents | ||
|
|
||
| | Action | Description | R | W | X | Git | Push | | ||
| |--------|-------------|---|---|---|-----|------| | ||
| | [Issue Triage (RO)](issue-triage/ro/README.md) | Triage new issues (read-only) | ✅ | ❌ | ❌ | ✅ | ❌ | | ||
| | [Issue Triage (RWX)](issue-triage/rwx/README.md) | Triage new issues (can execute tests) | ✅ | ✅ | ✅ | ✅ | ❌** | | ||
| | [PR Review (RO)](pr-review/ro/README.md) | Review PRs (suggestions only) | ✅ | ❌ | ❌ | ✅ | ❌ | | ||
| | [PR Review (RWX)](pr-review/rwx/README.md) | Review PRs (with test execution) | ✅ | ✅ | ✅ | ✅ | ❌** | | ||
|
|
||
| ### Assistant Agents | ||
|
|
||
| | Action | Description | R | W | X | Git | Push | | ||
| |--------|-------------|---|---|---|-----|------| | ||
| | [Mention in Issue (RWX)](mention-in-issue/rwx/README.md) | @claude in issues (no push) | ✅ | ✅ | ✅ | ✅ | ❌** | | ||
| | [Mention in Issue (RWXP)](mention-in-issue/rwxp/README.md) | @claude in issues (full access) | ✅ | ✅ | ✅ | ✅ | ✅ | | ||
| | [Mention in PR (RWX)](mention-in-pr/rwx/README.md) | @claude in PRs (no push) | ✅ | ✅ | ✅ | ✅ | ❌** | | ||
| | [Mention in PR (RWXP)](mention-in-pr/rwxp/README.md) | @claude in PRs (full access) | ✅ | ✅ | ✅ | ✅ | ✅ | | ||
| | [Build Failure Buildkite (RWX)](build-failure-buildkite/rwx/README.md) | Analyze Buildkite CI failures | ✅ | ✅ | ⚙️ | ✅ | ❌ | | ||
| | [Build Failure GitHub Actions (RWX)](build-failure-github-actions/rwx/README.md) | Analyze GitHub Actions failures | ✅ | ✅ | ⚙️ | ✅ | ❌ | | ||
|
|
||
| ### Overview Agents | ||
|
|
||
| | Action | Description | R | W | X | Git | Push | | ||
| |--------|-------------|---|---|---|-----|------| | ||
| | [Generate Report (RO)](generate-report/ro/README.md) | Scheduled report generation | ✅ | ❌ | ⚙️ | ✅ | ❌ | | ||
| | [Project Manager (RO)](project-manager/ro/README.md) | Periodic project state reviews | ✅ | ❌ | ❌ | ✅ | ❌ | | ||
|
|
||
| > ✅ = default, ⚙️ = via config, ❌ = unavailable, ❌** = prompt-discouraged (enforce with `contents: read`) | ||
|
|
||
| ## Usage | ||
|
|
||
| ```yaml | ||
| - uses: elastic/ai-github-actions/claude-workflows/pr-review/rwx@v0 | ||
| with: | ||
| prompt: "Review this PR" | ||
| claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | ||
| github-token: ${{ github.token }} | ||
| ``` | ||
|
|
||
| ### Base Action | ||
|
|
||
| The [base action](base/action.yml) provides full configurability: | ||
|
|
||
| | Input | Description | Required | Default | | ||
| |-------|-------------|----------|---------| | ||
| | `prompt` | Prompt to pass to Claude | Yes | — | | ||
| | `claude-oauth-token` | Claude OAuth token | Yes | — | | ||
| | `github-token` | GitHub token for Claude | Yes | — | | ||
| | `allowed-tools` | Comma-separated allowed tools | No | `""` | | ||
| | `model` | Model to use | No | `claude-opus-4-5-20251101` | | ||
| | `allowed-bots` | Allowed bot usernames, or `*` for all | No | `""` | | ||
| | `mcp-servers` | MCP server configuration JSON | No | See below | | ||
|
|
||
| ### MCP Servers | ||
|
|
||
| All workflow actions include default MCP servers (the base action does not): | ||
|
|
||
| - **agents-md-generator** — Generates repository summaries from AGENTS.md. Called automatically at startup. | ||
| - **public-code-search** — Search public GitHub repos for usage patterns and reference implementations. | ||
|
|
||
| Override with your own: | ||
|
|
||
| ```yaml | ||
| - uses: elastic/ai-github-actions/claude-workflows/base@v0 | ||
| with: | ||
| prompt: "Your prompt" | ||
| claude-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} | ||
| mcp-servers: '{"mcpServers":{"my-server":{"type":"http","url":"https://my-server.example.com/mcp"}}}' | ||
| ``` | ||
| Each action directory includes an `example.yml` and README for specific usage. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Developing | ||
|
|
||
| ## Repository structure | ||
|
|
||
| | Directory | What | Docs | | ||
| | --- | --- | --- | | ||
| | `.github/workflows/` | Workflow `gh-aw-*.md` sources, compiled `gh-aw-*.lock.yml` files, trigger copies, fragments | https://github.com/elastic/ai-github-actions/blob/main/gh-agent-workflows/DEVELOPING.md | | ||
| | `gh-agent-workflows/` | Per-workflow READMEs and `example.yml` triggers (examples + dogfood), consumer docs | https://github.com/elastic/ai-github-actions/blob/main/gh-agent-workflows/DEVELOPING.md | | ||
| | `claude-workflows/` | Composite actions wrapping Claude Code | https://github.com/elastic/ai-github-actions/blob/main/claude-workflows/DEVELOPING.md | | ||
|
|
||
| Internal-only workflows (e.g., `gh-aw-upgrade-check.md`, `ci.yml`, `release.yml`) also live in `.github/workflows/`. | ||
|
|
||
| ## Quick start | ||
|
|
||
| ```bash | ||
| make setup # install actionlint, action-validator, gh CLI, gh-aw compiler | ||
| make compile # sync triggers + compile to lock files | ||
| make lint # run all linters | ||
| ``` | ||
|
|
||
| ## Releasing | ||
|
|
||
| See [Release process](release.md) and the full guide in https://github.com/elastic/ai-github-actions/blob/main/RELEASE.md. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # AI GitHub Actions | ||
|
|
||
| AI-powered GitHub workflows for Elastic repositories. | ||
|
|
||
| ## Choose an approach | ||
|
|
||
| | Feature | GitHub Agent Workflows | Claude Composite Actions | | ||
| | --- | --- | --- | | ||
| | Engine | Copilot (default) or Claude | Claude only | | ||
| | Install | Copy trigger YAML (recommended) or `gh aw add` + `gh aw compile` | Copy `example.yml` to `.github/workflows/` | | ||
| | Guardrails | Safe-outputs framework (structured API outputs) | Read-only/RWX/RWXP variants via permissions | | ||
| | Customization | `additional-instructions`, `setup-commands`, or full shim edit | Edit YAML directly, adjust composite action inputs | | ||
|
|
||
| GitHub Agent Workflows are recommended for new deployments; Claude Composite Actions remain supported for legacy deployments. | ||
|
|
||
| ## Workflows | ||
|
|
||
| - [GitHub Agent Workflows](workflows/gh-agent-workflows.md) | ||
| - [Claude Composite Actions](workflows/claude-workflows.md) | ||
|
|
||
| ## More | ||
|
|
||
| - [Developing](developing.md) | ||
| - [Security](security.md) | ||
| - [Release process](release.md) | ||
| - [Repository README](https://github.com/elastic/ai-github-actions/blob/main/README.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| # Release process | ||
|
|
||
| This repository uses semver tags with floating major tags. For the full release guide, see https://github.com/elastic/ai-github-actions/blob/main/RELEASE.md. | ||
|
|
||
| ## Summary | ||
|
|
||
| - Use `@v0` for the floating major tag, or `@v0.1.0` for an exact release. | ||
| - Run `make release VERSION=x.y.z` from `main` to create a new tag and trigger the release workflow. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| mkdocs>=1.6.0,<2.0 | ||
| mkdocs-material>=9.5.0 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Security considerations | ||
|
|
||
| This page summarizes key guidance. For the full policy and examples, see https://github.com/elastic/ai-github-actions/blob/main/SECURITY.md. | ||
|
|
||
| ## Key practices | ||
|
|
||
| - Restrict triggers with `author_association` checks for issue and comment events. | ||
| - Use minimum `permissions:` and prefer `contents: read` to prevent unintended pushes. | ||
| - Treat user-controlled text as untrusted and avoid interpolating it into shell commands. | ||
| - Review action pinning guidance and consider SHA pinning for production use. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[MEDIUM] Workflow location prevents execution
GitHub only loads workflows from
.github/workflows/. With this file undergithub/workflows/, the docs workflow will never run, so Pages won't be built; move it to.github/workflows/mkdocs.ymlbefore merge.