How to force stop Copilot Session when setup step in copilot-setup-steps.yml fails?

[YanjieShiFennec]

Select Topic Area

Question

Copilot Feature Area

Copilot Agent Mode

Body

Hi all,
I found If any setup step fails by returning a non-zero exit code, Copilot will skip the remaining setup steps and begin working with the current state of its development environment. in GitHub document: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment#customizing-copilots-development-environment-with-copilot-setup-steps :

Here is part of my copilot-setup-steps.yml:

steps:
  - name: Check Token Presence
    run: |
      if [ -z "$TOKEN" ]; then
        echo "TOKEN IS EMPTY"
        exit 1
      else
        echo "TOKEN IS SET (Length: ${#TOKEN})"
      fi
    env:
      TOKEN: xxx
  - name: Checkout Repository with Submodules
    uses: actions/checkout@v4
    with:
      token: xxx
      submodules: recursive
  - name: Fetch All History Manually
    run: |
      git remote set-url origin https://x-access-token:xxx@github.com/${{ github.repository }}.git
      git fetch --unshallow origin
  - name: Check Submodule Presence
    run: |
      ls -la Automation_TestCase_Suite/Automation_TestCase_Suite
      if [ -d "Automation_TestCase_Suite/Automation_TestCase_Suite" ]; then
        echo "Submodule exists and initialized"
      else
        echo "Submodule not found or not initialized"
        exit 1
      fi

The exit 1 command has no effect; Copilot continues to operate, as described in the GitHub documentation.

Is there any way to force stop Copilot Session when setup step in copilot-setup-steps.yml fails?

[ChandrakantaMandal]

This is expected behavior today.

copilot-setup-steps.yml failures only stop the remaining setup steps — they don’t abort the Copilot agent session. The setup phase is treated as best-effort provisioning rather than a hard gate.

At the moment there isn’t a supported way to force-stop the session when a step fails. The usual workaround is to fail fast inside your repo scripts (or enforce strict checks in CI) so the agent can’t proceed meaningfully when the environment is invalid.

[pratikrath126]

Workaround: In your setup script, write a sentinel file on failure and have a background validation step that monitors for this file and kills the agent process (e.g., ). Cleanup: also remove the sentinel to avoid stale stops. Alternatively, use a timeout wrapper around the entire agent session so it exits automatically when your setup exceeds a threshold. These are self-managed approaches until GitHub adds a native abort-on-failure flag.

[Farhxn-15]

Yeah, what you are seeing is actually expected behavior with Copilot Agent Mode.

Returning a non zero exit code in copilot-setup-steps.yml does not terminate the Copilot session. It only stops the remaining setup steps and Copilot continues using the environment state that already exists.

From the docs:

If a step fails, Copilot skips the rest of the setup steps and proceeds with the current environment.

So exit 1 stops the setup sequence, not the session.

Why Copilot continues running

The setup phase prepares the environment. It is not treated as a critical failure boundary. Copilot assumes the workspace may still be usable and continues operating.

This design prevents transient setup failures from blocking the entire session.

How to actually stop the session

There is currently no built in flag in copilot-setup-steps.yml to force terminate the session.

However, you can enforce failure using one of these approaches:

1. Fail the workspace intentionally

If the environment is unusable, you can remove required dependencies:

exit 1

followed by making a required tool unavailable. This causes later commands to fail and prevents useful execution.

2. Validate prerequisites and block execution

Instead of relying on exit codes alone, create a guard file:

if [ -z "$TOKEN" ]; then
echo "TOKEN missing" > /workspace/.copilot-block
fi

Then in your tasks or scripts:

if [ -f /workspace/.copilot-block ]; then
echo "Environment invalid"
exit 1
fi

This prevents Copilot from continuing meaningful work.

3. Force agent tasks to fail early

If your workflow relies on scripts, make them validate environment readiness before doing anything.

This is currently the most reliable control point.

4. Use environment validation instead of setup termination

Think of setup steps as initialization, not enforcement. Enforcement should happen inside the commands Copilot executes.

Important takeaway

Setup steps failure
→ stops remaining setup steps
→ does NOT stop session

Task execution failure
→ stops the actual work

When would a true session stop be possible?

A full session abort would require platform level support. Right now Copilot Agent Mode is designed to continue even with partial setup failures.

Practical recommendation

Instead of trying to terminate the session, enforce environment validity checks in scripts and tasks. This gives deterministic control over execution.