From 7c90d8f4736107382f49136a0f36b684f710f13f Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Mon, 18 Aug 2025 12:56:33 +0300 Subject: [PATCH 1/4] Add i18n examples and revise the AI integration page for clarity. --- CLAUDE.md | 73 ++++++++++++++++++ .../LinearBAI/code-review/README.md | 76 ++++++++++--------- .../LinearBAI/describe-pr/README.md | 66 ++++++++++------ .../integrations/LinearBAI/code-review-bb.cm | 26 ------- .../integrations/LinearBAI/code-review-gl.cm | 27 ------- .../integrations/LinearBAI/describe-pr-bb.cm | 16 ---- .../integrations/LinearBAI/describe-pr-gl.cm | 17 ----- docs/integrations/LinearBAI.md | 6 +- 8 files changed, 157 insertions(+), 150 deletions(-) create mode 100644 CLAUDE.md delete mode 100644 docs/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm delete mode 100644 docs/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm delete mode 100644 docs/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm delete mode 100644 docs/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..807b4a467 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,73 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is the gitStream repository - a workflow automation tool for git repositories that allows users to create automated code review workflows using YAML and Jinja2 templates. gitStream processes Continuous Merge (CM) files (`.cm` extension) that define automations for pull/merge requests across GitHub, GitLab, and Bitbucket. + +## Development Commands + +### Documentation Server +The documentation is built using MkDocs Material theme. + +```bash +# Set up Python virtual environment (Python <= 3.10 required) +python -m venv .venv +. ./.venv/bin/activate + +# Install dependencies +pip install -r requirements.txt + +# Run documentation server locally +mkdocs serve # Runs at http://127.0.0.1:8000/ + +# Build documentation +mkdocs build +``` + +## Code Architecture + +### Project Structure +- **docs/** - Documentation source files (Markdown) + - `automations/` - Automation examples and library + - `downloads/` - Downloadable CM files and templates + - `integrations/` - Third-party integration documentation + - `screenshots/` - Documentation images +- **plugins/filters/** - JavaScript filter function plugins that extend gitStream capabilities + - Each plugin has its own directory with `index.js`, `README.md`, and optional test files + - Plugins enable custom data processing and external API integrations +- **site/** - Generated documentation site (do not edit directly) +- **automations/** - Example automation configurations +- **tutorials/** - Tutorial projects demonstrating gitStream usage + +### Core Concepts + +1. **CM Files (.cm)**: YAML + Jinja2 configuration files that define automation rules + - Located in `.cm/` directory at repository root + - Can also be defined at organization level in a special `cm` repository + - Each file must contain `manifest:` and `automations:` sections + +2. **Automation Components**: + - **Context Variables**: Pre-defined objects like `files`, `branch`, `repo` providing PR metadata + - **Filter Functions**: Functions applied to variables using pipe operator `|` + - **Automation Actions**: Actions like `add-comment`, `set-required-approvals`, `add-label` + - **Custom Expressions**: Reusable Jinja2 expressions defined in CM files + +3. **Plugin System**: JavaScript plugins in `plugins/filters/` that create new filter functions + - Each plugin exports a filter function that can be used in CM files + - Plugins can connect to external APIs or perform complex data processing + +### Key Files +- `mkdocs.yml` - Documentation site configuration +- `requirements.txt` - Python dependencies for documentation +- `.cm/*.cm` - Repository-level automation rules +- `docs/downloads/gitstream.cm` - Default automation template + +## Important Notes + +- When editing CM files, preserve YAML indentation as it's significant +- Organization-level rules can be overridden by repository-level rules with the same identifier +- The identifier is composed of filename + automation name (e.g., `gitstream/safe_changes`) +- gitStream triggers on PR creation and updates by default, with configurable explicit triggers +- Draft PRs are ignored by default (configurable via explicit triggers on GitHub) \ No newline at end of file diff --git a/docs/automations/integrations/LinearBAI/code-review/README.md b/docs/automations/integrations/LinearBAI/code-review/README.md index cc04fb207..9aa6d348b 100644 --- a/docs/automations/integrations/LinearBAI/code-review/README.md +++ b/docs/automations/integrations/LinearBAI/code-review/README.md @@ -5,7 +5,7 @@ category: [quality, genai, efficiency, quickstart] starter_kits: [genai] quickstart: true --- -# Code Review Using LinearB's AI :material-star-circle: +# Code Review Using LinearB's AI Use LinearB's AI with the [`code-review`](/automation-actions/#code-review) action to automatically review the introduced changes to the code. @@ -24,8 +24,6 @@ Use LinearB's AI with the [`code-review`](/automation-actions/#code-review) acti * Perform an AI-driven code review and append the review comments to the PR. * Use `guidelines` to add your prompts to the team or org review -=== "For GitHub" - !!! example "Configuration Example" ```yaml+jinja --8<-- "docs/downloads/automation-library/integrations/LinearBAI/code-review.cm" @@ -36,39 +34,45 @@ Use LinearB's AI with the [`code-review`](/automation-actions/#code-review) acti -=== "For GitLab" - - !!! example "Configuration Example" - ```yaml+jinja - --8<-- "docs/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm" - ``` -
- - [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm){ .md-button } - -
- -=== "For Bitbucket" - - !!! example "Configuration Example" - ```yaml+jinja - --8<-- "docs/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm" - ``` -
- - [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm){ .md-button } - -
- -!!! tip "`./REVIEW_RULES.md` example" - - This file should be created in your repo root: - - ``` - 1. Do not comment on missing documentation. - 2. Do not comment on missing tests. - 3. For JavaScript code, enforce using camelCase for variables and functions. - ``` +#### Localization Support + +You can request the AI to provide code review comments in your preferred language by adding it to the guidelines: + +```yaml+jinja +automations: +linearb_ai_review: + if: + - {{ not pr.draft }} + run: + - action: code-review@v1 + args: + guidelines: | + - Use Spanish language for all comments + - Focus on code quality and best practices +``` + +#### Repository rules file example + +1. Add the rules file to your repo root: + +```title="./REVIEW_RULES.md" +- Do not comment on missing documentation. +- Do not comment on missing tests. +- For JavaScript code, enforce using camelCase for variables and functions. +``` + +2. Load the file in the code review automation: + +``` +automations: + linearb_ai_review: + if: + - {{ not pr.draft }} + run: + - action: code-review@v1 + args: + guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} +``` diff --git a/docs/automations/integrations/LinearBAI/describe-pr/README.md b/docs/automations/integrations/LinearBAI/describe-pr/README.md index c44668457..c75e12228 100644 --- a/docs/automations/integrations/LinearBAI/describe-pr/README.md +++ b/docs/automations/integrations/LinearBAI/describe-pr/README.md @@ -5,7 +5,7 @@ category: [quality, genai, efficiency, quickstart] starter_kits: [genai] quickstart: true --- -# Add PR Description Using LinearB's AI :material-star-circle: +# PR Description Using LinearB's AI Use the [`describe-changes`](/automation-actions/#describe-changes) automation action to automatically generate and append a concise, AI-generated description to a pull request. This ensures that all PRs include meaningful and helpful descriptions, improving review efficiency. @@ -22,8 +22,6 @@ Use the [`describe-changes`](/automation-actions/#describe-changes) automation a * Append the AI-generated description to the PR description. -=== "For GitHub" - !!! example "Configuration Example" ```yaml+jinja --8<-- "docs/downloads/automation-library/integrations/LinearBAI/describe-pr.cm" @@ -34,29 +32,47 @@ Use the [`describe-changes`](/automation-actions/#describe-changes) automation a -=== "For GitLab" - - !!! example "Configuration Example" - ```yaml+jinja - --8<-- "docs/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm" - ``` -
- - [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm){ .md-button } - -
+#### Localization Support + +You can request the AI to provide code review comments in your preferred language by adding it to the guidelines: + +```yaml+jinja +automations: + linearb_ai_desc: + if: + - {{ not pr.draft }} + run: + - action: describe-changes@v1 + args: + concat_mode: append + guidelines: | + - Use Korean language for all comments +``` + +#### Repository rules file example + +1. Add the rules file to your repo root: + +```title="./DESCRIPTION_RULES.md" +- Add emojis to highlight important changes. +- Use clear and concise language. +- Avoid using jargon or technical terms. +``` + +2. Load the file in the code review automation: + +``` +automations: + linearb_ai_desc: + if: + - {{ not pr.draft }} + run: + - action: describe-changes@v1 + args: + concat_mode: append + guidelines: {{ "./DESCRIPTION_RULES.md" | readFile() | dump }} +``` -=== "For Bitbucket" - - !!! example "Configuration Example" - ```yaml+jinja - --8<-- "docs/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm" - ``` -
- - [:octicons-download-24: Download this example as a CM file.](/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm){ .md-button } - -
## Additional Resources diff --git a/docs/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm b/docs/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm deleted file mode 100644 index 7ae83ee6e..000000000 --- a/docs/downloads/automation-library/integrations/LinearBAI/code-review-bb.cm +++ /dev/null @@ -1,26 +0,0 @@ -manifest: - version: 1.0 - -automations: - linearb_ai_review: - if: - - {{ not (is.bot_author or is.bot_branch) }} - run: - - action: code-review@v1 - args: - approve_on_LGTM: {{ approve_pr_on_lgtm }} # optional arg, you can remove it - guidelines: {{ guidelines }} - -# Define variables -# Add conditions for PR approvals. For example - allow approval only for specific users -approve_pr_on_lgtm: false - -# Add `guidelines` to add your prompts to the review, you can have org wide instructions -# by placing the `REVIEW_RULES.md` in the `cm` repo or team level instructions by adding it to -# the team repo. -# Note: To when the file is in the `cm` repo, use this example: `../cm/REVIEW_RULES.md` -guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} - -is: - bot_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }} - bot_branch: {{ branch.name | match(list=['renovate/']) | some }} diff --git a/docs/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm b/docs/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm deleted file mode 100644 index 8e3c0cb3b..000000000 --- a/docs/downloads/automation-library/integrations/LinearBAI/code-review-gl.cm +++ /dev/null @@ -1,27 +0,0 @@ -manifest: - version: 1.0 - -automations: - linearb_ai_review: - if: - - {{ not pr.draft }} - - {{ not (is.bot_author or is.bot_branch) }} - run: - - action: code-review@v1 - args: - approve_on_LGTM: {{ approve_pr_on_lgtm }} # optional arg, you can remove it - guidelines: {{ guidelines }} - -# Define variables -# Add conditions for PR approvals. For example - allow approval only for specific users -approve_pr_on_lgtm: false - -# Add `guidelines` to add your prompts to the review, you can have org wide instructions -# by placing the `REVIEW_RULES.md` in the `cm` repo or team level instructions by adding it to -# the team repo. -# Note: To when the file is in the `cm` repo, use this example: `../cm/REVIEW_RULES.md` -guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} - -is: - bot_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }} - bot_branch: {{ branch.name | match(list=['renovate/']) | some }} diff --git a/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm b/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm deleted file mode 100644 index c86a1a505..000000000 --- a/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-bb.cm +++ /dev/null @@ -1,16 +0,0 @@ -manifest: - version: 1.0 - -automations: - linearb_ai_description: - # skip description for Draft PRs and PRs from bots - if: - - {{ not (is.bot_author or is.bot_branch) }} - run: - - action: describe-changes@v1 - args: - concat_mode: append - -is: - bot_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }} - bot_branch: {{ branch.name | match(list=['renovate/']) | some }} diff --git a/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm b/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm deleted file mode 100644 index 9cacd6fef..000000000 --- a/docs/downloads/automation-library/integrations/LinearBAI/describe-pr-gl.cm +++ /dev/null @@ -1,17 +0,0 @@ -manifest: - version: 1.0 - -automations: - linearb_ai_description: - # skip description for Draft PRs and PRs from bots - if: - - {{ not pr.draft }} - - {{ not (is.bot_author or is.bot_branch) }} - run: - - action: describe-changes@v1 - args: - concat_mode: append - -is: - bot_author: {{ pr.author | match(list=['github-actions', '_bot_', '[bot]', 'dependabot']) | some }} - bot_branch: {{ branch.name | match(list=['renovate/']) | some }} diff --git a/docs/integrations/LinearBAI.md b/docs/integrations/LinearBAI.md index 4a7a4fce6..12b844bda 100644 --- a/docs/integrations/LinearBAI.md +++ b/docs/integrations/LinearBAI.md @@ -7,17 +7,17 @@ category: [quality, genai, copilot, tests, efficiency] !!! tip "User Commands" - LinearB's AI is available also with user commands, read more about them [here](/user-commands) + LinearB's AI is available also with `/gs` user commands, read more about them [here](/user-commands). ## Automation Examples -### Use LinearB's AI for a comprehensive Code Review :material-star-circle: +### Code Review using LinearB's AI --8<-- "docs/automations/integrations/LinearBAI/code-review/README.md:example" -### Add PR Description Using LinearB's AI :material-star-circle: +### PR Description Using LinearB's AI --8<-- "docs/automations/integrations/LinearBAI/describe-pr/README.md:example" From 89a7ce2c1a6dbe453e02165f8c3170ce4ddc36b0 Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Mon, 18 Aug 2025 12:58:18 +0300 Subject: [PATCH 2/4] fix list numbers --- .../LinearBAI/code-review/README.md | 30 ++++++++--------- .../LinearBAI/describe-pr/README.md | 32 +++++++++---------- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/automations/integrations/LinearBAI/code-review/README.md b/docs/automations/integrations/LinearBAI/code-review/README.md index 9aa6d348b..ba0cd15b2 100644 --- a/docs/automations/integrations/LinearBAI/code-review/README.md +++ b/docs/automations/integrations/LinearBAI/code-review/README.md @@ -55,24 +55,24 @@ linearb_ai_review: 1. Add the rules file to your repo root: -```title="./REVIEW_RULES.md" -- Do not comment on missing documentation. -- Do not comment on missing tests. -- For JavaScript code, enforce using camelCase for variables and functions. -``` + ```title="./REVIEW_RULES.md" + - Do not comment on missing documentation. + - Do not comment on missing tests. + - For JavaScript code, enforce using camelCase for variables and functions. + ``` 2. Load the file in the code review automation: -``` -automations: - linearb_ai_review: - if: - - {{ not pr.draft }} - run: - - action: code-review@v1 - args: - guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} -``` + ``` + automations: + linearb_ai_review: + if: + - {{ not pr.draft }} + run: + - action: code-review@v1 + args: + guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} + ``` diff --git a/docs/automations/integrations/LinearBAI/describe-pr/README.md b/docs/automations/integrations/LinearBAI/describe-pr/README.md index c75e12228..d52cc5c44 100644 --- a/docs/automations/integrations/LinearBAI/describe-pr/README.md +++ b/docs/automations/integrations/LinearBAI/describe-pr/README.md @@ -53,25 +53,25 @@ automations: 1. Add the rules file to your repo root: -```title="./DESCRIPTION_RULES.md" -- Add emojis to highlight important changes. -- Use clear and concise language. -- Avoid using jargon or technical terms. -``` + ```title="./DESCRIPTION_RULES.md" + - Add emojis to highlight important changes. + - Use clear and concise language. + - Avoid using jargon or technical terms. + ``` 2. Load the file in the code review automation: -``` -automations: - linearb_ai_desc: - if: - - {{ not pr.draft }} - run: - - action: describe-changes@v1 - args: - concat_mode: append - guidelines: {{ "./DESCRIPTION_RULES.md" | readFile() | dump }} -``` + ``` + automations: + linearb_ai_desc: + if: + - {{ not pr.draft }} + run: + - action: describe-changes@v1 + args: + concat_mode: append + guidelines: {{ "./DESCRIPTION_RULES.md" | readFile() | dump }} + ``` From a361eef8edc49295da8347e2d769a7271ecddebf Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Mon, 18 Aug 2025 12:59:41 +0300 Subject: [PATCH 3/4] fix yaml identation --- .../LinearBAI/code-review/README.md | 16 +++++++-------- .../LinearBAI/describe-pr/README.md | 20 +++++++++---------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/automations/integrations/LinearBAI/code-review/README.md b/docs/automations/integrations/LinearBAI/code-review/README.md index ba0cd15b2..d50039062 100644 --- a/docs/automations/integrations/LinearBAI/code-review/README.md +++ b/docs/automations/integrations/LinearBAI/code-review/README.md @@ -40,13 +40,13 @@ You can request the AI to provide code review comments in your preferred languag ```yaml+jinja automations: -linearb_ai_review: + linearb_ai_review: if: - - {{ not pr.draft }} + - {{ not pr.draft }} run: - - action: code-review@v1 + - action: code-review@v1 args: - guidelines: | + guidelines: | - Use Spanish language for all comments - Focus on code quality and best practices ``` @@ -65,13 +65,13 @@ linearb_ai_review: ``` automations: - linearb_ai_review: + linearb_ai_review: if: - - {{ not pr.draft }} + - {{ not pr.draft }} run: - - action: code-review@v1 + - action: code-review@v1 args: - guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} + guidelines: {{ "./REVIEW_RULES.md" | readFile() | dump }} ``` diff --git a/docs/automations/integrations/LinearBAI/describe-pr/README.md b/docs/automations/integrations/LinearBAI/describe-pr/README.md index d52cc5c44..3ab9f14f0 100644 --- a/docs/automations/integrations/LinearBAI/describe-pr/README.md +++ b/docs/automations/integrations/LinearBAI/describe-pr/README.md @@ -38,14 +38,14 @@ You can request the AI to provide code review comments in your preferred languag ```yaml+jinja automations: - linearb_ai_desc: + linearb_ai_desc: if: - - {{ not pr.draft }} + - {{ not pr.draft }} run: - - action: describe-changes@v1 + - action: describe-changes@v1 args: - concat_mode: append - guidelines: | + concat_mode: append + guidelines: | - Use Korean language for all comments ``` @@ -63,14 +63,14 @@ automations: ``` automations: - linearb_ai_desc: + linearb_ai_desc: if: - - {{ not pr.draft }} + - {{ not pr.draft }} run: - - action: describe-changes@v1 + - action: describe-changes@v1 args: - concat_mode: append - guidelines: {{ "./DESCRIPTION_RULES.md" | readFile() | dump }} + concat_mode: append + guidelines: {{ "./DESCRIPTION_RULES.md" | readFile() | dump }} ``` From 63a12306886de4146125b89177523eca59967a13 Mon Sep 17 00:00:00 2001 From: Ofer Affias Date: Mon, 18 Aug 2025 13:02:06 +0300 Subject: [PATCH 4/4] fix copy paste error --- docs/automations/integrations/LinearBAI/describe-pr/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/automations/integrations/LinearBAI/describe-pr/README.md b/docs/automations/integrations/LinearBAI/describe-pr/README.md index 3ab9f14f0..e9b76384b 100644 --- a/docs/automations/integrations/LinearBAI/describe-pr/README.md +++ b/docs/automations/integrations/LinearBAI/describe-pr/README.md @@ -34,7 +34,7 @@ Use the [`describe-changes`](/automation-actions/#describe-changes) automation a #### Localization Support -You can request the AI to provide code review comments in your preferred language by adding it to the guidelines: +You can request the AI to add PR descriptions in your preferred language by adding it to the guidelines: ```yaml+jinja automations: @@ -59,7 +59,7 @@ automations: - Avoid using jargon or technical terms. ``` -2. Load the file in the code review automation: +2. Load the file in the PR descriptions automation: ``` automations: