To trigger automated tests from a GitHub Actions pipeline, all you need to do is add a miqa-test-kickoff Action into your workflow file. Follow the instructions below to copy a code snippet into your workflow YAML and then customize it by replacing the Docker URI variable to use your own Docker image.
YAML Definition
Example YAML snippets are shown below. Add the appropriate snippet to the steps section of your .github/workflows/<your_workflow>.yml file. To get a pre-built snippet, go to your test trigger, and from the Quick Actions menu choose "Get Integration Blurb".
Pre-Built Snippets
Follow the steps below to copy your customized pre-built snippet to use in your GitHub Actions workflow.
Navigate to the Triggers page from the Test Automation tab on the left-side tool bar
Select the test trigger you want to update and click the link to open the Test Trigger page
From the Quick actions menu at the top right of the Test Trigger page, click Get Integration Blurb.
Click on the GitHub Actions tab header to show the correct integration settings. Copy the snippet text on the right and paste it into the workflow YML file as an additional workflow step. Note: be mindful of indentation when copy/pasting into your workflow.
Note: the default pre-built snippets in Miqa are for the full flow with status updates. If you want the basic flow without status updates, modify the snippet to use miqa-test-kickoff-only in the "uses" statement, as shown below.
Important: If you are using the full flow with status updates (Updating Test Status on GitHub Pull Requests), you must have the GitHub Actions yml set up to run only on pull_request events in the "on:" section, e.g.:
Example Snippets
Example code snippets are listed below for demonstration purposes. It is recommended that you copy your snippet template code directly from the Integration page in Miqa (see above).
Example Snippet: trigger tests and get status updates sent back to pull request
Execute tests based on test trigger.
- id: miqa-kickoff
uses: magna-labs/[email protected]
with:
INSTALLATION_ID: <your_installation_ID>
CHECK_NAME: <your_test_name>
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TRIGGER_ID: <your_trigger_id>
DOCKER_URI: <your_docker_uri>
MIQA_ENDPOINT: <your_endpoint_url>
SHA: ${{ github.sha }}
REPOSITORY: ${{ github.repository }}
To use this flow, you must first add the GitHub Miqa app.
Example Snippet: trigger tests (no updates)
Execute tests based on test trigger.
- id: miqa-kickoff-only
uses: magna-labs/[email protected]
with:
INSTALLATION_ID: <your_installation_ID>
CHECK_NAME: <your_test_name>
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TRIGGER_ID: <your_trigger_id>
DOCKER_URI: <your_docker_uri>
MIQA_ENDPOINT: <your_endpoint_url>
SHA: ${{ github.sha }}
REPOSITORY: ${{ github.repository }}
Variables
For most use cases, only the DOCKER_URI variable will be changing from build to build. When pushing your new Docker version, you should capture its URI (either by declaring a unique tag before pushing or retrieving the unique build hash after pushing).
All other variables are either static configurations or variables that can be directly passed from GitHub default variables. Your individualized installation ID can be though miqa-status-check. It is best practice to give your tests specified names, but Miqa will give them default names if the variable is not specified in the YAML file.
Prerequisites
You must already have an account with Miqa and the appropriate components configured and linked to your target Docker repositories.
For the full flow with updates, you must have downstream GitHub updates set up (see Updating Test Status on GitHub Pull Requests | Magna Labs, Inc. Help Center). The GitHub downstream app must be enabled on any repository that you want to receive updates on.
For more information, contact [email protected].
FAQ
Q: My GitHub Action is showing a warning message that there are unexpected inputs. Is this a problem?
A: No. This is due to how the GitHub REST API interacts with the actions that call it. The "Unexpected input(s)" warning annotation (example below) does not reflect a problem in your configuration and will not affect the build.
Q: My GitHub Action is showing an "Error: Not Found" error message when calling the miqa-test-kickoff action. How do I resolve this?
A: You likely forgot to add the downstream GitHub update app to this repository. Follow the Updating Test Status on GitHub Pull Requests for each repository that uses the miqa-test-kickoff action. If you do not need status updates, use the miqa-kickoff-only action.
Q: My GitHub Action is showing "Error: No commit found for SHA: /check-suites".
A: You are attempting to run the full-flow action outside of the pull-request context. This is not supported in miqa-test-kickoff v1.0.2 and earlier. Either update to miqa-test-kickoff v1.0.3, or use pull_request trigger types only.
Q: What event triggers should I use for the GitHub Actions integration?
A: At a minimum, we recommend using pull_request event trigger types. This will ensure that you are correctly linking the automated tests to the pull request in GitHub, which is the desired use case for most users ("push" event triggers in GitHub follow different actions that do not directly link back to the Pull Request's "Checks" tab and overall status, but rather to the pushed commit itself).
If you would like to use multiple event trigger types, we recommend limiting them to particular branches or otherwise filtering so that you do not end up with duplicate test runs. The GitHub Actions developer community has several recommendations and possibilities here, including:
Recommendations on combining or choosing trigger types:
Strategies to add conditionals, by trigger type:
Q: Can I run multiple Miqa triggers per GitHub Actions/Pull Request?
A: Yes-make sure your triggers and docker URI's are correct, and your YAML indentation is correct and you can run multiple tests per YAML file in GitHub Actions.