Powered by Platform.sh
upsun.com platform.sh blackfire.io Discord Status Support
Articles
Up(sun) and ready with GitHub release assets installation

Up(sun) and ready with GitHub release assets installation

April 10, 2025· Florent Huck
Florent Huck
·Reading time: 4 minutes

One of my colleagues recently asked me how to install yq on his Upsun project, and after some searching, I discovered that the library can be easily installed from a GitHub repository.

This whole process made me realize that I didn’t really explain how this github-install-asset.sh shell script works in my previous blogpost about how to install Pandoc on Upsun. So, this is it.

In this guide, you will learn how to install any binary from a GitHub release into your Upsun project using this script. I’ve chosen yq as an example here, but feel free to test the process using your own favorite GitHub repository.

Assumptions:

  • You already have an Upsun account. If you don’t, please register for a trial account. You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
  • You already have an Upsun project live and ready on local. If you don’t, please follow this blogpost first to install a Symfony Demo on Upsun.
  • You have the Upsun CLI installed locally.

Create a new environment

As we never test things directly on production, we first need to create a new preview environment in order to test before going live.

To create a new environment, execute the following from the root of your source code.

Terminal
upsun branch install-yq

Call github-install-asset.sh in your hooks.build

As your application container is writable only during the hooks.build phase, you can install any additional packages you need. Using this github-install-asset.sh script allows you to install any chosen GitHub release asset you want.

In this guide we’re using yq as an example, so you can update your .upsun/config.yaml file with the following:

.upsun/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

applications:
  app:
    #.. 
    hooks:
      build: |
        set -x -e
        #...
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "mikefarah/yq"        
      deploy: |
        set -x -e
        #..
        yq -v

This generic install-github-asset.sh script can take 3 parameters:

curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "<org/repo>" ["<release_version>"] ["<asset_name>"]
  • <org/repo>: required, the GitHub organisation/repository where to find the asset
  • <release_version>: optional, get the latest release version if empty
  • <asset_name>: optional, if empty, we look for the first asset that contains linux + [amd64|arm64|x86] in its name.

🚨 Please note: In this blogpost, we’re using yq as an example, but this script also works with other GitHub release assets, like Pandoc or FrankenPHP:

.upsun/config.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

applications:
  app:
    #.. 
    hooks:
      build: |
        set -x -e
        #...
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "jgm/pandoc" "3.6.4"
        curl -fsS https://raw.githubusercontent.com/upsun/snippets/main/src/install-github-asset.sh | bash /dev/stdin "dunglas/frankenphp" "v1.5.0" "frankenphp-linux-x86_64-gnu"        
      deploy: | 
        set -x -e
        #..
        pandoc -v
        frankenphp -v

Now commit your change:

Terminal
git add . && git commit -m "adding yq installation and/or pandoc + frankenphp"
upsun push

Any tool installed via this install-github-asset.sh script will be available globally (installed in the /app/.global/bin folder) and you will be able to call it using the repo name:

upsun ssh 
yq -v
pandoc -v
frankenphp -v

Install from private GitHub repository

If you’re trying to install a GitHub release asset from a private repository, you’ll likely encounter an error like the one below in your deployment logs:

Terminal
>> Install <org/repo> GitHub asset.
On an Upsun/Platform.sh environment.
❌ Repository not accessible (404).
💡 It might be a private repository. Please set a valid GITHUB_API_TOKEN environment variable.

This is the excepted result, as the GitHub API returns a 404 HTTP response when access is denied. At this point, you’re still an anonymous GitHub user making the API request.

To fix this, you need to use a GitHub API Token, with at least the repo read access.

To access private GitHub repositories, you will need to define a GITHUB_API_TOKEN environment variable in your Upsun project. Our install-github-asset.sh will automatically use this GITHUB_API_TOKEN envVar and install any corresponding private release assets.

To define an environment variable in your project, use the Console or the following ‘variable:create’ command line:

Terminal
upsun variable:create env:GITHUB_API_TOKEN --value=ghp_[...] --sensitive=true --visible-build=true

and then redeploy your environment:

Terminal
upsun redeploy

Conclusion

Et voilà, you’re now in control and can easily install any GitHub release asset you want in your Upsun project.

Stay tuned.

Last updated on