> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/integrations-and-developer-tools/integrations/github-actions.md).

# GitHub Actions

Prepare GitHub Actions secrets, variables, triggers, and branch protection for a ContextQA test-plan quality gate.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

Prepare GitHub Actions secrets, variables, triggers, and branch protection for a ContextQA test-plan quality gate. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result.

## Key takeaways

* Prepare GitHub Actions secrets, variables, triggers, and branch protection for a ContextQA test-plan quality gate.
* Create and manually validate the test plan you want to use as the gate.
* In the GitHub repository, open Settings → Secrets and variables → Actions.

## What this page covers

Use GitHub Actions to place a ContextQA test-plan result in the pull-request or deployment path. ContextQA runs the browsers or devices; the GitHub runner coordinates the request and evaluates the result.

## Before you begin

* Create and manually validate the test plan you want to use as the gate.
* Open the plan's **CI / CD** tab and confirm GitHub Actions is listed.
* Select the intended environment and mobile build source, when applicable.
* Create a dedicated [API token](https://learning.contextqa.com/administration-and-reference/administration/api-tokens.md) with the narrowest required scopes.

{% hint style="warning" %}
Use the configuration generated by the current workspace instead of copying older examples or request URLs from portal network traffic. Keep the generated credential reference as a protected GitHub secret; never replace it with a literal token in the workflow file.
{% endhint %}

## Store GitHub configuration

In the GitHub repository, open **Settings → Secrets and variables → Actions**.

Add:

| Type     | Name                     | Value                                                         |
| -------- | ------------------------ | ------------------------------------------------------------- |
| Secret   | `CONTEXTQA_API_TOKEN`    | The one-time token value copied from ContextQA                |
| Variable | `CONTEXTQA_TEST_PLAN_ID` | The plan ID shown on the ContextQA plan overview              |
| Variable | `CONTEXTQA_API_BASE_URL` | The public base URL from the official contract, when supplied |

Use an environment-level secret when production deployments require stricter reviewers or a different token.

## Choose the workflow trigger

Select the event that matches the plan's purpose:

| Trigger         | Good fit                                             |
| --------------- | ---------------------------------------------------- |
| Pull request    | Small smoke or risk-based plan before merge          |
| Push to `main`  | Post-merge verification                              |
| Deployment      | Pre-production or post-deployment validation         |
| Schedule        | Broad regression outside the developer feedback loop |
| Manual dispatch | Troubleshooting and controlled reruns                |

Avoid running the same expensive plan on overlapping events unless the duplicate coverage is intentional.

## Implement the quality gate

The generated GitHub Actions workflow includes the trigger-and-poll pattern. Review it so the job will:

1. Read the token from `secrets.CONTEXTQA_API_TOKEN` and the plan ID from `vars.CONTEXTQA_TEST_PLAN_ID`.
2. Start the plan using the published request method, path, and payload.
3. Store the returned run ID as a step output.
4. Poll the published status operation with a bounded timeout.
5. Fail the job for every documented non-success terminal result.
6. Add the run ID to the job summary and direct reviewers to the ContextQA portal.

Do not construct a deep link unless the public response returns one.

## Protect the branch

After validating both pass and fail paths:

1. Open the repository ruleset or branch protection rule.
2. Require the ContextQA job's check name before merge.
3. Keep the workflow file and required-check name stable.
4. Require review for changes to the workflow when it protects production.

## Security guidance

* Use one token per repository or GitHub environment.
* Never use a user's ContextQA password in Actions.
* Mask response values that could contain sensitive test data.
* Rotate the token before expiry and immediately after suspected exposure.
* Add an IP allowlist only when the runner egress addresses are stable.

## Troubleshooting

**The workflow has no endpoint to call**

The current production CI/CD tab describes the operations but does not publish their paths. Obtain the public API contract for your workspace; do not infer it.

**The request returns unauthorized or forbidden**

Check the token's status, expiry, permission scopes, and IP allowlist. Confirm the workflow reads the intended GitHub secret.

**A passing plan does not unblock the pull request**

Verify that branch protection requires the exact current job name and that the workflow runs for the target pull-request event.

## Related pages

* [Prepare a CI/CD quality gate](https://learning.contextqa.com/start-here/ci-cd-tutorial.md)
* [Validate a CI quality gate](https://learning.contextqa.com/plan-evaluate-and-migrate/evaluation/ci-integration-acceptance-runbook.md)
* [Test Plans](https://learning.contextqa.com/enterprise-application-testing/web-testing/test-plans.md)
* [API tokens](https://learning.contextqa.com/administration-and-reference/administration/api-tokens.md)
* [Jenkins](https://learning.contextqa.com/integrations-and-developer-tools/integrations/jenkins.md)
* [GitLab CI](https://learning.contextqa.com/integrations-and-developer-tools/integrations/gitlab-ci.md)
* [CircleCI](https://learning.contextqa.com/integrations-and-developer-tools/integrations/circleci.md)

## Current plan setup

Open the plan's **CI / CD** tab and select **Open setup guide** for current provider instructions. Use the displayed plan ID and a scoped `CONTEXTQA_TOKEN` secret. See [CI/CD release gates](https://learning.contextqa.com/integrations-and-developer-tools/integrations/ci-cd-release-gates.md) for required permissions and failure-path validation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/integrations-and-developer-tools/integrations/github-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
