GX cloud

Quick Start

To use the GX Agent, you will need to have a Great Expectations Cloud account. You can sign up for free at https://app.greatexpectations.io.

Deployment instructions for the GX Agent can be found in the GX Cloud documentation.

Contributing

Follow these steps to create a development environment:

Use the version of Python specified in .python-version
- confirm with python --version
Use the version of Poetry specified in poetry.lock
- confirm with poetry --version
Set up virtual environment and install dependencies
- poetry sync
Activate your virtual environment
- eval $(poetry env activate)
Set up precommit hooks
- pre-commit install

Troubleshooting

If you run into issues, you can try pipx reinstall-all

Running locally for development

$ gx-agent --help
usage: gx-agent [-h] [--log-level LOG_LEVEL] [--skip-log-file SKIP_LOG_FILE] [--log-cfg-file LOG_CFG_FILE] [--version]

optional arguments:
  -h, --help            show this help message and exit
  --log-level LOG_LEVEL
                        Level of logging to use. Defaults to WARNING.
  --skip-log-file SKIP_LOG_FILE
                        Skip writing debug logs to a file. Defaults to False. Does not affect logging to stdout/stderr.
  --log-cfg-file LOG_CFG_FILE
                        Path to a logging configuration json file. Supersedes --log-level and --skip-log-file.
  --version             Show the GX Agent version.

Set ENV variables

GX_CLOUD_ACCESS_TOKEN GX_CLOUD_ORGANIZATION_ID

If you want to override where the GX Agent looks for the RabbitMQ queue you can also set AMQP_HOST_OVERRIDE and AMQP_PORT_OVERRIDE. For example, if you are running a local dockerized RabbitMQ service exposed on localhost port 5672, you can set AMQP_HOST_OVERRIDE=127.0.0.1 and AMQP_PORT_OVERRIDE=5672.

Start the GX Agent

If you intend to run the GX Agent against local services (Cloud backend or datasources) run the Agent outside of the container.

gx-agent

Developer Tasks

Common developer tasks are available via invoke (defined in tasks.py).

invoke --list to see available tasks.

Synchronize Dependencies

To ensure you are using the latest version of the core and development dependencies run poetry sync. Also available as an invoke task.

invoke deps

Updating `poetry.lock` dependencies

Use the latest version of poetry

pipx upgrade poetry

The dependencies installed in our CI and the Docker build step are determined by the poetry.lock file.

To update only a specific dependency (such as great_expectations) ...

poetry update great_expectations

Note: If poetry update does not find the latest version of great_expectations, you can manually update the version in pyproject.toml, and then update the lockfile using poetry lock.

To resolve and update all dependencies ...

poetry lock

In either case, the updated poetry.lock file must be committed and merged to main.

Building and Running the GX Agent Image

To build the GX Agent Docker image, run the following in the root dir:

invoke docker

Running the GX Agent:

invoke docker --run

docker run --env GX_CLOUD_ACCESS_TOKEN="<GX_TOKEN>" --env GX_CLOUD_ORGANIZATION_ID="<GX_ORG_ID>" gx/agent

Now go into GX Cloud and issue commands for the GX Agent to run, such as generating an Expectation Suite for a Data Source.

Note if you are pushing out a new image update the image tag version in containerize-agent.yaml. The image will be built and pushed out via GitHub Actions.

Example Data

The contents from /examples/agent/data will be copied to /data for the Docker container.

Adding an action to the Agent

Make a new action in great_expectations_cloud/agent/actions/ in a separate file.
Register your action in the file it was created in using great_expectations_cloud.agent.event_handler.register_event_action(). Register for the major version of GX Core that the action applies to, e.g. register_event_action("1", RunCheckpointEvent, RunCheckpointAction) registers the action for major version 1 of GX Core (e.g. 1.0.0).
Import your action in great_expectations_cloud/agent/actions/__init__.py

Note: The Agent is core-version specific but this registration mechanism allows us to preemptively work on actions for future versions of GX Core while still supporting the existing latest major version.

Release Process

Versioning

This is the version that will be used for the Docker image tag as well.

Standard Release: The versioning scheme is YYYYMMDD.{release_number} where:

the date is the date of the release
the release number starts at 0 for the first release of the day
the release number is incremented for each release within the same day

For example: 20240402.0

Pre-release: The versioning scheme is YYYYMMDD.{release_number}.dev{dev_number}

the date is the date of the release
the dev number starts at 0 for the first pre-release of the day
the dev number is incremented for each pre-release within the same day
the release number is the release that this pre-release is for

For example: 20240403.0.dev0 is the first pre-release for the 20240403.0 release.

For example, imagine the following sequence of releases given for a day with two releases:

