{"id":22599600,"url":"https://github.com/singularityhub/github-ci","last_synced_at":"2025-04-15T11:54:48.313Z","repository":{"id":43705179,"uuid":"202604747","full_name":"singularityhub/github-ci","owner":"singularityhub","description":"An example GitHub Action (CI) to build a Singularity container","archived":false,"fork":false,"pushed_at":"2023-06-07T13:19:40.000Z","size":71,"stargazers_count":69,"open_issues_count":3,"forks_count":28,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T19:50:06.101Z","etag":null,"topics":["container","github-ci","singularity","singularity-ci"],"latest_commit_sha":null,"homepage":"","language":"Singularity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/singularityhub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-15T20:08:23.000Z","updated_at":"2025-02-28T11:00:54.000Z","dependencies_parsed_at":"2025-03-28T19:47:15.398Z","dependency_job_id":"898914ba-3d7e-4e7f-aeac-ce8a7ab0b75b","html_url":"https://github.com/singularityhub/github-ci","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fgithub-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fgithub-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fgithub-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fgithub-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/singularityhub","download_url":"https://codeload.github.com/singularityhub/github-ci/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067774,"owners_count":21207395,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","github-ci","singularity","singularity-ci"],"created_at":"2024-12-08T11:10:38.658Z","updated_at":"2025-04-15T11:54:48.279Z","avatar_url":"https://github.com/singularityhub.png","language":"Singularity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Singularity Builder GitHub CI\n\n![img/sregistry-github-small.png](img/sregistry-github-small.png)\n\nThis is a simple example of how you can achieve:\n\n - version control of your recipes\n - build of associated container and\n - push to a storage endpoint\n\nfor a reproducible build workflow! By default, we will build on all pull requests and deploy\non push to main. The containers will go to an enabled GitHub package registry thanks to\nthe Singularity oras endpoint.\n\n**updated** August 2021, we can now push containers to the GitHub package registry! Woohoo!\n\nThere are three workflows configured as examples to build and deploy Singularity containers:\n\n1. [native install](.github/workflows/native-install.yml) discovers Singularity* changed files, and builds Singularity 3.x (with GoLang) natively, deploys to GitHub packages.\n2. [docker image](.github/workflows/container.yml) discovers Singularity* changed files, and builds in a [docker image](https://quay.io/repository/singularity/singularity), also deploys to GitHub packages.\n3. [manual deploy](.github/workflows/manual-deploy.yml) takes a list of manually specified Singularity recipes (that aren't required to be changed), builds Singularity 3.x natively, and deploys to GitHub packages.\n\nWhile the \"build in a container\" option is faster to complete and a more simple workflow, it should be noted that docker runs with\n`--privileged` which may lead to issues with the resulting container in a non privileged situation. Also note that you\nare free to mix and match the above recipes to your liking, or [open an issue](https://github.com/singularityhub/github-ci/issues) if you want to ask for help!\n\n**Why should this be managed via Github?**\n\nGithub, by way of easy integration with **native** continuous integration, is an easy way\nto have a workflow set up where multiple people can collaborate on a container recipe,\nthe recipe can be tested (with whatever testing you need), discussed in pull requests,\nand tested on merge to master. Further, now with GitHub packages we can push our containers\ndirectly to the GitHub package registry!\n\n**Why should I use this instead of a service?**\n\nYou could use a remote builder, but if you do the build in a continuous integration\nservice you get complete control over it. This means everything from the version of\nSingularity to use, to the tests that you run for your container. You have a lot more\nfreedom in the rate of building, and organization of your repository, because it's you\nthat writes the configuration.\n\n## Quick Start\n\n### 1. Enable Packages\n\nIf you want to use the [GitHub package registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)\nyou'll need to follow the instructions there to enable packages for your organization, specifically \"public\" and \"internal\" packages should be allowed to be created. You'll also want to add a username associated with your GitHub organization to the repository secret `GHCR_USERNAME`. If a package already exists for your repository, you may need to [follow instructions](https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-ghcrio) to update a package from using personal access tokens to the safer `GITHUB_TOKEN`. This means that:\n\n 1. If you want to be able to push to the package registry without extra work, don't push a container to the same package namespace that matches the repository before (e.g., from the command line).\n 2. If you have already pushed a container to the repository package namespace, or you want to test and don't mind making the manual changes, you will need to [follow these instructions](https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-ghcrio) to associate the package with your repository.\n\n### 2. Add Your Recipes\n\nAdd your Singularity recipes to this repository, which should be named `Singularity.\u003ctag\u003e` \nor just `Singularity` to follow the previously published convention. You can then choose your file in [.github/workflows](.github/workflows).\nIf you choose the `manual-deploy.yml` you can manually specify recipes in the matrix variable \"recipe.\"\nIf you choose either of the other two workflows, changed files that start with Singularity.* will\nbe automatically detected and built.\n\n### 3. Test your Container\n\nImportantly, we suggest that you add some steps to test your container! Whether that's running it,\nexec'ing a custom command, or invoking the test command, there is more than\none way to eat a reeses:\n\n```yaml\n    - name: Test Container\n      run: |\n        singularity exec smokey.sif python run_tests.py\n        singularity test smokey.sif\n        singularity run toasty.sif\n```\n\nThis step is not provided in the workflows, but it's recommended that you think about it and add if necessary.\n\n### 4. Check Triggers\n\nThe workflow files each have a section at the top that indicates when the workflow will\ntrigger. By default, we will do builds on pull requests, and deploys on pushes to a main\nbranch. If you want to change this logic, edit the top of the recipe files.\n\n### 5. Push to a registry\n\nIf you are good with GitHub packages, then you are good to go! Otherwise,\nif you want to push to other kinds of storage, you can install the [Singularity Registry Client](http://singularityhub.github.io/sregistry-cli) and push to your cloud storage of choice! You will want to add python and python-dev to the dependency\ninstall:\n\n```yaml\n    - name: Install Dependencies\n      run: |\n        sudo apt-get update \u0026\u0026 sudo apt-get install -y \\\n          build-essential \\\n          libssl-dev \\\n          uuid-dev \\\n          libgpgme11-dev \\\n          squashfs-tools \\\n          libseccomp-dev \\\n          pkg-config \\\n          python-dev python python3-pip\n```\n\nAnd then install and use sregistry client. Here are many examples:\n\n```yaml\n    - name: Deploy Container\n      run: |\n        sudo pip3 install sregistry\n        SREGISTRY_CLIENT=google-storage sregistry push --name username/reponame smokey.sif\n        SREGISTRY_CLIENT=s3 sregistry push --name username/reponame smokey.sif\n        SREGISTRY_CLIENT=registry sregistry push --name username/reponame smokey.sif\n        SREGISTRY_CLIENT=dropbox sregistry push --name username/reponame smokey.sif\n```\n\nSee the [clients page](https://singularityhub.github.io/sregistry-cli/clients) for all the options.\nIf you want to change the recipe triggers, see [here](https://help.github.com/en/articles/about-github-actions#core-concepts-for-github-actions)\nfor getting started with GitHub actions, and [please open an issue](https://www.github.com/singularityhub/github-ci/issues)\nif you need any help.\n\n### 6. Pull Your Container!\n\nThe example container here is published to [singularithub/github-ci](https://github.com/singularityhub/github-ci/pkgs/container/github-ci)\nand can be pulled as follows:\n\n```bash\n$ singularity pull oras://ghcr.io/singularityhub/github-ci:latest\nINFO:    Downloading oras image\n$ ls\ngithub-ci_latest.sif  img  README.md  Singularity\n\n$ ./github-ci_latest.sif \nHold me closer... tiny container :) :D\n```\n\n## Other Options\n\nYou can customize this base recipe in so many ways! For example:\n\n - If you want to build a Docker container and pull down to Singularity, that's a good approach too! We have a [container-builder-template](https://github.com/autamus/container-builder-template) to help you authenticate with several popular registries.\n - The action matrix can be extended to run builds on multiple platforms.\n - You can also do the same, but test multiple versions of Singularity.\n\nHave fun!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fgithub-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsingularityhub%2Fgithub-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fgithub-ci/lists"}