Publish your AiiDAlab app#

Here we explain how an app can be made available to AiiDAlab users by registering it on the AiiDAlab registry.

Prepare the app for registration


If the app was created with the app cookiecutter it should already have all necessary information and this step can be skipped.

In preparation of registering your AiiDAlab app in the AiiDAlab registry, ensure you have a valid and updated setup.cfg file in the root of your app’s repository. The setup.cfg file can alternatively also be placed within a hidden .aiidalab/ directory in which case it will be parsed with precedence.

AiiDAlab parses the setup.cfg file for metadata and will recognize fields both from the standard [metadata] section and a dedicated [aiidalab] section (fields declared within the [aiidalab] section take precedence). We suggest using the [aiidalab] section only for the title and categories fields, and the [metadata] for all others.


Use the aiidalab registry parse-app-repo command to test what metadata would be parsed from your app repository.

Example: aiidalab registry parse-app-repo ~/apps/my-app.

Register the app

The app registry uses a pull approach, meaning it regularly scans the registered app repositories for new releases. 6 This is to simplify the release procedure for app developers. For example, typically an app developer will register an app such that newly created tags on a dedicated git branch are automatically released to users.

To register an app, simply edit the apps.yaml file on GitHub by clicking on the icon in the top right corner and add an entry for your app according to one of the approaches shown below.

Releases are specified in the form of a list, where each list entry corresponds to one or more tagged commits of a git repository branch. In case that it corresponds to multiple commits, the release entry is called a release line.

The simplest approach to release new app versions, is to register the app once and then push new releases by creating tagged commits on a specific branch, e.g., the main branch, or `*` to get tags from all branches.

    - "git+"
    - "git+*:v1.0.0.."

where you replace the URL shown here with the one applicable for your app.


You can use the standard git revision selection syntax to further reduce the selected commits on a release line. For example, @main:v1.0.0.. means “select all tagged commits on the main branch after commit tagged with v1.0.0”. See the “Other” tab for details and more examples.

Instead of automatically releasing every tagged commit, you can also specify dedicated commmits instead.

  - "git+"
  - "git+"

Use this approach if you want more control over which versions of your app are installable through the app store.

The formal definition of the release URL is:

release-url  ::=  app-repository-url + [ "@" ( release | release-line ) ]
release      ::=  ( git-tag | git-commit-sha )
release-line ::=  branch + ":" + [ revision-selection ]

where the app-repository-url should point to a git repository and use the URL scheme git+https://. The optional revision-selection follows the standard git revision selection syntax and can be used to specify a tag range and thus, e.g., exclude early tagged commits, as opposed to releasing all tagged commits.


As opposed to an approach where users push new releases to the registry.

Review your app on the app store!

Once submmited, your pull request will be reviewed by the AiiDAlab registry maintainers. After it is accepted and merged it typically takes 15-30 minutes for your app (and new releases) to appear in the AiiDAlab app store.

Go to AiiDAlab app registry

You can also test whether your app is listed on the registry by either opening the app store in AiiDAlab or running the following command:

$ aiidalab search my-app

and install it with

$ aiidalab install my-app