GitHub Actions workflows side effects
One of the features that I like the most about GitHub Actions is the number of different events that you can use to trigger a workflow.
Triggers are defined using the on rule in the workflow file and there is a wide range of options available such as pushes to all or specific branches or changes to a pull request.
I recently learnt, thanks to this tweet from James Sherlock, that you can also use GitHub webhook events to trigger workflow runs. I have since used one of GitHub's available webhook events to trigger a workflow based on the completion of another workflow.
For sure! I've not touched Xcode Cloud yet, so have had a lot of time to get used to GHA pipelines and the amount of fun stuff you can do with it! I even did some work on SwiftPackageIndex to generate PRs from issues using GHA Let me know if you get stuck, happy to help 😀
The workflow James refers to in his tweet is used in the Swift Package Index project to generate PRs from issues using the issues event as a trigger.
If you'd like to find out which events are available to trigger a GitHub Actions workflow, check out this page in the GitHub Actions documentation.
What is a webhook?
Webhooks are automated messages that a website sends to a URL based on the occurrence of specific events. For example, when a workflow finishes running, GitHub sends a workflow_url event to the URL configured to receive such events.
GitHub webhooks are configurable on a per-repository basis and provide a great way to build custom integrations and automations. If you want a more in-depth example of a practical use case which involves webhooks and Xcode Cloud check out this article on my blog.
Triggering a workflow based on the workflow_run event
While webhooks can be very powerful, building integrations with them is not straightforward. They are POST network requests with a payload containing context and information about the action which triggered the event and hence require you to build, set up and maintain a back-end service that can receive POST network requests, parse their bodies and perform a set of actions when needed.
The great news is that GitHub Actions provide a way to define a webhook event as the trigger or start condition for a workflow directly from the definition file, which removes the need to build and maintain a back-end service 🎉.
In my specific use case, I want to set up a workflow that runs after a specific workflow or set of workflows finish executing, which is as simple as:
- Adding the
workflow_runevent to theonrule in the workflow file. This is the same you would do if you were using a different event such aspushorpull_request. - Filtering the event based on the
workflow_run's activity types. Out of the three available types (completed,requestedandin_progress), I am only interested in thecompletedactivity type. - Specifying the workflow name to trigger on. This is required and in my case, I am only interested in triggering the log workflow when the Lint workflow completes.
name: Log workflow run metrics
on:
workflow_run:
workflows: [Lint]
types:
- completed
jobs:
log:
runs-on: macos-latest
env:
ANALYTICS_ENDPOINT: ${{ secrets.ANALYTICS_ENDPOINT }}
steps:
- uses: actions/checkout@v3
with:
repository: polpielladev/metrics
- run: |
swift run GithubActionsMetricsCLI \
"${{ github.event.workflow_run.name }}" \
"${{ github.event.workflow_run.updated_at }}" \
"${{ github.event.workflow_run.run_started_at }}" \
"${{ github.event.workflow_run.head_repository.name }}" \
"${{ github.event.workflow_run.conclusion }}" \
"${{ github.event.workflow_run.head_commit.author.name }}"
As part of its execution, the workflow above checks out an external repository and then runs a script to log metrics from the Lint's workflow run to a third-party service.
As you can see in the code above, the workflow can access the webhook payload data using the github.event.workflow_run context variable and pass the relevant information from the event to the metrics script.
iOS CI Newsletter