Process completed with exit code 128 – Meaning, Causes, and How to Fix

Quick Answer

When a GitHub Actions workflow ends with “Process completed with exit code 128”, it usually means a Git command inside the job failed with a fatal error.

In most cases, the exit code itself is not the real issue. It simply indicates that Git stopped execution because something went wrong — authentication problems, missing repositories, or invalid references are common triggers.

To understand what actually failed, you need to check the log lines right above the exit code message, where Git normally prints the underlying error.

What this error means

If you see the message:

Process completed with exit code 128

inside a CI job, the runner is simply reporting the exit status returned by the command that ran in that step.

Git commands return numeric exit codes to indicate their outcome. A value of 0 means success, while any non-zero value signals a failure.

Exit code 128 is typically used by Git to report a fatal condition — meaning something prevented the command from completing safely.

Because of this behavior, the message printed at the end of the CI log rarely explains the real cause. The diagnostic message almost always appears earlier in the logs.

Why this happens

In CI environments such as GitHub Actions, workflows frequently run Git commands like cloning repositories, fetching branches, checking out commits, or initializing submodules.

Exit code 128 appears when Git cannot complete one of these operations.

Typical reasons include:

• the runner cannot authenticate with the repository
• the repository URL is incorrect
• the referenced branch or tag does not exist
• a private repository requires permissions that the workflow does not have
• submodules require additional credentials

Since Git treats these situations as fatal errors, it terminates immediately and returns exit code 128.

Exit code reference table

CI logs may contain various exit codes depending on the type of failure. The following table summarizes several common ones developers encounter during automated builds.

Common scenarios

Developers typically encounter this error in the following situations:

• a workflow attempts to clone a private repository without authentication
• the repository URL in the workflow configuration is incorrect
• a branch referenced in the workflow does not exist
• a Git submodule cannot be accessed
• repository permissions restrict the CI runner

These issues usually appear during the checkout stage of a workflow when the CI system retrieves the source code before building or testing.

How to fix

The correct solution depends on the underlying cause shown earlier in the logs.

Scenario A — Authentication failure

Why this happens

The workflow does not have permission to access the repository. This commonly occurs when cloning private repositories or accessing private submodules.

How to fix it

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

If external repositories are involved, you may need to provide a Personal Access Token.

Verification

• re-run the workflow
• confirm the checkout step completes successfully

Scenario B — Repository or branch not found

Why this happens

The workflow references a repository or branch that does not exist.

How to fix it

git ls-remote https://github.com/owner/repository

This command lists all available branches and tags so you can confirm the reference is correct.

Verification

• update the repository URL or branch name
• run the workflow again

Scenario C — Submodule access failure

Why this happens

Projects using Git submodules may require additional authentication.

How to fix it

- uses: actions/checkout@v4
  with:
    submodules: true

If the submodule repository is private, ensure the token used by the workflow has access permissions.

Verification

• check that submodule directories populate correctly

Example logs

Authentication failure example:

Cloning into 'repository'...
fatal: Authentication failed for 'https://github.com/org/repo'
Process completed with exit code 128

Repository not found example:

fatal: repository 'https://github.com/org/repo/' not found
Process completed with exit code 128

The fatal error printed above the exit code usually explains the real problem.

How to confirm the issue is resolved

After applying the fix, run the workflow again.

Expected results:

• the checkout step completes successfully
• the workflow continues to the next stage
• the process exits with status code 0

You should no longer see:

Process completed with exit code 128

FAQ

What does exit code 128 mean in GitHub Actions?

It indicates that a Git command failed with a fatal error. The CI runner simply reports the exit status returned by Git.

How do I find the real cause of exit code 128?

Look at the lines above the exit code message in the workflow logs. Git normally prints the detailed error message before terminating.

Is exit code 128 always related to Git?

Almost always. In CI environments, exit code 128 usually originates from Git operations such as clone, fetch, or checkout.

Why does Git return exit code 128 for authentication errors?

Git treats authentication failures as fatal conditions because repository operations cannot continue without valid credentials.

Related errors

• Process completed with exit code 1
• Build failed with exit code 17

Category / Hub link

This error belongs to the CI Execution category within GitHub Actions workflows.

Category hub:

/github-actions/errors/ci-execution/