> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Source operations
> Run automated code updates via source operations.
export const DynamicCodeBlock = ({language = 'yaml', filename, icon, lines, wrap, expandable, highlight, focus, children}) => {
const STORAGE_KEY = 'upsun_versions_cache';
const COMPOSABLE_STORAGE_KEY = 'upsun_composable_cache';
const CACHE_TTL = 5 * 60 * 1000;
const API_URL = 'https://meta.upsun.com/images';
const COMPOSABLE_API_URL = 'https://meta.upsun.com/composable';
const DEBUG_PREFIX = '[DynamicCodeBlock cache]';
const [versionData, setVersionData] = useState(null);
const [versionError, setVersionError] = useState(false);
const [composableData, setComposableData] = useState(null);
const [composableError, setComposableError] = useState(false);
useEffect(() => {
const fetchData = async () => {
let cachedData = null;
let cachedEtag = null;
if (typeof localStorage !== 'undefined') {
try {
const cached = localStorage.getItem(STORAGE_KEY);
if (cached) {
const parsed = JSON.parse(cached);
cachedData = parsed?.data || null;
cachedEtag = parsed?.etag || null;
if (cachedData && Date.now() - parsed.timestamp < CACHE_TTL) {
return cachedData;
}
}
} catch (err) {
console.error('Failed to load from cache:', err);
}
}
const requestHeaders = cachedEtag ? {
'If-None-Match': cachedEtag
} : {};
console.debug(`${DEBUG_PREFIX} revalidating`, {
storageKey: STORAGE_KEY,
hasCachedData: Boolean(cachedData),
hasCachedEtag: Boolean(cachedEtag)
});
const response = await fetch(API_URL, {
headers: requestHeaders
});
if (response.status === 304 && cachedData) {
console.debug(`${DEBUG_PREFIX} revalidated (304)`, {
storageKey: STORAGE_KEY
});
if (typeof localStorage !== 'undefined') {
try {
const etag = response.headers.get('etag') || cachedEtag;
localStorage.setItem(STORAGE_KEY, JSON.stringify({
data: cachedData,
etag,
timestamp: Date.now()
}));
} catch (err) {
console.error('Failed to refresh cache metadata:', err);
}
}
return cachedData;
}
if (!response.ok) throw new Error(`API request failed: ${response.statusText}`);
const data = await response.json();
const etag = response.headers.get('etag');
console.debug(`${DEBUG_PREFIX} refreshed (200)`, {
storageKey: STORAGE_KEY,
etag
});
if (typeof localStorage !== 'undefined') {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify({
data,
etag,
timestamp: Date.now()
}));
} catch (err) {
console.error('Failed to cache data:', err);
}
}
return data;
};
fetchData().then(data => setVersionData(data)).catch(err => console.error('Failed to fetch version data:', err));
}, []);
const findHighestVersion = versionsMap => {
if (!versionsMap || Object.keys(versionsMap).length === 0) return null;
const entries = Object.entries(versionsMap);
const active = entries.filter(([, v]) => v.upsun && v.upsun.status === 'supported' || v.upsun && v.upsun.status === 'deprecated');
const candidates = active.length > 0 ? active : entries;
let [highestName] = candidates[0];
for (let i = 1; i < candidates.length; i++) {
const [currentName] = candidates[i];
const cp = currentName.split('.').map(Number);
const hp = highestName.split('.').map(Number);
for (let j = 0; j < Math.max(cp.length, hp.length); j++) {
if ((cp[j] || 0) > (hp[j] || 0)) {
highestName = currentName;
break;
} else if ((cp[j] || 0) < (hp[j] || 0)) {
break;
}
}
}
return highestName;
};
const getVersion = (lang, requestedVersion = 'latest') => {
if (lang === 'composable') {
if (!composableData || !composableData.versions || Object.keys(composableData.versions).length === 0) return null;
if (requestedVersion && requestedVersion !== 'latest') {
return (requestedVersion in composableData.versions) ? requestedVersion : null;
}
return findHighestVersion(composableData.versions);
}
if (!versionData) return null;
const imageData = versionData[lang];
if (!imageData || !imageData.versions || Object.keys(imageData.versions).length === 0) {
return null;
}
if (requestedVersion && requestedVersion !== 'latest') {
return (requestedVersion in imageData.versions) ? requestedVersion : null;
}
return findHighestVersion(imageData.versions);
};
let code = typeof children === 'string' ? children : String(children || '');
const codeLines = code.split('\n');
while (codeLines.length > 0 && codeLines[0].trim() === '') codeLines.shift();
while (codeLines.length > 0 && codeLines[codeLines.length - 1].trim() === '') codeLines.pop();
if (codeLines.length > 0) {
const indents = codeLines.filter(line => line.trim().length > 0).map(line => line.match(/^[ \t]*/)[0].length);
const minIndent = Math.min(...indents);
code = codeLines.map(line => line.slice(minIndent)).join('\n');
}
code = code.replace(/\{\{version:(.*?)\}\}/g, (match, params) => {
const parts = params.split(':');
const lang = parts[0];
const ver = parts[1] || 'latest';
const isComposable = lang === 'composable';
const hasError = isComposable ? composableError : versionError;
const dataReady = isComposable ? composableData !== null : versionData !== null;
if (hasError) return '(unavailable)';
if (dataReady) {
const resolvedVersion = getVersion(lang, ver);
return resolvedVersion || match;
}
return '...';
});
const codeBlockProps = {
language,
...filename && ({
filename
}),
...icon && ({
icon
}),
...lines !== undefined && ({
lines
}),
...wrap !== undefined && ({
wrap
}),
...expandable !== undefined && ({
expandable
}),
...highlight && ({
highlight
}),
...focus && ({
focus
})
};
return {code};
};
export const VariableBlock = ({name}) => {
return {name};
};
export const SettingsIcon = () => ;
export const MoreIcon = () => ;
On Upsun, you can run automated code updates through a feature called **source operations**.
Defined in your [app configuration](/docs/configure-apps), source operations let you specify commands
that can commit changes to your project's repository when called.
For example, you can set up a source operation to [automatically update your application dependencies](/docs/core-concepts/common-tasks/dependency-updates),
[update a site from an upstream repository](#update-a-site-from-an-upstream-repository-or-template),
or [revert to the last commit](#revert-to-the-last-commit) pushed to your Git repository.
To run your source operations, you can use the [Upsun CLI](/cli) or the [Console](https://console.upsun.com).
If you want to run your source operations and update your code automatically,
you can also define [cron jobs](/docs/configure-apps/image-properties/crons).
## How source operations work
When you trigger a source operation, the following happens in order:
1. The current environment HEAD commit is checked out in Git.
It doesn't have any remotes or tags defined in the project.
It only has the current environment branch.
2. Sequentially, for each app that has an operation bearing [the name](#define-a-source-operation)
of the triggered source operation in its configuration,
the operation command is run in the app container.
The container isn't part of the environment's runtime cluster
and doesn't require that the environment is running.
The environment has all of the variables normally available during the build phase.
These may be optionally overridden by the variables specified when the operation is run.
3. If any new commits were created, they're pushed to the repository and the normal build process is triggered.
If multiple apps in a single project both result in a new commit,
there are two distinct commits in the Git history but only a single new build process.
## Define a source operation
A source operation requires two things:
* A name that must be unique within the application.
The name is the key of the block defined under `source.operations` in your [app configuration](/docs/configure-apps/image-properties/source).
* A `command` that defines what's run when the operation is triggered.
The syntax is similar to the following:
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
:
command: `
}
For example, to update a file from a remote location, you could define an operation like this:
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
update-file:
command: |
set -e
curl -O https://example.com/myfile.txt
git add myfile.txt
git commit -m "Update remote file"`
}
The name of the source operation in this case is `update-file`.
For more possibilities, see other [source operation examples](#source-operation-examples).
## Run a source operation
1. Navigate to the environment where you want to run the operation.
2. Click **More**.
3. Click **Run source operation**.
4. Select the operation you want to run.
5. Optional: Add the [variables](#use-variables-in-your-source-operations) required by your source operation.
6. Click **Run**.
Run the following command:
```bash theme={null}
upsun source-operation:run
```
Replace `` with the name of your operation, such as `update-file` in the [example above](#define-a-source-operation).
After running a source operation,
to apply the changes to your local development environment run the `git pull` command.
Note that you can [cancel pending or running source operations](/docs/environments/cancel-activity).
## Use variables in your source operations
You can add [variables](/docs/development/variables) to the environment of the source operation.
Use the `env:` prefix to expose each of those variables as a Unix environment variable.
In this way, they're referenced by the source operation
and interpreted the same way as any other variable set in your project.
For example, you might want to have a `FILE` variable available with the value `example.txt`
to pass to a source operation similar to the following:
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
update-file:
command: |
set -e
curl -O https://example.com/$FILE
git add $FILE
git commit -m "Update remote file"`
}
Follow these steps to run the source operation:
```bash Using the CLI theme={null}
upsun source-operation:run update-file --variable env:FILE="example.txt"
```
1. Navigate to the environment where you want to run the operation.
2. Click **More**.
3. Click **Run source operation**.
4. Select the operation you want to run.
5. Under **Add/override variables**, put `FILE` as the **Variable name** and `example.txt` as the **Value**.
The variable is automatically prefixed with `env:`.
6. Click **Run**.
## Source integrations
If your project is using a [source integration](/docs/integrations/source),
any new commits resulting from a source operation are first pushed to your external Git repository.
Then the source integration pushes those commits to Upsun and redeploys the environment.
When using a source integration,
you can't run source operations on environments created from pull or merge requests created on the external repository.
If you try running a source operation on a non-supported environment, you see the following error:
```text {no-copy="true"} theme={null}
[ApiFeatureMissingException]
This project doesn't support source operations.
```
## Automated source operations using a cron job
You can use a cron to automatically run your source operations.
Note that it’s best not to run source operations on your production environment,
but rather on a dedicated environment where you can test changes.
Make sure you have the [Upsun CLI](/cli) installed
and [an API token](/cli/api-tokens#2-create-an-api-token)
so you can run a cron job in your app container.
1. Set your API token as a top-level environment variable:
Run the following command:
```bash theme={null}
upsun variable:create --environment main --level environment --prefix 'env' --name UPSUN_CLI_TOKEN --sensitive true --value 'YOUR_UPSUN_CLI_TOKEN' --inheritable false --visible-build true --json false --enabled true --visible-runtime true
```
1. Open the environment where you want to add the variable.
2. Click **Settings**.
3. Click **Variables**.
4. Click **+ Add variable**.
5. In the **Variable name** field, enter `env:UPSUN_CLI_TOKEN`.
6. In the **Value** field, enter your API token.
7. Make sure the **Available at runtime** and **Sensitive variable** options are selected.
8. Click **Add variable**.
Once you add the API token as an environment variable,
anyone with [SSH access](/docs/development/ssh) can read its value.
Make sure you carefully check your [user access on this project](/docs/administration/users#manage-project-users).
2. Add a build hook to your app configuration to install the CLI as part of the build process:
```yaml .upsun/config.yaml theme={null}
applications:
myapp:
hooks:
build: |
set -e
echo "Installing Upsun CLI"
curl -fsSL https://raw.githubusercontent.com/upsun/cli/main/installer.sh | bash
echo "Testing Upsun CLI"
upsun
```
3. Then, to configure a cron job to automatically run a source operation once a day,
use a configuration similar to the following:
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
update-file:
command: |
set -e
curl -O https://example.com/$FILE
git add $FILE
git commit -m "Update remote file"
crons:
update:
# Run the code below every day at midnight.
spec: '0 0 * * *'
commands:
start: |
set -e
upsun sync -e development code data --no-wait --yes
upsun source-operation:run update-file --no-wait --yes`
}
The example above synchronizes the `development` environment with its parent
and then runs the `update-file` source operation defined [previously](#define-a-source-operation).
## Source operation examples
### Update your application dependencies
You can set up a source operation and a cron job to [automate your dependency updates](/docs/core-concepts/common-tasks/dependency-updates).
### Update a site from an upstream repository or template
The following source operation syncronizes your branch with an upstream Git repository.
1. [Add a project-level variable](/docs/development/variables/set-variables#create-project-variables)
named `env:UPSTREAM_REMOTE` with the Git URL of the upstream repository.
That makes that repository available as a Unix environment variable in all environments,
including in the source operation's environment.
* Variable name: `env:UPSTREAM_REMOTE`
* Variable example value: `https://github.com/platformsh/platformsh-docs`
2. In your app configuration, define a source operation to fetch from that upstream repository:
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
upstream-update:
command: |
set -e
git remote add upstream $UPSTREAM_REMOTE
git fetch --all
git merge upstream/main`
}
3. Now every time you run the `upstream-update` operation on a given branch,
the branch fetches all changes from the upstream git repository
and then merges the latest changes from the default branch in the upstream repository.
If there’s a conflict merging from the upstream repository,
the source operation fails and doesn't update from the upstream repository.
Run the `upstream-update` operation on a preview environment rather than directly on Production.
### Revert to the last commit
The following source operation reverts the last commit pushed to the Git repository.
This can be useful if you didn't properly test the changes of another operation
and you need to quickly revert to the previous state.
{`
applications:
myapp:
type: nodejs:{{version:nodejs:latest}}
source:
root: "/"
operations:
revert:
command: |
git reset --hard HEAD~`
}
Now every time you run the `revert` operation on a given branch,
the operation reverts to the last commit pushed to that branch.
### Update Drupal Core
The following source operation uses Composer to update Drupal Core:
{`
applications:
myapp:
type: php:{{version:php:latest}}
source:
root: "/"
operations:
update-drupal-core:
command: |
set -e
composer update drupal/core --with-dependencies
git add composer.lock
git commit -m "Automated Drupal Core update."`
}
`--with-dependencies` is used to also update Drupal Core dependencies.
Read more on how to [update Drupal Core via Composer on Drupal.org](https://www.drupal.org/docs/updating-drupal/updating-drupal-core-via-composer).
Now every time you run the `update-drupal-core` operation, it updates Drupal Core.
### Download a Drupal extension
The following source operation downloads a Drupal extension.
You can define the Drupal extension by setting an `EXTENSION` variable
or [overriding it](#use-variables-in-your-source-operations) when running the source operation.
{`
applications:
myapp:
type: php:{{version:php:latest}}
source:
root: "/"
operations:
download-drupal-extension:
command: |
set -e
composer require $EXTENSION
git add composer.json
git commit -am "Automated install of: $EXTENSION via Composer."`
}
Now every time you run the `download-drupal-extension` operation, it downloads the defined extension.
If it's a new extension, after the source operation finishes,
you need to enable the new extension via the Drupal management interface or using Drush.
### Update Git submodules
The following source operation updates all Git submodules recursively:
{`
applications:
myapp:
type: php:{{version:php:latest}}
source:
root: "/"
operations:
rebuild:
command: |
set -e
git submodule update --init --recursive
git submodule update --remote --checkout
SHA=$(git submodule | awk -F' ' '{print $1}' | sed -s 's/+//g')
echo -n "$SHA" > .sha
git add uppler .sha
git commit -m "Updating submodule to commit '$SHA'"`
}
Now every time you run the `rebuild` operation, it updates the Git submodules.