> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt # 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. 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`. ```yaml 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@v3 with: surrealdb_version: latest surrealdb_port: 8000 surrealdb_username: root surrealdb_password: secret surrealdb_auth: false surrealdb_strict: false surrealdb_log: info surrealdb_additional_args: --allow-all surrealdb_retry_count: 30 ``` ## Step 2: Customise workflow arguments The official SurrealDB GitHub Action accepts several arguments to configure the SurrealDB setup. The table below lists the available arguments and their defaults:

Argument	Description	Default	Value
surrealdb_version	SurrealDB version to use	latest	latest, nightly, beta, alpha, v1.x.x, v2.x.x, v3.x.x
surrealdb_datastore	Datastore to start SurrealDB with	memory	Any valid datastore path, for example rocksdb:data
surrealdb_port	Port to run SurrealDB on	8000	Valid number from 0 to 65535
surrealdb_username	Username to use for SurrealDB	root	Customisable by the user
surrealdb_password	Password to use for SurrealDB	root	Customisable by the user
surrealdb_auth	Enable authentication	false	true, false
surrealdb_strict	Enable strict mode	false	true, false
surrealdb_log	Enable logs	trace	none, full, error, warn, info, debug, trace
surrealdb_import_file	SurrealQL file to import on startup		Path to a .surql file, requires SurrealDB v3.0.0 or later
surrealdb_additional_args	Additional arguments for SurrealDB		Any valid SurrealDB CLI arguments
surrealdb_retry_count	Seconds to wait for SurrealDB to become ready	30	Any valid integer

The file passed to `surrealdb_import_file` selects its own namespace and database, so it should begin with a `USE NS ... DB ...;` statement. ### Workflow outputs The action exposes the details of the instance it started, so that later steps do not have to reconstruct them:

Output	Description
endpoint	The HTTP endpoint the SurrealDB instance is listening on
version	The exact version of SurrealDB that was installed

### Example configuration Here is an example configuration that sets specific values for each argument: ```yaml name: SurrealDB CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - name: Git checkout uses: actions/checkout@v4 - name: Start SurrealDB id: surrealdb uses: surrealdb/setup-surreal@v3 with: surrealdb_version: latest surrealdb_port: 8000 surrealdb_username: root surrealdb_password: secret surrealdb_auth: false surrealdb_strict: false surrealdb_log: info surrealdb_additional_args: --allow-all surrealdb_retry_count: 30 - name: Run the tests run: ./run-tests.sh env: SURREALDB_ENDPOINT: ${{ steps.surrealdb.outputs.endpoint }} ``` ### Tips for customisation 1. **Version Control**: Use specific versions to avoid unexpected changes. Example: surrealdb_version: v3.2.4. 2. **Security**: Always use strong passwords for surrealdb_password and avoid using default credentials in production. 3. **Logs**: Set an appropriate log level based on your needs. For debugging, use debug or trace. 4. **Additional Arguments**: Use 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: ```sh 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.