Skip to main content

Self-Managed Repository

Overview​

Self-managed repositories allow you to host and manage your Ganymede flow code within your organization, giving you greater control over version control, CI/CD, and code governance.

Benefits​

With this approach, you can:

  • Version Control: Store your code in your own Git-based repository
  • Standard Git Workflows: Use familiar Git workflows for code reviews, branching, and versioning
  • Custom CI/CD: Implement your own CI/CD pipelines for testing and deploying flows to Ganymede
  • Code Ownership: Maintain code ownership within your organization's infrastructure
  • Tool Integration: Integrate with existing development practices and tools familiar to your team

The setup instructions below explain how to configure the necessary GitHub Actions workflows to synchronize code between your repository and Ganymede environments, ensuring changes can flow both ways while maintaining proper version control.

info

If you run into any challenges configuring the repo, you can compare your self-managed repo to this reference version

Setup​

Initial Repository Setup​

  1. Create a GitHub Repository

    • Create a new GitHub repository in your organization, or use an existing repository

  2. Set Up from Template

    • Create a new repository from this templated repository
    • If you have an existing repository, copy the GitHub Workflows (deploy-from-action.yaml & pull-from-action.yaml) from the template repository
    • Place these workflows in the .github/workflows folder of your repository

Configure Repository Variables and Secrets​

  1. Set Repository Variables

    • Navigate to Settings > Secrets & Variables > Actions in your GitHub repository
    • Create a repository variable named GANYMEDE_SUBDOMAIN
    • Set the value to your corresponding Ganymede subdomain (e.g., if you access Ganymede at https://<tenant>.ganymede.bio, use <tenant>)

  2. Generate API Tokens

    • Generate an API token for each Ganymede environment
    • In the Ganymede UI, create an environment secret with:
      • Name starting with "ganymede_api_key_"
      • A randomly generated value (e.g., from random.org)

  3. Configure Environment Secrets

    • Recommended: Create GitHub environments corresponding to each Ganymede environment
    • Set the secret GANYMEDE_API_TOKEN with the generated API token in the corresponding Ganymede environment
    • Set the variable GANYMEDE_ENVIRONMENT with the name of the Ganymede environment (find this in the URL for the environment in Ganymede, e.g., https://<tenant>.ganymede.bio/<environment>)

Configure Workflows​

  1. Configure pull-from-action.yaml

    • Update the github_username and github_email environment variables to your desired values
    • These credentials will be used for creating pull requests in your GitHub repository
    • Update the environment input choices to match the environments you configured
    • Run the workflow via workflow dispatch for the desired environment to populate your repository with current flows

  2. Configure deploy-from-action.yaml

    • Update the environment input choices to match the environments you configured
    • These environments will correspond to the directory structure of your repository (e.g., dev/..., prod/...)
    • Consider creating multiple actions or jobs if you need to support multiple environments

Usage​

Syncing Code from Ganymede​

  • Pull Latest Changes: Run workflow dispatch on the pull-from-action.yaml workflow to pull the latest flow code
  • Automatic Pull Requests: This will create a pull request with the changes
  • Selective Sync: You can optionally specify a single flow to sync code from
  • Scheduled Sync: The workflow can also be scheduled to run on a cron schedule

Deploying Code to Ganymede​

  • Manual Deployment: Deployment can be triggered using the workflow dispatch action, provided a user email matching a Ganymede user is supplied
  • Automatic Deployment: For automatic deployments, you can set up a GitHub Action to trigger on push events to the repository and use a modified version of the flow-commit-action

Customizing Code Management​

Limitations​

Important Requirements
  • The author email in the deploy-from-action must match an email that is registered in Ganymede
  • If using the push GitHub event, the committer email address is used by default