---
title: "Running Autify Nexus Test Plans from GitHub Actions"
slug: "run-nexus-test-plan-github-actions"
updated: 2025-11-10T01:16:17Z
published: 2025-11-10T01:16:17Z
canonical: "helpcenter.autify.com/run-nexus-test-plan-github-actions"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.autify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Autify Nexus Test Plans from GitHub Actions

This article explains how to run test plans using the Autify Nexus API from a GitHub Actions workflow.

---

## **Prerequisites**

To configure this integration, you will need the following information:

- Nexus server URL (example: [https://1234.cloud.autify.com](https://1234.cloud.autify.com))
- Test plan name
- Autify Nexus API token (Client secret)

---

## **Step 1: Save the API token in GitHub Secrets**

First, obtain the API token by referring to [**Obtain the client secret.**](/v1-api/apidocs/getting-started-with-the-autify-nexus-api#obtain-the-client-secret)

Save the obtained API token in **GitHub Actions Secrets**.

1. Go to the **Settings** tab of the target GitHub repository.
2. From the left menu, select **Secrets and variables > Actions**.
3. Click **New repository secret**.
4. Enter a name for the secret (example: AUTIFY_NEXUS_API_TOKEN).
5. Enter the API token retrieved from Autify Nexus into the **Secret** field.
6. Click **Add secret**.

---

## **Step 2: Create a GitHub Actions workflow**

Next, create a workflow file (YAML) that contains the steps for running your test plan.

1. Create a new YAML file (example: run-autify-nexus.yml) inside the repository’s .github/workflows/ directory.
2. Define the workflow trigger (example: on: push or on: workflow_dispatch).
3. Define the jobs section and configure the steps inside it.
4. Add a run step to execute the API request script.

See the samples below.

### **Sample 1: Run a test plan (Do not wait for completion)**

This script sends a request to run an Autify Nexus test plan, but does not wait for the test to finish.

```yaml
name: Run Autify Nexus Test Plan (No Wait)

on:
  workflow_dispatch:   # Allow manual execution

jobs:
  run-nexus-test:
    runs-on: ubuntu-latest
    steps:
      - name: Run Autify Nexus Test Plan (No Wait)
        env:
          AUTIFY_NEXUS_API_TOKEN: ${{ secrets.AUTIFY_NEXUS_API_TOKEN }}

          # Update the values below to match your environment
          SERVER_URL: "https://<your-nexus-server>"
          TEST_PLAN_NAME: "<your-test-plan-name>"

        run: |
          set -euo pipefail

          echo "Starting Autify Nexus test run..."

          AUTH_HEADER="Authorization: Bearer ${AUTIFY_NEXUS_API_TOKEN}"
          ACCEPT_HEADER='Accept: application/json'

          # Retrieve workspace ID
          ws_res=$(curl --silent --show-error \
            --url "${SERVER_URL}/nexus/api/workspaces" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")

          WORKSPACE_ID=$(echo "$ws_res" | jq -r '.[0].id')

          if [ -z "${WORKSPACE_ID:-}" ] || [ "${WORKSPACE_ID}" = "null" ]; then
            echo "❌ Workspace not found. Response:"
            echo "$ws_res"
            exit 1
          fi
          echo "✅ Workspace ID: ${WORKSPACE_ID}"

          # Retrieve test plan ID by name
          tp_res=$(curl --silent --show-error \
            --url "${SERVER_URL}/nexus/api/workspaces/${WORKSPACE_ID}/testPlans" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")

          TEST_PLAN_ID=$(echo "$tp_res" | jq -r --arg NAME "$TEST_PLAN_NAME" '.[] | select(.name == $NAME) | .id')

          if [ -z "${TEST_PLAN_ID:-}" ] || [ "${TEST_PLAN_ID}" = "null" ]; then
            echo "❌ Test plan '${TEST_PLAN_NAME}' not found."
            echo "$tp_res"
            exit 1
          fi
          echo "✅ Test Plan ID: ${TEST_PLAN_ID}"

          # Execute test plan (No Wait)
          run_res=$(curl --silent --show-error \
            --request POST \
            --url "${SERVER_URL}/nexus/api/workspaces/${WORKSPACE_ID}/testPlans/${TEST_PLAN_ID}/run" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")

          RESULT_ID=$(echo "$run_res" | jq -r '.resultId')

          if [ -z "${RESULT_ID:-}" ] || [ "${RESULT_ID}" = "null" ]; then
            echo "❌ Failed to start test plan."
            echo "$run_res"
            exit 1
          fi

          echo "✅ Test started (No Wait). Result ID: ${RESULT_ID}"
          echo "✅ Job completed."
```

### **Sample 2: Run a test plan and wait for the result**

This script sends a request to run a test plan, then checks the test status every 5 seconds (polling) until the test is complete.

If the status is anything other than **PASSED** (e.g., FAILED), the GitHub Actions job will fail.

```yaml
name: Run Autify Nexus Test Plan (Wait for Result)

on:
  workflow_dispatch: # Allow manual execution

jobs:
  run-nexus-test:
    runs-on: ubuntu-latest
    steps:
      - name: Run Autify Nexus Test Plan (Wait for Result)
        env:
          AUTIFY_NEXUS_API_TOKEN: ${{ secrets.AUTIFY_NEXUS_API_TOKEN }}

          # Update the values below to match your environment
          SERVER_URL: "https://<your-nexus-server>"
          TEST_PLAN_NAME: "<your-test-plan-name>"

        run: |
          set -euo pipefail

          echo "Starting Autify Nexus test run..."

          AUTH_HEADER="Authorization: Bearer ${AUTIFY_NEXUS_API_TOKEN}"
          ACCEPT_HEADER='Accept: application/json'

          # Retrieve workspace ID
          ws_res=$(curl --silent --show-error \
            --url "${SERVER_URL}/nexus/api/workspaces" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")
          WORKSPACE_ID=$(echo "$ws_res" | jq -r '.[0].id')

          if [ -z "${WORKSPACE_ID:-}" ] || [ "${WORKSPACE_ID}" = "null" ]; then
            echo "❌ Workspace not found. Response:"
            echo "$ws_res"
            exit 1
          fi
          echo "✅ Workspace ID: ${WORKSPACE_ID}"

          # Retrieve test plan ID by name
          tp_res=$(curl --silent --show-error \
            --url "${SERVER_URL}/nexus/api/workspaces/${WORKSPACE_ID}/testPlans" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")
          TEST_PLAN_ID=$(echo "$tp_res" | jq -r --arg NAME "$TEST_PLAN_NAME" '.[] | select(.name == $NAME) | .id')

          if [ -z "${TEST_PLAN_ID:-}" ] || [ "${TEST_PLAN_ID}" = "null" ]; then
            echo "❌ Test plan '${TEST_PLAN_NAME}' not found."
            echo "$tp_res"
            exit 1
          fi
          echo "✅ Test Plan ID: ${TEST_PLAN_ID}"

          # Execute test plan (Wait)
          run_res=$(curl --silent --show-error \
            --request POST \
            --url "${SERVER_URL}/nexus/api/workspaces/${WORKSPACE_ID}/testPlans/${TEST_PLAN_ID}/run" \
            --header "$AUTH_HEADER" \
            --header "$ACCEPT_HEADER")

          RESULT_ID=$(echo "$run_res" | jq -r '.resultId')

          if [ -z "${RESULT_ID:-}" ] || [ "${RESULT_ID}" = "null" ]; then
            echo "❌ Failed to start test plan. Response:"
            echo "$run_res"
            exit 1
          fi

          echo "✅ Test started. Result ID: ${RESULT_ID}"
          echo "⏳ Waiting for test to complete..."

          # Poll test status (QUEUED / RUNNING)
          STATUS="QUEUED"
          while [ "$STATUS" = "QUEUED" ] || [ "$STATUS" = "RUNNING" ]; do
            sleep 5
            st_res=$(curl --silent --show-error \
              --url "${SERVER_URL}/nexus/api/workspaces/${WORKSPACE_ID}/testResults/${RESULT_ID}/status" \
              --header "$AUTH_HEADER" \
              --header "$ACCEPT_HEADER")
            STATUS=$(echo "$st_res" | jq -r '.status')
            if [ -z "${STATUS:-}" ] || [ "$STATUS" = "null" ]; then
              echo "❌ Failed to fetch result status. Response:"
              echo "$st_res"
              exit 1
            fi
            echo "Current status: $STATUS"
          done

          echo "Final status: $STATUS"

          # Fail GitHub Actions job based on Autify Nexus test result
          if [ "$STATUS" != "PASSED" ]; then
            echo "❌ Test failed with status: $STATUS"
            exit 1
          fi

          echo "✅ Test PASSED"
```

> [!WARNING]
> This method consumes GitHub Actions hosted runner minutes while waiting for the test to complete.

---

## **Step 3: Run the workflow and check the results**

When the workflow is triggered (via push or manual run), GitHub Actions will start running.

1. Navigate to the **Actions** tab in your repository.
2. Click the executed workflow (e.g., Run Autify Nexus Test Plan).
3. Click the job name (e.g., run-nexus-test) and expand the execution steps to view the logs.

> [!WARNING]
> If the test plan fails to run, check the following:
> 
> - The test plan has at least one cloud execution environment configured.
> - The test plan contains at least one scenario.