Source Control

Goal: Connect a GitHub organisation, so OpenX can see the repositories you choose.

This window opens as a panel: it floats at the right at first, docks anywhere, and keeps your place when you move it. See Node editors and work windows as panels.

The window is titled Source Control; its hero reads Your code, connected. GitHub works today. GitLab, Azure DevOps, Bitbucket and Fathym Hosted Source Control are listed as Coming soon, each with a panel that says what it will do and no Connect button.

What OpenX holds

• No password and no token. The record keeps which App and which install it is. Each time OpenX needs to reach GitHub it asks for a token that lasts one hour and works only on what that job needs.
• The App's signing key stays in your Key Vault. GitHub makes the key; OpenX imports it into your landing zone's vault as a key that can sign and cannot be read back, and the copy GitHub handed over is discarded.
• The App is yours. It belongs to your organisation, not to Fathym, and an owner can see it in the organisation's GitHub settings.

Before you start

• A connected cloud and a provisioned private landing zone. Until both exist the menu has no Source Control. The landing zone is needed because the App's key lives in its Key Vault, even for public repositories.
• The Workspace.SourceControl.Manage right to connect, accept or remove.
• An owner of the GitHub organisation, for the two steps on GitHub's own pages.

Connect an organisation

1. On the Connections tab, type the organisation's login in GitHub account or organisation and press Connect GitHub. OpenX adds a proposal for that account. Nothing happens on GitHub yet.
2. The card A connection is waiting for you appears. Press Accept connection. The connection is now a row reading Waiting for its App.
3. Press Create the GitHub App on the row. GitHub's own page opens in a new tab, already filled in. An owner of the organisation presses Create GitHub App.
4. GitHub brings you back and on to the install page. Choose which repositories OpenX may see, and install.
5. You land back in the workspace with this window open, and the row reads Installed.

An agent can start the same way: it proposes the connection, and a person accepts it and does the steps on GitHub.

The App was installed on another account

If the install lands on an account other than the one the connection names, you come back to this window with SOURCE_INSTALL_ACCOUNT_MISMATCH, both account names and a Keep button named for the account GitHub installed on. Keep adds a proposal to change the connection's account to that one; nothing changes until you accept it. Accept it, then press Install on GitHub again and the row reads Installed. To keep the account the connection names instead, install the App there.

What a row can say

State	What it means	What to do
Waiting for its App	Accepted; the organisation has no App yet	Create the GitHub App
Waiting for install	The App exists and is not installed	Install on GitHub
Installed	The App is installed	Nothing
Suspended	An owner suspended the App on GitHub	Unsuspend it in the organisation's GitHub settings
Kept by hand	A git host OpenX only trusts: it writes nothing there	Nothing
Removal staged	It goes at the next Deploy	Restore keeps it

Used by on a row lists the GitHub Events nodes using that connection; each name opens its node.

Repositories

The Repositories tab lists, under each connection, every repository that connection's install can see. A repository the workspace has added reads Added; the others offer Add. Private and archived repositories say so beside the name. Under each list a line names the connection, such as Read through acme, never copied. OpenX reads the repository through the connection's App each time it needs to, and keeps no copy of its code.

Repositories are rows in this window, not nodes: nothing is added to the canvas. A workbench picks one of these repositories in its Inspector.

Add a repository

1. Press Add on the repository.
2. Pick the branches to track. They are offered as chips from the repository's branches and tags; its default branch is picked for you.
3. Add a description if you like, and save.

The save asks GitHub first, through the connection. It is refused when the connection cannot reach the repository (SOURCE_REPO_NOT_REACHABLE, with the page that grants it), when the workspace already holds it (SOURCE_REPO_DUPLICATE, naming the one it has), or when a tracked branch or tag does not exist (SOURCE_REF_NOT_FOUND). An agent can propose a repository too; the same check answers its checkOnly, and a person accepts it.

Adding a repository needs Workspace.SourceControl.Manage. Without it the tab lists the repositories and offers no Add.

Health

Each added repository shows its health line, read from GitHub when you open the tab. For example: acme/orders is reachable; default branch main. main: latest 1a2b3c4 at 2026-10-31T09:12:00Z; branch rules: 2; last run: CI completed (success) at 2026-10-31T09:14:00Z. It ends with the form its builds present to a cloud (Its builds present the name form, or the ids form for a repository created, renamed or transferred on or after 15 July 2026).

