Skip to content

Opening a pull request

(for contributors)

To add software to EESSI, you should go through the semi-automatic software installation procedure by:

  • 1) Making a pull request to the software-layer repository to (add or) update an easystack file 📚 that is used by EasyBuild to install software;
  • 2) Instructing the bot 🤖 to build the software on all supported CPU microarchitectures;
  • 3) Instructing the bot 🤖 to deploy the built software for ingestion into the EESSI repository;
  • 4) Merging the pull request once CI indicates that the software has been ingested. ✅


Make sure you are also aware of our contribution policy when adding software to EESSI.


Before you can make a pull request to the software-layer, you should fork the repository in your GitHub account.

For the remainder of these instructions, we assume that your GitHub account is @koala 🐨.


Don't forget to replace koala 🐨 with the name of your GitHub account in the commands below!

1) Clone the EESSI/software-layer repository:

mkdir EESSI
git clone
cd software-layer

2) Add your fork 🐨 as a remote

git remote add koala

3) Check out the branch that corresponds to the version of EESSI repository you want to add software to, for example

git checkout


The commands above only need to be run once, to prepare your setup for making pull requests.

Creating a pull request

1) Make sure that your branch in the checkout of the EESSI/software-layer repository is up-to-date

cd EESSI/software-layer
git checkout 
git pull origin 

2) Create a new branch (use a sensible name, not example_branch as below), and check it out

git checkout -b example_branch

3) Determine the correct easystack file to change, and add one or more lines to it that specify which easyconfigs should be installed

echo '  - example-1.2.3-GCC-12.3.0.eb' >> easystacks/
Note that the naming scheme is standardized and should be eessi-<eessi_version>-eb-<eb_version>-<toolchain_version>.yml. See the official EasyBuild documentation on easystack files for more information on the syntax.

4) Stage and commit the changes into your your branch with a sensible message

git add easystacks/
git commit -m "{2023.06}[GCC/12.3.0] example 1.2.3"

5) Push your branch to your fork 🐨 of the software-layer repository

git push koala example_branch

6) Go to the GitHub web interface to open your pull request, or use the helpful link that should show up in the output of the git push command.

Make sure you target the correct branch: the one that corresponds to the version of EESSI you want to add software to (like

If all goes well, one or more bots 🤖 should almost instantly create a comment in your pull request with an overview of how it is configured - you will need this information when providing build instructions.

Rebuilding software

We typically do not rebuild software, since (strictly speaking) this breaks reproducibility for anyone using the software. However, there are certain situations in which it is difficult or impossible to avoid.

To do a rebuild, you add the software you want to rebuild to a dedicated easystack file in the rebuilds directory. Use the following naming convention: YYYYMMDD-eb-<EB_VERSION>-<APPLICATION_NAME>-<APPLICATION_VERSION>-<SHORT_DESCRIPTION>.yml, where YYYYMMDD is the opening date of your PR. E.g. 2024.05.06-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml was added in a PR on the 6th of May 2024 and used to rebuild CUDA-12.1.1 using EasyBuild 4.9.1 to resolve an issue with some runtime libraries missing from the initial CUDA 12.1.1 installation.

At the top of your easystack file, please use comments to include a short description, and make sure to include any relevant links to related issues (e.g. from the GitHub repositories of EESSI, EasyBuild, or the software you are rebuilding).

As an example, consider the full easystack file (2024.05.06-eb-4.9.1-CUDA-12.1.1-ship-full-runtime.yml) used for the aforementioned CUDA rebuild:

# 2024.05.06
# Original matching of files we could ship was not done correctly. We were
# matching the basename for files (e.g., from
# rather than the name stub (libcudart)
# See
  - CUDA-12.1.1.eb:
                accept-eula-for: CUDA

By separating rebuilds in dedicated files, we still maintain a complete software bill of materials: it is transparent what got rebuilt, for which reason, and when.