Check Version Action

The check-version action automatically checks for upstream version updates and optionally creates pull requests with the changes.

Overview

This action:

Scans all apps in your repository
Checks for version updates based on checkver configuration
Updates meta.json files when new versions are found
Optionally creates pull requests with the changes
Generates detailed summary reports

Usage

Basic Setup

.github/workflows/check-version.yaml

name: Check Version

on:
  schedule:
    - cron: '0 */2 * * *'  # Every 2 hours
  workflow_dispatch:

jobs:
  check-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check Version
        uses: ./action/check-version
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

With Auto PR Creation

- name: Check Version
  uses: ./action/check-version
  with:
    token: ${{ secrets.PAT }}  # Personal Access Token required for PRs
    create_pr: 'true'

Manual Trigger for Specific App

on:
  workflow_dispatch:
    inputs:
      context:
        description: 'App context (e.g., apps/icones)'
        type: choice
        default: all
        options:
          - all
          - apps/icones
          - apps/cobalt
      create_pr:
        description: 'Create PR'
        type: choice
        default: 'false'
        options:
          - 'true'
          - 'false'
          - development

jobs:
  check-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check Version
        uses: ./action/check-version
        with:
          token: ${{ secrets.PAT }}
          context: ${{ inputs.context }}
          create_pr: ${{ inputs.create_pr }}

Inputs

token

string

required

GitHub token for repository access.

Use GITHUB_TOKEN for read-only checks
Use Personal Access Token (PAT) for creating PRs

with:
  token: ${{ secrets.GITHUB_TOKEN }}

context

string

default:"all"

App context to check. Use all to check all apps.Examples:

all - Check all apps
apps/icones - Check only icones app
base/nginx - Check only nginx base image

with:
  context: apps/icones

create_pr

'true' | 'false' | 'development'

default:"'false'"

Control PR creation behavior:

'true' - Create PR to main/master branch
'false' - No PR (dry run)
'development' - Create PR to development branch

with:
  create_pr: 'true'

concurrency

number

default:"3"

Number of apps to check concurrently. Controls parallelism.

with:
  concurrency: 5

debug

boolean

default:"false"

Enable debug logging.

with:
  debug: true

logFormat

'simple' | 'detailed' | 'json'

Log output format for debugging.

simple - Minimal output
detailed - Verbose logging
json - JSON formatted logs

with:
  logFormat: detailed

Outputs

The action provides outputs in the GitHub Actions summary:

Summary Report

## Check Version Results

### Updated Apps (2)

#### apps/cobalt
- **latest**: 11.2 → 11.3 (e4b5388)
- **Commits**: 15 new commits
- **Changes**: web/package.json updated

#### apps/icones  
- **latest**: 0bc5918 → a7f3d21 (a7f3d21)
- **Commits**: 3 new commits

### Up-to-date Apps (12)

✅ All other apps are up to date

Complete Example

.github/workflows/check-version.yaml

name: Check Version

on:
  schedule:
    - cron: '0 */2 * * *'  # Every 2 hours
  workflow_dispatch:
    inputs:
      context:
        description: 'App context'
        type: choice
        default: all
        options:
          - all
          - apps/cobalt
          - apps/icones
          - apps/haitang
      create_pr:
        description: 'Create PR'
        type: choice
        default: 'false'
        options:
          - 'true'
          - 'false'
          - development
      debug:
        description: 'Debug mode'
        type: boolean
        default: false
  push:
    branches:
      - master
    paths:
      - apps/*/meta.json
      - apps/*/Dockerfile

jobs:
  check-version:
    name: Check Version
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write  # Required for creating PRs
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history required

      - name: Cache Git repositories
        uses: actions/cache@v4
        with:
          path: .git-cache
          key: git-repos-${{ hashFiles('**/meta.json') }}
          restore-keys: |
            git-repos-

      - name: Check Version
        uses: ./action/check-version
        env:
          TZ: Asia/Shanghai
        with:
          token: ${{ secrets.PAT }}
          context: ${{ inputs.context }}
          create_pr: ${{ inputs.create_pr }}
          debug: ${{ inputs.debug }}

