usage-metrics-modules.yml

name: Update Modules Usage Metrics

on:
  schedule:
    # Run monthly on the 1st at 10 AM UTC
    - cron: '0 10 1 * *'
  workflow_dispatch:
    inputs:
      modules:
        description: 'Comma-separated modules to query (leave empty for all modules)'
        required: false
        default: ''

permissions:
  contents: write
  pull-requests: write

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  collect-metrics:
    runs-on: ubuntu-latest
    timeout-minutes: 120
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Set up Go
        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
        with:
          go-version-file: 'usage-metrics/go.mod'

      - name: Query modules
        id: query
        working-directory: usage-metrics
        env:
          MODULES_INPUT: ${{ github.event.inputs.modules }}
        run: |
          # Build module flags array
          MODULE_FLAGS=()
          MODULES="$MODULES_INPUT"
          if [ -z "$MODULES" ]; then
            # Discover all modules by listing subdirectories under modules/ that contain a go.mod file
            while IFS= read -r go_mod_path; do
              module="${go_mod_path#../modules/}"
              module="${module%/go.mod}"
              [ -n "$module" ] && MODULE_FLAGS+=("-module" "$module")
            done < <(find ../modules -mindepth 2 -maxdepth 2 -name go.mod | sort)
          else
            IFS=',' read -ra MODULE_ARRAY <<< "$MODULES"
            for module in "${MODULE_ARRAY[@]}"; do
              module="${module#"${module%%[![:space:]]*}"}"  # trim leading whitespace
              module="${module%"${module##*[![:space:]]}"}"  # trim trailing whitespace
              [ -n "$module" ] && MODULE_FLAGS+=("-module" "$module")
            done
          fi

          echo "Querying modules: ${MODULE_FLAGS[*]}"

          # Query all modules in a single command
          go run collect.go modules "${MODULE_FLAGS[@]}" -csv "../docs/usage-metrics/modules.csv"

      - name: Create or update Pull Request
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          # Check for changes without staging (avoids conflicts on branch checkout)
          if git diff --quiet docs/usage-metrics/modules.csv; then
            echo "No changes to commit"
            exit 0
          fi

          DATE=$(date +%Y-%m-%d)
          MONTH=$(date +%Y-%m)
          BRANCH_NAME="chore/update-modules-usage-metrics-$MONTH"

          # Preserve the newly collected metrics before any branch switching
          cp docs/usage-metrics/modules.csv /tmp/modules-usage-metrics.csv

          # Check if the branch already exists on the remote
          if git ls-remote --heads origin "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
            echo "Branch $BRANCH_NAME already exists, pushing new commit to it"
            # Reset the working tree so checkout succeeds
            git checkout -- docs/usage-metrics/modules.csv
            git fetch origin "$BRANCH_NAME:refs/remotes/origin/$BRANCH_NAME"
            git checkout "$BRANCH_NAME"
          else
            echo "Creating new branch $BRANCH_NAME"
            git checkout -b "$BRANCH_NAME"
          fi

          # Restore the newly collected metrics and stage them
          cp /tmp/modules-usage-metrics.csv docs/usage-metrics/modules.csv
          git add docs/usage-metrics/modules.csv

          if git diff --staged --quiet; then
            echo "No changes to commit (branch already has identical data)"
            exit 0
          fi

          git commit -m "chore(metrics): update modules usage metrics ($DATE)"
          git push -u origin "$BRANCH_NAME"

          # Create a PR only if one doesn't already exist for this branch
          EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --state open --json number --jq '.[0].number')
          if [ -n "$EXISTING_PR" ]; then
            echo "PR #$EXISTING_PR already exists for branch $BRANCH_NAME, updated with new commit"
          else
            gh pr create \
              --title "chore: update modules usage metrics ($MONTH)" \
              --body "Automated update of modules usage metrics data. This PR updates the modules usage metrics CSV file with the latest GitHub import search counts for testcontainers-go modules." \
              --base main
          fi