/gha-form-dropdown-options

A github action populating options for an issue forms dropdown.

Primary LanguageJavaScriptMIT LicenseMIT

Issue Forms Dropdown Options

GitHub Marketplace Sponsor ShaMan123

๐Ÿงช Test ๐Ÿš€ Update Bug Report

A github action populating options for an issue forms dropdown.

Looking for a Version dropdown?

Checkout issue-forms-version-dropdown

Configuring

  • Follow this workflow.
  • Replace the uses: ./ directive to point to published action.
  • Refer to the inputs and outputs definitions in the spec.

Live ๐Ÿš€

This repo uses the action it defines.

Advanced Usage

Templates

The template option introduces a build step, sort of speaking. It reads the template and outputs a generated file using inputs.form. This means that you shouldn't edit the built form, as you wouldn't edit a build file.

The action will use template to build the form as follows:

  • Parse template
  • For each dropdown:
    • Determine if dropdown is static using inputs.strategy.
    • Static dropdowns (dropdowns with populated options in the template) take precedence over their built counterpart.
      See an example commit.
    • Dynamic dropdowns are persisted from the built file in order to enable updating parts of a form from multiple runs.
  • Set inputs.options
  • Write form

Using a template is suggested for the following:

  • Preserving comments: Parsing the yaml file will loose all comments
  • DX: Maintaining forms with long dropdown options
  • Dynamic Substitution

Dynamic Substitution

  • {...} : will populate the value from template if existing
  • {{...}} : will populate the previous value from form if existing.
Dynamic Substitution Flow

template.yml

    ...
    - type: dropdown
      id: _dropdown
      description: 'template says: {...}, build says: ...'
      options:
        - a
    ...

workflow.yml

    ...
    with:
      id: _dropdown
      description: 'template says: {...}, build says: ...'
      options: {...}, b
    ...

build.yml #1

    ...
    with:
      id: _dropdown
      description: 'template says: template says: {...}, build says: ..., build says: ...'
      options:
        - a
        - b
    ...

workflow.yml

    ...
    with:
      id: _dropdown
      description: 'template says: {{...}}, build says: ...'
      options: {{...}}, c
    ...

build.yml #2

    ...
    with:
      id: _dropdown
      description: 'template says: template says: template says: {...}, build says: ..., build says: ..., build says: ...'
      options:
        - a
        - b
        - c
    ...

workflow.yml

    ...
    with:
      id: _dropdown
      description: 'template says: {{...}} but build says: ...'
      options: {...}, d
    ...

build.yml #3

    ...
    with:
      id: _dropdown
      description: 'template says: template says: template says: template says: {...}, build says: ..., build says: ..., build says: ... but build says: ...'
      options:
        - a
        - d
    ...

Take a look at the template file used to generate the built file for a live example.

Conflicting Runs

Since workflows run in concurrency you may encounter a case in which a number of runs are trying to modify and commit the same file.
This might result in a merge conflict.
If that is the case the action will fail.

Consider the following:
The labels of this repo are populated into a dropdown (see Live).
Modifying a label more than once in a short period of time (before the previous runs completed) will fail to update the form.

Consider handling failures in a consequent step or use the dry_run option to prevent the action from trying to commit in the first place and handle that yourself.

Creating a PR

Consider using create-pull-request in order to commit changes in an orderly and safe fashion to a generated PR.

Refer to the update-long-report job in this workflow to see a usage example and to PR #5.
Don't forget to use the dry_run option.