Troubleshooting GitHub Actions deployment failures with Porter

Last updated: September 19, 2025

GitHub Actions deployments to Porter can fail for various reasons. This guide covers the most common issues and their solutions.

Common Error Messages and Solutions

"cluster is not reachable"

This error typically indicates a temporary connectivity issue between GitHub Actions and Porter's API.

Solution: Push a fresh commit to trigger a new deployment. Avoid re-running failed GitHub Actions as they use the original context.

"missing source type"

This error occurs when there's a configuration issue with your Porter YAML file or environment variables.

Solution: Ensure your porter.yaml file includes the required build section:

build:
  context: ./
  method: docker
  dockerfile: ./Dockerfile

"unable to find latest environment with provided name"

This error happens when environment groups referenced in your porter.yaml don't exist on the target cluster.

Solution: Create the same environment group on all clusters where you're deploying, or remove the envGroups section from your porter.yaml if not needed.

"exec format error"

This occurs when there's an architecture mismatch between your Docker image and cluster nodes.

Solution: Ensure you're building for the correct architecture (typically AMD64). If using Docker, add platform specification to your build process.

Authentication Issues

Expired Porter Tokens

If deployments fail with authentication errors, your Porter token may have expired.

Solution: Generate a new Porter token in Project Settings > API Tokens and update the corresponding GitHub secret (e.g., PORTER_APP_[PROJECT_ID]_[CLUSTER_ID]).

GitHub Integration Issues

If builds aren't showing up in the Porter dashboard, there may be an issue with GitHub integration.

Solution: Go to User Icon in the top-right of the dashboard and then Account Settings in Porter and re-authorize GitHub access. Hard refresh your browser after authorization.

Build and Deployment Timeouts

The default timeout for Porter deployments in GitHub Actions is 30 minutes.

Solution: If your builds take longer, increase the timeout in your workflow file:

- name: Deploy stack
  timeout-minutes: 45
  run: exec porter apply

Resource and Configuration Issues

Resource Validation Errors

Errors like "could not find resources for node" indicate resource allocation issues.

Solution: Check your resource requests in the Porter dashboard or porter.yaml file and ensure they don't exceed cluster capacity.

Missing Porter YAML

If your porter.yaml file is missing or incorrectly referenced, deployments may fail silently or with validation errors.

Solution: Ensure the porter.yaml file exists at the specified path in your repository and contains the required configuration sections.

General Troubleshooting Steps

  1. Check GitHub Actions logs: Review the full logs in the GitHub Actions tab for detailed error messages.

  2. Verify environment variables: Ensure all required Porter environment variables are correctly set in your workflow.

  3. Try a fresh commit: Push a new commit rather than re-running failed actions.

  4. Check Porter dashboard: Look for additional error details or logs in the Porter dashboard.

  5. Validate configuration: Ensure your porter.yaml file and GitHub workflow are properly configured.

If issues persist after trying these solutions, check Porter's status page or contact support with your full GitHub Actions logs and workflow configuration.