Trigger CircleCI Pipeline
Trigger your CircleCI pipelines from any event on GitHub with GitHub Actions.
How to Use
-
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-workflowsSelect 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: tcarac/trigger-circleci-pipeline-action@v1.0.5
env:
CCI_TOKEN: ${{ secrets.CCI_TOKEN }}
-
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. -
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 version2.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: ""
-
Use the Pipeline Parameter data to run workflows conditionally.
See: Examples
Inputs
Optional input parameters that allow you to specify additional metadata.
PR_Headref
required: false
description: An optional parameter to specify the branch to use on the CircleCI pipeline.
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: tcarac/trigger-circleci-pipeline-action@v1.0.5
with:
GHA_Meta: "<custom data>"
env:
PR_headref: my_branch
CCI_TOKEN: ${{ secrets.CCI_TOKEN }}
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