The line says	What it means	What to do
is reachable and a line per branch	Reachable, and every tracked branch or tag exists	Nothing
main: not found.	A tracked branch or tag is gone (SOURCE_REF_NOT_FOUND)	Track one the repository has, or restore it
Renamed on GitHub to ...	Renamed or transferred on GitHub (SOURCE_REPO_RENAMED)	Use the new name, or Deploy
is not reachable: ...	The connection cannot reach it (SOURCE_REPO_NOT_REACHABLE)	Add it to the install on GitHub

Branch rules the App cannot read, and runs GitHub will not list, read unknown and never turn a repository red. The App reads rulesets only; classic branch protection needs a permission it does not ask for.

Renamed or transferred on GitHub

OpenX knows a repository by the number GitHub gives it, so a rename or a transfer keeps it the same repository. Its health reads Renamed on GitHub to acme/orders-api (OpenX still has acme/orders). Reading health changes nothing. Press Use the new name to save the new name now, or Deploy: the next Deploy takes it. A change of letter case alone is not a rename.

A repository is not listed

The install decides what OpenX may see. An owner adds the repository to the install in the organisation's GitHub settings. An install that grants nothing reads This install can't see any repositories yet with the link Choose repositories on GitHub. If the list could not be read just now, the tab says so instead; that never means the install is empty. The Grants tab lists every permission the App holds at each account.

If a repository you added is later dropped from the install, the connection's health names it, with the install page to add it back, and the repository's own health reads down.

Remove a repository

Removing a repository is staged for the next Deploy, which drops only OpenX's record. OpenX never deletes, archives or changes a repository on GitHub.

GitHub Events nodes

A GitHub Events node forwards chosen events from a connected organisation to a data connection. Add one once an organisation has its App.

On the node's Receives tab you pick the Organisation from your connected ones; + Connect another opens this window. Repositories reads All repositories this install sees unless the node holds repository ids, shown as chips you can remove. Events lists only what that organisation's install can send, so an App without the Actions permission offers no Build runs. Branches takes one pattern a line; empty means every branch.

The Sends tab sets what a message carries: Summary and Link are on, Whole event is off. The whole event is stored in your workspace and the message carries a reference to it.

The node's on and off toggle pauses forwarding and keeps its settings.

How events reach the node

Each workspace has one GitHub receiver, a small function OpenX deploys into your landing zone the first time you connect an organisation. Every App in the workspace sends its events to it, so they arrive in your Azure, not at Fathym. The receiver:

• checks each event's signature with that App's webhook secret from your Key Vault, and refuses one that does not match without storing it;
• stores each event once, by GitHub's delivery id, answers GitHub at once, and forwards it afterwards;
• forwards it to every switched-on GitHub Events node whose organisation, repositories, events and branches match, sending the node's message to its data connection. A paused node gets nothing.

With Whole event on, the event is stored as a document of the data connection, and the message carries a reference to it and "WholeEvent": "attached".

If the receiver misses events (it was stopped, say), its catch-up asks GitHub for the App's recent deliveries and has GitHub send again each one it never stored. Those arrive marked as replays. GitHub keeps deliveries for 3 days, so catch-up never looks further back.

Recent events and Send again

The node's Recent events tab lists what the receiver forwarded to this node in the last 3 days, newest first: the event and its action, the repository and branch, when it arrived, and whether it reached the data connection. Not forwarded says why: refused by the data connection (with its status), the whole event could not be stored first, or the forward failed before the connection answered. A replay from catch-up reads (replay), and an event someone sent again reads (sent again). The tab is read when you open it; press Refresh for newer events.

Send again to the connection forwards one of those events to this node again, marked as a replay. Only this node gets it; other nodes that matched the event do not. It needs Workspace.SourceControl.Manage; without that right the tab shows the events and says sending again needs it. The row then reads Queued, or says why it was refused.

Removing a GitHub Events node changes nothing on GitHub: the App keeps sending events, and the receiver forwards them to no node.

Warnings from the last Deploy

