Skip to main content

​
Create proposed changes

Proposed changes provide a structured workflow for reviewing, validating, and merging branch changes into the main branch. This guide shows you how to create, review, and merge proposed changes.

​
Prerequisites

Before working with proposed changes, ensure you have:
  • An existing branch with changes to merge
  • Appropriate permissions to create and merge proposed changes
  • GraphQL API access or SDK installed (if using programmatic methods)

​
Create a proposed change

Create a proposed change to initiate the review and validation process for your branch.

​
Using GraphQL

mutation {
  CoreProposedChangeCreate(
    data: {
      source_branch: "feature-network-redesign"
      destination_branch: "main"
      name: "Network topology redesign"
      description: "Implementing new core network architecture"
    }
  ) {
    ok
    object {
      id
      display_label
      name
      state
      source_branch {
        value
      }
      destination_branch {
        value
      }
    }
  }
}
Parameters:
  • source_branch (required): The branch containing your changes
  • destination_branch (required): The target branch (typically main)
  • name (required): Short, descriptive name for the proposed change
  • description (optional): Detailed explanation of the changes

​
Using the Python SDK

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

proposed_change = await client.create(
    kind="CoreProposedChange",
    source_branch="feature-network-redesign",
    destination_branch="main",
    name="Network topology redesign",
    description="Implementing new core network architecture"
)

await proposed_change.save()
print(f"Proposed change created: {proposed_change.id}")

​
View proposed change details

Retrieve information about a proposed change, including its state, checks, and diff.

​
Query proposed change

query {
  CoreProposedChange(id: "<proposed-change-id>") {
    id
    name
    state {
      value
    }
    source_branch {
      value
    }
    destination_branch {
      value
    }
    created_at {
      value
    }
    reviewers {
      edges {
        node {
          display_label
        }
      }
    }
    approved_by {
      edges {
        node {
          display_label
        }
      }
    }
  }
}

​
List all proposed changes

query {
  CoreProposedChange {
    edges {
      node {
        id
        name
        state {
          value
        }
        source_branch {
          value
        }
        created_at {
          value
        }
      }
    }
  }
}

​
Proposed change states

Proposed changes follow a lifecycle with specific states:
  • OPEN: Active and ready for review
  • MERGED: Successfully merged into the destination branch
  • MERGING: Currently being merged
  • CLOSED: Closed without merging
  • CANCELED: Canceled and cannot be reopened
See the ProposedChangeState enum for implementation details at backend/infrahub/proposed_change/constants.py:14.

​
Check validation results

Proposed changes automatically run validation checks. View check results to ensure your changes are ready to merge.

​
Query checks

query {
  CoreProposedChange(id: "<proposed-change-id>") {
    checks {
      edges {
        node {
          id
          name {
            value
          }
          kind {
            value
          }
          severity {
            value
          }
          conclusion {
            value
          }
          message {
            value
          }
        }
      }
    }
  }
}
Check types:
  • DataIntegrity: Validates referential integrity
  • SchemaIntegrity: Validates schema changes
  • RepositoryCheck: Checks Git repository consistency
  • UserCheck: Custom user-defined checks
  • ArtifactGeneration: Validates artifact generation
  • GeneratorExecution: Validates Generator execution
Check conclusions:
  • success: Check passed
  • failure: Check failed (blocks merge)
  • unknown: Check status unknown

​
Review and approve changes

Add reviewers and approvals to proposed changes.

​
Add a reviewer

mutation {
  CoreProposedChangeUpdate(
    data: {
      id: "<proposed-change-id>"
      reviewers: [
        { id: "<account-id-1>" },
        { id: "<account-id-2>" }
      ]
    }
  ) {
    ok
  }
}

​
Approve a proposed change

Approve the proposed change using the approval action: 
mutation {
  CoreProposedChangeApprove(
    data: {
      id: "<proposed-change-id>"
    }
  ) {
    ok
  }
}

​
Reject a proposed change

mutation {
  CoreProposedChangeReject(
    data: {
      id: "<proposed-change-id>"
    }
  ) {
    ok
  }
}

​
Cancel approval or rejection

mutation {
  CoreProposedChangeCancelApprove(
    data: {
      id: "<proposed-change-id>"
    }
  ) {
    ok
  }
}

​
View the diff

Retrieve the diff between source and destination branches to understand what changes will be merged. 
query {
  CoreProposedChange(id: "<proposed-change-id>") {
    data_diff {
      id
      name
      action
      attributes {
        name
        action
        new_value
        previous_value
      }
      relationships {
        name
        action
        peers {
          action
          peer {
            id
            display_label
          }
        }
      }
    }
  }
}
Diff actions:
  • ADDED: New object or attribute
  • UPDATED: Modified object or attribute
  • REMOVED: Deleted object or attribute
  • UNCHANGED: No changes

​
Merge a proposed change

Merge the proposed change after it passes all checks and receives required approvals.

​
Using the branch merge mutation

mutation {
  BranchMerge(
    data: {
      name: "feature-network-redesign"
    }
    wait_until_completion: true
  ) {
    ok
    object {
      name
      status
    }
  }
}
Parameters:
  • wait_until_completion (optional, default: true): Wait for merge to complete
If wait_until_completion is false, the mutation returns a task ID: 
mutation {
  BranchMerge(
    data: { name: "feature-network-redesign" }
    wait_until_completion: false
  ) {
    ok
    task {
      id
    }
  }
}

​
Merge requirements

Before merging, ensure:
  1. All validation checks pass (no failing checks)
  2. All conflicts are resolved
  3. Required approvals are obtained (if configured)
  4. Branch status is OPEN (not NEED_REBASE or NEED_UPGRADE_REBASE)
The merge will fail if:
  • The branch has conflicts with the main branch
  • Any validation checks have failed
  • The branch status is NEED_UPGRADE_REBASE
See BranchMerge mutation at backend/infrahub/graphql/mutations/branch.py:270.

​
Close a proposed change

Close a proposed change without merging when it’s no longer needed: 
mutation {
  CoreProposedChangeClose(
    data: {
      id: "<proposed-change-id>"
    }
  ) {
    ok
  }
}
Closed proposed changes can be reopened: 
mutation {
  CoreProposedChangeReopen(
    data: {
      id: "<proposed-change-id>"
    }
  ) {
    ok
  }
}

​
Common patterns

​
Create a draft proposed change

Create a proposed change in draft mode for early feedback: 
mutation {
  CoreProposedChangeCreate(
    data: {
      source_branch: "feature-network-redesign"
      destination_branch: "main"
      name: "Network topology redesign"
      description: "Work in progress - early feedback welcome"
      state: "draft"
    }
  ) {
    ok
    object {
      id
      state {
        value
      }
    }
  }
}

​
Verify all checks passed

Before merging, verify all checks have passed: 
query {
  CoreProposedChange(id: "<proposed-change-id>") {
    checks {
      edges {
        node {
          name {
            value
          }
          conclusion {
            value
          }
        }
      }
    }
  }
}
Ensure all checks have conclusion: "success" before proceeding with the merge.

​
Verify merge completion

After merging, verify the branch status and proposed change state: 
query {
  CoreProposedChange(id: "<proposed-change-id>") {
    state {
      value
    }
  }
  Branch(name: "feature-network-redesign") {
    status
  }
}
Expected response: 
{
  "data": {
    "CoreProposedChange": {
      "state": {
        "value": "merged"
      }
    },
    "Branch": {
      "status": "OPEN"
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us