# Change Management ## Table of Contents 1. [Overview](#1-overview) 2. [Roles and Permissions](#2-roles-and-permissions) 3. [Navigating to Change Management](#3-navigating-to-change-management) 4. [Creating a Repository](#4-creating-a-repository) 5. [Initializing a Repository](#5-initializing-a-repository) 6. [Browsing and Managing Repositories](#6-browsing-and-managing-repositories) 7. [Editing a Repository](#7-editing-a-repository) 8. [Using the Machine Control Center](#8-using-the-machine-control-center) 9. [Adding a Repository Checkout to a Machine](#9-adding-a-repository-checkout-to-a-machine) 10. [Checking Out a Branch on a Machine](#10-checking-out-a-branch-on-a-machine) 11. [Pulling Latest Changes to a Machine](#11-pulling-latest-changes-to-a-machine) 12. [Checking Status on a Machine](#12-checking-status-on-a-machine) 13. [Committing Changes from a Machine](#13-committing-changes-from-a-machine) 14. [Creating a Change Request](#14-creating-a-change-request) 15. [Viewing Change Request Details](#15-viewing-change-request-details) 16. [Generating and Refreshing Diffs](#16-generating-and-refreshing-diffs) 17. [Reviewing a Change Request](#17-reviewing-a-change-request) 18. [Commenting on a Change Request](#18-commenting-on-a-change-request) 19. [Marking a Draft as Ready for Review](#19-marking-a-draft-as-ready-for-review) 20. [Merging a Change Request](#20-merging-a-change-request) 21. [Viewing Commit Details](#21-viewing-commit-details) 22. [Browsing All Change Requests](#22-browsing-all-change-requests) 23. [Managing Branches](#23-managing-branches) 24. [Resolving Merge Conflicts](#24-resolving-merge-conflicts) 25. [Reverting a Commit](#25-reverting-a-commit) 26. [Closing a Change Request](#26-closing-a-change-request) 27. [Viewing Operation History](#27-viewing-operation-history) 28. [Change Request Lifecycle Summary](#28-change-request-lifecycle-summary) *** ## 1. Overview The **Change Management** system in Axilon DevOps Desktop gives your team a structured, version-controlled workflow for managing changes to application configurations across your Axilon Box machines. Think of it as a pull-request workflow tailored for operational technology environments: you track every change, review it collaboratively, and apply it in a controlled way. The system is organized around five key concepts: * **Repositories** -- Containers that track the version-controlled state of a project. Each repository is linked to an Axilon application and holds branches, commits, and the scripts that define how changes are extracted, compared, applied, and merged. * **Branches** -- Independent lines of work within a repository. A default branch is created automatically with every new repository. * **Commits** -- Point-in-time snapshots of the application state on a given branch. * **Change Requests** -- Formal proposals to merge changes from one branch into another. They follow a draft/open/merged/closed lifecycle, support role-based approval gates, and provide side-by-side diff views so reviewers can see exactly what changed. * **Machine Control Center** -- A dashboard showing every machine and its current checkout state, with buttons for day-to-day operations like checkout, pull, status check, and commit. *** ## 2. Roles and Permissions Three roles govern what you can do inside Change Management: | Role | What you can do | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **Global Admin** | Create and edit repositories. Full visibility across the system. | | **Machine Admin** | Create, update, and merge change requests. Manage branches (create, update, delete). Retry diff computations. | | **Developer** | Create and update change requests. Retry diff computations. | All three roles can view every page in the Change Management section. ### Permissions at a Glance | Action | Global Admin | Machine Admin | Developer | | ------------------------------ | :----------: | :-----------: | :-------: | | Create / edit repository | Yes | -- | -- | | Create / update change request | -- | Yes | Yes | | Merge change request | -- | Yes | -- | | Retry diff computation | -- | Yes | Yes | | Create / edit / delete branch | -- | Yes | -- | ### Approval Gates Change requests can optionally require approvals from specific roles before they can be merged. For example, a policy might require one Machine Admin approval and two Developer approvals. The change request detail page tracks progress toward each requirement so everyone can see what is still needed. *** ## 3. Navigating to Change Management Open the sidebar and expand **Change Management**. You will see three sections: | Section | What it shows | | -------------------------- | ------------------------------------------------------------------ | | **Repositories** | All repositories, with the ability to create, view, and edit them. | | **Change Requests** | A cross-repository list of every change request, with filters. | | **Machine Control Center** | A card-based grid of machines and their checkout status. | *** ## 4. Creating a Repository > **Required role:** Global Admin ### Before You Begin Make sure at least one Axilon Application already exists in the system. The repository must be linked to an application. ### Steps 1. Go to **Change Management > Repositories**. 2. Click **"Create repository"** in the top-right corner. 3. Fill out the form: **Basic Information** * **Name** (required, up to 128 characters) -- A human-readable label for the repository. * **Project Name** (required, up to 128 characters) -- The name of the Ignition project being tracked. **Application** * **Application** (required) -- Choose the Axilon application this repository will track. **Branch** * A default branch is created automatically. You can add more branches later. **Custom Scripts** (all optional) * **Diff Generation Script** -- Computes differences between two states. * **Merge Application Script** -- Applies a merged state to the live system. * **Extract Script** -- Captures the current baseline state and converts it to JSON. * **Apply Script** -- Applies a JSON state to the live system. * **Revert Script** -- Rolls back a previously applied diff. * **Configuration Script** -- A `.yaml` or `.yml` file you can browse for and upload. A tooltip listing all available script variables (`$workspaceDirectory`, `$projectName`, `$diffOutputPath`, etc.) is available next to each script field. 4. Click **Submit**. 5. On success you will see a *"Repository created successfully!"* notification and be taken to the new repository's detail page. > **What happens next:** The repository exists but is **empty** -- it has no commits yet. You must initialize it before it can be used (see the next section). *** ## 5. Initializing a Repository ### Why This Step Is Needed A freshly created repository has no data. Initialization runs the extract process on a machine to capture the current application state and save it as the first commit. ### Before You Begin At least one machine must be registered in Axilon. ### Steps 1. Open the repository's detail page (from the Repositories list, click **View**). 2. You will see a yellow warning banner: > **Repository Not Initialized** This repository needs to be initialized before you can perform operations like commits or checkouts. 3. Click **"Initialize Repository"** on the banner. 4. In the dialog that opens, select the **machine** that should run the initialization from the dropdown. 5. Click **"Initialize repository"**. 6. A loading message appears: *"Initializing repository. This process may take some time to complete."* 7. Once the process finishes, a *"Repository initialization submitted successfully"* notification appears and the dialog closes. 8. Back on the detail page, you can monitor progress via the operation status card that replaces the banner while the process runs. 9. When initialization completes, the banner disappears and the Overview tab shows repository statistics and the initial commit. ### If Initialization Fails A warning icon appears next to the repository name in the header bar. You can re-attempt initialization by clicking the banner that reappears. *** ## 6. Browsing and Managing Repositories ### The Repositories List 1. Go to **Change Management > Repositories**. 2. Use the filters above the table to narrow results by **name** or **application**. 3. The table is paginated (10 items per page by default). 4. Each row has an actions menu offering **View** and **Update**. ### The Repository Detail Page Click **View** on any repository to open its detail page. The page contains: **Header area** * Repository name with breadcrumb navigation. * **"Create new change request"** button. * **"Back"** button. **Repository bar** * Displays the project name and repository name. * A three-dot menu with **"Edit Repository"**. * A **branch selector** to switch which branch you are viewing. **Three tabs:** | Tab | What it shows | | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Overview** | Application details, stats (total commits, branches, connected machines, last updated), and a list of recent commits. | | **Commits** | All commits on the selected branch (up to 20), with the branch name shown as a chip. | | **Change Requests** | Change requests associated with this repository. You can filter by source branch, target branch, or status. | *** ## 7. Editing a Repository > **Required role:** Global Admin 1. Navigate to the repository detail page. 2. Open the edit form in either of two ways: * Click the three-dot menu in the repository bar and choose **"Edit Repository"**. * Or click **"Update"** from the actions menu on the Repositories list page. 3. The form is pre-filled with the current values. All fields except **Application** can be changed (the application is locked after creation). 4. Make your changes and click **Submit**. 5. You will see a *"Repository updated successfully!"* notification and be returned to the detail page. *** ## 8. Using the Machine Control Center ### What It Is The Machine Control Center gives you a real-time operational view of every machine and its repository checkout state. It is your hub for day-to-day operations: checking out branches, pulling updates, checking for uncommitted changes, and creating new commits. ### Getting There Click **Change Management > Machine Control Center** in the sidebar. ### What You See * **Header** with an **"Add Repository Checkout"** button. * A **search bar** to find machines by name. * A **grid of machine cards**, paginated (12 per page by default). The page refreshes automatically every few seconds to keep status current. ### Reading a Machine Card | Area | What it shows | | ---------------- | ----------------------------------------------------------------------- | | Top | Machine name, IP address, and an online/offline indicator | | Chips | Online status, plus flags for Domain Controller and Clone if applicable | | Middle | Checked-out repository name, branch, and current commit ID | | Operation status | If a background operation is running, its type and progress | | Action buttons | **Checkout**, **Pull**, **Status**, **Commit** | | Footer | When the machine was last seen online | The four action buttons are disabled when the machine is offline, has no checkout, or already has an operation in progress. *** ## 9. Adding a Repository Checkout to a Machine ### Before You Begin At least one repository must be initialized, and at least one machine must be registered. ### Steps 1. Open the **Machine Control Center**. 2. Click **"Add Repository Checkout"** in the header. 3. In the dialog: * Select a **Machine**. * Select a **Repository**. The machine will automatically be placed on the repository's **main** branch. 4. Click **"Add Checkout"**. The machine card updates to show the newly assigned repository. *** ## 10. Checking Out a Branch on a Machine Use this when you need to switch which branch a machine is tracking. ### Before You Begin The machine must be online, must already have a repository checked out, and must not have another operation in progress. ### Steps 1. Find the machine card in the Machine Control Center. 2. Click **"Checkout"**. 3. In the dialog you will see the machine's name, IP, and current repository and branch. Select the **new branch** from the dropdown. 4. **Optional** You may choose to select whether this will be a **Hard** or **Soft** checkout. A **Hard** checkout will wipe any uncommitted changes from your machine. A **Soft** checkout will apply those uncommitted changes to your new branch. 5. Click **"Checkout"**. On success the dialog closes and the machine card updates to reflect the new branch. The state of the machine will also update to reflect the state of the new branch. *** ## 11. Pulling Latest Changes to a Machine Pull syncs the machine's working state with the latest commit on its checked-out branch. ### Before You Begin The machine must be online with a repository checked out, and no operation can already be in progress. ### Steps 1. Click **"Pull"** on the machine card. 2. The operation runs immediately -- no dialog is needed. A notification confirms success or reports an error. *** ## 12. Checking Status on a Machine A status check queries the machine to see whether its live application state has drifted from the last commit. ### Before You Begin The machine must be online with a repository checked out, and no operation can already be in progress. ### Steps 1. Click **"Status"** on the machine card. 2. The check runs immediately. *** ## 13. Committing Changes from a Machine Committing captures the current state of the application on the machine and saves it as a new commit on the checked-out branch. ### Before You Begin The machine must be online with a repository checked out, and no operation can already be in progress. ### Steps 1. Click **"Commit"** on the machine card. 2. In the dialog you will see the machine name, IP, repository, branch, and current commit ID. 3. Enter a **Commit Message** (required, up to 500 characters). A character counter is shown. 4. Click **"Commit"**. 5. On success the dialog closes and a notification confirms the commit was created. *** ## 14. Creating a Change Request A change request proposes merging changes from one branch into another. You can create one from two places. > **Required role:** Developer or Machine Admin ### From a Repository Detail Page 1. Open a repository's detail page. 2. Click **"Create new change request"** in the header. 3. The dialog opens pre-linked to this repository. ### From the Change Requests List 1. Go to **Change Management > Change Requests**. 2. Click **"Create new change request"** in the header. 3. The dialog opens with an additional **Repository** selector since no repository is assumed. ### Filling Out the Form | Field | Required? | Notes | | ----------------- | :----------------------------------: | ------------------------------------------------------------------------ | | **Repository** | Yes (only from Change Requests page) | Changing the repository clears any selected branches. | | **Title** | Yes (up to 256 characters) | A short summary of the change. | | **Source Branch** | Yes | The branch that contains the changes. | | **Target Branch** | Yes | The branch the changes will be merged into. Must differ from the source. | | **Description** | No (up to 500 characters) | Optional longer explanation. | If no machine is connected to the repository, the form shows a warning and the submit button is disabled. ### What Happens on Submit 1. Click **"Create change request"**. 2. A *"Change request created successfully"* notification appears. 3. The change request is created in **draft** status. It is visible to the team but not yet open for formal review or merge. *** ## 15. Viewing Change Request Details Open a change request by clicking **View** in the Change Requests table, or by clicking the detail icon on a change request card inside a repository. ### What You See **Header card** -- the main summary area: * **Title** and **status badge** (Draft / Open / Merged / Closed, each in a distinct color). * An **"Out of date"** badge if the diff is stale. * **Description**, if one was provided. * **Author**, **created** and **updated** timestamps, and a short ID. * **Branch flow** showing source branch -> target branch with a commit count. * **Diff status** showing whether a diff has been computed, is in progress, or has failed. On the right side, three summary boxes show the current count of **Approved**, **Changes Requested**, and **Denied** reviews. **Review Actions card** (visible only to users who are not the author) -- lets you approve, request changes, or deny. **Merge card** -- shows approval progress, an optional merge commit message field, any blocking reasons, and the merge or ready-for-review button. **Three detail tabs:** | Tab | Content | | ------------ | -------------------------------------------------------------------------------------------------------------- | | **Diff** | A visual diff viewer with search. Shows a *"No diff data available"* message if no diff has been computed yet. | | **Raw JSON** | The raw diff data in pretty-printed JSON format. | | **Comments** | A comment thread where any team member can leave notes. | If the change request is still a draft and you are the author, a banner at the bottom reminds you to click "Ready for review" to open it. *** ## 16. Generating and Refreshing Diffs A diff shows exactly what changed between the source and target branches. Diffs are computed on demand -- they are not generated automatically. ### When to Generate or Refresh * **After creating a change request** -- there is no diff yet. * **When the change request shows "Out of date"** -- new commits have been made since the last diff was computed. ### Steps 1. Open the change request detail page. 2. Click **"Generate diff"** (if no diff exists) or **"Refresh diff"** (if a previous diff exists but may be stale). 3. A *"Diff computation started"* notification appears. 4. A status indicator shows **"Computing diff..."** while the operation runs. 5. When finished: * **Success:** The indicator changes to **"Diff computed"** and the Diff tab populates with results. A summary line shows the number of additions, modifications, and deletions. * **Failure:** The indicator shows **"Diff computation failed"** and a banner invites you to try again. *** ## 17. Reviewing a Change Request > You can review any change request that is in **Open** or **Draft** status, as long as you are **not** the author. ### Steps 1. Open the change request detail page. 2. In the **Review Actions** card, you will see three options: | Option | Meaning | | ------------------- | --------------------------------------------------------- | | **Approve** | You are satisfied with the changes. | | **Request changes** | You want the author to make modifications before merging. | | **Deny** | You believe the changes should not be merged. | If you have already reviewed, your previous decision is highlighted. 3. Click the option you want. 4. A submit button appears. Click it (e.g., **"Approve change request"**). 5. A *"Review decision submitted"* notification confirms the action. The approval summary boxes in the header update. ### Changing Your Mind You can change a previously submitted review at any time: 1. Select a different option. 2. Click the new submit button that appears. *** ## 18. Commenting on a Change Request Any team member can leave comments on a change request that is in **Open** or **Draft** status. ### Steps 1. Open the change request detail page. 2. Switch to the **Comments** tab. 3. In the **"Add comment"** box, type your message. 4. Click **"Add comment"**. 5. A *"Comment added"* notification appears and your comment shows up in the thread. ### Reading Comments Each comment shows the author's name, a timestamp, and the full comment text. Comments are listed in chronological order. *** ## 19. Marking a Draft as Ready for Review When you create a change request, it starts as a **Draft**. Drafts are visible to the team, but the Merge button is not available and the change request is not formally open for review. > Only the **author** of the change request can promote it to Open. ### Steps 1. Open the draft change request's detail page. 2. A banner at the bottom reminds you: *"This change request is a draft. Click 'Ready for review' in the Merge section to open it."* 3. Scroll to the **Merge** card. Instead of a Merge button, you will see a green **"Ready for review"** button. 4. Click it. 5. A *"Change request is ready for review"* notification appears. The status badge changes from **Draft** (gray) to **Open** (green). The Merge button now appears for eligible users, and team members who are not the author can see the Review Actions card. *** ## 20. Merging a Change Request > **Required role:** Machine Admin ### Before You Begin * The change request must be in **Open** status. * All role-based approval requirements must be satisfied. The Merge card shows approval progress chips for each role (e.g., "Machine Admin 1/1", "Developer 2/2"). Green means the requirement is met; amber means it is not. * If merging is blocked, the card explains why: * *"Change request is already merged."* * *"Change request is not open for merging."* * *"Insufficient approvals to merge this change request."* * *"Merge is currently not possible for this change request."* ### Steps 1. Open the change request detail page. 2. In the **Merge** card, optionally enter a **merge commit message**. 3. Click **"Merge"**. 4. A *"Merge operation started successfully"* notification appears. 5. The page tracks the merge operation as it progresses. This may take a few moments. 6. When finished: * **Success:** A *"Merge completed successfully"* notification appears. The status badge changes to **Merged** (shown in a distinct purple/blue color with a merge icon). * **Failure:** A *"Merge failed"* notification appears. You can investigate and try again. ### After Merging * The change request is now **Merged** and can no longer be modified. * The merged commit appears in the target branch's commit history. * In change request lists, merged items show a merge icon, the user who merged, and the merge commit short hash. *** ## 21. Viewing Commit Details ### Steps 1. From a repository's **Overview** tab (Recent Commits) or **Commits** tab, click on a commit. 2. The commit detail page shows: * Commit metadata: message, author, repository name. * **Baseline** and **Diff** tabs to inspect the captured state and any computed differences. 3. Click **"Back"** to return to the repository detail page. *** ## 22. Browsing All Change Requests The Change Requests page gives you a cross-repository view of every change request in the system. ### Steps 1. Go to **Change Management > Change Requests** in the sidebar. 2. Use the filters to narrow the list: * **Search** -- search by change request title. * **Status** -- filter by Draft, Open, Merged, or Closed. 3. The table shows each change request's title, status, source and target branches, author, and creation date. 4. Click **View** on any row to open its detail page. 5. You can also click **"Create new change request"** in the header to create one (you will be asked to pick a repository first). *** ## 23. Managing Branches Branches are independent lines of work within a repository. A default branch is created automatically with every new repository. Machine Admins can create, edit, and delete additional branches. ### Creating a Branch > **Required role:** Machine Admin 1. Open a repository's detail page. 2. In the branch section, click **"Create branch"**. 3. Fill out the form: | Field | Required | Notes | | --------------- | :------: | --------------------------------------------------- | | **Branch Name** | Yes | A unique name within this repository. | | **Base Branch** | Yes | The branch to create the new branch from. | | **Description** | No | Optional description of the branch's purpose. | | **Protected** | No | Toggle to mark the branch as protected (see below). | 4. Click **"Create"**. 5. A *"Branch created successfully"* notification appears. ### Editing a Branch > **Required role:** Machine Admin 1. Open the repository detail page. 2. In the branch section, find the branch and click the **edit** action. 3. Update the branch name, description, or protected status. 4. Click **"Save"**. ### Deleting a Branch > **Required role:** Machine Admin 1. Open the repository detail page. 2. In the branch section, find the branch and click the **delete** action. 3. A confirmation dialog appears. > **Note:** The default branch cannot be deleted. If the branch is protected, you must type **"DELETE"** in the confirmation field to proceed. 4. Click **"Delete"** to confirm. 5. A *"Branch deleted successfully"* notification appears. ### Protected Branches Marking a branch as protected adds an extra safety layer: * Protected branches require an explicit confirmation (typing "DELETE") before they can be deleted. * The protected status is shown in the branch section. *** ## 24. Resolving Merge Conflicts When a change request has conflicting changes between the source and target branches, a **Conflicts** tab appears on the change request detail page. ### Viewing Conflicts 1. Open a change request that has merge conflicts. 2. The **Merge** card shows a warning with the number of conflicts (e.g., *"3 conflicts detected"*). The **Merge** button is disabled while conflicts remain unresolved. 3. Click the **Conflicts** tab. ### What You See * A progress indicator showing resolution status (e.g., *"2 of 5 conflicts resolved"*) with a progress bar. * Conflicts are grouped by entity type. * Each conflict shows: * **Entity ID** and **Entity Type** as a chip. * A description of the conflict. * A side-by-side comparison: * **Source (Ours)**: The content from the source branch. * **Target (Theirs)**: The content from the target branch. ### Resolving a Conflict For each conflict item: 1. Review the side-by-side comparison of the source and target content. 2. Click **"Accept Source (Ours)"** to keep the source branch's version, or **"Accept Target (Theirs)"** to keep the target branch's version. 3. A "Resolved" badge appears on the conflict item once a choice is made. 4. Repeat for all conflicts. The progress bar updates as you resolve each conflict. Once all conflicts are resolved, the Merge button becomes available again. *** ## 25. Reverting a Commit You can create a new commit that undoes the changes introduced by a previous commit. ### Steps 1. Navigate to a repository's **Commits** tab or the commit detail page. 2. Click the **revert** action on the commit you want to undo. 3. In the dialog that opens: * The commit message and details are shown. * Select a **target machine** from the dropdown. Only online machines with active checkouts are listed. 4. Click **"Revert"**. 5. A new commit is created that reverses the changes from the selected commit. > **Note:** The commit must have diff data available before it can be reverted. *** ## 26. Closing a Change Request A change request can be closed if it is no longer needed. > **Required role:** Developer or Machine Admin ### Steps 1. Open the change request detail page. 2. Click **"Close"** (available when the change request is in **Draft** or **Open** status). 3. The status changes to **Closed** (red badge). The change request can no longer be reviewed or merged. *** ## 27. Viewing Operation History The Machine Control Center tracks the history of operations performed on each machine. ### Steps 1. Open the **Machine Control Center**. 2. On a machine card, click the **operation history** action. 3. A modal displays the list of past operations for that machine, including: * Operation type (Checkout, Commit, Pull, Status Check, Initialize, Revert). * Status (Done, Failed, Pending, etc.). * Timestamps. *** ## 28. Change Request Lifecycle Summary ``` create | v +---------+ "Ready for review" +--------+ | DRAFT | -------------------------> | OPEN | +---------+ +--------+ | | | (close) | +----------------------------------+ | | | merge v v | +--------+ | +--------+ | CLOSED | +---> | MERGED | +--------+ +--------+ ``` | From | To | How | Who | | --------------------- | ---------- | --------------------------------------- | ------------------------ | | *(new)* | **Draft** | Create a change request | Developer, Machine Admin | | **Draft** | **Open** | Click "Ready for review" | Author only | | **Open** | **Merged** | Click "Merge" (all approvals satisfied) | Machine Admin | | **Draft** or **Open** | **Closed** | Close the change request | Developer, Machine Admin | ### Status Colors | Status | Color | | ------ | ------------- | | Draft | Gray | | Open | Green | | Merged | Purple / Blue | | Closed | Red |