create_or_update_file

Create or update files in GitHub repositories by specifying content, path, and commit details to manage repository files directly.

Instructions

Create or update a single file in a GitHub repository

Input Schema

TableJSON Schema

Name	Required	Description
`owner`	Yes	Repository owner (username or organization)
`repo`	Yes	Repository name
`path`	Yes	Path where to create/update the file
`content`	Yes	Content of the file
`message`	Yes	Commit message
`branch`	Yes	Branch to create/update the file in
`sha`	No	SHA of the file being replaced (required when updating existing files)

Implementation Reference

src/operations/files.ts:107-145 (handler)

Implements the core logic for creating or updating a file in a GitHub repository. Checks if the file exists to get SHA for updates, encodes content to base64, and uses GitHub Contents API PUT endpoint.

export async function createOrUpdateFile(
  github_pat: string,
  owner: string,
  repo: string,
  path: string,
  content: string,
  message: string,
  branch: string,
  sha?: string
) {
  
  let currentSha = sha;
  if (!currentSha) {
    try {
      const existingFile = await getFileContents({github_pat, owner, repo, path, branch});
      if (!Array.isArray(existingFile)) {
        currentSha = existingFile.sha;
      }
    } catch (error) {
      console.error("Note: File does not exist in branch, will create new file");
    }
  }
  
  const encodedContent = Buffer.from(content).toString("base64");
  const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}`;
  const body = {
    message,
    content: encodedContent,
    branch,
    ...(currentSha ? { sha: currentSha } : {}),
  };

  const response = await githubRequest(github_pat, url, {
    method: "PUT",
    body,
  });

  return GitHubCreateUpdateFileResponseSchema.parse(response);
}

src/operations/files.ts:18-26 (schema)

Zod schema defining the input parameters for the create_or_update_file tool, used for validation and JSON schema generation.

export const CreateOrUpdateFileSchema = z.object({
  owner: z.string().describe("Repository owner (username or organization)"),
  repo: z.string().describe("Repository name"),
  path: z.string().describe("Path where to create/update the file"),
  content: z.string().describe("Content of the file"),
  message: z.string().describe("Commit message"),
  branch: z.string().describe("Branch to create/update the file in"),
  sha: z.string().optional().describe("SHA of the file being replaced (required when updating existing files)"),
});

src/index.ts:79-82 (registration)

Registers the tool in the listTools handler by providing name, description, and input schema.

  name: "create_or_update_file",
  description: "Create or update a single file in a GitHub repository",
  inputSchema: zodToJsonSchema(files.CreateOrUpdateFileSchema),
},

src/index.ts:405-420 (registration)

Dispatches calls to the createOrUpdateFile handler function in the main CallToolRequestSchema handler.

case "create_or_update_file": {
  const args = files._CreateOrUpdateFileSchema.parse(params.arguments);
  const result = await files.createOrUpdateFile(
    args.github_pat,
    args.owner,
    args.repo,
    args.path,
    args.content,
    args.message,
    args.branch,
    args.sha
  );
  return {
    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
  };
}

src/operations/files.ts:28-30 (schema)

Extended schema including github_pat, used internally for parsing arguments in the dispatcher.

export const _CreateOrUpdateFileSchema = CreateOrUpdateFileSchema.extend({
  github_pat: z.string().describe("GitHub Personal Access Token"),
});

mcp-github