Skip to main content
Version: 8.3

Configuration

Repository Initialization​

When opening a project in the Designer for the first time, the status bar shows a Configure button. Click it to launch the initialization wizard. The wizard is a simple two-path flow: Choose, then either Remote or Local.

Set up credentials first

You can open the User Credentials dialog (the user icon in the status bar) before initializing to add your SSH keys or HTTPS credentials. The remote step of the wizard then lets you pick one directly.

Clone from Remote​

  1. Choose the Remote path
  2. Enter the repository URI (HTTPS or SSH)
  3. Pick a saved credential from the dropdown — it is filtered by the URI scheme (SSH keys for git@… URIs, HTTPS credentials for https://… URIs). Use Configure… to add one inline if needed.
  4. Click to clone — the module clones the repository and imports the project

Initialize Locally​

  1. Choose the Local path
  2. Confirm — no fields are required
  3. The module creates a local Git repository with an initial commit
  4. A remote can be added later via the Remotes manager
Commit author email

The commit author email comes from your Ignition user profile, not from a per-project setting. Make sure your Ignition user account has an email address configured.

User Credentials​

Credentials are user-level and shared across all your projects and remotes. Open the User Credentials dialog by clicking the user icon in the Designer status bar ("Manage Git Credentials"). It manages two kinds of credential:

SSH Keys​

ParameterTypeRequiredDescription
Key NameTextYesA label to identify this key in the credential picker
SSH KeyText or referenceYesThe SSH private key — either the private key content stored inline, or a reference to an Ignition Secret Provider entry that holds it

SSH transport uses Apache MINA sshd.

Store secrets in a Secret Provider

Instead of pasting the private key content inline, you can point the key at an Ignition Secret Provider. The module then resolves the secret at operation time rather than storing key material in the credential record. See Secret Providers below.

HTTPS Credentials​

ParameterTypeRequiredDescription
Host PatternTextNoAn organizational label to disambiguate credentials in the picker (e.g. github.com)
UsernameTextYesGit username
Password / TokenText or referenceYesPassword or personal access token — either stored encrypted inline in the credential record, or a reference to an Ignition Secret Provider entry

The dialog shows provider hint text for the common hosts:

  • GitHub / GitLab — use a Personal Access Token (PAT) as the password
  • Azure DevOps — use a PAT (the username may be left empty)
  • Bitbucket — use an App Password
Personal Access Tokens

Most Git hosting providers no longer accept account passwords for Git operations. Generate a personal access token (or app password) with appropriate repository permissions and use it as the password.

Host Pattern is a label only

Host Pattern is purely an organizational label in the credential picker — authentication never matches on it. Remotes resolve their credential strictly by the credential you select for them.

Remote Management​

Manage multiple remotes (e.g. origin, upstream) from the Designer status bar by clicking the Remotes button ("Manage Remotes").

Adding a Remote​

  1. Click Add Remote
  2. Enter the remote name (e.g. origin, upstream)
  3. Enter the remote URL
  4. Select the saved credential to use for this remote (or open User Credentials inline to create one)
  5. For an HTTPS remote whose server uses a self-signed certificate, tick Trust self-signed certificate — see TLS certificates
  6. Save

Editing a Remote​

  1. Select the remote in the list
  2. Edit the URL or the selected credential
  3. Save

Removing a Remote​

  1. Select the remote in the list
  2. Remove
Per-Remote Credentials

Each remote references one saved credential by id. This lets you push to different Git providers (e.g. GitHub and GitLab) with different authentication, while the underlying SSH keys and HTTPS credentials remain centrally managed in the User Credentials dialog. The authentication type (SSH vs HTTPS) is determined automatically from the remote URL.

Authentication​

The module selects the authentication method automatically from the remote URL:

  • HTTPS — when the URL starts with http:// or https://, the remote's referenced HTTPS credential (username + password/token) is used.
  • SSH — when the URL uses SSH format (e.g. git@github.com:user/repo.git), the remote's referenced SSH key is used.

Every remote must reference an explicit credential. If a remote has no credential set, or the referenced credential has been deleted, remote operations fail with a clear message asking you to pick a credential in the Remotes popup. Local-only repositories (no remote) degrade gracefully — remote operations show a friendly warning instead of failing.

Connection Security​

TLS certificates​

HTTPS remotes have their server certificate verified. A remote whose server presents a self-signed or otherwise untrusted certificate fails to connect until you opt it out explicitly with Trust self-signed certificate:

  • In the Designer's Remotes popup (HTTPS remotes only)
  • In the Versioning page's remote drawer, for the gateway config repository
  • On a self-hosted provider connection on the CI/CD page — see CI/CD Provider Connections

The opt-out applies to that one remote only: other remotes in the same repository keep verifying. Removing the remote drops its exception, and Test applies the pending choice, so a test reflects what the next push will do.

warning

Only trust a certificate you control or have verified. With verification off, the connection can be intercepted without the fetch or push noticing.

SSH host keys​

SSH remotes have the server's host key checked against keys you have accepted:

  • Unknown host — the operation stops and the Designer shows the host, key type and fingerprint. Accept it to store the key and re-run the operation (clone, push, force push, pull, or fetch). The Versioning drawer does the same for the config repository.
  • Changed key — a host presenting a different key than the one accepted earlier is refused outright and never offered for acceptance, because that is what interception looks like. Verify the new key with whoever runs the server, then remove the stored key on the gateway before connecting again.

Accepted keys are stored as git-known-host config resources rather than in a known_hosts file, so they are not swept into the gateway config repository.

No way to remove an accepted key

The module offers no UI for deleting a stored host key. After a deliberate server key rotation, the refusal above is permanent for that host — the new key can never be accepted. Until a removal path exists, the workaround is to delete the git-known-host resource from the gateway configuration directly.

Secret Providers​

Both SSH keys and HTTPS credentials can hold their secret material two ways:

  • Inline — the private key content (SSH) or password/token (HTTPS) is stored in the credential record. HTTPS passwords/tokens are stored encrypted.
  • Secret-Provider reference — the credential instead references an entry in an Ignition Secret Provider, and the module resolves the secret at operation time.

Using a Secret Provider keeps key material and tokens out of the module's own records and lets you manage rotation centrally in Ignition. Configure your Secret Provider in the gateway first, then reference its entry from the SSH key or HTTPS credential.

Gateway Configuration Versioning​

Separate from the per-project credentials above, the gateway Configuration Versioning page (Platform → System → "Versioning") maintains its own Git repository for the gateway data directory's config/. Its remote is configured on that page rather than in the Designer, and takes:

ParameterDescription
Remote URIThe Git URL for the config repository
BranchThe branch to sync to (defaults to main)
SecretThe authentication secret, supplied via an Ignition Secret Provider
Trust self-signed certificateHTTPS only — see TLS certificates

See Gateway Configuration Versioning in the Usage guide for the full workflow.

CI/CD Provider Connections​

The CI/CD page (Platform > System > CI/CD, requires gateway write permission) connects the gateway to a Git provider once, then deploys projects from its repositories. This page covers the connection; deploying is covered in Usage → CI/CD Deployments.

Click Connect provider and choose one of:

ProviderConnection typeHosts
GitHubA GitHub App, created for this gatewaygithub.com or a self-hosted instance
GitLabAn OAuth application you creategitlab.com or a self-hosted instance
GiteaAn OAuth2 application you creategitea.com or a self-hosted instance

Common fields​

FieldRequiredDescription
Gateway External URLYesThe gateway's publicly reachable URL. The provider must reach it for the connection callback and for push webhooks. Prefilled from the gateway's Public Address — edit it if you use a tunnel or reverse proxy. See Installation → Network Requirements.
Instance URL (self-hosted only)NoBase URL of a self-hosted provider. Leave blank for github.com, gitlab.com or gitea.com.
Trust self-signed certificateNoSkip TLS verification for this connection's traffic. Only honoured together with an Instance URL — cloud providers are always verified.

GitHub​

  1. Enter an App Name — it must be unique across GitHub
  2. Optionally enter an Organization to create the App under that organization; leave blank for a personal account
  3. Click Create GitHub App — you are sent to GitHub to confirm creating the App
  4. Install the App on the account or organization, choosing which repositories it may access
  5. GitHub redirects back to the CI/CD page and the connection is complete

The App is created private, with read-only Contents and Metadata permissions, subscribed to push events, and with its webhook already pointing at the gateway — there is no webhook to configure by hand.

Finish setup

If GitHub does not redirect back after installation, the connection stays pending. Use Finish setup from the connection's actions menu to look up the installation and complete it.

GitLab and Gitea​

  1. Create an OAuth application on the provider — the wizard has a button that opens the right page:
    • GitLab: User Settings > Access > Applications, as a confidential application with scopes api, read_user, read_repository
    • Gitea: Settings > Applications, as an OAuth2 application (Confidential Client)
  2. Use the Redirect URI the wizard displays (built from the Gateway External URL)
  3. Paste the Application ID (GitLab) or Client ID (Gitea) and the Client secret into the wizard
  4. You are sent to the provider to authorize, then back to the CI/CD page

A push hook is created on each repository when you add it as a project, and removed when you remove the project.

Stored data​

Each connection is a git-provider-connection config resource. Client secrets, the GitHub App private key, webhook secrets, and OAuth access/refresh tokens are stored encrypted; identifiers such as the App id, client id and instance URL are plain text.

Removing a connection

Removing a connection removes all of its deployments and their provider-side push hooks. The Ignition projects themselves are kept, but no longer registered with the module.