Create or update file contents

GitHub create or update file contents tool to create a new file or update an existing file in a GitHub repository. This is a write tool that creates a commit with the file changes, including support for custom commit metadata such as author, committer, branch, and SHA validation.

Replace deprecated GitHub tools

Use Create or update file (GitHub MCP) (create_or_update_file) instead of the deprecated githubcommitsinglefile tool.

Prerequisites

• Your admin must install and configure the GitHub connector, add the GitHub tools under Admin console → Platform → Tools, and enable this tool.

• A GitHub app must be installed on the relevant organization(s) and linked to the correct GitHub connector in the Glean Admin console.

• The GitHub app must have write permissions to repository contents.

Supported parameters

Parameter	Type	Required	Description
Owner	String	Yes	The account owner of the repository (case-insensitive).
Repository	String	Yes	The name of the repository without the .git extension (case-insensitive).
File path	String	Yes	The full path to the file in the repository, including filename and extension.
Content	String	Yes	The new file content, Base64 encoded (e.g., "SGVsbG8gV29ybGQ=" for "Hello World").
Commit message	String	Yes	The commit message for this file creation or update.
Branch	String	No	The branch name to create or update the file on (defaults to repository's default branch).
Author name	String	No	The commit author's name (requires author email if provided).
Author email	String	No	The commit author's email (requires author name if provided).
Author date	String	No	The author's timestamp in ISO 8601 format (defaults to committer date).
Committer name	String	No	The committer's name (requires committer email if provided).
Committer email	String	No	The committer's email (requires committer name if provided).
Committer date	String	No	The committer's timestamp in ISO 8601 format (defaults to current time).
SHA	String	No	The blob SHA of the file being replaced for validation (auto-fetched if omitted).

Note: If author and committer details are omitted, GitHub uses the authenticated user's identity for both.

Usage examples

• "Create a new README.md file in the 'myorg/myproject' repository with the content 'Welcome to My Project'."

• "Update the config.json file in 'facebook/react' on the 'develop' branch with new configuration settings."

• "Add a new API documentation file at 'docs/api/endpoints.md' in the 'microsoft/vscode' repository."

Troubleshooting

• Possible cause: The GitHub connector is not fully set up, the GitHub app is not installed on the target organization, or the app is missing write permissions to repository contents.
• Fix: Confirm that the GitHub connector is installed and authenticated, that the GitHub app is installed on the correct organization(s), and that it has write permissions to repository contents. If using a custom app, verify that the contents:write permission is enabled.

• Possible cause: The content parameter is not Base64 encoded, or the encoding is incorrect.
• Fix: Ensure that the content you pass to the tool is properly Base64 encoded. If you are sending plain text, convert it to Base64 first. Verify the encoding by decoding it locally before sending to the tool.

• Possible cause: The GitHub organization has enabled OAuth App access restrictions, and the app used by this tool is not allowed to access the target repository.
• Fix: Ask your GitHub organization admin to approve or allow the GitHub app used by this tool for the relevant repositories, then retry.

• Possible cause: The file has been modified since you last read it, or the SHA provided does not match the current file version.
• Fix: Retrieve the latest SHA for the file using a file reading tool, then retry the update with the correct SHA. Alternatively, omit the SHA parameter to have it automatically fetched (but be aware this may overwrite concurrent changes).

• Possible cause: The path parameter includes invalid characters, refers to a directory instead of a file, or the parent directories do not exist.
• Fix: Verify the path is a valid file path (not a directory). GitHub automatically creates parent directories as needed, so you do not need to create them separately. Ensure the path does not start with a leading slash.

FAQs

The Content parameter must be Base64 encoded. For example, "SGVsbG8gV29ybGQ=" decodes to "Hello World". Most programming languages have built-in Base64 encoding functions to help with this conversion.

When you include SHA, the tool validates that you are updating the expected file version, preventing accidental overwrites. If you omit SHA, it is automatically fetched before applying the update. For read-modify-write workflows, always use the SHA to avoid race conditions.

Yes. GitHub automatically creates parent directories as needed when you specify a path like "docs/api/README.md". You do not need to create the directories separately.

The tool updates the existing file with the new content by creating a new commit. If you provide a SHA, it validates that the file version matches before updating. If the file does not exist, a new file is created instead.