https://github.com/github/ai-moderator
An AI-powered GitHub Action that detects and tags spam in your repository
https://github.com/github/ai-moderator
actions ai spam-detection spam-prevention
Last synced: 2 months ago
JSON representation
An AI-powered GitHub Action that detects and tags spam in your repository
- Host: GitHub
- URL: https://github.com/github/ai-moderator
- Owner: github
- License: mit
- Created: 2025-07-24T03:25:24.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-08-07T01:45:02.000Z (2 months ago)
- Last Synced: 2025-08-07T03:26:34.677Z (2 months ago)
- Topics: actions, ai, spam-detection, spam-prevention
- Language: TypeScript
- Homepage:
- Size: 4.46 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
- awesome-ccamel - github/ai-moderator - An AI-powered GitHub Action that detects and tags spam in your repository (TypeScript)
README
# AI Moderator
An AI-powered GitHub Action that automatically detects spam in issues and
comments using LLMs. Detected issues are tagged as spam and detected comments
are (optionally) minimized.
Each new issue and comment is passed through a series of prompts: by default
checking for link spam, regular spam, and AI-generated content, but you can
[write your own custom prompt](#custom-prompts) if you've got more specific
requirements.
## Usage
Add this action to your repository's workflow file (e.g.,
`.github/workflows/moderator.yml`):
```yaml
name: AI Moderator
on:
issues:
types: [opened]
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
spam-detection:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
models: read
contents: read
steps:
- uses: actions/checkout@v4
- uses: github/ai-moderator
with:
token: ${{ secrets.GITHUB_TOKEN }}
spam-label: 'spam'
ai-label: 'ai-generated'
minimize-detected-comments: true
# Built-in prompt configuration (all enabled by default)
enable-spam-detection: true
enable-link-spam-detection: true
enable-ai-detection: true
# custom-prompt-path: '.github/prompts/my-custom.prompt.yml' # Optional
```
### Configuration
| Input | Description | Default | Required |
| ---------------------------- | ---------------------------------------------------------------------------------- | --------------------- | -------- |
| `token` | GitHub token with issues and pull-requests permissions | `${{ github.token }}` | No |
| `spam-label` | Label to add when generic spam is detected | `spam` | No |
| `ai-label` | Label to add when AI-generated content is detected | `ai-generated` | No |
| `minimize-detected-comments` | Whether to minimize comments detected as spam | `true` | No |
| `custom-prompt-path` | Path to a custom YAML prompt file in your repository (relative to repository root) | (none) | No |
| `enable-spam-detection` | Enable built-in spam detection prompt | `true` | No |
| `enable-link-spam-detection` | Enable built-in link spam detection prompt | `true` | No |
| `enable-ai-detection` | Enable built-in AI-generated content detection prompt | `true` | No |
## Inference
The action does not require any external API keys for inference - it uses the
built-in GitHub token with `models: read` permission to access GitHub Models.
Every GitHub user has GitHub Models inference for free, but if you're running
into rate limiting issues you can choose to
[opt in to paid usage](https://docs.github.com/en/billing/managing-billing-for-your-products/about-billing-for-github-models).
### Default prompts
The action uses built-in YAML prompts located in the `prompts/` directory. Each
prompt can be individually enabled or disabled using the configuration options:
- **`spam-detection.prompt.yml`**: Detects promotional content, scams, and
irrelevant posts (controlled by `enable-spam-detection`)
- **`ai-detection.prompt.yml`**: Identifies AI-generated content patterns
(controlled by `enable-ai-detection`)
- **`link-spam-detection.prompt.yml`**: Focuses on suspicious links and URLs
(controlled by `enable-link-spam-detection`)
All prompts are enabled by default. You can selectively disable them based on
your repository's moderation needs:
```yaml
- uses: github/ai-moderator
with:
token: ${{ secrets.GITHUB_TOKEN }}
enable-spam-detection: true # Enable general spam detection
enable-link-spam-detection: false # Disable link spam detection
enable-ai-detection: true # Enable AI content detection
```
You can iterate on or tweak these prompts via the
[Models tab](https://github.com/github/ai-moderator/models) on this repository.
If you want to push an update to this prompt, please also include updated test
data so we can see the effect of the prompt update.
### Custom prompts
You can also provide your own custom prompt file in your repository using the
`custom-prompt-path` input:
```yaml
- uses: github/ai-moderator
with:
token: ${{ secrets.GITHUB_TOKEN }}
custom-prompt-path: '.github/prompts/my-custom-spam-detection.prompt.yml'
```
Custom prompt files should follow the same YAML format as the built-in prompts.
An example custom prompt file is included at
`.github/prompts/example-custom.prompt.yml` that demonstrates the proper format
and shows how to create repository-specific spam detection rules.
## Development
```bash
# Install dependencies
npm install
# Run tests
npm test
# Build the action
npm run package
# Run linting
npm run lint
```
### Testing
The action includes comprehensive tests for all modules:
```bash
# Run all tests with coverage
npm run test
# Run tests in watch mode
npm run test:watch
```
## License
This project is licensed under the terms of the MIT open source license. Please
refer to [LICENSE](./LICENSE) for the full terms.