How It Works

1. Scan Apps

Scans the repository for apps with meta.json files:

apps/*/meta.json
base/*/meta.json
sync/*/meta.json
test/*/meta.json

2. Version Checking

For each app variant:

Reads checkver configuration
Clones/updates upstream repository (cached in .git-cache)
Extracts version based on checkver.type:
- version: Read from file (package.json, VERSION, etc.)
- tag: Get latest matching Git tag
- sha: Get latest commit SHA
- manual: Compare with previous commit
Compares with current version and sha in meta.json

3. Update Detection

Marks app as outdated if:

Version string changed
OR commit SHA changed

4. File Updates

When updates are found:

Updates meta.json with new version and SHA
Processes files listed in checkver.processFiles with placeholder replacement
Collects commit information from upstream

5. PR Creation

If create_pr is enabled:

Creates a new branch: update/{app-name}-{timestamp}
Commits changes with descriptive message
Creates pull request with:
- Title: “Update to ”
- Detailed changelog from upstream commits
- Links to upstream repository

Caching

The action uses Git repository caching to speed up subsequent runs:

- name: Cache Git repositories
  uses: actions/cache@v4
  with:
    path: .git-cache
    key: git-repos-${{ hashFiles('**/meta.json') }}
    restore-keys: |
      git-repos-

This caches cloned upstream repositories in .git-cache/ directory.

Permissions

Read-only (no PR)

permissions:
  contents: read

With PR creation

permissions:
  contents: write
  pull-requests: write

Triggers

Scheduled Checks

on:
  schedule:
    - cron: '0 */2 * * *'  # Every 2 hours

Common schedules:

Every 2 hours: '0 */2 * * *'
Every 6 hours: '0 */6 * * *'
Daily at midnight: '0 0 * * *'
Weekly on Monday: '0 0 * * 1'

On Push

on:
  push:
    branches:
      - master
    paths:
      - apps/*/meta.json
      - apps/*/Dockerfile

Runs when meta.json or Dockerfile changes are pushed.

Manual Dispatch

on:
  workflow_dispatch:
    inputs:
      context:
        description: 'App to check'
        default: all

Allows manual triggering from GitHub Actions UI.

Skip Checks

Add [skip check] to commit messages to skip version checking:

git commit -m "Update docs [skip check]"

Best Practices

Use caching to speed up runs:

- uses: actions/cache@v4
  with:
    path: .git-cache
    key: git-repos-${{ hashFiles('**/meta.json') }}

Set appropriate check frequency:
- Stable apps: Check daily or weekly
- Development branches: Check every few hours
- Use checkFrequency in meta.json to control per-app

Use PAT for PR creation:

token: ${{ secrets.PAT }}  # Not GITHUB_TOKEN

Enable debug for troubleshooting:
```
debug: true
```
Review PRs before merging:
- Check changelog
- Verify version bump is correct
- Test build if needed

Troubleshooting

No updates detected

Verify checkver configuration is correct
Check if upstream has new commits/tags
Enable debug: true for detailed logs
Verify repository URL is accessible

PR creation fails

Ensure using PAT with repo scope
Check pull-requests: write permission is set
Verify branch name doesn’t already exist

Cache issues

Clear cache manually from Actions UI
Update cache key if meta.json structure changed
Check .git-cache directory size

Checkver Types - Version checking strategies
Meta Schema - Configuration reference
Resolve Meta Action - Build metadata resolution

Meta Schema

Actions

​Overview

​Usage

​Basic Setup

​With Auto PR Creation

​Manual Trigger for Specific App

​Inputs

​Outputs

​Summary Report

​Complete Example

​How It Works

​1. Scan Apps

​2. Version Checking

​3. Update Detection

​4. File Updates

​5. PR Creation

​Caching

​Permissions

​Read-only (no PR)

​With PR creation

​Triggers

​Scheduled Checks

​On Push

​Manual Dispatch

​Skip Checks

​Best Practices

​Troubleshooting

​No updates detected

​PR creation fails

​Cache issues

​Related

Build docs developers (and LLMs) love