Setup SSH Agent

Configures SSH agent with private keys for Forgejo CI/CD workflows.

Quick Start

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: docker
    steps:
      - uses: actions/checkout@v6
      - name: Setup SSH
        uses: actions/setup-ssh@v1
        with:
          ssh-key: ${{ secrets.DEPLOY_KEY }}
      - name: Rsync your website
        run: rsync -e 'ssh -o StrictHostKeyChecking=no' -cavz --delete dist/ xyz00-website@xyz00.hostsharing.net:doms/example.com/htdocs-ssl/

How It Works

This action spawns an SSH agent with a unique socket path, loads your private key into memory, and exports SSH_AUTH_SOCK and SSH_AGENT_PID for subsequent workflow steps. The agent is automatically cleaned up after your job completes via a post-action hook.

How to Provide SSH Key

1. Create a temporary directory and generate a new SSH key:

   cd $(mktemp -d)
   ssh-keygen -t ed25519 -C 'forgejo action your-username/your-repo' -f id_ed25519
   

2. Copy the public key to the server's .ssh/authorized_keys file.

3. Set the private key as a Forgejo secret:

   export FORGEJO_TOKEN="dein_api_key_hier"
   bash <(curl -s https://forge.sebatec.eu/actions/setup-ssh/raw/tag/v1/upload-secret.sh) -r your-username/your-repo -s DEPLOY_KEY -f id_ed25519
   

   Tip

   Generate your FORGEJO_TOKEN at forge.sebatec.eu/user/settings/applications

4. Securely delete the local key files:

   shred id_ed25519* && rm id_ed25519*
   

Inputs

Name	Required	Description	Default
ssh-key	Yes	Private SSH key (RSA, Ed25519, etc.) for authentication	-
ssh-auth-sock	No	Custom socket path for SSH agent. Typically only needed for Docker actions; use workspace path if customizing.	/tmp/ssh_agent-{uuid}.sock
ssh-config	No	Content to write to ~/.ssh/config. Enables SSH connection control path pooling and other settings.	Default with ControlMaster, ControlPath, ControlPersist

Note

Custom socket paths are generally not recommended unless you're using Docker actions that require socket access from within containers.

Environment Variables

The action exports the following environment variables for use in subsequent workflow steps:

Variable	Value	Purpose
SSH_AUTH_SOCK	Socket path (default: /tmp/ssh_agent-{uuid}.sock)	Unix socket for SSH agent communication. Required by SSH tools (ssh, git, scp, etc.)
SSH_AGENT_PID	Process ID of the SSH agent	Used for cleanup and debugging

Note

If using Docker actions that need SSH access, set ssh-auth-sock to a workspace-relative path (e.g., ${{ forgejo.workspace }}/.ssh-agent.sock) so the socket is accessible inside containers. This is not recommended for standard workflows.

Usage Examples

Example 1: Clone Private Repository

name: CI
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - name: Setup SSH
        uses: actions/setup-ssh@v1
        with:
          ssh-key: ${{ secrets.DEPLOY_KEY }}

      - name: Clone Dependencies
        run: |
          git clone git@github.com:your-org/private-lib.git
          cd private-lib && npm install

Example 2: Deploy via SCP/Rsync

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    if: forgejo.repository == 'your-username/your-repo'
    runs-on: docker
    steps:
      - uses: actions/checkout@v6

      - name: Setup SSH
        uses: actions/setup-ssh@v1
        with:
          ssh-key: ${{ secrets.DEPLOY_KEY }}

      - name: Deploy to Server
        run: rsync -e 'ssh -o StrictHostKeyChecking=no' -cavz --delete dist/ xyz00-website@xyz00.hostsharing.net:doms/example.com/htdocs-ssl/

Example 3: Customizing SSH Configuration

By default, the action writes SSH connection pooling settings to ~/.ssh/config. You can customize this by providing your own configuration:

name: CI with Custom SSH Config
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - name: Setup SSH
        uses: actions/setup-ssh@v1
        with:
          ssh-key: ${{ secrets.DEPLOY_KEY }}
          ssh-config: |
            Host github.com
                StrictHostKeyChecking no
                User git
            Host *
                ControlPath /tmp/ssh-%r@%h:%p
                ControlMaster auto
                ControlPersist 10m
      - name: Clone and Build
        run: |
          git clone git@github.com:your-org/private-repo.git
          cd private-repo && npm install && npm run build

SSH Config Details

The default SSH config enables SSH multiplexing to reuse connections, boosting performance and preventing connection limit issues when running multiple SSH operations. See the ssh_config man page for detailed documentation.

Security Considerations

Caution

SSH keys must be stored as Forgejo secrets. Never commit private keys to your repository or hardcode them in workflow files.

• Secrets Management: Store SSH keys using Forgejo's secrets feature. Access them via ${{ secrets.SECRET_NAME }} in workflows.
• In-Memory Key Handling: Private keys are piped directly to ssh-add via stdin and never written to the filesystem.
• Dynamic Keys: If generating keys during workflow execution, use echo "::add-mask::$PRIVATE_KEY" to prevent accidental logging.

Contributing

We welcome contributions! Please follow these steps to contribute:

1. Fork the repository.
2. Create a new branch:

   git checkout -b feature-branch
   

3. Make your changes and commit them:

   git commit -m "Description of your changes"
   

4. Push to your fork:

   git push origin feature-branch
   

5. Create a pull request.

Guidelines

• Follow the existing code style.
• Write clear and concise commit messages.
• Ensure your changes do not break existing functionality.
• Update documentation as needed.

License

This project is licensed under the terms specified in the LICENSE file.