Triggering workflows from GitHub

This page documents the events we accept from GitHub as triggers for running Commands, Pipelines, and Services workflows on the CTO.ai 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).

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

services:
  - name: sample-expressjs:0.1.0
    description: preview of sample app
    run: node index.js
    port: ["8080:8080"]
    domain: ""
    env:
      static:
        - PORT=8080
        - DB_HOST=localhost
        - DB_PORT=3600
        - DB_USER=fake
      secrets:
        - SLACK_SIGNING_SECRET
        - SLACK_BOT_TOKEN
    events:
      - "github:github_org/github_repo:pull_request.opened"
      - "github:github_org/github_repo:pull_request.synchronize"
      - "github:github_org/github_repo:pull_request.reopened"
    trigger:
      - build
      - publish
      - start

pipelines:
  - name: sample-app-pipeline:0.1.0
    description: build a release for deployment on fargate
    env:
      static:
        - DEBIAN_FRONTEND=noninteractive
      secrets:
        - GITHUB_TOKEN
        - AWS_ACCESS_KEY_ID
        - AWS_SECRET_ACCESS_KEY
        - AWS_ACCOUNT_NUMBER
    events:
      - "github:github_org/github_repo:pull_request.merged"
      - "github:github_org/github_repo:create.tag"
    jobs:
      - name: sample-app-build-job
        description: example build step
        packages:
          - git
          - unzip
          - python
        steps:
          - curl https://s3.amazonaws.com/aws-cli/awscli-bundle-1.18.200.zip -o awscli-bundle.zip
          - unzip awscli-bundle.zip && ./awscli-bundle/install -b ~/bin/aws
          - export PATH=~/bin:$PATH

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:

# # # ...
events:
  - "github:github_org/github_repo:pull_request.opened"
  - "github:github_org/github_repo:pull_request.synchronize"
  - "github:github_org/github_repo:pull_request.reopened"
trigger:
  - build
  - publish
  - start

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:

# # # ...
events:
  - "github:github_org/github_repo:pull_request.merged"
  - "github:github_org/github_repo:create.tag"

Below is a more detailed description of the GitHub events that can currently be used to trigger workflows on the CTO.ai 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

Tag Events