webfactory/ssh-agent

When using GitHub Deploy Keys, GitHub servers only accept the first matching key. Because deploy keys are scoped to specific repositories, a standard SSH connection might fail if the wrong key is presented first.

To solve this, the ssh-agent action uses key comments to map keys to specific repositories:

1. Create key with comment: When generating your key, include the repository URL in the comment: ssh-keygen ... -C "git@github.com:owner/repo.git".
2. Automatic Configuration: The action scans these comments and automatically configures Git (using url.<base>.insteadof) and SSH (using a custom hostname/mapping) to ensure that requests to specific repositories use the correct corresponding key.

The ssh-agent action has specific design constraints:

• No File-based Keys: The action loads keys directly into memory (ssh-agent). It does not write keys to disk. Therefore, you cannot pass the key as a Docker build-arg or a mounted file. You must use the SSH agent socket forwarding method.
• No Remote Configuration: If you use the agent to connect to a remote machine via ssh, the action will not automatically configure known_hosts or other SSH settings on that remote machine.
• No Automatic ssh-keyscan: The action does not run ssh-keyscan for you. If you need to add host keys to known_hosts, you should do so via a shell command in your workflow.

When building Docker images using docker build, docker compose build, or the docker/build-push-action, you must explicitly pass the SSH agent socket to the build process to allow the use of private keys during the build.

For standard CLI commands, use the --ssh default=${{ env.SSH_AUTH_SOCK }} flag.

For the docker/build-push-action, use the ssh input.

      - name: Build and push
        id: docker_build
        uses: docker/build-push-action@v2
        with:
          ssh: |
            default=${{ env.SSH_AUTH_SOCK }}

When using private Git dependencies in Rust on Windows runners, Cargo may fail to clone them. You must force Cargo to use the Git CLI instead of its built-in implementation.

You can do this in two ways:

1. Via a shell step: Run a command to update the .cargo/config.toml file.
2. Via environment variable: Set CARGO_NET_GIT_FETCH_WITH_CLI to true for the entire workflow.

# Option 1: Shell step
      - name: Update cargo config to use Git CLI
        run: Set-Content -Path $env:USERPROFILE\.cargo\config.toml "[net]`ngit-fetch-with-cli = true"

# Option 2: Environment variable
env:
  CARGO_NET_GIT_FETCH_WITH_CLI: true

When generating keys to use with this action, ensure the key does not have a passphrase. The action requires the key to be usable without manual input.

Recommended generation commands:

• Ed25519 (Recommended): ssh-keygen -t ed25519 -a 100 -f path/to/keyfile
• RSA (Legacy): ssh-keygen -t rsa -b 4096 -o -f path/to/keyfile

When the ssh-agent action runs, it automatically exports environment variables that allow subsequent steps in your workflow to communicate with the running SSH agent.

Specifically, it exports:

• SSH_AUTH_SOCK: The path to the authentication socket.
• SSH_AGENT_PID: The process ID of the running ssh-agent.

These variables are set as job-level environment variables, meaning they are available to all following steps in the same job.

The action detects if any keys added to the agent are intended as GitHub Deploy Keys by inspecting their comments for a GitHub URL pattern (github.com:owner/repo).

If a match is found, the action performs the following setup:

1. Key Storage: Saves the public key to ~/.ssh/key-<sha256_hash> with 600 permissions.
2. SSH Config: Appends a configuration block to ~/.ssh/config using the Host key-<sha256_hash>.github.com pattern to ensure the correct IdentityFile is used for that specific repository.
3. Git Configuration: Configures Git to use the specific identity for GitHub URLs via insteadOf rules for:
   • https://github.com/owner/repo
   • git@github.com:owner/repo
   • ssh://git@github.com/owner/repo

If you encounter the error Error loading key "(stdin)": invalid format, your private key is likely not in PEM format. The action requires PEM format.

You can convert your key to PEM using the following command (ensure you have a backup first): ssh-keygen -p -f path/to/your/key -m pem

If you need to access multiple private repositories that use different deploy keys, you can pass multiple keys to the ssh-private-key input by providing them as a multi-line string. The ssh-agent will load all keys and attempt to use them in order during SSH connections.

Caveat: Some SSH servers may abort connections after a certain number of failed key attempts. If you have too many keys, the correct one might not be reached.

            - uses: webfactory/ssh-agent@v0.9.0
              with:
                  ssh-private-key: |
                        ${{ secrets.FIRST_KEY }}
                        ${{ secrets.NEXT_KEY }}
                        ${{ secrets.ANOTHER_KEY }}