Note

This GitHub Action does not yet support CircleCI projects that are integrated with the CircleCI GitHub App. If your CircleCI project URL looks like this: https://app.circleci.com/projects/organizations/circleci%, you are integrating with the CircleCI GitHub App and this GitHub Action is not yet supported. Contact sebastian@circleci.com with any questions/feedback. If your CircleCI project URL looks like this: https://app.circleci.com/projects/project-dashboard/github/, you are using CircleCI's OAuth App integration and this GitHub Action is supported.

Trigger CircleCI Pipeline

Trigger your CircleCI pipelines from any event on GitHub with GitHub Actions.

How to Use

1. Create a GitHub Action's workflow for the desired CircleCI pipeline.

   Do this by adding a workflow YAML file (we'll use main.yml) to ./.github/workflows.

   A release trigger is shown in this example. Try any of the GitHub events for triggering workflows: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows

   Select a custom name and id for the step for 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-Public/trigger-circleci-pipeline-action@v1.0.5
        env:
          CCI_TOKEN: ${{ secrets.CCI_TOKEN }}

2. Create an encrypted secret named CCI_TOKEN containing the Personal API Token that will be used to trigger the pipelines. This is suggested to be a machine user.

3. Add 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. Ensure you are specifying version 2.1

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

4. Use the Pipeline Parameter data to run workflows conditionally.

   See: Examples

Inputs

Optional input parameters that allow you to specify additional metadata.

GHA_Meta

required: false

description: An optional additional metadata parameter. Will be available on the CircleCI pipeline as GHA_Meta.

jobs:
  trigger-circleci:
    runs-on: ubuntu-latest
    steps:
      - name: <customize name>
        id: <customize id>
        uses: CircleCI-Public/trigger-circleci-pipeline-action@v1.0.5
        with:
          GHA_Meta: "<custom data>"
        env:
          CCI_TOKEN: ${{ secrets.CCI_TOKEN }}

target-slug

required: false

description: The CircleCI project slug of the target project (ex: github/<org>/<repo>). If not specified, the slug of the current GitHub repository will be used.

jobs:
  trigger-circleci:
    runs-on: ubuntu-latest
    steps:
      - name: <customize name>
        id: <customize id>
        uses: CircleCI-Public/trigger-circleci-pipeline-action@v1.0.5
        with:
          target-slug: "gh/<org>/<repo>" # Will trigger the pipeline for external project
        env:
          CCI_TOKEN: ${{ secrets.CCI_TOKEN }}

Outputs

Field	Data Type	Description
id	string (uuid)	The unique ID of the pipeline.
state	string (Enum: "created" "errored" "setup-pending" "setup" "pending")	The current state of the pipeline.
number	integer (int64)	The number of the pipeline.
created_at	string (date-time)	The date and time the pipeline was created.

Things To Know

GitHub Actions runs alongside native CircleCI integration.

By default, when a repository is connected to CircleCI, if the workflows within that project's configuration does not specify any conditionals or filters that would otherwise prevent execution, the workflow will execute on every push event by default.

This may mean it is possible to accidentally run a job twice, once on the push event from CircleCI, as well as other events triggered by the GitHub Action.

To prevent double execution

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 it's execution to only the GitHub Action trigger.

Example

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