Trigger your CircleCI pipelines from a GitHub Actions workflow

If you are already a GitHub user, you may know that GitHub Actions provides you with powerful tools to increase efficiencies in your software delivery life cycle. Actions can be impactful for team collaborations and process simplification. For example, you can automate things like building a container, welcoming new users to your open source projects, managing branches, or triaging issues.

It’s important to use the right tool for the right job. Using GitHub Actions along with CircleCI allows you to automate aspects of your version control system while also benefiting from features that are only available in your CircleCI pipelines. Imagine extending your VCS workflow to include advanced features like SSH debugging, test splitting, robust CPU and RAM options and GPU and Arm support.

For example, you can use Actions for team collaboration and process simplification while accelerating your build, test, and deploy stages with CircleCI.

To make it even easier to kick off your CircleCI pipelines from any event on GitHub, our team built the Trigger CircleCI Pipeline action, which is now available in the GitHub Marketplace.

In this article, we will describe a few ways you can incorporate the Trigger CircleCI Pipeline action into your workflow to make the most of your GitHub automation credits while benefiting from CircleCI’s world-class continuous integration capabilities.

Trigger CircleCI Pipeline: A GitHub Action for triggering workflows in CircleCI

With the Trigger CircleCI Pipeline action, you can kick off a CircleCI pipeline from any event on a given branch or tag. The action passes along a set of pipeline parameters containing metadata that can be used to control the flow of your CircleCI pipelines and workflows.

One potential use case for the Trigger CircleCI Pipeline action is triggering a CircleCI pipeline whenever a pull request is opened by a developer. Triggering on a pull request allows you to test changes in a PR even if the last commit was made prior to the PR being opened (or to trigger a build and test cycle any time changes are pushed to the branch a PR was opened from).

Another use case for the Trigger CircleCI Pipeline action is triggering a build and deployment from CircleCI whenever a release is created, edited, or published in GitHub. Triggering on a release allows you to build and deploy an application—such as deploying a Dockerized microservice to a Kubernetes cluster or publishing a binary to an app store—when the repo owner specifies a new release version of the application.

You can view complete implementations of these two use cases, including templates for both your CircleCI and GitHub Actions configuration files, in the Examples directory of the Trigger CircleCI Pipeline repository. Next we’ll explore an example of using the Trigger CircleCI Pipeline Action to initiate a CircleCI workflow when a new release is published.

How to use the Trigger CircleCI Pipeline Action to trigger a pipeline from a new release

The first step in setting up GitHub Actions to work with CircleCI is to create a GitHub Actions workflow for the desired CircleCI pipeline. You can do this by adding a workflow YAML file (we’ll use main.yml) to ./.github/workflows.

In the following example, you use the on and types syntax to specify that the trigger-circleci action triggers when a new release is published. Select a custom name and id for the step to provide additional contextual metadata in your CircleCI pipeline:

on:
  release:
    types: [published]
jobs:
  trigger-circleci:
    runs-on: ubuntu-latest
    steps:
      - name: <customize name>
        id: <customize id>
        uses: circleci/trigger_circleci_pipeline@v1.0
        env:
          CCI_TOKEN: $

Next, create an encrypted secret named CCI_TOKEN containing the personal API token that will be used to trigger the pipelines. We recommend making this a machine user.

Now that you have your GitHub workflow set up, you can modify your CircleCI config file to run when your GitHub Action kicks off. Start by adding the pipeline parameter definitions to your CircleCI config. This data will be entered by the GitHub Action when triggered.

Add the following to the top of your .circleci/config.yml file. Make sure you specify version 2.1:

version: 2.1
parameters:
  GHA_Event:
    type: string
    default: ""
  GHA_Actor:
    type: string
    default: ""
  GHA_Action:
    type: string
    default: ""
  GHA_Meta:
    type: string
    default: ""

The action generates several pipeline parameters:

• GHA_Actor indicates which user triggered the pipeline.
• GHA_Action is the id assigned in the workflow configuration.
• GHA_Event is the type of GitHub event that triggered the pipeline.
• GHA_Meta is an optional additional metadata parameter that allows you to specify additional metadata using input parameters.

You can use this pipeline parameter data to run workflows conditionally. In this example, the GHA_Event parameter will be populated with the value release, and you can use a when clause in your CircleCI config to specify workflows that should run only when triggered by the GitHub workflow:

jobs:
  release:
    docker:
      - image: cimg/node:lts
    steps:
      - run: npm install
      - run: npm build
      - run: npm publish

workflows:
  release:
    when:
      equal: ["release", << pipeline.parameters.GHA_Event >>]
    jobs:
      - release

This config snippet specifies a release job that publishes an npm package and a release workflow that invokes the release job. In the when clause, you specify that the release workflow will run only when the GitHub workflow runs and populates the GHA_Event parameter with the value release.

Although this example demonstrates how to set up a release trigger, you can use the same techniques to kick off a CircleCI pipeline from any of the available GitHub events for triggering workflows. To view the complete setup for triggering CircleCI from events on a pull request, visit the example GitHub repo.

How to prevent double execution of jobs in GitHub and CircleCI

It is important to emphasize that GitHub Actions runs alongside native CircleCI integration. By default, when a repository is connected to CircleCI, if a workflow within that project’s configuration does not specify any conditionals or filters that would otherwise prevent execution, then the workflow will execute on every push event by default. This means that it is possible to accidentally run a job twice, once on the push event from CircleCI and again on other events triggered by the GitHub Action.

If you are relying on GitHub Actions to provide all of your API triggers, ensure that each of your CircleCI configuration’s workflows contains a conditional limiting its execution to only the GitHub Action trigger, as in the following example:

workflows:
  # This workflow is set to be triggered conditionally, only when
  # the GitHub Action is triggered.
  # With no other workflows, normal push events will be ignored.
  when: << pipeline.parameters.GHA_Action >>
  test:
    jobs:
      - test

Using the when clause in your workflow declaration allows you to specify that CircleCI should run the workflow only when the specified GHA_Action is triggered and not after normal push events.

Conclusion

GitHub Actions is a useful tool for automating a variety of version control processes, from checking out a Git repository at a particular version to automatically creating or merging pull requests to updating README files based on changes to your code. With the help of the Trigger CircleCI Pipeline action, you can combine the time-saving benefits of version control automation with the powerful workflow acceleration that only the fastest, most secure, and feature-rich continuous integration platform can provide.

To add the Trigger CircleCI Pipeline action to your repository, visit the GitHub Marketplace and copy the workflow syntax to your workflow.yml file. If your team is not already using CircleCI to validate and ship changes to your users quickly and confidently, sign up for a free account today.