GitHub Actions inputs

Kenny DuMez
Kenny DuMez
Graphite software engineer

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 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.

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:

Terminal
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.

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:

Terminal
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.

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:

Terminal
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.

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

Terminal
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.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2