Using custom apps

Using custom apps#

To add custom apps to your Yaku configuration, you need to perform two steps:

First, you need to define an app repository in which the app is stored.
Then, you must add the app to your autopilot definition.

If you want to see a working custom app example using Github, please jump to the example config below.

Defining a repository#

Open the qg-config.yaml file of your Yaku configuration in the Web UI or in your favorite text editor.

Add a new section called repositories.

metadata:
  version: v1
header:
  name: My first QG config
  version: 1.0
repositories:
  - name: <repository-name>
    type: <repository-type>
    configuration:
      <repository-configuration>

Configure the repository with one of the available repository types. In the example below, a repository URL is given. This URL contains placeholders for name and version. How those placeholders are filled is described in the next paragraph.

metadata:
  version: v1
header:
  name: My first QG config
  version: 1.0
repositories:
  - name: my-repository
    type: curl
    configuration:
      url:  https://example.com/folder-with-apps/{name}/{version}

Adding the app to the autopilot definition#

After you have defined the repository for the custom app, you can now reference your custom app in your autopilot. Find your autopilot definition in your config file (introduced by the autopilots: section) and follow the next steps.

Add a new section called apps to the autopilot configuration and list the custom app you want to use.
```
autopilots:
  app-version-usage:
    apps:
      - <app-name>@<version>
```
Note

If you have multiple repositories configured, you can explicitly mention the repository from which you want to download the app. Simply replace <app-name>[@<version>] by <repository-name>::<app-name>[@<version>].

If the repository name is not provided, all repositories will be searched for the app. If the app is available in multiple repositories you must provide the repository name.
Use the custom app in the run section of the autopilot configuration.
```
autopilots:
  app-name-usage:
    apps:
      - <app-name>@<version>
    run: |
      <app-name> --help
```
Hint

If you have specified two different versions of the same app inside the apps: section, you can call the different versions of the app by appending ...@<version> to the <app-name> call in the run: section.
Save the changes to the qg-config.yaml file and run the Yaku configuration

Custom app example using GitHub#

You can find a sample workflow config file below. It downloads a specific version of jq. Simply copy and paste this file into a new configuration and press the Play button to execute the configuration.

Note

The workflow will fail with an error status because the autopilot does not return a complete check result. That’s ok, you can ignore this. Simply take a look at the log output of the autopilot to see the command line output of the jq --version command.

There are two versions listed in the apps: section: version 1.6 and version 1.7.1. One of them is commented out; if you want, you can simply uncomment it and comment out the other version to see how the command line output changes.

Example config for downloading and using a custom app#

metadata:
  version: v1
header:
  name: My first QG config
  version: 1.0.0
repositories:
  - name: github-jq-downloads
    type: curl
    configuration:
      url: https://github.com/jqlang/{name}/releases/download/{name}-{version}/{name}-linux64
autopilots:
  my-custom-jq:
    apps:
      #- github-jq-downloads::jq@1.7.1
      - github-jq-downloads::jq@1.6
    run: |
      jq --version
chapters:
  '1':
    title: Test custom apps
    requirements:
      '1':
        title: Verify that specific version of jq can be downloaded and used
        text: Long description
        checks:
          '1':
            title: 'Description of the check'
            automation:
              autopilot: my-custom-jq

Dealing with errors in the configuration#

The configuration of repositories and custom apps is read after you start a new Yaku run. If there is an error in your configuration, e.g., if an app is not available or if a repo URL is incorrect, you will only get feedback after the run was completed. Check the log output of your run for error messages.