Add MkDocs documentation with GitHub Pages deployment#52
Add MkDocs documentation with GitHub Pages deployment#52xinghaohuang91 wants to merge 7 commits into
Conversation
- Add MkDocs configuration with Material theme - Add documentation structure (getting-started, guides, examples, api) - Add GitHub Actions workflow for automatic deployment to gh-pages - Configure workflow to trigger on test-docs and main branches - Add .nojekyll file to site output for GitHub Pages compatibility Documentation will be published to: https://twilio.github.io/twilio-agent-connect-python/ Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
![semgrep-code-twilio[bot]](https://avatars.githubusercontent.com/u/109142?s=60&v=4){kind=small}
| touch site/.nojekyll | ||
|
|
||
| - name: Deploy to GitHub Pages | ||
| uses: peaceiris/actions-gh-pages@v4 |
There was a problem hiding this comment.
Semgrep identified an issue in your code:
GitHub Actions workflow uses version tag v4 instead of a pinned commit SHA, allowing the action to be swapped by an attacker who compromises the repository. Pinning to a full commit SHA ensures immutability and prevents malicious code injection.
More details about this
The GitHub Actions workflow uses peaceiris/actions-gh-pages pinned only to the v4 version tag instead of a specific commit SHA. Version tags can be moved or retagged by the maintainer, meaning the same tag could point to different code over time.
Exploit scenario:
- An attacker compromises the
peaceiris/actions-gh-pagesrepository (or gains write access to it). - They force-push a malicious commit and retag it as
v4, replacing the code that currently runs in your workflow. - The next time your workflow executes, the
uses: peaceiris/actions-gh-pages@v4line pulls the attacker's code instead. - The malicious action now runs with access to
secrets.GITHUB_TOKENandpublish_dir: ./site, allowing the attacker to steal your GitHub token, modify your site content, or compromise your repository and other actions.
By pinning to a full commit SHA (like uses: peaceiris/actions-gh-pages@a3523ae0e4cd1f5299b8aa5e37255467ec0de1ad), you lock to an immutable version that cannot be changed even if the repository is compromised.
To resolve this comment:
✨ Commit fix suggestion
| uses: peaceiris/actions-gh-pages@v4 | |
| uses: peaceiris/actions-gh-pages@d5007f704b97bcc11256c735197c9abb76aa19e6 # v4.0.0 |
View step-by-step instructions
- Find the specific commit SHA for the version of peaceiris/actions-gh-pages you want to use by checking the GitHub repository, for example at https://github.com/peaceiris/actions-gh-pages/releases or by running
$ git ls-remote https://github.com/peaceiris/actions-gh-pages.git v4. - Replace
uses: peaceiris/actions-gh-pages@v4withuses: peaceiris/actions-gh-pages@<commit-sha>, where<commit-sha>is the full 40-character commit hash.
For example:uses: peaceiris/actions-gh-pages@abcdef1234567890abcdef1234567890abcdef12 - Optionally, add a comment after the SHA noting the human-readable version, e.g.
# v4.0.0, to clarify which release you are pinning.
Pinning to a specific commit ensures that your workflow cannot be modified by upstream changes or supply chain attacks unless you explicitly update the SHA.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by third-party-action-not-pinned-to-commit-sha.
Need help with this issue? Consult our Semgrep Findings Documentation or ask in #help-appsec on Slack.
You can view more details about this finding in the Semgrep AppSec Platform.
| touch site/.nojekyll | ||
|
|
||
| - name: Deploy to GitHub Pages | ||
| uses: peaceiris/actions-gh-pages@v4 |
There was a problem hiding this comment.
Semgrep identified an issue in your code:
The peaceiris/actions-gh-pages@v4 step uses a mutable version tag that could be silently repointed to malicious code, compromising the GITHUB_TOKEN passed to it and enabling repository takeover.
More details about this
The GitHub Actions workflow step uses: peaceiris/actions-gh-pages@v4 references the action using a mutable version tag (v4) instead of a pinned commit SHA.
Exploit scenario:
- An attacker compromises the
peaceiris/actions-gh-pagesrepository on GitHub (or socially engineers the maintainer). - The attacker updates the
v4tag to point to a malicious commit containing code that exfiltrates${{ secrets.GITHUB_TOKEN }}(which is passed to this action). - Your workflow runs and automatically uses the updated malicious version because the tag is mutable.
- The attacker now has a valid
GITHUB_TOKENwithcontents: writepermissions and can push malicious code to your repository, modify your documentation site, or access other repositories you have access to.
This is especially dangerous here because the action receives github_token: ${{ secrets.GITHUB_TOKEN }}, giving the compromised action full write access to your repository. Similar attacks have already occurred in the wild (e.g., trivy-action and kics-github-action compromises).
To resolve this comment:
✨ Commit fix suggestion
| uses: peaceiris/actions-gh-pages@v4 | |
| uses: peaceiris/actions-gh-pages@13b7eb9eebd81f2444ea0ae2ebc6aa270d9f1a38 # v4.0.0 |
View step-by-step instructions
- Visit the peaceiris/actions-gh-pages GitHub repository and locate the specific release or commit SHA you want to use (see https://github.com/peaceiris/actions-gh-pages/tags).
- Copy the full 40-character commit SHA for the desired version (for example, the latest v4 release).
- Replace
uses: peaceiris/actions-gh-pages@v4withuses: peaceiris/actions-gh-pages@<commit-sha>, where<commit-sha>is the commit you copied. For example:uses: peaceiris/actions-gh-pages@13b7eb9eebd81f2444ea0ae2ebc6aa270d9f1a38 # v4.0.0. - Optionally, add a comment with the tag information for clarity, like
# v4.0.0, after the commit SHA.
Pinning to a commit SHA ensures your workflow always uses the trusted code, even if someone changes or repoints the tag or branch.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by github-actions-mutable-action-tag.
Need help with this issue? Consult our Semgrep Findings Documentation or ask in #help-appsec on Slack.
You can view more details about this finding in the Semgrep AppSec Platform.
| fetch-depth: 0 # Fetch all history for proper git info | ||
|
|
||
| - name: Set up Python | ||
| uses: actions/setup-python@v5 |
There was a problem hiding this comment.
Semgrep identified an issue in your code:
GitHub Actions step actions/setup-python@v5 uses a mutable version tag that could be silently redirected to malicious code by an attacker, enabling supply-chain attacks on your build pipeline.
More details about this
The GitHub Actions workflow uses actions/setup-python@v5, which references a mutable major version tag instead of a pinned commit SHA.
How an attacker could exploit this:
- An attacker compromises the GitHub Actions
setup-pythonrepository or the account that maintains it. - They force-push the
v5tag to point to a malicious commit containing backdoor code, perhaps a script that exfiltrates repository secrets likeGITHUB_TOKENor environment variables. - When your workflow runs, the runner automatically fetches the latest commit for the
v5tag without any warning or verification. - The malicious
setup-python@v5action runs in your workflow with full access to your repository's secrets and the ability to execute arbitrary commands. - The attacker can steal secrets, modify your codebase, or use your build environment to attack downstream dependencies.
This exact scenario happened with the trivy-action and kics-github-action compromises, where attackers gained control of version tags and silently injected malicious code into thousands of workflows.
To resolve this comment:
✨ Commit fix suggestion
| uses: actions/setup-python@v5 | |
| uses: actions/setup-python@f67e31fc8fd0c1e758ff2da11321c39dd442cafd # v5.0.0 |
View step-by-step instructions
- Replace the mutable version tag in
uses: actions/setup-python@v5with a specific 40-character commit SHA that corresponds to the version you want to use. For example, change it touses: actions/setup-python@<commit-sha>and add a comment with the version for reference, like# v5.x.x. - To find the latest commit SHA, visit https://github.com/actions/setup-python/releases, choose your intended release, and copy its commit SHA.
- Use the new pinned reference, e.g.
uses: actions/setup-python@a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0 # v5.0.0.
Pinning actions to a full-length commit SHA protects against supply-chain attacks because the action code cannot be changed by the action owner without you knowing.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by github-actions-mutable-action-tag.
Need help with this issue? Consult our Semgrep Findings Documentation or ask in #help-appsec on Slack.
You can view more details about this finding in the Semgrep AppSec Platform.
| deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 |
There was a problem hiding this comment.
Semgrep identified an issue in your code:
GitHub Actions step uses mutable version tag @v4 instead of pinned commit SHA, allowing attackers to silently redirect the action to malicious code.
More details about this
The actions/checkout step uses version tag @v4 instead of a pinned commit SHA. Version tags and branch references in GitHub Actions can be silently repointed by the action's owner to malicious code without any update to your workflow file. This enables supply-chain attacks where a compromised maintainer could redirect @v4 to inject malicious code that exfiltrates repository secrets or modifies your build output.
Exploit scenario:
- An attacker gains control of the
actions/checkoutrepository and force-pushes thev4tag to point to a commit containing malicious code - When your workflow runs, it automatically uses this new malicious version due to the mutable tag reference
- The malicious checkout action could execute arbitrary code with access to
GITHUB_TOKEN, allowing the attacker to read your repository secrets or push backdoors to your main branch - Your workflow file never changed—the attack is silent and difficult to detect
Pin to a full 40-character commit SHA (e.g., actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608) to ensure you always run the exact version you tested.
To resolve this comment:
✨ Commit fix suggestion
| - uses: actions/checkout@v4 | |
| # Pinned to commit SHA to prevent supply-chain attacks. See: https://github.com/actions/checkout/commits/v4 | |
| uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 |
View step-by-step instructions
- Find the commit SHA for the exact version of the action you want to use. You can find this by visiting the action's repository (for example, https://github.com/actions/checkout) and looking at the "commits" tab or in the release/tag list.
- Replace
uses: actions/checkout@v4withuses: actions/checkout@<commit-sha>where<commit-sha>is the full 40-character commit hash you found in step 1 (for example:uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608). - Repeat these steps for any other GitHub Actions referenced by branch or tag names (such as
v4,v3,main, or similar).
Pinning to a full commit SHA ensures the workflow always uses the same, reviewed code and protects against supply-chain attacks resulting from upstream changes.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by github-actions-mutable-action-tag.
Need help with this issue? Consult our Semgrep Findings Documentation or ask in #help-appsec on Slack.
You can view more details about this finding in the Semgrep AppSec Platform.
There was a problem hiding this comment.
Pull request overview
Adds a MkDocs-based documentation site for the Twilio Agent Connect Python SDK and configures GitHub Pages deployment.
Changes:
- Added MkDocs Material configuration, navigation, and documentation pages.
- Added getting-started, guides, examples, and API reference documentation structure.
- Added GitHub Actions deployment workflow and ignored local MkDocs build output.
Reviewed changes
Copilot reviewed 22 out of 23 changed files in this pull request and generated 37 comments.
Show a summary per file
| File | Description |
|---|---|
mkdocs.yml |
Defines MkDocs site metadata, theme, plugins, markdown extensions, and navigation. |
.github/workflows/docs.yml |
Adds automated docs build and GitHub Pages deployment workflow. |
.gitignore |
Ignores generated site output and Python bytecode. |
docs/README.md |
Adds contributor instructions for local docs development and deployment. |
docs/index.md |
Adds documentation homepage and quick-start example. |
docs/getting-started/index.md |
Adds getting-started overview. |
docs/getting-started/installation.md |
Adds package installation instructions. |
docs/getting-started/quickstart.md |
Adds first-agent tutorial and examples. |
docs/getting-started/twilio-setup.md |
Adds Twilio setup and webhook configuration guide. |
docs/guides/architecture.md |
Adds architecture overview. |
docs/guides/channels.md |
Adds channel usage guide. |
docs/guides/memory.md |
Adds placeholder memory guide. |
docs/guides/openai-adapter.md |
Adds placeholder OpenAI adapter guide. |
docs/guides/server.md |
Adds placeholder server guide. |
docs/examples/index.md |
Adds examples overview. |
docs/examples/openai.md |
Adds placeholder OpenAI examples page. |
docs/examples/aws.md |
Adds placeholder AWS examples page. |
docs/api/core.md |
Adds initial core API reference. |
docs/api/adapters.md |
Adds placeholder adapters API reference. |
docs/api/channels.md |
Adds placeholder channels API reference. |
docs/api/models.md |
Adds placeholder models API reference. |
docs/api/server.md |
Adds placeholder server API reference. |
docs/contributing.md |
Includes repository contributing guide in docs site. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Install dependencies: | ||
|
|
||
| ```bash | ||
| pip install -r docs-requirements.txt |
| branches: | ||
| - main | ||
| - test-docs # Add your test branch here |
|
|
||
| ### "Configuration not found" | ||
|
|
||
| - Verify `CONVERSATION_CONFIGURATION_ID` is correct |
| ```python | ||
| from tac.channels.whatsapp import WhatsAppChannel | ||
|
|
||
| whatsapp_channel = WhatsAppChannel(tac, memory_mode="always") |
| async def handle_whatsapp(user_message, context, memory_response): | ||
| # WhatsApp-specific context | ||
| from_number = context.from_ # e.g., "whatsapp:+1234567890" | ||
|
|
||
| return "Thanks for your WhatsApp message!" |
| @function_tool | ||
| async def check_weather(location: str) -> str: | ||
| """Check the weather for a location.""" | ||
| # Your weather API logic | ||
| return f"The weather in {location} is sunny" | ||
|
|
||
| @function_tool |
| @function_tool | ||
| async def check_weather(location: str) -> str: | ||
| """Check the weather for a location.""" | ||
| # Your weather API logic | ||
| return f"The weather in {location} is sunny" | ||
|
|
||
| @function_tool |
| api_key="SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", | ||
| api_token="your_api_secret_here", | ||
| account_sid="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", | ||
| conversation_configuration_id="conv_configuration_xxxxx" | ||
| ) |
| - [OpenAI Chat Completions](openai.md#chat-completions-api) - Using the Chat Completions API | ||
| - [OpenAI Responses API](openai.md#responses-api) - Using the new Responses API | ||
| - [OpenAI Agents SDK](openai.md#agents-sdk) - Integrating with OpenAI Agents |
| - [AWS Bedrock Agent](aws.md#bedrock-agent) - AWS Bedrock Agent integration | ||
| - [AWS Bedrock AgentCore](aws.md#bedrock-agentcore) - AWS Bedrock AgentCore integration | ||
| - [AWS Strands](aws.md#strands) - AWS Strands agent integration |
- Remove getting-started, guides, examples sections - Keep only API reference documentation - Update home page to focus on API docs - Clean navigation structure
- Use mkdocstrings to auto-generate API docs from Python docstrings - Document TAC, TACConfig classes from source - Document all channel classes (Voice, SMS, RCS, WhatsApp, Chat) - Document models module - Document adapters (OpenAI with_tac_memory) - Document server classes (TACFastAPIServer) - Remove placeholder 'Coming soon' content
- Add mkdocstrings filters to exclude private members (_prefix) - Explicitly list public methods for each class: - TAC: __init__, on_message_ready, on_conversation_ended, retrieve_memory, is_orchestrator_enabled - TACConfig: from_env, account_sid, api_key, api_secret, conversation_configuration_id - Channels: __init__, process_webhook/handle_*, send_response - Server: __init__, start, get_app - Hide undocumented members - Set show_source: false globally
- Simplify all API doc files to use module-level auto-generation - Remove manual member lists - now controlled by __all__ in Python code - Add DOCS_CONTROL.md guide explaining how to control docs from code - Docs now auto-generated from __all__ exports + docstrings - To hide: use _ prefix or remove from __all__ - To show: add to __all__ and add docstring
- Consolidate all API docs into single docs/api.md file - Remove docs/api/ folder (5 files → 1 file) - Update navigation to single 'API Reference' entry - All sections (Core, Channels, Adapters, Server, Models) on one page - Zero maintenance - fully auto-generated from __all__
- Use README.md as home page (symlink docs/index.md → README.md) - Keep only docs/api.md for API reference - Simplify mkdocs.yml to bare minimum (removed theme customization, markdown extensions) - Single source of truth: README.md maintained in root - Zero maintenance: Home = README.md (symlink), API = auto-generated from __all__
Summary
Sets up MkDocs documentation with automatic deployment to GitHub Pages.
Changes
mkdocs.yml) with Material themedocs/getting-started/- Installation, quickstart, Twilio setupdocs/guides/- Architecture, channels, memory, OpenAI adapter, serverdocs/examples/- OpenAI and AWS partner examplesdocs/api/- API reference for core, adapters, channels, models, server.github/workflows/docs.yml):mainandtest-docsbranchesgh-pagesbranch.nojekyllfile for GitHub Pages compatibilityDocumentation URL
Once merged and GitHub Pages is enabled, documentation will be available at:
https://twilio.github.io/twilio-agent-connect-python/
Testing
uv run mkdocs serveNext Steps
After merging:
gh-pagesbranch)main🤖 Generated with Claude Code