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 using variables to populate with version information (e.g. Docker URI, hash, or version name) at runtime.
Planning to use the full flow to update Pull Request status? First configure the GitHub integration (you only need to do this once) following the Configure section here: Updating Test Status on GitHub Pull Requests
YAML Definition
Example YAML snippets are shown below. Add the appropriate snippet to the steps section of your .github/workflows/<your_workflow>.yml file. Follow the following instructions to easily copy and paste a pre-built snippet right into your GitHub Actions YML.
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 your Test Trigger of interest and click the ID link to open the Test Trigger page
Check the Caller Configuration section to determine the callers that are set up for this trigger. If you haven't already added a GitHub Actions caller, click +Add at the bottom of this box
Choose GitHub Actions from the Integration dropdown. You can either choose to use kickoff-only mode, or to do a full integration, posting back test results to your pull request. We recommend the full integration when possible.
If you need to add a new GitHub integration for downstream updates, click the icon to the right of the "Using integration" menu to open the Integration Manager, and then choose Add GitHub Integration from the top right Quick Actions menu.
To view and copy the YML blurb, go back to the Test Trigger page and click the button in the Blurb column of the Caller Configuration section.
Copy the snippet text on the right and paste it into your GitHub Actions workflow YML file as a workflow step. Default GitHub variables are already populated for you, but please replace any variables in square brackets with your own from your pipeline (e.g. passing the URI for a newly created Docker image to the DOCKER_URI field). Note: be mindful of indentation when copy/pasting into your workflow.
Important: If you are using the full flow with status updates (Updating Test Status on GitHub Pull Requests), we recommend setting up the GitHub Actions yml set up to run on pull_request events in the "on:" section, e.g.:
See the FAQ below for more information.
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>
MIQA_API_KEY: <your_api_key>
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>
MIQA_API_KEY: <your_api_key>
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 found through 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.