20240403.0.dev0
20240403.0.dev1
20240403.0
20240403.1.dev0
20240403.1

There can be days with no standard releases, only pre-releases or days with no pre-release or standard release at all.

Pre-releases

Pre-releases are completed automatically with each merge to the main branch. The version is updated in pyproject.toml and a pre-release is created on PyPi. A new Docker tag will also be generated and pushed to Docker Hub

Manual Pre-releases

NOTE: CI will automatically create pre-releases on merges to main. Instead of manually creating pre-releases, consider using the CI process. This is only for exceptional cases.

To manually create a pre-release, run the following command to update the version in pyproject.toml and then merge it to main in a standalone PR:

invoke pre-release

This will create a new pre-release version. On the next merge to main, the release will be uploaded to PyPi. A new Docker tag will also be generated and pushed to Docker Hub

Releases

Releases will be completed on a regular basis by the maintainers of the project and with any release of GX Core

For maintainers, to create a release, run the following command to update the version in pyproject.toml and then merge it to main in a standalone PR:

invoke release

This will create a new release version. On the next merge to main, the release will be uploaded to PyPi. A new Docker tag will also be generated and pushed to Docker Hub. In addition, releases will be tagged with stable and latest tags.

GitHub Workflow for releasing

We use the GitHub Actions workflow to automate the release and pre-release process. There are two workflows involved:

CI - This workflow runs on each pull request and will update the version in pyproject.toml to the pre-release version if the version is not already manually updated in the PR. It will also run the tests and linting.
Containerize Agent - This workflows runs on merge with main and will create a new Docker image and push it to Docker Hub and PyPi. It uses the version in pyproject.toml.

A visual representation of the workflow is shown here

Dependabot and Releases/Pre-releases

GitHub's Dependabot regularly checks our dependencies for vulnerabilty-based updates and proposes PRs to update dependency version numbers accordingly.

Dependabot may only update the poetry.lock file. If only changes to poetry.lock are made, this may be done in a pre-release.

For changes to the pyproject.toml file:

If the version of a tool in the [tool.poetry.group.dev.dependencies] group is updated, this may be done without any version bump.
- While doing this, make sure any version references in the pre-commit config .pre-commit-config.yaml are kept in sync (e.g., ruff).
For other dependency updates or package build metadata changes, a new release should be orchestrated. This includes updates in the following sections:
- [tool.poetry.dependencies]
- [tool.poetry.group.*.dependencies] where * is the name of the group (not including the dev group)
To stop the auto-version bump add the no version bump label to the PR. Use this when:
- Only modifying dev dependencies.
- Only modifying tests that do not change functionality.

NOTE: Dependabot does not have permissions to access secrets in our CI. You may notice that integration tests fail on PRs that dependabot creates. If you add a commit (as a GX member) to the PR, the tests will run again and pass because they now have access to the secrets. That commit can be anything, including an empty commit e.g. git commit -m "some message" --allow-empty.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

great_expectations_cloud-20260416.0.tar.gz (80.8 kB view details)

Uploaded Apr 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

great_expectations_cloud-20260416.0-py3-none-any.whl (104.0 kB view details)

Uploaded Apr 16, 2026 Python 3

File details

Details for the file great_expectations_cloud-20260416.0.tar.gz.

File metadata

Download URL: great_expectations_cloud-20260416.0.tar.gz
Upload date: Apr 16, 2026
Size: 80.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for great_expectations_cloud-20260416.0.tar.gz
Algorithm	Hash digest
SHA256	`44730f236bcb99e84bba3b9adc875caddaed40249d9dbd3e1e14ec62a00e15fb`
MD5	`786d06a7ba3e8badb7bccf902f21dc78`
BLAKE2b-256	`3835b46f5e536a463c66158846d1a67c263bce2b8f300681b599c937a3b64eca`

See more details on using hashes here.

Provenance

The following attestation bundles were made for great_expectations_cloud-20260416.0.tar.gz:

Publisher: publish-to-pypi.yaml on great-expectations/cloud

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: great_expectations_cloud-20260416.0.tar.gz
- Subject digest: 44730f236bcb99e84bba3b9adc875caddaed40249d9dbd3e1e14ec62a00e15fb
- Sigstore transparency entry: 1319950653
- Sigstore integration time: Apr 16, 2026
Source repository:
- Permalink: great-expectations/cloud@eef39a6a91cffa54fde860105c4aa8abafdf1eec
- Branch / Tag: refs/heads/main
- Owner: https://github.com/great-expectations
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-to-pypi.yaml@eef39a6a91cffa54fde860105c4aa8abafdf1eec
- Trigger Event: push