The receiver is deployed, and its logs pointed at your landing zone's log workspace, when you Deploy a connection or a GitHub Events node. If part of that did not finish, the Connections tab lists Warnings under the line From the last Deploy of your connections and GitHub Events nodes.: each with its code, what happened and its Next step:. The receiver keeps running. The next Deploy of a connection or a GitHub Events node replaces the list, so a Deploy that finishes cleanly clears it.

Remove a connection

Press Remove on the row. While a GitHub Events node or a repository uses the connection the removal is refused, and the row names each one: remove those or point them at another connection first. Removing a repository never touches it on GitHub.

Otherwise the confirm says what will happen, and the removal is staged for the next Deploy, which:

• uninstalls the App from the organisation;
• moves the App's key and secrets to your vault's deleted list;
• removes the workspace's GitHub receiver with the last connection.

No API can delete a GitHub App, so the App itself stays on GitHub. The confirm gives the page where an owner of the organisation deletes it. A connection that never got an App made nothing on GitHub, so only the record goes.

By-hand connections

An agent can propose a host OpenX only trusts: Mode by-hand with a git URL in GitHost and the issuer of its OIDC tokens in OIDCIssuer, both https. OpenX writes nothing at that host and holds no token for it.

Builds: where images are kept

The Builds tab holds Where images are kept: your landing zone's Azure registry, or GitHub Packages in a connected organisation, public or private. Nothing builds until a person saves a choice, and an AI cannot set it. What each choice costs, and what the tab shows: Where your workbench's image lives.

Rights

Right	Lets you
Workspace.SourceControl.Read	Open the window, read the connections and repositories, and a GitHub Events node's recent events
Workspace.SourceControl.Manage	Connect, accept, save or remove a connection; add a repository; send a GitHub event again; choose where images are kept
Workspace.SourceControl.Runners.Manage	Manage runner pools, when they arrive

Messages you may see

Message or code	What to do
"That is not a GitHub login"	Use the name as it reads on GitHub: letters, numbers and hyphens
"already in your connections"	The account has a row. Use it
"already waiting for you"	Accept the card above
SOURCE_RECEIVER_REQUIRED	The workspace has no GitHub receiver yet, so no App was made
SOURCE_CONNECT_NOT_SET_UP	Connecting is not switched on for this platform yet. Ask your OpenX administrator
SOURCE_CONNECTION_IN_USE	A GitHub Events node or a repository uses it. Remove or move each one named first
SOURCE_REPO_NOT_REACHABLE	The connection can't reach that repository. Add it to the install on GitHub, on the page shown
SOURCE_REPO_DUPLICATE	The workspace already holds that repository, under the name shown. Change that one
SOURCE_REF_NOT_FOUND	A tracked branch or tag doesn't exist. Track one the repository has
SOURCE_REPO_RENAMED	Renamed on GitHub. Press Use the new name, or Deploy
SOURCE_INSTALL_NOT_RECORDED	The App is installed but the record did not take it. Press Install on GitHub again
SOURCE_INSTALL_ACCOUNT_MISMATCH	The App was installed on another account. Press Keep to propose that account, or install on the one the connection names
GITHUB_RECEIVER_LOG_SETTINGS_NOT_SET	The receiver runs, but its logs aren't being sent to the landing zone's log workspace. Follow the next step shown with it
GITHUB_RECEIVER_SETUP_INCOMPLETE	Part of the receiver's setup did not finish on that Deploy. Follow the next step shown with it
GITHUB_EVENTS_NODE_PAUSED	The node is switched off, so nothing is forwarded to it. Switch it on and Deploy, then send again
GITHUB_EVENTS_DELIVERY_NOT_RECENT	That event did not reach this node in the last 3 days. Pick one from Recent events
GITHUB_EVENTS_SEND_AGAIN_NOT_QUEUED	The receiver did not take it. Try again shortly; if it keeps failing, Deploy a change to a connection or a GitHub Events node, which grants the workspace leave to queue on the receiver
GITHUB_EVENTS_LOG_UNREADABLE	What the receiver forwarded could not be read just now. Try again shortly

Next steps

• The landing zone that holds the App's key -> Manage Private CALZ
• The order things unlock in -> Environment