From e006b922a6f7c747bfcaed98948ab304114a40e0 Mon Sep 17 00:00:00 2001
From: brucearctor <5032356+brucearctor@users.noreply.github.com>
Date: Mon, 3 Apr 2023 16:47:26 -0700
Subject: [PATCH] Add documentation for `ruff-action` (GitHub Action!) (#3857)

---
 README.md     | 14 +++++++++++++
 docs/usage.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a7cb7ee6e2..0cefa0f4a3 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,20 @@ Ruff can also be used as a [pre-commit](https://pre-commit.com) hook:
 Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or
 alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp).
 
+Ruff can also be used as a [GitHub Action](https://github.com/features/actions) via
+[`ruff-action`](https://github.com/chartboost/ruff-action):
+
+```yaml
+name: Ruff
+on: [ push, pull_request ]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1
+```
+
 ### Configuration
 
 Ruff can be configured through a `pyproject.toml`, `ruff.toml`, or `.ruff.toml` file (see:
diff --git a/docs/usage.md b/docs/usage.md
index f4bb24a1ba..7b670e7a38 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -15,6 +15,8 @@ You can run Ruff in `--watch` mode to automatically re-run on-change:
 ruff check path/to/code/ --watch
 ```
 
+## pre-commit
+
 Ruff can also be used as a [pre-commit](https://pre-commit.com) hook:
 
 ```yaml
@@ -33,7 +35,7 @@ Or, to enable autofix:
   rev: 'v0.0.260'
   hooks:
     - id: ruff
-      args: [--fix, --exit-non-zero-on-fix]
+      args: [ --fix, --exit-non-zero-on-fix ]
 ```
 
 Ruff's pre-commit hook should be placed after other formatting tools, such as Black and isort,
@@ -41,5 +43,55 @@ _unless_ you enable autofix, in which case, Ruff's pre-commit hook should run _b
 and other formatting tools, as Ruff's autofix behavior can output code changes that require
 reformatting.
 
+### VS Code
+
 Ruff can also be used as a [VS Code extension](https://github.com/charliermarsh/ruff-vscode) or
 alongside any other editor through the [Ruff LSP](https://github.com/charliermarsh/ruff-lsp).
+
+### GitHub Action
+
+Ruff can also be used as a GitHub Action via [`ruff-action`](https://github.com/chartboost/ruff-action).
+
+By default, `ruff-action` runs as a pass-fail test to ensure that a given repository doesn't contain
+any lint rule violations as per its [configuration](https://github.com/charliermarsh/ruff/blob/main/docs/configuration.md).
+However, under-the-hood, `ruff-action` installs and runs `ruff` directly, so it can be used to
+execute any supported `ruff` command (e.g., `ruff check --fix`).
+
+`ruff-action` supports all GitHub-hosted runners, and can be used with any published Ruff version
+(i.e., any version available on [PyPI](https://pypi.org/project/ruff/)).
+
+To use `ruff-action`, create a file (e.g., `.github/workflows/ruff.yml`) inside your repository
+with:
+
+```yaml
+name: Ruff
+on: [ push, pull_request ]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1
+```
+
+Alternatively, you can include `ruff-action` as a step in any other workflow file:
+
+```yaml
+      - uses: chartboost/ruff-action@v1
+```
+
+`ruff-action` accepts optional configuration parameters via `with:`, including:
+
+- `version`: The Ruff version to install (default: latest).
+- `options`: The command-line arguments to pass to Ruff (default: `"check"`).
+- `src`: The source paths to pass to Ruff (default: `"."`).
+
+For example, to run `ruff check --select B ./src` using Ruff version `0.0.259`:
+
+```yaml
+- uses: chartboost/ruff-action@v1
+  with:
+    src: "./src"
+    version: 0.0.259
+    args: --select B
+```