Create a release

Ship a new version of an app already in the SEPAL catalog

Once your app is in the catalog (see Request a new app), the way you ship a new version depends on the app’s endpoint (see Docker vs. Jupyter apps):

• Jupyter apps (and kernels, which are just hidden jupyter apps) are not pinned to a commit. The app-manager checks out the tip of the catalog’s branch (defaulting to HEAD) every time the sandbox refreshes the app, so a release is just a push to that branch in your source repository — no catalog change is needed.

• Docker apps are pinned in the catalog to an exact commit SHA. SEPAL keeps running the old commit until that commit field is advanced, so a release is, in practice, a pull request against the catalog.

The rest of this page describes each flow in turn.

Jupyter and kernel apps

These endpoints don’t take a commit field in the catalog — only branch (which defaults to HEAD). On every sandbox refresh the app-manager runs the equivalent of git fetch + checkout of that branch’s tip, so whatever is at the head of the tracked branch is what users get.

Releasing a new version

Push the change to the branch the catalog tracks for your app. The next time the user’s sandbox refreshes the app, the new tip is picked up automatically. No catalog PR is required.

The release branch convention

Because every push to the tracked branch is effectively a release, most contributors keep a dedicated release branch and pin "branch": "release" in the catalog rather than main. You develop on main and merge into release only when you intend to publish — that way unreviewed work on main doesn’t go live the moment it is pushed.

This is a convention, not a requirement. Any branch works; if you pin main, every push to main is a release.

Docker apps

Docker apps carry a required commit SHA in the catalog. The app-launcher runs git fetch origin <branch> followed by git checkout --detach <commit>, so SEPAL only ever runs that exact commit — regardless of what is at the tip of branch. Shipping a new version therefore means advancing the commit field in the catalog.

There are two ways to do that: a manual pull request, or an automated bump triggered when your source repository publishes a release.

The release branch convention

Many docker apps pin "branch": "release" rather than main. Since the catalog validation requires the pinned commit to be reachable from branch, keeping a dedicated release branch lets you continue developing on main while controlling exactly which commits are eligible to be pinned: you merge into release only when you intend to publish, and that merge commit is the one you pin.

This is a convention, not a requirement — any branch works as long as the pinned commit is reachable from it.

Manual release

1. Push the code you want to ship and note the commit SHA on your release branch.

2. Open a PR against apps.test.json changing the commit field of your app’s entry (and branch if it moved).

3. The Review helper bot posts a compare link showing exactly what changed upstream between the old and new commit, with risk flags. A maintainer reviews and merges; the change goes live on test.sepal.io.

4. Promote to sepal.io with a second PR against apps.prod.json (or the Promote app to production workflow).

Astuce

Validation requires the new commit to be an ancestor of (or equal to) the branch tip — exactly what the app-launcher needs, since it runs git fetch origin <branch> then git checkout --detach <commit>. You can spot-check this before opening the PR:

gh api repos/<owner>/<repo>/compare/<branch>...<commit> --jq '.ahead_by'
# must print 0

Automated release from your source repo

The catalog can bump a docker app automatically when your repository publishes a GitHub release. The catalog’s update-from-release.yml workflow listens for a repository_dispatch event of type bump-app; on receipt it updates the app’s commit in apps.test.json and opens a pull request for a maintainer to review.

To wire this up, add a workflow to your app’s repository that sends the dispatch on release. The snippet below is a starting point — adjust the app id and the catalog repository to match your setup:

# .github/workflows/notify-sepal-catalog.yml in your app repo
name: Notify SEPAL catalog
on:
  release:
    types: [published]

jobs:
  bump:
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch bump-app to the catalog
        run: |
          gh api repos/dfguerrerom/sepal-apps-catalog/dispatches \
            -f event_type=bump-app \
            -F client_payload[id]="my-app" \
            -F client_payload[commit]="${GITHUB_SHA}"
        env:
          GH_TOKEN: ${{ secrets.SEPAL_CATALOG_DISPATCH_TOKEN }}

The token must have permission to dispatch to the catalog repository. The bump only updates commit — never branch — and still goes through the normal validation, risk-flag review, and maintainer merge before reaching test.

Note

The exact client_payload fields the catalog expects may evolve. Confirm against the catalog’s update-from-release.yml and docs/ci.md before relying on this in production.

Voir aussi

The end-to-end lifecycle diagram lives on the section landing page — Develop apps.