Skip to main content

GitLab & GitHub

Connect GitLab or GitHub to close the loop between TestFlair and your engineering workflow. Both integrations do the same two things:

  • Push bugs out — turn TestFlair bugs into GitLab or GitHub issues.
  • Run tests from your pipeline — let GitLab CI or GitHub Actions start a TestFlair run and gate the build on the result.
Beta feature

The GitLab and GitHub integrations are Beta features, managed from the Integrations Hub. If the card shows Coming soon, they aren't enabled for your account yet — contact your workspace admin or [email protected].

The two integrations mirror each other. Where they differ, it's noted below.

Connecting​

Open the integration's card in the Integrations Hub and choose how to authenticate:

MethodWorks withNotes
OAuthGitLab.com / GitHub.comClick Connect with OAuth and authorize TestFlair. Recommended for hosted accounts.
Personal Access TokenHosted and self-managedEnter the base URL of your instance and paste a personal access token. The only option for self-hosted.

Connections are workspace-scoped — one connection serves every project in the workspace.

Mapping projects​

After connecting, map each TestFlair project to the GitLab project (or GitHub repository) it corresponds to. A single connection can carry several mappings. The connection card shows the mapped count alongside the connection's auth method, deployment type, and default branch.

Pushing Bugs to Issues​

Once at least one project is mapped:

  1. Open the integration's management page.
  2. In Push bugs to GitLab (or GitHub), select a mapped project.
  3. Click Push all bugs.

TestFlair creates an issue for every bug in that project. Results appear under Sync history, which lists recent pushes with their status and synced/failed counts.

Running TestFlair from Your Pipeline​

This is the inbound direction: your CI pipeline asks TestFlair to start one or more Test Runs, waits for the verdict, and fails the build if the tests fail.

1. Generate a CI token​

On the management page, find the CI token panel and click Generate token.

warning

The token is shown once, at the moment it's generated. Copy it straight into your CI secret store — you can't retrieve it later. If you lose it, use Rotate token to issue a new one; rotating immediately invalidates the previous token, so update your CI variable afterwards.

Generating and rotating tokens requires permission to manage integrations, so this panel is only visible to workspace Owners and Coordinators and to Project Admins, QA Managers and Testers.

2. Store it in your CI​

PlatformWhere
GitLabA masked CI/CD variable named TESTFLAIR_CI_TOKEN
GitHubAn Actions secret named TESTFLAIR_CI_TOKEN

3. Copy the pipeline snippet​

The management page builds the snippet for you. Pick the project mapping and the test runs you want the pipeline to start, and the page fills in the right IDs — no need to hunt for UUIDs by hand. Click Copy and paste it into your pipeline definition.

The snippet authenticates by sending your token in the X-TestFlair-CI-Token header, starts a run, polls until it finishes, and exits non-zero if the run failed.

When a run doesn't pass, the job log ends with a Why it failed section: a one-line summary followed by one ✗ line per failed or blocked case with its actual error — the assertion or exception message, the compiler error if the script didn't compile, or the blocking reason (no script, script still generating, wrong engine). You can read what broke straight from the pipeline log without opening TestFlair.

note

The pipeline runs the test cases, engine and execution preferences saved in each selected test run. To change what CI executes, edit the test run in TestFlair — the snippet does not need to change.

Triggering a Pipeline from TestFlair​

The outbound direction, on the same page:

  • GitLab — Trigger a GitLab pipeline: enter a branch or ref (the connection's default ref is pre-filled as the placeholder) and click Trigger pipeline.
  • GitHub — Dispatch a GitHub Actions workflow: the equivalent, dispatching a workflow on the mapped repository.

Disconnecting​

From the card menu, choose Disconnect. This removes the connection, its project or repository mappings, and its CI token. Issues, pipelines, and workflows already created on the GitLab/GitHub side are not affected.

Because disconnecting invalidates the CI token, any pipeline still using it will start failing — remove or update the TESTFLAIR_CI_TOKEN variable when you disconnect.

Troubleshooting​

Card shows "Coming soon"

  • The integration isn't enabled for your account. Contact your workspace admin or support.

No "Push bugs" section

  • You need at least one project mapping. Add one from the management page first.

CI token panel isn't visible

  • Generating and rotating tokens requires integration-management permission. Ask a workspace Owner or Coordinator.

Pipeline returns 401 / 403

  • The token was rotated, or the connection was disconnected. Generate a fresh token and update your CI variable.
  • Confirm the header name is exactly X-TestFlair-CI-Token.

Bugs push but no issues appear

  • Check that the token or OAuth account has permission to create issues on the mapped project or repository.
  • Review Sync history for the failure count and status of the most recent push.

Next Steps​