Running cog automatically against GitHub pull requests#

I really like Cog (previously) as a tool for automating aspects of my Python project documentation - things like the SQL schemas shown on the LLM logging page.

When using cog in this way it’s important to remember to run cog -r to update those generated files before pushing a commit.

I’ve previously been enforcing this using GitHub Actions - as part of my tests I run cog --check *.md so that my test suite fails if the generated files are out of date.

This morning I switched to a friendlier version. I now run a GitHub Actions workflow against any created or modified pull requests and, if cog needs to be run, the workflow runs it and then helpfully commits the files back to that repo.

I got Claude to write the initial workflow, and then iterated on it to get it working.

This goes in .github/workflows/cog.yml:

1
name: Run Cog
2

3
on:
4
  pull_request:
5
    types: [opened, synchronize]
6

7
permissions:
8
  contents: write
9
  pull-requests: write
10

11
jobs:
12
  run-cog:
13
    runs-on: ubuntu-latest
14
    steps:
15
      - uses: actions/checkout@v4
16
        with:
17
          ref: ${{ github.head_ref }}
18
      - name: Set up Python 3.11
19
        uses: actions/setup-python@v5
20
        with:
21
          python-version: '3.11'
22
      - name: Install dependencies
23
        run: pip install -e '.[test]'
24
      - name: Run cog
25
        run: |
26
          cog -r docs/**/*.md docs/*.md
27
      - name: Check for changes
28
        id: check-changes
29
        run: |
30
          if [ -n "$(git diff)" ]; then
31
            echo "changes=true" >> $GITHUB_OUTPUT
32
          else
33
            echo "changes=false" >> $GITHUB_OUTPUT
34
          fi
35
      - name: Commit and push if changed
36
        if: steps.check-changes.outputs.changes == 'true'
37
        run: |
38
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
39
          git config --local user.name "github-actions[bot]"
40
          git add -A
41
          git commit -m "Ran cog"
42
          git push

The [opened, synchronize] trigger means that the workflow will run whenever a pull request is either created or updated in some way.

Using that user.email and user.name causes the bot to get a nice icon of its own:

List of commits on GitHub - the last one reads Ran cog and shows a GitHub avatar icon

Squash-merging the PR causes the bot to be credited as a co-author.