Version and Source Control Guide

💡Have feedback for this page? Let us know on the IA Forum.

One of the most transformative changes in Ignition 8.3 is the migration from a SQLite database-driven configuration to a file system based configuration. Unlike Gateway configurations in Ignition 8.1, which use an internal database, 8.3 Gateways externalize configurations into a data/config directory structure. This fundamentally changes how to approach Gateway lifecycle management and version control in Ignition. This shift introduces opportunities to use version control that were previously challenging or impossible.

This guide outlines general integration of Git with Ignition, and Ignition 8.3 version control best practices. The included examples and guidelines detail how to set up and manage version control across multiple Ignition installations for both full data directory versioning and curated configuration mounting.

Version Control Integration

The features and functionality included with Ignition 8.3 change the way version control and Continuous Integration and Continuous Delivery (CI/CD) pipelines work with Ignition. The following sections describe some of these features and how they can be used alongside a version controlled environment.

Gateway File System Storage

As mentioned above, one of the most significant advancements is that all Ignition Gateway configuration, not just project resources, is now stored in the file system rather than being held in the internal database. Entire configurations, including database connections, device connections, tag configurations, alarm pipelines, and other Gateway-scoped resources, can now be version controlled alongside project code.

These files are designed to be human-readable, making them easy to audit and manage. This enables powerful workflows, such as change tracking, rollback, and automated deployments. It’s a foundational change that will significantly improve how teams collaborate and maintain Ignition systems at scale.

For more information on the Gateway file system, see the Gateway Folder Structure page.

Vision Considerations

For enhanced compatibility with version control systems, it is recommended to transition your project's encoding from binary to XML. By default, Vision projects are encoded as Java .bin files. This change will be implemented for existing projects incrementally as you modify and save individual windows.

It is recommended to add the following project resources to the .gitignore file. These resources are currently encoded as Java .bin files and not easily manageable outside of the Ignition environment with the exception of their API.

• Transaction Groups
• Client Tags
• Reports
• Alarm Pipelines

Gateway API

Ignition exposes a fully documented Gateway RESTful API, enabling external tools and systems to programmatically read from and write to the Gateway configuration. This includes access to key metrics, health checks, and the ability to manipulate configuration elements such as tags, devices, and connections. These interactions are completed through authenticated, standards-based requests.

The API allows teams to integrate Ignition Gateways directly into modern DevOps workflows. Configuration changes can be scripted, versioned, and reviewed before being pushed via API calls, enabling full GitOps-style deployments. Infrastructure-as-code tools such as Ansible, Terraform, or custom Python scripts can use this interface to audit, apply, or roll back changes as part of a continuous deployment pipeline.

For more information on the Gateway’s RESTful API, see the API Documentation page.

Deployment Modes

With Gateway Deployment Modes, a Gateway can identify and adapt to its role within an environment, such as development, staging, or production. This is possible due to the newly introduced resource collection hierarchy and inheritance structure, in which a resource definition can override a definition from another resource collection that it inherits from.

In terms of version control, Deployment Modes allow teams to maintain a single, unified configuration repository, and dynamically adjust behavior at runtime based on the environment. For example, a Gateway in development mode might automatically connect to test devices and databases, while the same configuration set deployed in a production mode would connect to live production infrastructure with no manual reconfiguration needed during deployment. This decouples environment-specific behavior from static configuration files, making the system both portable and context-aware.

For more information on the Deployment Modes, see the Gateway Deployment Modes page.

Helm Chart for Kubernetes Deployments

Helm, the package manager for Kubernetes, allows users to define, install, and upgrade full application stacks with ease and repeatability. An official Ignition Helm chart will soon be available for cloud-native and containerized Ignition deployments, so Ignition can be deployed into Kubernetes clusters using a versioned, declarative Helm chart that serves as a fully functional starting point.

This section will be further updated in a future release when the Ignition Helm chart is available.

Ignition Version Control Example

The following example demonstrates a full data directory versioning method performed in conjunction with GitHub. It requires careful consideration between the files that are essential for Gateway configuration and ones used for different Ignition purposes. This example relies on a .gitignore file within GitHub repositories to allow Git to “ignore” unneeded files and keep them out of the repository.

Teams with existing bare-metal or virtual machine deployments who want to start their version control journey may choose this option so they can get started immediately. However, be advised that while the setup time for this option is shorter, the subsequent maintenance can be more significant. This strategy will work best for small installations with one or two Gateways, and may not be appropriate for more sophisticated deployments or container-based solutions. Considerations for more advanced version control can be found below.

