How Actionsflow works

Actionsflow will execute the workflow you define regularly or through webhook event. A typical workflow file contains a trigger and a job (a job can have multiple steps), Actionsflow currently supports two types of triggers, scheduled trigger and webhook trigger.

• A trigger is provided by the official, community or local triggers customized by javascript.
• A Job may have many steps, you can use Github marketplace actions at step. With the steps, you can do many things with the trigger's result, such as sending a message, sending a HTTP request, or uploading a file, etc.

Every time Actionsflow runs, the updated trigger will return an array of results to Actionsflow, Actionsflow will cache and deduplicate the trigger's results, and integrate the results according to the user-defined workflow file, generate a standard Github actions workflow file with your the trigger result. Finally, the workflows are executed using act (a tool for running GitHub Actions locally).

Actionsflow uses Github Actions' scheduled event to run workflows regularly, and uses repository_dispatch event to trigger a Webhook event

In practical terms, the power of actionsflow comes from the following Github workflows file (.github/workflows/actionsflow.yml):

name: Actionsflow
on:
  repository_dispatch:
  workflow_dispatch:
  schedule:
    - cron: "*/5 * * * *"
  push:
jobs:
  run:
    runs-on: ubuntu-latest
    name: Run
    steps:
      - uses: actions/checkout@v2
      - name: Run Actionsflow
        uses: actionsflow/actionsflow-action@v1
        with:
          args: build
          json-secrets: ${{ toJSON(secrets) }}
          json-github: ${{ toJSON(github) }}
      - name: Setup act
        uses: actionsflow/setup-act-for-actionsflow@v1
      - name: Run act
        run: act --workflows ./dist/workflows --secret-file ./dist/.secrets --eventpath ./dist/event.json --env-file ./dist/.env -P ubuntu-latest=actionsflow/act-environment:v1 -P ubuntu-18.04=actionsflow/act-environment:v1

scheduled Run

Actionsflow sets up a Github scheduled action to run every 5 minutes. Actionsflow will call the trigger's manual run method to check if there are any updates to the triggers in the workflows. If an updated item is found, Actionsflow generates a standard Github actions workflow file with the item payload and calls act to run the built workflows.

For example, if an Actionsflow workflow file looks like this:

on:
  rss:
    url: https://hnrss.org/newest?points=300
jobs:
  print:
    name: Print
    runs-on: ubuntu-latest
    steps:
      - name: Print Outputs
        env:
          title: ${{on.rss.outputs.title}}
          contentSnippet: ${{on.rss.outputs.contentSnippet}}
          link: ${{on.rss.outputs.link}}
        run: |
          echo title: $title
          echo contentSnippet: $contentSnippet
          echo link: $link

Then, Actionsflow will call RSS trigger (more info here) and return data of the RSS feed items in JSON format. To do this, Actionsflow generates a standard Github actions workflow file, after doing some caching and deduplication work.

The standard Github actions workflow file it generates looks like this:

"on":
  - push
jobs:
  print_0:
    name: Print 0
    runs-on: ubuntu-latest
    steps:
      - name: Print Outputs
        env:
          title: >-
            ${{(fromJSON(env.ACTIONSFLOW_TRIGGER_RESULT_FOR_rss_0)).outputs.title}}
          contentSnippet: >-
            ${{(fromJSON(env.ACTIONSFLOW_TRIGGER_RESULT_FOR_rss_0)).outputs.contentSnippet}}
          link: >-
            ${{(fromJSON(env.ACTIONSFLOW_TRIGGER_RESULT_FOR_rss_0)).outputs.link}}
        run: |
          echo title: $title
          echo contentSnippet: $contentSnippet
          echo link: $link
env:
  ACTIONSFLOW_TRIGGER_RESULT_FOR_rss_0: |-
    {
      "outcome": "success",
      "conclusion": "success",
      "outputs": {
        "creator": "aripickar",
        "title": "Nikola: How to Parlay an Ocean of Lies into a Partnership with GM",
        "link": "https://hindenburgresearch.com/nikola/",
        "pubDate": "Thu, 10 Sep 2020 21:24:44 +0000",
        "dc:creator": "aripickar",
        "comments": "https://news.ycombinator.com/item?id=24436721",
        "content": "\n<p>Article URL: <a href=\"https://hindenburgresearch.com/nikola/\">https://hindenburgresearch.com/nikola/</a></p>\n<p>Comments URL: <a href=\"https://news.ycombinator.com/item?id=24436721\">https://news.ycombinator.com/item?id=24436721</a></p>\n<p>Points: 316</p>\n<p># Comments: 281</p>\n",
        "contentSnippet": "Article URL: https://hindenburgresearch.com/nikola/\nComments URL: https://news.ycombinator.com/item?id=24436721\nPoints: 316\n# Comments: 281",
        "guid": "https://news.ycombinator.com/item?id=24436721",
        "isoDate": "2020-09-10T21:24:44.000Z"
      }
    }

Then, Actionsflow will call act (a tool for running GitHub Actions locally) to run the jobs in the workflow file.

repository_dispatch Run

Github provides a repository_dispatch event which allows an outside service to trigger a Github actions workflow run.

Actionsflow uses it to support standard webhook requests.

To do this, we created the webhook2github project.

This API will forward the following original webhook request:

https://webhook.actionsflow.workers.dev/<owner>/<repo>/<your-path>?__token=<your-github-personal-token>

To https://api.github.com/repos/<owner>/<repo>/dispatches, with body:

{
  "event_type": "webhook",
  "client_payload": {
    "path": "<your-path>",
    "method": "<request.method>",
    "headers": "<request.headers>",
    "body": "<request body>"
  }
}

Then, Actionsflow will call the trigger's webhook handler to get the result items and generate a standard Github actions workflow file.

Finally, Actionsflow calls act (a tool for running GitHub Actions locally) on the generated workflow file, so that the jobs run.

What the Actionsflow workflow file includes

A typical Actionsflow workflow file includes a trigger and some jobs. Actionsflow also supports multiple triggers and multiple jobs.

To learn more about the Workflow syntax for Actionsflow, please see here.

To learn more about all Actionsflow's github workflow files, see Actionsflow Github Workflows.