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.

Prepare 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

  1. In Astra, create 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.

  2. 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

  1. At the root of your GitHub repository’s default branch, create .github/workflows directories.

  2. 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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com