The following prerequisites are required before beginning.

Prerequisites

• Git installed on your system
• GitHub account
• Basic understanding of Git commands

Repository Setup

1. Create a new empty repository on GitHub.
2. Copy the repository URL for later use.

Installation Setups

Installation A

1. Install Ignition 8.3 on the first machine.

2. Navigate to the Ignition data directory:

   cd <ignition-install-location>/ignition/data

3. Initialize the Git repository:

   git init

4. Create a .gitignore file with the following contents:

   # Database files
   **/db/
   **/metricsdb/
   **/autobackup/
   **/db_backup_sqlite.idb
   **/valueStore.idb
   
   # Cache and temporary files
   **/jar-cache/
   **/request
   **/response
   *.tmp
   *.bak
   **/var
   
   # Log files
   *.log
   **/logs
   
   # Certificates and security
   **/certificates/
   **/keystore/
   
   # Runtime configuration (environment-specific)
   **/config/local
   **/config/resources/local
   
   # Gateway-specific runtime files
   **/.container-init.conf
   
   # Backup and converted files
   **/conversion-report.txt
   **.digest.json
   
   # Project conversion artifacts
   **/projects/conversion-report.txt
   **/migration-log-*.md
   **/.resources/
   
   # Alarm history files
   **/.alarms_*
   note

   The valueStore.idb holds the persisted value of Memory tags when persistence is configured to the default database setting and should not be tracked by version control. Any tag values relevant to version control should have their value persistence set to configuration so those values are saved in human-readable .json files. There should be caution used in how many tags are written in files.

5. Add and commit initial files:

   git add .
   git commit -m "Initial configuration commit"

6. Add remote repository and push:

   git remote add origin <your-repository-url>
   git branch -M main
   git push -u origin main

Installation B

1. Install Ignition 8.3 on the second machine, but DO NOT start the service. To install without starting the service, uncheck the Start Ignition Now option during installation.

   

2. Delete the existing data directory:

   • Windows: C:\Program Files\Inductive Automation\Ignition
   • Linux: /usr/local/bin/ignition
   • Mac: /usr/local/ignition

   cd <ignition-install-directory>
   rm -rf data

3. Clone the repository data directory as the data directory:

   git clone <your-repository-url> data

4. Start the Ignition service:

   ./ignition.sh start or ./start-ignition.bat

Working with Changes

Making Changes (Installation A)

1. Create a local feature branch:

   git checkout main
   git pull origin main
   git checkout -b my-new-feature

2. Make changes to a project or Gateway config on the Gateway or in the Designer.

3. Review changes:

   git status
   git diff

4. Commit and push changes:

   git add .
   git commit -m "Description of changes"
   git push origin main

5. Create a Pull Request from the feature branch into main.

6. Merge the Pull Request into main.

Pulling Changes (Installation B)

1. Pull latest changes:

   cd <ignition-install-directory>/data
   git pull origin main

2. Trigger scans to apply changes on the Gateway using Scan File System, located in the top right corner of the following screens.

   • To scan the config files, navigate to Platform > System > Modes.

     

   • To scan the project files, navigate to Platform > System > Projects.

     

   tip

   File system scans can alternatively be performed using the following API endpoints:

   • <ip>:<port>/data/api/v1/scan/config
   • <ip>:<port>/data/api/v1/scan/projects

   Refer to the API Documentation to learn more about how to access and use the Gateway API.

Advanced Version Control Considerations

The example above serves as a simplified introduction that glosses over the complexities of modern production deployments. While it is useful for understanding basic concepts, real-world enterprise environments require more sophisticated approaches to version control and deployment automation. This section addresses several strategies for implementing version control in larger, more complex Ignition architectures.

These approaches are particularly useful for teams building cloud-native or multiple Gateway architectures where deployment consistency, scalability, and automation are critical. While these strategies require more upfront planning and development efforts compared to the basic full data directory versioning approach, the operational efficiency, reliability, and portability they provide can deliver significant long-term benefits for future enterprise-scale Ignition deployments.

Version Control in Container-Based Environments

Container-based Ignition deployments enable more sophisticated version control strategies that are particularly well-suited for team environments and multi-Gateway architectures. Unlike traditional installations where the entire data directory must be managed, containerized deployments allow for precise control over which files are version controlled through selective volume mounting. This approach aligns naturally with modern DevOps practices and provides the foundation for scalable, maintainable Ignition systems.

