GitHub Actions
==============

This guide explains how to integrate Fujin with GitHub Actions for automated deployments.

Prerequisites
-------------

Before setting up GitHub Actions integration, ensure you have:

1. A working Fujin project with a valid ``fujin.toml`` configuration
2. Access to your target deployment server
3. Admin access to your GitHub repository

SSH Key Setup
-------------

For secure authentication between GitHub Actions and your deployment server, you need to set up SSH keys:

**Option 1: Reuse Existing SSH Key (Recommended)**

If you're already using Fujin with your deployment host:

* Locate your existing private key (typically ``~/.ssh/id_rsa`` or ``~/.ssh/id_ed25519``)
* Copy this key for use in your GitHub Actions environment

**Option 2: Generate a Dedicated Deployment Key**

For improved security isolation:

.. code-block:: bash
    
    ssh-keygen -t ed25519 -C "deployment@example.com" -f deployment_key
    ssh-copy-id -i deployment_key.pub user@your-server.com

Configure GitHub Actions
----------------------

1. **Configure Repository Secrets**

   Go to **Settings → Secrets and variables → Actions** and add:
   
   * ``SSH_PRIVATE_KEY``: Your SSH private key content
   * Any application secrets referenced in your configuration

2. **Create Workflow File**

   .. code-block:: yaml
       :caption: .github/workflows/deploy.yml

       name: Deploy Application
       
       on:
         push:
           branches: [ main ]
       
       jobs:
         deploy:
           runs-on: ubuntu-latest
           
           steps:
           - uses: actions/checkout@v3
           
           - name: Set up SSH
             run: |
               mkdir -p ~/.ssh
               echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
               chmod 600 ~/.ssh/id_rsa
               ssh-keyscan -H example.com >> ~/.ssh/known_hosts

           - name: Install uv
             uses: astral-sh/setup-uv@v5
           
           - name: Install Fujin
             run: uv tool install --upgrade fujin-cli
           
           - name: Deploy with Fujin
             run: fujin deploy
             env:
               # Add application secrets here
               SECRET_KEY: ${{ secrets.SECRET_KEY }}
               DATABASE_PASSWORD: ${{ secrets.DATABASE_PASSWORD }}

Environment Configuration
------------------------

For CI/CD environments, configure your application environment variables directly in the ``fujin.toml`` file:

.. code-block:: toml
    :caption: fujin.toml

    [host]
    domain_name = "example.com"
    user = "deploy"
    # Use env property instead of envfile for CI/CD environments
    env = """
    DEBUG=False
    DATABASE_URL=$DATABASE_URL
    """

Handling Secrets
---------------

Sensitive information should be managed securely using Fujin's secrets feature:

.. code-block:: toml
    :caption: fujin.toml

    [secrets]
    adapter = "system"  # Use system environment variables

Secret values will be substituted from your GitHub Actions environment variables at deployment time. For additional secret manager options (Bitwarden, 1Password, Doppler), see the :doc:`../secrets` documentation.