Skip to main content
The Check Version workflow automatically monitors upstream repositories for new releases and creates pull requests when updates are detected.

​
Workflow Configuration

​
Triggers

The workflow runs in three scenarios: 
schedule:
  - cron: '0 */2 * * *'  # Every 2 hours
The workflow skips execution if the commit message contains [skip check]

​
Workflow Inputs

​
context
string
default:"all"
Specifies which app context to check. Use all to check all apps, or specify a specific path like apps/icones.Available contexts include:
  • Apps: apps/cobalt, apps/icones, apps/readest, etc.
  • Base images: base/alpine, base/nginx, base/vscode
  • Test contexts: test/icones, test/weektodo
​
create_pr
string
default:"false"
Controls pull request creation behavior:
  • 'true' - Create PR to master branch
  • 'false' - Only check versions, don’t create PR
  • 'development' - Create PR to development branch
​
debug
boolean
default:"false"
Enable debug mode for verbose logging and troubleshooting.

​
Job Steps

​
1. Checkout Repository

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history for git operations
Clones the repository with complete history to enable git operations.

​
2. Cache Git Repositories

- name: Cache Git repositories
  uses: actions/cache@v4
  with:
    path: .git-cache
    key: git-repos-${{ hashFiles('**/meta.json') }}
    restore-keys: |
      git-repos-
Caches cloned upstream repositories in .git-cache to:
  • Speed up subsequent version checks
  • Reduce network bandwidth
  • Improve workflow execution time
The cache key is based on meta.json files, so cache invalidates when metadata changes.

​
3. Execute Version Check

- 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 }}
Runs the custom check-version action defined in /action/check-version/action.yml.

​
Check Version Action

The action is implemented in TypeScript and performs the following operations:

​
Action Inputs

​
token
string
Personal Access Token (PAT) for repository access. Required when creating pull requests.
​
context
string
Context directory to check (e.g., apps/icones). If not specified, checks all contexts.
​
create_pr
string
default:"false"
Controls PR creation: 'true', 'false', or 'development'
​
debug
string
default:"false"
Enable debug logging

​
Execution Flow

The action follows this workflow (from action/src/check.ts:16-77):
1

Initialize Apps Manager

const appsManager = new CheckAppsManager()
Creates manager instance to handle app lifecycle
2

Scan Applications

const appPaths = await appsManager.scanApps()
if (!appPaths?.length) {
  logger.warn('No applications found to process')
  return
}
Discovers all apps based on context input
3

Load App Contexts

await appsManager.loadApps(appPaths)
Loads metadata and configuration for each app
4

Check Versions

const { allApps, outdatedApps } = await appsManager.checkAllVersions()
Compares current versions with upstream releases
5

Build PR Data

if (config.createPr || isAct) {
  const prResults = await appsManager.buildPrDatas(outdatedApps)
  await logger.json(prResults, 'PR Datas')
}
Generates pull request data for outdated apps
6

Create Pull Requests

if (config.createPr) {
  const createPrResults = await appsManager.createPr(prResults)
  await logger.json(createPrResults, 'Create PR Results')
}
Creates PRs if enabled
7

Generate Summary

appsManager.generateSummary(outdatedApps, allApps, createPrResults)
core.summary.write()
Outputs summary to GitHub Actions UI

​
Version Check Logic

The version checking process:
  1. Read meta.json: Parses app metadata containing upstream repository info
  2. Clone Upstream: Clones or updates cached upstream repository
  3. Fetch Tags: Retrieves latest tags from upstream
  4. Compare Versions: Compares current version with latest upstream version
  5. Detect Updates: Identifies apps with newer versions available

​
Pull Request Creation

When create_pr is enabled: 
// create_pr: 'true'
// Creates PR to master branch
{
  base: 'master',
  head: 'update-{app-name}-{version}',
  title: 'Update {app-name} to {version}'
}

​
Output Examples

​
All Up to Date

🎉 All apps are up to date, no updates needed
When all apps are current, the workflow completes without creating PRs

​
Updates Found

Total 15 apps checked, 3 apps needs update
The summary includes:
  • Total apps checked
  • Number of outdated apps
  • List of apps with available updates
  • Version differences
  • PR creation results (if enabled)

​
Permissions Required

permissions:
  contents: read
For PR creation, ensure PAT secret has:
  • repo scope for private repositories
  • public_repo scope for public repositories
  • pull_request write access

​
Skip Version Check

To skip the version check on a specific commit: 
git commit -m "Update configuration [skip check]"
The workflow checks for [skip check] in commit messages: 
if: |
  github.event_name == 'workflow_dispatch' || 
  github.event_name == 'schedule' || 
  (github.event_name == 'push' && 
   github.event.head_commit && 
   !contains(github.event.head_commit.message, '[skip check]'))

​
Caching Strategy

The Git cache significantly improves performance: 
path: .git-cache
key: git-repos-${{ hashFiles('**/meta.json') }}
restore-keys: |
  git-repos-
Cache Benefits:
  • Reduces clone time for upstream repositories
  • Minimizes network usage
  • Speeds up subsequent checks
Cache Invalidation:
  • Cache updates when any meta.json file changes
  • Falls back to partial match with git-repos- prefix

​
Troubleshooting

​
Enable Debug Mode

For verbose logging:
  1. Manual trigger: Set debug input to true
  2. Check action logs for detailed information
  3. Review JSON output for app data and PR results

​
Common Issues

Cause: Invalid context path or no apps in specified directorySolution: Verify context path matches directory structure (e.g., apps/icones, not icones)
Cause: Missing or invalid PAT tokenSolution:
  • Ensure PAT secret is configured
  • Verify token has required permissions
  • Check token hasn’t expired
Cause: Upstream repository is large or network is slowSolution:
  • Wait for cache to populate
  • Check upstream repository availability
  • Consider increasing workflow timeout

Build Image

Triggered after PR merge to build updated images

All Workflows

View complete workflow overview

Build docs developers (and LLMs) love

Get started for freeTalk to us