Merge pull request #650 from linear-b/add-limitation-info

added info on limits

Author: PavelLinearB

docs/execution-model.md

@@ -6,6 +6,18 @@ gitStream is triggered on new pull requests (PRs) for repositories that have git
 
 When a central `cm` repository is set with the CI/CD runner, the events for PRs from all installed repositories shall be evaluated in the `cm` repository pipeline, considering the organization-level and PR repository rules.
 
+## Execution behavior for free accounts
+
+Free accounts have a monthly limit on the number of PRs that can trigger automations. Once this limit is reached:
+
+- PRs will still be created, but gitStream will skip automations for them.  
+- The gitStream check on these PRs will be concluded as `Skipped`, to ensure that gitStream will not block the PR from merging.  
+- A warning is displayed in PR comments when the organization reaches 90% of its quota.  
+- The limit resets at the start of each month.  
+
+To remove automation limits, <a href="https://linearb.io/contact-us" target="_blank">Contact LinearB</a> and upgrade to a paid plan.  
+🔗 Learn more: [Automation Limits](limits.md)
+
 ## Triggering Mechanism
 
 gitStream automations are triggered by events related to pull requests (PRs). You can specify triggers to fine-tune which events should initiate automations.

docs/faq.md

@@ -25,6 +25,17 @@ To support automations that either Approve or Merge PRs, the git providers requi
 
 gitStream supports repositories in GitHub, GitLab, and Bitbucket. Note that the `add-label` action is not supported in Bitbucket as it does not have a native labeling feature.
 
+## Are there limits on gitStream automations for free accounts?
+
+Yes. Free accounts have a monthly limit on the number of PRs that can trigger automations.  
+
+- When the organization reaches 90% of the limit, a warning will appear in PR comments.  
+- Once the limit is exceeded, new PRs will not trigger automations and will be marked as "Skipped."  
+- The limit resets at the start of each month.  
+
+To remove automation limits, <a href="https://linearb.io/contact-us" target="_blank">Contact LinearB</a> and upgrade to a paid plan.  
+🔗 Learn more: [Automation Limits](limits.md)
+
 ## Can I use gitStream with Merge Queues?
 
 Yes. When a merge queue is used, and gitStream is set as a required check, gitStream automation will be invoked with the merge event. The automation will set gitStream to a `Completed` status and `Skipped` conclusion to allow the PR merge.

docs/index.md

@@ -75,6 +75,14 @@ gitStream is a workflow automation tool that enables you to use YAML configurati
 
 	That's it! Now sit back and watch gitStream run automation rules on your next PR.
 
+!!! warning "Automation limits for free accounts"
+    Free accounts have a monthly cap on PRs that can trigger gitStream automations.
+
+    - At 90% usage, a warning appears in PR comments.  
+    - Once the limit is reached, new PRs will not run automations and the gitStream check will be concluded as `Skipped`.  
+    - Limits reset at the start of each month.
+		
+    🔗 Learn more: [Automation Limits](limits.md)
 
 ## Get Involved
 Want to report a bug, request a new feature, ask a question, get updates for new features, or propose a new configuration for the automation library? [Join us on GitHub](https://github.com/linear-b/gitstream).

docs/limits.md

@@ -0,0 +1,19 @@
+# Automation limits for free accounts
+
+## Monthly PR automation limit
+
+Free accounts have a monthly cap on the number of PRs that can trigger automations in their organization. This limit ensures fair usage while allowing teams to experience gitStream’s benefits before upgrading.
+
+### How it works
+- When the account reaches 90% of its quota, a warning appears in PR comments.  
+- Once the limit is reached, new PRs will not execute automations and the gitStream check will be concluded as `Skipped`.  
+- The limit resets at the start of each month.  
+
+### What happens when the limit is reached?
+- PRs that exceed the quota will still be created as usual, but gitStream will not process automations on them.  
+- The PR check will indicate that automations were skipped due to limits.  
+
+## Need more automations?
+If your team requires a higher automation quota, upgrading to a paid plan will remove these restrictions.
+
+<a href="https://linearb.io/contact-us" target="_blank">Contact LinearB</a> or <a href="https://linearb.io/book-a-demo" target="_blank">Book a demo</a> to explore upgrade options.

mkdocs.yml

@@ -22,6 +22,7 @@ nav:
   - Reference:
     - Configuration: cm-file.md
     - Execution: execution-model.md
+    - Automation Limits: limits.md
     - Context variables: context-variables.md
     - Filter functions: filter-functions.md
     - Automation actions: automation-actions.md