Triggering Workflows

Triggering workflows from GitHub

This page documents the events we accept from GitHub as triggers for running Commands, Pipelines, and Services workflows on the platform.

To better understand how events are defined more generally, as well as how these events fit in the broader context of all the Lifecycle Events we use in various capacities, have a look at our Lifecycle Events documentation.

Triggering Workflows with Events

Events that should be used to trigger a workflow run are specified in your ops.yml files as an array of strings under the workflow’s events field. Each string defines the name of an event from an external service (after it has been processed and interpreted by our system).

Format of Trigger Events
  - "{origin}:{repo}:{event}"

In the above format for defining an Event that should trigger a workflow:

  • {origin} is the service that originated the event, e.g. github.
  • {repo} is the path to the repo on the service. On GitHub, the repo path is formatted as organization-name/repo-name.
  • {event} is a string representing the name of a lifecycle event on the originating service.

When a workflow is triggered by an event from GitHub, we also make some additional static environment variables available to your workflow:

  • REPO: The name of the repository that triggered this workflow.
  • ORG: The name of the organization that owns your repository on GitHub.

Supported Events from GitHub

Installing our GitHub app in one of your repositories gives you access to a subset of the events GitHub makes accessible as webhooks, listed below:

  • pull_request.opened
  • pull_request.merged
  • pull_request.synchronize
  • pull_request.closed
  • pull_request.reopened
  • create.tag

For a complete explanation of these supported events, review the Event Definitions section below.

Example Workflows

Below are simple ops.yml snippets that run workflows when certain events occur. In this example, the first workflow we define, a Service named sample-expressjs:0.1.0, will build a container image to run an app, publish that Service container to the platform, then start the Service to allow us to preview the changes contained within the Pull Request. The workflow in the second example is a Pipeline which will build a release of the application for deployment.

In our example Service, we have defined three Events that should trigger this workflow: When a Pull Request in the linked repository is opened, synchronized, or reopened. To fully define a Service workflow, we also need to specify the actions we will trigger (in this case, build, publish, and start) when we receive an Event matching one defined under events:

Unlike Services, Pipeline workflows don’t need the trigger key in their definition, so we only need to specify which received Event will cause the Pipeline to run. In this case, we are saying the Pipeline should run whenever a pull request is merged or a new tag is created in the repo specified by github_org/github_repo:

Below is a more detailed description of the GitHub events that can currently be used to trigger workflows on the platform.

Event Definitions

In the tables below, Event Key is the key used by our system to represent a processed event, Event Description is a brief summary of when that type of event occurs, and ref is the specific Git ref that our system will check out for use by the workflow. The Event Key value is what replaces the {event} placeholder in the {origin}:{repo}:{event} format defined above.

Pull Request Events

Event NameEvent Descriptionref
pull_request.openedA pull request has been opened on the specified GitHub repoHead branch of pull request
pull_request.closedA pull request has been closed without mergingHead branch of pull request
pull_request.reopenedA closed pull request has been reopenedHead branch of pull request
pull_request.synchronizeThe head branch of a pull request was updated (e.g. new commits were pushed to the branch)Head branch of pull request
pull_request.mergedA pull request was closed by merging into the base branch.SHA of the merge commit

Tag Events

Event NameEvent Descriptionref
create.tagA tag has been created in the specified GitHub repoThe created tag