Use SurrealDB in GitHub Actions

This guide will show you how to set up and use the official GitHub Action for SurrealDB in your CI/CD pipeline.

Step 1: Create a New GitHub Workflow File

Create a new YAML file in your repository's .github/workflows directory. You can name the file surrealdb-ci.yml.

name: SurrealDB CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Git checkout
      uses: actions/checkout@v4
    - name: Start SurrealDB
      uses: surrealdb/setup-surreal@v2
      with:
        surrealdb_version: latest
        surrealdb_port: 8000
        surrealdb_username: root
        surrealdb_password: root
        surrealdb_auth: false
        surrealdb_strict: false
        surrealdb_log: info
        surrealdb_additional_args: --allow-all
        surrealdb_retry_count: 30

Step 2: Customize Workflow Arguments

The official SurrealDB GitHub Action accepts several arguments to configure the SurrealDB setup. Here's a breakdown of the available arguments and their defaults:

Argument	Description	Default	Value
surrealdb_version	SurrealDB version to use	latest	latest, v2.x.x
surrealdb_port	Port to run SurrealDB on	8000	Valid number from 0 to 65535
surrealdb_username	Username to use for SurrealDB		Customisable by the user
surrealdb_password	Password to use for SurrealDB		Customisable by the user
surrealdb_auth	Enable authentication		true, false
surrealdb_strict	Enable strict mode		true, false
surrealdb_log	Enable logs		none, full, warn, info, debug, trace
surrealdb_additional_args	Additional arguments for SurrealDB		Any valid SurrealDB CLI arguments

Example Configuration

Here is an example configuration that sets specific values for each argument:

name: SurrealDB CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Git checkout
      uses: actions/checkout@v4
    - name: Start SurrealDB
      uses: surrealdb/setup-surreal@v2
      with:
        surrealdb_version: latest
        surrealdb_port: 8000
        surrealdb_username: root
        surrealdb_password: root
        surrealdb_auth: false
        surrealdb_strict: false
        surrealdb_log: info
        surrealdb_additional_args: --allow-all
        surrealdb_retry_count: 30

Tips for Customization

Version Control: Use specific versions to avoid unexpected changes. Example: surrealdb_version: v2.0.0.
Security: Always use strong passwords for surrealdb_password and avoid using default credentials in production.
Logs: Set an appropriate log level based on your needs. For debugging, use debug or trace.
Additional Arguments: Utilise surrealdb_additional_args to pass any additional CLI arguments required by your setup.

Step 3: Commit and Push

After creating and customising your workflow file, commit and push it to your repository:

git add .github/workflows/surrealdb-ci.yml
git commit -m "Add SurrealDB CI workflow"
git push origin main

Step 4: Verify Workflow Execution

Go to your repository on GitHub and navigate to the "Actions" tab. You should see your workflow running when you push changes or create a pull request. Check the logs to verify that SurrealDB is starting up correctly and that all steps are executed successfully.

Conclusion

Using the official GitHub Action for SurrealDB simplifies the process of setting up and running SurrealDB in your CI/CD pipeline. Customise the workflow as per your project requirements, and ensure you follow best practices for security and version control. Happy coding!