docs-pr.yml

##
## Github workflow for auto-opening a PR on the stacks-network/docs repo
##  whenever the auto-generated documentation here changes.
##
## It does this using a robot account `kantai-robot` to create a
##  _base_ for the PR, the robot doesn't need any permissions to anyone
##  else's git repositories.
##

name: Open Docs PR

defaults:
  run:
    shell: bash

env:
  ROBOT_OWNER: kantai-robot
  ROBOT_REPO: docs.blockstack
  TARGET_OWNER: stacks-network
  TARGET_REPO: docs
  TARGET_REPOSITORY: stacks-network/docs

## Only run when:
##   - push to master
on:
  push:
    branches:
      - master

jobs:
  dist:
    name: Open Docs PR
    runs-on: ubuntu-latest
    env:
      ROBOT_BRANCH: ${{ format('auto/clarity-ref-{0}', github.sha) }}
    steps:
      - name: Checkout the latest code
        id: git_checkout
        uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5

      - name: Build docs
        id: build_docs
        env:
          DOCKER_BUILDKIT: 1
        run: rm -rf docs-output && docker build -o docs-output -f ./.github/actions/docsgen/Dockerfile.docsgen .

      - name: Checkout latest docs
        id: git_checkout_docs
        uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
        with:
          token: ${{ secrets.DOCS_GITHUB_TOKEN }}
          repository: ${{ env.TARGET_REPOSITORY }}
          path: docs

      - name: Branch and commit
        id: push
        run: |
          cd docs
          git config user.email "kantai+robot@gmail.com"
          git config user.name "PR Robot"
          git fetch --unshallow
          git checkout -b $ROBOT_BRANCH
          cp ../docs-output/clarity-reference.json ./src/_data/clarity-reference.json
          cp ../docs-output/boot-contracts-reference.json ./src/_data/boot-contracts-reference.json
          git add src/_data/clarity-reference.json
          git add src/_data/boot-contracts-reference.json
          if $(git diff --staged --quiet --exit-code); then
            echo "No reference.json changes, stopping"
            echo "open_pr=0" >> "$GITHUB_OUTPUT"
          else
            git remote add robot https://github.com/$ROBOT_OWNER/$ROBOT_REPO
            git commit -m "auto: update Clarity references JSONs from stacks-core@${GITHUB_SHA}"
            git push robot $ROBOT_BRANCH
            echo "open_pr=1" >> "$GITHUB_OUTPUT"
          fi

      - name: Open PR
        id: open_pr
        if: ${{ steps.push.outputs.open_pr == '1' }}
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
        with:
          github-token: ${{ secrets.DOCS_GITHUB_TOKEN }}
          script: |
            // get env vars
            const process = require("process");
            const robot_owner = process.env.ROBOT_OWNER;
            const robot_branch = process.env.ROBOT_BRANCH;
            const head = `${robot_owner}:${robot_branch}`;
            const owner = process.env.TARGET_OWNER;
            const repo = process.env.TARGET_REPO;

            console.log(`Checking PR with params: head= ${head} owner= ${owner} repo= ${repo}`);

            // check if a pull exists
            const existingPulls = await github.pulls.list({
              owner, repo, state: "open" });
            const myPulls = existingPulls.data.filter( pull => pull.user.login == robot_owner );
            console.log(myPulls);

            for (myPull of myPulls) {
              // close any open PRs
              const pull_number = myPull.number;
              console.log(`Closing PR: ${ pull_number }`);
              await github.pulls.update({ owner, repo, pull_number, state: "closed" });
            }

            // Open PR if one doesn't exist
            console.log("Opening the new PR.");
            let result = await github.pulls.create({
                owner, repo, head,
                base: "master",
                title: "Auto: Update API documentation from stacks-core",
                body: "Update API documentation from the latest in `stacks-core`",
            });