Skip to content

GitHub Action

Rich-codex was primarily designed to run automatically with GitHub actions, to keep your screenshots up to date for you.

If there are changes to the images, the action can exit with an error (default) or automatically commit the updates.

Info

For GitHub Actions to push commits to your repository, you'll need to set Workflow permissions to Read and write permissions under Actions -> General in the repo settings. See the GitHub docs.

Example workflow

This action looks for rich-codex content in the repo. It removes any SVG files found in docs/img/ that don't match the outputs and generates the updated images. If there have been any changes, it pushes a new commit with the updated images.

.github/workflows/screenshots.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
name: Rich-codex
on: [push]
jobs:
  rich_codex:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3

      - name: Install your custom tools
        run: pip install .

      - name: Generate terminal images with rich-codex
        uses: ewels/rich-codex@v1
        with:
          commit_changes: "true"
          clean_img_paths: docs/img/*.svg

Tip

The @v1 installs the latest rich-codex release under the v1.x.x version. Rich-codex uses semantic versioning, so this means that your workflow will use the most up to date version without the risk of having breaking changes (which would warrant a v2.x.x release number).

Triggers

In the above example, the workflow is triggered by the line on: [push]. This means that new screenshots will be generated on every commit.

For some people this may be a little excessive, in which case you might prefer some of the following suggestions.

Warning

If you have commit_changes: "true" set as in the example above, you should only run in environments where pushing a new commit is possible. For example, using this in a workflow triggered by a release will fail because the workflow will be running on a detached commit.

Note that GitHub has extensive documentation on the different ways to trigger actions workflows.

Tip

You can mix and match multiple different triggers!

If specific files are edited

If you only want to re-render screenshots if certain files (or filetypes) are edited, you can filter the push event with the paths key:

on:
  push:
    paths:
      - "**.md"
      - .rich-codex.yml
      - src/myapp/cli-flags.py

Specific branches

You can run on pushes to the main and staging branches only by using:

on:
  push:
    - main
    - staging

Manually running

You can manually run the workflow by pressing a button in the GitHub website. Just use:

on: workflow_dispatch

Filtering for commit message

You can filter by commit message by always running on every push, but then using an if statement on the job.

For example, we can take the main example above and add the following to only run when the commit message includes the string [screenshots]:

.github/workflows/screenshots.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
name: Rich-codex
on: [push]
jobs:
  rich_codex:
    if: "contains(github.event.head_commit.message, '[screenshots]')"
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v3

      - name: Install your custom tools
        run: pip install .

      - name: Generate terminal images with rich-codex
        uses: ewels/rich-codex@v1
        with:
          commit_changes: "true"
          clean_img_paths: docs/img/*.svg

GitHub Action Inputs

Basically everything that you can configure via the command line interface / config can also be configured within GitHub actions via the with key.

For a full description of all available inputs, please see the configuration overview docs.