> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mergewatch.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Permissions Explained
> Exactly what MergeWatch requests, why it needs each permission, and what it deliberately does not request.
MergeWatch follows the principle of least privilege. Every permission below is the minimum required for the app to function. This page is written for security teams evaluating MergeWatch for enterprise adoption.
## Permission table
### Repository permissions
| Permission | Level | Why it's needed |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Checks** | `read & write` | Create check runs on the pull request with a findings summary, merge readiness score, and pass/fail status. 
|
| **Contents** | `read` | Read the pull request diff and the `.mergewatch.yml` configuration file from the repository root. MergeWatch never writes to repository contents. 
|
| **Issues** | `read & write` | Create and update PR summary comments (GitHub's API uses the Issues endpoint for PR comments), list existing comments to avoid duplicates, and add reactions (e.g., :eyes: when a review starts). 
|
| **Metadata** | `read` | Automatically granted to all GitHub Apps. Provides access to basic repository metadata (name, description, default branch). |
| **Pull requests** | `read & write` | Post inline review findings as PR review comments, create and dismiss reviews, and read PR metadata and diffs. This is the primary output channel for every review. 
|
### Organization permissions
| Permission | Level | Why it's needed |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Members** | `read` | Verify that the user accessing organization-level settings in the dashboard is an org admin. No member data is stored. 
|
All permissions are set at install time via the GitHub App manifest. You can verify them at any time in **GitHub Settings > Applications > MergeWatch > Permissions**.
## What MergeWatch does NOT request
Equally important is what the app *cannot* do. These permissions are intentionally excluded.
MergeWatch cannot push commits, merge pull requests, or modify any file in your repository. It is read-only with respect to code.
MergeWatch cannot access repository or organization secrets. It has zero visibility into your CI/CD credentials, tokens, or environment variables.
MergeWatch cannot trigger, cancel, or modify GitHub Actions workflows. It operates entirely outside your CI/CD pipeline.
## Webhook events
MergeWatch subscribes to the following webhook events. Each event triggers a specific, scoped action. All other events are acknowledged with `200 OK` and ignored.
| Event | Why it's subscribed |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pull_request` | Triggers the review pipeline on `opened`, `synchronize`, `ready_for_review`, and `reopened`. |
| `issue_comment` | Listens for `@mergewatch` mentions in PR comments (`@mergewatch review`, `@mergewatch summary`, or free-form respond mode). |
| `pull_request_review_comment` | Detects when a human replies inside a review-comment thread that MergeWatch started, so the bot can reply inline. Only `created` actions with an `in_reply_to_id` are handled. |
| `check_run` | Listens for `rerequested` so reviewers can re-run a MergeWatch review by clicking the **Re-run** button on the check in GitHub's Checks UI. |
| `installation` | Tracks when the app is installed or uninstalled so MergeWatch can provision or clean up installation records. |
See [Webhook Events](/github-app/webhook-events) for the exact action-level handling per event.
You can inspect every webhook delivery — including payload and response — in your GitHub App's **Advanced** tab under **Recent Deliveries**.
## Security model
MergeWatch is designed so that sensitive credentials are never embedded in code, environment variables, or Lambda configuration.
### Zero API keys in the runtime
GitHub credentials (App ID, private key, webhook secret) are stored in **AWS SSM Parameter Store**, encrypted at rest with AWS KMS. The Lambda function reads them at invocation time via the SSM API — they are never baked into the deployment artifact.
Amazon Bedrock authentication uses the **Lambda execution role** (IAM instance profile). There are no Bedrock API keys to manage, rotate, or leak.
### Webhook signature validation
Every incoming webhook is validated using **HMAC-SHA256** before any processing occurs. Requests with missing or invalid signatures are rejected immediately. This prevents spoofed payloads from triggering the review pipeline.
### IAM permissions are tightly scoped
The Lambda execution role follows least-privilege IAM policy design.
| IAM Action | Scope |
| ---------------------------------------------------- | -------------------------------------------------------------------- |
| `bedrock:InvokeModel` | Scoped to specific foundation model ARNs only. |
| `dynamodb:GetItem`, `PutItem`, `Query`, `UpdateItem` | Limited to the MergeWatch-specific tables created during deployment. |
| `ssm:GetParameter` | Limited to `/mergewatch/{stage}/*` parameters only. |
The IAM policy is defined in the SAM template and deployed via CloudFormation. You can audit the exact permissions in the `template.yaml` file of the MergeWatch repository.
## Frequently asked questions
No. MergeWatch has `contents: read` only. It cannot push commits, create branches, or modify any file. The only write operations are posting review comments (`pull_requests: read & write`) and creating check runs (`checks: read & write`).
No. Diffs are read from the GitHub API, processed in memory during the Lambda invocation, and discarded. No source code is written to DynamoDB, S3, or any other persistent store.
Yes. During installation, select **Only select repositories** instead of **All repositories**. You can change this at any time in GitHub Settings > Applications.
Three places to look: **GitHub webhook delivery logs** show every event sent to the app. **CloudWatch Logs** capture the full Lambda execution trace. **Bedrock invocation logs** (if enabled) show every model call and its input/output.