Fixing GitHub Actions ‘checkout’ Authentication Failure on macOS Local Environments

Troubleshoot repository authentication failures for the 'actions/checkout' action on macOS when running GitHub Actions locally. Resolve common PAT, SSH, and credential helper issues.

When developing or testing GitHub Actions workflows locally on a macOS machine, leveraging tools like act or a self-hosted runner, you might encounter issues with the actions/checkout action failing to authenticate. This typically manifests as an inability to clone private repositories, halting your workflow execution. This guide details the common causes and provides comprehensive, step-by-step solutions to resolve these authentication challenges.

Symptom & Error Signature

The primary symptom is the GitHub Actions checkout step failing, usually with messages indicating authentication problems when trying to access a repository, especially a private one.

You might see error messages similar to these in your local GitHub Actions runner or act output:

Run actions/checkout@v4
  with:
    repository: your-org/your-private-repo
    ref: main
    token: ***
    path: .
Cloning into '.'...
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.
fatal: Authentication failed for 'https://github.com/your-org/your-private-repo.git/'
##[error]Git post-checkout failed.
Error: Git post-checkout failed.

Or, if using SSH for Git operations:

Run actions/checkout@v4
  with:
    repository: your-org/your-private-repo
    ref: main
    token: ***
    path: .
Cloning into '.'...
[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
##[error]Git post-checkout failed.
Error: Git post-checkout failed.

Root Cause Analysis

The actions/checkout action internally uses Git commands to clone the specified repository. On a macOS local environment, authentication failures typically stem from one of the following underlying reasons:

1. Incorrect or Missing Git Credentials:

   • HTTPS: Git requires a Personal Access Token (PAT) for HTTPS authentication to GitHub after the deprecation of password authentication. If no PAT is configured, or an invalid/expired one is used, authentication will fail. The macOS Keychain Access utility is commonly used by Git's credential helper to store these.
   • SSH: If Git is configured to use SSH, the system needs to find a valid SSH key (private key) that is added to ssh-agent and whose corresponding public key is registered with GitHub (either in your user settings or as a deploy key on the repository). Incorrect permissions on the SSH key file, or the key not being known to the agent, will prevent authentication.

2. Insufficient Token Scope: If a Personal Access Token (PAT) is provided, it might lack the necessary scopes (e.g., repo scope for private repositories) to access the target repository.

3. Credential Helper Misconfiguration: Git's credential helpers (like osxkeychain on macOS) are crucial for caching credentials. If this helper is not correctly configured or has stale entries, Git might fail to retrieve the necessary authentication details.

4. Environment Variables: When using tools like act, the GITHUB_TOKEN environment variable or other credential-related variables might not be correctly passed or set within the local workflow's execution context.

5. Network/Firewall Restrictions: While less common for local environments, a strict local firewall, VPN, or corporate proxy could potentially interfere with Git's ability to connect to GitHub.

6. Repository Access Rights: The GitHub user or machine account associated with the provided credentials simply does not have read access to the specified repository.

Step-by-Step Resolution

Follow these steps to diagnose and resolve GitHub Actions checkout authentication issues on your macOS local environment.

1. Verify Git Configuration and Credential Helper

First, check your global Git configuration to understand how it's set up for credential management.

git config --global --list

Look for lines related to credential.helper and ensure it's set appropriately for macOS.

credential.helper=osxkeychain

If credential.helper is not osxkeychain, set it:

git config --global credential.helper osxkeychain

The osxkeychain helper stores your Git credentials securely in macOS's Keychain Access. This is the recommended approach for HTTPS authentication on macOS.

2. Configure Authentication Method: Personal Access Token (PAT)

This is the most common and recommended method for actions/checkout with HTTPS.

A. Generate a GitHub Personal Access Token (PAT)

1. Navigate to your GitHub account settings.
2. Go to Developer settings > Personal access tokens > Tokens (classic).
3. Click Generate new token > Generate new token (classic).
4. Give it a descriptive name (e.g., "macOS local CI/CD").
5. Scopes: Crucially, select the repo scope to grant full control over private repositories. For read-only access to private repositories, repo is often still the simplest. If you require more granular control, repo:status, repo_deployment, and public_repo might suffice for read-only.
6. Set an expiration date (or choose "No expiration" if you manage rotation carefully).
7. Click Generate token.
8. Copy the token immediately. You won't see it again.

Treat your PAT like a password. Do not hardcode it directly into scripts or publicly accessible files. Use environment variables or Git's credential helper.

B. Store PAT in macOS Keychain (for Git HTTPS)

To store the PAT for Git's HTTPS operations, simply perform a git clone or git pull operation on a private repository via HTTPS, and when prompted, use your GitHub username and the generated PAT as the password. The osxkeychain helper will then store it.

# Example: Try to clone a private repo.
# Replace 'your-org/your-private-repo' with an actual private repo you have access to.
git clone https://github.com/your-org/your-private-repo.git

When prompted for Username for 'https://github.com':, enter your GitHub username. When prompted for Password for 'https://[email protected]':, paste your PAT.

After this, Git will use the stored PAT for subsequent HTTPS operations. You can verify the entry in Keychain Access.app by searching for "github.com".

C. Pass PAT to act (or similar local runner)

If you are using act to run workflows locally, you can pass the PAT as an environment variable or secret.

# Pass as an environment variable
GITHUB_TOKEN="your_generated_pat" act pull_request

# Or, if your workflow explicitly uses a secret named GITHUB_TOKEN_FOR_CHECKOUT
act -s GITHUB_TOKEN_FOR_CHECKOUT="your_generated_pat" pull_request

When using actions/checkout in a GitHub Actions workflow, you usually don't need to specify a token if checking out the repository the workflow belongs to. It automatically uses the built-in GITHUB_TOKEN which has appropriate permissions for that specific repository. However, for checking out other private repositories, you must provide a PAT with repo scope as shown.

3. Configure Authentication Method: SSH Key

If your Git setup prefers SSH (e.g., git clone [email protected]:your-org/your-private-repo.git), ensure your SSH key is correctly configured.

A. Verify SSH Key Existence and Permissions

Check if you have an SSH key in ~/.ssh/. Common key names are id_rsa or id_ed25519.

ls -la ~/.ssh/

Ensure private keys have strict permissions:

chmod 600 ~/.ssh/id_rsa # or id_ed25519

B. Add SSH Key to ssh-agent

Start the ssh-agent if it's not running and add your key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa # or ~/.ssh/id_ed25519

You can verify keys added to the agent with ssh-add -l.

C. Configure ~/.ssh/config

It's good practice to have a robust SSH configuration for GitHub. Create or edit ~/.ssh/config:

nano ~/.ssh/config

Add the following (if not already present), replacing id_rsa or id_ed25519 with your actual private key file.

Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519 # Or ~/.ssh/id_rsa
  IdentitiesOnly yes
  User git

The UseKeychain yes directive, specific to macOS, tells ssh-agent to store passphrases in the macOS Keychain.

D. Add Public Key to GitHub

Ensure the public key (~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub) corresponding to your private key is added to your GitHub account settings under SSH and GPG keys or as a Deploy key on the target repository.

To get your public key:

cat ~/.ssh/id_ed25519.pub

Copy the entire output and paste it into GitHub.

4. Use GitHub CLI for Authentication (gh auth login)

The GitHub CLI (gh) can simplify authentication by setting up Git credentials for you, often using PATs.

1. Install GitHub CLI if you haven't:

   brew install gh
   

2. Authenticate:

   gh auth login
   

   Follow the prompts:
   • Choose GitHub.com.
   • Choose HTTPS (recommended for actions checkout).
   • Choose Login with a web browser.
   • Press Enter to open your browser, authorize the CLI, and paste the code if prompted.
   • Choose Authenticate Git with your GitHub credentials.
   • This will configure Git's credential helper (likely osxkeychain) to use a PAT generated by gh.

After successful authentication, try running your local GitHub Actions again.

5. Verify Repository Access and Permissions

Double-check that the GitHub user account associated with your PAT or SSH key actually has read access to the private repository in question. Sometimes, a PAT might belong to a different user, or a deploy key might have expired or been removed.

6. Clear Stale Credential Cache (if issues persist)

If you've tried multiple authentication methods or tokens, your macOS Keychain or Git's cache might hold stale credentials.

1. Clear Git's credential cache explicitly:

   git credential-osxkeychain erase host=github.com protocol=https
   

2. Manually check Keychain Access.app: Open Keychain Access.app (search in Spotlight). Search for "github.com". You might find entries like "github.com" or "git:https://github.com". Delete any entries that seem old or incorrect.

7. Network and Proxy Considerations

While less common for local authentication, ensure basic connectivity:

ping github.com
curl -v https://github.com

If you are behind a corporate proxy, ensure your Git and SSH configurations include proxy settings.

For Git (HTTPS):

git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy https://proxy.example.com:8080

For SSH: You might need ProxyCommand in your ~/.ssh/config or use tools like corkscrew.

Host github.com
  ProxyCommand nc -X connect -x proxy.example.com:8080 %h %p

After implementing these steps, retry running your GitHub Actions locally. The actions/checkout step should now successfully authenticate and clone your repositories.