├── LICENSE ├── README.md └── action.yml /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Packet Coders 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # GitHub Action - Setup and Cache Python Poetry 2 | 3 | This action simplifies the setup and caching of Poetry, and provides the following functionality for GitHub Actions users: 4 | * Python setup via [`actions/setup-python`](https://github.com/actions/setup-python). 5 | * Poetry install via [`snok/install-poetry`](https://github.com/snok/install-poetry). 6 | * Poetry binary caching via [`actions/cache`](https://github.com/actions/cache). 7 | * Poetry dependency caching via [`actions/cache`](https://github.com/actions/cache). 8 | 9 | ## Basic Usage 10 | 11 | **Note:** 12 | * We assume you already have `pyproject.toml`, `poetry.lock` and a test module created for `pytest` to run this workflow example. 13 | * For your first `push` to `main`, the workflow will download Poetry and the required project dependencies, then save it to the cache. 14 | * For your second run (whether it's on a different job, re-run the job or a different workflow [based on your first cached commit](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)) this Action will use the cache. 15 | * You can see list of cache entries by going to: `Your Repo` -> `Actions` tab -> `Caches` under `Managements` (left navbar, at the bottom). 16 | 17 | [Don't forget the limitation of cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). 18 | 19 | ```yml 20 | name: ci 21 | 22 | on: 23 | # Triggers the workflow on push but only for the main branch 24 | push: 25 | branches: [ main ] 26 | 27 | jobs: 28 | test: 29 | runs-on: ubuntu-latest 30 | steps: 31 | #-------------------------------------# 32 | # Check out repo and set up Python # 33 | #-------------------------------------# 34 | - name: Check out the repository 35 | uses: actions/checkout@v3 36 | - name: "Setup Python, Poetry and Dependencies" 37 | uses: packetcoders/action-setup-cache-python-poetry@main 38 | with: 39 | python-version: 3.8 40 | poetry-version: 1.2.2 41 | 42 | #------------------------# 43 | # Run your actual job # 44 | #------------------------# 45 | - name: Run tests 46 | run: | 47 | poetry run pytest 48 | ``` 49 | 50 | ## [Matrix Strategy](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs) Usage 51 | 52 | With a matrix strategy, several "workflows" are generated based on your matrix inputs. In this case, multiple caches for each of the matrix workflows will be generated. 53 | 54 | ```yml 55 | name: ci 56 | 57 | on: 58 | # Triggers the workflow on push but only for the main branch 59 | push: 60 | branches: [ main ] 61 | 62 | jobs: 63 | test: 64 | # Using matrix strategy 65 | strategy: 66 | matrix: 67 | python-version: [3.8, 3.9, 3.10] 68 | poetry-version: [1.2.2] 69 | runs-on: ubuntu-latest 70 | steps: 71 | #------------------------------------# 72 | # Check out repo and set up Python # 73 | #------------------------------------# 74 | - name: Check out the repository 75 | uses: actions/checkout@v3 76 | - name: "Setup Python, Poetry and Dependencies" 77 | uses: packetcoders/action-setup-cache-python-poetry@main 78 | with: 79 | python-version: ${{matrix.python-version}} 80 | poetry-version: ${{matrix.poetry-version}} 81 | 82 | #-----------------------# 83 | # Run your actual job # 84 | #-----------------------# 85 | - name: Run tests 86 | run: | 87 | poetry run pytest 88 | ``` 89 | 90 | ## Advanced usage 91 | 92 | ### Passing extra arguments to `poetry install` 93 | 94 | By default the action will install your dendencies with `poetry install --no-interaction --no-root` You can specify extra arguments with `install-args`, e.g. 95 | 96 | ```yml 97 | - name: "Setup Python, Poetry and Dependencies" 98 | uses: packetcoders/action-setup-cache-python-poetry@main 99 | with: 100 | python-version: "3.12" 101 | poetry-version: "1.6.1" 102 | install-args: --all-extras 103 | ``` 104 | to install any optional dependencies alongside the required ones. 105 | 106 | ## License 107 | 108 | The scripts and documentation in this project are released under the [MIT License](LICENSE). 109 | -------------------------------------------------------------------------------- /action.yml: -------------------------------------------------------------------------------- 1 | name: "Setup and Cache Python Poetry" 2 | description: "Python Poetry setup, including the caching of dependencies and Poetry installation." 3 | branding: 4 | icon: 'play' 5 | color: 'blue' 6 | 7 | inputs: 8 | python-version: 9 | description: Python Version 10 | required: true 11 | poetry-version: 12 | description: Poetry Version 13 | required: true 14 | install-args: 15 | description: Extra arguments to `poetry install` 16 | required: false 17 | default: '' 18 | 19 | runs: 20 | using: "composite" 21 | steps: 22 | #---------------------------# 23 | # Set-up python # 24 | #---------------------------# 25 | - name: Set up python ${{ inputs.python-version }} 26 | id: setup-python 27 | uses: actions/setup-python@v5 28 | with: 29 | python-version: ${{ inputs.python-version }} 30 | #----------------------------------------# 31 | # Install & configure Poetry # 32 | #----------------------------------------# 33 | - name: Load cached Poetry Binary 34 | id: cached-poetry-binary 35 | uses: actions/cache@v4 36 | with: 37 | path: ~/.local 38 | key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ inputs.poetry-version }} 39 | - name: Install Poetry 40 | uses: snok/install-poetry@v1 41 | with: 42 | version: ${{ inputs.poetry-version }} 43 | virtualenvs-create: true 44 | virtualenvs-in-project: true 45 | #----------------------------------------------# 46 | # Load cached venv if cache exists # 47 | #----------------------------------------------# 48 | - name: Load cached venv 49 | id: cached-poetry-dependencies 50 | uses: actions/cache@v4 51 | with: 52 | path: .venv 53 | key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}${{ inputs.install-args }} 54 | # Restore cache with this prefix if not exact match with key 55 | # Note cache-hit returns false in this case, so the below step will run 56 | restore-keys: | 57 | venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}- 58 | #----------------------------------------------------------# 59 | # Install dependencies if cache does not exist # 60 | #----------------------------------------------------------# 61 | - name: Install dependencies 62 | if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true' 63 | shell: bash 64 | run: poetry install --no-interaction --no-root ${{ inputs.install-args }} 65 | --------------------------------------------------------------------------------