webfactory/ssh-agent

Start ssh-agent and load a private key so a workflow can access other private repositories.

Community actionCategory: Source & CheckoutLatest v0.10View on GitHub

What it does

webfactory/ssh-agent runs ssh-agent, loads the private key you pass in, and exports the agent socket so every later step (git clone, npm/pip/go installs of private git dependencies, submodule checkout) can authenticate over SSH.

A post-run cleanup step stops the agent and removes the key from the runner when the job ends.

Usage

workflow (.yml)

steps:
  - uses: webfactory/ssh-agent@v0.10.0
    with:
      ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
  - uses: actions/checkout@v4
    with:
      submodules: recursive   # private submodules now clone over SSH
  - run: npm ci               # private git deps resolve too

Inputs

Input	Description	Default	Required
`ssh-private-key`	Private SSH key to register in the SSH agent.	-	Yes
`ssh-auth-sock`	Where to place the SSH Agent auth socket.	-	No
`log-public-key`	Whether or not to log public key fingerprints.	`true`	No

Notes

Run it before the step that needs SSH access (including checkout, when private submodules are involved).

ssh-private-key accepts multiple keys. When using multiple GitHub deploy keys, the key comment must contain the URL of the repository the key belongs to, so the action can route each host alias to the right key.

Common errors

Error loading key "(stdin)": invalid format means the secret is not a complete PEM private key, most often a missing trailing newline after -----END ... PRIVATE KEY-----, a truncated paste, or the public key pasted by mistake.
Permission denied (publickey) means the loaded key is not authorized for the target repo: the matching public key must be added as a deploy key or to a machine user.

Security and pinning

Prefer a read-only deploy key scoped to the one repository you need over a personal key with account-wide access.
Pin the action to a commit SHA, this action handles a raw private key, so supply-chain caution applies doubly.

Alternatives and related

actions/checkoutCheck out your repository so a workflow can access its code. actions/create-github-app-tokenMint a short-lived GitHub App installation token to use instead of a PAT or GITHUB_TOKEN.

Frequently asked questions

Why not just use a personal access token instead of SSH?

A PAT in a URL grants everything its scopes allow across your account. A deploy key loaded via ssh-agent can be read-only and scoped to a single repository, which is the least-privilege option for one private dependency.

Can I load keys for several private repositories?

Yes, pass multiple keys in ssh-private-key. For multiple GitHub deploy keys, set each key's comment to the repo URL it unlocks so the action can map hosts to keys.