.github

Reusable workflows (not only) for cvxgrp

⚠️ Private repositories

Be careful when using actions in private repositories. The group has a limited number of minutes per month. In public repositories, actions are free.

Poetry

To take full advantage of those actions we recommend moving to poetry. Poetry is a python package manager that allows to create virtual environments and to manage dependencies. It is also a build tool that can be used to create packages and to run tests.

Action workflows

Github workflows can help to robustify and to automate the process of creating software and documents. We recommend Github introduction.

We go through an incomplete list of example actions created for cvxgrp:

latex

This workflow is used to compile *.tex files. It uploads the generated documents to the draft branch.

build

This workflow is used to support the release of packages (to pypi). It assumes the project is built with poetry. It publishes the produced 'dist' folder to a dedicated branch.

setup-environment

This workflow installs python and poetry. It then proceeds to construct the virtual environment using poetry. It can rely on cached versions of the virtual environment. It assumes the project is built with poetry.

sphinx

This workflow builds a sphinx documentation based on your docstrings.

test

This workflow install pytest and some its friends. It uploads the test results as artifacts. It assumes the project is built with poetry.

Using workflows

Creating workflows for your own repository is simple. Please follow:

Create the '.github/workflows' folder.

In this folder create a yml file with the name of the workflow you want to use, e.g. basic.yml.

name: "basic"

on:
  push:

jobs:
  pre-commit:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - uses: pre-commit/action@v3.0.1
      with:
        extra_args: '--verbose --all-files'

  test:
    runs-on: ubuntu-latest
    steps:
    - uses: cvxgrp/.github/actions/test@main

    - name: Coveralls GitHub Action
      uses: coverallsapp/github-action@v2
      with:
        files: artifacts/tests/coverage/coverage.info
        format: lcov

Every push to the repository will trigger the workflow. It will run all jobs in the workflow. There are two jobs defined here: pre-commit and test. Both these jobs run on a ubuntu machine. Each job consists of at least one step. The steps are the actions that will be executed.

In pre-commit job we checkout the repository first and then run the 3rd party pre-commit/action step.

In the test job we run the cvxgrp action performing all tests. The action would checkout the repository first. In the second step we share the coverage results with yet another 3rdd party GitHub action.

It is very common to use external GitHub actions.

There are many more examples of such workflow files in the repositories:

Note the strong overlap between both projects. The jobs are essentially all the same. Rather than coding the same workflow twice we point from both places to the actions defined here.

For a paper repository we use the LaTeX workflow. For an example

cov_pred_finance

All paper repos tend to be private and are hence only visible to members of the group.