Container orchestration platforms like Kubernetes can leverage GitOps tools (e.g., git-sync, ArgoCD, Flux) to automatically synchronize configuration changes, creating deployments that stay current with repository updates. This integration enables teams to treat Ignition configurations as code, applying the same rigor and automation used for application deployments.

Curated Configuration Mounts (Additive Approach)

The Ignition Version Control Example demonstrated a subtractive approach, where everything was added from the data directory and unwanted files were excluded through .gitignore. This method becomes unwieldy in team environments and multi-Gateway deployments. A more scalable strategy is the additive approach, which selectively includes only the configuration files needed for your specific use case.

The curated mounting strategy works by bind-mounting specific directories from your version control repository into the Ignition container, allowing you to track exactly what's needed while letting Ignition handle all runtime concerns separately. The additive approach dramatically simplifies .gitignore files and enables managing multiple Gateways from a single repository structure.

Implementation Example

Example Docker Compose

services:
  ignition:
    image: inductiveautomation/ignition:8.3.0
    volumes:
      - ./services/ignition/config:/usr/local/bin/ignition/data/config
      - ./services/ignition/projects:/usr/local/bin/ignition/data/projects

Example Repository Structure

services/ignition/
├── config/
│   ├── ignition/        # Gateway configuration
└── projects/
    └── [project directories]

Example .gitignore

**/config/local
**/config/resources/local

**/conversion-report.txt
**/.resources/

Selective File Tracking

With the additive approach, you only version control the files essential to your deployment strategy. Consider these common patterns:

• Project-Only Strategy: If your team prefers to manage Gateway configuration through the web interface or API, mount only the projects directory. This keeps project resources under version control while allowing manual configuration management:

  volumes: 
      - ./projects:/usr/local/bin/ignition/data/projects

• Full Configuration: For complete infrastructure-as-code deployments, include both projects and curated configuration files. You may need to add additional files beyond the basic config and project directories, such as redundancy configurations, accepted certificates, or custom modules, depending on your specific requirements.

• Multi-Gateway Management: Unlike the subtractive approach which accommodates only a single Gateway per repository, curated configuration mounts enable managing entire fleets of Gateways from a unified repository structure:

  repository/
  ├── services/
  │   ├── gateway-01/
  │   └── gateway-02/
  └── shared/
  ├── projects/
  └── common-config/

This structure provides a single source of truth for all Gateway configurations while maintaining clear separation between environments and individual Gateway instances. Teams can leverage shared configurations and projects while allowing for Gateway-specific customizations where needed.

Once folders have been successfully mounted within Docker, continue using the Working with Changes section above to migrate updates between repositories.

CI/CD Pipelines

Ignition 8.3's file system based configuration and Gateway API enable seamless integration with CI/CD pipelines. Version-controlled Ignition configurations can be validated, tested, and deployed through automated workflows. CI/CD tools like GitHub Actions, Jenkins, or Azure DevOps can lint configuration files for syntax errors, run automated tests against project resources, and deploy validated changes to target environments using the Gateway API. A typical workflow might involve configuration changes committed to a Git repository triggering a pipeline that validates and deploys the changes to a staging Gateway via API calls, where integration tests run before approved changes are promoted to production environments. And this is all accomplished while maintaining full audit trails through version control.

GitOps

GitOps represents a natural evolution for Ignition 8.3 deployments, where Git repositories serve as the single source of truth for Gateway configurations and deployments are driven by repository changes. Tools like ArgoCD, Flux, or Kargo can monitor Ignition configuration repositories and automatically synchronize changes to running Gateways through file system mounts or Gateway API calls. This approach is particularly powerful when combined with the curated configuration mounts strategy described above, where a single repository can manage configurations for entire fleets of Gateways across multiple environments.

In a typical GitOps workflow, operations teams commit configuration changes to specific branches or directories representing different environments (development, staging, production). The GitOps controller detects these changes and automatically applies them to the corresponding Ignition Gateways, either by updating mounted configuration volumes in containerized deployments or by pushing changes through the Gateway API. This creates a fully auditable, declarative deployment model where the desired state is always defined in version control, and any configuration drift is automatically corrected. Combined with Ignition's Deployment Modes, teams can maintain environment-specific behaviors while keeping all configuration logic version-controlled and automatically deployed.