How to dispatch a GitHub Workflow from iOS Shortcuts

#technology

January 9th, 2023

Dispatching a GitHub Workflow from iOS Shortcuts is pretty simple, albeit a bit confusing at first. When I first discovered the ability to trigger a GitHub Workflow from my iPhone, I could not find any authoritative documentation, so I had to tinker with the configurations to get it to work. I wanted to write this blog post for anyone struggling to get their Shortcut to work and my future self who will undoubtedly forget how. (Hello, future self 👋. How is it in the future? Am I rich? Did I finally get to eat at a Michelin-starred restaurant?)

Requirements: You have

a GitHub account and a repository to add a workflow to,
an iPhone running at least iOS 12,
and the GitHub App downloaded on your phone from the App Store.

Hello, shortcut!

In this tutorial, we will be creating a simple "Hello, world!" program. We will:

create a simple workflow in GitHub that takes your name as standard input and outputs "Hello, <your name>!" as standard output.
set up the GitHub "Dispatch Workflow" Action in iOS Shortcuts with your name and the necessary configurations.

Setting up the GitHub Workflow

In your GitHub repository, create a new directory at the root called .github/workflows. Next, inside of .github/workflows, create a new file called hello-world.yml. Copy and paste the following code in the yaml file:

# .github/workflows/hello-world.yml
# This is a basic workflow to help you get started with Actions

name: Hello, world!

# Controls when the workflow will run
on:
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
    inputs:
      name:
        description: "Your name."
        required: true
        default: "warning"

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      # Runs a single command using the runners shell
      - name: Run a one-line script
        run: echo "Hello, ${{ inputs.name }}!"

I will not go into depth about the various components of this yaml file in this blog post but, will point out several important aspects that will be necessary to dispatch the workflow correctly from iOS Shortcuts:

First, we need to add a workflow_dispatch trigger event using the on keyword.
Second, we need to specify the inputs that will be passed to the workflow under the inputs keyword under the workflow_dispatch keyword. In this case, we will be passing a variable called name from our Shortcut Action.
Lastly, the last step in our workflow is where we will run out one line script to output "Hello, <your name>!".

Setting up the Shortcut Action

1. Go to the iOS Shortcuts application on your device.

2. Click the "+" button in the top tool bar to create a new shortcut.

3. Give your shortcut a name.

4. Click "Add Action". This will open a modal of all of the available Shortcut Actions available on your device. Search for “GitHub” and then click "Dispatch Workflow".

5. Fill out the missing fields in the Action:

Under the Owner field, enter your GitHub handle.
Under the Workflow ID, enter the workflow ID associated with the `hello-world.yml` workflow we added earlier. The easiest way to get this value is by installing the GitHub CLI, clone the repository locally (if you don't already have the repository cloned on your machine,) cd into the project directory and run gh workflow list.
Under Repository add the name of the repository.
Under Branch/ref add main or master depending on what you've named your default branch.
Lastly under Inputs, we will need to pass a dictionary with key, name and value, your name. To create the dictionary,
1. search for "Dictionary" in the search bar.
2. Under "Scripting" select "Dictionary".
3. Within the "Dictionary" action tile, click the green circle with the "+" icon and select "Text" from the pop out menu.
4. Enter "name" as the Key and your name as the Text.
Back under the "Dispatch Workflow" action tile, select the "Inputs" field and select "Select Variable". This will allow you to manually select the variable to input into a field. Select "Dictionary" (highlighted in blue).

6. If you have done everything correctly, your Shortcut should look something like this:

Now if you run the Shortcut, you should be able to see the workflow running under "Actions" tab on GitHub!