Integrate GitHub Actions with Astra DB Serverless

query_builder 30 min

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform for pipeline automation.

Your GitHub Actions workflows can connect to your Astra DB Serverless databases and issue DevOps API, Data API, and Astra CLI commands.

Prerequisites

Familiarity with the concepts of CI/CD, unit testing, and integration testing.

Familiarity with GitHub Actions is helpful but not required.
A GitHub account.
A GitHub repository where you want to run a GitHub Actions workflow.
Recommended: One or more Astra DB Serverless databases exclusively for testing that are loaded with test data.

You can create fresh test databases for each workflow run, but this adds to the total runtime, requires extra steps to create, load, and terminate the database with every run, and requires an application token with more expansive permissions.

For more information, see the following section about preparing test databases.

Because Astra is a cloud-based DBaaS offering, if you want to perform unit and integration tests with Astra’s full set of features and APIs, DataStax recommends that you create dedicated test databases in Astra.

You can create separate databases for each developer or team, depending on your testing requirements. With separate databases, your developers are less likely to hit the per-database collection limit, they can keep test data separated, and they can test in relative or absolute isolation. For further separation, you can create separate Astra organizations for each team or environment (development, test, production).

Long-lived test databases are recommended for faster testing and minimal access requirements.

If you choose to terminate the test database after each workflow run, you must recreate and repopulate it for each workflow run. This increases the workflow’s runtime and complexity. For example, your scripts must wait long enough for the database to be created before attempting to write to the test data. Additionally, creating databases requires more expansive credentials than reading and writing to existing databases.

For more information about integrating Astra into your DevOps pipelines, contact your DataStax account representative or DataStax Support.

Store an Astra secret in GitHub

In Astra, generate an application token that can access your test database.

The application token must have sufficient permissions to execute the commands that you will include in your GitHub Actions workflow.

If you have multiple test databases, you can create one token with access to all of your test databases, or you can create a separate token for each database. For more information, see Manage application tokens.
In your GitHub repository, add your Astra application token as a secret. For instructions, see the GitHub documentation on Using secrets in GitHub Actions.

To follow along with this example, name your secret ASTRA_DB_APPLICATION_TOKEN.

Create a GitHub Actions workflow

At the root of your GitHub repository’s default branch, create .github/workflows directories.
In the workflows directory, create a YAML file that contains your workflow script.

The following example workflow installs Astra CLI and uses it to list the collections in a given keyspace:
cli-db-create.yml
```
name: Astra CLI Sample
on:
  push:
    branches:
      - main
jobs:
  cli-get-collections:
    env:
      ASTRA_DB_APPLICATION_TOKEN: ${{ secrets.ASTRA_DB_APPLICATION_TOKEN }}
      ASTRA_DB_ID: DATABASE_ID
      ASTRA_DB_KEYSPACE: KEYSPACE_NAME
      TERM: linux
    runs-on: ubuntu-latest
    steps:

      - name: Checkout
        uses: actions/checkout@v5

      - name: Install Astra CLI
        run: curl -Ls "https://dtsx.io/get-astra-cli" | bash

      - name: Get Collections
        run: |
          echo $ASTRA_DB_ID
          /home/runner/.astra/cli/astra db list-collections $ASTRA_DB_ID -k $ASTRA_DB_KEYSPACE --token $ASTRA_DB_APPLICATION_TOKEN
```
Replace the following:
- ASTRA_DB_APPLICATION_TOKEN: The name of the GitHub secret containing your Astra application token if you used a different name.
- DATABASE_ID: The ID of your test database.
- KEYSPACE_NAME: The name of a keyspace in your test database, such as default_keyspace.
- linux and ubuntu-latest: If you prefer a different platform for your tests, change the TERM and runs-on values as needed. You might also need to modify the run commands if they aren’t compatible with your chosen platform.

Test your workflow

To test your workflow, trigger the workflow using the on event specified in your workflow. For example, the workflow in the previous section runs whenever code is pushed to the main branch of the repository.

Once the workflow starts, you can monitor the workflow’s progress during and after the run.

Next steps

To continue building on the example workflow in this guide, try these next steps:

Instead of using Astra CLI, install a Data API client and run Data API commands in your workflow.
Add more files to your .github and workflows directories as needed to manage dependencies and build a complete workflow.

For more information about writing GitHub Actions workflows, including guides for specific languages, workflow triggers, and managing dependencies, see the GitHub Actions documentation.

Integrate GitHub Actions with Astra DB Serverless

Prerequisites

Prepare test databases

Store an Astra secret in GitHub

Create a GitHub Actions workflow

Test your workflow

Next steps

Was this helpful?

Give Feedback