0
# tox-gh-actions
1

2
A tox plugin that enables seamless integration between tox testing environments and GitHub Actions workflows. The plugin automatically detects which tox environments to run based on the Python version and other factors configured in GitHub Actions matrix strategies, eliminating the need for manual environment selection and enabling efficient parallel testing across multiple Python versions and platforms.
3

4
## Package Information
5

6
- **Package Name**: tox-gh-actions
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install tox-gh-actions`
10

11
## Core Imports
12

13
The plugin operates automatically when installed. The only direct import typically needed is for version information:
14

15
```python
16
from tox_gh_actions import __version__
17
```
18

19
## Basic Usage
20

21
The plugin operates automatically once installed - no direct Python API calls are needed. Configuration is done through tox configuration files.
22

23
### Basic Configuration
24

25
Add a `[gh-actions]` section to your `tox.ini`, `setup.cfg`, or `pyproject.toml`:
26

27
```ini
28
[tox]
29
envlist = py37, py38, py39, py310, py311, mypy
30

31
[gh-actions]
32
python =
33
    3.7: py37
34
    3.8: py38
35
    3.9: py39
36
    3.10: py310
37
    3.11: py311, mypy
38

39
[testenv]
40
# Your test configuration
41
```
42

43
### GitHub Actions Workflow
44

45
```yaml
46
name: Tests
47

48
on: [push, pull_request]
49

50
jobs:
51
  test:
52
    runs-on: ubuntu-latest
53
    strategy:
54
      matrix:
55
        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
56
    
57
    steps:
58
    - uses: actions/checkout@v3
59
    - uses: actions/setup-python@v4
60
      with:
61
        python-version: ${{ matrix.python-version }}
62
    - name: Install dependencies
63
      run: |
64
        python -m pip install --upgrade pip
65
        python -m pip install tox tox-gh-actions
66
    - name: Test with tox
67
      run: tox
68
```
69

70
## Architecture
71

72
The plugin integrates with tox's plugin system through three main hooks:
73

74
- **Environment Selection**: Analyzes GitHub Actions environment and Python version to determine which tox environments to run
75
- **Log Grouping**: Provides GitHub Actions log grouping for better CI output readability
76
- **Configuration Processing**: Parses `[gh-actions]` and `[gh-actions:env]` sections from tox configuration files
77

78
The plugin operates transparently - it detects the GitHub Actions environment, reads the configuration, and automatically overrides tox's envlist to run only the environments appropriate for the current Python version and environment variables.
79

80
## Capabilities
81

82
### Package Version
83

84
Access to package version information.
85

86
```python { .api }
87
__version__: str
88
```
89

90
### Python Version Configuration
91

92
Maps Python versions to tox environments in the `[gh-actions]` section. This is the primary way users configure the plugin.
93

94
```ini { .api }
95
[gh-actions]
96
python =
97
    3.7: py37
98
    3.8: py38, flake8
99
    3.9: py39
100
    3.10: py310, mypy
101
    3.11: py311
102
    pypy-3.7: pypy3
103
    pyston-3.8: pyston38
104
```
105

106
**Supported version formats:**
107
- `3.8`: Specific major.minor version
108
- `3`: Major version only  
109
- `pypy-3.7`: PyPy with specific version
110
- `pyston-3.8`: Pyston with specific version
111

112
**Version matching rules:**
113
- Plugin uses the most specific matching version
114
- If both `3` and `3.8` are configured, `3.8` takes precedence for Python 3.8
115
- Plugin checks versions in order of specificity: `3.8` before `3`
116

117
### Environment Variable Configuration
118

119
Maps environment variable values to tox factors in the `[gh-actions:env]` section.
120

121
```ini { .api }
122
[gh-actions:env]
123
PLATFORM =
124
    ubuntu-latest: linux
125
    macos-latest: macos  
126
    windows-latest: windows
127
DATABASE =
128
    postgresql: pg
129
    mysql: mysql
130
```
131

132
**Environment variable rules:**
133
- Variable names are automatically converted to uppercase
134
- Values map to tox environment factors
135
- Multiple environment variables can be specified
136
- Factors from different variables are combined with factors from Python version
137

138
### Plugin Behavior
139

140
The plugin automatically handles various scenarios:
141

142
**Environment Detection:**
143
- Only activates when `GITHUB_ACTIONS=true` environment variable is present
144
- Falls back gracefully when not running on GitHub Actions
145
- Logs warnings when not in GitHub Actions environment
146

147
**Configuration Handling:**
148
- Respects explicit environment specification via `-e` option or `TOXENV` variable
149
- Uses original envlist when no `[gh-actions]` configuration is present
150
- Handles missing or invalid configuration gracefully
151

152
**Log Management:**
153
- Automatically enables GitHub Actions log grouping for better CI output
154
- Disables log grouping when parallel execution is used to prevent mixed output
155

156
**Common Usage Patterns:**
157

158
```bash
159
# Plugin automatically selects environments based on Python version
160
tox
161

162
# Plugin respects explicit environment selection
163
tox -e py38,py39
164

165
# Plugin respects TOXENV environment variable  
166
TOXENV=py310,mypy tox
167
```
168

169
## Integration Patterns
170

171
### Multi-Platform Testing
172

173
```ini
174
[tox]
175
envlist = py{38,39,310}-{linux,macos,windows}
176

177
[gh-actions]
178
python =
179
    3.8: py38
180
    3.9: py39
181
    3.10: py310
182

183
[gh-actions:env]
184
PLATFORM =
185
    ubuntu-latest: linux
186
    macos-latest: macos
187
    windows-latest: windows
188
```
189

190
### Complex Factor Combinations
191

192
```ini
193
[tox]
194
envlist = py{38,39}-django{22,32,40}-{sqlite,postgres}
195

196
[gh-actions]
197
python =
198
    3.8: py38
199
    3.9: py39
200

201
[gh-actions:env]
202
DATABASE =
203
    sqlite: sqlite
204
    postgres: postgres
205
DJANGO_VERSION =
206
    2.2: django22
207
    3.2: django32  
208
    4.0: django40
209
```
210

211
### Integration with tox requires
212

213
```ini
214
[tox]
215
requires =
216
    tox-conda
217
    tox-gh-actions
218
envlist = py38, py39, py310
219
```