Usage
Designer Interface
Git Pro adds a status bar and two dockable panels to the Ignition Designer.
Status Bar
Located at the bottom of the Designer, the status bar displays:
- Branch name — the current branch (or short commit hash with "(detached)" when checked out to a specific commit)
- Remotes (clickable) — opens the remote management popup
- Git credentials (clickable, user icon) — opens the User Credentials dialog; shows a verified icon when your identity is configured
Before a project is registered, the status bar instead shows a Configure button (launches the setup wizard) alongside the credentials button.
Dockable Panels
The Commit and History panels are tabbed alongside the Project Browser and stay visible across workspace switches (Perspective, Vision, SFC, Scripting, etc.). They are the primary way to drive the module — see Dockable Panels below.
Committing Changes
Using the Commit Panel
- Open the dockable Commit panel
- The changes list shows all uncommitted changes with:
- Resource name and type
- Change type: Added (A), Modified (M), Deleted (D), Untracked (U)
- Select the resources to include in the commit
- Write a commit message
- Click Commit
The module automatically hides resource.json and thumbnail.png changes when no sibling source file in the same directory was also modified, and it suppresses changes that only reorder JSON keys. This eliminates noise from Ignition's internal timestamp, thumbnail, and key-ordering updates.
Amending a Commit
To modify the last commit (fix the message or add forgotten files):
- In the Commit panel, check Amend last commit
- The previous commit message is loaded for editing
- Select any additional resources to include
- Click Commit — the previous commit is replaced (a message-only amend is allowed)
Viewing Diffs
- Double-click a resource to open the side-by-side diff viewer
- In the Commit panel, right-click a resource and select View Diff
- The diff viewer shows additions in green and removals in red with synchronized scrolling
Discarding Changes
To revert uncommitted changes:
- In the Commit panel, right-click a resource
- Select Discard Changes
- Tracked files are reverted to their last committed state; untracked files are deleted
Gateway Resource Snapshots
The Commit panel header has three snapshot buttons — Tags, Themes, and Images — that capture gateway-side resources into the project so they can be version-controlled:
- Tags — snapshots the gateway tag-provider state into project files
- Themes — snapshots the gateway Perspective theme files into the project
- Images — snapshots the gateway image manager state into the project
After a snapshot, the captured resources appear as normal file changes in the list below, so you can review them and select exactly which to commit.
Push, Pull & Fetch
Push, Fetch, and Pull are available from the History panel toolbar.
Push
Sends local commits to the remote repository.
- By default, only the current branch is pushed (no surprise pushes of experimental branches)
- If the remote rejects the push (e.g. after amending a pushed commit), a confirmation dialog offers force push
- When multiple remotes are configured, a remote selector appears
Pull
Fetches and merges remote changes into the current branch.
- Pulled changes are reflected immediately in the Designer
- When multiple remotes are configured, a remote selector appears
Fetch
Retrieves remote commits and updates remote-tracking branches without merging.
- After fetching, the History panel shows incoming commits with their remote ref badges
- Use this to review what changed before pulling
- When multiple remotes are configured, a remote selector appears
For repositories without a remote, push, fetch, and pull display a friendly warning instead of failing. Add a remote first via the Remotes manager.
Branch Management
Click the branch name in the status bar to open the branch management popup.
Available Operations
| Operation | Description |
|---|---|
| List branches | View all local and remote branches, with the current branch highlighted |
| Create branch | Create a new branch from the current HEAD |
| Checkout branch | Switch to another branch — uncommitted changes are automatically stashed and restored |
| Delete branch | Delete a local branch |
When switching branches, the module automatically stashes uncommitted changes on the current branch and restores any stashed changes on the target branch. This prevents losing work during branch switches.
Detached HEAD
When checking out a specific commit (from the History panel), the status bar shows the short commit hash with a "(detached)" indicator. Create a new branch from this state to preserve your work.
Commit History
History Panel
The dockable History panel shows the commit log for the current branch plus its upstream tracking branch (so fetched commits appear with remote ref badges before merge). Each row shows:
- Short commit hash
- Author name
- Commit date
- Commit message
- Branch and tag reference badges (color-coded)
Use Load More to page through older commits.
Inspecting a Commit
- Double-click a commit to view its changed files
- From the commit detail view, you can:
- View the diff of any changed file
- Checkout the commit (enters detached HEAD)
- Revert the commit (creates a new commit undoing the changes)
Context Menu
Right-click a commit in the History panel to access:
- Checkout — switch to this commit (detached HEAD)
- Revert — create a new commit that undoes this commit's changes
Merge Conflict Resolution
When a pull results in merge conflicts, a dedicated popup appears:
- The popup lists all conflicting files
- For each file, you can:
- Click Accept Ours to keep the local version
- Click Accept Theirs to accept the remote version
- View the conflict diff side-by-side
- Global actions:
- Accept All Ours / Accept All Theirs — resolve all files at once
- Abort Merge — cancel the merge and return to the previous state
- Complete Merge — finalize the merge after resolving all conflicts
Closing the merge popup prompts you to confirm aborting the merge, so the repository can't be left in a conflicted state by accident.
Dockable Panels
Commit Panel
An always-visible panel tabbed alongside the Project Browser:
- Shows all uncommitted changes at a glance
- Commit message field with Commit button and an Amend last commit checkbox
- Snapshot buttons in the header — Tags, Themes, Images — plus a Refresh button
- Double-click a resource to view its diff
- Right-click context menu: View Diff / Discard Changes
- Auto-refreshes every 15 seconds and after each Git operation
- Persists across all workspace switches
History Panel
An always-visible panel showing the commit log:
- Commit table with branch/tag ref badges (color-coded)
- Refresh, Push, Fetch, and Pull buttons in the toolbar
- Double-click a commit to view its details
- Right-click context menu: Checkout / Revert
- Load More pagination
- Persists across all workspace switches
Gateway Configuration Versioning (config-as-code)
In addition to the per-project Designer workflow above, Git Pro can version-control the gateway's own configuration as code. This is a gateway feature with its own web page — it is independent of any project repository.
Where it lives
Open the gateway web interface and navigate to Platform → System → "Versioning".
What it tracks
The feature creates a separate Git repository at <dataDir>/.git that tracks only the <dataDir>/config/ directory. A .gitignore excludes everything else — projects/, databases, logs, the keystore, certificates, and config/local. Your project code stays with the per-project Designer repositories; this repo is strictly for gateway configuration.
Auto-commit
Once initialized, the page auto-commits gateway configuration changes as they happen:
- Changes are coalesced with a short quiesce window (about 2 seconds) so a burst of edits becomes a single commit
- The commit author is the gateway system name
- On startup, any configuration that changed while the module was offline is swept into a catch-up commit a few seconds after the gateway comes up
Only gateway config/ is versioned. Project resources are handled entirely by the Designer Commit/History panels.
Restore to a commit (no restart)
You can restore the gateway configuration to any commit from the page. Restoring resets the working tree to that commit and records a forward "Restore config to <hash>" commit (history is never rewritten), then applies the restored configuration live — no gateway restart required.
Remote sync (manual, never auto-push)
Auto-commit is local only. Pushing to a remote is always manual — the module never auto-pushes.
- Configure the config-repo remote (URI + branch, default
main, plus a Secret-Provider secret) on the page — see Configuration - Push sends
HEADto the remote branch - The header shows a sync indicator: "N not synced" when local commits are ahead of the remote, or "Up to date" once pushed
Recovering after a gateway backup restore
Restoring a gateway backup (.gwbk) brings back the config/ files but drops the <dataDir>/.git repository, while the module's record of the remote survives. Use Update from remote to re-clone the config repo from that remembered remote and reattach it, restoring the version history without re-entering the remote.
Secret providers
The config repo's remote authentication is supplied through an Ignition Secret Provider, the same mechanism available to per-project credentials.
Deinitializing
Deinitializing the feature removes the .git repository, the .gitignore, and the stored remote record, but keeps your credentials/secret-provider configuration so you can re-initialize later.
Git Pro has no scripting functions. There is no system.git.* namespace; the Designer talks to the Gateway over an internal module RPC only. Drive the gateway features from their web pages.
CI/CD Deployments
CI/CD deployments keep an Ignition project on the gateway in step with a branch of a repository: push to the branch, and the gateway updates the project. They are managed on Platform > System > CI/CD, which lists your Git providers and your Deployments.
Deployments need an activated license or a running trial — see Licensing. Connect a provider first — see Configuration → CI/CD Provider Connections.
Adding a project
- Click Add project (available once a provider is connected)
- Select the Provider app
- Select the Repository from the list the provider returns
- Select the Branch to deploy — the repository's default branch is marked
- Enter the Ignition project name, which must not already exist
- Click Create project
The gateway clones the branch over HTTPS with a short-lived provider token, creates the Ignition project, and records the deployment. On GitLab and Gitea it also creates a push hook on the repository; on GitHub the App already receives pushes. If any step fails, the whole creation is rolled back.
Deploy on push
When a push arrives for a deployment's repository and branch, the gateway deploys it:
- The branch is fetched with the connection's token
- The project's working tree is reset to the pushed commit
- The project is reimported into the running gateway
Pushes to other branches are ignored. A burst of pushes arriving within about two seconds is coalesced into a single deployment.
A deployment makes the project on the gateway match the pushed commit exactly. Uncommitted edits to a deployed project on that gateway are discarded at the next deployment — make changes in the repository and push them instead.
The exception is local commits that are not on the remote: the deployment refuses to overwrite them and reports DIVERGED until you pull or merge by hand.
Deployments grid
| Column | Shows |
|---|---|
| Project | The Ignition project name |
| Repository @ branch | What is deployed |
| Status | Enabled or Disabled (auto-deploy) |
| Deployed commit | Title, short hash and date of the commit the project is on |
| Last deploy | Result of the last run (see below) |
| Deploy date | When the last run happened |
| Result | Meaning |
|---|---|
| UPDATED | The project was updated and reimported |
| UP TO DATE | Nothing new to deploy |
| DIVERGED | Local commits are not on the remote — pull or merge manually |
| NO REMOTE | The project has no origin remote, or the branch no longer exists on it |
| ERROR | The deployment failed; the message says why |
Catch-up after downtime
About ten seconds after the gateway starts — and whenever a license is activated — every enabled deployment is run once. Pushes that arrived while the gateway was down or the trial had expired are therefore not lost: the project is brought up to its branch's current tip.
Deployment actions
Each deployment's actions menu offers:
- Deploy now — run a deployment immediately, without waiting for a push
- Branch — switch the deployment to another branch; an enabled deployment switches the project to it immediately
- Enable / Disable — a disabled deployment ignores pushes and the catch-up run
- Remove — stop deploying. The provider-side push hook is removed and the project is unregistered from the module. Choose whether to also delete the Ignition project and its files; otherwise the project is kept and can be added again later.
Renamed repositories
Deployments follow the provider's stable repository id, not its name. After a repository is renamed or moved, the next push updates the stored name and clone URL, and deploying carries on. As a safeguard, a new clone URL is only adopted when it keeps the same scheme, host and port.
Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| Status bar shows "Configure" | Project not registered | Click Configure to run the initialization wizard |
| Push rejected | Remote has new commits | Pull first, resolve any conflicts, then push again |
| Push rejected after amend | Amended a pushed commit | Use force push when prompted (only if you are the sole contributor on the branch) |
| "Pick a credential" error | Remote has no credential, or the referenced credential was deleted | Open the Remotes popup and select a saved credential for the remote |
| Authentication failure (HTTPS) | Invalid credentials | Verify the username and token — use a personal access token, not an account password |
| Authentication failure (SSH) | Invalid or missing SSH key | Verify the SSH key content in the User Credentials dialog |
| Merge conflicts after pull | Divergent changes | Use the Merge Conflict popup to resolve each file, then complete the merge |
| Changes not appearing | Auto-refresh delay | Click Refresh in the Commit panel, or wait for the 15-second auto-refresh |
| Panels disappear after workspace switch | UI refresh timing | Panels re-appear automatically within ~1 second via the visibility polling mechanism |
| Config repo shows "N not synced" | Local config commits not yet pushed | This is expected — click Push on the Versioning page to sync to the remote |
Config version history gone after a .gwbk restore | The restore dropped <dataDir>/.git | Use Update from remote on the Versioning page to re-clone from the remembered remote |
| TLS / certificate error on an HTTPS remote | Self-signed or untrusted server certificate | Verify the certificate, then tick Trust self-signed certificate on that remote — see TLS certificates |
| "Unknown host key" prompt | First SSH connection to that host | Check the fingerprint with the server's owner, then accept it |
| "Host key changed" error | The server's key differs from the accepted one | Treat as a possible interception; see SSH host keys |
| Accepting a host key keeps re-prompting | The key could not be saved on the gateway | Check the gateway log |
| Pushes do not deploy | Provider cannot reach the gateway | Check the Gateway External URL is reachable from the provider, and the webhook deliveries in the provider's settings |
| Pushes do not deploy | Auto-deploy disabled, or pushed to a different branch | Check the deployment's Status and branch |
| CI/CD page says deployments are halted | Trial expired | Activate a license, or reset the trial |
| GitHub connection stays pending | GitHub did not redirect back after installing the App | Use Finish setup on the connection |
| "Unknown or expired connect request" | The connect flow took too long, or was replayed | Start the connection again from the CI/CD page |
| Last deploy shows DIVERGED | Local commits on the gateway are not on the remote | Pull or merge the project manually, then deploy again |
Best Practices
- Commit often — make small, focused commits with clear messages to maintain a clean history
- Fetch before pull — use Fetch to review incoming changes in the History panel before merging
- Use branches — create feature branches for new work and merge when complete
- Review diffs — always review changes in the diff viewer before committing
- Centralize credentials — manage SSH keys and HTTPS credentials once in the User Credentials dialog and reference them from each remote
- Snapshot gateway resources — regularly snapshot tags, images, and themes to keep gateway configuration in version control
- Avoid force push on shared branches — only force push on branches where you are the sole contributor
- Version gateway config too — enable Configuration Versioning to track gateway
config/as code, and Push it to a remote regularly so the "N not synced" indicator returns to "Up to date" - Deploy, don't edit, on CI/CD gateways — treat a deployed project as read-only on that gateway; make changes in the repository so the next deployment does not discard them
- Keep certificate verification on — only use Trust self-signed certificate for servers you control