> 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/github-actions.md).

# GitHub Actions

## 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.

## 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 is listed.
* Obtain the current public start and status contract supplied for your workspace.
* Create a dedicated [API token](/administration/api-tokens.md) with the narrowest required scopes.

{% hint style="warning" %}
The verified production **CI / CD** tab does not display public endpoint paths. Do not use older examples based on account-password login or `/testplans/{id}/execute`. Do not copy request URLs from portal network traffic.
{% 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

When the public contract is available, the workflow job should:

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](/getting-started/ci-cd-tutorial.md)
* [Test Plans](/web-testing/test-plans.md)
* [API tokens](/administration/api-tokens.md)
* [Jenkins](/integrations/jenkins.md)
* [GitLab CI](/integrations/gitlab-ci.md)
* [CircleCI](/integrations/circleci.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.