GitHub Actions inputs

Inputs in GitHub Actions play a critical role by allowing parameters to be passed to actions and workflows, enabling more dynamic and configurable executions. This guide will delve into the different input types available in GitHub Actions, how to use inputs in workflow dispatch events, and managing specific input types like booleans.

GitHub Actions input types

Overview of input types

GitHub Actions supports several input types that can be used to customize the behavior of workflows and actions. Inputs are typically defined in workflow files (YAML) and can vary based on what is needed for a particular action or workflow. The basic input types supported include:

• String: The most common type, used for text inputs.
• Boolean: Used for true/false conditions.
• Choice: Allows the user to select from a predefined list of options.

These inputs can be used in different parts of a GitHub Action workflow, particularly in steps that require user interaction or configuration.

Defining inputs in action metadata

When creating custom actions, you can define inputs in the action's configuration file (action.yml or action.yaml). Here is an example of how inputs can be defined:

name: 'My Custom Action'
description: 'Performs an action with inputs'
inputs:
  myInput:
    description: 'A custom input'
    required: true
    default: 'default value'
runs:
  using: 'node12'
  main: 'index.js'

In this example, myInput is a required input with a default value.

GitHub Actions workflow dispatch inputs

Using inputs with workflow dispatch

Workflow dispatch is a feature in GitHub Actions that allows workflows to be manually triggered. This is particularly useful for workflows that require input from the user at the time of execution, such as deploying a specific version of an application.

To define inputs for a workflow dispatch, you can add an inputs section under the on.workflow_dispatch trigger in your workflow file:

name: Manual Workflow
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        default: 'staging'
      enableFeatureX:
        description: 'Enable feature X'
        required: false
        type: 'boolean'
        default: 'false'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Deploy
        run: echo "Deploying to ${{ github.event.inputs.environment }}"
        env:
          FEATURE_X_ENABLED: ${{ github.event.inputs.enableFeatureX }}

In this example, the workflow takes two inputs: environment and enableFeatureX, which is a boolean.

When running this action manually through the GitHub webapp, the UI will prompt you to fill in each of the specified inputs under the workflow_dispatch field.

Managing specific input types

Handling boolean inputs

Boolean inputs in GitHub Actions need to be defined and managed carefully, as they determine the flow of conditional steps within a workflow. When defining a boolean input, it is crucial to set the type explicitly and manage the default value carefully to ensure correct workflow behavior.

Here’s a more detailed look at a boolean input in a workflow dispatch:

on:
  workflow_dispatch:
    inputs:
      dryRun:
        description: 'Run without making changes'
        required: true
        type: 'boolean'
        default: 'false'

The default value means that unless otherwise specified or overwritten, the input will default to fault.

Accessing inputs in workflows

Inputs can be accessed within a workflow by referencing them through the github.event.inputs context. For example, to access an input named myInput:

steps:
  - name: Use input
    run: echo "Input was ${{ github.event.inputs.myInput }}"

This allows you to access data provided by the inputs, and can also be used to elicit conditional behavior from workflow runs.

For further reading on GitHub Actions inputs, see the official GitHub documentation.