Git Data API Usage

Relevant source files

The following files were used as context for generating this wiki page:

• src/github/mod.rs
• AGENTS.md
• src/sync.rs
• README.md
• src/main.rs
• action.yml

Orcastrate uses the GitHub Git Data API to perform low-level Git operations. This approach allows the system to create commits and update references directly without requiring a local git clone or using the high-level Contents API for file updates. By using the Git Data API, Orcastrate avoids common workflow scope limitations associated with updating files in the .github/workflows/ directory.

Sources: AGENTS.md:42-44, README.md:158-160

Architecture and Data Flow

The Git Data API operations follow a structured sequence to update repository files. The GitHubClient coordinates these calls to build a new Git tree, create a commit object, and update a branch reference.

The following diagram illustrates the sequence of operations required to commit files via the Git Data API:

Core Components and Data Structures

Orcastrate defines several structures to manage the data required for Git API interactions.

Data Structures

Structure	Purpose	Fields
CommitRequest	Encapsulates all data needed to perform a multi-file commit.	owner, repo, branch, message, base_sha, files
FileChange	Represents an individual file to be modified or created.	path, content
GitHubClient	Manages the octocrab instances and executes API requests.	crab, pr_crab, is_app_auth, dry_run

Sources: src/github/mod.rs:19-41

Key Functions

• create_branch: Creates a new reference in the repository. If the branch already exists, it force-updates the reference to the from_sha.
  • Endpoint: POST /repos/{owner}/{repo}/git/refs
  • Sources: src/github/mod.rs:135-168
• commit_files: Executes the low-level commit flow by creating a tree and a commit object.
  • Endpoints: POST /git/trees, POST /git/commits, PATCH /git/refs/heads/{branch}
  • Sources: src/github/mod.rs:170-244
• get_branch_sha: Retrieves the current SHA for a specific branch.
  • Endpoint: GET /repos/{owner}/{repo}/git/refs/heads/{branch}
  • Sources: src/github/mod.rs:118-133

Commit Implementation Details

The commit_files function implements the Git object model. It first creates a tree object containing the file changes, then a commit object that points to that tree, and finally updates the branch pointer.

Tree Creation

The client maps FileChange items into tree entries with mode 100644 (blob). It uses a base_tree to ensure the new tree is created relative to the existing repository state.
Sources: src/github/mod.rs:182-196

Commit Creation and Author Identity

The client constructs the commit object with a message, tree SHA, and parent SHA. Author identity depends on the authentication method:

• GitHub App: Uses the App's implicit identity.
• PAT/Personal Token: Explicitly sets the author and committer to github-actions[bot].

Sources: src/github/mod.rs:214-222, AGENTS.md:52-57

// src/github/mod.rs:214-222
if !self.is_app_auth {
    let bot = serde_json::json!({
        "name": BOT_NAME,
        "email": BOT_EMAIL,
    });
    commit_body["author"] = bot.clone();
    commit_body["committer"] = bot;
}

Reference Update

The final step patches the Git reference for the target branch to point to the new commit SHA, using a force update to ensure the pointer moves even if it is not a fast-forward operation.
Sources: src/github/mod.rs:228-242

Integration in Sync Workflow

The sync module utilizes these Git Data API functions when SyncMode::Pr is active.

1. Resolve Base: The system fetches the default branch and its current SHA.
2. Branch Management: It creates a feature branch prefixed with the configured branch_prefix (default: orcastrate/sync/).
3. Atomic Commit: It pushes the rendered workflow content using commit_files.
4. PR Linking: High-level PR APIs are then used to link this Git data to a Pull Request.

Sources: src/sync.rs:250-272, src/config.rs:43-45

Authentication Requirements

Directly writing to .github/workflows/ via the Git Data API requires specific token permissions.

Token Type	Required Permission	Usage
ORCASTRATE_TOKEN	Workflows (Read/Write)	Used for all Git Data API writes to workflow files.
ORCASTRATE_APP	Workflows (Read/Write)	Used for both Git writes and PR management.

Sources: README.md:173-195, AGENTS.md:46-50

Orcastrate leverages the low-level Git Data API to ensure reliable management of GitHub Actions workflows across multiple repositories, bypassing the restrictions typically placed on high-level file modification APIs.