Skip to content

GitHub Action Usage

Use uptool as a GitHub Action to automate dependency updates.

Quick Start

# .github/workflows/uptool.yml
name: Dependency Updates

on:
  schedule:
    - cron: '0 9 * * 1'  # Monday at 9 AM UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: santosr2/uptool@v0  # Latest stable (recommended)
        with:
          command: update
          create-pr: 'true'
          token: ${{ secrets.GITHUB_TOKEN }}

Version pinning:

  • @v0 - Latest stable (auto-updates)
  • @v0.1 - Latest patch
  • @v0.1.0 - Exact version (most secure)

Common Patterns

Scan Only (No Updates)

- uses: santosr2/uptool@v0
  with:
    command: scan
    format: json

Dry-Run Before Applying

- uses: santosr2/uptool@v0
  with:
    command: update
    dry-run: 'true'

Integration-Specific Updates

- uses: santosr2/uptool@v0
  with:
    command: update
    only: npm,helm
    create-pr: 'true'

Monorepo Pattern

strategy:
  matrix:
    package: [api, web, worker]
steps:
  - uses: santosr2/uptool@v0
    with:
      working-directory: packages/${{ matrix.package }}
      command: update

Auto-Merge Patch Updates

- uses: santosr2/uptool@v0
  with:
    command: update
    create-pr: 'true'
    pr-auto-merge: 'true'  # Only for patch updates

Inputs

Input Required Default Description
command Yes - Command: scan, plan, or update
create-pr No false Create pull request
token No ${{ github.token }} GitHub token
only No - Comma-separated integrations
exclude No - Exclude integrations
dry-run No false Preview without applying
format No table Output format: table or json
pr-title No chore(deps): update dependencies PR title
pr-branch No uptool/updates PR branch name
pr-auto-merge No false Auto-merge PR
working-directory No . Working directory

Outputs

Output Description
updates-available true if updates found
manifests-count Number of manifests detected
updates-count Number of updates available
pr-number Created PR number (if applicable)
pr-url Created PR URL (if applicable)

Usage:

- uses: santosr2/uptool@v0
  id: uptool
  with:
    command: scan

- name: Check results
  if: steps.uptool.outputs.updates-available == 'true'
  run: echo "Found ${{ steps.uptool.outputs.updates-count }} updates"

Permissions

Minimum required:

permissions:
  contents: write          # To commit changes
  pull-requests: write     # To create PRs

For auto-merge:

permissions:
  contents: write
  pull-requests: write
  checks: read             # To verify checks pass

Advanced Patterns

Skip CI on Update PRs

- uses: santosr2/uptool@v0
  with:
    pr-title: 'chore(deps): update dependencies [skip ci]'

Notify on Failures

- uses: santosr2/uptool@v0
  continue-on-error: true
  id: uptool

- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "uptool failed: ${{ steps.uptool.outputs.error }}"
      }

Custom PR Body

- uses: santosr2/uptool@v0
  with:
    pr-body: |
      ## Automated Dependency Updates

      This PR updates dependencies to their latest compatible versions.

      **Generated by**: uptool
      **Schedule**: Weekly on Monday

Matrix Strategy for Environments

strategy:
  matrix:
    env: [staging, production]
steps:
  - uses: santosr2/uptool@v0
    with:
      command: update
      working-directory: environments/${{ matrix.env }}
      pr-branch: uptool/updates-${{ matrix.env }}

Troubleshooting

PR Not Created

Check:

  • Permissions include contents: write and pull-requests: write
  • Token has repo access
  • No existing PR with same branch name

No Updates Found

Check:

  • Manifest files exist in repository
  • Integration enabled in uptool.yaml
  • Run with dry-run: 'true' to see debug output

Authentication Errors

For private packages:

- name: Setup npm auth
  run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc

- uses: santosr2/uptool@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Action Times Out

Increase timeout:

- uses: santosr2/uptool@v0
  timeout-minutes: 15  # Default is 360

Best Practices

  1. Use semantic versioning: Pin to @v0 for auto-updates
  2. Run on schedule: Weekly or daily, avoid high-traffic times
  3. Enable manual trigger: Add workflow_dispatch for testing
  4. Test in staging first: Use matrix strategy for environments
  5. Review PRs: Don't blindly auto-merge major updates
  6. Set PR labels: Use pr-labels: 'dependencies,automated'
  7. Configure branch protection: Require reviews for major updates

Examples

See .github/workflows/ for working examples:

  • dependency-updates.yml - Weekly automated updates
  • dependency-scan.yml - PR scan checks

See Also