Build / Release templates - specify inputs the user have to provide before starting the build

You could be able to specify “build templates” in the bitrise.yml, and then “build a template” both with CLI in local and on bitrise.io

“Build a template” would look like this: the inputs defined in the template have to be provided manually (in the CLI it’d ask for those in the Terminal/Command Line, on bitrise.io it’d present a popup with the inputs) then the build would run exactly the same as a normal build.

An example for a very minimal version number based release:

workflows:
  create-release:
    envs:
    - RELEASE_VERSION_NUMBER:
        opts:
          is_required: true
          title: "The version number for the release"
    steps: []

  publish-release:
    before_run:
    - create-release
    envs:
    - RELEASE_TYPE:
        opts:
          is_required: true
          title: "Type of release"
          value_options:
          - internal
          - external
    steps: []

If you’d run the create-release workflow you’d have to provide the RELEASE_VERSION_NUMBER input (via the UI on bitrise.io and via interactive input in the CLI), while if you’d run publish-release you’d have to provide both RELEASE_VERSION_NUMBER and RELEASE_TYPE, where RELEASE_TYPE would be a dropdown on the UI (the same how value_options are treated in Step inputs). If title is specified then that will be printed, otherwise the env var’s key (RELEASE_VERSION_NUMBER and RELEASE_TYPE in the example) will be printed.

Basically when triggering a workflow the system would go through the whole workflow-graph, collecting all is_required env vars from the specified workflow and every other workflow referenced via before_run and after_run (recursive) workflow chaining.

The input provided will be handled the exact same way if you’d specify this input (env var) in the App Env Vars, so it’ll be 100% compatible with the current tooling/steps/mechanisms.

So, if you have this template and you want to create a release, you’d simply bitrise run create-release or on bitrise.io select the template in the “Build Now” popup, fill out the required inputs (in this case “The version number for the release”) and then it’ll start a build with the specified workflow (create-release in the example), just like if you’d do /usr/bin/env RELEASE_VERSION_NUMBER="x.x.x" bitrise run create-release or specifying RELEASE_VERSION_NUMBER in .bitrise.secrets.yml and then bitrise run create-release.

Important technical note: recognize inputs provided via Secrets!

What’s the purpose?

  • A formalized dynamic input handling mechanism, both in the CLI and on bitrise.io, with validation that all required inputs are provided.
  • To make it easy to define e.g. Release workflows which do require manual input (e.g. a version number and a release notes inputs).
  • To be able to list required inputs of workflows and those be tested by the CLI instead of writing Script steps to validate that all required inputs were provided.

An example

You can define a workflow on bitrise.io / in bitrise.yml right now that can auto create everything for a release, but today you have two options to provide manual inputs (like a release note):

  1. Either require those inputs, doing custom checks with Script steps or similar, until the user provides it through e.g. bitrise secrets or as custom build env vars
  2. You bump the version number and write the changelog manually, and only after that you start a build which uses those

With “Build Templates” you could simply specify the required inputs, and a workflow which can do the release automatically for you. E.g. it’ll write the version number into a file in your project, and prepend your CHANGELOG file with the specified changelog text, then proceed with creating the release and publishing it.

In case of a Bitrise CLI release for example, where we do maintain manual version numbering and write manual changelogs, right now we have to:

  1. Bump the version number manually
  2. Write the changelog
  3. Commit & push
  4. Then once the release binaries are available create the GitHub release and upload there

With Build Templates we could specify the version number and the release notes as required inputs, and automate everything else:

  1. setting the version number
  2. creating the release binaries
  3. saving the changelog
  4. tagging the commit
  5. creating the github release
  6. specifying the changelog there
  7. and uploading the release binaries

The current checklist for a CLI release: https://github.com/bitrise-io/bitrise/pull/485/files

Which could be automated from the “Bump RELEASE_VERSION in bitrise.yml” point, simply by providing a Version Number and a Changelog input through the defined template

Technical notes:

  • The inputs could be defined for the CLI as parameters, in which case the CLI won’t ask for the inputs. E.g. the inputs could be specified before the bitrise run .. in .bitrise.secrets.yml, which will be loaded and processed
  • The CLI should not ask for inputs in CI mode, it should just fail if a required input is not provided
  • Q: what if the input is specified in App Env Vars? Should that be valid, or should the template overwrite those values? Basically, the dynamic inputs provided for the Template should be appended or prepended to the App Env Vars (or to the target workflow’s Workflow Env Vars)?

Separate Templates or build into Workflows?

It might be better to build it into Workflows, with Envs marked as Required.

That way you can compose a workflow chain, each one requiring its own set of params, and the CLI will simply parse through the whole chain.

Envs can have title, summary and description, so all the meta data are there, only a is required flag/handling is missing.

Providing a combobox styles would be better.

12 PM

2 Likes

That’s a good idea, but should be a separate Feature Requests as this can also be useful for e.g. Step input fields; as well as this is not specific to release templates (e.g. combo box is not suitable for release notes, only for some input types).

@han.tran feel free to create a Feature Requests for it! :wink:

This is exactly what we want :slight_smile:

2 Likes

@philipbjorge please vote, to bump its priority! :wink:

1 Like

Description of the feature request

Currently there are 2 variants to run the manual build: basic and advanced. Basic will run build with default “settings” and advanced will allow you to customize it and specify some environmental variables.

What is the problem?
Advanced build actually requires you to write both the variable key and it’s value by hand. So you should either remember or write down all things that you might want to change/add.

What is the solution?
Perfect solution will be to create some form of “Template” that will act just like Advanced Manual build view, but all environmental variable keys will be pre-defined and values will be not the text input, but the drop down selector.

Use case / for what or how I would use it

This will shine for building android apps that have many flavors/build types.
So you can just open this “Templated” build window, select desired build type (eg. release or debug) and select desired flavor (eg. demo, free, stage, full, etc). And then values you select will be translated to environmental variables that will be used for building your app.

I already saw solutions for running build for multiple flavors, but it requires creation of several workflows, what is not really efficient when you have 10+ flavors. (or building altogether, what is not efficient either)

3 Likes

I made a revision on the proposed format and example, to include all the requested features from the comments above in this thread.

Update: in the new proposal there’s a use case which isn’t addressed: how to handle optional inputs. We should still list these but not require a value. The original proposal addressed this use case, but that was too redundant:

template:
  create-release-template:
    workflow: _the-release-workflow
    envs:
    - RELEASE_VERSION_NUMBER:
        opts:
          title: "The version number for the release"
workflows:
  _the-release-workflow:
    steps: []
1 Like

any news about required user inputs env vars when manually triggering build in UI?

1 Like

Simply showing the Workflow description in the Build Trigger Popup would go a long way towards the end goal. This is discussed in #4884 but it is marked as “Released”. Add support for workflow description

I have people triggering builds manually and they need to know what key/values to enter as Env. variables in the Advanced section. The only piece of info visible I can control is the name of the workflow.