Skip to main content
Ryvn allows you to define your infrastructure as code using resource-based YAML files stored in a Git repository. This enables you to manage your environments, services, blueprints, and installations as code, providing version control, collaboration, and automated synchronization.

​
Setting Up Git Sync

​
Prerequisites

To start using Infrastructure as Code, you must have already configured or enabled the following:
  • Ryvn GitHub App: Must be connected to your Ryvn organization and any pending permissions must be approved

​
Setup

To configure Git Sync for your organization:
1

Navigate to Settings

Go to the Settings tab in the Ryvn Dashboard
2

Access Git Sync

Click on Git Sync in the settings menu
3

Add Git Sync

  1. Click Add Git Sync button
  2. Select a repository from the dropdown list
  3. Optionally specify a branch name (defaults to the repository’s default branch)
  4. Click Configure to set up the sync
4

Create Resource Files

  1. In your selected repository, create YAML files defining your resources
  2. Each resource uses the kind, metadata, spec structure
  3. Commit and push the files to your repository
5

Monitor Sync Status

  1. Return to the Git Sync page to monitor the sync status
  2. Check for any validation errors or sync failures
  3. Verify that your resources are created in the Ryvn Dashboard
You must have GitHub integration configured and access to the repository you want to sync with.

​
Resource File Structure

Each resource follows a standard pattern with kind, metadata, and spec fields. Ryvn recursively scans all YAML files from your entry point directory and identifies resources by their kind field. 
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Service
metadata:
  name: my-service
spec:
  type: server
  repo: my-org/my-repo
  build:
    context: .
    dockerfile: Dockerfile
Add # yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json at the top of your resource files to enable autocomplete and validation in editors that support YAML Language Server (VS Code, Neovim, etc.).

​
Usage Examples

​
Creating a Helm Chart Installation

Here’s a simple example of creating an environment with a helm-chart installation: 
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Environment
metadata:
  name: production
spec:
  provider:
    type: aws
    accountId: "123456789012"
  installations:
    - name: nginx-ingress
      service: nginx-ingress
      namespace: ingress-nginx
      config: |
        controller:
          replicaCount: 2
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 200m
              memory: 256Mi
          tls:
            secretName: '{{ k8sSecretName "production-tls-cert" }}'
This example installs an nginx-ingress helm chart on the production environment. The configuration sets up the controller with 2 replicas and resource limits, placing the installation in the ingress-nginx namespace. It references a variable group for the TLS certificate — all environment variable groups are automatically available to Helm Chart installations as Kubernetes secrets.
Use variable groups to manage and share secrets across installations. For Helm Chart and Terraform installations, all environment variable groups are automatically available as Kubernetes secrets — reference them in config via k8sSecretName or k8sSecretValue.

​
Reference

See GitOps Reference

​
Managing Secrets with Variable Groups

Variable groups are the recommended way to manage shared secrets and environment variables across installations. They are scoped to environments.
1

Navigate to Variable Groups

Go to the Variable Groups page in the Ryvn Dashboard
2

Create a Group

Click Create, select a target environment, and give the group a name
3

Add Variables

Add your key-value pairs — toggle the lock icon for sensitive values
4

Reference in Installations

  • Web-server and job installations: link groups explicitly using the variableGroups field in your resource files
  • Helm Chart and Terraform installations: all environment variable groups are automatically available — no explicit linking needed. Reference them in config via k8sSecretName or k8sSecretValue
Variable groups are encrypted and stored securely. For web-server and job installations, reference them using the variableGroups field. For Helm Chart and Terraform installations, all variable groups in the environment are automatically available as Kubernetes secrets without explicit linking.

​
Sync Status and Monitoring

The Git Sync page displays the current status of your repository synchronization:
StatusDescriptionAction Required
In ProgressCurrently syncing repositoryWait for completion
CompletedLast sync was successfulNone - resources are up to date
FailedSync failed due to errorsCheck validation errors and fix issues
File Not FoundNo resource files found in repositoryCreate resource files in the repository

​
Validation Errors

If sync fails due to validation errors, you’ll see:
  • Resource Type: The type of resource that failed validation
  • Resource Name: The name of the specific resource
  • Error Message: Detailed description of the validation issue
Fix all validation errors in your resource files before the sync can complete successfully.

​
Drift Protection

When you modify a git-synced resource through the dashboard or API, Ryvn protects it from being overwritten by the next git sync. You can export your changes to a git branch or remove protection to re-sync from git. Drift protection is enabled by default for new Git Sync configurations. See the Drift Protection guide for details on how it works and how to manage drifted resources.