251 lines
13 KiB
Markdown
251 lines
13 KiB
Markdown
<a href="https://www.ultralytics.com/"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/Ultralytics_Logotype_Original.svg" width="320" alt="Ultralytics logo"></a>
|
|
|
|
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
|
|
# 🚀 Ultralytics Actions
|
|
|
|
Welcome to [Ultralytics Actions](https://github.com/ultralytics/actions) - a collection of GitHub Actions for automating code quality, PR management, and CI/CD workflows across Ultralytics projects.
|
|
|
|
[](https://github.com/marketplace/actions/ultralytics-actions)
|
|
|
|
[](https://github.com/ultralytics/actions/actions/workflows/ci.yml)
|
|
[](https://github.com/ultralytics/actions/actions/workflows/format.yml)
|
|
[](https://github.com/ultralytics/actions/actions/workflows/github_report.yml)
|
|
[](https://app.codecov.io/github/ultralytics/actions)
|
|
|
|
[](https://discord.com/invite/ultralytics)
|
|
[](https://community.ultralytics.com/)
|
|
[](https://reddit.com/r/ultralytics)
|
|
|
|
## 📦 Repository Contents
|
|
|
|
This repository provides three main components:
|
|
|
|
1. **[Ultralytics Actions](#ultralytics-actions-main-action)** - Main GitHub Action for AI-powered code formatting, PR summaries, and auto-labeling
|
|
2. **[Standalone Actions](#standalone-actions)** - Reusable composite actions for common CI/CD tasks
|
|
3. **[Python Package](#python-package)** - `ultralytics-actions` package for programmatic use
|
|
|
|
## Ultralytics Actions (Main Action)
|
|
|
|
AI-powered formatting, labeling, and PR summaries for Python, JavaScript/TypeScript, Swift, Dart, and web/docs files.
|
|
|
|
### 📄 Features
|
|
|
|
- **Python Code:** Formatted using [Ruff](https://github.com/astral-sh/ruff), an extremely fast Python linter and formatter
|
|
- **Python Docstrings:** Google-style formatting enforced with Ultralytics Python docstring formatter (optional)
|
|
- **JavaScript/TypeScript:** Formatted with [Biome](https://biomejs.dev/), an extremely fast formatter for JS, TS, JSX, TSX, and JSON (optional, auto-detected via `biome.json` or `biome.jsonc`)
|
|
- **Web and Docs Files:** Styled with [Prettier](https://github.com/prettier/prettier) for JS, TS, CSS, HTML, JSON, YAML, Markdown, and shell scripts
|
|
- **Swift Code:** Formatted with [`swift-format`](https://github.com/swiftlang/swift-format) _(requires `macos-latest` runner)_
|
|
- **Dart Code:** Formatted with [`dart format`](https://dart.dev/tools/dart-format) for Dart and Flutter projects
|
|
- **Spell Check:** Common misspellings caught using [codespell](https://github.com/codespell-project/codespell)
|
|
- **Broken Links Check:** Broken links identified using [Lychee](https://github.com/lycheeverse/lychee)
|
|
- **PR Summary:** Concise Pull Request summaries generated using AI
|
|
- **PR Review:** AI-powered code reviews identify critical bugs, security issues, and quality concerns with suggested fixes
|
|
- **Auto-labeling:** Applies relevant labels to issues, PRs, and discussions via AI
|
|
|
|
### 🤖 Supported AI Providers
|
|
|
|
Choose between [OpenAI](https://developers.openai.com/) or [Anthropic](https://www.anthropic.com/) for AI-powered features:
|
|
|
|
| Provider | Default Model | API Key |
|
|
| --------- | ------------------- | ------------------- |
|
|
| OpenAI | `gpt-5.6-luna` | `openai_api_key` |
|
|
| Anthropic | `claude-sonnet-4-6` | `anthropic_api_key` |
|
|
|
|
The model is auto-detected based on which API key you provide. Override with the `model` input, or use `review_model` to override PR review only.
|
|
|
|
### 🛠️ How It Works
|
|
|
|
Triggers on GitHub events to streamline workflows:
|
|
|
|
- **Pull Requests:** Ensures formatting standards, generates summaries, provides AI reviews, and applies labels
|
|
- **Issues:** Automatically applies relevant labels using AI
|
|
- **Discussions:** Automatically applies relevant labels using AI
|
|
|
|
### 🔧 Setup
|
|
|
|
Create `.github/workflows/ultralytics-actions.yml`:
|
|
|
|
```yaml
|
|
# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
|
|
|
|
# Ultralytics Actions https://github.com/ultralytics/actions
|
|
# This workflow formats code and documentation in PRs to Ultralytics standards
|
|
|
|
name: Ultralytics Actions
|
|
|
|
on:
|
|
issues:
|
|
types: [opened]
|
|
discussion:
|
|
types: [created]
|
|
pull_request:
|
|
branches: [main]
|
|
types: [opened, closed, synchronize, review_requested]
|
|
|
|
permissions:
|
|
contents: write # Modify code in PRs
|
|
pull-requests: write # Add comments and labels to PRs
|
|
issues: write # Add comments and labels to issues
|
|
discussions: write # Add labels to discussions
|
|
|
|
jobs:
|
|
actions:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Run Ultralytics Actions
|
|
uses: ultralytics/actions@main
|
|
with:
|
|
token: ${{ secrets.GITHUB_TOKEN }} # Auto-generated token
|
|
labels: true # Auto-label issues/PRs using AI
|
|
python: true # Format Python with Ruff
|
|
# python-version: "3.14" # Optional: set up a specific Python version (default: runner Python)
|
|
python_docstrings: true # Format Python docstrings (default: true)
|
|
biome: true # Format JS/TS with Biome (auto-detected via biome.json or biome.jsonc)
|
|
prettier: true # Format YAML, JSON, Markdown, CSS
|
|
swift: false # Format Swift (requires macos-latest)
|
|
dart: false # Format Dart/Flutter
|
|
spelling: true # Check spelling with codespell
|
|
links: true # Check broken links with Lychee
|
|
summary: true # Generate AI-powered PR summaries
|
|
# AI API keys - provide OpenAI OR Anthropic (model auto-detected from key)
|
|
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
|
|
# anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
# model: gpt-5.6-luna # Optional: set model explicitly
|
|
# review_model: claude-opus-4-7 # Optional: override PR review model
|
|
brave_api_key: ${{ secrets.BRAVE_API_KEY }} # Used for broken link resolution
|
|
```
|
|
|
|
## Standalone Actions
|
|
|
|
Reusable composite actions for common CI/CD tasks. Each can be used independently in your workflows.
|
|
|
|
### 1. Retry Action
|
|
|
|
Retry failed commands with exponential backoff and jitter.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/retry@main
|
|
with:
|
|
run: npm install
|
|
retries: 3
|
|
timeout_minutes: 5
|
|
```
|
|
|
|
[**📖 Full Documentation →**](retry/README.md)
|
|
|
|
### 2. Cleanup Disk Action
|
|
|
|
Free up disk space on GitHub runners by removing unnecessary packages and files.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/cleanup-disk@main
|
|
```
|
|
|
|
[**📖 Full Documentation →**](cleanup-disk/README.md)
|
|
|
|
### 3. GitHub Report Action
|
|
|
|
Summarize open PRs and failed default-branch GitHub Actions across organization repositories.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/github-report@main
|
|
with:
|
|
token: ${{ secrets.GITHUB_TOKEN }}
|
|
org: ultralytics # Optional: defaults to ultralytics
|
|
visibility: all # Optional: public, private, internal, all, or comma-separated
|
|
auto_merge_actions_prs: true # Optional: auto-merge eligible GitHub Actions update PRs
|
|
```
|
|
|
|
[**📖 Full Documentation →**](github-report/README.md)
|
|
|
|
### 4. Dependabot Action
|
|
|
|
Update GitHub Actions versions across organization repositories with cached release resolution.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/dependabot@main
|
|
with:
|
|
token: ${{ secrets.GITHUB_TOKEN }}
|
|
```
|
|
|
|
[**📖 Full Documentation →**](dependabot/README.md)
|
|
|
|
### 5. CLA Action
|
|
|
|
Check every pull request commit author against the central Ultralytics CLA signature ledger.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/cla@main
|
|
with:
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
cla-token: ${{ secrets._GITHUB_TOKEN }}
|
|
```
|
|
|
|
[**📖 Full Documentation →**](cla/README.md)
|
|
|
|
### 6. Setup uv Action
|
|
|
|
Install the latest uv with retry support and optionally activate a Python environment.
|
|
|
|
```yaml
|
|
- uses: ultralytics/actions/setup-uv@main
|
|
with:
|
|
python-version: "3.14"
|
|
activate-environment: true
|
|
```
|
|
|
|
[**📖 Full Documentation →**](setup-uv/README.md)
|
|
|
|
## Python Package
|
|
|
|
Install the `ultralytics-actions` package for programmatic access to action utilities, including all [requirements](https://github.com/ultralytics/actions/blob/main/pyproject.toml), in a [**Python>=3.8**](https://www.python.org/) environment.
|
|
|
|
[](https://pypi.org/project/ultralytics-actions/) [](https://clickpy.clickhouse.com/dashboard/ultralytics-actions) [](https://pypi.org/project/ultralytics-actions/)
|
|
|
|
```bash
|
|
uv pip install ultralytics-actions
|
|
```
|
|
|
|
**Available Modules:**
|
|
|
|
- `actions.review_pr` - AI-powered PR review
|
|
- `actions.summarize_pr` - Generate PR summaries
|
|
- `actions.github_report` - Generate GitHub organization reports
|
|
- `actions.first_interaction` - Welcome message for new contributors
|
|
- And more in `actions/` directory
|
|
|
|
## 💡 Contribute
|
|
|
|
Ultralytics thrives on community collaboration, and we deeply value your contributions! Please see our [Contributing Guide](https://docs.ultralytics.com/help/contributing) for details on how you can get involved. We also encourage you to share your feedback through our [Survey](https://www.ultralytics.com/survey?utm_source=github&utm_medium=social&utm_campaign=Survey). A huge thank you 🙏 to all our contributors!
|
|
|
|
[](https://github.com/ultralytics/ultralytics/graphs/contributors)
|
|
|
|
## 📄 License
|
|
|
|
Ultralytics offers two licensing options:
|
|
|
|
- **AGPL-3.0 License**: An [OSI-approved](https://opensource.org/license/agpl-3.0) open-source license ideal for students, researchers, and enthusiasts who value open collaboration. See the [LICENSE](https://github.com/ultralytics/actions/blob/main/LICENSE) file for details.
|
|
- **Enterprise License**: Designed for commercial use, this license allows integrating Ultralytics software and AI models into commercial products without AGPL-3.0's open-source requirements. For enterprise solutions, contact [Ultralytics Licensing](https://www.ultralytics.com/license).
|
|
|
|
## 📫 Contact
|
|
|
|
For bug reports or feature suggestions related to Ultralytics Actions, please submit an issue via [GitHub Issues](https://github.com/ultralytics/actions/issues). Join our [Discord](https://discord.com/invite/ultralytics) community for discussions and support!
|
|
|
|
<br>
|
|
<div align="center">
|
|
<a href="https://github.com/ultralytics"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-github.png" width="3%" alt="Ultralytics GitHub"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://www.linkedin.com/company/ultralytics/"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-linkedin.png" width="3%" alt="Ultralytics LinkedIn"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://twitter.com/ultralytics"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-twitter.png" width="3%" alt="Ultralytics Twitter"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://www.youtube.com/ultralytics"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-youtube.png" width="3%" alt="Ultralytics YouTube"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://www.tiktok.com/@ultralytics"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-tiktok.png" width="3%" alt="Ultralytics TikTok"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://ultralytics.com/bilibili"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-bilibili.png" width="3%" alt="Ultralytics BiliBili"></a>
|
|
<img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-transparent.png" width="3%" alt="space">
|
|
<a href="https://discord.com/invite/ultralytics"><img src="https://raw.githubusercontent.com/ultralytics/assets/main/social/logo-social-discord.png" width="3%" alt="Ultralytics Discord"></a>
|
|
</div>
|