{"id":13880692,"url":"https://github.com/sturdy-dev/codeball-action","last_synced_at":"2025-09-07T21:14:38.551Z","repository":{"id":36961142,"uuid":"494489850","full_name":"sturdy-dev/codeball-action","owner":"sturdy-dev","description":"🔮 Codeball – AI Code Review that finds bugs and fast-tracks your code","archived":false,"fork":false,"pushed_at":"2023-04-06T17:06:02.000Z","size":7889,"stargazers_count":311,"open_issues_count":19,"forks_count":34,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-01T11:03:13.611Z","etag":null,"topics":["actions","ai","code-review","codeball","github-actions","pull-request"],"latest_commit_sha":null,"homepage":"https://codeball.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sturdy-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-20T14:10:23.000Z","updated_at":"2025-03-30T08:19:41.000Z","dependencies_parsed_at":"2024-10-14T20:11:16.178Z","dependency_job_id":null,"html_url":"https://github.com/sturdy-dev/codeball-action","commit_stats":{"total_commits":184,"total_committers":5,"mean_commits":36.8,"dds":"0.46739130434782605","last_synced_commit":"4e96dfa904bedf8fe7d4d4e227e6125b663f4ff3"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sturdy-dev%2Fcodeball-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sturdy-dev%2Fcodeball-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sturdy-dev%2Fcodeball-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sturdy-dev%2Fcodeball-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sturdy-dev","download_url":"https://codeload.github.com/sturdy-dev/codeball-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149501,"owners_count":20891954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","ai","code-review","codeball","github-actions","pull-request"],"created_at":"2024-08-06T08:03:24.020Z","updated_at":"2025-04-04T09:08:15.244Z","avatar_url":"https://github.com/sturdy-dev.png","language":"TypeScript","readme":"![Codeball](https://user-images.githubusercontent.com/47952/173048697-d3d39fc3-6238-4fc3-9baf-ccbbb3b4258c.png)\n\n[![Discord](https://img.shields.io/badge/join-Discord-blue.svg)](https://discord.gg/nE4UcQHZtV)\n\n\n# 🔮 Codeball \u0026mdash; AI Code Review \n\nCodeball is a code review AI that scores Pull Requests on a grade from 0 _(needs careful review)_ to 1 _(you should merge this!)_\n\nUse Codeball to add labels to help you focus, to auto approve PRs, and more. The Codeball action is easy to use (sane defaults), and is highly customizeable to fit your workflow when needed.\n\n🏷 Labels PRs when you should **review with caution**  – Stay sharp, don't let the bugs pass through!\n\n✅ Identifies and **approves** or labels safe PRs – Save time by fast-tracking PRs that are easy to review\n\n🏖 **Great defaults**, fully customizable and programmable with GitHub Actions  \n\n## GitHub Action\n\nThe Codeball GitHub Action runs [Codeball](https://codeball.ai/) on all new Pull Requests, and approves the Pull Request ([example](https://github.com/sturdy-dev/codeball-action/pull/7)) if the model classifies it as safe.\n\n- [Online Demo](https://codeball.ai/)\n- [How Codeball Works](https://codeball.ai/how)\n\n## Quick Start\n\n1. Create a new file called `.github/workflows/codeball.yml` with the following content:\n\n```yaml\nname: Codeball\non:\n  pull_request: {}\n  pull_request_review_comment:\n    types: [created, edited]\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          # For all configuration options see https://github.com/sturdy-dev/codeball-action/blob/v2/action.yml\n          approvePullRequests: \"true\"\n          labelPullRequestsWhenApproved: \"true\"\n          labelPullRequestsWhenReviewNeeded: \"false\"\n          failJobsWhenReviewNeeded: \"false\"\n```\n\n2. 🎉 That's it! Codeball will now run on new Pull Requests, and will approve the PR if it's a good one!\n\n## Customizations\n\nCodeball Actions are built on multiple smaller building-blocks, that are heavily configurable through GitHub Actions. Here's a few examples:\n\n_If you're using Codeball in another way, please let us know in an issue!_\n\n### Example: \"Dry-run\" mode, labels all PRs with the Codeball Result\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ codeball-dry-run.yml\u003c/summary\u003e\n  \n```yaml\nname: Codeball\non: [pull_request]\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          approvePullRequests: \"false\"\n          labelPullRequestsWhenApproved: \"true\"\n          labelPullRequestsWhenReviewNeeded: \"true\"\n          failJobsWhenReviewNeeded: \"false\"\n```\n\u003c/details\u003e\n\n### Example: Approve only (no labels)\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ codeball-approve.yml\u003c/summary\u003e\n  \n```yaml\nname: Codeball\non: [pull_request]\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          approvePullRequests: \"true\"\n          labelPullRequestsWhenApproved: \"false\"\n          labelPullRequestsWhenReviewNeeded: \"false\"\n          failJobsWhenReviewNeeded: \"false\"\n```\n\u003c/details\u003e\n\n\n### Example: Filter files (run only for PRs modifying a single service)\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ codeball-filter-files.yml\u003c/summary\u003e\n  \n```yaml\nname: Codeball\non:\n  pull_request:\n    # Run Codeball only if files under \"/web/\" has been modified (and no other files)\n    # See: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-and-excluding-paths\n    paths:\n      - '!**'\n      - '/web/**'\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          approvePullRequests: \"true\"\n          labelPullRequestsWhenApproved: \"true\"\n          labelPullRequestsWhenReviewNeeded: \"false\"\n          failJobsWhenReviewNeeded: \"false\"\n```\n\u003c/details\u003e\n\n\n### Example: Fail the Codeball Action (❌) if Codeball does not approve the contribution\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ codeball-fail-not-approved.yml\u003c/summary\u003e\n\n```yaml\nname: Codeball\non: [pull_request]\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          approvePullRequests: \"true\"\n          labelPullRequestsWhenApproved: \"true\"\n          labelPullRequestsWhenReviewNeeded: \"false\"\n          failJobsWhenReviewNeeded: \"true\"\n```\n\u003c/details\u003e\n\n### Example: Skip Draft pull requests\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ skip-drafts.yml\u003c/summary\u003e\n\n```yaml\nname: Codeball\non:\n  pull_request:\n     types:\n     - opened\n     - reopened\n     - synchronize\n     - ready_for_review\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    if: ${{ !github.event.pull_request.draft }}\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n```\n\u003c/details\u003e\n\n### Example: Running Codeball as a different user (to support CODEOWNERS, etc)\n\n\u003cdetails\u003e\n  \u003csummary\u003e▶️ run-different-user.yml\u003c/summary\u003e\n  \n  #### Instructions\n  \n1. If you don't have one already, create a new GitHub bot account (a normal account, named something like `your-org-bot`)\n2. Invite the account to your repository or org, and give it WRITE permissions\n3. Generate a Personal Access Token for the bot account\n4. Create a new Organization Action Secret (https://github.com/organizations/YOUR-ORG-NAME/settings/secrets/actions), or Repository secret (https://github.com/YOUR-ORG-NAME/YOUR-REPO/settings/secrets/actions) named `CODEBALL_BOT_TOKEN` with the PAT as the value.\n5. Add `GITHUB_TOKEN: ${{ secrets.CODEBALL_BOT_TOKEN }}` to your `codeball.yml` (see example below)\n6. All Codeball related actions (adding/removing labels, approving PRs, etc) will now run as your newly configured user!\n7. _(Optional)_ Add your new user to CODEOWNERS \n\n```yaml\nname: Codeball\non:\n  pull_request: {}\n\njobs:\n  codeball_job:\n    runs-on: ubuntu-latest\n    name: Codeball\n    steps:\n      - name: Codeball\n        uses: sturdy-dev/codeball-action@v2\n        with:\n          GITHUB_TOKEN: ${{ secrets.CODEBALL_BOT_TOKEN }}\n```\n\u003c/details\u003e\n\n## Building Blocks\n\nThe Codeball sub-actions are:\n\n* [`sturdy-dev/codeball-action/baller/@v2`](./baller/README.md) – Triggers new Codeball Jobs\n* [`sturdy-dev/codeball-action/status/@v2`](./status/README.md) – Waits for the the Codeball result\n* [`sturdy-dev/codeball-action/approver/@v2`](./approver/README.md) - Approves PRs\n* [`sturdy-dev/codeball-action/labeler/@v2`](./labeler/README.md) – Adds labels to PRs\n* [`sturdy-dev/codeball-action/suggester/@v2`](./suggester/README.md) – Converts comments to code suggestions\n\n## How Codeball works\n\nCodeball uses a deep learning model that has been trained on over 1 million Pull Requests. For each contribution it considers in hundreds of inputs, including:\n\n- The code diffs (perceptual hashes)\n- The author's recent experience with the affected files\n- The change frequency of the affected files\n- Past code reversals / fix-ups\n\nCodeball is optimized for precision, which means it only approves contributions that it's really confident in.\n\n## Troubleshooting\n\n### Permissions\n\nCodeball works out of the box with GitHub Actions. \n\nIf you're using non-default permissions, or want to use a custom access token. Make sure that you're running Codeball with the following permissions:\n\n```yaml\npermissions:\n  contents: read\n  issues: write\n  pull-requests: write\n```\n\nTo allow PR approvals, make sure that **\"Allow GitHub Actions to Create and Approve Pull Requests\"** is enabled in the repository and organization settings on GitHub (under \"Settings \u003e Actions \u003e General\").\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow recommended GitHub Permissions\u003c/summary\u003e\n  \n![Fork pull request workflows from outside collaborators](https://user-images.githubusercontent.com/47952/184130867-8c149bfa-e827-425c-882b-eacf775c9542.png)\n![Fork pull request workflows in private repositories](https://user-images.githubusercontent.com/47952/184130872-7e91445d-4287-4b80-8c3b-6ff40fc893db.png)\n![Workflow permissions](https://user-images.githubusercontent.com/47952/184130874-54458e54-84f4-48fb-9347-0188c3ba27b6.png)\n\u003c/details\u003e\n\nIf you can not (or do not want to) update the org and repo settings for GitHub Actions, install the [\"Codeball AI Writer\"](https://github.com/apps/codeball-ai-writer) GitHub App on the repository. When installed, Codeball will use the permissions granted via the app instead of the GitHub Actions token.\n\n### Forks and public repositories\n\nGitHub does not offer (and reasonably so) a way for Pull Requests from a fork to a public repository to run with \"write\" permissions to the parent repository.\n\nIf you want to use Codeball on a public repository, install the [\"Codeball AI Writer\"](https://github.com/apps/codeball-ai-writer) app on the parent repository. This allows the Codeball Action to use the permissions from the app as a fallback if the action is running without write permissions.\n\n### Forks and private repositories\n\nBy default, Pull Requests from a fork does not have \"write\" permissions when running in GitHub Actions, and those Pull Requests can not be approved or labeled.\n\nThe easiest workaround to this issue is to install the [\"Codeball AI Writer\"](https://github.com/apps/codeball-ai-writer) app (see instructions for how to use Codeball on a public repository).\n\nAlternatively, you can enable \"Send write tokens to workflows from fork pull requests\" on the repository ([docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)) via GitHub.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsturdy-dev%2Fcodeball-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsturdy-dev%2Fcodeball-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsturdy-dev%2Fcodeball-action/lists"}