Automating Composer Updates with Source Operations on Upsun

Jared Wright

Updated March 20, 2026 22:26

Overview

Source Operations on Upsun are a powerful feature that allows you to run write-enabled commands against your application's source code. Unlike standard hooks (build/deploy), which run in a read-only file system, Source Operations can commit changes directly back to your Git repository.

A common use case is automating dependency updates. This article details how to configure a Source Operation to run composer update, commit the updated composer.lock, and automate the process via a Cron job.

1. Prerequisites

To manage Source Operations effectively, ensure you have the following:

The Upsun CLI installed locally.
An API Token: Required for the environment to authenticate "as itself" when committing code.
A dedicated environment: It is highly recommended to run these updates on a development or "staging" branch rather than main.

2. Step 1: Create an API Token Variable

To allow the Source Operation to commit changes, Upsun needs an API token.

Generate an API token in the Upsun Console under your User Settings.

Create a project-level variable for this token using the CLI:

Bash

upsun variable:create -l project --name env:UPSUN_CLI_TOKEN --value "YOUR_TOKEN_HERE" --sensitive true --visible-runtime true --visible-build true

3. Step 2: Define the Source Operation

Add the source: operations block to your .upsun/config.yaml. This script performs the update, checks for changes, and commits them.

YAML

applications:
  myapp:
    # ... your existing config (type: php:8.x, etc.)
    
    source:
      operations:
        auto-update:
          command: |
            set -e
            # Ensure we are using the project's token for the CLI
            export PLATFORM_CLI_TOKEN=$UPSUN_CLI_TOKEN
            
            # Run the update
            composer update --no-interaction --no-progress --no-scripts
            
            # Stage changes
            git add composer.json composer.lock
            
            # Only commit if there are actual changes
            if ! git diff-index --quiet HEAD; then
              git commit -m "Automated dependency update: $(date +'%Y-%m-%d')"
            else
              echo "No updates available."
            fi

4. Step 3: Automate with Cron

To make this truly "hands-off," trigger the operation on a schedule. Add a crons section to your .upsun/config.yaml.

Best Practice: Use the upsun source-operation:run command within the cron to trigger the logic defined above.

YAML

applications:
  myapp:
    # ... 
    crons:
      weekly-update:
        # Run at 03:00 every Monday
        spec: "0 3 * * 1"
        commands:
          start: |
            # Only run this on the 'updates' environment to avoid production churn
            if [ "$UPSUN_BRANCH" = "updates" ]; then
              upsun source-operation:run auto-update
            fi

5. How it Works: The Source Operation Workflow

The following diagram illustrates the lifecycle of a Source Operation compared to a standard build.

Unlike the standard build process where the container is destroyed after the build, a Source Operation:

Unlocks the file system to allow Git operations.
Executes your script (e.g., updating composer.lock).
Persists changes by creating a new Git commit.
Triggers a new Build/Deploy cycle automatically because the code has changed.

6. Manual Execution

You can also trigger the update manually at any time via the CLI: