1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204# ruff-action
A GitHub Action to run [ruff](https://github.com/astral-sh/ruff).
This action is commonly used as a pass/fail test to ensure your repository stays
clean, abiding the [rules](https://docs.astral.sh/ruff/rules/) specified in your
configuration. Though it runs `ruff check` by default, the action can do
anything `ruff` can (ex, fix).
## Contents
- [Usage](#usage)
- [Basic](#basic)
- [Specify a different source directory](#specify-a-different-source-directory)
- [Specify multiple files](#specify-multiple-files)
- [Use to install ruff](#use-to-install-ruff)
- [Use `ruff format`](#use-ruff-format)
- [Install specific versions](#install-specific-versions)
- [Install the latest version](#install-the-latest-version)
- [Install a specific version](#install-a-specific-version)
- [Install a version by supplying a semver range or pep440 specifier](#install-a-version-by-supplying-a-semver-range-or-pep440-specifier)
- [Install a version from a specified version file](#install-a-version-from-a-specified-version-file)
- [Validate checksum](#validate-checksum)
- [GitHub authentication token](#github-authentication-token)
- [Outputs](#outputs)
## Usage
| Input | Description | Default |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
| `version` | The version of Ruff to install. See [Install specific versions](#install-specific-versions) | `latest` |
| `version-file` | The file to read the version from. See [Install a version from a specified version file](#install-a-version-from-a-specified-version-file) | None |
| `args` | The arguments to pass to the `ruff` command. See [Configuring Ruff] | `check` |
| `src` | The directory or single files to run `ruff` on. | [github.workspace] |
| `checksum` | The sha256 checksum of the downloaded executable. | None |
| `github-token` | The GitHub token to use for authentication. | `GITHUB_TOKEN` |
### Basic
```yaml
- uses: astral-sh/ruff-action@v3
```
### Specify a different source directory
```yaml
- uses: astral-sh/ruff-action@v3
with:
src: "./src"
```
### Specify multiple files
```yaml
- uses: astral-sh/ruff-action@v3
with:
src: >-
path/to/file1.py
path/to/file2.py
```
### Use to install ruff
This action adds ruff to the PATH, so you can use it in subsequent steps.
```yaml
- uses: astral-sh/ruff-action@v3
- run: ruff check --fix
- run: ruff format
```
By default, this action runs `ruff check` after installation.
If you do not want to run any `ruff` command but only install it,
you can use the `args` input to overwrite the default value (`check`):
```yaml
- name: Install ruff without running check or format
uses: astral-sh/ruff-action@v3
with:
args: "--version"
```
### Use `ruff format`
```yaml
- uses: astral-sh/ruff-action@v3
with:
args: "format --check --diff"
```
### Install specific versions
By default this action looks for a pyproject.toml file in the root of the repository to determine
the ruff version to install. If no pyproject.toml file is found, or no ruff version is defined in
`project.dependencies`, `project.optional-dependencies`, or `dependency-groups`,
the latest version is installed.
> [!NOTE]
> This action does only support ruff versions v0.0.247 and above.
#### Install the latest version
```yaml
- name: Install the latest version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "latest"
```
#### Install a specific version
```yaml
- name: Install a specific version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "0.4.4"
```
#### Install a version by supplying a semver range or pep440 specifier
You can specify a [semver range](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
or [pep440 specifier](https://peps.python.org/pep-0440/#version-specifiers)
to install the latest version that satisfies the range.
```yaml
- name: Install a semver range of ruff
uses: astral-sh/ruff-action@v3
with:
version: ">=0.4.0"
```
```yaml
- name: Pinning a minor version of ruff
uses: astral-sh/ruff-action@v3
with:
version: "0.4.x"
```
```yaml
- name: Install a pep440-specifier-satisfying version of ruff
uses: astral-sh/ruff-action@v3
with:
version: ">=0.11.10,<0.12.0"
```
#### Install a version from a specified version file
You can specify a file to read the version from.
Currently `pyproject.toml` and `requirements.txt` are supported.
```yaml
- name: Install a version from a specified version file
uses: astral-sh/ruff-action@v3
with:
version-file: "my-path/to/pyproject.toml-or-requirements.txt"
```
### Validate checksum
You can specify a checksum to validate the downloaded executable. Checksums up to the default version
are automatically verified by this action. The sha256 hashes can be found on the
[releases page](https://github.com/astral-sh/ruff/releases) of the ruff repo.
```yaml
- name: Install a specific version and validate the checksum
uses: astral-sh/ruff-action@v3
with:
version: "0.7.4"
checksum: "0de731c669b9ece77e799ac3f4a160c30849752714d9775c94cc4cfaf326860c"
```
### GitHub authentication token
This action uses the GitHub API to fetch the ruff release artifacts. To avoid hitting the GitHub API
rate limit too quickly, an authentication token can be provided via the `github-token` input. By
default, the `GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.
If the default
[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
are not sufficient, you can provide a custom GitHub token with the necessary permissions.
```yaml
- name: Install the latest version of ruff with a custom GitHub token
uses: astral-sh/ruff-action@v3
with:
github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
```
## Outputs
| Output | Description |
|----------------|-----------------------------------------|
| `ruff-version` | The version of Ruff that was installed. |
<div align="center">
<a target="_blank" href="https://astral.sh" style="background:none">
<img src="https://raw.githubusercontent.com/astral-sh/uv/main/assets/svg/Astral.svg" alt="Made by Astral">
</a>
</div>
[Configuring Ruff]: https://github.com/astral-sh/ruff/blob/main/docs/configuration.md
[github.workspace]: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context